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}.
57 * Mathematical Constants:: Precise numeric values for often-used
59 * Trig Functions:: Sine, cosine, tangent, and friends.
60 * Inverse Trig Functions:: Arcsine, arccosine, etc.
61 * Exponents and Logarithms:: Also pow and sqrt.
62 * Hyperbolic Functions:: sinh, cosh, tanh, etc.
63 * Special Functions:: Bessel, gamma, erf.
64 * Errors in Math Functions:: Known Maximum Errors in Math Functions.
65 * Pseudo-Random Numbers:: Functions for generating pseudo-random
67 * FP Function Optimizations:: Fast code or small code.
70 @node Mathematical Constants
71 @section Predefined Mathematical Constants
73 @cindex mathematical constants
75 The header @file{math.h} defines several useful mathematical constants.
76 All values are defined as preprocessor macros starting with @code{M_}.
77 The values provided are:
81 The base of natural logarithms.
83 The logarithm to base @code{2} of @code{M_E}.
85 The logarithm to base @code{10} of @code{M_E}.
87 The natural logarithm of @code{2}.
89 The natural logarithm of @code{10}.
91 Pi, the ratio of a circle's circumference to its diameter.
97 The reciprocal of pi (1/pi)
99 Two times the reciprocal of pi.
101 Two times the reciprocal of the square root of pi.
103 The square root of two.
105 The reciprocal of the square root of two (also the square root of 1/2).
108 These constants come from the Unix98 standard and were also available in
109 4.4BSD; therefore they are only defined if
110 @code{_XOPEN_SOURCE=500}, or a more general feature select macro, is
111 defined. The default set of features includes these constants.
112 @xref{Feature Test Macros}.
114 All values are of type @code{double}. As an extension, @theglibc{}
115 also defines these constants with type @code{long double}. The
116 @code{long double} macros have a lowercase @samp{l} appended to their
117 names: @code{M_El}, @code{M_PIl}, and so forth. These are only
118 available if @code{_GNU_SOURCE} is defined.
121 @emph{Note:} Some programs use a constant named @code{PI} which has the
122 same value as @code{M_PI}. This constant is not standard; it may have
123 appeared in some old AT&T headers, and is mentioned in Stroustrup's book
124 on C++. It infringes on the user's name space, so @theglibc{}
125 does not define it. Fixing programs written to expect it is simple:
126 replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI}
127 on the compiler command line.
130 @section Trigonometric Functions
131 @cindex trigonometric functions
133 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
134 The arguments to all of these functions are in units of radians; recall
135 that pi radians equals 180 degrees.
137 @cindex pi (trigonometric constant)
138 The math library normally defines @code{M_PI} to a @code{double}
139 approximation of pi. If strict ISO and/or POSIX compliance
140 are requested this constant is not defined, but you can easily define it
144 #define M_PI 3.14159265358979323846264338327
148 You can also compute the value of pi with the expression @code{acos
153 @deftypefun double sin (double @var{x})
156 @deftypefunx float sinf (float @var{x})
159 @deftypefunx {long double} sinl (long double @var{x})
160 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
161 These functions return the sine of @var{x}, where @var{x} is given in
162 radians. The return value is in the range @code{-1} to @code{1}.
167 @deftypefun double cos (double @var{x})
170 @deftypefunx float cosf (float @var{x})
173 @deftypefunx {long double} cosl (long double @var{x})
174 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
175 These functions return the cosine of @var{x}, where @var{x} is given in
176 radians. The return value is in the range @code{-1} to @code{1}.
181 @deftypefun double tan (double @var{x})
184 @deftypefunx float tanf (float @var{x})
187 @deftypefunx {long double} tanl (long double @var{x})
188 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
189 These functions return the tangent of @var{x}, where @var{x} is given in
192 Mathematically, the tangent function has singularities at odd multiples
193 of pi/2. If the argument @var{x} is too close to one of these
194 singularities, @code{tan} will signal overflow.
197 In many applications where @code{sin} and @code{cos} are used, the sine
198 and cosine of the same angle are needed at the same time. It is more
199 efficient to compute them simultaneously, so the library provides a
204 @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
207 @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
210 @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
211 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
212 These functions return the sine of @var{x} in @code{*@var{sinx}} and the
213 cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
214 radians. Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
215 the range of @code{-1} to @code{1}.
217 This function is a GNU extension. Portable programs should be prepared
218 to cope with its absence.
221 @cindex complex trigonometric functions
223 @w{ISO C99} defines variants of the trig functions which work on
224 complex numbers. @Theglibc{} provides these functions, but they
225 are only useful if your compiler supports the new complex types defined
227 @c XXX Change this when gcc is fixed. -zw
228 (As of this writing GCC supports complex numbers, but there are bugs in
233 @deftypefun {complex double} csin (complex double @var{z})
236 @deftypefunx {complex float} csinf (complex float @var{z})
239 @deftypefunx {complex long double} csinl (complex long double @var{z})
240 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
241 @c There are calls to nan* that could trigger @mtslocale if they didn't get
243 These functions return the complex sine of @var{z}.
244 The mathematical definition of the complex sine is
247 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
250 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
256 @deftypefun {complex double} ccos (complex double @var{z})
259 @deftypefunx {complex float} ccosf (complex float @var{z})
262 @deftypefunx {complex long double} ccosl (complex long double @var{z})
263 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
264 These functions return the complex cosine of @var{z}.
265 The mathematical definition of the complex cosine is
268 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
271 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
277 @deftypefun {complex double} ctan (complex double @var{z})
280 @deftypefunx {complex float} ctanf (complex float @var{z})
283 @deftypefunx {complex long double} ctanl (complex long double @var{z})
284 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
285 These functions return the complex tangent of @var{z}.
286 The mathematical definition of the complex tangent is
289 @math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
292 $$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
296 The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an
297 integer. @code{ctan} may signal overflow if @var{z} is too close to a
302 @node Inverse Trig Functions
303 @section Inverse Trigonometric Functions
304 @cindex inverse trigonometric functions
306 These are the usual arc sine, arc cosine and arc tangent functions,
307 which are the inverses of the sine, cosine and tangent functions
312 @deftypefun double asin (double @var{x})
315 @deftypefunx float asinf (float @var{x})
318 @deftypefunx {long double} asinl (long double @var{x})
319 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
320 These functions compute the arc sine of @var{x}---that is, the value whose
321 sine is @var{x}. The value is in units of radians. Mathematically,
322 there are infinitely many such values; the one actually returned is the
323 one between @code{-pi/2} and @code{pi/2} (inclusive).
325 The arc sine function is defined mathematically only
326 over the domain @code{-1} to @code{1}. If @var{x} is outside the
327 domain, @code{asin} signals a domain error.
332 @deftypefun double acos (double @var{x})
335 @deftypefunx float acosf (float @var{x})
338 @deftypefunx {long double} acosl (long double @var{x})
339 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
340 These functions compute the arc cosine of @var{x}---that is, the value
341 whose cosine is @var{x}. The value is in units of radians.
342 Mathematically, there are infinitely many such values; the one actually
343 returned is the one between @code{0} and @code{pi} (inclusive).
345 The arc cosine function is defined mathematically only
346 over the domain @code{-1} to @code{1}. If @var{x} is outside the
347 domain, @code{acos} signals a domain error.
352 @deftypefun double atan (double @var{x})
355 @deftypefunx float atanf (float @var{x})
358 @deftypefunx {long double} atanl (long double @var{x})
359 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
360 These functions compute the arc tangent of @var{x}---that is, the value
361 whose tangent is @var{x}. The value is in units of radians.
362 Mathematically, there are infinitely many such values; the one actually
363 returned is the one between @code{-pi/2} and @code{pi/2} (inclusive).
368 @deftypefun double atan2 (double @var{y}, double @var{x})
371 @deftypefunx float atan2f (float @var{y}, float @var{x})
374 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
375 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
376 This function computes the arc tangent of @var{y}/@var{x}, but the signs
377 of both arguments are used to determine the quadrant of the result, and
378 @var{x} is permitted to be zero. The return value is given in radians
379 and is in the range @code{-pi} to @code{pi}, inclusive.
381 If @var{x} and @var{y} are coordinates of a point in the plane,
382 @code{atan2} returns the signed angle between the line from the origin
383 to that point and the x-axis. Thus, @code{atan2} is useful for
384 converting Cartesian coordinates to polar coordinates. (To compute the
385 radial coordinate, use @code{hypot}; see @ref{Exponents and
388 @c This is experimentally true. Should it be so? -zw
389 If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
392 @cindex inverse complex trigonometric functions
393 @w{ISO C99} defines complex versions of the inverse trig functions.
397 @deftypefun {complex double} casin (complex double @var{z})
400 @deftypefunx {complex float} casinf (complex float @var{z})
403 @deftypefunx {complex long double} casinl (complex long double @var{z})
404 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
405 These functions compute the complex arc sine of @var{z}---that is, the
406 value whose sine is @var{z}. The value returned is in radians.
408 Unlike the real-valued functions, @code{casin} is defined for all
414 @deftypefun {complex double} cacos (complex double @var{z})
417 @deftypefunx {complex float} cacosf (complex float @var{z})
420 @deftypefunx {complex long double} cacosl (complex long double @var{z})
421 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
422 These functions compute the complex arc cosine of @var{z}---that is, the
423 value whose cosine is @var{z}. The value returned is in radians.
425 Unlike the real-valued functions, @code{cacos} is defined for all
432 @deftypefun {complex double} catan (complex double @var{z})
435 @deftypefunx {complex float} catanf (complex float @var{z})
438 @deftypefunx {complex long double} catanl (complex long double @var{z})
439 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
440 These functions compute the complex arc tangent of @var{z}---that is,
441 the value whose tangent is @var{z}. The value is in units of radians.
445 @node Exponents and Logarithms
446 @section Exponentiation and Logarithms
447 @cindex exponentiation functions
448 @cindex power functions
449 @cindex logarithm functions
453 @deftypefun double exp (double @var{x})
456 @deftypefunx float expf (float @var{x})
459 @deftypefunx {long double} expl (long double @var{x})
460 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
461 These functions compute @code{e} (the base of natural logarithms) raised
462 to the power @var{x}.
464 If the magnitude of the result is too large to be representable,
465 @code{exp} signals overflow.
470 @deftypefun double exp2 (double @var{x})
473 @deftypefunx float exp2f (float @var{x})
476 @deftypefunx {long double} exp2l (long double @var{x})
477 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
478 These functions compute @code{2} raised to the power @var{x}.
479 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
484 @deftypefun double exp10 (double @var{x})
487 @deftypefunx float exp10f (float @var{x})
490 @deftypefunx {long double} exp10l (long double @var{x})
493 @deftypefunx double pow10 (double @var{x})
496 @deftypefunx float pow10f (float @var{x})
499 @deftypefunx {long double} pow10l (long double @var{x})
500 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
501 These functions compute @code{10} raised to the power @var{x}.
502 Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
504 These functions are GNU extensions. The name @code{exp10} is
505 preferred, since it is analogous to @code{exp} and @code{exp2}.
511 @deftypefun double log (double @var{x})
514 @deftypefunx float logf (float @var{x})
517 @deftypefunx {long double} logl (long double @var{x})
518 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
519 These functions compute the natural logarithm of @var{x}. @code{exp (log
520 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
523 If @var{x} is negative, @code{log} signals a domain error. If @var{x}
524 is zero, it returns negative infinity; if @var{x} is too close to zero,
525 it may signal overflow.
530 @deftypefun double log10 (double @var{x})
533 @deftypefunx float log10f (float @var{x})
536 @deftypefunx {long double} log10l (long double @var{x})
537 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
538 These functions return the base-10 logarithm of @var{x}.
539 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
545 @deftypefun double log2 (double @var{x})
548 @deftypefunx float log2f (float @var{x})
551 @deftypefunx {long double} log2l (long double @var{x})
552 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
553 These functions return the base-2 logarithm of @var{x}.
554 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
559 @deftypefun double logb (double @var{x})
562 @deftypefunx float logbf (float @var{x})
565 @deftypefunx {long double} logbl (long double @var{x})
566 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
567 These functions extract the exponent of @var{x} and return it as a
568 floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal
569 to @code{floor (log2 (x))}, except it's probably faster.
571 If @var{x} is de-normalized, @code{logb} returns the exponent @var{x}
572 would have if it were normalized. If @var{x} is infinity (positive or
573 negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero,
574 @code{logb} returns @math{@infinity{}}. It does not signal.
579 @deftypefun int ilogb (double @var{x})
582 @deftypefunx int ilogbf (float @var{x})
585 @deftypefunx int ilogbl (long double @var{x})
586 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
587 These functions are equivalent to the corresponding @code{logb}
588 functions except that they return signed integer values.
592 Since integers cannot represent infinity and NaN, @code{ilogb} instead
593 returns an integer that can't be the exponent of a normal floating-point
594 number. @file{math.h} defines constants so you can check for this.
598 @deftypevr Macro int FP_ILOGB0
599 @code{ilogb} returns this value if its argument is @code{0}. The
600 numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
602 This macro is defined in @w{ISO C99}.
607 @deftypevr Macro int FP_ILOGBNAN
608 @code{ilogb} returns this value if its argument is @code{NaN}. The
609 numeric value is either @code{INT_MIN} or @code{INT_MAX}.
611 This macro is defined in @w{ISO C99}.
614 These values are system specific. They might even be the same. The
615 proper way to test the result of @code{ilogb} is as follows:
619 if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
623 /* @r{Handle NaN.} */
627 /* @r{Handle 0.0.} */
631 /* @r{Some other value with large exponent,}
639 @deftypefun double pow (double @var{base}, double @var{power})
642 @deftypefunx float powf (float @var{base}, float @var{power})
645 @deftypefunx {long double} powl (long double @var{base}, long double @var{power})
646 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
647 These are general exponentiation functions, returning @var{base} raised
650 Mathematically, @code{pow} would return a complex number when @var{base}
651 is negative and @var{power} is not an integral value. @code{pow} can't
652 do that, so instead it signals a domain error. @code{pow} may also
653 underflow or overflow the destination type.
656 @cindex square root function
659 @deftypefun double sqrt (double @var{x})
662 @deftypefunx float sqrtf (float @var{x})
665 @deftypefunx {long double} sqrtl (long double @var{x})
666 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
667 These functions return the nonnegative square root of @var{x}.
669 If @var{x} is negative, @code{sqrt} signals a domain error.
670 Mathematically, it should return a complex number.
673 @cindex cube root function
676 @deftypefun double cbrt (double @var{x})
679 @deftypefunx float cbrtf (float @var{x})
682 @deftypefunx {long double} cbrtl (long double @var{x})
683 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
684 These functions return the cube root of @var{x}. They cannot
685 fail; every representable real value has a representable real cube root.
690 @deftypefun double hypot (double @var{x}, double @var{y})
693 @deftypefunx float hypotf (float @var{x}, float @var{y})
696 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
697 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
698 These functions return @code{sqrt (@var{x}*@var{x} +
699 @var{y}*@var{y})}. This is the length of the hypotenuse of a right
700 triangle with sides of length @var{x} and @var{y}, or the distance
701 of the point (@var{x}, @var{y}) from the origin. Using this function
702 instead of the direct formula is wise, since the error is
703 much smaller. See also the function @code{cabs} in @ref{Absolute Value}.
708 @deftypefun double expm1 (double @var{x})
711 @deftypefunx float expm1f (float @var{x})
714 @deftypefunx {long double} expm1l (long double @var{x})
715 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
716 These functions return a value equivalent to @code{exp (@var{x}) - 1}.
717 They are computed in a way that is accurate even if @var{x} is
718 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing
719 to subtraction of two numbers that are nearly equal.
724 @deftypefun double log1p (double @var{x})
727 @deftypefunx float log1pf (float @var{x})
730 @deftypefunx {long double} log1pl (long double @var{x})
731 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
732 These functions returns a value equivalent to @w{@code{log (1 + @var{x})}}.
733 They are computed in a way that is accurate even if @var{x} is
737 @cindex complex exponentiation functions
738 @cindex complex logarithm functions
740 @w{ISO C99} defines complex variants of some of the exponentiation and
745 @deftypefun {complex double} cexp (complex double @var{z})
748 @deftypefunx {complex float} cexpf (complex float @var{z})
751 @deftypefunx {complex long double} cexpl (complex long double @var{z})
752 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
753 These functions return @code{e} (the base of natural
754 logarithms) raised to the power of @var{z}.
755 Mathematically, this corresponds to the value
758 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
761 $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
767 @deftypefun {complex double} clog (complex double @var{z})
770 @deftypefunx {complex float} clogf (complex float @var{z})
773 @deftypefunx {complex long double} clogl (complex long double @var{z})
774 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
775 These functions return the natural logarithm of @var{z}.
776 Mathematically, this corresponds to the value
779 @math{log (z) = log (cabs (z)) + I * carg (z)}
782 $$\log(z) = \log |z| + i \arg z$$
786 @code{clog} has a pole at 0, and will signal overflow if @var{z} equals
787 or is very close to 0. It is well-defined for all other values of
794 @deftypefun {complex double} clog10 (complex double @var{z})
797 @deftypefunx {complex float} clog10f (complex float @var{z})
800 @deftypefunx {complex long double} clog10l (complex long double @var{z})
801 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
802 These functions return the base 10 logarithm of the complex value
803 @var{z}. Mathematically, this corresponds to the value
806 @math{log (z) = log10 (cabs (z)) + I * carg (z)}
809 $$\log_{10}(z) = \log_{10}|z| + i \arg z$$
812 These functions are GNU extensions.
817 @deftypefun {complex double} csqrt (complex double @var{z})
820 @deftypefunx {complex float} csqrtf (complex float @var{z})
823 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
824 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
825 These functions return the complex square root of the argument @var{z}. Unlike
826 the real-valued functions, they are defined for all values of @var{z}.
831 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
834 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
837 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
838 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
839 These functions return @var{base} raised to the power of
840 @var{power}. This is equivalent to @w{@code{cexp (y * clog (x))}}
843 @node Hyperbolic Functions
844 @section Hyperbolic Functions
845 @cindex hyperbolic functions
847 The functions in this section are related to the exponential functions;
848 see @ref{Exponents and Logarithms}.
852 @deftypefun double sinh (double @var{x})
855 @deftypefunx float sinhf (float @var{x})
858 @deftypefunx {long double} sinhl (long double @var{x})
859 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
860 These functions return the hyperbolic sine of @var{x}, defined
861 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}. They
862 may signal overflow if @var{x} is too large.
867 @deftypefun double cosh (double @var{x})
870 @deftypefunx float coshf (float @var{x})
873 @deftypefunx {long double} coshl (long double @var{x})
874 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
875 These function return the hyperbolic cosine of @var{x},
876 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
877 They may signal overflow if @var{x} is too large.
882 @deftypefun double tanh (double @var{x})
885 @deftypefunx float tanhf (float @var{x})
888 @deftypefunx {long double} tanhl (long double @var{x})
889 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
890 These functions return the hyperbolic tangent of @var{x},
891 defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
892 They may signal overflow if @var{x} is too large.
895 @cindex hyperbolic functions
897 There are counterparts for the hyperbolic functions which take
902 @deftypefun {complex double} csinh (complex double @var{z})
905 @deftypefunx {complex float} csinhf (complex float @var{z})
908 @deftypefunx {complex long double} csinhl (complex long double @var{z})
909 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
910 These functions return the complex hyperbolic sine of @var{z}, defined
911 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.
916 @deftypefun {complex double} ccosh (complex double @var{z})
919 @deftypefunx {complex float} ccoshf (complex float @var{z})
922 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
923 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
924 These functions return the complex hyperbolic cosine of @var{z}, defined
925 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.
930 @deftypefun {complex double} ctanh (complex double @var{z})
933 @deftypefunx {complex float} ctanhf (complex float @var{z})
936 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
937 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
938 These functions return the complex hyperbolic tangent of @var{z},
939 defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
943 @cindex inverse hyperbolic functions
947 @deftypefun double asinh (double @var{x})
950 @deftypefunx float asinhf (float @var{x})
953 @deftypefunx {long double} asinhl (long double @var{x})
954 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
955 These functions return the inverse hyperbolic sine of @var{x}---the
956 value whose hyperbolic sine is @var{x}.
961 @deftypefun double acosh (double @var{x})
964 @deftypefunx float acoshf (float @var{x})
967 @deftypefunx {long double} acoshl (long double @var{x})
968 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
969 These functions return the inverse hyperbolic cosine of @var{x}---the
970 value whose hyperbolic cosine is @var{x}. If @var{x} is less than
971 @code{1}, @code{acosh} signals a domain error.
976 @deftypefun double atanh (double @var{x})
979 @deftypefunx float atanhf (float @var{x})
982 @deftypefunx {long double} atanhl (long double @var{x})
983 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
984 These functions return the inverse hyperbolic tangent of @var{x}---the
985 value whose hyperbolic tangent is @var{x}. If the absolute value of
986 @var{x} is greater than @code{1}, @code{atanh} signals a domain error;
987 if it is equal to 1, @code{atanh} returns infinity.
990 @cindex inverse complex hyperbolic functions
994 @deftypefun {complex double} casinh (complex double @var{z})
997 @deftypefunx {complex float} casinhf (complex float @var{z})
1000 @deftypefunx {complex long double} casinhl (complex long double @var{z})
1001 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1002 These functions return the inverse complex hyperbolic sine of
1003 @var{z}---the value whose complex hyperbolic sine is @var{z}.
1008 @deftypefun {complex double} cacosh (complex double @var{z})
1011 @deftypefunx {complex float} cacoshf (complex float @var{z})
1014 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
1015 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1016 These functions return the inverse complex hyperbolic cosine of
1017 @var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike
1018 the real-valued functions, there are no restrictions on the value of @var{z}.
1023 @deftypefun {complex double} catanh (complex double @var{z})
1026 @deftypefunx {complex float} catanhf (complex float @var{z})
1029 @deftypefunx {complex long double} catanhl (complex long double @var{z})
1030 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1031 These functions return the inverse complex hyperbolic tangent of
1032 @var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike
1033 the real-valued functions, there are no restrictions on the value of
1037 @node Special Functions
1038 @section Special Functions
1039 @cindex special functions
1040 @cindex Bessel functions
1041 @cindex gamma function
1043 These are some more exotic mathematical functions which are sometimes
1044 useful. Currently they only have real-valued versions.
1048 @deftypefun double erf (double @var{x})
1051 @deftypefunx float erff (float @var{x})
1054 @deftypefunx {long double} erfl (long double @var{x})
1055 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1056 @code{erf} returns the error function of @var{x}. The error
1057 function is defined as
1059 $$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$
1063 erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
1070 @deftypefun double erfc (double @var{x})
1073 @deftypefunx float erfcf (float @var{x})
1076 @deftypefunx {long double} erfcl (long double @var{x})
1077 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1078 @code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
1079 fashion that avoids round-off error when @var{x} is large.
1084 @deftypefun double lgamma (double @var{x})
1087 @deftypefunx float lgammaf (float @var{x})
1090 @deftypefunx {long double} lgammal (long double @var{x})
1091 @safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}}
1092 @code{lgamma} returns the natural logarithm of the absolute value of
1093 the gamma function of @var{x}. The gamma function is defined as
1095 $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
1099 gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
1104 The sign of the gamma function is stored in the global variable
1105 @var{signgam}, which is declared in @file{math.h}. It is @code{1} if
1106 the intermediate result was positive or zero, or @code{-1} if it was
1109 To compute the real gamma function you can use the @code{tgamma}
1110 function or you can compute the values as follows:
1113 gam = signgam*exp(lgam);
1116 The gamma function has singularities at the non-positive integers.
1117 @code{lgamma} will raise the zero divide exception if evaluated at a
1123 @deftypefun double lgamma_r (double @var{x}, int *@var{signp})
1126 @deftypefunx float lgammaf_r (float @var{x}, int *@var{signp})
1129 @deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp})
1130 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1131 @code{lgamma_r} is just like @code{lgamma}, but it stores the sign of
1132 the intermediate result in the variable pointed to by @var{signp}
1133 instead of in the @var{signgam} global. This means it is reentrant.
1138 @deftypefun double gamma (double @var{x})
1141 @deftypefunx float gammaf (float @var{x})
1144 @deftypefunx {long double} gammal (long double @var{x})
1145 @safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}}
1146 These functions exist for compatibility reasons. They are equivalent to
1147 @code{lgamma} etc. It is better to use @code{lgamma} since for one the
1148 name reflects better the actual computation, moreover @code{lgamma} is
1149 standardized in @w{ISO C99} while @code{gamma} is not.
1154 @deftypefun double tgamma (double @var{x})
1157 @deftypefunx float tgammaf (float @var{x})
1160 @deftypefunx {long double} tgammal (long double @var{x})
1161 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1162 @code{tgamma} applies the gamma function to @var{x}. The gamma
1163 function is defined as
1165 $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
1169 gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
1173 This function was introduced in @w{ISO C99}.
1178 @deftypefun double j0 (double @var{x})
1181 @deftypefunx float j0f (float @var{x})
1184 @deftypefunx {long double} j0l (long double @var{x})
1185 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1186 @code{j0} returns the Bessel function of the first kind of order 0 of
1187 @var{x}. It may signal underflow if @var{x} is too large.
1192 @deftypefun double j1 (double @var{x})
1195 @deftypefunx float j1f (float @var{x})
1198 @deftypefunx {long double} j1l (long double @var{x})
1199 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1200 @code{j1} returns the Bessel function of the first kind of order 1 of
1201 @var{x}. It may signal underflow if @var{x} is too large.
1206 @deftypefun double jn (int @var{n}, double @var{x})
1209 @deftypefunx float jnf (int @var{n}, float @var{x})
1212 @deftypefunx {long double} jnl (int @var{n}, long double @var{x})
1213 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1214 @code{jn} returns the Bessel function of the first kind of order
1215 @var{n} of @var{x}. It may signal underflow if @var{x} is too large.
1220 @deftypefun double y0 (double @var{x})
1223 @deftypefunx float y0f (float @var{x})
1226 @deftypefunx {long double} y0l (long double @var{x})
1227 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1228 @code{y0} returns the Bessel function of the second kind of order 0 of
1229 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
1230 is negative, @code{y0} signals a domain error; if it is zero,
1231 @code{y0} signals overflow and returns @math{-@infinity}.
1236 @deftypefun double y1 (double @var{x})
1239 @deftypefunx float y1f (float @var{x})
1242 @deftypefunx {long double} y1l (long double @var{x})
1243 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1244 @code{y1} returns the Bessel function of the second kind of order 1 of
1245 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
1246 is negative, @code{y1} signals a domain error; if it is zero,
1247 @code{y1} signals overflow and returns @math{-@infinity}.
1252 @deftypefun double yn (int @var{n}, double @var{x})
1255 @deftypefunx float ynf (int @var{n}, float @var{x})
1258 @deftypefunx {long double} ynl (int @var{n}, long double @var{x})
1259 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1260 @code{yn} returns the Bessel function of the second kind of order @var{n} of
1261 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
1262 is negative, @code{yn} signals a domain error; if it is zero,
1263 @code{yn} signals overflow and returns @math{-@infinity}.
1266 @node Errors in Math Functions
1267 @section Known Maximum Errors in Math Functions
1271 This section lists the known errors of the functions in the math
1272 library. Errors are measured in ``units of the last place''. This is a
1273 measure for the relative error. For a number @math{z} with the
1274 representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE
1275 floating-point numbers with base 2) the ULP is represented by
1278 $${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$
1282 |d.d...d - (z / 2^e)| / 2^(p - 1)
1287 where @math{p} is the number of bits in the mantissa of the
1288 floating-point number representation. Ideally the error for all
1289 functions is always less than 0.5ulps in round-to-nearest mode. Using
1290 rounding bits this is also
1291 possible and normally implemented for the basic operations. Except
1292 for certain functions such as @code{sqrt}, @code{fma} and @code{rint}
1293 whose results are fully specified by reference to corresponding IEEE
1294 754 floating-point operations, and conversions between strings and
1295 floating point, @theglibc{} does not aim for correctly rounded results
1296 for functions in the math library, and does not aim for correctness in
1297 whether ``inexact'' exceptions are raised. Instead, the goals for
1298 accuracy of functions without fully specified results are as follows;
1299 some functions have bugs meaning they do not meet these goals in all
1300 cases. In future, @theglibc{} may provide some other correctly
1301 rounding functions under the names such as @code{crsin} proposed for
1302 an extension to ISO C.
1307 Each function with a floating-point result behaves as if it computes
1308 an infinite-precision result that is within a few ulp (in both real
1309 and complex parts, for functions with complex results) of the
1310 mathematically correct value of the function (interpreted together
1311 with ISO C or POSIX semantics for the function in question) at the
1312 exact value passed as the input. Exceptions are raised appropriately
1313 for this value and in accordance with IEEE 754 / ISO C / POSIX
1314 semantics, and it is then rounded according to the current rounding
1315 direction to the result that is returned to the user. @code{errno}
1316 may also be set (@pxref{Math Error Reporting}). (The ``inexact''
1317 exception may be raised, or not raised, even if this is inconsistent
1318 with the infinite-precision value.)
1321 For the IBM @code{long double} format, as used on PowerPC GNU/Linux,
1322 the accuracy goal is weaker for input values not exactly representable
1323 in 106 bits of precision; it is as if the input value is some value
1324 within 0.5ulp of the value actually passed, where ``ulp'' is
1325 interpreted in terms of a fixed-precision 106-bit mantissa, but not
1326 necessarily the exact value actually passed with discontiguous
1330 For the IBM @code{long double} format, functions whose results are
1331 fully specified by reference to corresponding IEEE 754 floating-point
1332 operations have the same accuracy goals as other functions, but with
1333 the error bound being the same as that for division (3ulp).
1334 Furthermore, ``inexact'' and ``underflow'' exceptions may be raised
1335 for all functions for any inputs, even where such exceptions are
1336 inconsistent with the returned value, since the underlying
1337 floating-point arithmetic has that property.
1340 Functions behave as if the infinite-precision result computed is zero,
1341 infinity or NaN if and only if that is the mathematically correct
1342 infinite-precision result. They behave as if the infinite-precision
1343 result computed always has the same sign as the mathematically correct
1347 If the mathematical result is more than a few ulp above the overflow
1348 threshold for the current rounding direction, the value returned is
1349 the appropriate overflow value for the current rounding direction,
1350 with the overflow exception raised.
1353 If the mathematical result has magnitude well below half the least
1354 subnormal magnitude, the returned value is either zero or the least
1355 subnormal (in each case, with the correct sign), according to the
1356 current rounding direction and with the underflow exception raised.
1359 Where the mathematical result underflows (before rounding) and is not
1360 exactly representable as a floating-point value, the function does not
1361 behave as if the computed infinite-precision result is an exact value
1362 in the subnormal range. This means that the underflow exception is
1363 raised other than possibly for cases where the mathematical result is
1364 very close to the underflow threshold and the function behaves as if
1365 it computes an infinite-precision result that does not underflow. (So
1366 there may be spurious underflow exceptions in cases where the
1367 underflowing result is exact, but not missing underflow exceptions in
1368 cases where it is inexact.)
1371 @Theglibc{} does not aim for functions to satisfy other properties of
1372 the underlying mathematical function, such as monotonicity, where not
1373 implied by the above goals.
1376 All the above applies to both real and complex parts, for complex
1381 Therefore many of the functions in the math library have errors. The
1382 table lists the maximum error for each function which is exposed by one
1383 of the existing tests in the test suite. The table tries to cover as much
1384 as possible and list the actual maximum error (or at least a ballpark
1385 figure) but this is often not achieved due to the large search space.
1387 The table lists the ULP values for different architectures. Different
1388 architectures have different results since their hardware support for
1389 floating-point operations varies and also the existing hardware support
1393 @c This multitable does not fit on a single page
1394 @include libm-err.texi
1396 @node Pseudo-Random Numbers
1397 @section Pseudo-Random Numbers
1398 @cindex random numbers
1399 @cindex pseudo-random numbers
1400 @cindex seed (for random numbers)
1402 This section describes the GNU facilities for generating a series of
1403 pseudo-random numbers. The numbers generated are not truly random;
1404 typically, they form a sequence that repeats periodically, with a period
1405 so large that you can ignore it for ordinary purposes. The random
1406 number generator works by remembering a @dfn{seed} value which it uses
1407 to compute the next random number and also to compute a new seed.
1409 Although the generated numbers look unpredictable within one run of a
1410 program, the sequence of numbers is @emph{exactly the same} from one run
1411 to the next. This is because the initial seed is always the same. This
1412 is convenient when you are debugging a program, but it is unhelpful if
1413 you want the program to behave unpredictably. If you want a different
1414 pseudo-random series each time your program runs, you must specify a
1415 different seed each time. For ordinary purposes, basing the seed on the
1416 current time works well.
1418 You can obtain repeatable sequences of numbers on a particular machine type
1419 by specifying the same initial seed value for the random number
1420 generator. There is no standard meaning for a particular seed value;
1421 the same seed, used in different C libraries or on different CPU types,
1422 will give you different random numbers.
1424 @Theglibc{} supports the standard @w{ISO C} random number functions
1425 plus two other sets derived from BSD and SVID. The BSD and @w{ISO C}
1426 functions provide identical, somewhat limited functionality. If only a
1427 small number of random bits are required, we recommend you use the
1428 @w{ISO C} interface, @code{rand} and @code{srand}. The SVID functions
1429 provide a more flexible interface, which allows better random number
1430 generator algorithms, provides more random bits (up to 48) per call, and
1431 can provide random floating-point numbers. These functions are required
1432 by the XPG standard and therefore will be present in all modern Unix
1436 * ISO Random:: @code{rand} and friends.
1437 * BSD Random:: @code{random} and friends.
1438 * SVID Random:: @code{drand48} and friends.
1442 @subsection ISO C Random Number Functions
1444 This section describes the random number functions that are part of
1445 the @w{ISO C} standard.
1447 To use these facilities, you should include the header file
1448 @file{stdlib.h} in your program.
1453 @deftypevr Macro int RAND_MAX
1454 The value of this macro is an integer constant representing the largest
1455 value the @code{rand} function can return. In @theglibc{}, it is
1456 @code{2147483647}, which is the largest signed integer representable in
1457 32 bits. In other libraries, it may be as low as @code{32767}.
1462 @deftypefun int rand (void)
1463 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1464 @c Just calls random.
1465 The @code{rand} function returns the next pseudo-random number in the
1466 series. The value ranges from @code{0} to @code{RAND_MAX}.
1471 @deftypefun void srand (unsigned int @var{seed})
1472 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1473 @c Alias to srandom.
1474 This function establishes @var{seed} as the seed for a new series of
1475 pseudo-random numbers. If you call @code{rand} before a seed has been
1476 established with @code{srand}, it uses the value @code{1} as a default
1479 To produce a different pseudo-random series each time your program is
1480 run, do @code{srand (time (0))}.
1483 POSIX.1 extended the C standard functions to support reproducible random
1484 numbers in multi-threaded programs. However, the extension is badly
1485 designed and unsuitable for serious work.
1489 @deftypefun int rand_r (unsigned int *@var{seed})
1490 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
1491 This function returns a random number in the range 0 to @code{RAND_MAX}
1492 just as @code{rand} does. However, all its state is stored in the
1493 @var{seed} argument. This means the RNG's state can only have as many
1494 bits as the type @code{unsigned int} has. This is far too few to
1497 If your program requires a reentrant RNG, we recommend you use the
1498 reentrant GNU extensions to the SVID random number generator. The
1499 POSIX.1 interface should only be used when the GNU extensions are not
1505 @subsection BSD Random Number Functions
1507 This section describes a set of random number generation functions that
1508 are derived from BSD. There is no advantage to using these functions
1509 with @theglibc{}; we support them for BSD compatibility only.
1511 The prototypes for these functions are in @file{stdlib.h}.
1516 @deftypefun {long int} random (void)
1517 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1518 @c Takes a lock and calls random_r with an automatic variable and the
1519 @c global state, while holding a lock.
1520 This function returns the next pseudo-random number in the sequence.
1521 The value returned ranges from @code{0} to @code{2147483647}.
1523 @strong{NB:} Temporarily this function was defined to return a
1524 @code{int32_t} value to indicate that the return value always contains
1525 32 bits even if @code{long int} is wider. The standard demands it
1526 differently. Users must always be aware of the 32-bit limitation,
1532 @deftypefun void srandom (unsigned int @var{seed})
1533 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1534 @c Takes a lock and calls srandom_r with an automatic variable and a
1535 @c static buffer. There's no MT-safety issue because the static buffer
1536 @c is internally protected by a lock, although other threads may modify
1537 @c the set state before it is used.
1538 The @code{srandom} function sets the state of the random number
1539 generator based on the integer @var{seed}. If you supply a @var{seed} value
1540 of @code{1}, this will cause @code{random} to reproduce the default set
1543 To produce a different set of pseudo-random numbers each time your
1544 program runs, do @code{srandom (time (0))}.
1549 @deftypefun {char *} initstate (unsigned int @var{seed}, char *@var{state}, size_t @var{size})
1550 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1551 The @code{initstate} function is used to initialize the random number
1552 generator state. The argument @var{state} is an array of @var{size}
1553 bytes, used to hold the state information. It is initialized based on
1554 @var{seed}. The size must be between 8 and 256 bytes, and should be a
1555 power of two. The bigger the @var{state} array, the better.
1557 The return value is the previous value of the state information array.
1558 You can use this value later as an argument to @code{setstate} to
1564 @deftypefun {char *} setstate (char *@var{state})
1565 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
1566 The @code{setstate} function restores the random number state
1567 information @var{state}. The argument must have been the result of
1568 a previous call to @var{initstate} or @var{setstate}.
1570 The return value is the previous value of the state information array.
1571 You can use this value later as an argument to @code{setstate} to
1574 If the function fails the return value is @code{NULL}.
1577 The four functions described so far in this section all work on a state
1578 which is shared by all threads. The state is not directly accessible to
1579 the user and can only be modified by these functions. This makes it
1580 hard to deal with situations where each thread should have its own
1581 pseudo-random number generator.
1583 @Theglibc{} contains four additional functions which contain the
1584 state as an explicit parameter and therefore make it possible to handle
1585 thread-local PRNGs. Beside this there is no difference. In fact, the
1586 four functions already discussed are implemented internally using the
1587 following interfaces.
1589 The @file{stdlib.h} header contains a definition of the following type:
1593 @deftp {Data Type} {struct random_data}
1595 Objects of type @code{struct random_data} contain the information
1596 necessary to represent the state of the PRNG. Although a complete
1597 definition of the type is present the type should be treated as opaque.
1600 The functions modifying the state follow exactly the already described
1605 @deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result})
1606 @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
1607 The @code{random_r} function behaves exactly like the @code{random}
1608 function except that it uses and modifies the state in the object
1609 pointed to by the first parameter instead of the global state.
1614 @deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf})
1615 @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
1616 The @code{srandom_r} function behaves exactly like the @code{srandom}
1617 function except that it uses and modifies the state in the object
1618 pointed to by the second parameter instead of the global state.
1623 @deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf})
1624 @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
1625 The @code{initstate_r} function behaves exactly like the @code{initstate}
1626 function except that it uses and modifies the state in the object
1627 pointed to by the fourth parameter instead of the global state.
1632 @deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf})
1633 @safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}}
1634 The @code{setstate_r} function behaves exactly like the @code{setstate}
1635 function except that it uses and modifies the state in the object
1636 pointed to by the first parameter instead of the global state.
1640 @subsection SVID Random Number Function
1642 The C library on SVID systems contains yet another kind of random number
1643 generator functions. They use a state of 48 bits of data. The user can
1644 choose among a collection of functions which return the random bits
1647 Generally there are two kinds of function. The first uses a state of
1648 the random number generator which is shared among several functions and
1649 by all threads of the process. The second requires the user to handle
1652 All functions have in common that they use the same congruential
1653 formula with the same constants. The formula is
1656 Y = (a * X + c) mod m
1660 where @var{X} is the state of the generator at the beginning and
1661 @var{Y} the state at the end. @code{a} and @code{c} are constants
1662 determining the way the generator works. By default they are
1665 a = 0x5DEECE66D = 25214903917
1670 but they can also be changed by the user. @code{m} is of course 2^48
1671 since the state consists of a 48-bit array.
1673 The prototypes for these functions are in @file{stdlib.h}.
1679 @deftypefun double drand48 (void)
1680 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1681 @c Uses of the static state buffer are not guarded by a lock (thus
1682 @c @mtasurace:drand48), so they may be found or left at a
1683 @c partially-updated state in case of calls from within signal handlers
1684 @c or cancellation. None of this will break safety rules or invoke
1685 @c undefined behavior, but it may affect randomness.
1686 This function returns a @code{double} value in the range of @code{0.0}
1687 to @code{1.0} (exclusive). The random bits are determined by the global
1688 state of the random number generator in the C library.
1690 Since the @code{double} type according to @w{IEEE 754} has a 52-bit
1691 mantissa this means 4 bits are not initialized by the random number
1692 generator. These are (of course) chosen to be the least significant
1693 bits and they are initialized to @code{0}.
1698 @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
1699 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1700 @c The static buffer is just initialized with default parameters, which
1701 @c are later read to advance the state held in xsubi.
1702 This function returns a @code{double} value in the range of @code{0.0}
1703 to @code{1.0} (exclusive), similarly to @code{drand48}. The argument is
1704 an array describing the state of the random number generator.
1706 This function can be called subsequently since it updates the array to
1707 guarantee random numbers. The array should have been initialized before
1708 initial use to obtain reproducible results.
1713 @deftypefun {long int} lrand48 (void)
1714 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1715 The @code{lrand48} function returns an integer value in the range of
1716 @code{0} to @code{2^31} (exclusive). Even if the size of the @code{long
1717 int} type can take more than 32 bits, no higher numbers are returned.
1718 The random bits are determined by the global state of the random number
1719 generator in the C library.
1724 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
1725 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1726 This function is similar to the @code{lrand48} function in that it
1727 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1728 the state of the random number generator used to produce the random bits
1729 is determined by the array provided as the parameter to the function.
1731 The numbers in the array are updated afterwards so that subsequent calls
1732 to this function yield different results (as is expected of a random
1733 number generator). The array should have been initialized before the
1734 first call to obtain reproducible results.
1739 @deftypefun {long int} mrand48 (void)
1740 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1741 The @code{mrand48} function is similar to @code{lrand48}. The only
1742 difference is that the numbers returned are in the range @code{-2^31} to
1743 @code{2^31} (exclusive).
1748 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
1749 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1750 The @code{jrand48} function is similar to @code{nrand48}. The only
1751 difference is that the numbers returned are in the range @code{-2^31} to
1752 @code{2^31} (exclusive). For the @code{xsubi} parameter the same
1753 requirements are necessary.
1756 The internal state of the random number generator can be initialized in
1757 several ways. The methods differ in the completeness of the
1758 information provided.
1762 @deftypefun void srand48 (long int @var{seedval})
1763 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1764 The @code{srand48} function sets the most significant 32 bits of the
1765 internal state of the random number generator to the least
1766 significant 32 bits of the @var{seedval} parameter. The lower 16 bits
1767 are initialized to the value @code{0x330E}. Even if the @code{long
1768 int} type contains more than 32 bits only the lower 32 bits are used.
1770 Owing to this limitation, initialization of the state of this
1771 function is not very useful. But it makes it easy to use a construct
1772 like @code{srand48 (time (0))}.
1774 A side-effect of this function is that the values @code{a} and @code{c}
1775 from the internal state, which are used in the congruential formula,
1776 are reset to the default values given above. This is of importance once
1777 the user has called the @code{lcong48} function (see below).
1782 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
1783 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1784 The @code{seed48} function initializes all 48 bits of the state of the
1785 internal random number generator from the contents of the parameter
1786 @var{seed16v}. Here the lower 16 bits of the first element of
1787 @var{see16v} initialize the least significant 16 bits of the internal
1788 state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
1789 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
1790 initialize the most significant 16 bits of the state.
1792 Unlike @code{srand48} this function lets the user initialize all 48 bits
1795 The value returned by @code{seed48} is a pointer to an array containing
1796 the values of the internal state before the change. This might be
1797 useful to restart the random number generator at a certain state.
1798 Otherwise the value can simply be ignored.
1800 As for @code{srand48}, the values @code{a} and @code{c} from the
1801 congruential formula are reset to the default values.
1804 There is one more function to initialize the random number generator
1805 which enables you to specify even more information by allowing you to
1806 change the parameters in the congruential formula.
1810 @deftypefun void lcong48 (unsigned short int @var{param}[7])
1811 @safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}}
1812 The @code{lcong48} function allows the user to change the complete state
1813 of the random number generator. Unlike @code{srand48} and
1814 @code{seed48}, this function also changes the constants in the
1815 congruential formula.
1817 From the seven elements in the array @var{param} the least significant
1818 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
1819 determine the initial state, the least significant 16 bits of
1820 @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
1821 constant @code{a} and @code{@var{param}[6]} determines the 16-bit value
1825 All the above functions have in common that they use the global
1826 parameters for the congruential formula. In multi-threaded programs it
1827 might sometimes be useful to have different parameters in different
1828 threads. For this reason all the above functions have a counterpart
1829 which works on a description of the random number generator in the
1830 user-supplied buffer instead of the global state.
1832 Please note that it is no problem if several threads use the global
1833 state if all threads use the functions which take a pointer to an array
1834 containing the state. The random numbers are computed following the
1835 same loop but if the state in the array is different all threads will
1836 obtain an individual random number generator.
1838 The user-supplied buffer must be of type @code{struct drand48_data}.
1839 This type should be regarded as opaque and not manipulated directly.
1843 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1844 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1845 This function is equivalent to the @code{drand48} function with the
1846 difference that it does not modify the global random number generator
1847 parameters but instead the parameters in the buffer supplied through the
1848 pointer @var{buffer}. The random number is returned in the variable
1849 pointed to by @var{result}.
1851 The return value of the function indicates whether the call succeeded.
1852 If the value is less than @code{0} an error occurred and @var{errno} is
1853 set to indicate the problem.
1855 This function is a GNU extension and should not be used in portable
1861 @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
1862 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1863 The @code{erand48_r} function works like @code{erand48}, but in addition
1864 it takes an argument @var{buffer} which describes the random number
1865 generator. The state of the random number generator is taken from the
1866 @code{xsubi} array, the parameters for the congruential formula from the
1867 global random number generator data. The random number is returned in
1868 the variable pointed to by @var{result}.
1870 The return value is non-negative if the call succeeded.
1872 This function is a GNU extension and should not be used in portable
1878 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
1879 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1880 This function is similar to @code{lrand48}, but in addition it takes a
1881 pointer to a buffer describing the state of the random number generator
1882 just like @code{drand48}.
1884 If the return value of the function is non-negative the variable pointed
1885 to by @var{result} contains the result. Otherwise an error occurred.
1887 This function is a GNU extension and should not be used in portable
1893 @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1894 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1895 The @code{nrand48_r} function works like @code{nrand48} in that it
1896 produces a random number in the range @code{0} to @code{2^31}. But instead
1897 of using the global parameters for the congruential formula it uses the
1898 information from the buffer pointed to by @var{buffer}. The state is
1899 described by the values in @var{xsubi}.
1901 If the return value is non-negative the variable pointed to by
1902 @var{result} contains the result.
1904 This function is a GNU extension and should not be used in portable
1910 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, long int *@var{result})
1911 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1912 This function is similar to @code{mrand48} but like the other reentrant
1913 functions it uses the random number generator described by the value in
1914 the buffer pointed to by @var{buffer}.
1916 If the return value is non-negative the variable pointed to by
1917 @var{result} contains the result.
1919 This function is a GNU extension and should not be used in portable
1925 @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1926 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1927 The @code{jrand48_r} function is similar to @code{jrand48}. Like the
1928 other reentrant functions of this function family it uses the
1929 congruential formula parameters from the buffer pointed to by
1932 If the return value is non-negative the variable pointed to by
1933 @var{result} contains the result.
1935 This function is a GNU extension and should not be used in portable
1939 Before any of the above functions are used the buffer of type
1940 @code{struct drand48_data} should be initialized. The easiest way to do
1941 this is to fill the whole buffer with null bytes, e.g. by
1944 memset (buffer, '\0', sizeof (struct drand48_data));
1948 Using any of the reentrant functions of this family now will
1949 automatically initialize the random number generator to the default
1950 values for the state and the parameters of the congruential formula.
1952 The other possibility is to use any of the functions which explicitly
1953 initialize the buffer. Though it might be obvious how to initialize the
1954 buffer from looking at the parameter to the function, it is highly
1955 recommended to use these functions since the result might not always be
1960 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1961 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1962 The description of the random number generator represented by the
1963 information in @var{buffer} is initialized similarly to what the function
1964 @code{srand48} does. The state is initialized from the parameter
1965 @var{seedval} and the parameters for the congruential formula are
1966 initialized to their default values.
1968 If the return value is non-negative the function call succeeded.
1970 This function is a GNU extension and should not be used in portable
1976 @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
1977 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1978 This function is similar to @code{srand48_r} but like @code{seed48} it
1979 initializes all 48 bits of the state from the parameter @var{seed16v}.
1981 If the return value is non-negative the function call succeeded. It
1982 does not return a pointer to the previous state of the random number
1983 generator like the @code{seed48} function does. If the user wants to
1984 preserve the state for a later re-run s/he can copy the whole buffer
1985 pointed to by @var{buffer}.
1987 This function is a GNU extension and should not be used in portable
1993 @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
1994 @safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}}
1995 This function initializes all aspects of the random number generator
1996 described in @var{buffer} with the data in @var{param}. Here it is
1997 especially true that the function does more than just copying the
1998 contents of @var{param} and @var{buffer}. More work is required and
1999 therefore it is important to use this function rather than initializing
2000 the random number generator directly.
2002 If the return value is non-negative the function call succeeded.
2004 This function is a GNU extension and should not be used in portable
2008 @node FP Function Optimizations
2009 @section Is Fast Code or Small Code preferred?
2010 @cindex Optimization
2012 If an application uses many floating point functions it is often the case
2013 that the cost of the function calls themselves is not negligible.
2014 Modern processors can often execute the operations themselves
2015 very fast, but the function call disrupts the instruction pipeline.
2017 For this reason @theglibc{} provides optimizations for many of the
2018 frequently-used math functions. When GNU CC is used and the user
2019 activates the optimizer, several new inline functions and macros are
2020 defined. These new functions and macros have the same names as the
2021 library functions and so are used instead of the latter. In the case of
2022 inline functions the compiler will decide whether it is reasonable to
2023 use them, and this decision is usually correct.
2025 This means that no calls to the library functions may be necessary, and
2026 can increase the speed of generated code significantly. The drawback is
2027 that code size will increase, and the increase is not always negligible.
2029 There are two kind of inline functions: Those that give the same result
2030 as the library functions and others that might not set @code{errno} and
2031 might have a reduced precision and/or argument range in comparison with
2032 the library functions. The latter inline functions are only available
2033 if the flag @code{-ffast-math} is given to GNU CC.
2035 In cases where the inline functions and macros are not wanted the symbol
2036 @code{__NO_MATH_INLINES} should be defined before any system header is
2037 included. This will ensure that only library functions are used. Of
2038 course, it can be determined for each file in the project whether
2039 giving this option is preferable or not.
2041 Not all hardware implements the entire @w{IEEE 754} standard, and even
2042 if it does there may be a substantial performance penalty for using some
2043 of its features. For example, enabling traps on some processors forces
2044 the FPU to run un-pipelined, which can more than double calculation time.
2045 @c ***Add explanation of -lieee, -mieee.