1 @c We need some definitions here.
30 @node Mathematics, Arithmetic, Syslog, Top
31 @c %MENU% Math functions, useful constants, random numbers
34 This chapter contains information about functions for performing
35 mathematical computations, such as trigonometric functions. Most of
36 these functions have prototypes declared in the header file
37 @file{math.h}. The complex-valued functions are defined in
42 All mathematical functions which take a floating-point argument
43 have three variants, one each for @code{double}, @code{float}, and
44 @code{long double} arguments. The @code{double} versions are mostly
45 defined in @w{ISO C89}. The @code{float} and @code{long double}
46 versions are from the numeric extensions to C included in @w{ISO C99}.
48 Which of the three versions of a function should be used depends on the
49 situation. For most calculations, the @code{float} functions are the
50 fastest. On the other hand, the @code{long double} functions have the
51 highest precision. @code{double} is somewhere in between. It is
52 usually wise to pick the narrowest type that can accommodate your data.
53 Not all machines have a distinct @code{long double} type; it may be the
54 same as @code{double}.
56 On some machines, @theglibc{} also provides @code{_Float@var{N}} and
57 @code{_Float@var{N}x} types. These types are defined in @w{ISO/IEC TS
58 18661-3}, which extends @w{ISO C} and defines floating-point types that
59 are not machine-dependent. When such a type, such as @code{_Float128},
60 is supported by @theglibc{}, extra variants for most of the mathematical
61 functions provided for @code{double}, @code{float}, and @code{long
62 double} are also provided for the supported type.
64 Currently, support for @code{_Float@var{N}} or @code{_Float@var{N}x}
65 types is not provided for any machine.
68 * Mathematical Constants:: Precise numeric values for often-used
70 * Trig Functions:: Sine, cosine, tangent, and friends.
71 * Inverse Trig Functions:: Arcsine, arccosine, etc.
72 * Exponents and Logarithms:: Also pow and sqrt.
73 * Hyperbolic Functions:: sinh, cosh, tanh, etc.
74 * Special Functions:: Bessel, gamma, erf.
75 * Errors in Math Functions:: Known Maximum Errors in Math Functions.
76 * Pseudo-Random Numbers:: Functions for generating pseudo-random
78 * FP Function Optimizations:: Fast code or small code.
81 @node Mathematical Constants
82 @section Predefined Mathematical Constants
84 @cindex mathematical constants
86 The header @file{math.h} defines several useful mathematical constants.
87 All values are defined as preprocessor macros starting with @code{M_}.
88 The values provided are:
92 The base of natural logarithms.
94 The logarithm to base @code{2} of @code{M_E}.
96 The logarithm to base @code{10} of @code{M_E}.
98 The natural logarithm of @code{2}.
100 The natural logarithm of @code{10}.
102 Pi, the ratio of a circle's circumference to its diameter.
108 The reciprocal of pi (1/pi)
110 Two times the reciprocal of pi.
112 Two times the reciprocal of the square root of pi.
114 The square root of two.
116 The reciprocal of the square root of two (also the square root of 1/2).
119 These constants come from the Unix98 standard and were also available in
120 4.4BSD; therefore they are only defined if
121 @code{_XOPEN_SOURCE=500}, or a more general feature select macro, is
122 defined. The default set of features includes these constants.
123 @xref{Feature Test Macros}.
125 All values are of type @code{double}. As an extension, @theglibc{}
126 also defines these constants with type @code{long double}. The
127 @code{long double} macros have a lowercase @samp{l} appended to their
128 names: @code{M_El}, @code{M_PIl}, and so forth. These are only
129 available if @code{_GNU_SOURCE} is defined.
132 @emph{Note:} Some programs use a constant named @code{PI} which has the
133 same value as @code{M_PI}. This constant is not standard; it may have
134 appeared in some old AT&T headers, and is mentioned in Stroustrup's book
135 on C++. It infringes on the user's name space, so @theglibc{}
136 does not define it. Fixing programs written to expect it is simple:
137 replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI}
138 on the compiler command line.
141 @section Trigonometric Functions
142 @cindex trigonometric functions
144 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
145 The arguments to all of these functions are in units of radians; recall
146 that pi radians equals 180 degrees.
148 @cindex pi (trigonometric constant)
149 The math library normally defines @code{M_PI} to a @code{double}
150 approximation of pi. If strict ISO and/or POSIX compliance
151 are requested this constant is not defined, but you can easily define it
155 #define M_PI 3.14159265358979323846264338327
159 You can also compute the value of pi with the expression @code{acos
164 @deftypefun double sin (double @var{x})
167 @deftypefunx float sinf (float @var{x})
170 @deftypefunx {long double} sinl (long double @var{x})
171 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
172 These functions return the sine of @var{x}, where @var{x} is given in
173 radians. The return value is in the range @code{-1} to @code{1}.
178 @deftypefun double cos (double @var{x})
181 @deftypefunx float cosf (float @var{x})
184 @deftypefunx {long double} cosl (long double @var{x})
185 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
186 These functions return the cosine of @var{x}, where @var{x} is given in
187 radians. The return value is in the range @code{-1} to @code{1}.
192 @deftypefun double tan (double @var{x})
195 @deftypefunx float tanf (float @var{x})
198 @deftypefunx {long double} tanl (long double @var{x})
199 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
200 These functions return the tangent of @var{x}, where @var{x} is given in
203 Mathematically, the tangent function has singularities at odd multiples
204 of pi/2. If the argument @var{x} is too close to one of these
205 singularities, @code{tan} will signal overflow.
208 In many applications where @code{sin} and @code{cos} are used, the sine
209 and cosine of the same angle are needed at the same time. It is more
210 efficient to compute them simultaneously, so the library provides a
215 @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
218 @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
221 @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
222 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
223 These functions return the sine of @var{x} in @code{*@var{sinx}} and the
224 cosine of @var{x} in @code{*@var{cosx}}, where @var{x} is given in
225 radians. Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
226 the range of @code{-1} to @code{1}.
228 This function is a GNU extension. Portable programs should be prepared
229 to cope with its absence.
232 @cindex complex trigonometric functions
234 @w{ISO C99} defines variants of the trig functions which work on
235 complex numbers. @Theglibc{} provides these functions, but they
236 are only useful if your compiler supports the new complex types defined
238 @c XXX Change this when gcc is fixed. -zw
239 (As of this writing GCC supports complex numbers, but there are bugs in
244 @deftypefun {complex double} csin (complex double @var{z})
247 @deftypefunx {complex float} csinf (complex float @var{z})
250 @deftypefunx {complex long double} csinl (complex long double @var{z})
251 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
252 @c There are calls to nan* that could trigger @mtslocale if they didn't get
254 These functions return the complex sine of @var{z}.
255 The mathematical definition of the complex sine is
258 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
261 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
267 @deftypefun {complex double} ccos (complex double @var{z})
270 @deftypefunx {complex float} ccosf (complex float @var{z})
273 @deftypefunx {complex long double} ccosl (complex long double @var{z})
274 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
275 These functions return the complex cosine of @var{z}.
276 The mathematical definition of the complex cosine is
279 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
282 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
288 @deftypefun {complex double} ctan (complex double @var{z})
291 @deftypefunx {complex float} ctanf (complex float @var{z})
294 @deftypefunx {complex long double} ctanl (complex long double @var{z})
295 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
296 These functions return the complex tangent of @var{z}.
297 The mathematical definition of the complex tangent is
300 @math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
303 $$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
307 The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an
308 integer. @code{ctan} may signal overflow if @var{z} is too close to a
313 @node Inverse Trig Functions
314 @section Inverse Trigonometric Functions
315 @cindex inverse trigonometric functions
317 These are the usual arcsine, arccosine and arctangent functions,
318 which are the inverses of the sine, cosine and tangent functions
323 @deftypefun double asin (double @var{x})
326 @deftypefunx float asinf (float @var{x})
329 @deftypefunx {long double} asinl (long double @var{x})
330 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
331 These functions compute the arcsine of @var{x}---that is, the value whose
332 sine is @var{x}. The value is in units of radians. Mathematically,
333 there are infinitely many such values; the one actually returned is the
334 one between @code{-pi/2} and @code{pi/2} (inclusive).
336 The arcsine function is defined mathematically only
337 over the domain @code{-1} to @code{1}. If @var{x} is outside the
338 domain, @code{asin} signals a domain error.
343 @deftypefun double acos (double @var{x})
346 @deftypefunx float acosf (float @var{x})
349 @deftypefunx {long double} acosl (long double @var{x})
350 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
351 These functions compute the arccosine of @var{x}---that is, the value
352 whose cosine is @var{x}. The value is in units of radians.
353 Mathematically, there are infinitely many such values; the one actually
354 returned is the one between @code{0} and @code{pi} (inclusive).
356 The arccosine function is defined mathematically only
357 over the domain @code{-1} to @code{1}. If @var{x} is outside the
358 domain, @code{acos} signals a domain error.
363 @deftypefun double atan (double @var{x})
366 @deftypefunx float atanf (float @var{x})
369 @deftypefunx {long double} atanl (long double @var{x})
370 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
371 These functions compute the arctangent of @var{x}---that is, the value
372 whose tangent is @var{x}. The value is in units of radians.
373 Mathematically, there are infinitely many such values; the one actually
374 returned is the one between @code{-pi/2} and @code{pi/2} (inclusive).
379 @deftypefun double atan2 (double @var{y}, double @var{x})
382 @deftypefunx float atan2f (float @var{y}, float @var{x})
385 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
386 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
387 This function computes the arctangent of @var{y}/@var{x}, but the signs
388 of both arguments are used to determine the quadrant of the result, and
389 @var{x} is permitted to be zero. The return value is given in radians
390 and is in the range @code{-pi} to @code{pi}, inclusive.
392 If @var{x} and @var{y} are coordinates of a point in the plane,
393 @code{atan2} returns the signed angle between the line from the origin
394 to that point and the x-axis. Thus, @code{atan2} is useful for
395 converting Cartesian coordinates to polar coordinates. (To compute the
396 radial coordinate, use @code{hypot}; see @ref{Exponents and
399 @c This is experimentally true. Should it be so? -zw
400 If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
403 @cindex inverse complex trigonometric functions
404 @w{ISO C99} defines complex versions of the inverse trig functions.
408 @deftypefun {complex double} casin (complex double @var{z})
411 @deftypefunx {complex float} casinf (complex float @var{z})
414 @deftypefunx {complex long double} casinl (complex long double @var{z})
415 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
416 These functions compute the complex arcsine of @var{z}---that is, the
417 value whose sine is @var{z}. The value returned is in radians.
419 Unlike the real-valued functions, @code{casin} is defined for all
425 @deftypefun {complex double} cacos (complex double @var{z})
428 @deftypefunx {complex float} cacosf (complex float @var{z})
431 @deftypefunx {complex long double} cacosl (complex long double @var{z})
432 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
433 These functions compute the complex arccosine of @var{z}---that is, the
434 value whose cosine is @var{z}. The value returned is in radians.
436 Unlike the real-valued functions, @code{cacos} is defined for all
443 @deftypefun {complex double} catan (complex double @var{z})
446 @deftypefunx {complex float} catanf (complex float @var{z})
449 @deftypefunx {complex long double} catanl (complex long double @var{z})
450 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
451 These functions compute the complex arctangent of @var{z}---that is,
452 the value whose tangent is @var{z}. The value is in units of radians.
456 @node Exponents and Logarithms
457 @section Exponentiation and Logarithms
458 @cindex exponentiation functions
459 @cindex power functions
460 @cindex logarithm functions
464 @deftypefun double exp (double @var{x})
467 @deftypefunx float expf (float @var{x})
470 @deftypefunx {long double} expl (long double @var{x})
471 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
472 These functions compute @code{e} (the base of natural logarithms) raised
473 to the power @var{x}.
475 If the magnitude of the result is too large to be representable,
476 @code{exp} signals overflow.
481 @deftypefun double exp2 (double @var{x})
484 @deftypefunx float exp2f (float @var{x})
487 @deftypefunx {long double} exp2l (long double @var{x})
488 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
489 These functions compute @code{2} raised to the power @var{x}.
490 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
495 @deftypefun double exp10 (double @var{x})
498 @deftypefunx float exp10f (float @var{x})
501 @deftypefunx {long double} exp10l (long double @var{x})
504 @deftypefunx double pow10 (double @var{x})
507 @deftypefunx float pow10f (float @var{x})
510 @deftypefunx {long double} pow10l (long double @var{x})
511 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
512 These functions compute @code{10} raised to the power @var{x}.
513 Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
515 The @code{exp10} functions are from TS 18661-4:2015; the @code{pow10}
516 names are GNU extensions. The name @code{exp10} is
517 preferred, since it is analogous to @code{exp} and @code{exp2}.
523 @deftypefun double log (double @var{x})
526 @deftypefunx float logf (float @var{x})
529 @deftypefunx {long double} logl (long double @var{x})
530 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
531 These functions compute the natural logarithm of @var{x}. @code{exp (log
532 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
535 If @var{x} is negative, @code{log} signals a domain error. If @var{x}
536 is zero, it returns negative infinity; if @var{x} is too close to zero,
537 it may signal overflow.
542 @deftypefun double log10 (double @var{x})
545 @deftypefunx float log10f (float @var{x})
548 @deftypefunx {long double} log10l (long double @var{x})
549 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
550 These functions return the base-10 logarithm of @var{x}.
551 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
557 @deftypefun double log2 (double @var{x})
560 @deftypefunx float log2f (float @var{x})
563 @deftypefunx {long double} log2l (long double @var{x})
564 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
565 These functions return the base-2 logarithm of @var{x}.
566 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
571 @deftypefun double logb (double @var{x})
574 @deftypefunx float logbf (float @var{x})
577 @deftypefunx {long double} logbl (long double @var{x})
578 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
579 These functions extract the exponent of @var{x} and return it as a
580 floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal
581 to @code{floor (log2 (x))}, except it's probably faster.
583 If @var{x} is de-normalized, @code{logb} returns the exponent @var{x}
584 would have if it were normalized. If @var{x} is infinity (positive or
585 negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero,
586 @code{logb} returns @math{@infinity{}}. It does not signal.
591 @deftypefun int ilogb (double @var{x})
594 @deftypefunx int ilogbf (float @var{x})
597 @deftypefunx int ilogbl (long double @var{x})
600 @deftypefunx {long int} llogb (double @var{x})
603 @deftypefunx {long int} llogbf (float @var{x})
606 @deftypefunx {long int} llogbl (long double @var{x})
607 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
608 These functions are equivalent to the corresponding @code{logb}
609 functions except that they return signed integer values. The
610 @code{ilogb} functions are from ISO C99; the @code{llogb} functions
611 are from TS 18661-1:2014.
615 Since integers cannot represent infinity and NaN, @code{ilogb} instead
616 returns an integer that can't be the exponent of a normal floating-point
617 number. @file{math.h} defines constants so you can check for this.
621 @deftypevr Macro int FP_ILOGB0
622 @code{ilogb} returns this value if its argument is @code{0}. The
623 numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
625 This macro is defined in @w{ISO C99}.
630 @deftypevr Macro {long int} FP_LLOGB0
631 @code{llogb} returns this value if its argument is @code{0}. The
632 numeric value is either @code{LONG_MIN} or @code{-LONG_MAX}.
634 This macro is defined in TS 18661-1:2014.
639 @deftypevr Macro int FP_ILOGBNAN
640 @code{ilogb} returns this value if its argument is @code{NaN}. The
641 numeric value is either @code{INT_MIN} or @code{INT_MAX}.
643 This macro is defined in @w{ISO C99}.
648 @deftypevr Macro {long int} FP_LLOGBNAN
649 @code{llogb} returns this value if its argument is @code{NaN}. The
650 numeric value is either @code{LONG_MIN} or @code{LONG_MAX}.
652 This macro is defined in TS 18661-1:2014.
655 These values are system specific. They might even be the same. The
656 proper way to test the result of @code{ilogb} is as follows:
660 if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
664 /* @r{Handle NaN.} */
668 /* @r{Handle 0.0.} */
672 /* @r{Some other value with large exponent,}
680 @deftypefun double pow (double @var{base}, double @var{power})
683 @deftypefunx float powf (float @var{base}, float @var{power})
686 @deftypefunx {long double} powl (long double @var{base}, long double @var{power})
687 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
688 These are general exponentiation functions, returning @var{base} raised
691 Mathematically, @code{pow} would return a complex number when @var{base}
692 is negative and @var{power} is not an integral value. @code{pow} can't
693 do that, so instead it signals a domain error. @code{pow} may also
694 underflow or overflow the destination type.
697 @cindex square root function
700 @deftypefun double sqrt (double @var{x})
703 @deftypefunx float sqrtf (float @var{x})
706 @deftypefunx {long double} sqrtl (long double @var{x})
707 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
708 These functions return the nonnegative square root of @var{x}.
710 If @var{x} is negative, @code{sqrt} signals a domain error.
711 Mathematically, it should return a complex number.
714 @cindex cube root function
717 @deftypefun double cbrt (double @var{x})
720 @deftypefunx float cbrtf (float @var{x})
723 @deftypefunx {long double} cbrtl (long double @var{x})
724 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
725 These functions return the cube root of @var{x}. They cannot
726 fail; every representable real value has a representable real cube root.
731 @deftypefun double hypot (double @var{x}, double @var{y})
734 @deftypefunx float hypotf (float @var{x}, float @var{y})
737 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
738 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
739 These functions return @code{sqrt (@var{x}*@var{x} +
740 @var{y}*@var{y})}. This is the length of the hypotenuse of a right
741 triangle with sides of length @var{x} and @var{y}, or the distance
742 of the point (@var{x}, @var{y}) from the origin. Using this function
743 instead of the direct formula is wise, since the error is
744 much smaller. See also the function @code{cabs} in @ref{Absolute Value}.
749 @deftypefun double expm1 (double @var{x})
752 @deftypefunx float expm1f (float @var{x})
755 @deftypefunx {long double} expm1l (long double @var{x})
756 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
757 These functions return a value equivalent to @code{exp (@var{x}) - 1}.
758 They are computed in a way that is accurate even if @var{x} is
759 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing
760 to subtraction of two numbers that are nearly equal.
765 @deftypefun double log1p (double @var{x})
768 @deftypefunx float log1pf (float @var{x})
771 @deftypefunx {long double} log1pl (long double @var{x})
772 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
773 These functions return a value equivalent to @w{@code{log (1 + @var{x})}}.
774 They are computed in a way that is accurate even if @var{x} is
778 @cindex complex exponentiation functions
779 @cindex complex logarithm functions
781 @w{ISO C99} defines complex variants of some of the exponentiation and
786 @deftypefun {complex double} cexp (complex double @var{z})
789 @deftypefunx {complex float} cexpf (complex float @var{z})
792 @deftypefunx {complex long double} cexpl (complex long double @var{z})
793 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
794 These functions return @code{e} (the base of natural
795 logarithms) raised to the power of @var{z}.
796 Mathematically, this corresponds to the value
799 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
802 $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
808 @deftypefun {complex double} clog (complex double @var{z})
811 @deftypefunx {complex float} clogf (complex float @var{z})
814 @deftypefunx {complex long double} clogl (complex long double @var{z})
815 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
816 These functions return the natural logarithm of @var{z}.
817 Mathematically, this corresponds to the value
820 @math{log (z) = log (cabs (z)) + I * carg (z)}
823 $$\log(z) = \log |z| + i \arg z$$
827 @code{clog} has a pole at 0, and will signal overflow if @var{z} equals
828 or is very close to 0. It is well-defined for all other values of
835 @deftypefun {complex double} clog10 (complex double @var{z})
838 @deftypefunx {complex float} clog10f (complex float @var{z})
841 @deftypefunx {complex long double} clog10l (complex long double @var{z})
842 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
843 These functions return the base 10 logarithm of the complex value
844 @var{z}. Mathematically, this corresponds to the value
847 @math{log10 (z) = log10 (cabs (z)) + I * carg (z) / log (10)}
850 $$\log_{10}(z) = \log_{10}|z| + i \arg z / \log (10)$$
853 These functions are GNU extensions.
858 @deftypefun {complex double} csqrt (complex double @var{z})
861 @deftypefunx {complex float} csqrtf (complex float @var{z})
864 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
865 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
866 These functions return the complex square root of the argument @var{z}. Unlike
867 the real-valued functions, they are defined for all values of @var{z}.
872 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
875 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
878 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
879 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
880 These functions return @var{base} raised to the power of
881 @var{power}. This is equivalent to @w{@code{cexp (y * clog (x))}}
884 @node Hyperbolic Functions
885 @section Hyperbolic Functions
886 @cindex hyperbolic functions
888 The functions in this section are related to the exponential functions;
889 see @ref{Exponents and Logarithms}.
893 @deftypefun double sinh (double @var{x})
896 @deftypefunx float sinhf (float @var{x})
899 @deftypefunx {long double} sinhl (long double @var{x})
900 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
901 These functions return the hyperbolic sine of @var{x}, defined
902 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}. They
903 may signal overflow if @var{x} is too large.
908 @deftypefun double cosh (double @var{x})
911 @deftypefunx float coshf (float @var{x})
914 @deftypefunx {long double} coshl (long double @var{x})
915 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
916 These functions return the hyperbolic cosine of @var{x},
917 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
918 They may signal overflow if @var{x} is too large.
923 @deftypefun double tanh (double @var{x})
926 @deftypefunx float tanhf (float @var{x})
929 @deftypefunx {long double} tanhl (long double @var{x})
930 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
931 These functions return the hyperbolic tangent of @var{x},
932 defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
933 They may signal overflow if @var{x} is too large.
936 @cindex hyperbolic functions
938 There are counterparts for the hyperbolic functions which take
943 @deftypefun {complex double} csinh (complex double @var{z})
946 @deftypefunx {complex float} csinhf (complex float @var{z})
949 @deftypefunx {complex long double} csinhl (complex long double @var{z})
950 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
951 These functions return the complex hyperbolic sine of @var{z}, defined
952 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.
957 @deftypefun {complex double} ccosh (complex double @var{z})
960 @deftypefunx {complex float} ccoshf (complex float @var{z})
963 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
964 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
965 These functions return the complex hyperbolic cosine of @var{z}, defined
966 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.
971 @deftypefun {complex double} ctanh (complex double @var{z})
974 @deftypefunx {complex float} ctanhf (complex float @var{z})
977 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
978 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
979 These functions return the complex hyperbolic tangent of @var{z},
980 defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
984 @cindex inverse hyperbolic functions
988 @deftypefun double asinh (double @var{x})
991 @deftypefunx float asinhf (float @var{x})
994 @deftypefunx {long double} asinhl (long double @var{x})
995 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
996 These functions return the inverse hyperbolic sine of @var{x}---the
997 value whose hyperbolic sine is @var{x}.
1002 @deftypefun double acosh (double @var{x})
1005 @deftypefunx float acoshf (float @var{x})
1008 @deftypefunx {long double} acoshl (long double @var{x})
1009 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1010 These functions return the inverse hyperbolic cosine of @var{x}---the
1011 value whose hyperbolic cosine is @var{x}. If @var{x} is less than
1012 @code{1}, @code{acosh} signals a domain error.
1017 @deftypefun double atanh (double @var{x})
1020 @deftypefunx float atanhf (float @var{x})
1023 @deftypefunx {long double} atanhl (long double @var{x})
1024 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1025 These functions return the inverse hyperbolic tangent of @var{x}---the
1026 value whose hyperbolic tangent is @var{x}. If the absolute value of
1027 @var{x} is greater than @code{1}, @code{atanh} signals a domain error;
1028 if it is equal to 1, @code{atanh} returns infinity.
1031 @cindex inverse complex hyperbolic functions
1035 @deftypefun {complex double} casinh (complex double @var{z})
1038 @deftypefunx {complex float} casinhf (complex float @var{z})
1041 @deftypefunx {complex long double} casinhl (complex long double @var{z})
1042 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1043 These functions return the inverse complex hyperbolic sine of
1044 @var{z}---the value whose complex hyperbolic sine is @var{z}.
1049 @deftypefun {complex double} cacosh (complex double @var{z})
1052 @deftypefunx {complex float} cacoshf (complex float @var{z})
1055 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
1056 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1057 These functions return the inverse complex hyperbolic cosine of
1058 @var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike
1059 the real-valued functions, there are no restrictions on the value of @var{z}.
1064 @deftypefun {complex double} catanh (complex double @var{z})
1067 @deftypefunx {complex float} catanhf (complex float @var{z})
1070 @deftypefunx {complex long double} catanhl (complex long double @var{z})
1071 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1072 These functions return the inverse complex hyperbolic tangent of
1073 @var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike
1074 the real-valued functions, there are no restrictions on the value of
1078 @node Special Functions
1079 @section Special Functions
1080 @cindex special functions
1081 @cindex Bessel functions
1082 @cindex gamma function
1084 These are some more exotic mathematical functions which are sometimes
1085 useful. Currently they only have real-valued versions.
1089 @deftypefun double erf (double @var{x})
1092 @deftypefunx float erff (float @var{x})
1095 @deftypefunx {long double} erfl (long double @var{x})
1096 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1097 @code{erf} returns the error function of @var{x}. The error
1098 function is defined as
1100 $$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$
1104 erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
1111 @deftypefun double erfc (double @var{x})
1114 @deftypefunx float erfcf (float @var{x})
1117 @deftypefunx {long double} erfcl (long double @var{x})
1118 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1119 @code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
1120 fashion that avoids round-off error when @var{x} is large.
1125 @deftypefun double lgamma (double @var{x})
1128 @deftypefunx float lgammaf (float @var{x})
1131 @deftypefunx {long double} lgammal (long double @var{x})
1132 @safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}}
1133 @code{lgamma} returns the natural logarithm of the absolute value of
1134 the gamma function of @var{x}. The gamma function is defined as
1136 $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
1140 gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
1145 The sign of the gamma function is stored in the global variable
1146 @var{signgam}, which is declared in @file{math.h}. It is @code{1} if
1147 the intermediate result was positive or zero, or @code{-1} if it was
1150 To compute the real gamma function you can use the @code{tgamma}
1151 function or you can compute the values as follows:
1154 gam = signgam*exp(lgam);
1157 The gamma function has singularities at the non-positive integers.
1158 @code{lgamma} will raise the zero divide exception if evaluated at a
1164 @deftypefun double lgamma_r (double @var{x}, int *@var{signp})
1167 @deftypefunx float lgammaf_r (float @var{x}, int *@var{signp})
1170 @deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp})
1171 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1172 @code{lgamma_r} is just like @code{lgamma}, but it stores the sign of
1173 the intermediate result in the variable pointed to by @var{signp}
1174 instead of in the @var{signgam} global. This means it is reentrant.
1179 @deftypefun double gamma (double @var{x})
1182 @deftypefunx float gammaf (float @var{x})
1185 @deftypefunx {long double} gammal (long double @var{x})
1186 @safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}}
1187 These functions exist for compatibility reasons. They are equivalent to
1188 @code{lgamma} etc. It is better to use @code{lgamma} since for one the
1189 name reflects better the actual computation, and moreover @code{lgamma} is
1190 standardized in @w{ISO C99} while @code{gamma} is not.
1195 @deftypefun double tgamma (double @var{x})
1198 @deftypefunx float tgammaf (float @var{x})
1201 @deftypefunx {long double} tgammal (long double @var{x})
1202 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1203 @code{tgamma} applies the gamma function to @var{x}. The gamma
1204 function is defined as
1206 $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
1210 gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
1214 This function was introduced in @w{ISO C99}.
1219 @deftypefun double j0 (double @var{x})
1222 @deftypefunx float j0f (float @var{x})
1225 @deftypefunx {long double} j0l (long double @var{x})
1226 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1227 @code{j0} returns the Bessel function of the first kind of order 0 of
1228 @var{x}. It may signal underflow if @var{x} is too large.
1233 @deftypefun double j1 (double @var{x})
1236 @deftypefunx float j1f (float @var{x})
1239 @deftypefunx {long double} j1l (long double @var{x})
1240 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1241 @code{j1} returns the Bessel function of the first kind of order 1 of
1242 @var{x}. It may signal underflow if @var{x} is too large.
1247 @deftypefun double jn (int @var{n}, double @var{x})
1250 @deftypefunx float jnf (int @var{n}, float @var{x})
1253 @deftypefunx {long double} jnl (int @var{n}, long double @var{x})
1254 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1255 @code{jn} returns the Bessel function of the first kind of order
1256 @var{n} of @var{x}. It may signal underflow if @var{x} is too large.
1261 @deftypefun double y0 (double @var{x})
1264 @deftypefunx float y0f (float @var{x})
1267 @deftypefunx {long double} y0l (long double @var{x})
1268 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1269 @code{y0} returns the Bessel function of the second kind of order 0 of
1270 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
1271 is negative, @code{y0} signals a domain error; if it is zero,
1272 @code{y0} signals overflow and returns @math{-@infinity}.
1277 @deftypefun double y1 (double @var{x})
1280 @deftypefunx float y1f (float @var{x})
1283 @deftypefunx {long double} y1l (long double @var{x})
1284 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1285 @code{y1} returns the Bessel function of the second kind of order 1 of
1286 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
1287 is negative, @code{y1} signals a domain error; if it is zero,
1288 @code{y1} signals overflow and returns @math{-@infinity}.
1293 @deftypefun double yn (int @var{n}, double @var{x})
1296 @deftypefunx float ynf (int @var{n}, float @var{x})
1299 @deftypefunx {long double} ynl (int @var{n}, long double @var{x})
1300 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1301 @code{yn} returns the Bessel function of the second kind of order @var{n} of
1302 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
1303 is negative, @code{yn} signals a domain error; if it is zero,
1304 @code{yn} signals overflow and returns @math{-@infinity}.
1307 @node Errors in Math Functions
1308 @section Known Maximum Errors in Math Functions
1312 This section lists the known errors of the functions in the math
1313 library. Errors are measured in ``units of the last place''. This is a
1314 measure for the relative error. For a number @math{z} with the
1315 representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE
1316 floating-point numbers with base 2) the ULP is represented by
1319 $${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$
1323 |d.d...d - (z / 2^e)| / 2^(p - 1)
1328 where @math{p} is the number of bits in the mantissa of the
1329 floating-point number representation. Ideally the error for all
1330 functions is always less than 0.5ulps in round-to-nearest mode. Using
1331 rounding bits this is also
1332 possible and normally implemented for the basic operations. Except
1333 for certain functions such as @code{sqrt}, @code{fma} and @code{rint}
1334 whose results are fully specified by reference to corresponding IEEE
1335 754 floating-point operations, and conversions between strings and
1336 floating point, @theglibc{} does not aim for correctly rounded results
1337 for functions in the math library, and does not aim for correctness in
1338 whether ``inexact'' exceptions are raised. Instead, the goals for
1339 accuracy of functions without fully specified results are as follows;
1340 some functions have bugs meaning they do not meet these goals in all
1341 cases. In the future, @theglibc{} may provide some other correctly
1342 rounding functions under the names such as @code{crsin} proposed for
1343 an extension to ISO C.
1348 Each function with a floating-point result behaves as if it computes
1349 an infinite-precision result that is within a few ulp (in both real
1350 and complex parts, for functions with complex results) of the
1351 mathematically correct value of the function (interpreted together
1352 with ISO C or POSIX semantics for the function in question) at the
1353 exact value passed as the input. Exceptions are raised appropriately
1354 for this value and in accordance with IEEE 754 / ISO C / POSIX
1355 semantics, and it is then rounded according to the current rounding
1356 direction to the result that is returned to the user. @code{errno}
1357 may also be set (@pxref{Math Error Reporting}). (The ``inexact''
1358 exception may be raised, or not raised, even if this is inconsistent
1359 with the infinite-precision value.)
1362 For the IBM @code{long double} format, as used on PowerPC GNU/Linux,
1363 the accuracy goal is weaker for input values not exactly representable
1364 in 106 bits of precision; it is as if the input value is some value
1365 within 0.5ulp of the value actually passed, where ``ulp'' is
1366 interpreted in terms of a fixed-precision 106-bit mantissa, but not
1367 necessarily the exact value actually passed with discontiguous
1371 For the IBM @code{long double} format, functions whose results are
1372 fully specified by reference to corresponding IEEE 754 floating-point
1373 operations have the same accuracy goals as other functions, but with
1374 the error bound being the same as that for division (3ulp).
1375 Furthermore, ``inexact'' and ``underflow'' exceptions may be raised
1376 for all functions for any inputs, even where such exceptions are
1377 inconsistent with the returned value, since the underlying
1378 floating-point arithmetic has that property.
1381 Functions behave as if the infinite-precision result computed is zero,
1382 infinity or NaN if and only if that is the mathematically correct
1383 infinite-precision result. They behave as if the infinite-precision
1384 result computed always has the same sign as the mathematically correct
1388 If the mathematical result is more than a few ulp above the overflow
1389 threshold for the current rounding direction, the value returned is
1390 the appropriate overflow value for the current rounding direction,
1391 with the overflow exception raised.
1394 If the mathematical result has magnitude well below half the least
1395 subnormal magnitude, the returned value is either zero or the least
1396 subnormal (in each case, with the correct sign), according to the
1397 current rounding direction and with the underflow exception raised.
1400 Where the mathematical result underflows (before rounding) and is not
1401 exactly representable as a floating-point value, the function does not
1402 behave as if the computed infinite-precision result is an exact value
1403 in the subnormal range. This means that the underflow exception is
1404 raised other than possibly for cases where the mathematical result is
1405 very close to the underflow threshold and the function behaves as if
1406 it computes an infinite-precision result that does not underflow. (So
1407 there may be spurious underflow exceptions in cases where the
1408 underflowing result is exact, but not missing underflow exceptions in
1409 cases where it is inexact.)
1412 @Theglibc{} does not aim for functions to satisfy other properties of
1413 the underlying mathematical function, such as monotonicity, where not
1414 implied by the above goals.
1417 All the above applies to both real and complex parts, for complex
1422 Therefore many of the functions in the math library have errors. The
1423 table lists the maximum error for each function which is exposed by one
1424 of the existing tests in the test suite. The table tries to cover as much
1425 as possible and list the actual maximum error (or at least a ballpark
1426 figure) but this is often not achieved due to the large search space.
1428 The table lists the ULP values for different architectures. Different
1429 architectures have different results since their hardware support for
1430 floating-point operations varies and also the existing hardware support
1431 is different. Only the round-to-nearest rounding mode is covered by
1432 this table, and vector versions of functions are not covered.
1433 Functions not listed do not have known errors.
1436 @c This multitable does not fit on a single page
1437 @include libm-err.texi
1439 @node Pseudo-Random Numbers
1440 @section Pseudo-Random Numbers
1441 @cindex random numbers
1442 @cindex pseudo-random numbers
1443 @cindex seed (for random numbers)
1445 This section describes the GNU facilities for generating a series of
1446 pseudo-random numbers. The numbers generated are not truly random;
1447 typically, they form a sequence that repeats periodically, with a period
1448 so large that you can ignore it for ordinary purposes. The random
1449 number generator works by remembering a @dfn{seed} value which it uses
1450 to compute the next random number and also to compute a new seed.
1452 Although the generated numbers look unpredictable within one run of a
1453 program, the sequence of numbers is @emph{exactly the same} from one run
1454 to the next. This is because the initial seed is always the same. This
1455 is convenient when you are debugging a program, but it is unhelpful if
1456 you want the program to behave unpredictably. If you want a different
1457 pseudo-random series each time your program runs, you must specify a
1458 different seed each time. For ordinary purposes, basing the seed on the
1459 current time works well. For random numbers in cryptography,
1460 @pxref{Unpredictable Bytes}.
1462 You can obtain repeatable sequences of numbers on a particular machine type
1463 by specifying the same initial seed value for the random number
1464 generator. There is no standard meaning for a particular seed value;
1465 the same seed, used in different C libraries or on different CPU types,
1466 will give you different random numbers.
1468 @Theglibc{} supports the standard @w{ISO C} random number functions
1469 plus two other sets derived from BSD and SVID. The BSD and @w{ISO C}
1470 functions provide identical, somewhat limited functionality. If only a
1471 small number of random bits are required, we recommend you use the
1472 @w{ISO C} interface, @code{rand} and @code{srand}. The SVID functions
1473 provide a more flexible interface, which allows better random number
1474 generator algorithms, provides more random bits (up to 48) per call, and
1475 can provide random floating-point numbers. These functions are required
1476 by the XPG standard and therefore will be present in all modern Unix
1480 * ISO Random:: @code{rand} and friends.
1481 * BSD Random:: @code{random} and friends.
1482 * SVID Random:: @code{drand48} and friends.
1486 @subsection ISO C Random Number Functions
1488 This section describes the random number functions that are part of
1489 the @w{ISO C} standard.
1491 To use these facilities, you should include the header file
1492 @file{stdlib.h} in your program.
1497 @deftypevr Macro int RAND_MAX
1498 The value of this macro is an integer constant representing the largest
1499 value the @code{rand} function can return. In @theglibc{}, it is
1500 @code{2147483647}, which is the largest signed integer representable in
1501 32 bits. In other libraries, it may be as low as @code{32767}.
1506 @deftypefun int rand (void)
1507 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1508 @c Just calls random.
1509 The @code{rand} function returns the next pseudo-random number in the
1510 series. The value ranges from @code{0} to @code{RAND_MAX}.
1515 @deftypefun void srand (unsigned int @var{seed})
1516 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1517 @c Alias to srandom.
1518 This function establishes @var{seed} as the seed for a new series of
1519 pseudo-random numbers. If you call @code{rand} before a seed has been
1520 established with @code{srand}, it uses the value @code{1} as a default
1523 To produce a different pseudo-random series each time your program is
1524 run, do @code{srand (time (0))}.
1527 POSIX.1 extended the C standard functions to support reproducible random
1528 numbers in multi-threaded programs. However, the extension is badly
1529 designed and unsuitable for serious work.
1533 @deftypefun int rand_r (unsigned int *@var{seed})
1534 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1535 This function returns a random number in the range 0 to @code{RAND_MAX}
1536 just as @code{rand} does. However, all its state is stored in the
1537 @var{seed} argument. This means the RNG's state can only have as many
1538 bits as the type @code{unsigned int} has. This is far too few to
1541 If your program requires a reentrant RNG, we recommend you use the
1542 reentrant GNU extensions to the SVID random number generator. The
1543 POSIX.1 interface should only be used when the GNU extensions are not
1549 @subsection BSD Random Number Functions
1551 This section describes a set of random number generation functions that
1552 are derived from BSD. There is no advantage to using these functions
1553 with @theglibc{}; we support them for BSD compatibility only.
1555 The prototypes for these functions are in @file{stdlib.h}.
1560 @deftypefun {long int} random (void)
1561 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1562 @c Takes a lock and calls random_r with an automatic variable and the
1563 @c global state, while holding a lock.
1564 This function returns the next pseudo-random number in the sequence.
1565 The value returned ranges from @code{0} to @code{2147483647}.
1567 @strong{NB:} Temporarily this function was defined to return a
1568 @code{int32_t} value to indicate that the return value always contains
1569 32 bits even if @code{long int} is wider. The standard demands it
1570 differently. Users must always be aware of the 32-bit limitation,
1576 @deftypefun void srandom (unsigned int @var{seed})
1577 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1578 @c Takes a lock and calls srandom_r with an automatic variable and a
1579 @c static buffer. There's no MT-safety issue because the static buffer
1580 @c is internally protected by a lock, although other threads may modify
1581 @c the set state before it is used.
1582 The @code{srandom} function sets the state of the random number
1583 generator based on the integer @var{seed}. If you supply a @var{seed} value
1584 of @code{1}, this will cause @code{random} to reproduce the default set
1587 To produce a different set of pseudo-random numbers each time your
1588 program runs, do @code{srandom (time (0))}.
1593 @deftypefun {char *} initstate (unsigned int @var{seed}, char *@var{state}, size_t @var{size})
1594 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1595 The @code{initstate} function is used to initialize the random number
1596 generator state. The argument @var{state} is an array of @var{size}
1597 bytes, used to hold the state information. It is initialized based on
1598 @var{seed}. The size must be between 8 and 256 bytes, and should be a
1599 power of two. The bigger the @var{state} array, the better.
1601 The return value is the previous value of the state information array.
1602 You can use this value later as an argument to @code{setstate} to
1608 @deftypefun {char *} setstate (char *@var{state})
1609 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1610 The @code{setstate} function restores the random number state
1611 information @var{state}. The argument must have been the result of
1612 a previous call to @var{initstate} or @var{setstate}.
1614 The return value is the previous value of the state information array.
1615 You can use this value later as an argument to @code{setstate} to
1618 If the function fails the return value is @code{NULL}.
1621 The four functions described so far in this section all work on a state
1622 which is shared by all threads. The state is not directly accessible to
1623 the user and can only be modified by these functions. This makes it
1624 hard to deal with situations where each thread should have its own
1625 pseudo-random number generator.
1627 @Theglibc{} contains four additional functions which contain the
1628 state as an explicit parameter and therefore make it possible to handle
1629 thread-local PRNGs. Besides this there is no difference. In fact, the
1630 four functions already discussed are implemented internally using the
1631 following interfaces.
1633 The @file{stdlib.h} header contains a definition of the following type:
1637 @deftp {Data Type} {struct random_data}
1639 Objects of type @code{struct random_data} contain the information
1640 necessary to represent the state of the PRNG. Although a complete
1641 definition of the type is present the type should be treated as opaque.
1644 The functions modifying the state follow exactly the already described
1649 @deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result})
1650 @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
1651 The @code{random_r} function behaves exactly like the @code{random}
1652 function except that it uses and modifies the state in the object
1653 pointed to by the first parameter instead of the global state.
1658 @deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf})
1659 @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
1660 The @code{srandom_r} function behaves exactly like the @code{srandom}
1661 function except that it uses and modifies the state in the object
1662 pointed to by the second parameter instead of the global state.
1667 @deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf})
1668 @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
1669 The @code{initstate_r} function behaves exactly like the @code{initstate}
1670 function except that it uses and modifies the state in the object
1671 pointed to by the fourth parameter instead of the global state.
1676 @deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf})
1677 @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
1678 The @code{setstate_r} function behaves exactly like the @code{setstate}
1679 function except that it uses and modifies the state in the object
1680 pointed to by the first parameter instead of the global state.
1684 @subsection SVID Random Number Function
1686 The C library on SVID systems contains yet another kind of random number
1687 generator functions. They use a state of 48 bits of data. The user can
1688 choose among a collection of functions which return the random bits
1691 Generally there are two kinds of function. The first uses a state of
1692 the random number generator which is shared among several functions and
1693 by all threads of the process. The second requires the user to handle
1696 All functions have in common that they use the same congruential
1697 formula with the same constants. The formula is
1700 Y = (a * X + c) mod m
1704 where @var{X} is the state of the generator at the beginning and
1705 @var{Y} the state at the end. @code{a} and @code{c} are constants
1706 determining the way the generator works. By default they are
1709 a = 0x5DEECE66D = 25214903917
1714 but they can also be changed by the user. @code{m} is of course 2^48
1715 since the state consists of a 48-bit array.
1717 The prototypes for these functions are in @file{stdlib.h}.
1723 @deftypefun double drand48 (void)
1724 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1725 @c Uses of the static state buffer are not guarded by a lock (thus
1726 @c @mtasurace:drand48), so they may be found or left at a
1727 @c partially-updated state in case of calls from within signal handlers
1728 @c or cancellation. None of this will break safety rules or invoke
1729 @c undefined behavior, but it may affect randomness.
1730 This function returns a @code{double} value in the range of @code{0.0}
1731 to @code{1.0} (exclusive). The random bits are determined by the global
1732 state of the random number generator in the C library.
1734 Since the @code{double} type according to @w{IEEE 754} has a 52-bit
1735 mantissa this means 4 bits are not initialized by the random number
1736 generator. These are (of course) chosen to be the least significant
1737 bits and they are initialized to @code{0}.
1742 @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
1743 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1744 @c The static buffer is just initialized with default parameters, which
1745 @c are later read to advance the state held in xsubi.
1746 This function returns a @code{double} value in the range of @code{0.0}
1747 to @code{1.0} (exclusive), similarly to @code{drand48}. The argument is
1748 an array describing the state of the random number generator.
1750 This function can be called subsequently since it updates the array to
1751 guarantee random numbers. The array should have been initialized before
1752 initial use to obtain reproducible results.
1757 @deftypefun {long int} lrand48 (void)
1758 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1759 The @code{lrand48} function returns an integer value in the range of
1760 @code{0} to @code{2^31} (exclusive). Even if the size of the @code{long
1761 int} type can take more than 32 bits, no higher numbers are returned.
1762 The random bits are determined by the global state of the random number
1763 generator in the C library.
1768 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
1769 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1770 This function is similar to the @code{lrand48} function in that it
1771 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1772 the state of the random number generator used to produce the random bits
1773 is determined by the array provided as the parameter to the function.
1775 The numbers in the array are updated afterwards so that subsequent calls
1776 to this function yield different results (as is expected of a random
1777 number generator). The array should have been initialized before the
1778 first call to obtain reproducible results.
1783 @deftypefun {long int} mrand48 (void)
1784 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1785 The @code{mrand48} function is similar to @code{lrand48}. The only
1786 difference is that the numbers returned are in the range @code{-2^31} to
1787 @code{2^31} (exclusive).
1792 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
1793 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1794 The @code{jrand48} function is similar to @code{nrand48}. The only
1795 difference is that the numbers returned are in the range @code{-2^31} to
1796 @code{2^31} (exclusive). For the @code{xsubi} parameter the same
1797 requirements are necessary.
1800 The internal state of the random number generator can be initialized in
1801 several ways. The methods differ in the completeness of the
1802 information provided.
1806 @deftypefun void srand48 (long int @var{seedval})
1807 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1808 The @code{srand48} function sets the most significant 32 bits of the
1809 internal state of the random number generator to the least
1810 significant 32 bits of the @var{seedval} parameter. The lower 16 bits
1811 are initialized to the value @code{0x330E}. Even if the @code{long
1812 int} type contains more than 32 bits only the lower 32 bits are used.
1814 Owing to this limitation, initialization of the state of this
1815 function is not very useful. But it makes it easy to use a construct
1816 like @code{srand48 (time (0))}.
1818 A side-effect of this function is that the values @code{a} and @code{c}
1819 from the internal state, which are used in the congruential formula,
1820 are reset to the default values given above. This is of importance once
1821 the user has called the @code{lcong48} function (see below).
1826 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
1827 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1828 The @code{seed48} function initializes all 48 bits of the state of the
1829 internal random number generator from the contents of the parameter
1830 @var{seed16v}. Here the lower 16 bits of the first element of
1831 @var{seed16v} initialize the least significant 16 bits of the internal
1832 state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
1833 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
1834 initialize the most significant 16 bits of the state.
1836 Unlike @code{srand48} this function lets the user initialize all 48 bits
1839 The value returned by @code{seed48} is a pointer to an array containing
1840 the values of the internal state before the change. This might be
1841 useful to restart the random number generator at a certain state.
1842 Otherwise the value can simply be ignored.
1844 As for @code{srand48}, the values @code{a} and @code{c} from the
1845 congruential formula are reset to the default values.
1848 There is one more function to initialize the random number generator
1849 which enables you to specify even more information by allowing you to
1850 change the parameters in the congruential formula.
1854 @deftypefun void lcong48 (unsigned short int @var{param}[7])
1855 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1856 The @code{lcong48} function allows the user to change the complete state
1857 of the random number generator. Unlike @code{srand48} and
1858 @code{seed48}, this function also changes the constants in the
1859 congruential formula.
1861 From the seven elements in the array @var{param} the least significant
1862 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
1863 determine the initial state, the least significant 16 bits of
1864 @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
1865 constant @code{a} and @code{@var{param}[6]} determines the 16-bit value
1869 All the above functions have in common that they use the global
1870 parameters for the congruential formula. In multi-threaded programs it
1871 might sometimes be useful to have different parameters in different
1872 threads. For this reason all the above functions have a counterpart
1873 which works on a description of the random number generator in the
1874 user-supplied buffer instead of the global state.
1876 Please note that it is no problem if several threads use the global
1877 state if all threads use the functions which take a pointer to an array
1878 containing the state. The random numbers are computed following the
1879 same loop but if the state in the array is different all threads will
1880 obtain an individual random number generator.
1882 The user-supplied buffer must be of type @code{struct drand48_data}.
1883 This type should be regarded as opaque and not manipulated directly.
1887 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1888 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1889 This function is equivalent to the @code{drand48} function with the
1890 difference that it does not modify the global random number generator
1891 parameters but instead the parameters in the buffer supplied through the
1892 pointer @var{buffer}. The random number is returned in the variable
1893 pointed to by @var{result}.
1895 The return value of the function indicates whether the call succeeded.
1896 If the value is less than @code{0} an error occurred and @var{errno} is
1897 set to indicate the problem.
1899 This function is a GNU extension and should not be used in portable
1905 @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
1906 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1907 The @code{erand48_r} function works like @code{erand48}, but in addition
1908 it takes an argument @var{buffer} which describes the random number
1909 generator. The state of the random number generator is taken from the
1910 @code{xsubi} array, the parameters for the congruential formula from the
1911 global random number generator data. The random number is returned in
1912 the variable pointed to by @var{result}.
1914 The return value is non-negative if the call succeeded.
1916 This function is a GNU extension and should not be used in portable
1922 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
1923 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1924 This function is similar to @code{lrand48}, but in addition it takes a
1925 pointer to a buffer describing the state of the random number generator
1926 just like @code{drand48}.
1928 If the return value of the function is non-negative the variable pointed
1929 to by @var{result} contains the result. Otherwise an error occurred.
1931 This function is a GNU extension and should not be used in portable
1937 @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1938 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1939 The @code{nrand48_r} function works like @code{nrand48} in that it
1940 produces a random number in the range @code{0} to @code{2^31}. But instead
1941 of using the global parameters for the congruential formula it uses the
1942 information from the buffer pointed to by @var{buffer}. The state is
1943 described by the values in @var{xsubi}.
1945 If the return value is non-negative the variable pointed to by
1946 @var{result} contains the result.
1948 This function is a GNU extension and should not be used in portable
1954 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
1955 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1956 This function is similar to @code{mrand48} but like the other reentrant
1957 functions it uses the random number generator described by the value in
1958 the buffer pointed to by @var{buffer}.
1960 If the return value is non-negative the variable pointed to by
1961 @var{result} contains the result.
1963 This function is a GNU extension and should not be used in portable
1969 @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1970 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1971 The @code{jrand48_r} function is similar to @code{jrand48}. Like the
1972 other reentrant functions of this function family it uses the
1973 congruential formula parameters from the buffer pointed to by
1976 If the return value is non-negative the variable pointed to by
1977 @var{result} contains the result.
1979 This function is a GNU extension and should not be used in portable
1983 Before any of the above functions are used the buffer of type
1984 @code{struct drand48_data} should be initialized. The easiest way to do
1985 this is to fill the whole buffer with null bytes, e.g. by
1988 memset (buffer, '\0', sizeof (struct drand48_data));
1992 Using any of the reentrant functions of this family now will
1993 automatically initialize the random number generator to the default
1994 values for the state and the parameters of the congruential formula.
1996 The other possibility is to use any of the functions which explicitly
1997 initialize the buffer. Though it might be obvious how to initialize the
1998 buffer from looking at the parameter to the function, it is highly
1999 recommended to use these functions since the result might not always be
2004 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
2005 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
2006 The description of the random number generator represented by the
2007 information in @var{buffer} is initialized similarly to what the function
2008 @code{srand48} does. The state is initialized from the parameter
2009 @var{seedval} and the parameters for the congruential formula are
2010 initialized to their default values.
2012 If the return value is non-negative the function call succeeded.
2014 This function is a GNU extension and should not be used in portable
2020 @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
2021 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
2022 This function is similar to @code{srand48_r} but like @code{seed48} it
2023 initializes all 48 bits of the state from the parameter @var{seed16v}.
2025 If the return value is non-negative the function call succeeded. It
2026 does not return a pointer to the previous state of the random number
2027 generator like the @code{seed48} function does. If the user wants to
2028 preserve the state for a later re-run s/he can copy the whole buffer
2029 pointed to by @var{buffer}.
2031 This function is a GNU extension and should not be used in portable
2037 @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
2038 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
2039 This function initializes all aspects of the random number generator
2040 described in @var{buffer} with the data in @var{param}. Here it is
2041 especially true that the function does more than just copying the
2042 contents of @var{param} and @var{buffer}. More work is required and
2043 therefore it is important to use this function rather than initializing
2044 the random number generator directly.
2046 If the return value is non-negative the function call succeeded.
2048 This function is a GNU extension and should not be used in portable
2052 @node FP Function Optimizations
2053 @section Is Fast Code or Small Code preferred?
2054 @cindex Optimization
2056 If an application uses many floating point functions it is often the case
2057 that the cost of the function calls themselves is not negligible.
2058 Modern processors can often execute the operations themselves
2059 very fast, but the function call disrupts the instruction pipeline.
2061 For this reason @theglibc{} provides optimizations for many of the
2062 frequently-used math functions. When GNU CC is used and the user
2063 activates the optimizer, several new inline functions and macros are
2064 defined. These new functions and macros have the same names as the
2065 library functions and so are used instead of the latter. In the case of
2066 inline functions the compiler will decide whether it is reasonable to
2067 use them, and this decision is usually correct.
2069 This means that no calls to the library functions may be necessary, and
2070 can increase the speed of generated code significantly. The drawback is
2071 that code size will increase, and the increase is not always negligible.
2073 There are two kinds of inline functions: those that give the same result
2074 as the library functions and others that might not set @code{errno} and
2075 might have a reduced precision and/or argument range in comparison with
2076 the library functions. The latter inline functions are only available
2077 if the flag @code{-ffast-math} is given to GNU CC.
2079 In cases where the inline functions and macros are not wanted the symbol
2080 @code{__NO_MATH_INLINES} should be defined before any system header is
2081 included. This will ensure that only library functions are used. Of
2082 course, it can be determined for each file in the project whether
2083 giving this option is preferable or not.
2085 Not all hardware implements the entire @w{IEEE 754} standard, and even
2086 if it does there may be a substantial performance penalty for using some
2087 of its features. For example, enabling traps on some processors forces
2088 the FPU to run un-pipelined, which can more than double calculation time.
2089 @c ***Add explanation of -lieee, -mieee.