Thu Jan 18 00:32:43 1996 Roland McGrath <roland@churchy.gnu.ai.mit.edu>
[kopensolaris-gnu/glibc.git] / manual / math.texi
index 345329f..a97d76c 100644 (file)
@@ -1,32 +1,29 @@
-@node Mathematics
-@chapter Mathematics --- @file{<math.h>}
-@pindex <math.h>
+@node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
+@chapter Mathematics
 
 This chapter contains information about functions for performing
-mathematical computations, such as trigonometric functions.  Most
-of these functions have prototypes declared in the header file
-@file{<math.h>}.
+mathematical computations, such as trigonometric functions.  Most of
+these functions have prototypes declared in the header file
+@file{math.h}.
+@pindex math.h
 
-@strong{Incomplete:}  This chapter doesn't have any examples.
+All of the functions that operate on floating-point numbers accept
+arguments and return results of type @code{double}.  In the future,
+there may be additional functions that operate on @code{float} and
+@code{long double} values.  For example, @code{cosf} and @code{cosl}
+would be versions of the @code{cos} function that operate on
+@code{float} and @code{long double} arguments, respectively.  In the
+meantime, you should avoid using these names yourself.  @xref{Reserved
+Names}.
 
 @menu
-* Domain and Range Errors::            How overflow conditions and the like
-                                        are reported.
-* Trigonometric Functions::            Sine, cosine, and tangent.
-* Inverse Trigonometric Functions::    Arc sine, arc cosine, and arc tangent.
-* Exponentiation and Logarithms::      Also includes square root.
-* Hyperbolic Functions::               Hyperbolic sine and friends.
-* Normalization Functions::            Hacks for radix-2 representations.
-* Rounding and Remainder Functions::   Determinining the integer and
-                                        fractional parts of a float.
-* Pseudo-Random Numbers::              Functions for generating pseudo-random
-                                        numbers.
-* Integer Division::                   Functions for performing integer
-                                        division.
-* Absolute Value::                     Absolute value functions.
-* Predicates on Floats::               Some miscellaneous test functions.
-* Parsing of Numbers::                 Functions for ``reading'' numbers
-                                        from strings.
+* Domain and Range Errors::     Detecting overflow conditions and the like.
+* Trig Functions::              Sine, cosine, and tangent.
+* Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
+* Exponents and Logarithms::    Also includes square root.
+* Hyperbolic Functions::        Hyperbolic sine and friends.
+* Pseudo-Random Numbers::       Functions for generating pseudo-random
+                                numbers.
 @end menu
 
 @node Domain and Range Errors
@@ -37,151 +34,155 @@ 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
-this is taking the square root of a negative number.  Since the C
-language has no support for complex numbers, this is treated like a
-domain error.
+this is taking the square root of a negative number.  The functions in
+this chapter take only real arguments and return only real values;
+therefore, if the value ought to be nonreal, this is treated as a domain
+error.
 
 @cindex range error
 A related problem is that the mathematical result of a function may not
-be representable as a floating point number.  If magnitude of the result
-is too large to be represented, the value of the macro @code{HUGE_VAL}
-is returned (with the appropriate sign), and @code{errno} is set to
-@code{ERANGE} to indicate a @dfn{range error}.  If the magnitude of the
-result is too small, a value of zero is returned instead.  In the case
-of underflow, @code{errno} might or might not be set to @code{ERANGE}.
-
-None of these functions ever generate externally visible exceptions
-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 Handling}, for more information about signals.
+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 (@w{@code{- HUGE_VAL}}).
 
-All of the functions that operate on floating-point numbers accept
-arguments and return results of type @code{double}.  In future revisions
-of the ANSI C standard, additional functions may be added that operate
-on @code{float} and @code{long double} values.  For example, @code{cosf}
-and @code{cosl} would be versions of the @code{cos} function that
-operate on @code{float} and @code{long double} arguments, respectively.
-In the meantime, you should avoid using these names yourself.
-@xref{Reserved Names}.
+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
+set to @code{ERANGE}.
+
+The only completely reliable way to check for domain and range errors is
+to set @code{errno} to @code{0} before you call the mathematical function 
+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
+Handling}, for more information about signals.)
 
 @comment math.h
 @comment ANSI
-@defvr Macro HUGE_VAL
-This macro expands into a (possibly non-constant) expression of type
-@code{double} representing a very large positive number.  This is
-typically either the largest representable floating-point number, or a
-value indicating infinity if the floating-point representation has one.
-(The IEEE floating-point does have such a reserved value.)
+@deftypevr Macro double HUGE_VAL
+An expression representing a particular very large number.  On machines
+that use IEEE floating point format, the value is ``infinity''.  On
+other machines, it's typically the largest positive number that can be
+represented.
 
 The value of this macro is used as the return value from various 
 mathematical functions in overflow situations.
-@end defvr
+@end deftypevr
 
 For more information about floating-point representations and limits,
-@xref{Floating-Point Limits}.  In particular, the macro @code{DBL_MAX}
-might be more appropriate than @code{HUGE_VAL} for many uses.
+see @ref{Floating Point Parameters}.  In particular, the macro
+@code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many
+uses other than testing for an error in a mathematical function.
 
-
-@node Trigonometric Functions
+@node Trig Functions
 @section Trigonometric Functions
-
-@strong{Incomplete:}  What font convention should be used for things
-like ``pi'' and ``e''?
+@cindex trigonometric functions
 
 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
-The arguments to all of these functions are specified in radians; recall
-that pi radians is equivalent to 180 degrees.  
+The arguments to all of these functions are in units of radians; recall
+that pi radians equals 180 degrees.
 
 @cindex pi (trigonometric constant)
 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 @samp{acos (-1.0)}.
+You can also compute the value of pi with the expression @code{acos
+(-1.0)}.
 
 
 @comment math.h
 @comment ANSI
 @deftypefun double sin (double @var{x})
-This function returns the sine of @var{x}, which is given in radians.
-The return value is in the range @code{-1} to @code{1}.
+This function returns the sine of @var{x}, where @var{x} is given in
+radians.  The return value is in the range @code{-1} to @code{1}.
 @end deftypefun
 
 @comment math.h
 @comment ANSI
 @deftypefun double cos (double @var{x})
-This function returns the cosine of @var{x}, which is given in radians.
-The return value is in the range @code{-1} to @code{1}.
+This function returns the cosine of @var{x}, where @var{x} is given in
+radians.  The return value is in the range @code{-1} to @code{1}.
 @end deftypefun
 
 @comment math.h
 @comment ANSI
 @deftypefun double tan (double @var{x})
-This function returns the tangent of @var{x}, which is given in radians.
+This function returns the tangent of @var{x}, where @var{x} is given in
+radians.
 
 The following @code{errno} error conditions are defined for this function:
 
 @table @code
 @item ERANGE
-Mathematically, the tangent function has singularities at odd multiples of
-pi/2.  If the argument @var{x} is too close to one of these singularities,
-@code{tan} sets this error condition and returns either positive or
-negative @code{HUGE_VAL}.
+Mathematically, the tangent function has singularities at odd multiples
+of pi/2.  If the argument @var{x} is too close to one of these
+singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
+either positive or negative @code{HUGE_VAL}.
 @end table
 @end deftypefun
 
 
-@node Inverse Trigonometric Functions
+@node Inverse Trig Functions
 @section Inverse Trigonometric Functions
+@cindex inverse trigonmetric functions
 
-These are the usual arc sine, arc cosine, and arc tangent functions.
+These are the usual arc sine, arc cosine and arc tangent functions,
+which are the inverses of the sine, cosine and tangent functions,
+respectively.
 
 @comment math.h
 @comment ANSI
 @deftypefun double asin (double @var{x})
-This function computes the arc sine of @var{x}.  The return value is
-given in radians and is in the range -pi/2 to pi/2 (inclusive).
-
-The following @code{errno} error conditions are defined for this function:
+This function computes the arc sine of @var{x}---that is, the value whose
+sine is @var{x}.  The value is in units of radians.  Mathematically,
+there are infinitely many such values; the one actually returned is the
+one between @code{-pi/2} and @code{pi/2} (inclusive).
 
-@table @code
-@item EDOM
-The argument @var{x} is out of range.  The arc sine function is defined
-mathematically only over the domain -1 to 1.
-@end table
+@code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
+out of range.  The arc sine function is defined mathematically only
+over the domain @code{-1} to @code{1}.
 @end deftypefun
 
 @comment math.h
 @comment ANSI
 @deftypefun double acos (double @var{x})
-This function computes the arc cosine of @var{x}.  The return value is
-given in radians and is in the range 0 to pi (inclusive).
-
-The following @code{errno} error conditions are defined for this function:
+This function computes the arc cosine of @var{x}---that is, the value
+whose cosine is @var{x}.  The value is in units of radians.
+Mathematically, there are infinitely many such values; the one actually
+returned is the one between @code{0} and @code{pi} (inclusive).
 
-@table @code
-@item EDOM
-The argument @var{x} is out of range.  The arc cosine function is defined
-mathematically only over the domain -1 to 1.
-@end table
+@code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
+out of range.  The arc cosine function is defined mathematically only
+over the domain @code{-1} to @code{1}.
 @end deftypefun
 
 
 @comment math.h
 @comment ANSI
 @deftypefun double atan (double @var{x})
-This function returns the arc tangent of @var{x}.  The return value is
-given in radians and is in the range -pi/2 to pi/2 (inclusive).
+This function computes the arc tangent of @var{x}---that is, the value
+whose tangent is @var{x}.  The value is in units of radians.
+Mathematically, there are infinitely many such values; the one actually
+returned is the one between @code{-pi/2} and @code{pi/2}
+(inclusive).
 @end deftypefun
 
 @comment math.h
@@ -191,20 +192,26 @@ This is the two argument arc tangent function.  It is similar to computing
 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
 are used to determine the quadrant of the result, and @var{x} is
 permitted to be zero.  The return value is given in radians and is in
-the range -pi to pi (inclusive).
+the range @code{-pi} to @code{pi}, inclusive.
 
-The following @code{errno} error conditions are defined for this function:
+If @var{x} and @var{y} are coordinates of a point in the plane,
+@code{atan2} returns the signed angle between the line from the origin
+to that point and the x-axis.  Thus, @code{atan2} is useful for
+converting Cartesian coordinates to polar coordinates.  (To compute the
+radial coordinate, use @code{hypot}; see @ref{Exponents and
+Logarithms}.)
 
-@table @code
-@item EDOM
-Both the @var{x} and @var{y} arguments are zero; the value of the
-function is not defined in this case.
-@end table
+The function @code{atan2} sets @code{errno} to @code{EDOM} if both
+@var{x} and @var{y} are zero; the return value is not defined in this
+case.
 @end deftypefun
 
 
-@node Exponentiation and Logarithms
+@node Exponents and Logarithms
 @section Exponentiation and Logarithms
+@cindex exponentiation functions
+@cindex power functions
+@cindex logarithm functions
 
 @comment math.h
 @comment ANSI
@@ -212,29 +219,26 @@ function is not defined in this case.
 The @code{exp} function returns the value of e (the base of natural
 logarithms) raised to power @var{x}.
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item ERANGE
-The magnitude of the result is too large to be representable.
-@end table
+The function fails, and sets @code{errno} to @code{ERANGE}, if the
+magnitude of the result is too large to be representable.
 @end deftypefun
 
 @comment math.h
 @comment ANSI
 @deftypefun double log (double @var{x})
-This function returns the natural logarithm of @var{x}.
+This function returns the natural logarithm of @var{x}.  @code{exp (log
+(@var{x}))} equals @var{x}, exactly in mathematics and approximately in
+C.
 
 The following @code{errno} error conditions are defined for this function:
 
 @table @code
 @item EDOM
-The log function is defined mathematically to return a non-complex
-result only on positive arguments.  This error is used to report a
-negative argument @var{x}.
+The argument @var{x} is negative.  The log function is defined
+mathematically to return a real result only on positive arguments.
 
 @item ERANGE
-The result of the function on an argument of zero is not defined.
+The argument is zero.  The log of zero is not defined.
 @end table
 @end deftypefun
 
@@ -242,7 +246,8 @@ The result of the function on an argument of zero is not defined.
 @comment ANSI
 @deftypefun double log10 (double @var{x})
 This function returns the base-10 logarithm of @var{x}.  Except for the
-different base, it is similar to the @code{log} function.
+different base, it is similar to the @code{log} function.  In fact,
+@code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
 @end deftypefun
 
 @comment math.h
@@ -251,6 +256,7 @@ different base, it is similar to the @code{log} function.
 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
@@ -263,323 +269,170 @@ An underflow or overflow condition was detected in the result.
 @end table
 @end deftypefun
 
+@cindex square root function
 @comment math.h
 @comment ANSI
 @deftypefun double sqrt (double @var{x})
 This function returns the nonnegative square root of @var{x}.
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The argument @var{x} is negative.  Mathematically, the square root would
-be a complex number.
-@end table
+The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
+@var{x} is negative.  Mathematically, the square root would be a complex
+number.
 @end deftypefun
 
+@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 returns the cube root of @var{x}.  This function cannot
+fail; every representable real value has a representable real cube root.
 @end deftypefun
 
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double hypot (double @var{x}, double @var{y})
 The @code{hypot} function returns @code{sqrt (@var{x}*@var{x} +
 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
 triangle with sides of length @var{x} and @var{y}, or the distance
-of the point (@var{x}, @var{y}) from the origin.)
-@end deftypefun
-
-@comment math.h
-@comment GNU
-@deftypefun double cabs (struct @{ double x, y; @} @var{z})
-The @code{cabs} function is similar to @code{hypot}, but the argument
-is specified as a @code{struct} representing a complex number.
+of the point (@var{x}, @var{y}) from the origin.)  See also the function
+@code{cabs} in @ref{Absolute Value}.
 @end deftypefun
 
-
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double expm1 (double @var{x})
 This function returns a value equivalent to @code{exp (@var{x}) - 1}.
-It is computed in a way that is accurate even if the value of @var{x}
-is very small.
+It is computed in a way that is accurate even if the value of @var{x} is
+near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
+to subtraction of two numbers that are nearly equal.
 @end deftypefun
 
-
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double log1p (double @var{x})
-This function returns a value equivalent to @code{log (1 + @var{x})}.
-It is computed in a way that is accurate even if the value of @var{x}
-is very small.
+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
 
-
-
 @node Hyperbolic Functions
 @section Hyperbolic Functions
+@cindex hyperbolic functions
 
-The functions in this section are related to the exponential and
-functions; @pxref{Exponentiation and Logarithms}.
+The functions in this section are related to the exponential functions;
+see @ref{Exponents and Logarithms}.
 
 @comment math.h
 @comment ANSI
 @deftypefun double sinh (double @var{x})
-The @code{sinh} function returns the hyperbolic sine of @var{x}.  The
-following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item ERANGE
-The value of the argument @var{x} is too large; an overflow condition
-was detected.
-@end table
+The @code{sinh} function returns the hyperbolic sine of @var{x}, 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
 
 @comment math.h
 @comment ANSI
 @deftypefun double cosh (double @var{x})
-The @code{cosh} function returns the hyperbolic cosine of @var{x}.  The
-following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item ERANGE
-The value of the argument @var{x} is too large; an overflow condition
-was detected.
-@end table
+The @code{cosh} function returns the hyperbolic cosine of @var{x},
+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
 
 @comment math.h
 @comment ANSI
 @deftypefun double tanh (double @var{x})
-This function returns the hyperbolic tangent of @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
+
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double asinh (double @var{x})
-This function returns the inverse hyperbolic cosine of @var{x}.
+This function returns the inverse hyperbolic sine of @var{x}---the
+value whose hyperbolic sine is @var{x}.
 @end deftypefun
 
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double acosh (double @var{x})
-This function returns the inverse hyperbolic cosine of @var{x}.  If
-the argument is less than @code{1}, @code{acosh} returns @code{HUGE_VAL}.
+This function returns the inverse hyperbolic cosine of @var{x}---the
+value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
+@code{1}, @code{acosh} returns @code{HUGE_VAL}.
 @end deftypefun
 
 @comment math.h
-@comment GNU
+@comment BSD
 @deftypefun double atanh (double @var{x})
-This function returns the inverse hyperbolic cosine of @var{x}.  If
-the absolute value of the argument is greater than or equal to @code{1},
-@code{atanh} returns @code{HUGE_VAL}.
+This function returns the inverse hyperbolic tangent of @var{x}---the
+value whose hyperbolic tangent is @var{x}.  If the absolute value of
+@var{x} is greater than or equal to @code{1}, @code{atanh} returns
+@code{HUGE_VAL}.
 @end deftypefun
 
-
-@node Normalization Functions
-@section Normalization Functions
-
-The functions described in this section are primarily provided as a way
-to efficiently perform certain low-level manipulations on floating point
-numbers that are represented internally using a binary radix;
-@pxref{Floating-Point Representation}.  These functions are required to
-have equivalent behavior even if the representation does not use a radix
-of 2, but of course they are unlikely to be particularly efficient in
-those cases.
-
-@comment math.h
-@comment GNU
-@deftypefun double copysign (double @var{value}, double @var{sign})
-The @code{copysign} function returns a value whose absolute value is the
-same as that of @var{value}, and whose sign matches that of @var{sign}.
-@end deftypefun
-
-@comment math.h
-@comment ANSI
-@deftypefun double frexp (double @var{value}, int *@var{exponent})
-The @code{frexp} function is used to normalize the number @var{value}.
-
-If the argument @var{value} is not zero, the return value is a
-floating-point number with magnitude in the range 1/2 (inclusive) to 1
-(exclusive).  The corresponding exponent is stored in the location
-pointed at by @var{exponent}; the return value multiplied by 2 raised to
-this exponent is equal to the original number @var{value}.
-
-If @var{value} is zero, then both parts of the result are zero.
-@end deftypefun
-
-@comment math.h
-@comment ANSI
-@deftypefun double ldexp (double @var{value}, int @var{exponent})
-This function returns the result of multiplying the floating-point
-number @var{value} by 2 raised to the power @var{exponent}.  (It can
-be used to reassemble floating-point numbers that were taken apart
-by @code{frexp}.)
-@end deftypefun
-
-@comment math.h
-@comment GNU
-@deftypefun double scalb (double @var{value}, int @var{exponent})
-The @code{scalb} function does the same thing as @code{ldexp}.
-@end deftypefun
-
-@comment math.h
-@comment GNU
-@deftypefun double logb (double @var{x})
-This function returns the base-2 exponent of @var{x}, an integer value
-converted to a @code{double}.  The return value is such that dividing
-the absolute value of @var{x} by @code{2} raised to this power is
-greater than or equal to @code{1}, but less than @code{2}.
-
-@strong{Incomplete:}  What happens if @var{x} is zero?
-@end deftypefun
-
-
-@node Rounding and Remainder Functions
-@section Rounding and Remainder Functions
-
-The functions listed here perform operations such as rounding, 
-truncation, and remainder computation.
-
-You can also convert floating-point numbers to integers simply by
-casting them to @code{int}.  This discards the fractional part,
-effectively rounding towards zero.  However, this only works if the
-result can actually be represented as an @code{int} --- for very large
-numbers, the result is undefined.  The functions listed here return the
-result as a @code{double} instead to get around this problem.
-
-@comment math.h
-@comment ANSI
-@deftypefun double ceil (double @var{x})
-The @code{ceil} function rounds @var{x} upwards to the nearest integer,
-returning that value as a @code{double}.
-@end deftypefun
-
-@comment math.h
-@comment ANSI
-@deftypefun double floor (double @var{x})
-The @code{ceil} function rounds @var{x} downwards to the nearest
-integer, returning that value as a @code{double}.
-@end deftypefun
-
-@comment math.h
-@comment GNU
-@deftypefun double rint (double @var{x})
-This function returns the integer nearest @var{x} according to the
-current rounding mode.  @xref{Floating-Point Parameters}, for information
-about the @code{FLT_ROUNDS} macro.
-@end deftypefun
-
-@comment math.h
-@comment ANSI
-@deftypefun double modf (double @var{value}, double *@var{integer_part})
-This function breaks the argument @var{value} into an integer part and a
-fractional part.  Each of the parts has the same sign as the original
-@var{value}, so the rounding of the integer part is towards zero.  The
-integer part is stored at the location pointed at by @var{integer_part},
-and the fractional part is returned.
-@end deftypefun
-
-
-@comment math.h
-@comment ANSI
-@deftypefun double fmod (double @var{numerator}, double @var{denominator})
-This function computes the remainder from dividing @var{numerator} by
-@var{denominator}.  The result has the same sign as the @var{numerator}
-and has magnitude less than the magnitude of the @var{denominator}.
-(Recall that the built-in @samp{%} operator isn't defined on
-floating-point values.)
-
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The @var{denominator} is zero.
-@end table
-@end deftypefun
-
-@comment math.h
-@comment GNU
-@deftypefun double drem (double @var{numerator}, double @var{denominator})
-This function returns the remainder from dividing @var{numerator} by
-@var{denominator}.  Specifically, the return value is @code{@var{numerator}
-- @var{n} * @var{denominator}}, where @var{n} is the integer closest to
-the exact quotient of @var{numerator} and @var{denominator}.  The absolute
-value of the result is less than or equal to one half the absolute value
-of the @var{denominator}.
-
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The @var{denominator} is zero.
-@end table
-@end deftypefun
-
-
 @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 C
-Random Number Functions}, 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 Number Functions}, are derived from BSD Unix.  This uses a better
-random number generator (producing numbers that are more random), but
-is 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.  However,
-the actual algorithm used to generate the random number series may be
-implementation-dependent or implementation-dependent.
-
+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 C Random Number Functions::     @code{rand} and friends.
-* BSD Random Number Functions::                @code{random} and friends.
+* ANSI Random::      @code{rand} and friends.
+* BSD Random::       @code{random} and friends.
 @end menu
 
-@node ANSI C Random Number Functions
+@node ANSI Random
 @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.
+@file{stdlib.h} in your program.
+@pindex stdlib.h
 
 @comment stdlib.h
 @comment ANSI
-@defvr Macro RAND_MAX
+@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.  It is guaranteed to be at least @code{32767}.
-@end defvr
+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
 @comment ANSI
-@deftypefun int rand (void)
+@deftypefun int rand ()
 The @code{rand} function returns the next pseudo-random number in the
 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
 @end deftypefun
@@ -588,24 +441,27 @@ series.  The value is in the range from @code{0} to @code{RAND_MAX}.
 @comment ANSI
 @deftypefun void srand (unsigned int @var{seed})
 This function establishes @var{seed} as the seed for a new series of
-pseudo-random numbers.  If @code{rand} is called before a seed has been
-established with @code{srand}, it is equivalent to having specified an
-initial seed value of @code{1}.
+pseudo-random numbers.  If you call @code{rand} before a seed has been
+established with @code{srand}, it uses the value @code{1} as a default
+seed.
+
+To produce truly random numbers (not just pseudo-random), do @code{srand
+(time (0))}.
 @end deftypefun
 
-@node BSD Random Number Functions
+@node BSD Random
 @subsection BSD Random Number Functions
 
-This section describes a set of random number generation functions
-that are derived from BSD Unix.  The @code{random} function can generate
-better random numbers than @code{rand}, because it maintains more bits
-of internal state.
+This section describes a set of random number generation functions that
+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>}.
+The prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
 
 @comment stdlib.h
 @comment BSD
-@deftypefun long int random (void)
+@deftypefun {long int} random ()
 This function returns the next pseudo-random number in the sequence.
 The range of values returned is from @code{0} to @code{RAND_MAX}.
 @end deftypefun
@@ -614,26 +470,26 @@ The range of values returned is from @code{0} to @code{RAND_MAX}.
 @comment BSD
 @deftypefun void srandom (unsigned int @var{seed})
 The @code{srandom} function sets the seed for the current random number
-state to @var{seed}.  If you supply a @var{seed} value of @code{1}, this
-will cause @code{random} to reproduce the default set of random numbers.
-@end deftypefun
+state based on the integer @var{seed}.  If you supply a @var{seed} value
+of @code{1}, this will cause @code{random} to reproduce the default set
+of random numbers.
 
-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.
+To produce truly random numbers (not just pseudo-random), do
+@code{srandom (time (0))}.
+@end deftypefun
 
 @comment stdlib.h
 @comment BSD
 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
 The @code{initstate} function is used to initialize the random number
-generator state.  The @var{state} is an array of @var{size} bytes, used to
-hold the state information.  The size must be at least 8 bytes, and optimal
-sizes are 8, 16, 32, 64, 128, and 256.  The bigger the @var{state} array,
-the better.
+generator state.  The argument @var{state} is an array of @var{size}
+bytes, used to hold the state information.  The size must be at least 8
+bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
+the @var{state} array, the better.
 
 The return value is the previous value of the state information array.
+You can use this value later as an argument to @code{setstate} to
+restore that state.
 @end deftypefun
 
 @comment stdlib.h
@@ -644,326 +500,6 @@ information @var{state}.  The argument must have been the result of
 a previous call to @var{initstate} or @var{setstate}.  
 
 The return value is the previous value of the state information array.
+You can use thise value later as an argument to @code{setstate} to
+restore that state.
 @end deftypefun
-
-
-
-
-
-@node Integer Division
-@section Integer Division
-
-This section describes functions for performing integer division.
-To use these facilities, you should include the header file
-@file{<stdlib.h>} in your program.
-
-These functions are not necessarily equivalent to the division performed
-by the built-in @code{/} and @code{%} operators.  While the built-in
-division operator is permitted to round in either direction if the
-quotient is negative, the @code{div} and @code{ldiv} functions are
-required to round towards zero.  It is also required that these
-functions return a result @var{r} such that
-@code{@var{r}.quot*@var{denominator} + @var{r}.rem} be equal to
-@var{numerator}.
-
-@comment stdlib.h
-@comment ANSI
-@deftp {Data Type} div_t
-This is a structure type used to hold the result returned by the @code{div}
-function.  It has the following members:
-
-@table @code
-@item {int quot}
-The quotient from the division.
-
-@item {int rem}
-The remainder from the division.
-@end table
-@end deftp
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun div_t div (int @var{numerator}, int @var{denominator})
-This function @code{div} computes the quotient and remainder from
-the division of @var{numerator} by @var{denominator}, returning the
-result in a structure of type @code{div_t}.
-
-If the result cannot be represented (as in a division by zero), the
-behavior is undefined.
-@end deftypefun
-
-
-@comment stdlib.h
-@comment ANSI
-@deftp {Data Type} ldiv_t
-This is a structure type used to hold the result returned by the @code{ldiv}
-function.  It has the following members:
-
-@table @code
-@item {long int quot}
-The quotient from the division.
-
-@item {long int rem}
-The remainder from the division.
-@end table
-
-(This is identical to the type @code{div_t} except that the components
-are of type @code{long int} rather than @code{int}.)
-@end deftp
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun ldiv_t ldiv (long int @var{numerator}, long int @var{denominator})
-The @code{ldiv} function is similar to @code{div}, except that the
-arguments are of type @code{long int} and the result is returned as a
-structure of type @code{ldiv}.
-@end deftypefun
-
-
-@node Absolute Value
-@section Absolute Value
-
-These functions are provided for obtaining the absolute value of
-integer values.  Prototypes for @code{abs} and @code{abs} are declared
-in @file{<stdlib.h>}; @code{fabs} is declared in @file{<math.h>}.
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun int abs (int @var{number})
-This function returns the absolute value (or magnitude) of @var{number}.
-In a two's complement integer representation, the absolute value of
-@code{INT_MIN} (the smallest possible @code{int}) cannot be represented;
-in this case, the behavior of @code{abs} is undefined.
-@end deftypefun
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun {long int} labs (long int @var{number})
-This is similar to @code{abs}, except that both the argument and result
-are of type @code{long int} rather than @code{int}.
-@end deftypefun
-
-@comment math.h
-@comment ANSI
-@deftypefun double fabs (double @var{number})
-This function returns the absolute value of the floating-point number
-@var{number}.
-@end deftypefun
-
-There is also the function @code{cabs} for computing the absolute value
-of a complex number; @pxref{Exponentiation and Logarithms}.
-
-@node Parsing of Numbers
-@section Parsing of Numbers
-@cindex parsing of numbers
-@cindex string conversion
-@cindex number syntax
-
-This section describes functions for ``reading'' integer and
-floating-point numbers from a string.  In many cases, it is more
-appropriate to use @code{sscanf} or one of the related functions;
-@pxref{Formatted Input}.  The syntax recognized by the formatted input
-functions for the numeric conversions is exactly the same as the syntax
-recognized by the functions described in this section.
-
-These functions are declared in @file{<stdlib.h>}.
-
-@menu
-* Parsing of Integers::                Functions for conversion of integer values.
-* Parsing of Floats::          Functions for conversion of floating-point
-                                values.
-@end menu
-
-@node Parsing of Integers
-@subsection Parsing of Integers
-@cindex parsing of integers
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
-The @code{strtol} (``string-to-long'') function converts the initial
-part of @var{string} to a signed integer, which is returned as a value
-of type @code{long int}.  
-
-This function attempts to decompose @var{string} as follows:
-
-@itemize @bullet
-@item 
-A (possibly empty) sequence of whitespace characters, as determined by
-the @code{isspace} function (@pxref{Classification of Characters}).
-These are discarded.
-
-@item 
-An optional plus or minus sign (@samp{+} or @samp{-}).
-
-@item 
-A nonempty sequence of digits in the radix specified by @var{base}.  If
-@var{base} is zero, decimal radix is assumed unless the series of digits
-begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
-(specifying hexadecimal radix); in other words, the same syntax that is
-used for integer constants in the C language is recognized.  Otherwise
-@var{base} must have a value between @code{2} and @code{35}.  If
-@var{base} is @code{16}, the digits may optionally be preceeded by
-@samp{0x} or @samp{0X}.
-
-@item 
-Any remaining characters in the string.  If @var{tailptr} is not a null
-pointer, a pointer to this tail of the string is stored in the object
-it points to.
-@end itemize
-
-If the string is empty, contains only whitespace, or does not contain an
-initial substring that has the expected syntax for an integer in the
-specified @var{base}, no conversion is performed.  In this case,
-@code{strtol} returns a value of zero and the value returned in
-@var{tailptr} is the value of @var{string}.
-
-In a locale other than the standard @code{"C"} locale, this function
-may recognize additional implementation-dependent syntax.
-
-If the string has valid syntax for an integer but the value is not
-representable because of overflow, @code{strtol} returns either
-@code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
-Limits}), as appropriate for the sign of the value.
-
-The following @code{errno} error conditions are defined for this
-function:
-
-@table @code
-@item ERANGE
-An overflow condition was detected.
-@end table
-@end deftypefun
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
-The @code{strtoul} (``string-to-unsigned-long'') function is similar to
-@code{strtol} except that it returns its value as an object of type
-@code{unsigned long int}.  The value returned in case of overflow is
-@code{ULONG_MAX} (@pxref{Integer Representation Limits}).
-@end deftypefun
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun {long int} atol (const char *@var{string})
-This function is similar to the @code{strtol} function with a @var{base}
-argument of @code{10}, except that it need not detect overflow errors.
-The @code{atol} function is provided mostly for compatibility with
-existing code; using @code{strtol} is considered better style.
-@end deftypefun
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun int atoi (const char *@var{string})
-This function is similar to the @code{atol} function, except that
-returns its value as an @code{int} rather than @code{long int}.  The
-@code{atoi} function is also considered obsolete; use @code{strtol}
-instead.
-@end deftypefun
-
-@node Predicates on Floats
-@subsection Predicates on Floats
-
-This section describes some miscellaneous test functions on doubles.
-Prototypes for these functions appear in @file{<math.h>}.
-
-@comment math.h
-@comment GNU
-@deftypefun int isinf (double @var{x})
-This function returns @code{-1} if @var{x} represents negative infinity,
-@code{1} if @var{x} represents positive infinity, and @code{0} otherwise.
-@end deftypefun
-
-@comment math.h
-@comment GNU
-@deftypefun int isnan (double @var{x})
-This function returns a nonzero value if @var{x} is the ``not a number''
-value, and zero otherwise.
-@end deftypefun
-
-@comment math.h
-@comment GNU
-@deftypefun int finite (double @var{x})
-This function returns a nonzero value if @var{x} is finite or the ``not
-a number'' value, and zero otherwise.
-@end deftypefun
-
-@comment math.h
-@comment GNU
-@deftypefun double infnan (int @var{error})
-@strong{Incomplete:}  I don't understand what this function does.
-@end deftypefun
-
-
-
-@strong{Portability Note:} The functions listed in this section are GNU
-extensions.
-
-@node Parsing of Floats
-@subsection Parsing of Floats
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
-The @code{strtod} (``string-to-double'') function converts the initial
-part of @var{string} to a floating-point number, which is returned as a
-value of type @code{double}.  
-
-This function attempts to decompose @var{string} as follows:
-
-@itemize @bullet
-@item 
-A (possibly empty) sequence of whitespace characters, as determined
-by the @code{isspace} function.  These are discarded.
-
-@item
-An optional plus or minus sign (@samp{+} or @samp{-}).
-
-@item
-A nonempty sequence of digits optionally containing a decimal-point
-character (@samp{.}).
-
-@item
-An optional exponent part, consisting of a character @samp{e} or
-@samp{E}, an optional sign, and a sequence of digits.
-
-@item
-Any remaining characters in the string.  If @var{tailptr} is not a null
-pointer, a pointer to this tail of the string is stored in the object it
-points to.
-@end itemize
-
-If the string is empty, contains only whitespace, or does not contain
-an initial substring that has the expected syntax for a floating-point
-number, no conversion is performed.  In this case, @code{strtod} returns
-a value of zero and the value returned in @var{tailptr} is the value of
-@var{string}.
-
-In a locale other than the standard @code{"C"} locale, this function
-may recognize additional implementation-dependent syntax.
-
-If the string has valid syntax for a floating-point number but the value
-is not representable because of overflow, @code{strtod} returns either
-positive or negative @code{HUGE_VAL} (@pxref{Mathematics}), depending on
-the sign of the value.  Similarly, if the value is not representable
-because of underflow, @code{strtod} returns zero.
-
-The following @code{errno} error conditions are defined for this
-function:
-
-@table @code
-@item ERANGE
-An overflow or underflow condition was detected.
-@end table
-@end deftypefun
-
-@comment stdlib.h
-@comment ANSI
-@deftypefun double atof (const char *@var{string})
-This function is similar to the @code{strtod} function, except that it
-need not detect overflow and underflow errors.  The @code{atof} function
-is provided mostly for compatibility with existing code; using
-@code{strtod} is considered better style.
-@end deftypefun
-