index 1ec2441..7ebcdde 100644 (file)
-@node Mathematics
+@c We need some definitions here.
+@ifclear mult
+@ifhtml
+@set mult &middot;
+@set infty &infin;
+@set pie &pi;
+@end ifhtml
+@iftex
+@set mult @cdot
+@set infty @infty
+@end iftex
+@ifclear mult
+@set mult *
+@set infty oo
+@set pie pi
+@end ifclear
+@macro mul
+@value{mult}
+@end macro
+@macro infinity
+@value{infty}
+@end macro
+@ifnottex
+@macro pi
+@value{pie}
+@end macro
+@end ifnottex
+@end ifclear
+
+@node Mathematics, Arithmetic, Syslog, Top
+@c %MENU% Math functions, useful constants, random numbers
@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}.  The complex-valued functions are defined in
+@file{complex.h}.
@pindex math.h
-
-@strong{Incomplete:}  This chapter doesn't have any examples.
+@pindex complex.h
+
+All mathematical functions which take a floating-point argument
+have three variants, one each for @code{double}, @code{float}, and
+@code{long double} arguments.  The @code{double} versions are mostly
+defined in @w{ISO C89}.  The @code{float} and @code{long double}
+versions are from the numeric extensions to C included in @w{ISO C99}.
+
+Which of the three versions of a function should be used depends on the
+situation.  For most calculations, the @code{float} functions are the
+fastest.  On the other hand, the @code{long double} functions have the
+highest precision.  @code{double} is somewhere in between.  It is
+usually wise to pick the narrowest type that can accommodate your data.
+Not all machines have a distinct @code{long double} type; it may be the
+same as @code{double}.

-* 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.
+* Mathematical Constants::      Precise numeric values for often-used
+                                 constants.
+* Trig Functions::              Sine, cosine, tangent, and friends.
+* Inverse Trig Functions::      Arcsine, arccosine, etc.
+* Exponents and Logarithms::    Also pow and sqrt.
+* Hyperbolic Functions::        sinh, cosh, tanh, etc.
+* Special Functions::           Bessel, gamma, erf.
+* Errors in Math Functions::    Known Maximum Errors in Math Functions.
+* Pseudo-Random Numbers::       Functions for generating pseudo-random
+                                numbers.
+* FP Function Optimizations::   Fast code or small code.

-@node Domain and Range Errors
-@section Domain and Range Errors
-
-@cindex domain error
-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}.
-
-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.
-
-@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.
-
-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}.
-
-@comment math.h
-@comment ANSI
-@deftypevr Macro double HUGE_VAL
-This macro expands into a (possibly non-constant) expression
-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.)
-
-The value of this macro is used as the return value from various
-mathematical functions in overflow situations.
-@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.
-
-
-@node Trigonometric Functions
+@node Mathematical Constants
+@section Predefined Mathematical Constants
+@cindex constants
+@cindex mathematical constants
+
+The header @file{math.h} defines several useful mathematical constants.
+All values are defined as preprocessor macros starting with @code{M_}.
+The values provided are:
+
+@vtable @code
+@item M_E
+The base of natural logarithms.
+@item M_LOG2E
+The logarithm to base @code{2} of @code{M_E}.
+@item M_LOG10E
+The logarithm to base @code{10} of @code{M_E}.
+@item M_LN2
+The natural logarithm of @code{2}.
+@item M_LN10
+The natural logarithm of @code{10}.
+@item M_PI
+Pi, the ratio of a circle's circumference to its diameter.
+@item M_PI_2
+Pi divided by two.
+@item M_PI_4
+Pi divided by four.
+@item M_1_PI
+The reciprocal of pi (1/pi)
+@item M_2_PI
+Two times the reciprocal of pi.
+@item M_2_SQRTPI
+Two times the reciprocal of the square root of pi.
+@item M_SQRT2
+The square root of two.
+@item M_SQRT1_2
+The reciprocal of the square root of two (also the square root of 1/2).
+@end vtable
+
+These constants come from the Unix98 standard and were also available in
+4.4BSD; therefore they are only defined if @code{_BSD_SOURCE} or
+@code{_XOPEN_SOURCE=500}, or a more general feature select macro, is
+defined.  The default set of features includes these constants.
+@xref{Feature Test Macros}.
+
+All values are of type @code{double}.  As an extension, the GNU C
+library also defines these constants with type @code{long double}.  The
+@code{long double} macros have a lowercase @samp{l} appended to their
+names: @code{M_El}, @code{M_PIl}, and so forth.  These are only
+available if @code{_GNU_SOURCE} is defined.
+
+@vindex PI
+@emph{Note:} Some programs use a constant named @code{PI} which has the
+same value as @code{M_PI}.  This constant is not standard; it may have
+appeared in some old AT&T headers, and is mentioned in Stroustrup's book
+on C++.  It infringes on the user's name space, so the GNU C library
+does not define it.  Fixing programs written to expect it is simple:
+replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI}
+on the compiler command line.
+
+@node Trig Functions
@section Trigonometric Functions
-@cindex trignometric 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:
+The math library normally defines @code{M_PI} to a @code{double}
+approximation of pi.  If strict ISO and/or POSIX compliance
+are requested this constant is not defined, but you can easily define it
+yourself:

-@example
-#define PI 3.14159265358979323846264338327
-@end example
+@smallexample
+#define M_PI 3.14159265358979323846264338327
+@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
+@comment ISO
@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}.
+@comment math.h
+@comment ISO
+@deftypefunx float sinf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} sinl (long double @var{x})
+These functions return 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
+@comment ISO
@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}.
+@comment math.h
+@comment ISO
+@deftypefunx float cosf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} cosl (long double @var{x})
+These functions return 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
+@comment ISO
@deftypefun double tan (double @var{x})
-This function returns the tangent of @var{x}, which is given in radians.
+@comment math.h
+@comment ISO
+@deftypefunx float tanf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} tanl (long double @var{x})
+These functions return the tangent of @var{x}, where @var{x} is given in
+
+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} will signal overflow.
+@end deftypefun
+
+In many applications where @code{sin} and @code{cos} are used, the sine
+and cosine of the same angle are needed at the same time.  It is more
+efficient to compute them simultaneously, so the library provides a
+function to do that.
+
+@comment math.h
+@comment GNU
+@deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
+@comment math.h
+@comment GNU
+@deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
+@comment math.h
+@comment GNU
+@deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
+These functions return the sine of @var{x} in @code{*@var{sinx}} and the
+cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
+radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
+the range of @code{-1} to @code{1}.
+
+This function is a GNU extension.  Portable programs should be prepared
+to cope with its absence.
+@end deftypefun
+
+@cindex complex trigonometric functions
+
+@w{ISO C99} defines variants of the trig functions which work on
+complex numbers.  The GNU C library provides these functions, but they
+are only useful if your compiler supports the new complex types defined
+by the standard.
+@c XXX Change this when gcc is fixed. -zw
+(As of this writing GCC supports complex numbers, but there are bugs in
+the implementation.)
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csin (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} csinf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} csinl (complex long double @var{z})
+These functions return the complex sine of @var{z}.
+The mathematical definition of the complex sine is
+
+@ifnottex
+@math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
+@end ifnottex
+@tex
+$$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
+@end tex
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ccos (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ccosf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ccosl (complex long double @var{z})
+These functions return the complex cosine of @var{z}.
+The mathematical definition of the complex cosine is
+
+@ifnottex
+@math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
+@end ifnottex
+@tex
+$$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
+@end tex
+@end deftypefun

-The following @code{errno} error conditions are defined for this function:
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ctan (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ctanf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ctanl (complex long double @var{z})
+These functions return the complex tangent of @var{z}.
+The mathematical definition of the complex tangent is
+
+@ifnottex
+@math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
+@end ifnottex
+@tex
+$$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
+@end tex

-@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}.
-@end table
+@noindent
+The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an
+integer.  @code{ctan} may signal overflow if @var{z} is too close to a
+pole.
@end deftypefun

-@node Inverse Trigonometric Functions
+@node Inverse Trig Functions
@section Inverse Trigonometric Functions
-@cindex inverse trigonmetric functions
+@cindex inverse trigonometric 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
+@comment ISO
@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:
-
-@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
+@comment math.h
+@comment ISO
+@deftypefunx float asinf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} asinl (long double @var{x})
+These functions compute 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).
+
+The arc sine function is defined mathematically only
+over the domain @code{-1} to @code{1}.  If @var{x} is outside the
+domain, @code{asin} signals a domain error.
@end deftypefun

@comment math.h
-@comment ANSI
+@comment ISO
@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:
-
-@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
+@comment math.h
+@comment ISO
+@deftypefunx float acosf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} acosl (long double @var{x})
+These functions compute 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).
+
+The arc cosine function is defined mathematically only
+over the domain @code{-1} to @code{1}.  If @var{x} is outside the
+domain, @code{acos} signals a domain error.
@end deftypefun

-
@comment math.h
-@comment ANSI
+@comment ISO
@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).
+@comment math.h
+@comment ISO
+@deftypefunx float atanf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} atanl (long double @var{x})
+These functions compute 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
-@comment ANSI
+@comment ISO
@deftypefun double atan2 (double @var{y}, double @var{x})
-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).
+@comment math.h
+@comment ISO
+@deftypefunx float atan2f (float @var{y}, float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
+This function computes the arc tangent of @var{y}/@var{x}, but 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 @code{-pi} to @code{pi}, inclusive.
+
+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}.)
+
+@c This is experimentally true.  Should it be so? -zw
+If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
+@end deftypefun
+
+@cindex inverse complex trigonometric functions
+@w{ISO C99} defines complex versions of the inverse trig functions.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} casin (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} casinf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} casinl (complex long double @var{z})
+These functions compute the complex arc sine of @var{z}---that is, the
+value whose sine is @var{z}.  The value returned is in radians.
+
+Unlike the real-valued functions, @code{casin} is defined for all
+values of @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cacos (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cacosf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cacosl (complex long double @var{z})
+These functions compute the complex arc cosine of @var{z}---that is, the
+value whose cosine is @var{z}.  The value returned is in radians.
+
+Unlike the real-valued functions, @code{cacos} is defined for all
+values of @var{z}.
+@end deftypefun

-The following @code{errno} error conditions are defined for this function:

-@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
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} catan (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} catanf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} catanl (complex long double @var{z})
+These functions compute the complex arc tangent of @var{z}---that is,
+the value whose tangent is @var{z}.  The value is in units of radians.
@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
+@comment ISO
@deftypefun double exp (double @var{x})
-The @code{exp} function returns the value of e (the base of natural
-logarithms) raised to power @var{x}.
+@comment math.h
+@comment ISO
+@deftypefunx float expf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} expl (long double @var{x})
+These functions compute @code{e} (the base of natural logarithms) raised
+to the power @var{x}.

-The following @code{errno} error conditions are defined for this function:
+If the magnitude of the result is too large to be representable,
+@code{exp} signals overflow.
+@end deftypefun

-@table @code
-@item ERANGE
-The magnitude of the result is too large to be representable.
-@end table
+@comment math.h
+@comment ISO
+@deftypefun double exp2 (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float exp2f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} exp2l (long double @var{x})
+These functions compute @code{2} raised to the power @var{x}.
+Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
@end deftypefun

@comment math.h
-@comment ANSI
-@deftypefun double log (double @var{x})
-This function returns the natural logarithm of @var{x}.
+@comment GNU
+@deftypefun double exp10 (double @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx float exp10f (float @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx {long double} exp10l (long double @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx double pow10 (double @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx float pow10f (float @var{x})
+@comment math.h
+@comment GNU
+@deftypefunx {long double} pow10l (long double @var{x})
+These functions compute @code{10} raised to the power @var{x}.
+Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.

-The following @code{errno} error conditions are defined for this function:
+These functions are GNU extensions.  The name @code{exp10} is
+preferred, since it is analogous to @code{exp} and @code{exp2}.
+@end deftypefun

-@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}.

-@item ERANGE
-The result of the function on an argument of zero is not defined.
-@end table
+@comment math.h
+@comment ISO
+@deftypefun double log (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float logf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} logl (long double @var{x})
+These functions compute the natural logarithm of @var{x}.  @code{exp (log
+(@var{x}))} equals @var{x}, exactly in mathematics and approximately in
+C.
+
+If @var{x} is negative, @code{log} signals a domain error.  If @var{x}
+is zero, it returns negative infinity; if @var{x} is too close to zero,
+it may signal overflow.
@end deftypefun

@comment math.h
-@comment ANSI
+@comment ISO
@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.
+@comment math.h
+@comment ISO
+@deftypefunx float log10f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} log10l (long double @var{x})
+These functions return the base-10 logarithm of @var{x}.
+@code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
+
@end deftypefun

@comment math.h
-@comment ANSI
-@deftypefun double pow (double @var{base}, double @var{power})
-This is a general exponentiation function, returning @var{base} raised
-to @var{power}.
+@comment ISO
+@deftypefun double log2 (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float log2f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} log2l (long double @var{x})
+These functions return the base-2 logarithm of @var{x}.
+@code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun double logb (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float logbf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} logbl (long double @var{x})
+These functions extract the exponent of @var{x} and return it as a
+floating-point value.  If @code{FLT_RADIX} is two, @code{logb} is equal
+to @code{floor (log2 (x))}, except it's probably faster.
+
+If @var{x} is de-normalized, @code{logb} returns the exponent @var{x}
+would have if it were normalized.  If @var{x} is infinity (positive or
+negative), @code{logb} returns @math{@infinity{}}.  If @var{x} is zero,
+@code{logb} returns @math{@infinity{}}.  It does not signal.
+@end deftypefun
+
+@comment math.h
+@comment ISO
+@deftypefun int ilogb (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx int ilogbf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx int ilogbl (long double @var{x})
+These functions are equivalent to the corresponding @code{logb}
+functions except that they return signed integer values.
+@end deftypefun
+
+@noindent
+Since integers cannot represent infinity and NaN, @code{ilogb} instead
+returns an integer that can't be the exponent of a normal floating-point
+number.  @file{math.h} defines constants so you can check for this.
+
+@comment math.h
+@comment ISO
+@deftypevr Macro int FP_ILOGB0
+@code{ilogb} returns this value if its argument is @code{0}.  The
+numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
+
+This macro is defined in @w{ISO C99}.
+@end deftypevr
+
+@comment math.h
+@comment ISO
+@deftypevr Macro int FP_ILOGBNAN
+@code{ilogb} returns this value if its argument is @code{NaN}.  The
+numeric value is either @code{INT_MIN} or @code{INT_MAX}.
+
+This macro is defined in @w{ISO C99}.
+@end deftypevr

-The following @code{errno} error conditions are defined for this function:
+These values are system specific.  They might even be the same.  The
+proper way to test the result of @code{ilogb} is as follows:
+
+@smallexample
+i = ilogb (f);
+if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
+  @{
+    if (isnan (f))
+      @{
+        /* @r{Handle NaN.}  */
+      @}
+    else if (f  == 0.0)
+      @{
+        /* @r{Handle 0.0.}  */
+      @}
+    else
+      @{
+        /* @r{Some other value with large exponent,}
+           @r{perhaps +Inf.}  */
+      @}
+  @}
+@end smallexample

-@table @code
-@item EDOM
-The argument @var{base} is negative and @var{power} is not an integral
-value.  Mathematically, the result would be a complex number in this case.
+@comment math.h
+@comment ISO
+@deftypefun double pow (double @var{base}, double @var{power})
+@comment math.h
+@comment ISO
+@deftypefunx float powf (float @var{base}, float @var{power})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} powl (long double @var{base}, long double @var{power})
+These are general exponentiation functions, returning @var{base} raised
+to @var{power}.

-@item ERANGE
-An underflow or overflow condition was detected in the result.
-@end table
+Mathematically, @code{pow} would return a complex number when @var{base}
+is negative and @var{power} is not an integral value.  @code{pow} can't
+do that, so instead it signals a domain error. @code{pow} may also
+underflow or overflow the destination type.
@end deftypefun

@cindex square root function
@comment math.h
-@comment ANSI
+@comment ISO
@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:
+@comment math.h
+@comment ISO
+@deftypefunx float sqrtf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} sqrtl (long double @var{x})
+These functions return the nonnegative square root of @var{x}.

-@table @code
-@item EDOM
-The argument @var{x} is negative.  Mathematically, the square root would
-be a complex number.
-@end table
+If @var{x} is negative, @code{sqrt} signals a domain error.
+Mathematically, it should return 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}.
+@comment math.h
+@comment BSD
+@deftypefunx float cbrtf (float @var{x})
+@comment math.h
+@comment BSD
+@deftypefunx {long double} cbrtl (long double @var{x})
+These functions return the cube root of @var{x}.  They cannot
+fail; every representable real value has a representable real cube root.
@end deftypefun

@comment math.h
-@comment GNU
+@comment ISO
@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
+@comment math.h
+@comment ISO
+@deftypefunx float hypotf (float @var{x}, float @var{y})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
+These functions return @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.)
+of the point (@var{x}, @var{y}) from the origin.  Using this function
+instead of the direct formula is wise, since the error is
+much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
@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.
+@comment ISO
+@deftypefun double expm1 (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float expm1f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} expm1l (long double @var{x})
+These functions return a value equivalent to @code{exp (@var{x}) - 1}.
+They are computed in a way that is accurate even if @var{x} is
+near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing
+to subtraction of two numbers that are nearly equal.
@end deftypefun

-
@comment math.h
-@comment GNU
-@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.
+@comment ISO
+@deftypefun double log1p (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float log1pf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} log1pl (long double @var{x})
+These functions returns a value equivalent to @w{@code{log (1 + @var{x})}}.
+They are computed in a way that is accurate even if @var{x} is
+near zero.
@end deftypefun

+@cindex complex exponentiation functions
+@cindex complex logarithm functions
+
+@w{ISO C99} defines complex variants of some of the exponentiation and
+logarithm functions.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cexp (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cexpf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cexpl (complex long double @var{z})
+These functions return @code{e} (the base of natural
+logarithms) raised to the power of @var{z}.
+Mathematically, this corresponds to the value
+
+@ifnottex
+@math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
+@end ifnottex
+@tex
+$$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
+@end tex
+@end deftypefun

-@comment math.h
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} clog (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} clogf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} clogl (complex long double @var{z})
+These functions return the natural logarithm of @var{z}.
+Mathematically, this corresponds to the value
+
+@ifnottex
+@math{log (z) = log (cabs (z)) + I * carg (z)}
+@end ifnottex
+@tex
+$$\log(z) = \log |z| + i \arg z$$
+@end tex
+
+@noindent
+@code{clog} has a pole at 0, and will signal overflow if @var{z} equals
+or is very close to 0.  It is well-defined for all other values of
+@var{z}.
+@end deftypefun
+
+
+@comment complex.h
@comment GNU
-@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.
+@deftypefun {complex double} clog10 (complex double @var{z})
+@comment complex.h
+@comment GNU
+@deftypefunx {complex float} clog10f (complex float @var{z})
+@comment complex.h
+@comment GNU
+@deftypefunx {complex long double} clog10l (complex long double @var{z})
+These functions return the base 10 logarithm of the complex value
+@var{z}. Mathematically, this corresponds to the value
+
+@ifnottex
+@math{log (z) = log10 (cabs (z)) + I * carg (z)}
+@end ifnottex
+@tex
+$$\log_{10}(z) = \log_{10}|z| + i \arg z$$
+@end tex
+
+These functions are GNU extensions.
@end deftypefun

+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csqrt (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} csqrtf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} csqrtl (complex long double @var{z})
+These functions return the complex square root of the argument @var{z}.  Unlike
+the real-valued functions, they are defined for all values of @var{z}.
+@end deftypefun

+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
+These functions return @var{base} raised to the power of
+@var{power}.  This is equivalent to @w{@code{cexp (y * clog (x))}}
+@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
+@comment ISO
@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
+@comment math.h
+@comment ISO
+@deftypefunx float sinhf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} sinhl (long double @var{x})
+These functions return the hyperbolic sine of @var{x}, defined
+mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  They
+may signal overflow if @var{x} is too large.
@end deftypefun

@comment math.h
-@comment ANSI
+@comment ISO
@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
+@comment math.h
+@comment ISO
+@deftypefunx float coshf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} coshl (long double @var{x})
+These function return the hyperbolic cosine of @var{x},
+defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
+They may signal overflow if @var{x} is too large.
@end deftypefun

@comment math.h
-@comment ANSI
+@comment ISO
@deftypefun double tanh (double @var{x})
-This function returns the hyperbolic tangent of @var{x}.
+@comment math.h
+@comment ISO
+@deftypefunx float tanhf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} tanhl (long double @var{x})
+These functions return the hyperbolic tangent of @var{x},
+defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
+They may signal overflow if @var{x} is too large.
+@end deftypefun
+
+@cindex hyperbolic functions
+
+There are counterparts for the hyperbolic functions which take
+complex arguments.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csinh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} csinhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} csinhl (complex long double @var{z})
+These functions return the complex hyperbolic sine of @var{z}, defined
+mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ccosh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ccoshf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ccoshl (complex long double @var{z})
+These functions return the complex hyperbolic cosine of @var{z}, defined
+mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.
@end deftypefun

+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ctanh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ctanhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ctanhl (complex long double @var{z})
+These functions return the complex hyperbolic tangent of @var{z},
+defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
+@end deftypefun
+
+
@cindex inverse hyperbolic functions

@comment math.h
-@comment GNU
+@comment ISO
@deftypefun double asinh (double @var{x})
-This function returns the inverse hyperbolic cosine of @var{x}.
+@comment math.h
+@comment ISO
+@deftypefunx float asinhf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} asinhl (long double @var{x})
+These functions return the inverse hyperbolic sine of @var{x}---the
+value whose hyperbolic sine is @var{x}.
@end deftypefun

@comment math.h
-@comment GNU
+@comment ISO
@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}.
+@comment math.h
+@comment ISO
+@deftypefunx float acoshf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} acoshl (long double @var{x})
+These functions return 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} signals a domain error.
@end deftypefun

@comment math.h
-@comment GNU
+@comment ISO
@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}.
+@comment math.h
+@comment ISO
+@deftypefunx float atanhf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} atanhl (long double @var{x})
+These functions return 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 @code{1}, @code{atanh} signals a domain error;
+if it is equal to 1, @code{atanh} returns infinity.
@end deftypefun

+@cindex inverse complex hyperbolic functions
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} casinh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} casinhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} casinhl (complex long double @var{z})
+These functions return the inverse complex hyperbolic sine of
+@var{z}---the value whose complex hyperbolic sine is @var{z}.
+@end deftypefun

-@node Normalization Functions
-@section Normalization Functions
-@cindex normalization functions (floating-point)
-
-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 complex.h
+@comment ISO
+@deftypefun {complex double} cacosh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cacoshf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cacoshl (complex long double @var{z})
+These functions return the inverse complex hyperbolic cosine of
+@var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
+the real-valued functions, there are no restrictions on the value of @var{z}.
+@end deftypefun

-@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}.
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} catanh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} catanhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} catanhl (complex long double @var{z})
+These functions return the inverse complex hyperbolic tangent of
+@var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
+the real-valued functions, there are no restrictions on the value of
+@var{z}.
@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}.
+@node Special Functions
+@section Special Functions
+@cindex special functions
+@cindex Bessel functions
+@cindex gamma function

-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}.
+These are some more exotic mathematical functions which are sometimes
+useful.  Currently they only have real-valued versions.

-If @var{value} is zero, then both parts of the result are zero.
+@comment math.h
+@comment SVID
+@deftypefun double erf (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float erff (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} erfl (long double @var{x})
+@code{erf} returns the error function of @var{x}.  The error
+function is defined as
+@tex
+$$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
+@end smallexample
+@end ifnottex
@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}.)
+@comment SVID
+@deftypefun double erfc (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float erfcf (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} erfcl (long double @var{x})
+@code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
+fashion that avoids round-off error when @var{x} is large.
@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}.
+@comment SVID
+@deftypefun double lgamma (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float lgammaf (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} lgammal (long double @var{x})
+@code{lgamma} returns the natural logarithm of the absolute value of
+the gamma function of @var{x}.  The gamma function is defined as
+@tex
+$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
+@end smallexample
+@end ifnottex
+
+@vindex signgam
+The sign of the gamma function is stored in the global variable
+@var{signgam}, which is declared in @file{math.h}.  It is @code{1} if
+the intermediate result was positive or zero, or @code{-1} if it was
+negative.
+
+To compute the real gamma function you can use the @code{tgamma}
+function or you can compute the values as follows:
+@smallexample
+lgam = lgamma(x);
+gam  = signgam*exp(lgam);
+@end smallexample
+
+The gamma function has singularities at the non-positive integers.
+@code{lgamma} will raise the zero divide exception if evaluated at a
+singularity.
@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?
+@comment XPG
+@deftypefun double lgamma_r (double @var{x}, int *@var{signp})
+@comment math.h
+@comment XPG
+@deftypefunx float lgammaf_r (float @var{x}, int *@var{signp})
+@comment math.h
+@comment XPG
+@deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp})
+@code{lgamma_r} is just like @code{lgamma}, but it stores the sign of
+the intermediate result in the variable pointed to by @var{signp}
+instead of in the @var{signgam} global.  This means it is reentrant.
@end deftypefun

-
-@node Rounding and Remainder Functions
-@section Rounding and Remainder Functions
-@cindex rounding functions
-@cindex remainder functions
-@cindex converting floats to integers
-
-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}.
+@comment SVID
+@deftypefun double gamma (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float gammaf (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} gammal (long double @var{x})
+These functions exist for compatibility reasons.  They are equivalent to
+@code{lgamma} etc.  It is better to use @code{lgamma} since for one the
+name reflects better the actual computation, moreover @code{lgamma} is
+standardized in @w{ISO C99} while @code{gamma} is not.
@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}.
+@comment XPG, ISO
+@deftypefun double tgamma (double @var{x})
+@comment math.h
+@comment XPG, ISO
+@deftypefunx float tgammaf (float @var{x})
+@comment math.h
+@comment XPG, ISO
+@deftypefunx {long double} tgammal (long double @var{x})
+@code{tgamma} applies the gamma function to @var{x}.  The gamma
+function is defined as
+@tex
+$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
+@end smallexample
+@end ifnottex
+
+This function was introduced in @w{ISO C99}.
@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
+@comment SVID
+@deftypefun double j0 (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float j0f (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} j0l (long double @var{x})
+@code{j0} returns the Bessel function of the first kind of order 0 of
+@var{x}.  It may signal underflow if @var{x} is too large.
@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.
+@comment SVID
+@deftypefun double j1 (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float j1f (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} j1l (long double @var{x})
+@code{j1} returns the Bessel function of the first kind of order 1 of
+@var{x}.  It may signal underflow if @var{x} is too large.
@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
+@comment SVID
+@deftypefun double jn (int n, double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float jnf (int n, float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} jnl (int n, long double @var{x})
+@code{jn} returns the Bessel function of the first kind of order
+@var{n} of @var{x}.  It may signal underflow if @var{x} is too large.
@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}.
+@comment SVID
+@deftypefun double y0 (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float y0f (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} y0l (long double @var{x})
+@code{y0} returns the Bessel function of the second kind of order 0 of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{y0} signals a domain error; if it is zero,
+@code{y0} signals overflow and returns @math{-@infinity}.
+@end deftypefun

-The following @code{errno} error conditions are defined for this function:
+@comment math.h
+@comment SVID
+@deftypefun double y1 (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float y1f (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} y1l (long double @var{x})
+@code{y1} returns the Bessel function of the second kind of order 1 of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{y1} signals a domain error; if it is zero,
+@code{y1} signals overflow and returns @math{-@infinity}.
+@end deftypefun

-@table @code
-@item EDOM
-The @var{denominator} is zero.
-@end table
+@comment math.h
+@comment SVID
+@deftypefun double yn (int n, double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float ynf (int n, float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} ynl (int n, long double @var{x})
+@code{yn} returns the Bessel function of the second kind of order @var{n} of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{yn} signals a domain error; if it is zero,
+@code{yn} signals overflow and returns @math{-@infinity}.
@end deftypefun

+@node Errors in Math Functions
+@section Known Maximum Errors in Math Functions
+@cindex math errors
+@cindex ulps
+
+This section lists the known errors of the functions in the math
+library.  Errors are measured in units of the last place''.  This is a
+measure for the relative error.  For a number @math{z} with the
+representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE
+floating-point numbers with base 2) the ULP is represented by
+
+@tex
+$${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$
+@end tex
+@ifnottex
+@smallexample
+|d.d...d - (z / 2^e)| / 2^(p - 1)
+@end smallexample
+@end ifnottex
+
+@noindent
+where @math{p} is the number of bits in the mantissa of the
+floating-point number representation.  Ideally the error for all
+functions is always less than 0.5ulps.  Using rounding bits this is also
+possible and normally implemented for the basic operations.  To achieve
+the same for the complex math functions requires a lot more work and
+this has not yet been done.
+
+Therefore many of the functions in the math library have errors.  The
+table lists the maximum error for each function which is exposed by one
+of the existing tests in the test suite.  The table tries to cover as much
+as possible and list the actual maximum error (or at least a ballpark
+figure) but this is often not achieved due to the large search space.
+
+The table lists the ULP values for different architectures.  Different
+architectures have different results since their hardware support for
+floating-point operations varies and also the existing hardware support
+is different.
+
+@page
+@c This multitable does not fit on a single page
+@include libm-err.texi

@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 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 a different
+pseudo-random series each time your program runs, you must specify a
+different seed each time.  For ordinary purposes, basing the seed on the
+current time works well.
+
+You can obtain 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 @w{ISO C} random number functions
+plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
+functions provide identical, somewhat limited functionality.  If only a
+small number of random bits are required, we recommend you use the
+@w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
+provide a more flexible interface, which allows better random number
+generator algorithms, provides more random bits (up to 48) per call, and
+can provide random floating-point numbers.  These functions are required
+by the XPG standard and therefore will be present in all modern Unix
+systems.

-* ANSI C Random Number Functions::     @code{rand} and friends.
-* BSD Random Number Functions::                @code{random} and friends.
+* ISO Random::                  @code{rand} and friends.
+* BSD Random::                  @code{random} and friends.
+* SVID Random::                 @code{drand48} and friends.

-@node ANSI C Random Number Functions
-@subsection ANSI C Random Number Functions
+@node ISO Random
+@subsection ISO 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 @w{ISO C} standard.

To use these facilities, you should include the header file
@file{stdlib.h} in your program.
@pindex stdlib.h

@comment stdlib.h
-@comment ANSI
+@comment ISO
@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}.
+The value of this macro is an integer constant representing the largest
+value the @code{rand} function can return.  In the GNU library, it is
+@code{2147483647}, 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
+@comment ISO
@deftypefun int rand (void)
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}.
+series.  The value ranges from @code{0} to @code{RAND_MAX}.
@end deftypefun

@comment stdlib.h
-@comment ANSI
+@comment ISO
@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 a different pseudo-random series each time your program is
+run, do @code{srand (time (0))}.
@end deftypefun

-@node BSD Random Number Functions
+POSIX.1 extended the C standard functions to support reproducible random
+designed and unsuitable for serious work.
+
+@comment stdlib.h
+@comment POSIX.1
+@deftypefun int rand_r (unsigned int *@var{seed})
+This function returns a random number in the range 0 to @code{RAND_MAX}
+just as @code{rand} does.  However, all its state is stored in the
+@var{seed} argument.  This means the RNG's state can only have as many
+bits as the type @code{unsigned int} has.  This is far too few to
+provide a good RNG.
+
+If your program requires a reentrant RNG, we recommend you use the
+reentrant GNU extensions to the SVID random number generator.  The
+POSIX.1 interface should only be used when the GNU extensions are not
+available.
+@end deftypefun
+
+
+@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}.
@pindex stdlib.h

@comment stdlib.h
@comment BSD
-@deftypefun long int random (void)
+@deftypefun {long int} random (void)
This function returns the next pseudo-random number in the sequence.
-The range of values returned is from @code{0} to @code{RAND_MAX}.
+The value returned ranges from @code{0} to @code{RAND_MAX}.
+
+@strong{Note:} Temporarily this function was defined to return a
+@code{int32_t} value to indicate that the return value always contains
+32 bits even if @code{long int} is wider.  The standard demands it
+differently.  Users must always be aware of the 32-bit limitation,
+though.
@end deftypefun

@comment stdlib.h
@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
+The @code{srandom} function sets the state of the random number
+generator 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 a different set of pseudo-random numbers each time your
+program runs, 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.  It is initialized based on
+@var{seed}.  The size must be between 8 and 256 bytes, and should be a
+power of two.  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
The return value is the previous value of the state information array.
@deftypefun {void *} setstate (void *@var{state})
The @code{setstate} function restores the random number state
information @var{state}.  The argument must have been the result of
-a previous call to @var{initstate} or @var{setstate}.
+a previous call to @var{initstate} or @var{setstate}.

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.
+
+If the function fails the return value is @code{NULL}.
@end deftypefun

+The four functions described so far in this section all work on a state
+which is shared by all threads.  The state is not directly accessible to
+the user and can only be modified by these functions.  This makes it
+hard to deal with situations where each thread should have its own
+pseudo-random number generator.

+The GNU C library contains four additional functions which contain the
+state as an explicit parameter and therefore make it possible to handle
+thread-local PRNGs.  Beside this there are no difference.  In fact, the
+four functions already discussed are implemented internally using the
+following interfaces.

+The @file{stdlib.h} header contains a definition of the following type:

+@comment stdlib.h
+@comment GNU
+@deftp {Data Type} {struct random_data}

-@node Integer Division
-@section Integer Division
-@cindex integer division functions
+Objects of type @code{struct random_data} contain the information
+necessary to represent the state of the PRNG.  Although a complete
+definition of the type is present the type should be treated as opaque.
+@end deftp

-This section describes functions for performing integer division.
-To use these facilities, you should include the header file
-@file{stdlib.h} in your program.
-@pindex stdlib.h
+The functions modifying the state follow exactly the already described
+functions.

-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 GNU
+@deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result})
+The @code{random_r} function behaves exactly like the @code{random}
+function except that it uses and modifies the state in the object
+pointed to by the first parameter instead of the global state.
+@end deftypefun

@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 GNU
+@deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf})
+The @code{srandom_r} function behaves exactly like the @code{srandom}
+function except that it uses and modifies the state in the object
+pointed to by the second parameter instead of the global state.
+@end deftypefun

@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}.
+@comment GNU
+@deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf})
+The @code{initstate_r} function behaves exactly like the @code{initstate}
+function except that it uses and modifies the state in the object
+pointed to by the fourth parameter instead of the global state.
+@end deftypefun

-If the result cannot be represented (as in a division by zero), the
-behavior is undefined.
+@comment stdlib.h
+@comment GNU
+@deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf})
+The @code{setstate_r} function behaves exactly like the @code{setstate}
+function except that it uses and modifies the state in the object
+pointed to by the first parameter instead of the global state.
@end deftypefun

+@node SVID Random
+@subsection SVID Random Number Function

-@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:
+The C library on SVID systems contains yet another kind of random number
+generator functions.  They use a state of 48 bits of data.  The user can
+choose among a collection of functions which return the random bits
+in different forms.

-@table @code
-@item {long int quot}
-The quotient from the division.
+Generally there are two kinds of function.  The first uses a state of
+the random number generator which is shared among several functions and
+by all threads of the process.  The second requires the user to handle
+the state.

-@item {long int rem}
-The remainder from the division.
-@end table
+All functions have in common that they use the same congruential
+formula with the same constants.  The formula is

-(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
+@smallexample
+Y = (a * X + c) mod m
+@end smallexample

-@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
+@noindent
+where @var{X} is the state of the generator at the beginning and
+@var{Y} the state at the end.  @code{a} and @code{c} are constants
+determining the way the generator works.  By default they are

+@smallexample
+a = 0x5DEECE66D = 25214903917
+c = 0xb = 11
+@end smallexample

-@node Absolute Value
-@section Absolute Value
-@cindex absolute value functions
+@noindent
+but they can also be changed by the user.  @code{m} is of course 2^48
+since the state consists of a 48-bit array.

-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}.
-@pindex math.h
+The prototypes for these functions are in @file{stdlib.h}.
@pindex stdlib.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.
+@comment SVID
+@deftypefun double drand48 (void)
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive).  The random bits are determined by the global
+state of the random number generator in the C library.
+
+Since the @code{double} type according to @w{IEEE 754} has a 52-bit
+mantissa this means 4 bits are not initialized by the random number
+generator.  These are (of course) chosen to be the least significant
+bits and they are initialized to @code{0}.
@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}.
+@comment SVID
+@deftypefun double erand48 (unsigned short int @var{xsubi})
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive), similarly to @code{drand48}.  The argument is
+an array describing the state of the random number generator.
+
+This function can be called subsequently since it updates the array to
+guarantee random numbers.  The array should have been initialized before
+initial use to obtain reproducible results.
@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}.
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} lrand48 (void)
+The @code{lrand48} function returns an integer value in the range of
+@code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
+int} type can take more than 32 bits, no higher numbers are returned.
+The random bits are determined by the global state of the random number
+generator in the C library.
@end deftypefun

-There is also the function @code{cabs} for computing the absolute value
-of a complex number; @pxref{Exponentiation and Logarithms}.
-
-
-@node Predicates on Floats
-@section Predicates on Floats
-@cindex predicates on floats
-
-This section describes some miscellaneous test functions on doubles.
-Prototypes for these functions appear in @file{math.h}.
-@pindex 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.
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} nrand48 (unsigned short int @var{xsubi})
+This function is similar to the @code{lrand48} function in that it
+returns a number in the range of @code{0} to @code{2^31} (exclusive) but
+the state of the random number generator used to produce the random bits
+is determined by the array provided as the parameter to the function.
+
+The numbers in the array are updated afterwards so that subsequent calls
+to this function yield different results (as is expected of a random
+number generator).  The array should have been initialized before the
+first call to obtain reproducible results.
@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.
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} mrand48 (void)
+The @code{mrand48} function is similar to @code{lrand48}.  The only
+difference is that the numbers returned are in the range @code{-2^31} to
+@code{2^31} (exclusive).
@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.
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} jrand48 (unsigned short int @var{xsubi})
+The @code{jrand48} function is similar to @code{nrand48}.  The only
+difference is that the numbers returned are in the range @code{-2^31} to
+@code{2^31} (exclusive).  For the @code{xsubi} parameter the same
+requirements are necessary.
@end deftypefun

-@comment math.h
-@comment GNU
-@deftypefun double infnan (int @var{error})
-@strong{Incomplete:}  I don't understand what this function does.
+The internal state of the random number generator can be initialized in
+several ways.  The methods differ in the completeness of the
+information provided.
+
+@comment stdlib.h
+@comment SVID
+@deftypefun void srand48 (long int @var{seedval})
+The @code{srand48} function sets the most significant 32 bits of the
+internal state of the random number generator to the least
+significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
+are initialized to the value @code{0x330E}.  Even if the @code{long
+int} type contains more than 32 bits only the lower 32 bits are used.
+
+Owing to this limitation, initialization of the state of this
+function is not very useful.  But it makes it easy to use a construct
+like @code{srand48 (time (0))}.
+
+A side-effect of this function is that the values @code{a} and @code{c}
+from the internal state, which are used in the congruential formula,
+are reset to the default values given above.  This is of importance once
+the user has called the @code{lcong48} function (see below).
@end deftypefun

-@strong{Portability Note:} The functions listed in this section are GNU
-extensions.
+@comment stdlib.h
+@comment SVID
+@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v})
+The @code{seed48} function initializes all 48 bits of the state of the
+internal random number generator from the contents of the parameter
+@var{seed16v}.  Here the lower 16 bits of the first element of
+@var{see16v} initialize the least significant 16 bits of the internal
+state, the lower 16 bits of @code{@var{seed16v}} initialize the mid-order
+16 bits of the state and the 16 lower bits of @code{@var{seed16v}}
+initialize the most significant 16 bits of the state.
+
+Unlike @code{srand48} this function lets the user initialize all 48 bits
+of the state.
+
+The value returned by @code{seed48} is a pointer to an array containing
+the values of the internal state before the change.  This might be
+useful to restart the random number generator at a certain state.
+Otherwise the value can simply be ignored.
+
+As for @code{srand48}, the values @code{a} and @code{c} from the
+congruential formula are reset to the default values.
+@end deftypefun

-@node Parsing of Numbers
-@section Parsing of Numbers
-@cindex parsing numbers (in formatted input)
-@cindex converting strings to numbers
-@cindex number syntax, parsing
+There is one more function to initialize the random number generator
+which enables you to specify even more information by allowing you to
+change the parameters in the congruential formula.

-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.
+@comment stdlib.h
+@comment SVID
+@deftypefun void lcong48 (unsigned short int @var{param})
+The @code{lcong48} function allows the user to change the complete state
+of the random number generator.  Unlike @code{srand48} and
+@code{seed48}, this function also changes the constants in the
+congruential formula.
+
+From the seven elements in the array @var{param} the least significant
+16 bits of the entries @code{@var{param}} to @code{@var{param}}
+determine the initial state, the least significant 16 bits of
+@code{@var{param}} to @code{@var{param}} determine the 48 bit
+constant @code{a} and @code{@var{param}} determines the 16-bit value
+@code{c}.
+@end deftypefun

-These functions are declared in @file{stdlib.h}.
-@pindex stdlib.h
+All the above functions have in common that they use the global
+parameters for the congruential formula.  In multi-threaded programs it
+might sometimes be useful to have different parameters in different
+threads.  For this reason all the above functions have a counterpart
+which works on a description of the random number generator in the
+user-supplied buffer instead of the global state.

-* Parsing of Integers::                Functions for conversion of integer values.
-* Parsing of Floats::          Functions for conversion of floating-point
-                                values.
+Please note that it is no problem if several threads use the global
+state if all threads use the functions which take a pointer to an array
+containing the state.  The random numbers are computed following the
+same loop but if the state in the array is different all threads will
+obtain an individual random number generator.

-@node Parsing of Integers
-@subsection Parsing of Integers
+The user-supplied buffer must be of type @code{struct drand48_data}.
+This type should be regarded as opaque and not manipulated directly.

@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}).
-
-@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}
-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
-
-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
+@comment GNU
+@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is equivalent to the @code{drand48} function with the
+difference that it does not modify the global random number generator
+parameters but instead the parameters in the buffer supplied through the
+pointer @var{buffer}.  The random number is returned in the variable
+pointed to by @var{result}.
+
+The return value of the function indicates whether the call succeeded.
+If the value is less than @code{0} an error occurred and @var{errno} is
+set to indicate the problem.
+
+This function is a GNU extension and should not be used in portable
+programs.
@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}).
+@comment GNU
+@deftypefun int erand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, double *@var{result})
+The @code{erand48_r} function works like @code{erand48}, but in addition
+it takes an argument @var{buffer} which describes the random number
+generator.  The state of the random number generator is taken from the
+@code{xsubi} array, the parameters for the congruential formula from the
+global random number generator data.  The random number is returned in
+the variable pointed to by @var{result}.
+
+The return value is non-negative if the call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
@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.
+@comment GNU
+@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is similar to @code{lrand48}, but in addition it takes a
+pointer to a buffer describing the state of the random number generator
+just like @code{drand48}.
+
+If the return value of the function is non-negative the variable pointed
+to by @var{result} contains the result.  Otherwise an error occurred.
+
+This function is a GNU extension and should not be used in portable
+programs.
@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}
+@comment GNU
+@deftypefun int nrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
+The @code{nrand48_r} function works like @code{nrand48} in that it
+produces a random number in the range @code{0} to @code{2^31}.  But instead
+of using the global parameters for the congruential formula it uses the
+information from the buffer pointed to by @var{buffer}.  The state is
+described by the values in @var{xsubi}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
@end deftypefun

+@comment stdlib.h
+@comment GNU
+@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is similar to @code{mrand48} but like the other reentrant
+functions it uses the random number generator described by the value in
+the buffer pointed to by @var{buffer}.

-@node Parsing of Floats
-@subsection Parsing of Floats
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.

-@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 is a GNU extension and should not be used in portable
+programs.
+@end deftypefun

-This function attempts to decompose @var{string} as follows:
+@comment stdlib.h
+@comment GNU
+@deftypefun int jrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
+The @code{jrand48_r} function is similar to @code{jrand48}.  Like the
+other reentrant functions of this function family it uses the
+congruential formula parameters from the buffer pointed to by
+@var{buffer}.

-@itemize @bullet
-@item
-A (possibly empty) sequence of whitespace characters, as determined
-by the @code{isspace} function.  These are discarded.
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.

-@item
-An optional plus or minus sign (@samp{+} or @samp{-}).
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun

-@item
-A nonempty sequence of digits optionally containing a decimal-point
-character (@samp{.}).
+Before any of the above functions are used the buffer of type
+@code{struct drand48_data} should be initialized.  The easiest way to do
+this is to fill the whole buffer with null bytes, e.g. by

-@item
-An optional exponent part, consisting of a character @samp{e} or
-@samp{E}, an optional sign, and a sequence of digits.
+@smallexample
+memset (buffer, '\0', sizeof (struct drand48_data));
+@end smallexample

-@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
+@noindent
+Using any of the reentrant functions of this family now will
+automatically initialize the random number generator to the default
+values for the state and the parameters of the congruential formula.

-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}.
+The other possibility is to use any of the functions which explicitly
+initialize the buffer.  Though it might be obvious how to initialize the
+buffer from looking at the parameter to the function, it is highly
+recommended to use these functions since the result might not always be
+what you expect.

-In a locale other than the standard @code{"C"} locale, this function
+@comment stdlib.h
+@comment GNU
+@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
+The description of the random number generator represented by the
+information in @var{buffer} is initialized similarly to what the function
+@code{srand48} does.  The state is initialized from the parameter
+@var{seedval} and the parameters for the congruential formula are
+initialized to their default values.

-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.
+If the return value is non-negative the function call succeeded.

-The following @code{errno} error conditions are defined for this
-function:
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun

-@table @code
-@item ERANGE
-An overflow or underflow condition was detected.
-@end table
+@comment stdlib.h
+@comment GNU
+@deftypefun int seed48_r (unsigned short int @var{seed16v}, struct drand48_data *@var{buffer})
+This function is similar to @code{srand48_r} but like @code{seed48} it
+initializes all 48 bits of the state from the parameter @var{seed16v}.
+
+If the return value is non-negative the function call succeeded.  It
+does not return a pointer to the previous state of the random number
+generator like the @code{seed48} function does.  If the user wants to
+preserve the state for a later re-run s/he can copy the whole buffer
+pointed to by @var{buffer}.
+
+This function is a GNU extension and should not be used in portable
+programs.
@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.
+@comment GNU
+@deftypefun int lcong48_r (unsigned short int @var{param}, struct drand48_data *@var{buffer})
+This function initializes all aspects of the random number generator
+described in @var{buffer} with the data in @var{param}.  Here it is
+especially true that the function does more than just copying the
+contents of @var{param} and @var{buffer}.  More work is required and
+therefore it is important to use this function rather than initializing
+the random number generator directly.
+
+If the return value is non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
@end deftypefun

+@node FP Function Optimizations
+@section Is Fast Code or Small Code preferred?
+@cindex Optimization
+
+If an application uses many floating point functions it is often the case
+that the cost of the function calls themselves is not negligible.
+Modern processors can often execute the operations themselves
+very fast, but the function call disrupts the instruction pipeline.
+
+For this reason the GNU C Library provides optimizations for many of the
+frequently-used math functions.  When GNU CC is used and the user
+activates the optimizer, several new inline functions and macros are
+defined.  These new functions and macros have the same names as the
+library functions and so are used instead of the latter.  In the case of
+inline functions the compiler will decide whether it is reasonable to
+use them, and this decision is usually correct.
+
+This means that no calls to the library functions may be necessary, and
+can increase the speed of generated code significantly.  The drawback is
+that code size will increase, and the increase is not always negligible.
+
+There are two kind of inline functions: Those that give the same result
+as the library functions and others that might not set @code{errno} and
+might have a reduced precision and/or argument range in comparison with
+the library functions.  The latter inline functions are only available
+if the flag @code{-ffast-math} is given to GNU CC.
+
+In cases where the inline functions and macros are not wanted the symbol
+@code{__NO_MATH_INLINES} should be defined before any system header is
+included.  This will ensure that only library functions are used.  Of
+course, it can be determined for each file in the project whether
+giving this option is preferable or not.
+
+Not all hardware implements the entire @w{IEEE 754} standard, and even
+if it does there may be a substantial performance penalty for using some
+of its features.  For example, enabling traps on some processors forces
+the FPU to run un-pipelined, which can more than double calculation time.
+@c ***Add explanation of -lieee, -mieee.