index f83569c..a97d76c 100644 (file)
@@ -34,9 +34,10 @@ Many of the functions listed in this chapter are defined mathematically
over a domain that is only a subset of real numbers.  For example, the
@code{acos} function is defined over the domain between @code{-1} and
@code{1}.  If you pass an argument to one of these functions that is
-outside the domain over which it is defined, the function returns
-an unspecified value and sets @code{errno} to @code{EDOM} to indicate
-a @dfn{domain error}.
+outside the domain over which it is defined, the function sets
+@code{errno} to @code{EDOM} to indicate a @dfn{domain error}.  On
+machines that support IEEE floating point, functions reporting error
+@code{EDOM} also return a NaN.

Some of these functions are defined mathematically to result in a
complex value over parts of their domains.  The most familiar example of
@@ -51,7 +52,7 @@ be representable as a floating point number.  If magnitude of the
correct result is too large to be represented, the function sets
@code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
returns a particular very large value (named by the macro
-@code{HUGE_VAL}) or its negation.
+@code{HUGE_VAL}) or its negation (@w{@code{- HUGE_VAL}}).

If the magnitude of the result is too small, a value of zero is returned
instead.  In this case, @code{errno} might or might not be
@@ -63,6 +64,7 @@ and test @code{errno} afterward.  As a consequence of this use of
@code{errno}, use of the mathematical functions is not reentrant if you
check for errors.

+@c !!! this isn't always true at the moment....
None of the mathematical functions ever generates signals as a result of
domain or range errors.  In particular, this means that you won't see
@code{SIGFPE} signals generated within these functions.  (@xref{Signal
@@ -97,9 +99,9 @@ that pi radians equals 180 degrees.
The math library doesn't define a symbolic constant for pi, but you can
define your own if you need one:

-@example
+@smallexample
#define PI 3.14159265358979323846264338327
-@end example
+@end smallexample

@noindent
You can also compute the value of pi with the expression @code{acos
@@ -254,6 +256,7 @@ different base, it is similar to the @code{log} function.  In fact,
This is a general exponentiation function, returning @var{base} raised
to @var{power}.

+@need 250
The following @code{errno} error conditions are defined for this function:

@table @code
@@ -279,10 +282,10 @@ number.

@cindex cube root function
@comment math.h
-@comment GNU
+@comment BSD
@deftypefun double cbrt (double @var{x})
This function returns the cube root of @var{x}.  This function cannot
-fail; every representable real value has a represetable real cube root.
+fail; every representable real value has a representable real cube root.
@end deftypefun

@comment math.h
@@ -307,7 +310,7 @@ to subtraction of two numbers that are nearly equal.
@comment math.h
@comment BSD
@deftypefun double log1p (double @var{x})
-This function returns a value equivalent to @code{log (1 + @var{x})}.
+This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
It is computed in a way that is accurate even if the value of @var{x} is
near zero.
@end deftypefun
@@ -323,7 +326,7 @@ see @ref{Exponents and Logarithms}.
@comment ANSI
@deftypefun double sinh (double @var{x})
The @code{sinh} function returns the hyperbolic sine of @var{x}, defined
-mathematically as @code{(exp (@var{x}) - exp (-@var{x}) / 2}.  The
+mathematically as @w{@code{exp (@var{x}) - exp (-@var{x}) / 2}}.  The
function fails, and sets @code{errno} to @code{ERANGE}, if the value of
@var{x} is too large; that is, if overflow occurs.
@end deftypefun
@@ -332,7 +335,7 @@ function fails, and sets @code{errno} to @code{ERANGE}, if the value of
@comment ANSI
@deftypefun double cosh (double @var{x})
The @code{cosh} function returns the hyperbolic cosine of @var{x},
-defined mathematically as @code{(exp (@var{x}) + exp (-@var{x}) / 2}.
+defined mathematically as @w{@code{exp (@var{x}) + exp (-@var{x}) / 2}}.
The function fails, and sets @code{errno} to @code{ERANGE}, if the value
of @var{x} is too large; that is, if overflow occurs.
@end deftypefun
@@ -340,8 +343,8 @@ of @var{x} is too large; that is, if overflow occurs.
@comment math.h
@comment ANSI
@deftypefun double tanh (double @var{x})
-This function returns the hyperbolic tangent of @var{x}, defined
-mathematically as @code{sinh (@var{x}) / cosh (@var{x})}.
+This function returns the hyperbolic tangent of @var{x}, whose
+mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
@end deftypefun

@cindex inverse hyperbolic functions
@@ -372,36 +375,35 @@ value whose hyperbolic tangent is @var{x}.  If the absolute value of

@node Pseudo-Random Numbers
@section Pseudo-Random Numbers
-
-This section describes the GNU facilities for generating a series of
-pseudo-random numbers.  The numbers generated are not necessarily truly
-random; typically, the sequences repeat periodically, with the period
-being a function of the number of bits in the @dfn{seed} or initial
-state.
@cindex random numbers
@cindex pseudo-random numbers
@cindex seed (for random numbers)

-There are actually two sets of random number functions provided.
-
-@itemize @bullet
-@item
-The @code{rand} and @code{srand} functions, described in @ref{ANSI
-Random}, are part of the ANSI C standard.  You can use these functions
-portably in many C implementations.
-
-@item
-The @code{random} and @code{srandom} functions, described in @ref{BSD
-Random}, are derived from BSD.  They use a better random number
-generator (producing numbers that are more random), but are less
-portable.
-@end itemize
-
-For both sets of functions, you can get repeatable sequences of numbers
-within a single implementation on a single machine type by specifying
-the same initial seed value for the random number generator.  Other C
-libraries may produce different sequences of values for the same seed.
-
+This section describes the GNU facilities for generating a series of
+pseudo-random numbers.  The numbers generated are not truly random;
+typically, they form a sequence that repeats periodically, with a
+period so large that you can ignore it for ordinary purposes.  The
+random number generator works by remembering at all times a @dfn{seed}
+value which it uses to compute the next random number and also to
+compute a new seed.
+
+Although the generated numbers look unpredictable within one run of a
+program, the sequence of numbers is @emph{exactly the same} from one run
+to the next.  This is because the initial seed is always the same.  This
+is convenient when you are debugging a program, but it is unhelpful if
+you want the program to behave unpredictably.  If you want truly random
+numbers, not just pseudo-random, specify a seed based on the current
+time.
+
+You can get repeatable sequences of numbers on a particular machine type
+by specifying the same initial seed value for the random number
+generator.  There is no standard meaning for a particular seed value;
+the same seed, used in different C libraries or on different CPU types,
+will give you different random numbers.
+
+The GNU library supports the standard ANSI C random number functions
+plus another set derived from BSD.  We recommend you use the standard
+ones, @code{rand} and @code{srand}.

@menu
* ANSI Random::      @code{rand} and friends.
@@ -412,8 +414,7 @@ libraries may produce different sequences of values for the same seed.
@subsection ANSI C Random Number Functions

This section describes the random number functions that are part of
-the ANSI C standard.  These functions represent the state of the
-random number generator as an @code{int}.
+the ANSI C standard.

To use these facilities, you should include the header file
@file{stdlib.h} in your program.
@@ -424,8 +425,9 @@ To use these facilities, you should include the header file
@deftypevr Macro int RAND_MAX
The value of this macro is an integer constant expression that
represents the maximum possible value returned by the @code{rand}
-function.  In the GNU library, it is @code{037777777}.  In other
-libraries, it may be as low as @code{32767}.
+function.  In the GNU library, it is @code{037777777}, which is the
+largest signed integer representable in 32 bits.  In other libraries, it
+may be as low as @code{32767}.
@end deftypevr

@comment stdlib.h
@@ -451,9 +453,8 @@ To produce truly random numbers (not just pseudo-random), do @code{srand
@subsection BSD Random Number Functions

This section describes a set of random number generation functions that
-are derived from BSD.  The @code{random} function can generate better
-random numbers than @code{rand}, because it maintains more bits of
-internal state.
+are derived from BSD.  There is no advantage to using these functions
+with the GNU C library; we support them for BSD compatibility only.

The prototypes for these functions are in @file{stdlib.h}.
@pindex stdlib.h
@@ -477,12 +478,6 @@ To produce truly random numbers (not just pseudo-random), do
@code{srandom (time (0))}.
@end deftypefun

-Because this random number generator uses more state information than
-will fit in an @code{int}, @code{srandom} does not return a value that
-is useful for saving and restoring the random number state.  Instead,
-you should use the @code{initstate} and @code{setstate} functions to do
-this.
-
@comment stdlib.h
@comment BSD
@deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})