XGitUrl: http://git.csclub.uwaterloo.ca/?p=kopensolarisgnu%2Fglibc.git;a=blobdiff_plain;f=manual%2Fmath.texi;h=7ebcddee3f468dd3c29d9d6f917bfb5de3640386;hp=cadce992bb18f603a890b5800c716d121e83d144;hb=eeaf69262a1f3fc21938ce2d2a58a70459457f83;hpb=9e80db06f16d09db163d9589b166d9569861ffbb
diff git a/manual/math.texi b/manual/math.texi
index cadce992bb..7ebcddee3f 100644
 a/manual/math.texi
+++ b/manual/math.texi
@@ 1,639 +1,1402 @@
@node Mathematics
@chapter Mathematics  @file{}
@pindex
+@c We need some definitions here.
+@ifclear mult
+@ifhtml
+@set mult ·
+@set infty ∞
+@set pie π
+@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{}.

@strong{Incomplete:} This chapter doesn't have any examples.
+mathematical computations, such as trigonometric functions. Most of
+these functions have prototypes declared in the header file
+@file{math.h}. The complexvalued functions are defined in
+@file{complex.h}.
+@pindex math.h
+@pindex complex.h
+
+All mathematical functions which take a floatingpoint 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}.
@menu
* Domain and Range Errors:: How overflow conditions and the like
 are reported.
* Trigonometric Functions:: Sine, cosine, and tangent.
* Inverse Trigonometric Functions:: Arc sine, arc cosine, and arc tangent.
* Exponentiation and Logarithms:: Also includes square root.
* Hyperbolic Functions:: Hyperbolic sine and friends.
* Normalization Functions:: Hacks for radix2 representations.
* Rounding and Remainder Functions:: Determinining the integer and
 fractional parts of a float.
* PseudoRandom Numbers:: Functions for generating pseudorandom
 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 oftenused
+ 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.
+* PseudoRandom Numbers:: Functions for generating pseudorandom
+ numbers.
+* FP Function Optimizations:: Fast code or small code.
@end menu
@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 floatingpoint 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
@defvr Macro HUGE_VAL
This macro expands into a (possibly nonconstant) expression of type
@code{double} representing a very large positive number. This is
typically either the largest representable floatingpoint number, or a
value indicating infinity if the floatingpoint representation has one.
(The IEEE floatingpoint 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 defvr

For more information about floatingpoint representations and limits,
@xref{FloatingPoint 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

@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
+radians.
+
+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
The following @code{errno} error conditions are defined for this function:
+@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
@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
+@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
+@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
+
+@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 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 xaxis. 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
The following @code{errno} error conditions are defined for this function:
+@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 realvalued functions, @code{casin} is defined for all
+values of @var{z}.
+@end deftypefun
@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} 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 realvalued functions, @code{cacos} is defined for all
+values of @var{z}.
@end deftypefun
@node Exponentiation and Logarithms
+@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 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 noncomplex
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 base10 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 base10 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 base2 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
+floatingpoint 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 denormalized, @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
The following @code{errno} error conditions are defined for this function:
+@noindent
+Since integers cannot represent infinity and NaN, @code{ilogb} instead
+returns an integer that can't be the exponent of a normal floatingpoint
+number. @file{math.h} defines constants so you can check for this.
@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
+@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
+
+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
@item ERANGE
An underflow or overflow condition was detected in the result.
@end table
+@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}.
+
+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 zeroa 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 welldefined 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 realvalued 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

The functions described in this section are primarily provided as a way
to efficiently perform certain lowlevel manipulations on floating point
numbers that are represented internally using a binary radix;
@pxref{FloatingPoint 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 realvalued 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 realvalued 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
floatingpoint 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 realvalued 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 floatingpoint
number @var{value} by 2 raised to the power @var{exponent}. (It can
be used to reassemble floatingpoint 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 roundoff 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^{x1} e^{t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x1) 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 nonpositive 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 base2 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

The functions listed here perform operations such as rounding,
truncation, and remainder computation.

You can also convert floatingpoint 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^{x1} e^{t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x1) 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{FloatingPoint Parameters}, for information
about the @code{FLT_ROUNDS} macro.
+@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 builtin @samp{%} operator isn't defined on
floatingpoint 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
+floatingpoint numbers with base 2) the ULP is represented by
+
+@tex
+$${d.d\dots d  (z/2^e)}\over {2^{p1}}$$
+@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
+floatingpoint 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
+floatingpoint operations varies and also the existing hardware support
+is different.
+
+@page
+@c This multitable does not fit on a single page
+@include libmerr.texi
@node PseudoRandom Numbers
@section PseudoRandom Numbers

This section describes the GNU facilities for generating a series of
pseudorandom 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 pseudorandom 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
implementationdependent or implementationdependent.

+This section describes the GNU facilities for generating a series of
+pseudorandom 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
+pseudorandom 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 floatingpoint numbers. These functions are required
+by the XPG standard and therefore will be present in all modern Unix
+systems.
@menu
* 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.
@end menu
@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{} in your program.
+@file{stdlib.h} in your program.
+@pindex stdlib.h
@comment stdlib.h
@comment ANSI
@defvr Macro RAND_MAX
The value of this macro is an integer constant expression that
represents the maximum possible value returned by the @code{rand}
function. It is guaranteed to be at least @code{32767}.
@end defvr
+@comment ISO
+@deftypevr Macro int RAND_MAX
+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 pseudorandom 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
pseudorandom 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}.
+pseudorandom 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 pseudorandom series each time your program is
+run, do @code{srand (time (0))}.
+@end deftypefun
+
+POSIX.1 extended the C standard functions to support reproducible random
+numbers in multithreaded programs. However, the extension is badly
+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 Number Functions
+
+@node BSD Random
@subsection BSD Random Number Functions
This section describes a set of random number generation functions
that are derived from BSD Unix. The @code{random} function can generate
better random numbers than @code{rand}, because it maintains more bits
of internal state.
+This section describes a set of random number generation functions that
+are derived from BSD. There is no advantage to using these functions
+with the GNU C library; we support them for BSD compatibility only.
The prototypes for these functions are in @file{}.
+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 pseudorandom 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 32bit 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 pseudorandom 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
@@ 641,328 +1404,452 @@ 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
+pseudorandom 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
+threadlocal 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
+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{} in your program.
+The functions modifying the state follow exactly the already described
+functions.
These functions are not necessarily equivalent to the division performed
by the builtin @code{/} and @code{%} operators. While the builtin
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 such that @code{quot*@var{denominator} + 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
+
+@noindent
+but they can also be changed by the user. @code{m} is of course 2^48
+since the state consists of a 48bit array.
@node Absolute Value
@section Absolute Value
+The prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
These functions are provided for obtaining the absolute value of
integer values. Prototypes for @code{abs} and @code{abs} are declared
in @file{}; @code{fabs} is declared in @file{}.
@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 52bit
+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}[3])
+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 floatingpoint 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 Parsing of Numbers
@section Parsing of Numbers
@cindex parsing of numbers
@cindex string conversion
@cindex number syntax

This section describes functions for ``reading'' integer and
floatingpoint numbers from a string. In many cases, it is more
appropriate to use @code{sscanf} or one of the related functions;
@pxref{Formatted Input}. The syntax recognized by the formatted input
functions for the numeric conversions is exactly the same as the syntax
recognized by the functions described in this section.

These functions are declared in @file{}.

@menu
* Parsing of Integers:: Functions for conversion of integer values.
* Parsing of Floats:: Functions for conversion of floatingpoint
 values.
@end menu
+@comment stdlib.h
+@comment SVID
+@deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
+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
@node Parsing of Integers
@subsection Parsing of Integers
@cindex parsing of integers
+@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 stdlib.h
@comment ANSI
@deftypefun {long int} strtol (const char *@var{string}, char **@var{tailptr}, int @var{base})
The @code{strtol} (``stringtolong'') function converts the initial
part of @var{string} to a signed integer, which is returned as a value
of type @code{long int}.

This function attempts to decompose @var{string} as follows:

@itemize @bullet
@item
A (possibly empty) sequence of whitespace characters, as determined by
the @code{isspace} function (@pxref{Classification of Characters}).
These are discarded.

@item
An optional plus or minus sign (@samp{+} or @samp{}).

@item
A nonempty sequence of digits in the radix specified by @var{base}. If
@var{base} is zero, decimal radix is assumed unless the series of digits
begins with @samp{0} (specifying octal radix), or @samp{0x} or @samp{0X}
(specifying hexadecimal radix); in other words, the same syntax that is
used for integer constants in the C language is recognized. Otherwise
@var{base} must have a value between @code{2} and @code{35}. If
@var{base} is @code{16}, the digits may optionally be preceeded by
@samp{0x} or @samp{0X}.

@item
Any remaining characters in the string. If @var{tailptr} is not a null
pointer, a pointer to this tail of the string is stored in the object
it points to.
@end itemize

If the string is empty, contains only whitespace, or does not contain an
initial substring that has the expected syntax for an integer in the
specified @var{base}, no conversion is performed. In this case,
@code{strtol} returns a value of zero and the value returned in
@var{tailptr} is the value of @var{string}.

In a locale other than the standard @code{"C"} locale, this function
may recognize additional implementationdependent syntax.

If the string has valid syntax for an integer but the value is not
representable because of overflow, @code{strtol} returns either
@code{LONG_MAX} or @code{LONG_MIN} (@pxref{Integer Representation
Limits}), as appropriate for the sign of the value.

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

@table @code
@item ERANGE
An overflow condition was detected.
@end table
+@comment SVID
+@deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
+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
+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 ANSI
@deftypefun {unsigned long int} strtoul (const char *@var{string}, char **@var{tailptr}, int @var{base})
The @code{strtoul} (``stringtounsignedlong'') 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 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 sideeffect 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
@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 SVID
+@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
+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}[1]} initialize the midorder
+16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
+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
+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.
+
@comment stdlib.h
@comment ANSI
@deftypefun int atoi (const char *@var{string})
This function is similar to the @code{atol} function, except that
returns its value as an @code{int} rather than @code{long int}. The
@code{atoi} function is also considered obsolete; use @code{strtol}
instead.
+@comment SVID
+@deftypefun void lcong48 (unsigned short int @var{param}[7])
+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}[0]} to @code{@var{param}[2]}
+determine the initial state, the least significant 16 bits of
+@code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
+constant @code{a} and @code{@var{param}[6]} determines the 16bit value
+@code{c}.
@end deftypefun
@node Predicates on Floats
@subsection Predicates on Floats
+All the above functions have in common that they use the global
+parameters for the congruential formula. In multithreaded 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
+usersupplied buffer instead of the global state.
This section describes some miscellaneous test functions on doubles.
Prototypes for these functions appear in @file{}.
+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.
@comment math.h
+The usersupplied buffer must be of type @code{struct drand48_data}.
+This type should be regarded as opaque and not manipulated directly.
+
+@comment stdlib.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.
+@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 math.h
+@comment stdlib.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.
+@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], 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 nonnegative if the call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
@end deftypefun
@comment math.h
+@comment stdlib.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.
+@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 nonnegative 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 math.h
+@comment stdlib.h
@comment GNU
@deftypefun double infnan (int @var{error})
@strong{Incomplete:} I don't understand what this function does.
+@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], 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 nonnegative 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}.
+If the return value is nonnegative the variable pointed to by
+@var{result} contains the result.
@strong{Portability Note:} The functions listed in this section are GNU
extensions.

@node Parsing of Floats
@subsection Parsing of Floats
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
@comment stdlib.h
@comment ANSI
@deftypefun double strtod (const char *@var{string}, char **@var{tailptr})
The @code{strtod} (``stringtodouble'') function converts the initial
part of @var{string} to a floatingpoint number, which is returned as a
value of type @code{double}.

This function attempts to decompose @var{string} as follows:
+@comment GNU
+@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], 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 nonnegative 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 decimalpoint
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 floatingpoint
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
may recognize additional implementationdependent syntax.
+@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 floatingpoint 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 nonnegative 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}[3], 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 nonnegative 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 rerun 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}[7], 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 nonnegative 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
+frequentlyused 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{ffastmath} 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 unpipelined, which can more than double calculation time.
+@c ***Add explanation of lieee, mieee.