1 @c We need some definitions here.
30 @node Mathematics, Arithmetic, Low-Level Terminal Interface, 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 C 89}. The @code{float} and @code{long double}
46 versions are from the numeric extensions to C included in @w{ISO C 9X}.
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 accomodate 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 * Pseudo-Random Numbers:: Functions for generating pseudo-random
66 * FP Function Optimizations:: Fast code or small code.
69 @node Mathematical Constants
70 @section Predefined Mathematical Constants
72 @cindex mathematical constants
74 The header @file{math.h} defines several useful mathematical constants.
75 All values are defined as preprocessor macros starting with @code{M_}.
76 The values provided are:
80 The base of natural logarithms.
82 The logarithm to base @code{2} of @code{M_E}.
84 The logarithm to base @code{10} of @code{M_E}.
86 The natural logarithm of @code{2}.
88 The natural logarithm of @code{10}.
90 Pi, the ratio of a circle's circumrefence to its diameter.
96 The reciprocal of pi (1/pi)
98 Two times the reciprocal of pi.
100 Two times the reciprocal of the square root of pi.
102 The square root of two.
104 The reciprocal of the square root of two (also the square root of 1/2).
107 These constants come from the Unix98 standard and were also available in
108 4.4BSD; therefore, they are only defined if @code{_BSD_SOURCE} or
109 @code{_XOPEN_SOURCE=500}, or a more general feature select macro, is
110 defined. The default set of features includes these constants.
111 @xref{Feature Test Macros}.
113 All values are of type @code{double}. As an extension, the GNU C
114 library also defines these constants with type @code{long double}. The
115 @code{long double} macros have a lowercase @samp{l} appended to their
116 names: @code{M_El}, @code{M_PIl}, and so forth. These are only
117 available if @code{_GNU_SOURCE} is defined.
120 @emph{Note:} Some programs use a constant named @code{PI} which has the
121 same value as @code{M_PI}. This constant is not standard; it may have
122 appeared in some old AT&T headers, and is mentioned in Stroustrup's book
123 on C++. It infringes on the user's name space, so the GNU C library
124 does not define it. Fixing programs written to expect it is simple:
125 replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI}
126 on the compiler command line.
129 @section Trigonometric Functions
130 @cindex trigonometric functions
132 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
133 The arguments to all of these functions are in units of radians; recall
134 that pi radians equals 180 degrees.
136 @cindex pi (trigonometric constant)
137 The math library normally defines @code{M_PI} to a @code{double}
138 approximation of pi. If strict ISO and/or POSIX compliance
139 are requested this constant is not defined, but you can easily define it
143 #define M_PI 3.14159265358979323846264338327
147 You can also compute the value of pi with the expression @code{acos
152 @deftypefun double sin (double @var{x})
153 @deftypefunx float sinf (float @var{x})
154 @deftypefunx {long double} sinl (long double @var{x})
155 These functions return the sine of @var{x}, where @var{x} is given in
156 radians. The return value is in the range @code{-1} to @code{1}.
161 @deftypefun double cos (double @var{x})
162 @deftypefunx float cosf (float @var{x})
163 @deftypefunx {long double} cosl (long double @var{x})
164 These functions return the cosine of @var{x}, where @var{x} is given in
165 radians. The return value is in the range @code{-1} to @code{1}.
170 @deftypefun double tan (double @var{x})
171 @deftypefunx float tanf (float @var{x})
172 @deftypefunx {long double} tanl (long double @var{x})
173 These functions return the tangent of @var{x}, where @var{x} is given in
176 Mathematically, the tangent function has singularities at odd multiples
177 of pi/2. If the argument @var{x} is too close to one of these
178 singularities, @code{tan} will signal overflow.
181 In many applications where @code{sin} and @code{cos} are used, the sine
182 and cosine of the same angle are needed at the same time. It is more
183 efficient to compute them simultaneously, so the library provides a
188 @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
189 @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
190 @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
191 These functions return the sine of @var{x} in @code{*@var{sinx}} and the
192 cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
193 radians. Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
194 the range of @code{-1} to @code{1}.
196 This function is a GNU extension. Portable programs should be prepared
197 to cope with its absence.
200 @cindex complex trigonometric functions
202 @w{ISO C 9x} defines variants of the trig functions which work on
203 complex numbers. The GNU C library provides these functions, but they
204 are only useful if your compiler supports the new complex types defined
206 @c Change this when gcc is fixed. -zw
207 (As of this writing GCC supports complex numbers, but there are bugs in
212 @deftypefun {complex double} csin (complex double @var{z})
213 @deftypefunx {complex float} csinf (complex float @var{z})
214 @deftypefunx {complex long double} csinl (complex long double @var{z})
215 These functions return the complex sine of @var{z}.
216 The mathematical definition of the complex sine is
219 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
222 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
228 @deftypefun {complex double} ccos (complex double @var{z})
229 @deftypefunx {complex float} ccosf (complex float @var{z})
230 @deftypefunx {complex long double} ccosl (complex long double @var{z})
231 These functions return the complex cosine of @var{z}.
232 The mathematical definition of the complex cosine is
235 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
238 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
244 @deftypefun {complex double} ctan (complex double @var{z})
245 @deftypefunx {complex float} ctanf (complex float @var{z})
246 @deftypefunx {complex long double} ctanl (complex long double @var{z})
247 These functions return the complex tangent of @var{z}.
248 The mathematical definition of the complex tangent is
251 @math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
254 $$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
258 The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an
259 integer. @code{ctan} may signal overflow if @var{z} is too close to a
264 @node Inverse Trig Functions
265 @section Inverse Trigonometric Functions
266 @cindex inverse trigonometric functions
268 These are the usual arc sine, arc cosine and arc tangent functions,
269 which are the inverses of the sine, cosine and tangent functions,
274 @deftypefun double asin (double @var{x})
275 @deftypefunx float asinf (float @var{x})
276 @deftypefunx {long double} asinl (long double @var{x})
277 These functions compute the arc sine of @var{x}---that is, the value whose
278 sine is @var{x}. The value is in units of radians. Mathematically,
279 there are infinitely many such values; the one actually returned is the
280 one between @code{-pi/2} and @code{pi/2} (inclusive).
282 The arc sine function is defined mathematically only
283 over the domain @code{-1} to @code{1}. If @var{x} is outside the
284 domain, @code{asin} signals a domain error.
289 @deftypefun double acos (double @var{x})
290 @deftypefunx float acosf (float @var{x})
291 @deftypefunx {long double} acosl (long double @var{x})
292 These functions compute the arc cosine of @var{x}---that is, the value
293 whose cosine is @var{x}. The value is in units of radians.
294 Mathematically, there are infinitely many such values; the one actually
295 returned is the one between @code{0} and @code{pi} (inclusive).
297 The arc cosine function is defined mathematically only
298 over the domain @code{-1} to @code{1}. If @var{x} is outside the
299 domain, @code{acos} signals a domain error.
304 @deftypefun double atan (double @var{x})
305 @deftypefunx float atanf (float @var{x})
306 @deftypefunx {long double} atanl (long double @var{x})
307 These functions compute the arc tangent of @var{x}---that is, the value
308 whose tangent is @var{x}. The value is in units of radians.
309 Mathematically, there are infinitely many such values; the one actually
310 returned is the one between @code{-pi/2} and @code{pi/2} (inclusive).
315 @deftypefun double atan2 (double @var{y}, double @var{x})
316 @deftypefunx float atan2f (float @var{y}, float @var{x})
317 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
318 This function computes the arc tangent of @var{y}/@var{x}, but the signs
319 of both arguments are used to determine the quadrant of the result, and
320 @var{x} is permitted to be zero. The return value is given in radians
321 and is in the range @code{-pi} to @code{pi}, inclusive.
323 If @var{x} and @var{y} are coordinates of a point in the plane,
324 @code{atan2} returns the signed angle between the line from the origin
325 to that point and the x-axis. Thus, @code{atan2} is useful for
326 converting Cartesian coordinates to polar coordinates. (To compute the
327 radial coordinate, use @code{hypot}; see @ref{Exponents and
330 @c This is experimentally true. Should it be so? -zw
331 If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
334 @cindex inverse complex trigonometric functions
335 @w{ISO C 9x} defines complex versions of the inverse trig functions.
339 @deftypefun {complex double} casin (complex double @var{z})
340 @deftypefunx {complex float} casinf (complex float @var{z})
341 @deftypefunx {complex long double} casinl (complex long double @var{z})
342 These functions compute the complex arc sine of @var{z}---that is, the
343 value whose sine is @var{z}. The value returned is in radians.
345 Unlike the real-valued functions, @code{casin} is defined for all
351 @deftypefun {complex double} cacos (complex double @var{z})
352 @deftypefunx {complex float} cacosf (complex float @var{z})
353 @deftypefunx {complex long double} cacosl (complex long double @var{z})
354 These functions compute the complex arc cosine of @var{z}---that is, the
355 value whose cosine is @var{z}. The value returned is in radians.
357 Unlike the real-valued functions, @code{cacos} is defined for all
364 @deftypefun {complex double} catan (complex double @var{z})
365 @deftypefunx {complex float} catanf (complex float @var{z})
366 @deftypefunx {complex long double} catanl (complex long double @var{z})
367 These functions compute the complex arc tangent of @var{z}---that is,
368 the value whose tangent is @var{z}. The value is in units of radians.
372 @node Exponents and Logarithms
373 @section Exponentiation and Logarithms
374 @cindex exponentiation functions
375 @cindex power functions
376 @cindex logarithm functions
380 @deftypefun double exp (double @var{x})
381 @deftypefunx float expf (float @var{x})
382 @deftypefunx {long double} expl (long double @var{x})
383 These functions compute @code{e} (the base of natural logarithms) raised
384 to the power @var{x}.
386 If the magnitude of the result is too large to be representable,
387 @code{exp} signals overflow.
392 @deftypefun double exp2 (double @var{x})
393 @deftypefunx float exp2f (float @var{x})
394 @deftypefunx {long double} exp2l (long double @var{x})
395 These functions compute @code{2} raised to the power @var{x}.
396 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
401 @deftypefun double exp10 (double @var{x})
402 @deftypefunx float exp10f (float @var{x})
403 @deftypefunx {long double} exp10l (long double @var{x})
404 @deftypefunx double pow10 (double @var{x})
405 @deftypefunx float pow10f (float @var{x})
406 @deftypefunx {long double} pow10l (long double @var{x})
407 These functions compute @code{10} raised to the power @var{x}.
408 Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
410 These functions are GNU extensions. The name @code{exp10} is
411 preferred, since it is analogous to @code{exp} and @code{exp2}.
417 @deftypefun double log (double @var{x})
418 @deftypefunx float logf (float @var{x})
419 @deftypefunx {long double} logl (long double @var{x})
420 These functions compute the natural logarithm of @var{x}. @code{exp (log
421 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
424 If @var{x} is negative, @code{log} signals a domain error. If @var{x}
425 is zero, it returns negative infinity; if @var{x} is too close to zero,
426 it may signal overflow.
431 @deftypefun double log10 (double @var{x})
432 @deftypefunx float log10f (float @var{x})
433 @deftypefunx {long double} log10l (long double @var{x})
434 These functions return the base-10 logarithm of @var{x}.
435 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
441 @deftypefun double log2 (double @var{x})
442 @deftypefunx float log2f (float @var{x})
443 @deftypefunx {long double} log2l (long double @var{x})
444 These functions return the base-2 logarithm of @var{x}.
445 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
450 @deftypefun double logb (double @var{x})
451 @deftypefunx float logbf (float @var{x})
452 @deftypefunx {long double} logbl (long double @var{x})
453 These functions extract the exponent of @var{x} and return it as a
454 floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal
455 to @code{floor (log2 (x))}, except it's probably faster.
457 If @var{x} is denormalized, @code{logb} returns the exponent @var{x}
458 would have if it were normalized. If @var{x} is infinity (positive or
459 negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero,
460 @code{logb} returns @math{@infinity{}}. It does not signal.
465 @deftypefun int ilogb (double @var{x})
466 @deftypefunx int ilogbf (float @var{x})
467 @deftypefunx int ilogbl (long double @var{x})
468 These functions are equivalent to the corresponding @code{logb}
469 functions except that they return signed integer values.
473 Since integers cannot represent infinity and NaN, @code{ilogb} instead
474 returns an integer that can't be the exponent of a normal floating-point
475 number. @file{math.h} defines constants so you can check for this.
479 @deftypevr Macro int FP_ILOGB0
480 @code{ilogb} returns this value if its argument is @code{0}. The
481 numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
483 This macro is defined in @w{ISO C 9X}.
488 @deftypevr Macro int FP_ILOGBNAN
489 @code{ilogb} returns this value if its argument is @code{NaN}. The
490 numeric value is either @code{INT_MIN} or @code{INT_MAX}.
492 This macro is defined in @w{ISO C 9X}.
495 These values are system specific. They might even be the same. The
496 proper way to test the result of @code{ilogb} is as follows:
500 if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
504 /* @r{Handle NaN.} */
508 /* @r{Handle 0.0.} */
512 /* @r{Some other value with large exponent,}
520 @deftypefun double pow (double @var{base}, double @var{power})
521 @deftypefunx float powf (float @var{base}, float @var{power})
522 @deftypefunx {long double} powl (long double @var{base}, long double @var{power})
523 These are general exponentiation functions, returning @var{base} raised
526 Mathematically, @code{pow} would return a complex number when @var{base}
527 is negative and @var{power} is not an integral value. @code{pow} can't
528 do that, so instead it signals a domain error. @code{pow} may also
529 underflow or overflow the destination type.
532 @cindex square root function
535 @deftypefun double sqrt (double @var{x})
536 @deftypefunx float sqrtf (float @var{x})
537 @deftypefunx {long double} sqrtl (long double @var{x})
538 These functions return the nonnegative square root of @var{x}.
540 If @var{x} is negative, @code{sqrt} signals a domain error.
541 Mathematically, it should return a complex number.
544 @cindex cube root function
547 @deftypefun double cbrt (double @var{x})
548 @deftypefunx float cbrtf (float @var{x})
549 @deftypefunx {long double} cbrtl (long double @var{x})
550 These functions return the cube root of @var{x}. They cannot
551 fail; every representable real value has a representable real cube root.
556 @deftypefun double hypot (double @var{x}, double @var{y})
557 @deftypefunx float hypotf (float @var{x}, float @var{y})
558 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
559 These functions return @code{sqrt (@var{x}*@var{x} +
560 @var{y}*@var{y})}. This is the length of the hypotenuse of a right
561 triangle with sides of length @var{x} and @var{y}, or the distance
562 of the point (@var{x}, @var{y}) from the origin. Using this function
563 instead of the direct formula is wise, since the error is
564 much smaller. See also the function @code{cabs} in @ref{Absolute Value}.
569 @deftypefun double expm1 (double @var{x})
570 @deftypefunx float expm1f (float @var{x})
571 @deftypefunx {long double} expm1l (long double @var{x})
572 These functions return a value equivalent to @code{exp (@var{x}) - 1}.
573 They are computed in a way that is accurate even if @var{x} is
574 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
575 to subtraction of two numbers that are nearly equal.
580 @deftypefun double log1p (double @var{x})
581 @deftypefunx float log1pf (float @var{x})
582 @deftypefunx {long double} log1pl (long double @var{x})
583 These functions returns a value equivalent to @w{@code{log (1 + @var{x})}}.
584 They are computed in a way that is accurate even if @var{x} is
588 @cindex complex exponentiation functions
589 @cindex complex logarithm functions
591 @w{ISO C 9X} defines complex variants of some of the exponentiation and
596 @deftypefun {complex double} cexp (complex double @var{z})
597 @deftypefunx {complex float} cexpf (complex float @var{z})
598 @deftypefunx {complex long double} cexpl (complex long double @var{z})
599 These functions return @code{e} (the base of natural
600 logarithms) raised to the power of @var{z}.
601 Mathematically this corresponds to the value
604 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
607 $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
613 @deftypefun {complex double} clog (complex double @var{z})
614 @deftypefunx {complex float} clogf (complex float @var{z})
615 @deftypefunx {complex long double} clogl (complex long double @var{z})
616 These functions return the natural logarithm of @var{z}.
617 Mathematically this corresponds to the value
620 @math{log (z) = log (cabs (z)) + I * carg (z)}
623 $$\log(z) = \log |z| + i \arg z$$
627 @code{clog} has a pole at 0, and will signal overflow if @var{z} equals
628 or is very close to 0. It is well-defined for all other values of
635 @deftypefun {complex double} clog10 (complex double @var{z})
636 @deftypefunx {complex float} clog10f (complex float @var{z})
637 @deftypefunx {complex long double} clog10l (complex long double @var{z})
638 These functions return the base 10 logarithm of the complex value
639 @var{z}. Mathematically this corresponds to the value
642 @math{log (z) = log10 (cabs (z)) + I * carg (z)}
645 $$\log_{10}(z) = \log_{10}|z| + i \arg z$$
648 These functions are GNU extensions.
653 @deftypefun {complex double} csqrt (complex double @var{z})
654 @deftypefunx {complex float} csqrtf (complex float @var{z})
655 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
656 These functions return the complex square root of the argument @var{z}. Unlike
657 the real-valued functions, they are defined for all values of @var{z}.
662 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
663 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
664 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
665 These functions return @var{base} raised to the power of
666 @var{power}. This is equivalent to @w{@code{cexp (y * clog (x))}}
669 @node Hyperbolic Functions
670 @section Hyperbolic Functions
671 @cindex hyperbolic functions
673 The functions in this section are related to the exponential functions;
674 see @ref{Exponents and Logarithms}.
678 @deftypefun double sinh (double @var{x})
679 @deftypefunx float sinhf (float @var{x})
680 @deftypefunx {long double} sinhl (long double @var{x})
681 These functions return the hyperbolic sine of @var{x}, defined
682 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}. They
683 may signal overflow if @var{x} is too large.
688 @deftypefun double cosh (double @var{x})
689 @deftypefunx float coshf (float @var{x})
690 @deftypefunx {long double} coshl (long double @var{x})
691 These function return the hyperbolic cosine of @var{x},
692 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
693 They may signal overflow if @var{x} is too large.
698 @deftypefun double tanh (double @var{x})
699 @deftypefunx float tanhf (float @var{x})
700 @deftypefunx {long double} tanhl (long double @var{x})
701 These functions return the hyperbolic tangent of @var{x},
702 defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
703 They may signal overflow if @var{x} is too large.
706 @cindex hyperbolic functions
708 There are counterparts for the hyperbolic functions which take
713 @deftypefun {complex double} csinh (complex double @var{z})
714 @deftypefunx {complex float} csinhf (complex float @var{z})
715 @deftypefunx {complex long double} csinhl (complex long double @var{z})
716 These functions return the complex hyperbolic sine of @var{z}, defined
717 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.
722 @deftypefun {complex double} ccosh (complex double @var{z})
723 @deftypefunx {complex float} ccoshf (complex float @var{z})
724 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
725 These functions return the complex hyperbolic cosine of @var{z}, defined
726 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.
731 @deftypefun {complex double} ctanh (complex double @var{z})
732 @deftypefunx {complex float} ctanhf (complex float @var{z})
733 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
734 These functions return the complex hyperbolic tangent of @var{z},
735 defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
739 @cindex inverse hyperbolic functions
743 @deftypefun double asinh (double @var{x})
744 @deftypefunx float asinhf (float @var{x})
745 @deftypefunx {long double} asinhl (long double @var{x})
746 These functions return the inverse hyperbolic sine of @var{x}---the
747 value whose hyperbolic sine is @var{x}.
752 @deftypefun double acosh (double @var{x})
753 @deftypefunx float acoshf (float @var{x})
754 @deftypefunx {long double} acoshl (long double @var{x})
755 These functions return the inverse hyperbolic cosine of @var{x}---the
756 value whose hyperbolic cosine is @var{x}. If @var{x} is less than
757 @code{1}, @code{acosh} signals a domain error.
762 @deftypefun double atanh (double @var{x})
763 @deftypefunx float atanhf (float @var{x})
764 @deftypefunx {long double} atanhl (long double @var{x})
765 These functions return the inverse hyperbolic tangent of @var{x}---the
766 value whose hyperbolic tangent is @var{x}. If the absolute value of
767 @var{x} is greater than @code{1}, @code{atanh} signals a domain error;
768 if it is equal to 1, @code{atanh} returns infinity.
771 @cindex inverse complex hyperbolic functions
775 @deftypefun {complex double} casinh (complex double @var{z})
776 @deftypefunx {complex float} casinhf (complex float @var{z})
777 @deftypefunx {complex long double} casinhl (complex long double @var{z})
778 These functions return the inverse complex hyperbolic sine of
779 @var{z}---the value whose complex hyperbolic sine is @var{z}.
784 @deftypefun {complex double} cacosh (complex double @var{z})
785 @deftypefunx {complex float} cacoshf (complex float @var{z})
786 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
787 These functions return the inverse complex hyperbolic cosine of
788 @var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike
789 the real-valued functions, there are no restrictions on the value of @var{z}.
794 @deftypefun {complex double} catanh (complex double @var{z})
795 @deftypefunx {complex float} catanhf (complex float @var{z})
796 @deftypefunx {complex long double} catanhl (complex long double @var{z})
797 These functions return the inverse complex hyperbolic tangent of
798 @var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike
799 the real-valued functions, there are no restrictions on the value of
803 @node Special Functions
804 @section Special Functions
805 @cindex special functions
806 @cindex Bessel functions
807 @cindex gamma function
809 These are some more exotic mathematical functions, which are sometimes
810 useful. Currently they only have real-valued versions.
814 @deftypefun double erf (double @var{x})
815 @deftypefunx float erff (float @var{x})
816 @deftypefunx {long double} erfl (long double @var{x})
817 @code{erf} returns the error function of @var{x}. The error
818 function is defined as
820 $$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$
824 erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
831 @deftypefun double erfc (double @var{x})
832 @deftypefunx float erfcf (float @var{x})
833 @deftypefunx {long double} erfcl (long double @var{x})
834 @code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
835 fashion that avoids round-off error when @var{x} is large.
840 @deftypefun double lgamma (double @var{x})
841 @deftypefunx float lgammaf (float @var{x})
842 @deftypefunx {long double} lgammal (long double @var{x})
843 @code{lgamma} returns the natural logarithm of the absolute value of
844 the gamma function of @var{x}. The gamma function is defined as
846 $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
850 gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
855 The sign of the gamma function is stored in the global variable
856 @var{signgam}, which is declared in @file{math.h}. It is @code{1} if
857 the intermediate result was positive or zero, and, @code{-1} if it was
860 You can compute the actual gamma function as follows:
863 gam = signgam*exp(lgam);
866 The gamma function has singularities at the nonpositive integers.
867 @code{lgamma} will raise the zero divide exception if evaluated at a
873 @deftypefun double lgamma_r (double @var{x}, int *@var{signp})
874 @deftypefunx float lgammaf_r (float @var{x}, int *@var{signp})
875 @deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp})
876 @code{lgamma_r} is just like @code{lgamma}, but it stores the sign of
877 the intermediate result in the variable pointed to by @var{signp}
878 instead of in the @var{signgam} global.
884 @deftypefun double gamma (double @var{x})
885 @deftypefunx float gammaf (float @var{x})
886 @deftypefunx {long double} gammal (long double @var{x})
887 ??? _not_ exp(lgamma())*signgam - historical?
893 @deftypefun double j0 (double @var{x})
894 @deftypefunx float j0f (float @var{x})
895 @deftypefunx {long double} j0l (long double @var{x})
896 @code{j0} returns the Bessel function of the first kind of order 0 of
897 @var{x}. It may signal underflow if @var{x} is too large.
902 @deftypefun double j1 (double @var{x})
903 @deftypefunx float j1f (float @var{x})
904 @deftypefunx {long double} j1l (long double @var{x})
905 @code{j1} returns the Bessel function of the first kind of order 1 of
906 @var{x}. It may signal underflow if @var{x} is too large.
911 @deftypefun double jn (int n, double @var{x})
912 @deftypefunx float jnf (int n, float @var{x})
913 @deftypefunx {long double} jnl (int n, long double @var{x})
914 @code{jn} returns the Bessel function of the first kind of order
915 @var{n} of @var{x}. It may signal underflow if @var{x} is too large.
920 @deftypefun double y0 (double @var{x})
921 @deftypefunx float y0f (float @var{x})
922 @deftypefunx {long double} y0l (long double @var{x})
923 @code{y0} returns the Bessel function of the second kind of order 0 of
924 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
925 is negative, @code{y0} signals a domain error; if it is zero,
926 @code{y0} signals overflow and returns @math{-@infinity}.
931 @deftypefun double y1 (double @var{x})
932 @deftypefunx float y1f (float @var{x})
933 @deftypefunx {long double} y1l (long double @var{x})
934 @code{y1} returns the Bessel function of the second kind of order 1 of
935 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
936 is negative, @code{y1} signals a domain error; if it is zero,
937 @code{y1} signals overflow and returns @math{-@infinity}.
942 @deftypefun double yn (int n, double @var{x})
943 @deftypefunx float ynf (int n, float @var{x})
944 @deftypefunx {long double} ynl (int n, long double @var{x})
945 @code{yn} returns the Bessel function of the second kind of order @var{n} of
946 @var{x}. It may signal underflow if @var{x} is too large. If @var{x}
947 is negative, @code{yn} signals a domain error; if it is zero,
948 @code{yn} signals overflow and returns @math{-@infinity}.
951 @node Pseudo-Random Numbers
952 @section Pseudo-Random Numbers
953 @cindex random numbers
954 @cindex pseudo-random numbers
955 @cindex seed (for random numbers)
957 This section describes the GNU facilities for generating a series of
958 pseudo-random numbers. The numbers generated are not truly random;
959 typically, they form a sequence that repeats periodically, with a period
960 so large that you can ignore it for ordinary purposes. The random
961 number generator works by remembering a @dfn{seed} value which it uses
962 to compute the next random number and also to compute a new seed.
964 Although the generated numbers look unpredictable within one run of a
965 program, the sequence of numbers is @emph{exactly the same} from one run
966 to the next. This is because the initial seed is always the same. This
967 is convenient when you are debugging a program, but it is unhelpful if
968 you want the program to behave unpredictably. If you want a different
969 pseudo-random series each time your program runs, you must specify a
970 different seed each time. For ordinary purposes, basing the seed on the
971 current time works well.
973 You can get repeatable sequences of numbers on a particular machine type
974 by specifying the same initial seed value for the random number
975 generator. There is no standard meaning for a particular seed value;
976 the same seed, used in different C libraries or on different CPU types,
977 will give you different random numbers.
979 The GNU library supports the standard @w{ISO C} random number functions
980 plus two other sets derived from BSD and SVID. The BSD and @w{ISO C}
981 functions provide identical, somewhat limited functionality. If only a
982 small number of random bits are required, we recommend you use the
983 @w{ISO C} interface, @code{rand} and @code{srand}. The SVID functions
984 provide a more flexible interface, which allows better random number
985 generator algorithms, provides more random bits (up to 48) per call, and
986 can provide random floating-point numbers. These functions are required
987 by the XPG standard and therefore will be present in all modern Unix
991 * ISO Random:: @code{rand} and friends.
992 * BSD Random:: @code{random} and friends.
993 * SVID Random:: @code{drand48} and friends.
997 @subsection ISO C Random Number Functions
999 This section describes the random number functions that are part of
1000 the @w{ISO C} standard.
1002 To use these facilities, you should include the header file
1003 @file{stdlib.h} in your program.
1008 @deftypevr Macro int RAND_MAX
1009 The value of this macro is an integer constant representing the largest
1010 value the @code{rand} function can return. In the GNU library, it is
1011 @code{2147483647}, which is the largest signed integer representable in
1012 32 bits. In other libraries, it may be as low as @code{32767}.
1017 @deftypefun int rand (void)
1018 The @code{rand} function returns the next pseudo-random number in the
1019 series. The value ranges from @code{0} to @code{RAND_MAX}.
1024 @deftypefun void srand (unsigned int @var{seed})
1025 This function establishes @var{seed} as the seed for a new series of
1026 pseudo-random numbers. If you call @code{rand} before a seed has been
1027 established with @code{srand}, it uses the value @code{1} as a default
1030 To produce a different pseudo-random series each time your program is
1031 run, do @code{srand (time (0))}.
1034 POSIX.1 extended the C standard functions to support reproducible random
1035 numbers in multi-threaded programs. However, the extension is badly
1036 designed and unsuitable for serious work.
1040 @deftypefun int rand_r (unsigned int *@var{seed})
1041 This function returns a random number in the range 0 to @code{RAND_MAX}
1042 just as @code{rand} does. However, all its state is stored in the
1043 @var{seed} argument. This means the RNG's state can only have as many
1044 bits as the type @code{unsigned int} has. This is far too few to
1047 If your program requires a reentrant RNG, we recommend you use the
1048 reentrant GNU extensions to the SVID random number generator. The
1049 POSIX.1 interface should only be used when the GNU extensions are not
1055 @subsection BSD Random Number Functions
1057 This section describes a set of random number generation functions that
1058 are derived from BSD. There is no advantage to using these functions
1059 with the GNU C library; we support them for BSD compatibility only.
1061 The prototypes for these functions are in @file{stdlib.h}.
1066 @deftypefun {int32_t} random (void)
1067 This function returns the next pseudo-random number in the sequence.
1068 The value returned ranges from @code{0} to @code{RAND_MAX}.
1070 @strong{Note:} Historically this function returned a @code{long
1071 int} value. On 64bit systems @code{long int} would have been larger
1072 than programs expected, so @code{random} is now defined to return
1078 @deftypefun void srandom (unsigned int @var{seed})
1079 The @code{srandom} function sets the state of the random number
1080 generator based on the integer @var{seed}. If you supply a @var{seed} value
1081 of @code{1}, this will cause @code{random} to reproduce the default set
1084 To produce a different set of pseudo-random numbers each time your
1085 program runs, do @code{srandom (time (0))}.
1090 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1091 The @code{initstate} function is used to initialize the random number
1092 generator state. The argument @var{state} is an array of @var{size}
1093 bytes, used to hold the state information. It is initialized based on
1094 @var{seed}. The size must be between 8 and 256 bytes, and should be a
1095 power of two. The bigger the @var{state} array, the better.
1097 The return value is the previous value of the state information array.
1098 You can use this value later as an argument to @code{setstate} to
1104 @deftypefun {void *} setstate (void *@var{state})
1105 The @code{setstate} function restores the random number state
1106 information @var{state}. The argument must have been the result of
1107 a previous call to @var{initstate} or @var{setstate}.
1109 The return value is the previous value of the state information array.
1110 You can use this value later as an argument to @code{setstate} to
1115 @subsection SVID Random Number Function
1117 The C library on SVID systems contains yet another kind of random number
1118 generator functions. They use a state of 48 bits of data. The user can
1119 choose among a collection of functions which return the random bits
1122 Generally there are two kinds of functions: those which use a state of
1123 the random number generator which is shared among several functions and
1124 by all threads of the process. The second group of functions require
1125 the user to handle the state.
1127 All functions have in common that they use the same congruential
1128 formula with the same constants. The formula is
1131 Y = (a * X + c) mod m
1135 where @var{X} is the state of the generator at the beginning and
1136 @var{Y} the state at the end. @code{a} and @code{c} are constants
1137 determining the way the generator work. By default they are
1140 a = 0x5DEECE66D = 25214903917
1145 but they can also be changed by the user. @code{m} is of course 2^48
1146 since the state consists of a 48 bit array.
1151 @deftypefun double drand48 (void)
1152 This function returns a @code{double} value in the range of @code{0.0}
1153 to @code{1.0} (exclusive). The random bits are determined by the global
1154 state of the random number generator in the C library.
1156 Since the @code{double} type according to @w{IEEE 754} has a 52 bit
1157 mantissa this means 4 bits are not initialized by the random number
1158 generator. These are (of course) chosen to be the least significant
1159 bits and they are initialized to @code{0}.
1164 @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
1165 This function returns a @code{double} value in the range of @code{0.0}
1166 to @code{1.0} (exclusive), similar to @code{drand48}. The argument is
1167 an array describing the state of the random number generator.
1169 This function can be called subsequently since it updates the array to
1170 guarantee random numbers. The array should have been initialized before
1171 using to get reproducible results.
1176 @deftypefun {long int} lrand48 (void)
1177 The @code{lrand48} functions return an integer value in the range of
1178 @code{0} to @code{2^31} (exclusive). Even if the size of the @code{long
1179 int} type can take more than 32 bits no higher numbers are returned.
1180 The random bits are determined by the global state of the random number
1181 generator in the C library.
1186 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
1187 This function is similar to the @code{lrand48} function in that it
1188 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1189 the state of the random number generator used to produce the random bits
1190 is determined by the array provided as the parameter to the function.
1192 The numbers in the array are afterwards updated so that subsequent calls
1193 to this function yield to different results (as it is expected by a
1194 random number generator). The array should have been initialized before
1195 the first call to get reproducible results.
1200 @deftypefun {long int} mrand48 (void)
1201 The @code{mrand48} function is similar to @code{lrand48}. The only
1202 difference is that the numbers returned are in the range @code{-2^31} to
1203 @code{2^31} (exclusive).
1208 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
1209 The @code{jrand48} function is similar to @code{nrand48}. The only
1210 difference is that the numbers returned are in the range @code{-2^31} to
1211 @code{2^31} (exclusive). For the @code{xsubi} parameter the same
1212 requirements are necessary.
1215 The internal state of the random number generator can be initialized in
1216 several ways. The functions differ in the completeness of the
1217 information provided.
1221 @deftypefun void srand48 (long int @var{seedval}))
1222 The @code{srand48} function sets the most significant 32 bits of the
1223 state internal state of the random number generator to the least
1224 significant 32 bits of the @var{seedval} parameter. The lower 16 bits
1225 are initialized to the value @code{0x330E}. Even if the @code{long
1226 int} type contains more the 32 bits only the lower 32 bits are used.
1228 Due to this limitation the initialization of the state using this
1229 function of not very useful. But it makes it easy to use a construct
1230 like @code{srand48 (time (0))}.
1232 A side-effect of this function is that the values @code{a} and @code{c}
1233 from the internal state, which are used in the congruential formula,
1234 are reset to the default values given above. This is of importance once
1235 the user called the @code{lcong48} function (see below).
1240 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
1241 The @code{seed48} function initializes all 48 bits of the state of the
1242 internal random number generator from the content of the parameter
1243 @var{seed16v}. Here the lower 16 bits of the first element of
1244 @var{see16v} initialize the least significant 16 bits of the internal
1245 state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
1246 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
1247 initialize the most significant 16 bits of the state.
1249 Unlike @code{srand48} this function lets the user initialize all 48 bits
1252 The value returned by @code{seed48} is a pointer to an array containing
1253 the values of the internal state before the change. This might be
1254 useful to restart the random number generator at a certain state.
1255 Otherwise, the value can simply be ignored.
1257 As for @code{srand48}, the values @code{a} and @code{c} from the
1258 congruential formula are reset to the default values.
1261 There is one more function to initialize the random number generator
1262 which allows to specify even more information by allowing to change the
1263 parameters in the congruential formula.
1267 @deftypefun void lcong48 (unsigned short int @var{param}[7])
1268 The @code{lcong48} function allows the user to change the complete state
1269 of the random number generator. Unlike @code{srand48} and
1270 @code{seed48}, this function also changes the constants in the
1271 congruential formula.
1273 From the seven elements in the array @var{param} the least significant
1274 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
1275 determine the initial state, the least 16 bits of
1276 @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
1277 constant @code{a} and @code{@var{param}[6]} determines the 16 bit value
1281 All the above functions have in common that they use the global
1282 parameters for the congruential formula. In multi-threaded programs it
1283 might sometimes be useful to have different parameters in different
1284 threads. For this reason all the above functions have a counterpart
1285 which works on a description of the random number generator in the
1286 user-supplied buffer instead of the global state.
1288 Please note that it is no problem if several threads use the global
1289 state if all threads use the functions which take a pointer to an array
1290 containing the state. The random numbers are computed following the
1291 same loop but if the state in the array is different all threads will
1292 get an individual random number generator.
1294 The user supplied buffer must be of type @code{struct drand48_data}.
1295 This type should be regarded as opaque and no member should be used
1300 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1301 This function is equivalent to the @code{drand48} function with the
1302 difference it does not modify the global random number generator
1303 parameters but instead the parameters is the buffer supplied by the
1304 buffer through the pointer @var{buffer}. The random number is return in
1305 the variable pointed to by @var{result}.
1307 The return value of the function indicate whether the call succeeded.
1308 If the value is less than @code{0} an error occurred and @var{errno} is
1309 set to indicate the problem.
1311 This function is a GNU extension and should not be used in portable
1317 @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
1318 The @code{erand48_r} function works like the @code{erand48} and it takes
1319 an argument @var{buffer} which describes the random number generator.
1320 The state of the random number generator is taken from the @code{xsubi}
1321 array, the parameters for the congruential formula from the global
1322 random number generator data. The random number is return in the
1323 variable pointed to by @var{result}.
1325 The return value is non-negative is the call succeeded.
1327 This function is a GNU extension and should not be used in portable
1333 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1334 This function is similar to @code{lrand48} and it takes a pointer to a
1335 buffer describing the state of the random number generator as a
1336 parameter just like @code{drand48}.
1338 If the return value of the function is non-negative the variable pointed
1339 to by @var{result} contains the result. Otherwise an error occurred.
1341 This function is a GNU extension and should not be used in portable
1347 @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1348 The @code{nrand48_r} function works like @code{nrand48} in that it
1349 produces a random number in range @code{0} to @code{2^31}. But instead
1350 of using the global parameters for the congruential formula it uses the
1351 information from the buffer pointed to by @var{buffer}. The state is
1352 described by the values in @var{xsubi}.
1354 If the return value is non-negative the variable pointed to by
1355 @var{result} contains the result.
1357 This function is a GNU extension and should not be used in portable
1363 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1364 This function is similar to @code{mrand48} but as the other reentrant
1365 function it uses the random number generator described by the value in
1366 the buffer pointed to by @var{buffer}.
1368 If the return value is non-negative the variable pointed to by
1369 @var{result} contains the result.
1371 This function is a GNU extension and should not be used in portable
1377 @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1378 The @code{jrand48_r} function is similar to @code{jrand48}. But as the
1379 other reentrant functions of this function family it uses the
1380 congruential formula parameters from the buffer pointed to by
1383 If the return value is non-negative the variable pointed to by
1384 @var{result} contains the result.
1386 This function is a GNU extension and should not be used in portable
1390 Before any of the above functions should be used the buffer of type
1391 @code{struct drand48_data} should initialized. The easiest way is to
1392 fill the whole buffer with null bytes, e.g., using
1395 memset (buffer, '\0', sizeof (struct drand48_data));
1399 Using any of the reentrant functions of this family now will
1400 automatically initialize the random number generator to the default
1401 values for the state and the parameters of the congruential formula.
1403 The other possibility is too use any of the functions which explicitely
1404 initialize the buffer. Though it might be obvious how to initialize the
1405 buffer from the data given as parameter from the function it is highly
1406 recommended to use these functions since the result might not always be
1411 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1412 The description of the random number generator represented by the
1413 information in @var{buffer} is initialized similar to what the function
1414 @code{srand48} does. The state is initialized from the parameter
1415 @var{seedval} and the parameters for the congruential formula are
1416 initialized to the default values.
1418 If the return value is non-negative the function call succeeded.
1420 This function is a GNU extension and should not be used in portable
1426 @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
1427 This function is similar to @code{srand48_r} but like @code{seed48} it
1428 initializes all 48 bits of the state from the parameter @var{seed16v}.
1430 If the return value is non-negative the function call succeeded. It
1431 does not return a pointer to the previous state of the random number
1432 generator like the @code{seed48} function does. if the user wants to
1433 preserve the state for a later rerun s/he can copy the whole buffer
1434 pointed to by @var{buffer}.
1436 This function is a GNU extension and should not be used in portable
1442 @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
1443 This function initializes all aspects of the random number generator
1444 described in @var{buffer} by the data in @var{param}. Here it is
1445 especially true the function does more than just copying the contents of
1446 @var{param} of @var{buffer}. Some more actions are required and
1447 therefore it is important to use this function and not initialized the
1448 random number generator directly.
1450 If the return value is non-negative the function call succeeded.
1452 This function is a GNU extension and should not be used in portable
1456 @node FP Function Optimizations
1457 @section Is Fast Code or Small Code preferred?
1458 @cindex Optimization
1460 If an application uses many floating point function it is often the case
1461 that the costs for the function calls itselfs are not neglectable.
1462 Modern processor implementation often can execute the operation itself
1463 very fast but the call means a disturbance of the control flow.
1465 For this reason the GNU C Library provides optimizations for many of the
1466 frequently used math functions. When the GNU CC is used and the user
1467 activates the optimizer several new inline functions and macros get
1468 defined. These new functions and macros have the same names as the
1469 library function and so get used instead of the later. In case of
1470 inline functions the compiler will decide whether it is reasonable to
1471 use the inline function and this decision is usually correct.
1473 For the generated code this means that no calls to the library functions
1474 are necessary. This increases the speed significantly. But the
1475 drawback is that the code size increases and this increase is not always
1478 In cases where the inline functions and macros are not wanted the symbol
1479 @code{__NO_MATH_INLINES} should be defined before any system header is
1480 included. This will make sure only library functions are used. Of
1481 course it can be determined for each single file in the project whether
1482 giving this option is preferred or not.
1484 Not all hardware implements the entire @w{IEEE 754} standard, or if it
1485 does, there may be a substantial performance penalty for using some of
1486 its features. For example, enabling traps on some processors forces
1487 the FPU to run unpipelined, which more than doubles calculation time.
1488 @c ***Add explanation of -lieee, -mieee.