This is Info file libc.info, produced by Makeinfo version 1.68 from the
input file libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

   This file documents the GNU C library.

   This is Edition 0.08 DRAFT, last updated 11 Jan 1999, of `The GNU C
Library Reference Manual', for Version 2.1 Beta.

   Copyright (C) 1993, '94, '95, '96, '97, '98, '99 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.


File: libc.info,  Node: Exponents and Logarithms,  Next: Hyperbolic Functions,  Prev: Inverse Trig Functions,  Up: Mathematics

Exponentiation and Logarithms
=============================

 - Function: double exp (double X)
 - Function: float expf (float X)
 - Function: long double expl (long double X)
     These functions compute `e' (the base of natural logarithms) raised
     to the power X.

     If the magnitude of the result is too large to be representable,
     `exp' signals overflow.

 - Function: double exp2 (double X)
 - Function: float exp2f (float X)
 - Function: long double exp2l (long double X)
     These functions compute `2' raised to the power X.
     Mathematically, `exp2 (x)' is the same as `exp (x * log (2))'.

 - Function: double exp10 (double X)
 - Function: float exp10f (float X)
 - Function: long double exp10l (long double X)
 - Function: double pow10 (double X)
 - Function: float pow10f (float X)
 - Function: long double pow10l (long double X)
     These functions compute `10' raised to the power X.
     Mathematically, `exp10 (x)' is the same as `exp (x * log (10))'.

     These functions are GNU extensions.  The name `exp10' is
     preferred, since it is analogous to `exp' and `exp2'.

 - Function: double log (double X)
 - Function: float logf (float X)
 - Function: long double logl (long double X)
     These functions compute the natural logarithm of X.  `exp (log
     (X))' equals X, exactly in mathematics and approximately in C.

     If X is negative, `log' signals a domain error.  If X is zero, it
     returns negative infinity; if X is too close to zero, it may
     signal overflow.

 - Function: double log10 (double X)
 - Function: float log10f (float X)
 - Function: long double log10l (long double X)
     These functions return the base-10 logarithm of X.  `log10 (X)'
     equals `log (X) / log (10)'.


 - Function: double log2 (double X)
 - Function: float log2f (float X)
 - Function: long double log2l (long double X)
     These functions return the base-2 logarithm of X.  `log2 (X)'
     equals `log (X) / log (2)'.

 - Function: double logb (double X)
 - Function: float logbf (float X)
 - Function: long double logbl (long double X)
     These functions extract the exponent of X and return it as a
     floating-point value.  If `FLT_RADIX' is two, `logb' is equal to
     `floor (log2 (x))', except it's probably faster.

     If X is denormalized, `logb' returns the exponent X would have if
     it were normalized.  If X is infinity (positive or negative),
     `logb' returns oo.  If X is zero, `logb' returns oo.  It does not
     signal.

 - Function: int ilogb (double X)
 - Function: int ilogbf (float X)
 - Function: int ilogbl (long double X)
     These functions are equivalent to the corresponding `logb'
     functions except that they return signed integer values.

Since integers cannot represent infinity and NaN, `ilogb' instead
returns an integer that can't be the exponent of a normal floating-point
number.  `math.h' defines constants so you can check for this.

 - Macro: int FP_ILOGB0
     `ilogb' returns this value if its argument is `0'.  The numeric
     value is either `INT_MIN' or `-INT_MAX'.

     This macro is defined in ISO C 9X.

 - Macro: int FP_ILOGBNAN
     `ilogb' returns this value if its argument is `NaN'.  The numeric
     value is either `INT_MIN' or `INT_MAX'.

     This macro is defined in ISO C 9X.

   These values are system specific.  They might even be the same.  The
proper way to test the result of `ilogb' is as follows:

     i = ilogb (f);
     if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
       {
         if (isnan (f))
           {
             /* Handle NaN.  */
           }
         else if (f  == 0.0)
           {
             /* Handle 0.0.  */
           }
         else
           {
             /* Some other value with large exponent,
                perhaps +Inf.  */
           }
       }

 - Function: double pow (double BASE, double POWER)
 - Function: float powf (float BASE, float POWER)
 - Function: long double powl (long double BASE, long double POWER)
     These are general exponentiation functions, returning BASE raised
     to POWER.

     Mathematically, `pow' would return a complex number when BASE is
     negative and POWER is not an integral value.  `pow' can't do that,
     so instead it signals a domain error. `pow' may also underflow or
     overflow the destination type.

 - Function: double sqrt (double X)
 - Function: float sqrtf (float X)
 - Function: long double sqrtl (long double X)
     These functions return the nonnegative square root of X.

     If X is negative, `sqrt' signals a domain error.  Mathematically,
     it should return a complex number.

 - Function: double cbrt (double X)
 - Function: float cbrtf (float X)
 - Function: long double cbrtl (long double X)
     These functions return the cube root of X.  They cannot fail;
     every representable real value has a representable real cube root.

 - Function: double hypot (double X, double Y)
 - Function: float hypotf (float X, float Y)
 - Function: long double hypotl (long double X, long double Y)
     These functions return `sqrt (X*X + Y*Y)'.  This is the length of
     the hypotenuse of a right triangle with sides of length X and Y,
     or the distance of the point (X, Y) from the origin.  Using this
     function instead of the direct formula is wise, since the error is
     much smaller.  See also the function `cabs' in *Note Absolute
     Value::.

 - Function: double expm1 (double X)
 - Function: float expm1f (float X)
 - Function: long double expm1l (long double X)
     These functions return a value equivalent to `exp (X) - 1'.  They
     are computed in a way that is accurate even if X is near zero--a
     case where `exp (X) - 1' would be inaccurate due to subtraction of
     two numbers that are nearly equal.

 - Function: double log1p (double X)
 - Function: float log1pf (float X)
 - Function: long double log1pl (long double X)
     These functions returns a value equivalent to `log (1 + X)'.  They
     are computed in a way that is accurate even if X is near zero.

   ISO C 9X defines complex variants of some of the exponentiation and
logarithm functions.

 - Function: complex double cexp (complex double Z)
 - Function: complex float cexpf (complex float Z)
 - Function: complex long double cexpl (complex long double Z)
     These functions return `e' (the base of natural logarithms) raised
     to the power of Z.  Mathematically this corresponds to the value

     exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))

 - Function: complex double clog (complex double Z)
 - Function: complex float clogf (complex float Z)
 - Function: complex long double clogl (complex long double Z)
     These functions return the natural logarithm of Z.  Mathematically
     this corresponds to the value

     log (z) = log (cabs (z)) + I * carg (z)

     `clog' has a pole at 0, and will signal overflow if Z equals or is
     very close to 0.  It is well-defined for all other values of Z.

 - Function: complex double clog10 (complex double Z)
 - Function: complex float clog10f (complex float Z)
 - Function: complex long double clog10l (complex long double Z)
     These functions return the base 10 logarithm of the complex value
     Z. Mathematically this corresponds to the value

     log (z) = log10 (cabs (z)) + I * carg (z)

     These functions are GNU extensions.

 - Function: complex double csqrt (complex double Z)
 - Function: complex float csqrtf (complex float Z)
 - Function: complex long double csqrtl (complex long double Z)
     These functions return the complex square root of the argument Z.
     Unlike the real-valued functions, they are defined for all values
     of Z.

 - Function: complex double cpow (complex double BASE, complex double
          POWER)
 - Function: complex float cpowf (complex float BASE, complex float
          POWER)
 - Function: complex long double cpowl (complex long double BASE,
          complex long double POWER)
     These functions return BASE raised to the power of POWER.  This is
     equivalent to `cexp (y * clog (x))'


File: libc.info,  Node: Hyperbolic Functions,  Next: Special Functions,  Prev: Exponents and Logarithms,  Up: Mathematics

Hyperbolic Functions
====================

   The functions in this section are related to the exponential
functions; see *Note Exponents and Logarithms::.

 - Function: double sinh (double X)
 - Function: float sinhf (float X)
 - Function: long double sinhl (long double X)
     These functions return the hyperbolic sine of X, defined
     mathematically as `(exp (X) - exp (-X)) / 2'.  They may signal
     overflow if X is too large.

 - Function: double cosh (double X)
 - Function: float coshf (float X)
 - Function: long double coshl (long double X)
     These function return the hyperbolic cosine of X, defined
     mathematically as `(exp (X) + exp (-X)) / 2'.  They may signal
     overflow if X is too large.

 - Function: double tanh (double X)
 - Function: float tanhf (float X)
 - Function: long double tanhl (long double X)
     These functions return the hyperbolic tangent of X, defined
     mathematically as `sinh (X) / cosh (X)'.  They may signal overflow
     if X is too large.

   There are counterparts for the hyperbolic functions which take
complex arguments.

 - Function: complex double csinh (complex double Z)
 - Function: complex float csinhf (complex float Z)
 - Function: complex long double csinhl (complex long double Z)
     These functions return the complex hyperbolic sine of Z, defined
     mathematically as `(exp (Z) - exp (-Z)) / 2'.

 - Function: complex double ccosh (complex double Z)
 - Function: complex float ccoshf (complex float Z)
 - Function: complex long double ccoshl (complex long double Z)
     These functions return the complex hyperbolic cosine of Z, defined
     mathematically as `(exp (Z) + exp (-Z)) / 2'.

 - Function: complex double ctanh (complex double Z)
 - Function: complex float ctanhf (complex float Z)
 - Function: complex long double ctanhl (complex long double Z)
     These functions return the complex hyperbolic tangent of Z,
     defined mathematically as `csinh (Z) / ccosh (Z)'.

 - Function: double asinh (double X)
 - Function: float asinhf (float X)
 - Function: long double asinhl (long double X)
     These functions return the inverse hyperbolic sine of X--the value
     whose hyperbolic sine is X.

 - Function: double acosh (double X)
 - Function: float acoshf (float X)
 - Function: long double acoshl (long double X)
     These functions return the inverse hyperbolic cosine of X--the
     value whose hyperbolic cosine is X.  If X is less than `1',
     `acosh' signals a domain error.

 - Function: double atanh (double X)
 - Function: float atanhf (float X)
 - Function: long double atanhl (long double X)
     These functions return the inverse hyperbolic tangent of X--the
     value whose hyperbolic tangent is X.  If the absolute value of X
     is greater than `1', `atanh' signals a domain error; if it is
     equal to 1, `atanh' returns infinity.

 - Function: complex double casinh (complex double Z)
 - Function: complex float casinhf (complex float Z)
 - Function: complex long double casinhl (complex long double Z)
     These functions return the inverse complex hyperbolic sine of
     Z--the value whose complex hyperbolic sine is Z.

 - Function: complex double cacosh (complex double Z)
 - Function: complex float cacoshf (complex float Z)
 - Function: complex long double cacoshl (complex long double Z)
     These functions return the inverse complex hyperbolic cosine of
     Z--the value whose complex hyperbolic cosine is Z.  Unlike the
     real-valued functions, there are no restrictions on the value of Z.

 - Function: complex double catanh (complex double Z)
 - Function: complex float catanhf (complex float Z)
 - Function: complex long double catanhl (complex long double Z)
     These functions return the inverse complex hyperbolic tangent of
     Z--the value whose complex hyperbolic tangent is Z.  Unlike the
     real-valued functions, there are no restrictions on the value of Z.


File: libc.info,  Node: Special Functions,  Next: Pseudo-Random Numbers,  Prev: Hyperbolic Functions,  Up: Mathematics

Special Functions
=================

   These are some more exotic mathematical functions, which are
sometimes useful.  Currently they only have real-valued versions.

 - Function: double erf (double X)
 - Function: float erff (float X)
 - Function: long double erfl (long double X)
     `erf' returns the error function of X.  The error function is
     defined as
          erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt

 - Function: double erfc (double X)
 - Function: float erfcf (float X)
 - Function: long double erfcl (long double X)
     `erfc' returns `1.0 - erf(X)', but computed in a fashion that
     avoids round-off error when X is large.

 - Function: double lgamma (double X)
 - Function: float lgammaf (float X)
 - Function: long double lgammal (long double X)
     `lgamma' returns the natural logarithm of the absolute value of
     the gamma function of X.  The gamma function is defined as
          gamma (x) = integral from 0 to oo of t^(x-1) e^-t dt

     The sign of the gamma function is stored in the global variable
     SIGNGAM, which is declared in `math.h'.  It is `1' if the
     intermediate result was positive or zero, and, `-1' if it was
     negative.

     To compute the real gamma function you can use the `tgamma'
     function or you can compute the values as follows:
          lgam = lgamma(x);
          gam  = signgam*exp(lgam);

     The gamma function has singularities at the nonpositive integers.
     `lgamma' will raise the zero divide exception if evaluated at a
     singularity.

 - Function: double lgamma_r (double X, int *SIGNP)
 - Function: float lgammaf_r (float X, int *SIGNP)
 - Function: long double lgammal_r (long double X, int *SIGNP)
     `lgamma_r' is just like `lgamma', but it stores the sign of the
     intermediate result in the variable pointed to by SIGNP instead of
     in the SIGNGAM global.

 - Function: double gamma (double X)
 - Function: float gammaf (float X)
 - Function: long double gammal (long double X)
     These functions exist for compatibility reasons.  They are
     equivalent to `lgamma' etc.  It is better to use `lgamma' since
     for one the name reflects better the actual computation and
     `lgamma' is also standardized in ISO C 9x while `gamma' is not.

 - Function: double tgamma (double X)
 - Function: float tgammaf (float X)
 - Function: long double tgammal (long double X)
     `tgamma' applies the gamma function to X.  The gamma function is
     defined as
          gamma (x) = integral from 0 to oo of t^(x-1) e^-t dt

     This function was introduced in ISO C 9x.

 - Function: double j0 (double X)
 - Function: float j0f (float X)
 - Function: long double j0l (long double X)
     `j0' returns the Bessel function of the first kind of order 0 of
     X.  It may signal underflow if X is too large.

 - Function: double j1 (double X)
 - Function: float j1f (float X)
 - Function: long double j1l (long double X)
     `j1' returns the Bessel function of the first kind of order 1 of
     X.  It may signal underflow if X is too large.

 - Function: double jn (int n, double X)
 - Function: float jnf (int n, float X)
 - Function: long double jnl (int n, long double X)
     `jn' returns the Bessel function of the first kind of order N of
     X.  It may signal underflow if X is too large.

 - Function: double y0 (double X)
 - Function: float y0f (float X)
 - Function: long double y0l (long double X)
     `y0' returns the Bessel function of the second kind of order 0 of
     X.  It may signal underflow if X is too large.  If X is negative,
     `y0' signals a domain error; if it is zero, `y0' signals overflow
     and returns -oo.

 - Function: double y1 (double X)
 - Function: float y1f (float X)
 - Function: long double y1l (long double X)
     `y1' returns the Bessel function of the second kind of order 1 of
     X.  It may signal underflow if X is too large.  If X is negative,
     `y1' signals a domain error; if it is zero, `y1' signals overflow
     and returns -oo.

 - Function: double yn (int n, double X)
 - Function: float ynf (int n, float X)
 - Function: long double ynl (int n, long double X)
     `yn' returns the Bessel function of the second kind of order N of
     X.  It may signal underflow if X is too large.  If X is negative,
     `yn' signals a domain error; if it is zero, `yn' signals overflow
     and returns -oo.


File: libc.info,  Node: Pseudo-Random Numbers,  Next: FP Function Optimizations,  Prev: Special Functions,  Up: Mathematics

Pseudo-Random Numbers
=====================

   This section describes the GNU facilities for generating a series of
pseudo-random numbers.  The numbers generated are not truly random;
typically, they form a sequence that repeats periodically, with a period
so large that you can ignore it for ordinary purposes.  The random
number generator works by remembering a "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 *exactly the same* from one run to
the next.  This is because the initial seed is always the same.  This
is convenient when you are debugging a program, but it is unhelpful if
you want the program to behave unpredictably.  If you want a different
pseudo-random series each time your program runs, you must specify a
different seed each time.  For ordinary purposes, basing the seed on the
current time works well.

   You can get repeatable sequences of numbers on a particular machine
type by specifying the same initial seed value for the random number
generator.  There is no standard meaning for a particular seed value;
the same seed, used in different C libraries or on different CPU types,
will give you different random numbers.

   The GNU library supports the standard ISO C random number functions
plus two other sets derived from BSD and SVID.  The BSD and ISO C
functions provide identical, somewhat limited functionality.  If only a
small number of random bits are required, we recommend you use the
ISO C interface, `rand' and `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:

* ISO Random::                  `rand' and friends.
* BSD Random::                  `random' and friends.
* SVID Random::                 `drand48' and friends.


File: libc.info,  Node: ISO Random,  Next: BSD Random,  Up: Pseudo-Random Numbers

ISO C Random Number Functions
-----------------------------

   This section describes the random number functions that are part of
the ISO C standard.

   To use these facilities, you should include the header file
`stdlib.h' in your program.

 - Macro: int RAND_MAX
     The value of this macro is an integer constant representing the
     largest value the `rand' function can return.  In the GNU library,
     it is `2147483647', which is the largest signed integer
     representable in 32 bits.  In other libraries, it may be as low as
     `32767'.

 - Function: int rand (void)
     The `rand' function returns the next pseudo-random number in the
     series.  The value ranges from `0' to `RAND_MAX'.

 - Function: void srand (unsigned int SEED)
     This function establishes SEED as the seed for a new series of
     pseudo-random numbers.  If you call `rand' before a seed has been
     established with `srand', it uses the value `1' as a default seed.

     To produce a different pseudo-random series each time your program
     is run, do `srand (time (0))'.

   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.

 - Function: int rand_r (unsigned int *SEED)
     This function returns a random number in the range 0 to `RAND_MAX'
     just as `rand' does.  However, all its state is stored in the SEED
     argument.  This means the RNG's state can only have as many bits
     as the type `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.


File: libc.info,  Node: BSD Random,  Next: SVID Random,  Prev: ISO Random,  Up: Pseudo-Random Numbers

BSD Random Number Functions
---------------------------

   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 `stdlib.h'.

 - Function: int32_t random (void)
     This function returns the next pseudo-random number in the
     sequence.  The value returned ranges from `0' to `RAND_MAX'.

     *Note:* Historically this function returned a `long int' value.
     On 64bit systems `long int' would have been larger than programs
     expected, so `random' is now defined to return exactly 32 bits.

 - Function: void srandom (unsigned int SEED)
     The `srandom' function sets the state of the random number
     generator based on the integer SEED.  If you supply a SEED value
     of `1', this will cause `random' to reproduce the default set of
     random numbers.

     To produce a different set of pseudo-random numbers each time your
     program runs, do `srandom (time (0))'.

 - Function: void * initstate (unsigned int SEED, void *STATE, size_t
          SIZE)
     The `initstate' function is used to initialize the random number
     generator state.  The argument STATE is an array of SIZE bytes,
     used to hold the state information.  It is initialized based on
     SEED.  The size must be between 8 and 256 bytes, and should be a
     power of two.  The bigger the 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 `setstate'
     to restore that state.

 - Function: void * setstate (void *STATE)
     The `setstate' function restores the random number state
     information STATE.  The argument must have been the result of a
     previous call to INITSTATE or SETSTATE.

     The return value is the previous value of the state information
     array.  You can use this value later as an argument to `setstate'
     to restore that state.


File: libc.info,  Node: SVID Random,  Prev: BSD Random,  Up: Pseudo-Random Numbers

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 functions: those which use a state
of the random number generator which is shared among several functions
and by all threads of the process.  The second group of functions
require 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

     Y = (a * X + c) mod m

where X is the state of the generator at the beginning and Y the state
at the end.  `a' and `c' are constants determining the way the
generator work.  By default they are

     a = 0x5DEECE66D = 25214903917
     c = 0xb = 11

but they can also be changed by the user.  `m' is of course 2^48 since
the state consists of a 48 bit array.

 - Function: double drand48 (void)
     This function returns a `double' value in the range of `0.0' to
     `1.0' (exclusive).  The random bits are determined by the global
     state of the random number generator in the C library.

     Since the `double' type according to 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 `0'.

 - Function: double erand48 (unsigned short int XSUBI[3])
     This function returns a `double' value in the range of `0.0' to
     `1.0' (exclusive), similar to `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 using to get reproducible results.

 - Function: long int lrand48 (void)
     The `lrand48' functions return an integer value in the range of
     `0' to `2^31' (exclusive).  Even if the size of the `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.

 - Function: long int nrand48 (unsigned short int XSUBI[3])
     This function is similar to the `lrand48' function in that it
     returns a number in the range of `0' to `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 afterwards updated so that subsequent
     calls to this function yield to different results (as it is
     expected by a random number generator).  The array should have
     been initialized before the first call to get reproducible results.

 - Function: long int mrand48 (void)
     The `mrand48' function is similar to `lrand48'.  The only
     difference is that the numbers returned are in the range `-2^31' to
     `2^31' (exclusive).

 - Function: long int jrand48 (unsigned short int XSUBI[3])
     The `jrand48' function is similar to `nrand48'.  The only
     difference is that the numbers returned are in the range `-2^31' to
     `2^31' (exclusive).  For the `xsubi' parameter the same
     requirements are necessary.

   The internal state of the random number generator can be initialized
in several ways.  The functions differ in the completeness of the
information provided.

 - Function: void srand48 (long int SEEDVAL))
     The `srand48' function sets the most significant 32 bits of the
     state internal state of the random number generator to the least
     significant 32 bits of the SEEDVAL parameter.  The lower 16 bits
     are initialized to the value `0x330E'.  Even if the `long int'
     type contains more the 32 bits only the lower 32 bits are used.

     Due to this limitation the initialization of the state using this
     function of not very useful.  But it makes it easy to use a
     construct like `srand48 (time (0))'.

     A side-effect of this function is that the values `a' and `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 called the `lcong48' function (see below).

 - Function: unsigned short int * seed48 (unsigned short int SEED16V[3])
     The `seed48' function initializes all 48 bits of the state of the
     internal random number generator from the content of the parameter
     SEED16V.  Here the lower 16 bits of the first element of SEE16V
     initialize the least significant 16 bits of the internal state,
     the lower 16 bits of `SEED16V[1]' initialize the mid-order 16 bits
     of the state and the 16 lower bits of `SEED16V[2]' initialize the
     most significant 16 bits of the state.

     Unlike `srand48' this function lets the user initialize all 48 bits
     of the state.

     The value returned by `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 `srand48', the values `a' and `c' from the congruential
     formula are reset to the default values.

   There is one more function to initialize the random number generator
which allows to specify even more information by allowing to change the
parameters in the congruential formula.

 - Function: void lcong48 (unsigned short int PARAM[7])
     The `lcong48' function allows the user to change the complete state
     of the random number generator.  Unlike `srand48' and `seed48',
     this function also changes the constants in the congruential
     formula.

     From the seven elements in the array PARAM the least significant
     16 bits of the entries `PARAM[0]' to `PARAM[2]' determine the
     initial state, the least 16 bits of `PARAM[3]' to `PARAM[5]'
     determine the 48 bit constant `a' and `PARAM[6]' determines the 16
     bit value `c'.

   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
get an individual random number generator.

   The user supplied buffer must be of type `struct drand48_data'.
This type should be regarded as opaque and no member should be used
directly.

 - Function: int drand48_r (struct drand48_data *BUFFER, double *RESULT)
     This function is equivalent to the `drand48' function with the
     difference it does not modify the global random number generator
     parameters but instead the parameters is the buffer supplied by the
     buffer through the pointer BUFFER.  The random number is return in
     the variable pointed to by RESULT.

     The return value of the function indicate whether the call
     succeeded.  If the value is less than `0' an error occurred and
     ERRNO is set to indicate the problem.

     This function is a GNU extension and should not be used in portable
     programs.

 - Function: int erand48_r (unsigned short int XSUBI[3], struct
          drand48_data *BUFFER, double *RESULT)
     The `erand48_r' function works like the `erand48' and it takes an
     argument BUFFER which describes the random number generator.  The
     state of the random number generator is taken from the `xsubi'
     array, the parameters for the congruential formula from the global
     random number generator data.  The random number is return in the
     variable pointed to by RESULT.

     The return value is non-negative is the call succeeded.

     This function is a GNU extension and should not be used in portable
     programs.

 - Function: int lrand48_r (struct drand48_data *BUFFER, double *RESULT)
     This function is similar to `lrand48' and it takes a pointer to a
     buffer describing the state of the random number generator as a
     parameter just like `drand48'.

     If the return value of the function is non-negative the variable
     pointed to by RESULT contains the result.  Otherwise an error
     occurred.

     This function is a GNU extension and should not be used in portable
     programs.

 - Function: int nrand48_r (unsigned short int XSUBI[3], struct
          drand48_data *BUFFER, long int *RESULT)
     The `nrand48_r' function works like `nrand48' in that it produces
     a random number in range `0' to `2^31'.  But instead of using the
     global parameters for the congruential formula it uses the
     information from the buffer pointed to by BUFFER.  The state is
     described by the values in XSUBI.

     If the return value is non-negative the variable pointed to by
     RESULT contains the result.

     This function is a GNU extension and should not be used in portable
     programs.

 - Function: int mrand48_r (struct drand48_data *BUFFER, double *RESULT)
     This function is similar to `mrand48' but as the other reentrant
     function it uses the random number generator described by the
     value in the buffer pointed to by BUFFER.

     If the return value is non-negative the variable pointed to by
     RESULT contains the result.

     This function is a GNU extension and should not be used in portable
     programs.

 - Function: int jrand48_r (unsigned short int XSUBI[3], struct
          drand48_data *BUFFER, long int *RESULT)
     The `jrand48_r' function is similar to `jrand48'.  But as the
     other reentrant functions of this function family it uses the
     congruential formula parameters from the buffer pointed to by
     BUFFER.

     If the return value is non-negative the variable pointed to by
     RESULT contains the result.

     This function is a GNU extension and should not be used in portable
     programs.

   Before any of the above functions should be used the buffer of type
`struct drand48_data' should initialized.  The easiest way is to fill
the whole buffer with null bytes, e.g., using

     memset (buffer, '\0', sizeof (struct drand48_data));

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 too use any of the functions which
explicitely initialize the buffer.  Though it might be obvious how to
initialize the buffer from the data given as parameter from the
function it is highly recommended to use these functions since the
result might not always be what you expect.

 - Function: int srand48_r (long int SEEDVAL, struct drand48_data
          *BUFFER)
     The description of the random number generator represented by the
     information in BUFFER is initialized similar to what the function
     `srand48' does.  The state is initialized from the parameter
     SEEDVAL and the parameters for the congruential formula are
     initialized to the 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.

 - Function: int seed48_r (unsigned short int SEED16V[3], struct
          drand48_data *BUFFER)
     This function is similar to `srand48_r' but like `seed48' it
     initializes all 48 bits of the state from the parameter 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 `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 BUFFER.

     This function is a GNU extension and should not be used in portable
     programs.

 - Function: int lcong48_r (unsigned short int PARAM[7], struct
          drand48_data *BUFFER)
     This function initializes all aspects of the random number
     generator described in BUFFER by the data in PARAM.  Here it is
     especially true the function does more than just copying the
     contents of PARAM of BUFFER.  Some more actions are required and
     therefore it is important to use this function and not initialized
     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.


File: libc.info,  Node: FP Function Optimizations,  Prev: Pseudo-Random Numbers,  Up: Mathematics

Is Fast Code or Small Code preferred?
=====================================

   If an application uses many floating point function it is often the
case that the costs for the function calls itselfs are not neglectable.
Modern processor implementation often can execute the operation itself
very fast but the call means a disturbance of the control flow.

   For this reason the GNU C Library provides optimizations for many of
the frequently used math functions.  When the GNU CC is used and the
user activates the optimizer several new inline functions and macros get
defined.  These new functions and macros have the same names as the
library function and so get used instead of the later.  In case of
inline functions the compiler will decide whether it is reasonable to
use the inline function and this decision is usually correct.

   For the generated code this means that no calls to the library
functions are necessary.  This increases the speed significantly.  But
the drawback is that the code size increases and this increase is not
always neglectable.

   In cases where the inline functions and macros are not wanted the
symbol `__NO_MATH_INLINES' should be defined before any system header is
included.  This will make sure only library functions are used.  Of
course it can be determined for each single file in the project whether
giving this option is preferred or not.

   Not all hardware implements the entire IEEE 754 standard, or 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 more than doubles calculation time.


File: libc.info,  Node: Arithmetic,  Next: Date and Time,  Prev: Mathematics,  Up: Top

Arithmetic Functions
********************

   This chapter contains information about functions for doing basic
arithmetic operations, such as splitting a float into its integer and
fractional parts or retrieving the imaginary part of a complex value.
These functions are declared in the header files `math.h' and
`complex.h'.

* Menu:

* Floating Point Numbers::      Basic concepts.  IEEE 754.
* Floating Point Classes::      The five kinds of floating-point number.
* Floating Point Errors::       When something goes wrong in a calculation.
* Rounding::                    Controlling how results are rounded.
* Control Functions::           Saving and restoring the FPU's state.
* Arithmetic Functions::        Fundamental operations provided by the library.
* Complex Numbers::             The types.  Writing complex constants.
* Operations on Complex::       Projection, conjugation, decomposition.
* Integer Division::            Integer division with guaranteed rounding.
* Parsing of Numbers::          Converting strings to numbers.
* System V Number Conversion::  An archaic way to convert numbers to strings.


File: libc.info,  Node: Floating Point Numbers,  Next: Floating Point Classes,  Up: Arithmetic

Floating Point Numbers
======================

   Most computer hardware has support for two different kinds of
numbers: integers (...-3, -2, -1, 0, 1, 2, 3...) and floating-point
numbers.  Floating-point numbers have three parts: the "mantissa", the
"exponent", and the "sign bit".  The real number represented by a
floating-point value is given by (s ? -1 : 1) * 2^e * M where s is the
sign bit, e the exponent, and M the mantissa.  *Note Floating Point
Concepts::, for details.  (It is possible to have a different "base"
for the exponent, but all modern hardware uses 2.)

   Floating-point numbers can represent a finite subset of the real
numbers.  While this subset is large enough for most purposes, it is
important to remember that the only reals that can be represented
exactly are rational numbers that have a terminating binary expansion
shorter than the width of the mantissa.  Even simple fractions such as
1/5 can only be approximated by floating point.

   Mathematical operations and functions frequently need to produce
values that are not representable.  Often these values can be
approximated closely enough for practical purposes, but sometimes they
can't.  Historically there was no way to tell when the results of a
calculation were inaccurate.  Modern computers implement the IEEE 754
standard for numerical computations, which defines a framework for
indicating to the program when the results of calculation are not
trustworthy.  This framework consists of a set of "exceptions" that
indicate why a result could not be represented, and the special values
"infinity" and "not a number" (NaN).


File: libc.info,  Node: Floating Point Classes,  Next: Floating Point Errors,  Prev: Floating Point Numbers,  Up: Arithmetic

Floating-Point Number Classification Functions
==============================================

   ISO C 9x defines macros that let you determine what sort of
floating-point number a variable holds.

 - Macro: int fpclassify (*float-type* X)
     This is a generic macro which works on all floating-point types and
     which returns a value of type `int'.  The possible values are:

    `FP_NAN'
          The floating-point number X is "Not a Number" (*note Infinity
          and NaN::.)

    `FP_INFINITE'
          The value of X is either plus or minus infinity (*note
          Infinity and NaN::.)

    `FP_ZERO'
          The value of X is zero.  In floating-point formats like
          IEEE 754, where zero can be signed, this value is also
          returned if X is negative zero.

    `FP_SUBNORMAL'
          Numbers whose absolute value is too small to be represented
          in the normal format are represented in an alternate,
          "denormalized" format (*note Floating Point Concepts::.).
          This format is less precise but can represent values closer
          to zero.  `fpclassify' returns this value for values of X in
          this alternate format.

    `FP_NORMAL'
          This value is returned for all other values of X.  It
          indicates that there is nothing special about the number.


   `fpclassify' is most useful if more than one property of a number
must be tested.  There are more specific macros which only test one
property at a time.  Generally these macros execute faster than
`fpclassify', since there is special hardware support for them.  You
should therefore use the specific macros whenever possible.

 - Macro: int isfinite (*float-type* X)
     This macro returns a nonzero value if X is finite: not plus or
     minus infinity, and not NaN.  It is equivalent to

          (fpclassify (x) != FP_NAN && fpclassify (x) != FP_INFINITE)

     `isfinite' is implemented as a macro which accepts any
     floating-point type.

 - Macro: int isnormal (*float-type* X)
     This macro returns a nonzero value if X is finite and normalized.
     It is equivalent to

          (fpclassify (x) == FP_NORMAL)

 - Macro: int isnan (*float-type* X)
     This macro returns a nonzero value if X is NaN.  It is equivalent
     to

          (fpclassify (x) == FP_NAN)

   Another set of floating-point classification functions was provided
by BSD.  The GNU C library also supports these functions; however, we
recommend that you use the C9x macros in new code.  Those are standard
and will be available more widely.  Also, since they are macros, you do
not have to worry about the type of their argument.

 - Function: int isinf (double X)
 - Function: int isinff (float X)
 - Function: int isinfl (long double X)
     This function returns `-1' if X represents negative infinity, `1'
     if X represents positive infinity, and `0' otherwise.

 - Function: int isnan (double X)
 - Function: int isnanf (float X)
 - Function: int isnanl (long double X)
     This function returns a nonzero value if X is a "not a number"
     value, and zero otherwise.

     *Note:* The `isnan' macro defined by ISO C 9x overrides the BSD
     function.  This is normally not a problem, because the two
     routines behave identically.  However, if you really need to get
     the BSD function for some reason, you can write

          (isnan) (x)

 - Function: int finite (double X)
 - Function: int finitef (float X)
 - Function: int finitel (long double X)
     This function returns a nonzero value if X is finite or a "not a
     number" value, and zero otherwise.

 - Function: double infnan (int ERROR)
     This function is provided for compatibility with BSD.  Its
     argument is an error code, `EDOM' or `ERANGE'; `infnan' returns the
     value that a math function would return if it set `errno' to that
     value.  *Note Math Error Reporting::.  `-ERANGE' is also acceptable
     as an argument, and corresponds to `-HUGE_VAL' as a value.

     In the BSD library, on certain machines, `infnan' raises a fatal
     signal in all cases.  The GNU library does not do likewise,
     because that does not fit the ISO C specification.

   *Portability Note:* The functions listed in this section are BSD
extensions.


File: libc.info,  Node: Floating Point Errors,  Next: Rounding,  Prev: Floating Point Classes,  Up: Arithmetic

Errors in Floating-Point Calculations
=====================================

* Menu:

* FP Exceptions::               IEEE 754 math exceptions and how to detect them.
* Infinity and NaN::            Special values returned by calculations.
* Status bit operations::       Checking for exceptions after the fact.
* Math Error Reporting::        How the math functions report errors.

