7ebcddee3f468dd3c29d9d6f917bfb5de3640386
1 @c We need some definitions here.
2 @ifclear mult
3 @ifhtml
4 @set mult &middot;
5 @set infty &infin;
6 @set pie &pi;
7 @end ifhtml
8 @iftex
9 @set mult @cdot
10 @set infty @infty
11 @end iftex
12 @ifclear mult
13 @set mult *
14 @set infty oo
15 @set pie pi
16 @end ifclear
17 @macro mul
18 @value{mult}
19 @end macro
20 @macro infinity
21 @value{infty}
22 @end macro
23 @ifnottex
24 @macro pi
25 @value{pie}
26 @end macro
27 @end ifnottex
28 @end ifclear
30 @node Mathematics, Arithmetic, Syslog, Top
31 @c %MENU% Math functions, useful constants, random numbers
32 @chapter Mathematics
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
38 @file{complex.h}.
39 @pindex math.h
40 @pindex complex.h
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
58                                  constants.
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
66                                  numbers.
67 * FP Function Optimizations::   Fast code or small code.
70 @node Mathematical Constants
71 @section Predefined Mathematical Constants
72 @cindex 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:
79 @vtable @code
80 @item M_E
81 The base of natural logarithms.
82 @item M_LOG2E
83 The logarithm to base @code{2} of @code{M_E}.
84 @item M_LOG10E
85 The logarithm to base @code{10} of @code{M_E}.
86 @item M_LN2
87 The natural logarithm of @code{2}.
88 @item M_LN10
89 The natural logarithm of @code{10}.
90 @item M_PI
91 Pi, the ratio of a circle's circumference to its diameter.
92 @item M_PI_2
93 Pi divided by two.
94 @item M_PI_4
95 Pi divided by four.
96 @item M_1_PI
97 The reciprocal of pi (1/pi)
98 @item M_2_PI
99 Two times the reciprocal of pi.
100 @item M_2_SQRTPI
101 Two times the reciprocal of the square root of pi.
102 @item M_SQRT2
103 The square root of two.
104 @item M_SQRT1_2
105 The reciprocal of the square root of two (also the square root of 1/2).
106 @end vtable
108 These constants come from the Unix98 standard and were also available in
109 4.4BSD; therefore they are only defined if @code{_BSD_SOURCE} or
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, the GNU C
115 library 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.
120 @vindex PI
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 the GNU C library
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.
129 @node Trig Functions
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
141 yourself:
143 @smallexample
144 #define M_PI 3.14159265358979323846264338327
145 @end smallexample
147 @noindent
148 You can also compute the value of pi with the expression @code{acos
149 (-1.0)}.
151 @comment math.h
152 @comment ISO
153 @deftypefun double sin (double @var{x})
154 @comment math.h
155 @comment ISO
156 @deftypefunx float sinf (float @var{x})
157 @comment math.h
158 @comment ISO
159 @deftypefunx {long double} sinl (long double @var{x})
160 These functions return the sine of @var{x}, where @var{x} is given in
161 radians.  The return value is in the range @code{-1} to @code{1}.
162 @end deftypefun
164 @comment math.h
165 @comment ISO
166 @deftypefun double cos (double @var{x})
167 @comment math.h
168 @comment ISO
169 @deftypefunx float cosf (float @var{x})
170 @comment math.h
171 @comment ISO
172 @deftypefunx {long double} cosl (long double @var{x})
173 These functions return the cosine of @var{x}, where @var{x} is given in
174 radians.  The return value is in the range @code{-1} to @code{1}.
175 @end deftypefun
177 @comment math.h
178 @comment ISO
179 @deftypefun double tan (double @var{x})
180 @comment math.h
181 @comment ISO
182 @deftypefunx float tanf (float @var{x})
183 @comment math.h
184 @comment ISO
185 @deftypefunx {long double} tanl (long double @var{x})
186 These functions return the tangent of @var{x}, where @var{x} is given in
189 Mathematically, the tangent function has singularities at odd multiples
190 of pi/2.  If the argument @var{x} is too close to one of these
191 singularities, @code{tan} will signal overflow.
192 @end deftypefun
194 In many applications where @code{sin} and @code{cos} are used, the sine
195 and cosine of the same angle are needed at the same time.  It is more
196 efficient to compute them simultaneously, so the library provides a
197 function to do that.
199 @comment math.h
200 @comment GNU
201 @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
202 @comment math.h
203 @comment GNU
204 @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
205 @comment math.h
206 @comment GNU
207 @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
208 These functions return the sine of @var{x} in @code{*@var{sinx}} and the
209 cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
210 radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
211 the range of @code{-1} to @code{1}.
213 This function is a GNU extension.  Portable programs should be prepared
214 to cope with its absence.
215 @end deftypefun
217 @cindex complex trigonometric functions
219 @w{ISO C99} defines variants of the trig functions which work on
220 complex numbers.  The GNU C library provides these functions, but they
221 are only useful if your compiler supports the new complex types defined
222 by the standard.
223 @c XXX Change this when gcc is fixed. -zw
224 (As of this writing GCC supports complex numbers, but there are bugs in
225 the implementation.)
227 @comment complex.h
228 @comment ISO
229 @deftypefun {complex double} csin (complex double @var{z})
230 @comment complex.h
231 @comment ISO
232 @deftypefunx {complex float} csinf (complex float @var{z})
233 @comment complex.h
234 @comment ISO
235 @deftypefunx {complex long double} csinl (complex long double @var{z})
236 These functions return the complex sine of @var{z}.
237 The mathematical definition of the complex sine is
239 @ifnottex
240 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
241 @end ifnottex
242 @tex
243 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
244 @end tex
245 @end deftypefun
247 @comment complex.h
248 @comment ISO
249 @deftypefun {complex double} ccos (complex double @var{z})
250 @comment complex.h
251 @comment ISO
252 @deftypefunx {complex float} ccosf (complex float @var{z})
253 @comment complex.h
254 @comment ISO
255 @deftypefunx {complex long double} ccosl (complex long double @var{z})
256 These functions return the complex cosine of @var{z}.
257 The mathematical definition of the complex cosine is
259 @ifnottex
260 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
261 @end ifnottex
262 @tex
263 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
264 @end tex
265 @end deftypefun
267 @comment complex.h
268 @comment ISO
269 @deftypefun {complex double} ctan (complex double @var{z})
270 @comment complex.h
271 @comment ISO
272 @deftypefunx {complex float} ctanf (complex float @var{z})
273 @comment complex.h
274 @comment ISO
275 @deftypefunx {complex long double} ctanl (complex long double @var{z})
276 These functions return the complex tangent of @var{z}.
277 The mathematical definition of the complex tangent is
279 @ifnottex
280 @math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
281 @end ifnottex
282 @tex
283 $$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
284 @end tex
286 @noindent
287 The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an
288 integer.  @code{ctan} may signal overflow if @var{z} is too close to a
289 pole.
290 @end deftypefun
293 @node Inverse Trig Functions
294 @section Inverse Trigonometric Functions
295 @cindex inverse trigonometric functions
297 These are the usual arc sine, arc cosine and arc tangent functions,
298 which are the inverses of the sine, cosine and tangent functions
299 respectively.
301 @comment math.h
302 @comment ISO
303 @deftypefun double asin (double @var{x})
304 @comment math.h
305 @comment ISO
306 @deftypefunx float asinf (float @var{x})
307 @comment math.h
308 @comment ISO
309 @deftypefunx {long double} asinl (long double @var{x})
310 These functions compute the arc sine of @var{x}---that is, the value whose
311 sine is @var{x}.  The value is in units of radians.  Mathematically,
312 there are infinitely many such values; the one actually returned is the
313 one between @code{-pi/2} and @code{pi/2} (inclusive).
315 The arc sine function is defined mathematically only
316 over the domain @code{-1} to @code{1}.  If @var{x} is outside the
317 domain, @code{asin} signals a domain error.
318 @end deftypefun
320 @comment math.h
321 @comment ISO
322 @deftypefun double acos (double @var{x})
323 @comment math.h
324 @comment ISO
325 @deftypefunx float acosf (float @var{x})
326 @comment math.h
327 @comment ISO
328 @deftypefunx {long double} acosl (long double @var{x})
329 These functions compute the arc cosine of @var{x}---that is, the value
330 whose cosine is @var{x}.  The value is in units of radians.
331 Mathematically, there are infinitely many such values; the one actually
332 returned is the one between @code{0} and @code{pi} (inclusive).
334 The arc cosine function is defined mathematically only
335 over the domain @code{-1} to @code{1}.  If @var{x} is outside the
336 domain, @code{acos} signals a domain error.
337 @end deftypefun
339 @comment math.h
340 @comment ISO
341 @deftypefun double atan (double @var{x})
342 @comment math.h
343 @comment ISO
344 @deftypefunx float atanf (float @var{x})
345 @comment math.h
346 @comment ISO
347 @deftypefunx {long double} atanl (long double @var{x})
348 These functions compute the arc tangent of @var{x}---that is, the value
349 whose tangent is @var{x}.  The value is in units of radians.
350 Mathematically, there are infinitely many such values; the one actually
351 returned is the one between @code{-pi/2} and @code{pi/2} (inclusive).
352 @end deftypefun
354 @comment math.h
355 @comment ISO
356 @deftypefun double atan2 (double @var{y}, double @var{x})
357 @comment math.h
358 @comment ISO
359 @deftypefunx float atan2f (float @var{y}, float @var{x})
360 @comment math.h
361 @comment ISO
362 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
363 This function computes the arc tangent of @var{y}/@var{x}, but the signs
364 of both arguments are used to determine the quadrant of the result, and
365 @var{x} is permitted to be zero.  The return value is given in radians
366 and is in the range @code{-pi} to @code{pi}, inclusive.
368 If @var{x} and @var{y} are coordinates of a point in the plane,
369 @code{atan2} returns the signed angle between the line from the origin
370 to that point and the x-axis.  Thus, @code{atan2} is useful for
371 converting Cartesian coordinates to polar coordinates.  (To compute the
372 radial coordinate, use @code{hypot}; see @ref{Exponents and
373 Logarithms}.)
375 @c This is experimentally true.  Should it be so? -zw
376 If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
377 @end deftypefun
379 @cindex inverse complex trigonometric functions
380 @w{ISO C99} defines complex versions of the inverse trig functions.
382 @comment complex.h
383 @comment ISO
384 @deftypefun {complex double} casin (complex double @var{z})
385 @comment complex.h
386 @comment ISO
387 @deftypefunx {complex float} casinf (complex float @var{z})
388 @comment complex.h
389 @comment ISO
390 @deftypefunx {complex long double} casinl (complex long double @var{z})
391 These functions compute the complex arc sine of @var{z}---that is, the
392 value whose sine is @var{z}.  The value returned is in radians.
394 Unlike the real-valued functions, @code{casin} is defined for all
395 values of @var{z}.
396 @end deftypefun
398 @comment complex.h
399 @comment ISO
400 @deftypefun {complex double} cacos (complex double @var{z})
401 @comment complex.h
402 @comment ISO
403 @deftypefunx {complex float} cacosf (complex float @var{z})
404 @comment complex.h
405 @comment ISO
406 @deftypefunx {complex long double} cacosl (complex long double @var{z})
407 These functions compute the complex arc cosine of @var{z}---that is, the
408 value whose cosine is @var{z}.  The value returned is in radians.
410 Unlike the real-valued functions, @code{cacos} is defined for all
411 values of @var{z}.
412 @end deftypefun
415 @comment complex.h
416 @comment ISO
417 @deftypefun {complex double} catan (complex double @var{z})
418 @comment complex.h
419 @comment ISO
420 @deftypefunx {complex float} catanf (complex float @var{z})
421 @comment complex.h
422 @comment ISO
423 @deftypefunx {complex long double} catanl (complex long double @var{z})
424 These functions compute the complex arc tangent of @var{z}---that is,
425 the value whose tangent is @var{z}.  The value is in units of radians.
426 @end deftypefun
429 @node Exponents and Logarithms
430 @section Exponentiation and Logarithms
431 @cindex exponentiation functions
432 @cindex power functions
433 @cindex logarithm functions
435 @comment math.h
436 @comment ISO
437 @deftypefun double exp (double @var{x})
438 @comment math.h
439 @comment ISO
440 @deftypefunx float expf (float @var{x})
441 @comment math.h
442 @comment ISO
443 @deftypefunx {long double} expl (long double @var{x})
444 These functions compute @code{e} (the base of natural logarithms) raised
445 to the power @var{x}.
447 If the magnitude of the result is too large to be representable,
448 @code{exp} signals overflow.
449 @end deftypefun
451 @comment math.h
452 @comment ISO
453 @deftypefun double exp2 (double @var{x})
454 @comment math.h
455 @comment ISO
456 @deftypefunx float exp2f (float @var{x})
457 @comment math.h
458 @comment ISO
459 @deftypefunx {long double} exp2l (long double @var{x})
460 These functions compute @code{2} raised to the power @var{x}.
461 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
462 @end deftypefun
464 @comment math.h
465 @comment GNU
466 @deftypefun double exp10 (double @var{x})
467 @comment math.h
468 @comment GNU
469 @deftypefunx float exp10f (float @var{x})
470 @comment math.h
471 @comment GNU
472 @deftypefunx {long double} exp10l (long double @var{x})
473 @comment math.h
474 @comment GNU
475 @deftypefunx double pow10 (double @var{x})
476 @comment math.h
477 @comment GNU
478 @deftypefunx float pow10f (float @var{x})
479 @comment math.h
480 @comment GNU
481 @deftypefunx {long double} pow10l (long double @var{x})
482 These functions compute @code{10} raised to the power @var{x}.
483 Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
485 These functions are GNU extensions.  The name @code{exp10} is
486 preferred, since it is analogous to @code{exp} and @code{exp2}.
487 @end deftypefun
490 @comment math.h
491 @comment ISO
492 @deftypefun double log (double @var{x})
493 @comment math.h
494 @comment ISO
495 @deftypefunx float logf (float @var{x})
496 @comment math.h
497 @comment ISO
498 @deftypefunx {long double} logl (long double @var{x})
499 These functions compute the natural logarithm of @var{x}.  @code{exp (log
500 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
501 C.
503 If @var{x} is negative, @code{log} signals a domain error.  If @var{x}
504 is zero, it returns negative infinity; if @var{x} is too close to zero,
505 it may signal overflow.
506 @end deftypefun
508 @comment math.h
509 @comment ISO
510 @deftypefun double log10 (double @var{x})
511 @comment math.h
512 @comment ISO
513 @deftypefunx float log10f (float @var{x})
514 @comment math.h
515 @comment ISO
516 @deftypefunx {long double} log10l (long double @var{x})
517 These functions return the base-10 logarithm of @var{x}.
518 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
520 @end deftypefun
522 @comment math.h
523 @comment ISO
524 @deftypefun double log2 (double @var{x})
525 @comment math.h
526 @comment ISO
527 @deftypefunx float log2f (float @var{x})
528 @comment math.h
529 @comment ISO
530 @deftypefunx {long double} log2l (long double @var{x})
531 These functions return the base-2 logarithm of @var{x}.
532 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
533 @end deftypefun
535 @comment math.h
536 @comment ISO
537 @deftypefun double logb (double @var{x})
538 @comment math.h
539 @comment ISO
540 @deftypefunx float logbf (float @var{x})
541 @comment math.h
542 @comment ISO
543 @deftypefunx {long double} logbl (long double @var{x})
544 These functions extract the exponent of @var{x} and return it as a
545 floating-point value.  If @code{FLT_RADIX} is two, @code{logb} is equal
546 to @code{floor (log2 (x))}, except it's probably faster.
548 If @var{x} is de-normalized, @code{logb} returns the exponent @var{x}
549 would have if it were normalized.  If @var{x} is infinity (positive or
550 negative), @code{logb} returns @math{@infinity{}}.  If @var{x} is zero,
551 @code{logb} returns @math{@infinity{}}.  It does not signal.
552 @end deftypefun
554 @comment math.h
555 @comment ISO
556 @deftypefun int ilogb (double @var{x})
557 @comment math.h
558 @comment ISO
559 @deftypefunx int ilogbf (float @var{x})
560 @comment math.h
561 @comment ISO
562 @deftypefunx int ilogbl (long double @var{x})
563 These functions are equivalent to the corresponding @code{logb}
564 functions except that they return signed integer values.
565 @end deftypefun
567 @noindent
568 Since integers cannot represent infinity and NaN, @code{ilogb} instead
569 returns an integer that can't be the exponent of a normal floating-point
570 number.  @file{math.h} defines constants so you can check for this.
572 @comment math.h
573 @comment ISO
574 @deftypevr Macro int FP_ILOGB0
575 @code{ilogb} returns this value if its argument is @code{0}.  The
576 numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
578 This macro is defined in @w{ISO C99}.
579 @end deftypevr
581 @comment math.h
582 @comment ISO
583 @deftypevr Macro int FP_ILOGBNAN
584 @code{ilogb} returns this value if its argument is @code{NaN}.  The
585 numeric value is either @code{INT_MIN} or @code{INT_MAX}.
587 This macro is defined in @w{ISO C99}.
588 @end deftypevr
590 These values are system specific.  They might even be the same.  The
591 proper way to test the result of @code{ilogb} is as follows:
593 @smallexample
594 i = ilogb (f);
595 if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
596   @{
597     if (isnan (f))
598       @{
599         /* @r{Handle NaN.}  */
600       @}
601     else if (f  == 0.0)
602       @{
603         /* @r{Handle 0.0.}  */
604       @}
605     else
606       @{
607         /* @r{Some other value with large exponent,}
608            @r{perhaps +Inf.}  */
609       @}
610   @}
611 @end smallexample
613 @comment math.h
614 @comment ISO
615 @deftypefun double pow (double @var{base}, double @var{power})
616 @comment math.h
617 @comment ISO
618 @deftypefunx float powf (float @var{base}, float @var{power})
619 @comment math.h
620 @comment ISO
621 @deftypefunx {long double} powl (long double @var{base}, long double @var{power})
622 These are general exponentiation functions, returning @var{base} raised
623 to @var{power}.
625 Mathematically, @code{pow} would return a complex number when @var{base}
626 is negative and @var{power} is not an integral value.  @code{pow} can't
627 do that, so instead it signals a domain error. @code{pow} may also
628 underflow or overflow the destination type.
629 @end deftypefun
631 @cindex square root function
632 @comment math.h
633 @comment ISO
634 @deftypefun double sqrt (double @var{x})
635 @comment math.h
636 @comment ISO
637 @deftypefunx float sqrtf (float @var{x})
638 @comment math.h
639 @comment ISO
640 @deftypefunx {long double} sqrtl (long double @var{x})
641 These functions return the nonnegative square root of @var{x}.
643 If @var{x} is negative, @code{sqrt} signals a domain error.
644 Mathematically, it should return a complex number.
645 @end deftypefun
647 @cindex cube root function
648 @comment math.h
649 @comment BSD
650 @deftypefun double cbrt (double @var{x})
651 @comment math.h
652 @comment BSD
653 @deftypefunx float cbrtf (float @var{x})
654 @comment math.h
655 @comment BSD
656 @deftypefunx {long double} cbrtl (long double @var{x})
657 These functions return the cube root of @var{x}.  They cannot
658 fail; every representable real value has a representable real cube root.
659 @end deftypefun
661 @comment math.h
662 @comment ISO
663 @deftypefun double hypot (double @var{x}, double @var{y})
664 @comment math.h
665 @comment ISO
666 @deftypefunx float hypotf (float @var{x}, float @var{y})
667 @comment math.h
668 @comment ISO
669 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
670 These functions return @code{sqrt (@var{x}*@var{x} +
671 @var{y}*@var{y})}.  This is the length of the hypotenuse of a right
672 triangle with sides of length @var{x} and @var{y}, or the distance
673 of the point (@var{x}, @var{y}) from the origin.  Using this function
674 instead of the direct formula is wise, since the error is
675 much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
676 @end deftypefun
678 @comment math.h
679 @comment ISO
680 @deftypefun double expm1 (double @var{x})
681 @comment math.h
682 @comment ISO
683 @deftypefunx float expm1f (float @var{x})
684 @comment math.h
685 @comment ISO
686 @deftypefunx {long double} expm1l (long double @var{x})
687 These functions return a value equivalent to @code{exp (@var{x}) - 1}.
688 They are computed in a way that is accurate even if @var{x} is
689 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate owing
690 to subtraction of two numbers that are nearly equal.
691 @end deftypefun
693 @comment math.h
694 @comment ISO
695 @deftypefun double log1p (double @var{x})
696 @comment math.h
697 @comment ISO
698 @deftypefunx float log1pf (float @var{x})
699 @comment math.h
700 @comment ISO
701 @deftypefunx {long double} log1pl (long double @var{x})
702 These functions returns a value equivalent to @w{@code{log (1 + @var{x})}}.
703 They are computed in a way that is accurate even if @var{x} is
704 near zero.
705 @end deftypefun
707 @cindex complex exponentiation functions
708 @cindex complex logarithm functions
710 @w{ISO C99} defines complex variants of some of the exponentiation and
711 logarithm functions.
713 @comment complex.h
714 @comment ISO
715 @deftypefun {complex double} cexp (complex double @var{z})
716 @comment complex.h
717 @comment ISO
718 @deftypefunx {complex float} cexpf (complex float @var{z})
719 @comment complex.h
720 @comment ISO
721 @deftypefunx {complex long double} cexpl (complex long double @var{z})
722 These functions return @code{e} (the base of natural
723 logarithms) raised to the power of @var{z}.
724 Mathematically, this corresponds to the value
726 @ifnottex
727 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
728 @end ifnottex
729 @tex
730 $$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
731 @end tex
732 @end deftypefun
734 @comment complex.h
735 @comment ISO
736 @deftypefun {complex double} clog (complex double @var{z})
737 @comment complex.h
738 @comment ISO
739 @deftypefunx {complex float} clogf (complex float @var{z})
740 @comment complex.h
741 @comment ISO
742 @deftypefunx {complex long double} clogl (complex long double @var{z})
743 These functions return the natural logarithm of @var{z}.
744 Mathematically, this corresponds to the value
746 @ifnottex
747 @math{log (z) = log (cabs (z)) + I * carg (z)}
748 @end ifnottex
749 @tex
750 $$\log(z) = \log |z| + i \arg z$$
751 @end tex
753 @noindent
754 @code{clog} has a pole at 0, and will signal overflow if @var{z} equals
755 or is very close to 0.  It is well-defined for all other values of
756 @var{z}.
757 @end deftypefun
760 @comment complex.h
761 @comment GNU
762 @deftypefun {complex double} clog10 (complex double @var{z})
763 @comment complex.h
764 @comment GNU
765 @deftypefunx {complex float} clog10f (complex float @var{z})
766 @comment complex.h
767 @comment GNU
768 @deftypefunx {complex long double} clog10l (complex long double @var{z})
769 These functions return the base 10 logarithm of the complex value
770 @var{z}. Mathematically, this corresponds to the value
772 @ifnottex
773 @math{log (z) = log10 (cabs (z)) + I * carg (z)}
774 @end ifnottex
775 @tex
776 $$\log_{10}(z) = \log_{10}|z| + i \arg z$$
777 @end tex
779 These functions are GNU extensions.
780 @end deftypefun
782 @comment complex.h
783 @comment ISO
784 @deftypefun {complex double} csqrt (complex double @var{z})
785 @comment complex.h
786 @comment ISO
787 @deftypefunx {complex float} csqrtf (complex float @var{z})
788 @comment complex.h
789 @comment ISO
790 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
791 These functions return the complex square root of the argument @var{z}.  Unlike
792 the real-valued functions, they are defined for all values of @var{z}.
793 @end deftypefun
795 @comment complex.h
796 @comment ISO
797 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
798 @comment complex.h
799 @comment ISO
800 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
801 @comment complex.h
802 @comment ISO
803 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
804 These functions return @var{base} raised to the power of
805 @var{power}.  This is equivalent to @w{@code{cexp (y * clog (x))}}
806 @end deftypefun
808 @node Hyperbolic Functions
809 @section Hyperbolic Functions
810 @cindex hyperbolic functions
812 The functions in this section are related to the exponential functions;
813 see @ref{Exponents and Logarithms}.
815 @comment math.h
816 @comment ISO
817 @deftypefun double sinh (double @var{x})
818 @comment math.h
819 @comment ISO
820 @deftypefunx float sinhf (float @var{x})
821 @comment math.h
822 @comment ISO
823 @deftypefunx {long double} sinhl (long double @var{x})
824 These functions return the hyperbolic sine of @var{x}, defined
825 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  They
826 may signal overflow if @var{x} is too large.
827 @end deftypefun
829 @comment math.h
830 @comment ISO
831 @deftypefun double cosh (double @var{x})
832 @comment math.h
833 @comment ISO
834 @deftypefunx float coshf (float @var{x})
835 @comment math.h
836 @comment ISO
837 @deftypefunx {long double} coshl (long double @var{x})
838 These function return the hyperbolic cosine of @var{x},
839 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
840 They may signal overflow if @var{x} is too large.
841 @end deftypefun
843 @comment math.h
844 @comment ISO
845 @deftypefun double tanh (double @var{x})
846 @comment math.h
847 @comment ISO
848 @deftypefunx float tanhf (float @var{x})
849 @comment math.h
850 @comment ISO
851 @deftypefunx {long double} tanhl (long double @var{x})
852 These functions return the hyperbolic tangent of @var{x},
853 defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
854 They may signal overflow if @var{x} is too large.
855 @end deftypefun
857 @cindex hyperbolic functions
859 There are counterparts for the hyperbolic functions which take
860 complex arguments.
862 @comment complex.h
863 @comment ISO
864 @deftypefun {complex double} csinh (complex double @var{z})
865 @comment complex.h
866 @comment ISO
867 @deftypefunx {complex float} csinhf (complex float @var{z})
868 @comment complex.h
869 @comment ISO
870 @deftypefunx {complex long double} csinhl (complex long double @var{z})
871 These functions return the complex hyperbolic sine of @var{z}, defined
872 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.
873 @end deftypefun
875 @comment complex.h
876 @comment ISO
877 @deftypefun {complex double} ccosh (complex double @var{z})
878 @comment complex.h
879 @comment ISO
880 @deftypefunx {complex float} ccoshf (complex float @var{z})
881 @comment complex.h
882 @comment ISO
883 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
884 These functions return the complex hyperbolic cosine of @var{z}, defined
885 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.
886 @end deftypefun
888 @comment complex.h
889 @comment ISO
890 @deftypefun {complex double} ctanh (complex double @var{z})
891 @comment complex.h
892 @comment ISO
893 @deftypefunx {complex float} ctanhf (complex float @var{z})
894 @comment complex.h
895 @comment ISO
896 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
897 These functions return the complex hyperbolic tangent of @var{z},
898 defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
899 @end deftypefun
902 @cindex inverse hyperbolic functions
904 @comment math.h
905 @comment ISO
906 @deftypefun double asinh (double @var{x})
907 @comment math.h
908 @comment ISO
909 @deftypefunx float asinhf (float @var{x})
910 @comment math.h
911 @comment ISO
912 @deftypefunx {long double} asinhl (long double @var{x})
913 These functions return the inverse hyperbolic sine of @var{x}---the
914 value whose hyperbolic sine is @var{x}.
915 @end deftypefun
917 @comment math.h
918 @comment ISO
919 @deftypefun double acosh (double @var{x})
920 @comment math.h
921 @comment ISO
922 @deftypefunx float acoshf (float @var{x})
923 @comment math.h
924 @comment ISO
925 @deftypefunx {long double} acoshl (long double @var{x})
926 These functions return the inverse hyperbolic cosine of @var{x}---the
927 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
928 @code{1}, @code{acosh} signals a domain error.
929 @end deftypefun
931 @comment math.h
932 @comment ISO
933 @deftypefun double atanh (double @var{x})
934 @comment math.h
935 @comment ISO
936 @deftypefunx float atanhf (float @var{x})
937 @comment math.h
938 @comment ISO
939 @deftypefunx {long double} atanhl (long double @var{x})
940 These functions return the inverse hyperbolic tangent of @var{x}---the
941 value whose hyperbolic tangent is @var{x}.  If the absolute value of
942 @var{x} is greater than @code{1}, @code{atanh} signals a domain error;
943 if it is equal to 1, @code{atanh} returns infinity.
944 @end deftypefun
946 @cindex inverse complex hyperbolic functions
948 @comment complex.h
949 @comment ISO
950 @deftypefun {complex double} casinh (complex double @var{z})
951 @comment complex.h
952 @comment ISO
953 @deftypefunx {complex float} casinhf (complex float @var{z})
954 @comment complex.h
955 @comment ISO
956 @deftypefunx {complex long double} casinhl (complex long double @var{z})
957 These functions return the inverse complex hyperbolic sine of
958 @var{z}---the value whose complex hyperbolic sine is @var{z}.
959 @end deftypefun
961 @comment complex.h
962 @comment ISO
963 @deftypefun {complex double} cacosh (complex double @var{z})
964 @comment complex.h
965 @comment ISO
966 @deftypefunx {complex float} cacoshf (complex float @var{z})
967 @comment complex.h
968 @comment ISO
969 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
970 These functions return the inverse complex hyperbolic cosine of
971 @var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
972 the real-valued functions, there are no restrictions on the value of @var{z}.
973 @end deftypefun
975 @comment complex.h
976 @comment ISO
977 @deftypefun {complex double} catanh (complex double @var{z})
978 @comment complex.h
979 @comment ISO
980 @deftypefunx {complex float} catanhf (complex float @var{z})
981 @comment complex.h
982 @comment ISO
983 @deftypefunx {complex long double} catanhl (complex long double @var{z})
984 These functions return the inverse complex hyperbolic tangent of
985 @var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
986 the real-valued functions, there are no restrictions on the value of
987 @var{z}.
988 @end deftypefun
990 @node Special Functions
991 @section Special Functions
992 @cindex special functions
993 @cindex Bessel functions
994 @cindex gamma function
996 These are some more exotic mathematical functions which are sometimes
997 useful.  Currently they only have real-valued versions.
999 @comment math.h
1000 @comment SVID
1001 @deftypefun double erf (double @var{x})
1002 @comment math.h
1003 @comment SVID
1004 @deftypefunx float erff (float @var{x})
1005 @comment math.h
1006 @comment SVID
1007 @deftypefunx {long double} erfl (long double @var{x})
1008 @code{erf} returns the error function of @var{x}.  The error
1009 function is defined as
1010 @tex
1011 $$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$
1012 @end tex
1013 @ifnottex
1014 @smallexample
1015 erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
1016 @end smallexample
1017 @end ifnottex
1018 @end deftypefun
1020 @comment math.h
1021 @comment SVID
1022 @deftypefun double erfc (double @var{x})
1023 @comment math.h
1024 @comment SVID
1025 @deftypefunx float erfcf (float @var{x})
1026 @comment math.h
1027 @comment SVID
1028 @deftypefunx {long double} erfcl (long double @var{x})
1029 @code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
1030 fashion that avoids round-off error when @var{x} is large.
1031 @end deftypefun
1033 @comment math.h
1034 @comment SVID
1035 @deftypefun double lgamma (double @var{x})
1036 @comment math.h
1037 @comment SVID
1038 @deftypefunx float lgammaf (float @var{x})
1039 @comment math.h
1040 @comment SVID
1041 @deftypefunx {long double} lgammal (long double @var{x})
1042 @code{lgamma} returns the natural logarithm of the absolute value of
1043 the gamma function of @var{x}.  The gamma function is defined as
1044 @tex
1045 $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
1046 @end tex
1047 @ifnottex
1048 @smallexample
1049 gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
1050 @end smallexample
1051 @end ifnottex
1053 @vindex signgam
1054 The sign of the gamma function is stored in the global variable
1055 @var{signgam}, which is declared in @file{math.h}.  It is @code{1} if
1056 the intermediate result was positive or zero, or @code{-1} if it was
1057 negative.
1059 To compute the real gamma function you can use the @code{tgamma}
1060 function or you can compute the values as follows:
1061 @smallexample
1062 lgam = lgamma(x);
1063 gam  = signgam*exp(lgam);
1064 @end smallexample
1066 The gamma function has singularities at the non-positive integers.
1067 @code{lgamma} will raise the zero divide exception if evaluated at a
1068 singularity.
1069 @end deftypefun
1071 @comment math.h
1072 @comment XPG
1073 @deftypefun double lgamma_r (double @var{x}, int *@var{signp})
1074 @comment math.h
1075 @comment XPG
1076 @deftypefunx float lgammaf_r (float @var{x}, int *@var{signp})
1077 @comment math.h
1078 @comment XPG
1079 @deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp})
1080 @code{lgamma_r} is just like @code{lgamma}, but it stores the sign of
1081 the intermediate result in the variable pointed to by @var{signp}
1082 instead of in the @var{signgam} global.  This means it is reentrant.
1083 @end deftypefun
1085 @comment math.h
1086 @comment SVID
1087 @deftypefun double gamma (double @var{x})
1088 @comment math.h
1089 @comment SVID
1090 @deftypefunx float gammaf (float @var{x})
1091 @comment math.h
1092 @comment SVID
1093 @deftypefunx {long double} gammal (long double @var{x})
1094 These functions exist for compatibility reasons.  They are equivalent to
1095 @code{lgamma} etc.  It is better to use @code{lgamma} since for one the
1096 name reflects better the actual computation, moreover @code{lgamma} is
1097 standardized in @w{ISO C99} while @code{gamma} is not.
1098 @end deftypefun
1100 @comment math.h
1101 @comment XPG, ISO
1102 @deftypefun double tgamma (double @var{x})
1103 @comment math.h
1104 @comment XPG, ISO
1105 @deftypefunx float tgammaf (float @var{x})
1106 @comment math.h
1107 @comment XPG, ISO
1108 @deftypefunx {long double} tgammal (long double @var{x})
1109 @code{tgamma} applies the gamma function to @var{x}.  The gamma
1110 function is defined as
1111 @tex
1112 $$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
1113 @end tex
1114 @ifnottex
1115 @smallexample
1116 gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
1117 @end smallexample
1118 @end ifnottex
1120 This function was introduced in @w{ISO C99}.
1121 @end deftypefun
1123 @comment math.h
1124 @comment SVID
1125 @deftypefun double j0 (double @var{x})
1126 @comment math.h
1127 @comment SVID
1128 @deftypefunx float j0f (float @var{x})
1129 @comment math.h
1130 @comment SVID
1131 @deftypefunx {long double} j0l (long double @var{x})
1132 @code{j0} returns the Bessel function of the first kind of order 0 of
1133 @var{x}.  It may signal underflow if @var{x} is too large.
1134 @end deftypefun
1136 @comment math.h
1137 @comment SVID
1138 @deftypefun double j1 (double @var{x})
1139 @comment math.h
1140 @comment SVID
1141 @deftypefunx float j1f (float @var{x})
1142 @comment math.h
1143 @comment SVID
1144 @deftypefunx {long double} j1l (long double @var{x})
1145 @code{j1} returns the Bessel function of the first kind of order 1 of
1146 @var{x}.  It may signal underflow if @var{x} is too large.
1147 @end deftypefun
1149 @comment math.h
1150 @comment SVID
1151 @deftypefun double jn (int n, double @var{x})
1152 @comment math.h
1153 @comment SVID
1154 @deftypefunx float jnf (int n, float @var{x})
1155 @comment math.h
1156 @comment SVID
1157 @deftypefunx {long double} jnl (int n, long double @var{x})
1158 @code{jn} returns the Bessel function of the first kind of order
1159 @var{n} of @var{x}.  It may signal underflow if @var{x} is too large.
1160 @end deftypefun
1162 @comment math.h
1163 @comment SVID
1164 @deftypefun double y0 (double @var{x})
1165 @comment math.h
1166 @comment SVID
1167 @deftypefunx float y0f (float @var{x})
1168 @comment math.h
1169 @comment SVID
1170 @deftypefunx {long double} y0l (long double @var{x})
1171 @code{y0} returns the Bessel function of the second kind of order 0 of
1172 @var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
1173 is negative, @code{y0} signals a domain error; if it is zero,
1174 @code{y0} signals overflow and returns @math{-@infinity}.
1175 @end deftypefun
1177 @comment math.h
1178 @comment SVID
1179 @deftypefun double y1 (double @var{x})
1180 @comment math.h
1181 @comment SVID
1182 @deftypefunx float y1f (float @var{x})
1183 @comment math.h
1184 @comment SVID
1185 @deftypefunx {long double} y1l (long double @var{x})
1186 @code{y1} returns the Bessel function of the second kind of order 1 of
1187 @var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
1188 is negative, @code{y1} signals a domain error; if it is zero,
1189 @code{y1} signals overflow and returns @math{-@infinity}.
1190 @end deftypefun
1192 @comment math.h
1193 @comment SVID
1194 @deftypefun double yn (int n, double @var{x})
1195 @comment math.h
1196 @comment SVID
1197 @deftypefunx float ynf (int n, float @var{x})
1198 @comment math.h
1199 @comment SVID
1200 @deftypefunx {long double} ynl (int n, long double @var{x})
1201 @code{yn} returns the Bessel function of the second kind of order @var{n} of
1202 @var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
1203 is negative, @code{yn} signals a domain error; if it is zero,
1204 @code{yn} signals overflow and returns @math{-@infinity}.
1205 @end deftypefun
1207 @node Errors in Math Functions
1208 @section Known Maximum Errors in Math Functions
1209 @cindex math errors
1210 @cindex ulps
1212 This section lists the known errors of the functions in the math
1213 library.  Errors are measured in units of the last place''.  This is a
1214 measure for the relative error.  For a number @math{z} with the
1215 representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE
1216 floating-point numbers with base 2) the ULP is represented by
1218 @tex
1219 $${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$
1220 @end tex
1221 @ifnottex
1222 @smallexample
1223 |d.d...d - (z / 2^e)| / 2^(p - 1)
1224 @end smallexample
1225 @end ifnottex
1227 @noindent
1228 where @math{p} is the number of bits in the mantissa of the
1229 floating-point number representation.  Ideally the error for all
1230 functions is always less than 0.5ulps.  Using rounding bits this is also
1231 possible and normally implemented for the basic operations.  To achieve
1232 the same for the complex math functions requires a lot more work and
1233 this has not yet been done.
1235 Therefore many of the functions in the math library have errors.  The
1236 table lists the maximum error for each function which is exposed by one
1237 of the existing tests in the test suite.  The table tries to cover as much
1238 as possible and list the actual maximum error (or at least a ballpark
1239 figure) but this is often not achieved due to the large search space.
1241 The table lists the ULP values for different architectures.  Different
1242 architectures have different results since their hardware support for
1243 floating-point operations varies and also the existing hardware support
1244 is different.
1246 @page
1247 @c This multitable does not fit on a single page
1248 @include libm-err.texi
1250 @node Pseudo-Random Numbers
1251 @section Pseudo-Random Numbers
1252 @cindex random numbers
1253 @cindex pseudo-random numbers
1254 @cindex seed (for random numbers)
1256 This section describes the GNU facilities for generating a series of
1257 pseudo-random numbers.  The numbers generated are not truly random;
1258 typically, they form a sequence that repeats periodically, with a period
1259 so large that you can ignore it for ordinary purposes.  The random
1260 number generator works by remembering a @dfn{seed} value which it uses
1261 to compute the next random number and also to compute a new seed.
1263 Although the generated numbers look unpredictable within one run of a
1264 program, the sequence of numbers is @emph{exactly the same} from one run
1265 to the next.  This is because the initial seed is always the same.  This
1266 is convenient when you are debugging a program, but it is unhelpful if
1267 you want the program to behave unpredictably.  If you want a different
1268 pseudo-random series each time your program runs, you must specify a
1269 different seed each time.  For ordinary purposes, basing the seed on the
1270 current time works well.
1272 You can obtain repeatable sequences of numbers on a particular machine type
1273 by specifying the same initial seed value for the random number
1274 generator.  There is no standard meaning for a particular seed value;
1275 the same seed, used in different C libraries or on different CPU types,
1276 will give you different random numbers.
1278 The GNU library supports the standard @w{ISO C} random number functions
1279 plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
1280 functions provide identical, somewhat limited functionality.  If only a
1281 small number of random bits are required, we recommend you use the
1282 @w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
1283 provide a more flexible interface, which allows better random number
1284 generator algorithms, provides more random bits (up to 48) per call, and
1285 can provide random floating-point numbers.  These functions are required
1286 by the XPG standard and therefore will be present in all modern Unix
1287 systems.
1290 * ISO Random::                  @code{rand} and friends.
1291 * BSD Random::                  @code{random} and friends.
1292 * SVID Random::                 @code{drand48} and friends.
1295 @node ISO Random
1296 @subsection ISO C Random Number Functions
1298 This section describes the random number functions that are part of
1299 the @w{ISO C} standard.
1301 To use these facilities, you should include the header file
1302 @file{stdlib.h} in your program.
1303 @pindex stdlib.h
1305 @comment stdlib.h
1306 @comment ISO
1307 @deftypevr Macro int RAND_MAX
1308 The value of this macro is an integer constant representing the largest
1309 value the @code{rand} function can return.  In the GNU library, it is
1310 @code{2147483647}, which is the largest signed integer representable in
1311 32 bits.  In other libraries, it may be as low as @code{32767}.
1312 @end deftypevr
1314 @comment stdlib.h
1315 @comment ISO
1316 @deftypefun int rand (void)
1317 The @code{rand} function returns the next pseudo-random number in the
1318 series.  The value ranges from @code{0} to @code{RAND_MAX}.
1319 @end deftypefun
1321 @comment stdlib.h
1322 @comment ISO
1323 @deftypefun void srand (unsigned int @var{seed})
1324 This function establishes @var{seed} as the seed for a new series of
1325 pseudo-random numbers.  If you call @code{rand} before a seed has been
1326 established with @code{srand}, it uses the value @code{1} as a default
1327 seed.
1329 To produce a different pseudo-random series each time your program is
1330 run, do @code{srand (time (0))}.
1331 @end deftypefun
1333 POSIX.1 extended the C standard functions to support reproducible random
1335 designed and unsuitable for serious work.
1337 @comment stdlib.h
1338 @comment POSIX.1
1339 @deftypefun int rand_r (unsigned int *@var{seed})
1340 This function returns a random number in the range 0 to @code{RAND_MAX}
1341 just as @code{rand} does.  However, all its state is stored in the
1342 @var{seed} argument.  This means the RNG's state can only have as many
1343 bits as the type @code{unsigned int} has.  This is far too few to
1344 provide a good RNG.
1346 If your program requires a reentrant RNG, we recommend you use the
1347 reentrant GNU extensions to the SVID random number generator.  The
1348 POSIX.1 interface should only be used when the GNU extensions are not
1349 available.
1350 @end deftypefun
1353 @node BSD Random
1354 @subsection BSD Random Number Functions
1356 This section describes a set of random number generation functions that
1357 are derived from BSD.  There is no advantage to using these functions
1358 with the GNU C library; we support them for BSD compatibility only.
1360 The prototypes for these functions are in @file{stdlib.h}.
1361 @pindex stdlib.h
1363 @comment stdlib.h
1364 @comment BSD
1365 @deftypefun {long int} random (void)
1366 This function returns the next pseudo-random number in the sequence.
1367 The value returned ranges from @code{0} to @code{RAND_MAX}.
1369 @strong{Note:} Temporarily this function was defined to return a
1370 @code{int32_t} value to indicate that the return value always contains
1371 32 bits even if @code{long int} is wider.  The standard demands it
1372 differently.  Users must always be aware of the 32-bit limitation,
1373 though.
1374 @end deftypefun
1376 @comment stdlib.h
1377 @comment BSD
1378 @deftypefun void srandom (unsigned int @var{seed})
1379 The @code{srandom} function sets the state of the random number
1380 generator based on the integer @var{seed}.  If you supply a @var{seed} value
1381 of @code{1}, this will cause @code{random} to reproduce the default set
1382 of random numbers.
1384 To produce a different set of pseudo-random numbers each time your
1385 program runs, do @code{srandom (time (0))}.
1386 @end deftypefun
1388 @comment stdlib.h
1389 @comment BSD
1390 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1391 The @code{initstate} function is used to initialize the random number
1392 generator state.  The argument @var{state} is an array of @var{size}
1393 bytes, used to hold the state information.  It is initialized based on
1394 @var{seed}.  The size must be between 8 and 256 bytes, and should be a
1395 power of two.  The bigger the @var{state} array, the better.
1397 The return value is the previous value of the state information array.
1398 You can use this value later as an argument to @code{setstate} to
1399 restore that state.
1400 @end deftypefun
1402 @comment stdlib.h
1403 @comment BSD
1404 @deftypefun {void *} setstate (void *@var{state})
1405 The @code{setstate} function restores the random number state
1406 information @var{state}.  The argument must have been the result of
1407 a previous call to @var{initstate} or @var{setstate}.
1409 The return value is the previous value of the state information array.
1410 You can use this value later as an argument to @code{setstate} to
1411 restore that state.
1413 If the function fails the return value is @code{NULL}.
1414 @end deftypefun
1416 The four functions described so far in this section all work on a state
1417 which is shared by all threads.  The state is not directly accessible to
1418 the user and can only be modified by these functions.  This makes it
1419 hard to deal with situations where each thread should have its own
1420 pseudo-random number generator.
1422 The GNU C library contains four additional functions which contain the
1423 state as an explicit parameter and therefore make it possible to handle
1424 thread-local PRNGs.  Beside this there are no difference.  In fact, the
1425 four functions already discussed are implemented internally using the
1426 following interfaces.
1428 The @file{stdlib.h} header contains a definition of the following type:
1430 @comment stdlib.h
1431 @comment GNU
1432 @deftp {Data Type} {struct random_data}
1434 Objects of type @code{struct random_data} contain the information
1435 necessary to represent the state of the PRNG.  Although a complete
1436 definition of the type is present the type should be treated as opaque.
1437 @end deftp
1439 The functions modifying the state follow exactly the already described
1440 functions.
1442 @comment stdlib.h
1443 @comment GNU
1444 @deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result})
1445 The @code{random_r} function behaves exactly like the @code{random}
1446 function except that it uses and modifies the state in the object
1447 pointed to by the first parameter instead of the global state.
1448 @end deftypefun
1450 @comment stdlib.h
1451 @comment GNU
1452 @deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf})
1453 The @code{srandom_r} function behaves exactly like the @code{srandom}
1454 function except that it uses and modifies the state in the object
1455 pointed to by the second parameter instead of the global state.
1456 @end deftypefun
1458 @comment stdlib.h
1459 @comment GNU
1460 @deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf})
1461 The @code{initstate_r} function behaves exactly like the @code{initstate}
1462 function except that it uses and modifies the state in the object
1463 pointed to by the fourth parameter instead of the global state.
1464 @end deftypefun
1466 @comment stdlib.h
1467 @comment GNU
1468 @deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf})
1469 The @code{setstate_r} function behaves exactly like the @code{setstate}
1470 function except that it uses and modifies the state in the object
1471 pointed to by the first parameter instead of the global state.
1472 @end deftypefun
1474 @node SVID Random
1475 @subsection SVID Random Number Function
1477 The C library on SVID systems contains yet another kind of random number
1478 generator functions.  They use a state of 48 bits of data.  The user can
1479 choose among a collection of functions which return the random bits
1480 in different forms.
1482 Generally there are two kinds of function.  The first uses a state of
1483 the random number generator which is shared among several functions and
1484 by all threads of the process.  The second requires the user to handle
1485 the state.
1487 All functions have in common that they use the same congruential
1488 formula with the same constants.  The formula is
1490 @smallexample
1491 Y = (a * X + c) mod m
1492 @end smallexample
1494 @noindent
1495 where @var{X} is the state of the generator at the beginning and
1496 @var{Y} the state at the end.  @code{a} and @code{c} are constants
1497 determining the way the generator works.  By default they are
1499 @smallexample
1500 a = 0x5DEECE66D = 25214903917
1501 c = 0xb = 11
1502 @end smallexample
1504 @noindent
1505 but they can also be changed by the user.  @code{m} is of course 2^48
1506 since the state consists of a 48-bit array.
1508 The prototypes for these functions are in @file{stdlib.h}.
1509 @pindex stdlib.h
1512 @comment stdlib.h
1513 @comment SVID
1514 @deftypefun double drand48 (void)
1515 This function returns a @code{double} value in the range of @code{0.0}
1516 to @code{1.0} (exclusive).  The random bits are determined by the global
1517 state of the random number generator in the C library.
1519 Since the @code{double} type according to @w{IEEE 754} has a 52-bit
1520 mantissa this means 4 bits are not initialized by the random number
1521 generator.  These are (of course) chosen to be the least significant
1522 bits and they are initialized to @code{0}.
1523 @end deftypefun
1525 @comment stdlib.h
1526 @comment SVID
1527 @deftypefun double erand48 (unsigned short int @var{xsubi})
1528 This function returns a @code{double} value in the range of @code{0.0}
1529 to @code{1.0} (exclusive), similarly to @code{drand48}.  The argument is
1530 an array describing the state of the random number generator.
1532 This function can be called subsequently since it updates the array to
1533 guarantee random numbers.  The array should have been initialized before
1534 initial use to obtain reproducible results.
1535 @end deftypefun
1537 @comment stdlib.h
1538 @comment SVID
1539 @deftypefun {long int} lrand48 (void)
1540 The @code{lrand48} function returns an integer value in the range of
1541 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
1542 int} type can take more than 32 bits, no higher numbers are returned.
1543 The random bits are determined by the global state of the random number
1544 generator in the C library.
1545 @end deftypefun
1547 @comment stdlib.h
1548 @comment SVID
1549 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi})
1550 This function is similar to the @code{lrand48} function in that it
1551 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1552 the state of the random number generator used to produce the random bits
1553 is determined by the array provided as the parameter to the function.
1555 The numbers in the array are updated afterwards so that subsequent calls
1556 to this function yield different results (as is expected of a random
1557 number generator).  The array should have been initialized before the
1558 first call to obtain reproducible results.
1559 @end deftypefun
1561 @comment stdlib.h
1562 @comment SVID
1563 @deftypefun {long int} mrand48 (void)
1564 The @code{mrand48} function is similar to @code{lrand48}.  The only
1565 difference is that the numbers returned are in the range @code{-2^31} to
1566 @code{2^31} (exclusive).
1567 @end deftypefun
1569 @comment stdlib.h
1570 @comment SVID
1571 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi})
1572 The @code{jrand48} function is similar to @code{nrand48}.  The only
1573 difference is that the numbers returned are in the range @code{-2^31} to
1574 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
1575 requirements are necessary.
1576 @end deftypefun
1578 The internal state of the random number generator can be initialized in
1579 several ways.  The methods differ in the completeness of the
1580 information provided.
1582 @comment stdlib.h
1583 @comment SVID
1584 @deftypefun void srand48 (long int @var{seedval})
1585 The @code{srand48} function sets the most significant 32 bits of the
1586 internal state of the random number generator to the least
1587 significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
1588 are initialized to the value @code{0x330E}.  Even if the @code{long
1589 int} type contains more than 32 bits only the lower 32 bits are used.
1591 Owing to this limitation, initialization of the state of this
1592 function is not very useful.  But it makes it easy to use a construct
1593 like @code{srand48 (time (0))}.
1595 A side-effect of this function is that the values @code{a} and @code{c}
1596 from the internal state, which are used in the congruential formula,
1597 are reset to the default values given above.  This is of importance once
1598 the user has called the @code{lcong48} function (see below).
1599 @end deftypefun
1601 @comment stdlib.h
1602 @comment SVID
1603 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v})
1604 The @code{seed48} function initializes all 48 bits of the state of the
1605 internal random number generator from the contents of the parameter
1606 @var{seed16v}.  Here the lower 16 bits of the first element of
1607 @var{see16v} initialize the least significant 16 bits of the internal
1608 state, the lower 16 bits of @code{@var{seed16v}} initialize the mid-order
1609 16 bits of the state and the 16 lower bits of @code{@var{seed16v}}
1610 initialize the most significant 16 bits of the state.
1612 Unlike @code{srand48} this function lets the user initialize all 48 bits
1613 of the state.
1615 The value returned by @code{seed48} is a pointer to an array containing
1616 the values of the internal state before the change.  This might be
1617 useful to restart the random number generator at a certain state.
1618 Otherwise the value can simply be ignored.
1620 As for @code{srand48}, the values @code{a} and @code{c} from the
1621 congruential formula are reset to the default values.
1622 @end deftypefun
1624 There is one more function to initialize the random number generator
1625 which enables you to specify even more information by allowing you to
1626 change the parameters in the congruential formula.
1628 @comment stdlib.h
1629 @comment SVID
1630 @deftypefun void lcong48 (unsigned short int @var{param})
1631 The @code{lcong48} function allows the user to change the complete state
1632 of the random number generator.  Unlike @code{srand48} and
1633 @code{seed48}, this function also changes the constants in the
1634 congruential formula.
1636 From the seven elements in the array @var{param} the least significant
1637 16 bits of the entries @code{@var{param}} to @code{@var{param}}
1638 determine the initial state, the least significant 16 bits of
1639 @code{@var{param}} to @code{@var{param}} determine the 48 bit
1640 constant @code{a} and @code{@var{param}} determines the 16-bit value
1641 @code{c}.
1642 @end deftypefun
1644 All the above functions have in common that they use the global
1645 parameters for the congruential formula.  In multi-threaded programs it
1646 might sometimes be useful to have different parameters in different
1647 threads.  For this reason all the above functions have a counterpart
1648 which works on a description of the random number generator in the
1649 user-supplied buffer instead of the global state.
1651 Please note that it is no problem if several threads use the global
1652 state if all threads use the functions which take a pointer to an array
1653 containing the state.  The random numbers are computed following the
1654 same loop but if the state in the array is different all threads will
1655 obtain an individual random number generator.
1657 The user-supplied buffer must be of type @code{struct drand48_data}.
1658 This type should be regarded as opaque and not manipulated directly.
1660 @comment stdlib.h
1661 @comment GNU
1662 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1663 This function is equivalent to the @code{drand48} function with the
1664 difference that it does not modify the global random number generator
1665 parameters but instead the parameters in the buffer supplied through the
1666 pointer @var{buffer}.  The random number is returned in the variable
1667 pointed to by @var{result}.
1669 The return value of the function indicates whether the call succeeded.
1670 If the value is less than @code{0} an error occurred and @var{errno} is
1671 set to indicate the problem.
1673 This function is a GNU extension and should not be used in portable
1674 programs.
1675 @end deftypefun
1677 @comment stdlib.h
1678 @comment GNU
1679 @deftypefun int erand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, double *@var{result})
1680 The @code{erand48_r} function works like @code{erand48}, but in addition
1681 it takes an argument @var{buffer} which describes the random number
1682 generator.  The state of the random number generator is taken from the
1683 @code{xsubi} array, the parameters for the congruential formula from the
1684 global random number generator data.  The random number is returned in
1685 the variable pointed to by @var{result}.
1687 The return value is non-negative if the call succeeded.
1689 This function is a GNU extension and should not be used in portable
1690 programs.
1691 @end deftypefun
1693 @comment stdlib.h
1694 @comment GNU
1695 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1696 This function is similar to @code{lrand48}, but in addition it takes a
1697 pointer to a buffer describing the state of the random number generator
1698 just like @code{drand48}.
1700 If the return value of the function is non-negative the variable pointed
1701 to by @var{result} contains the result.  Otherwise an error occurred.
1703 This function is a GNU extension and should not be used in portable
1704 programs.
1705 @end deftypefun
1707 @comment stdlib.h
1708 @comment GNU
1709 @deftypefun int nrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
1710 The @code{nrand48_r} function works like @code{nrand48} in that it
1711 produces a random number in the range @code{0} to @code{2^31}.  But instead
1712 of using the global parameters for the congruential formula it uses the
1713 information from the buffer pointed to by @var{buffer}.  The state is
1714 described by the values in @var{xsubi}.
1716 If the return value is non-negative the variable pointed to by
1717 @var{result} contains the result.
1719 This function is a GNU extension and should not be used in portable
1720 programs.
1721 @end deftypefun
1723 @comment stdlib.h
1724 @comment GNU
1725 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1726 This function is similar to @code{mrand48} but like the other reentrant
1727 functions it uses the random number generator described by the value in
1728 the buffer pointed to by @var{buffer}.
1730 If the return value is non-negative the variable pointed to by
1731 @var{result} contains the result.
1733 This function is a GNU extension and should not be used in portable
1734 programs.
1735 @end deftypefun
1737 @comment stdlib.h
1738 @comment GNU
1739 @deftypefun int jrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
1740 The @code{jrand48_r} function is similar to @code{jrand48}.  Like the
1741 other reentrant functions of this function family it uses the
1742 congruential formula parameters from the buffer pointed to by
1743 @var{buffer}.
1745 If the return value is non-negative the variable pointed to by
1746 @var{result} contains the result.
1748 This function is a GNU extension and should not be used in portable
1749 programs.
1750 @end deftypefun
1752 Before any of the above functions are used the buffer of type
1753 @code{struct drand48_data} should be initialized.  The easiest way to do
1754 this is to fill the whole buffer with null bytes, e.g. by
1756 @smallexample
1757 memset (buffer, '\0', sizeof (struct drand48_data));
1758 @end smallexample
1760 @noindent
1761 Using any of the reentrant functions of this family now will
1762 automatically initialize the random number generator to the default
1763 values for the state and the parameters of the congruential formula.
1765 The other possibility is to use any of the functions which explicitly
1766 initialize the buffer.  Though it might be obvious how to initialize the
1767 buffer from looking at the parameter to the function, it is highly
1768 recommended to use these functions since the result might not always be
1769 what you expect.
1771 @comment stdlib.h
1772 @comment GNU
1773 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1774 The description of the random number generator represented by the
1775 information in @var{buffer} is initialized similarly to what the function
1776 @code{srand48} does.  The state is initialized from the parameter
1777 @var{seedval} and the parameters for the congruential formula are
1778 initialized to their default values.
1780 If the return value is non-negative the function call succeeded.
1782 This function is a GNU extension and should not be used in portable
1783 programs.
1784 @end deftypefun
1786 @comment stdlib.h
1787 @comment GNU
1788 @deftypefun int seed48_r (unsigned short int @var{seed16v}, struct drand48_data *@var{buffer})
1789 This function is similar to @code{srand48_r} but like @code{seed48} it
1790 initializes all 48 bits of the state from the parameter @var{seed16v}.
1792 If the return value is non-negative the function call succeeded.  It
1793 does not return a pointer to the previous state of the random number
1794 generator like the @code{seed48} function does.  If the user wants to
1795 preserve the state for a later re-run s/he can copy the whole buffer
1796 pointed to by @var{buffer}.
1798 This function is a GNU extension and should not be used in portable
1799 programs.
1800 @end deftypefun
1802 @comment stdlib.h
1803 @comment GNU
1804 @deftypefun int lcong48_r (unsigned short int @var{param}, struct drand48_data *@var{buffer})
1805 This function initializes all aspects of the random number generator
1806 described in @var{buffer} with the data in @var{param}.  Here it is
1807 especially true that the function does more than just copying the
1808 contents of @var{param} and @var{buffer}.  More work is required and
1809 therefore it is important to use this function rather than initializing
1810 the random number generator directly.
1812 If the return value is non-negative the function call succeeded.
1814 This function is a GNU extension and should not be used in portable
1815 programs.
1816 @end deftypefun
1818 @node FP Function Optimizations
1819 @section Is Fast Code or Small Code preferred?
1820 @cindex Optimization
1822 If an application uses many floating point functions it is often the case
1823 that the cost of the function calls themselves is not negligible.
1824 Modern processors can often execute the operations themselves
1825 very fast, but the function call disrupts the instruction pipeline.
1827 For this reason the GNU C Library provides optimizations for many of the
1828 frequently-used math functions.  When GNU CC is used and the user
1829 activates the optimizer, several new inline functions and macros are
1830 defined.  These new functions and macros have the same names as the
1831 library functions and so are used instead of the latter.  In the case of
1832 inline functions the compiler will decide whether it is reasonable to
1833 use them, and this decision is usually correct.
1835 This means that no calls to the library functions may be necessary, and
1836 can increase the speed of generated code significantly.  The drawback is
1837 that code size will increase, and the increase is not always negligible.
1839 There are two kind of inline functions: Those that give the same result
1840 as the library functions and others that might not set @code{errno} and
1841 might have a reduced precision and/or argument range in comparison with
1842 the library functions.  The latter inline functions are only available
1843 if the flag @code{-ffast-math} is given to GNU CC.
1845 In cases where the inline functions and macros are not wanted the symbol
1846 @code{__NO_MATH_INLINES} should be defined before any system header is
1847 included.  This will ensure that only library functions are used.  Of
1848 course, it can be determined for each file in the project whether
1849 giving this option is preferable or not.
1851 Not all hardware implements the entire @w{IEEE 754} standard, and even
1852 if it does there may be a substantial performance penalty for using some
1853 of its features.  For example, enabling traps on some processors forces
1854 the FPU to run un-pipelined, which can more than double calculation time.
1855 @c ***Add explanation of -lieee, -mieee.