(Tools for Compilation): Grammar fixes.
[kopensolaris-gnu/glibc.git] / manual / math.texi
index 7de6d16..7ebcdde 100644 (file)
-@node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
+@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{math.h}.
+@file{math.h}.  The complex-valued functions are defined in
+@file{complex.h}.
 @pindex math.h
-
-All of the functions that operate on floating-point numbers accept
-arguments and return results of type @code{double}.  In the future,
-there may be additional functions that operate on @code{float} and
-@code{long double} values.  For example, @code{cosf} and @code{cosl}
-would be versions of the @code{cos} function that operate on
-@code{float} and @code{long double} arguments, respectively.  In the
-meantime, you should avoid using these names yourself.  @xref{Reserved
-Names}.
+@pindex complex.h
+
+All mathematical functions which take a floating-point argument
+have three variants, one each for @code{double}, @code{float}, and
+@code{long double} arguments.  The @code{double} versions are mostly
+defined in @w{ISO C89}.  The @code{float} and @code{long double}
+versions are from the numeric extensions to C included in @w{ISO C99}.
+
+Which of the three versions of a function should be used depends on the
+situation.  For most calculations, the @code{float} functions are the
+fastest.  On the other hand, the @code{long double} functions have the
+highest precision.  @code{double} is somewhere in between.  It is
+usually wise to pick the narrowest type that can accommodate your data.
+Not all machines have a distinct @code{long double} type; it may be the
+same as @code{double}.
 
 @menu
-* Domain and Range Errors::     Detecting overflow conditions and the like.
-* Trig Functions::              Sine, cosine, and tangent.
-* Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
-* Exponents and Logarithms::    Also includes square root.
-* Hyperbolic Functions::        Hyperbolic sine and friends.
+* Mathematical Constants::      Precise numeric values for often-used
+                                 constants.
+* Trig Functions::              Sine, cosine, tangent, and friends.
+* Inverse Trig Functions::      Arcsine, arccosine, etc.
+* Exponents and Logarithms::    Also pow and sqrt.
+* Hyperbolic Functions::        sinh, cosh, tanh, etc.
+* Special Functions::           Bessel, gamma, erf.
+* Errors in Math Functions::    Known Maximum Errors in Math Functions.
 * Pseudo-Random Numbers::       Functions for generating pseudo-random
                                 numbers.
+* FP Function Optimizations::   Fast code or small code.
 @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 sets
-@code{errno} to @code{EDOM} to indicate a @dfn{domain error}.  On
-machines that support @w{IEEE 754} floating point, functions reporting
-error @code{EDOM} also return a NaN.
-
-Some of these functions are defined mathematically to result in a
-complex value over parts of their domains.  The most familiar example of
-this is taking the square root of a negative number.  The functions in
-this chapter take only real arguments and return only real values;
-therefore, if the value ought to be nonreal, this is treated as a domain
-error.
-
-@cindex range error
-A related problem is that the mathematical result of a function may not
-be representable as a floating point number.  If magnitude of the
-correct result is too large to be represented, the function sets
-@code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
-returns a particular very large value (named by the macro
-@code{HUGE_VAL}) or its negation (@w{@code{- HUGE_VAL}}).
-
-If the magnitude of the result is too small, a value of zero is returned
-instead.  In this case, @code{errno} might or might not be
-set to @code{ERANGE}.
-
-The only completely reliable way to check for domain and range errors is
-to set @code{errno} to @code{0} before you call the mathematical function
-and test @code{errno} afterward.  As a consequence of this use of
-@code{errno}, use of the mathematical functions is not reentrant if you
-check for errors.
-
-@c !!! this isn't always true at the moment....
-None of the mathematical functions ever generates signals as a result of
-domain or range errors.  In particular, this means that you won't see
-@code{SIGFPE} signals generated within these functions.  (@xref{Signal
-Handling}, for more information about signals.)
-
-@comment math.h
-@comment ANSI
-@deftypevr Macro double HUGE_VAL
-An expression representing a particular very large number.  On machines
-that use @w{IEEE 754} floating point format, the value is ``infinity''.
-On other machines, it's typically the largest positive number that can
-be represented.
-
-The value of this macro is used as the return value from various
-mathematical @code{double} returning functions in overflow situations.
-@end deftypevr
-
-@comment math.h
-@comment GNU
-@deftypevr Macro float HUGE_VALf
-This macro is similar to the @code{HUGE_VAL} macro except that it is
-used by functions returning @code{float} values.
-
-This macro is a GNU extension.
-@end deftypevr
-
-@comment math.h
-@comment GNU
-@deftypevr Macro {long double} HUGE_VALl
-This macro is similar to the @code{HUGE_VAL} macro except that it is
-used by functions returning @code{long double} values.  The value is
-only different from @code{HUGE_VAL} if the architecture really supports
-@code{long double} values.
-
-This macro is a GNU extension.
-@end deftypevr
-
-
-@comment
-
-For more information about floating-point representations and limits,
-see @ref{Floating Point Parameters}.  In particular, the macro
-@code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many
-uses other than testing for an error in a mathematical function.
+@node 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
@@ -119,103 +135,235 @@ 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:
 
 @smallexample
-#define PI 3.14159265358979323846264338327
+#define M_PI 3.14159265358979323846264338327
 @end smallexample
 
 @noindent
 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}, where @var{x} is given in
+@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}, where @var{x} is given in
+@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}, where @var{x} is given in
+@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.
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item ERANGE
 Mathematically, the tangent function has singularities at odd multiples
 of pi/2.  If the argument @var{x} is too close to one of these
-singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
-either positive or negative @code{HUGE_VAL}.
-@end table
+singularities, @code{tan} will signal overflow.
+@end deftypefun
+
+In many applications where @code{sin} and @code{cos} are used, the sine
+and cosine of the same angle are needed at the same time.  It is more
+efficient to compute them simultaneously, so the library provides a
+function to do that.
+
+@comment math.h
+@comment GNU
+@deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
+@comment math.h
+@comment GNU
+@deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
+@comment math.h
+@comment GNU
+@deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
+These functions return the sine of @var{x} in @code{*@var{sinx}} and the
+cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
+radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
+the range of @code{-1} to @code{1}.
+
+This function is a GNU extension.  Portable programs should be prepared
+to cope with its absence.
+@end deftypefun
+
+@cindex complex trigonometric functions
+
+@w{ISO C99} defines variants of the trig functions which work on
+complex numbers.  The GNU C library provides these functions, but they
+are only useful if your compiler supports the new complex types defined
+by the standard.
+@c XXX Change this when gcc is fixed. -zw
+(As of this writing GCC supports complex numbers, but there are bugs in
+the implementation.)
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csin (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} csinf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} csinl (complex long double @var{z})
+These functions return the complex sine of @var{z}.
+The mathematical definition of the complex sine is
+
+@ifnottex
+@math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
+@end ifnottex
+@tex
+$$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
+@end tex
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} ccos (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} ccosf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} ccosl (complex long double @var{z})
+These functions return the complex cosine of @var{z}.
+The mathematical definition of the complex cosine is
+
+@ifnottex
+@math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
+@end ifnottex
+@tex
+$$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
+@end tex
+@end deftypefun
+
+@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 Trig Functions
 @section Inverse Trigonometric Functions
-@cindex inverse trigonmetric functions
+@cindex inverse trigonometric functions
 
 These are the usual arc sine, arc cosine and arc tangent functions,
-which are the inverses of the sine, cosine and 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}---that is, the value whose
+@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).
 
-@code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
-out of range.  The arc sine function is defined mathematically only
-over the domain @code{-1} to @code{1}.
+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}---that is, the value
+@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).
 
-@code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
-out of range.  The arc cosine function is defined mathematically only
-over the domain @code{-1} to @code{1}.
+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 computes the arc tangent of @var{x}---that is, the value
+@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).
+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 @code{-pi} to @code{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
@@ -224,9 +372,57 @@ converting Cartesian coordinates to polar coordinates.  (To compute the
 radial coordinate, use @code{hypot}; see @ref{Exponents and
 Logarithms}.)
 
-The function @code{atan2} sets @code{errno} to @code{EDOM} if both
-@var{x} and @var{y} are zero; the return value is not defined in this
-case.
+@c This is experimentally true.  Should it be so? -zw
+If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
+@end deftypefun
+
+@cindex inverse complex trigonometric functions
+@w{ISO C99} defines complex versions of the inverse trig functions.
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} casin (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} casinf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} casinl (complex long double @var{z})
+These functions compute the complex arc sine of @var{z}---that is, the
+value whose sine is @var{z}.  The value returned is in radians.
+
+Unlike the real-valued functions, @code{casin} is defined for all
+values of @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cacos (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cacosf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cacosl (complex long double @var{z})
+These functions compute the complex arc cosine of @var{z}---that is, the
+value whose cosine is @var{z}.  The value returned is in radians.
+
+Unlike the real-valued functions, @code{cacos} is defined for all
+values of @var{z}.
+@end deftypefun
+
+
+@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
 
 
@@ -237,107 +433,378 @@ case.
 @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}.
+
+If the magnitude of the result is too large to be representable,
+@code{exp} signals overflow.
+@end deftypefun
 
-The function fails, and sets @code{errno} to @code{ERANGE}, if the
-magnitude of the result is too large to be representable.
+@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
+@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))}.
+
+These functions are GNU extensions.  The name @code{exp10} is
+preferred, since it is analogous to @code{exp} and @code{exp2}.
+@end deftypefun
+
+
+@comment math.h
+@comment ISO
 @deftypefun double log (double @var{x})
-This function returns the natural logarithm of @var{x}.  @code{exp (log
+@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.
 
-The following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item EDOM
-The argument @var{x} is negative.  The log function is defined
-mathematically to return a real result only on positive arguments.
-
-@item ERANGE
-The argument is zero.  The log of zero is not defined.
-@end table
+If @var{x} is negative, @code{log} signals a domain error.  If @var{x}
+is zero, it returns negative infinity; if @var{x} is too close to zero,
+it may signal overflow.
 @end deftypefun
 
 @comment math.h
-@comment ANSI
+@comment ISO
 @deftypefun double log10 (double @var{x})
-This function returns the base-10 logarithm of @var{x}.  Except for the
-different base, it is similar to the @code{log} function.  In fact,
+@comment math.h
+@comment ISO
+@deftypefunx float log10f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} log10l (long double @var{x})
+These functions return the base-10 logarithm of @var{x}.
 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
+
 @end deftypefun
 
 @comment math.h
-@comment ANSI
-@deftypefun double pow (double @var{base}, double @var{power})
-This is a general exponentiation function, returning @var{base} raised
-to @var{power}.
+@comment ISO
+@deftypefun double log2 (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float log2f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} log2l (long double @var{x})
+These functions return the base-2 logarithm of @var{x}.
+@code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
+@end deftypefun
 
-@need 250
-The following @code{errno} error conditions are defined for this function:
+@comment math.h
+@comment ISO
+@deftypefun double logb (double @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx float logbf (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} logbl (long double @var{x})
+These functions extract the exponent of @var{x} and return it as a
+floating-point value.  If @code{FLT_RADIX} is two, @code{logb} is equal
+to @code{floor (log2 (x))}, except it's probably faster.
+
+If @var{x} is de-normalized, @code{logb} returns the exponent @var{x}
+would have if it were normalized.  If @var{x} is infinity (positive or
+negative), @code{logb} returns @math{@infinity{}}.  If @var{x} is zero,
+@code{logb} returns @math{@infinity{}}.  It does not signal.
+@end deftypefun
 
-@table @code
-@item EDOM
-The argument @var{base} is negative and @var{power} is not an integral
-value.  Mathematically, the result would be a complex number in this case.
+@comment math.h
+@comment ISO
+@deftypefun 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
 
-@item ERANGE
-An underflow or overflow condition was detected in the result.
-@end table
+@noindent
+Since integers cannot represent infinity and NaN, @code{ilogb} instead
+returns an integer that can't be the exponent of a normal floating-point
+number.  @file{math.h} defines constants so you can check for this.
+
+@comment math.h
+@comment ISO
+@deftypevr Macro int FP_ILOGB0
+@code{ilogb} returns this value if its argument is @code{0}.  The
+numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
+
+This macro is defined in @w{ISO C99}.
+@end deftypevr
+
+@comment math.h
+@comment ISO
+@deftypevr Macro int FP_ILOGBNAN
+@code{ilogb} returns this value if its argument is @code{NaN}.  The
+numeric value is either @code{INT_MIN} or @code{INT_MAX}.
+
+This macro is defined in @w{ISO C99}.
+@end deftypevr
+
+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
+
+@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}.
+@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}.
 
-The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
-@var{x} is negative.  Mathematically, the square root would be a complex
-number.
+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 BSD
 @deftypefun double cbrt (double @var{x})
-This function returns the cube root of @var{x}.  This function cannot
+@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 BSD
+@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.)  See also the function
-@code{cabs} in @ref{Absolute Value}.
+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 BSD
+@comment ISO
 @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
-near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
+@comment math.h
+@comment ISO
+@deftypefunx float expm1f (float @var{x})
+@comment math.h
+@comment ISO
+@deftypefunx {long double} expm1l (long double @var{x})
+These functions return a value equivalent to @code{exp (@var{x}) - 1}.
+They are computed in a way that is accurate even if @var{x} is
+near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing
 to subtraction of two numbers that are nearly equal.
 @end deftypefun
 
 @comment math.h
-@comment BSD
+@comment ISO
 @deftypefun double log1p (double @var{x})
-This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
-It is computed in a way that is accurate even if the value of @var{x} is
+@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 complex.h
+@comment ISO
+@deftypefun {complex double} clog (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} clogf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} clogl (complex long double @var{z})
+These functions return the natural logarithm of @var{z}.
+Mathematically, this corresponds to the value
+
+@ifnottex
+@math{log (z) = log (cabs (z)) + I * carg (z)}
+@end ifnottex
+@tex
+$$\log(z) = \log |z| + i \arg z$$
+@end tex
+
+@noindent
+@code{clog} has a pole at 0, and will signal overflow if @var{z} equals
+or is very close to 0.  It is well-defined for all other values of
+@var{z}.
+@end deftypefun
+
+
+@comment complex.h
+@comment GNU
+@deftypefun {complex double} clog10 (complex double @var{z})
+@comment complex.h
+@comment GNU
+@deftypefunx {complex float} clog10f (complex float @var{z})
+@comment complex.h
+@comment GNU
+@deftypefunx {complex long double} clog10l (complex long double @var{z})
+These functions return the base 10 logarithm of the complex value
+@var{z}. Mathematically, this corresponds to the value
+
+@ifnottex
+@math{log (z) = log10 (cabs (z)) + I * carg (z)}
+@end ifnottex
+@tex
+$$\log_{10}(z) = \log_{10}|z| + i \arg z$$
+@end tex
+
+These functions are GNU extensions.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} csqrt (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} csqrtf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} csqrtl (complex long double @var{z})
+These functions return the complex square root of the argument @var{z}.  Unlike
+the real-valued functions, they are defined for all values of @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
+These functions return @var{base} raised to the power of
+@var{power}.  This is equivalent to @w{@code{cexp (y * clog (x))}}
+@end deftypefun
+
 @node Hyperbolic Functions
 @section Hyperbolic Functions
 @cindex hyperbolic functions
@@ -346,56 +813,440 @@ 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}, defined
-mathematically as @w{@code{exp (@var{x}) - exp (-@var{x}) / 2}}.  The
-function fails, and sets @code{errno} to @code{ERANGE}, if the value of
-@var{x} is too large; that is, if overflow occurs.
+@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},
-defined mathematically as @w{@code{exp (@var{x}) + exp (-@var{x}) / 2}}.
-The function fails, and sets @code{errno} to @code{ERANGE}, if the value
-of @var{x} is too large; that is, if overflow occurs.
+@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}, whose
-mathematical definition is @w{@code{sinh (@var{x}) / cosh (@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 BSD
+@comment ISO
 @deftypefun double asinh (double @var{x})
-This function returns the inverse hyperbolic sine of @var{x}---the
+@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 BSD
+@comment ISO
 @deftypefun double acosh (double @var{x})
-This function returns the inverse hyperbolic cosine of @var{x}---the
+@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} returns @code{HUGE_VAL}.
+@code{1}, @code{acosh} signals a domain error.
 @end deftypefun
 
 @comment math.h
-@comment BSD
+@comment ISO
 @deftypefun double atanh (double @var{x})
-This function returns the inverse hyperbolic tangent of @var{x}---the
+@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 or equal to @code{1}, @code{atanh} returns
-@code{HUGE_VAL}.
+@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
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} cacosh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} cacoshf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} cacoshl (complex long double @var{z})
+These functions return the inverse complex hyperbolic cosine of
+@var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
+the real-valued functions, there are no restrictions on the value of @var{z}.
+@end deftypefun
+
+@comment complex.h
+@comment ISO
+@deftypefun {complex double} catanh (complex double @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex float} catanhf (complex float @var{z})
+@comment complex.h
+@comment ISO
+@deftypefunx {complex long double} catanhl (complex long double @var{z})
+These functions return the inverse complex hyperbolic tangent of
+@var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
+the real-valued functions, there are no restrictions on the value of
+@var{z}.
+@end deftypefun
+
+@node Special Functions
+@section Special Functions
+@cindex special functions
+@cindex Bessel functions
+@cindex gamma function
+
+These are some more exotic mathematical functions which are sometimes
+useful.  Currently they only have real-valued versions.
+
+@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 SVID
+@deftypefun double erfc (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float erfcf (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} erfcl (long double @var{x})
+@code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
+fashion that avoids round-off error when @var{x} is large.
 @end deftypefun
 
+@comment math.h
+@comment SVID
+@deftypefun double lgamma (double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float lgammaf (float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} lgammal (long double @var{x})
+@code{lgamma} returns the natural logarithm of the absolute value of
+the gamma function of @var{x}.  The gamma function is defined as
+@tex
+$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
+@end smallexample
+@end ifnottex
+
+@vindex signgam
+The sign of the gamma function is stored in the global variable
+@var{signgam}, which is declared in @file{math.h}.  It is @code{1} if
+the intermediate result was positive or zero, or @code{-1} if it was
+negative.
+
+To compute the real gamma function you can use the @code{tgamma}
+function or you can compute the values as follows:
+@smallexample
+lgam = lgamma(x);
+gam  = signgam*exp(lgam);
+@end smallexample
+
+The gamma function has singularities at the non-positive integers.
+@code{lgamma} will raise the zero divide exception if evaluated at a
+singularity.
+@end deftypefun
+
+@comment math.h
+@comment 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
+
+@comment math.h
+@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 XPG, ISO
+@deftypefun double tgamma (double @var{x})
+@comment math.h
+@comment XPG, ISO
+@deftypefunx float tgammaf (float @var{x})
+@comment math.h
+@comment XPG, ISO
+@deftypefunx {long double} tgammal (long double @var{x})
+@code{tgamma} applies the gamma function to @var{x}.  The gamma
+function is defined as
+@tex
+$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
+@end tex
+@ifnottex
+@smallexample
+gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
+@end smallexample
+@end ifnottex
+
+This function was introduced in @w{ISO C99}.
+@end deftypefun
+
+@comment math.h
+@comment 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 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 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 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
+
+@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
+
+@comment math.h
+@comment SVID
+@deftypefun double yn (int n, double @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx float ynf (int n, float @var{x})
+@comment math.h
+@comment SVID
+@deftypefunx {long double} ynl (int n, long double @var{x})
+@code{yn} returns the Bessel function of the second kind of order @var{n} of
+@var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
+is negative, @code{yn} signals a domain error; if it is zero,
+@code{yn} signals overflow and returns @math{-@infinity}.
+@end deftypefun
+
+@node Errors in Math Functions
+@section Known Maximum Errors in Math Functions
+@cindex math errors
+@cindex ulps
+
+This section lists the known errors of the functions in the math
+library.  Errors are measured in ``units of the last place''.  This is a
+measure for the relative error.  For a number @math{z} with the
+representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE
+floating-point numbers with base 2) the ULP is represented by
+
+@tex
+$${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$
+@end tex
+@ifnottex
+@smallexample
+|d.d...d - (z / 2^e)| / 2^(p - 1)
+@end smallexample
+@end ifnottex
+
+@noindent
+where @math{p} is the number of bits in the mantissa of the
+floating-point number representation.  Ideally the error for all
+functions is always less than 0.5ulps.  Using rounding bits this is also
+possible and normally implemented for the basic operations.  To achieve
+the same for the complex math functions requires a lot more work and
+this has not yet been done.
+
+Therefore many of the functions in the math library have errors.  The
+table lists the maximum error for each function which is exposed by one
+of the existing tests in the test suite.  The table tries to cover as much
+as possible and list the actual maximum error (or at least a ballpark
+figure) but this is often not achieved due to the large search space.
+
+The table lists the ULP values for different architectures.  Different
+architectures have different results since their hardware support for
+floating-point operations varies and also the existing hardware support
+is different.
+
+@page
+@c This multitable does not fit on a single page
+@include libm-err.texi
+
 @node Pseudo-Random Numbers
 @section Pseudo-Random Numbers
 @cindex random numbers
@@ -404,74 +1255,101 @@ value whose hyperbolic tangent is @var{x}.  If the absolute value of
 
 This section describes the GNU facilities for generating a series of
 pseudo-random numbers.  The numbers generated are not truly random;
-typically, they form a sequence that repeats periodically, with a
-period so large that you can ignore it for ordinary purposes.  The
-random number generator works by remembering at all times a @dfn{seed}
-value which it uses to compute the next random number and also to
-compute a new seed.
+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 truly random
-numbers, not just pseudo-random, specify a seed based on the current
-time.
+you want the program to behave unpredictably.  If you want a different
+pseudo-random series each time your program runs, you must specify a
+different seed each time.  For ordinary purposes, basing the seed on the
+current time works well.
 
-You can get repeatable sequences of numbers on a particular machine type
+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 ANSI C random number functions
-plus another set derived from BSD.  We recommend you use the standard
-ones, @code{rand} and @code{srand}.
+The GNU library supports the standard @w{ISO C} random number functions
+plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
+functions provide identical, somewhat limited functionality.  If only a
+small number of random bits are required, we recommend you use the
+@w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
+provide a more flexible interface, which allows better random number
+generator algorithms, provides more random bits (up to 48) per call, and
+can provide random floating-point numbers.  These functions are required
+by the XPG standard and therefore will be present in all modern Unix
+systems.
 
 @menu
-* ANSI Random::      @code{rand} and friends.
-* BSD Random::       @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 Random
-@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.
+the @w{ISO C} standard.
 
 To use these facilities, you should include the header file
 @file{stdlib.h} in your program.
 @pindex stdlib.h
 
 @comment stdlib.h
-@comment ANSI
+@comment ISO
 @deftypevr Macro int RAND_MAX
-The value of this macro is an integer constant expression that
-represents the maximum possible value returned by the @code{rand}
-function.  In the GNU library, it is @code{037777777}, which is the
-largest signed integer representable in 32 bits.  In other libraries, it
-may be as low as @code{32767}.
+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
-@deftypefun int rand ()
+@comment ISO
+@deftypefun int rand (void)
 The @code{rand} function returns the next pseudo-random number in the
-series.  The value is in the range from @code{0} to @code{RAND_MAX}.
+series.  The value ranges from @code{0} to @code{RAND_MAX}.
 @end deftypefun
 
 @comment stdlib.h
-@comment ANSI
+@comment ISO
 @deftypefun void srand (unsigned int @var{seed})
 This function establishes @var{seed} as the seed for a new series of
 pseudo-random numbers.  If you call @code{rand} before a seed has been
 established with @code{srand}, it uses the value @code{1} as a default
 seed.
 
-To produce truly random numbers (not just pseudo-random), do @code{srand
-(time (0))}.
+To produce a different pseudo-random 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 multi-threaded 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
 @subsection BSD Random Number Functions
 
@@ -484,21 +1362,27 @@ The prototypes for these functions are in @file{stdlib.h}.
 
 @comment stdlib.h
 @comment BSD
-@deftypefun {long int} random ()
+@deftypefun {long int} random (void)
 This function returns the next pseudo-random number in the sequence.
-The range of values returned is from @code{0} to @code{RAND_MAX}.
+The value returned ranges from @code{0} to @code{RAND_MAX}.
+
+@strong{Note:} Temporarily this function was defined to return a
+@code{int32_t} value to indicate that the return value always contains
+32 bits even if @code{long int} is wider.  The standard demands it
+differently.  Users must always be aware of the 32-bit limitation,
+though.
 @end deftypefun
 
 @comment stdlib.h
 @comment BSD
 @deftypefun void srandom (unsigned int @var{seed})
-The @code{srandom} function sets the seed for the current random number
-state based on the integer @var{seed}.  If you supply a @var{seed} value
+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.
 
-To produce truly random numbers (not just pseudo-random), do
-@code{srandom (time (0))}.
+To produce a different set of pseudo-random numbers each time your
+program runs, do @code{srandom (time (0))}.
 @end deftypefun
 
 @comment stdlib.h
@@ -506,9 +1390,9 @@ To produce truly random numbers (not just pseudo-random), do
 @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 argument @var{state} is an array of @var{size}
-bytes, used to hold the state information.  The size must be at least 8
-bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
-the @var{state} array, the better.
+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
@@ -523,6 +1407,449 @@ information @var{state}.  The argument must have been the result of
 a previous call to @var{initstate} or @var{setstate}.
 
 The return value is the previous value of the state information array.
-You can use thise value later as an argument to @code{setstate} to
+You can use this value later as an argument to @code{setstate} to
 restore that state.
+
+If the function fails the return value is @code{NULL}.
+@end deftypefun
+
+The four functions described so far in this section all work on a state
+which is shared by all threads.  The state is not directly accessible to
+the user and can only be modified by these functions.  This makes it
+hard to deal with situations where each thread should have its own
+pseudo-random number generator.
+
+The GNU C library contains four additional functions which contain the
+state as an explicit parameter and therefore make it possible to handle
+thread-local PRNGs.  Beside this there are no difference.  In fact, the
+four functions already discussed are implemented internally using the
+following interfaces.
+
+The @file{stdlib.h} header contains a definition of the following type:
+
+@comment stdlib.h
+@comment GNU
+@deftp {Data Type} {struct random_data}
+
+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
+
+The functions modifying the state follow exactly the already described
+functions.
+
+@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 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 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
+
+@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
+
+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.
+
+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.
+
+All functions have in common that they use the same congruential
+formula with the same constants.  The formula is
+
+@smallexample
+Y = (a * X + c) mod m
+@end smallexample
+
+@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 48-bit array.
+
+The prototypes for these functions are in @file{stdlib.h}.
+@pindex stdlib.h
+
+
+@comment stdlib.h
+@comment SVID
+@deftypefun double drand48 (void)
+This function returns a @code{double} value in the range of @code{0.0}
+to @code{1.0} (exclusive).  The random bits are determined by the global
+state of the random number generator in the C library.
+
+Since the @code{double} type according to @w{IEEE 754} has a 52-bit
+mantissa this means 4 bits are not initialized by the random number
+generator.  These are (of course) chosen to be the least significant
+bits and they are initialized to @code{0}.
+@end deftypefun
+
+@comment stdlib.h
+@comment 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 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
+
+@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
+
+@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 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 SVID
+@deftypefun void srand48 (long int @var{seedval})
+The @code{srand48} function sets the most significant 32 bits of the
+internal state of the random number generator to the least
+significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
+are initialized to the value @code{0x330E}.  Even if the @code{long
+int} type contains more than 32 bits only the lower 32 bits are used.
+
+Owing to this limitation, initialization of the state of this
+function is not very useful.  But it makes it easy to use a construct
+like @code{srand48 (time (0))}.
+
+A side-effect of this function is that the values @code{a} and @code{c}
+from the internal state, which are used in the congruential formula,
+are reset to the default values given above.  This is of importance once
+the user has called the @code{lcong48} function (see below).
+@end deftypefun
+
+@comment stdlib.h
+@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 mid-order
+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 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 16-bit value
+@code{c}.
+@end deftypefun
+
+All the above functions have in common that they use the global
+parameters for the congruential formula.  In multi-threaded programs it
+might sometimes be useful to have different parameters in different
+threads.  For this reason all the above functions have a counterpart
+which works on a description of the random number generator in the
+user-supplied buffer instead of the global state.
+
+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.
+
+The user-supplied buffer must be of type @code{struct drand48_data}.
+This type should be regarded as opaque and not manipulated directly.
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is equivalent to the @code{drand48} function with the
+difference that it does not modify the global random number generator
+parameters but instead the parameters in the buffer supplied through the
+pointer @var{buffer}.  The random number is returned in the variable
+pointed to by @var{result}.
+
+The return value of the function indicates whether the call succeeded.
+If the value is less than @code{0} an error occurred and @var{errno} is
+set to indicate the problem.
+
+This function is a GNU extension and should not be used in portable
+programs.
 @end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@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 non-negative if the call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is similar to @code{lrand48}, but in addition it takes a
+pointer to a buffer describing the state of the random number generator
+just like @code{drand48}.
+
+If the return value of the function is non-negative the variable pointed
+to by @var{result} contains the result.  Otherwise an error occurred.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@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 non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
+This function is similar to @code{mrand48} but like the other reentrant
+functions it uses the random number generator described by the value in
+the buffer pointed to by @var{buffer}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment GNU
+@deftypefun int 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}.
+
+If the return value is non-negative the variable pointed to by
+@var{result} contains the result.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+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
+
+@smallexample
+memset (buffer, '\0', sizeof (struct drand48_data));
+@end smallexample
+
+@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.
+
+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.
+
+@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 return value is non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@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 non-negative the function call succeeded.  It
+does not return a pointer to the previous state of the random number
+generator like the @code{seed48} function does.  If the user wants to
+preserve the state for a later re-run s/he can copy the whole buffer
+pointed to by @var{buffer}.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@comment stdlib.h
+@comment 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 non-negative the function call succeeded.
+
+This function is a GNU extension and should not be used in portable
+programs.
+@end deftypefun
+
+@node FP Function Optimizations
+@section Is Fast Code or Small Code preferred?
+@cindex Optimization
+
+If an application uses many floating point functions it is often the case
+that the cost of the function calls themselves is not negligible.
+Modern processors can often execute the operations themselves
+very fast, but the function call disrupts the instruction pipeline.
+
+For this reason the GNU C Library provides optimizations for many of the
+frequently-used math functions.  When GNU CC is used and the user
+activates the optimizer, several new inline functions and macros are
+defined.  These new functions and macros have the same names as the
+library functions and so are used instead of the latter.  In the case of
+inline functions the compiler will decide whether it is reasonable to
+use them, and this decision is usually correct.
+
+This means that no calls to the library functions may be necessary, and
+can increase the speed of generated code significantly.  The drawback is
+that code size will increase, and the increase is not always negligible.
+
+There are two kind of inline functions: Those that give the same result
+as the library functions and others that might not set @code{errno} and
+might have a reduced precision and/or argument range in comparison with
+the library functions.  The latter inline functions are only available
+if the flag @code{-ffast-math} is given to GNU CC.
+
+In cases where the inline functions and macros are not wanted the symbol
+@code{__NO_MATH_INLINES} should be defined before any system header is
+included.  This will ensure that only library functions are used.  Of
+course, it can be determined for each file in the project whether
+giving this option is preferable or not.
+
+Not all hardware implements the entire @w{IEEE 754} standard, and even
+if it does there may be a substantial performance penalty for using some
+of its features.  For example, enabling traps on some processors forces
+the FPU to run un-pipelined, which can more than double calculation time.
+@c ***Add explanation of -lieee, -mieee.