Update.
[kopensolaris-gnu/glibc.git] / manual / math.texi
1 @c We need some definitions here.
2 @ifclear mult
3 @ifhtml
4 @set mult ·
5 @set infty ∞
6 @set pie π
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
29
30 @node Mathematics, Arithmetic, Syslog, Top
31 @c %MENU% Math functions, useful constants, random numbers
32 @chapter Mathematics
33
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
41
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}.
47
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}.
55
56 @menu
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.
68 @end menu
69
70 @node Mathematical Constants
71 @section Predefined Mathematical Constants
72 @cindex constants
73 @cindex mathematical constants
74
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:
78
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
107
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}.
113
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.
119
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.
128
129 @node Trig Functions
130 @section Trigonometric Functions
131 @cindex trigonometric functions
132
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.
136
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:
142
143 @smallexample
144 #define M_PI 3.14159265358979323846264338327
145 @end smallexample
146
147 @noindent
148 You can also compute the value of pi with the expression @code{acos
149 (-1.0)}.
150
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
163
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
176
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
187 radians.
188
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
193
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.
198
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}.
212
213 This function is a GNU extension.  Portable programs should be prepared
214 to cope with its absence.
215 @end deftypefun
216
217 @cindex complex trigonometric functions
218
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.)
226
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
238
239 @ifinfo
240 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
241 @end ifinfo
242 @tex
243 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
244 @end tex
245 @end deftypefun
246
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
258
259 @ifinfo
260 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
261 @end ifinfo
262 @tex
263 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
264 @end tex
265 @end deftypefun
266
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
278
279 @ifinfo
280 @math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
281 @end ifinfo
282 @tex
283 $$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
284 @end tex
285
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
291
292
293 @node Inverse Trig Functions
294 @section Inverse Trigonometric Functions
295 @cindex inverse trigonometric functions
296
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.
300
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).
314
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
319
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).
333
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
338
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
353
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.
367
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}.)
374
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
378
379 @cindex inverse complex trigonometric functions
380 @w{ISO C99} defines complex versions of the inverse trig functions.
381
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.
393
394 Unlike the real-valued functions, @code{casin} is defined for all
395 values of @var{z}.
396 @end deftypefun
397
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.
409
410 Unlike the real-valued functions, @code{cacos} is defined for all
411 values of @var{z}.
412 @end deftypefun
413
414
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
427
428
429 @node Exponents and Logarithms
430 @section Exponentiation and Logarithms
431 @cindex exponentiation functions
432 @cindex power functions
433 @cindex logarithm functions
434
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}.
446
447 If the magnitude of the result is too large to be representable,
448 @code{exp} signals overflow.
449 @end deftypefun
450
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
463
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))}.
484
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
488
489
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.
502
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
507
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)}.
519
520 @end deftypefun
521
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
534
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.
547
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
553
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
566
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.
571
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}.
577
578 This macro is defined in @w{ISO C99}.
579 @end deftypevr
580
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}.
586
587 This macro is defined in @w{ISO C99}.
588 @end deftypevr
589
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:
592
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
612
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}.
624
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
630
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}.
642
643 If @var{x} is negative, @code{sqrt} signals a domain error.
644 Mathematically, it should return a complex number.
645 @end deftypefun
646
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
660
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
677
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
692
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
706
707 @cindex complex exponentiation functions
708 @cindex complex logarithm functions
709
710 @w{ISO C99} defines complex variants of some of the exponentiation and
711 logarithm functions.
712
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
725
726 @ifinfo
727 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
728 @end ifinfo
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
733
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
745
746 @ifinfo
747 @math{log (z) = log (cabs (z)) + I * carg (z)}
748 @end ifinfo
749 @tex
750 $$\log(z) = \log |z| + i \arg z$$
751 @end tex
752
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
758
759
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
771
772 @ifinfo
773 @math{log (z) = log10 (cabs (z)) + I * carg (z)}
774 @end ifinfo
775 @tex
776 $$\log_{10}(z) = \log_{10}|z| + i \arg z$$
777 @end tex
778
779 These functions are GNU extensions.
780 @end deftypefun
781
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
794
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
807
808 @node Hyperbolic Functions
809 @section Hyperbolic Functions
810 @cindex hyperbolic functions
811
812 The functions in this section are related to the exponential functions;
813 see @ref{Exponents and Logarithms}.
814
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
828
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
842
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
856
857 @cindex hyperbolic functions
858
859 There are counterparts for the hyperbolic functions which take
860 complex arguments.
861
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
874
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
887
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
900
901
902 @cindex inverse hyperbolic functions
903
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
916
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
930
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
945
946 @cindex inverse complex hyperbolic functions
947
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
960
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
974
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
989
990 @node Special Functions
991 @section Special Functions
992 @cindex special functions
993 @cindex Bessel functions
994 @cindex gamma function
995
996 These are some more exotic mathematical functions which are sometimes
997 useful.  Currently they only have real-valued versions.
998
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
1019
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
1032
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
1052
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.
1058
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
1065
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
1070
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
1084
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
1099
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
1119
1120 This function was introduced in @w{ISO C99}.
1121 @end deftypefun
1122
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
1135
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
1148
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
1161
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
1176
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
1191
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
1206
1207 @node Errors in Math Functions
1208 @section Known Maximum Errors in Math Functions
1209 @cindex math errors
1210 @cindex ulps
1211
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
1217
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
1226
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 was not spend so far.
1234
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.  It is tried to cover as much
1238 as possible and really list the maximum error (or at least a ballpark
1239 figure) but this is often not achieved due to the large search space.
1240
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.
1245
1246 @include libm-err.texi
1247
1248 @node Pseudo-Random Numbers
1249 @section Pseudo-Random Numbers
1250 @cindex random numbers
1251 @cindex pseudo-random numbers
1252 @cindex seed (for random numbers)
1253
1254 This section describes the GNU facilities for generating a series of
1255 pseudo-random numbers.  The numbers generated are not truly random;
1256 typically, they form a sequence that repeats periodically, with a period
1257 so large that you can ignore it for ordinary purposes.  The random
1258 number generator works by remembering a @dfn{seed} value which it uses
1259 to compute the next random number and also to compute a new seed.
1260
1261 Although the generated numbers look unpredictable within one run of a
1262 program, the sequence of numbers is @emph{exactly the same} from one run
1263 to the next.  This is because the initial seed is always the same.  This
1264 is convenient when you are debugging a program, but it is unhelpful if
1265 you want the program to behave unpredictably.  If you want a different
1266 pseudo-random series each time your program runs, you must specify a
1267 different seed each time.  For ordinary purposes, basing the seed on the
1268 current time works well.
1269
1270 You can obtain repeatable sequences of numbers on a particular machine type
1271 by specifying the same initial seed value for the random number
1272 generator.  There is no standard meaning for a particular seed value;
1273 the same seed, used in different C libraries or on different CPU types,
1274 will give you different random numbers.
1275
1276 The GNU library supports the standard @w{ISO C} random number functions
1277 plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
1278 functions provide identical, somewhat limited functionality.  If only a
1279 small number of random bits are required, we recommend you use the
1280 @w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
1281 provide a more flexible interface, which allows better random number
1282 generator algorithms, provides more random bits (up to 48) per call, and
1283 can provide random floating-point numbers.  These functions are required
1284 by the XPG standard and therefore will be present in all modern Unix
1285 systems.
1286
1287 @menu
1288 * ISO Random::                  @code{rand} and friends.
1289 * BSD Random::                  @code{random} and friends.
1290 * SVID Random::                 @code{drand48} and friends.
1291 @end menu
1292
1293 @node ISO Random
1294 @subsection ISO C Random Number Functions
1295
1296 This section describes the random number functions that are part of
1297 the @w{ISO C} standard.
1298
1299 To use these facilities, you should include the header file
1300 @file{stdlib.h} in your program.
1301 @pindex stdlib.h
1302
1303 @comment stdlib.h
1304 @comment ISO
1305 @deftypevr Macro int RAND_MAX
1306 The value of this macro is an integer constant representing the largest
1307 value the @code{rand} function can return.  In the GNU library, it is
1308 @code{2147483647}, which is the largest signed integer representable in
1309 32 bits.  In other libraries, it may be as low as @code{32767}.
1310 @end deftypevr
1311
1312 @comment stdlib.h
1313 @comment ISO
1314 @deftypefun int rand (void)
1315 The @code{rand} function returns the next pseudo-random number in the
1316 series.  The value ranges from @code{0} to @code{RAND_MAX}.
1317 @end deftypefun
1318
1319 @comment stdlib.h
1320 @comment ISO
1321 @deftypefun void srand (unsigned int @var{seed})
1322 This function establishes @var{seed} as the seed for a new series of
1323 pseudo-random numbers.  If you call @code{rand} before a seed has been
1324 established with @code{srand}, it uses the value @code{1} as a default
1325 seed.
1326
1327 To produce a different pseudo-random series each time your program is
1328 run, do @code{srand (time (0))}.
1329 @end deftypefun
1330
1331 POSIX.1 extended the C standard functions to support reproducible random
1332 numbers in multi-threaded programs.  However, the extension is badly
1333 designed and unsuitable for serious work.
1334
1335 @comment stdlib.h
1336 @comment POSIX.1
1337 @deftypefun int rand_r (unsigned int *@var{seed})
1338 This function returns a random number in the range 0 to @code{RAND_MAX}
1339 just as @code{rand} does.  However, all its state is stored in the
1340 @var{seed} argument.  This means the RNG's state can only have as many
1341 bits as the type @code{unsigned int} has.  This is far too few to
1342 provide a good RNG.
1343
1344 If your program requires a reentrant RNG, we recommend you use the
1345 reentrant GNU extensions to the SVID random number generator.  The
1346 POSIX.1 interface should only be used when the GNU extensions are not
1347 available.
1348 @end deftypefun
1349
1350
1351 @node BSD Random
1352 @subsection BSD Random Number Functions
1353
1354 This section describes a set of random number generation functions that
1355 are derived from BSD.  There is no advantage to using these functions
1356 with the GNU C library; we support them for BSD compatibility only.
1357
1358 The prototypes for these functions are in @file{stdlib.h}.
1359 @pindex stdlib.h
1360
1361 @comment stdlib.h
1362 @comment BSD
1363 @deftypefun {int32_t} random (void)
1364 This function returns the next pseudo-random number in the sequence.
1365 The value returned ranges from @code{0} to @code{RAND_MAX}.
1366
1367 @strong{Note:} Historically this function returned a @code{long int}
1368 value.  On 64-bit systems @code{long int} would have been larger than
1369 programs expected, so @code{random} is now defined to return exactly 32
1370 bits.
1371 @end deftypefun
1372
1373 @comment stdlib.h
1374 @comment BSD
1375 @deftypefun void srandom (unsigned int @var{seed})
1376 The @code{srandom} function sets the state of the random number
1377 generator based on the integer @var{seed}.  If you supply a @var{seed} value
1378 of @code{1}, this will cause @code{random} to reproduce the default set
1379 of random numbers.
1380
1381 To produce a different set of pseudo-random numbers each time your
1382 program runs, do @code{srandom (time (0))}.
1383 @end deftypefun
1384
1385 @comment stdlib.h
1386 @comment BSD
1387 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1388 The @code{initstate} function is used to initialize the random number
1389 generator state.  The argument @var{state} is an array of @var{size}
1390 bytes, used to hold the state information.  It is initialized based on
1391 @var{seed}.  The size must be between 8 and 256 bytes, and should be a
1392 power of two.  The bigger the @var{state} array, the better.
1393
1394 The return value is the previous value of the state information array.
1395 You can use this value later as an argument to @code{setstate} to
1396 restore that state.
1397 @end deftypefun
1398
1399 @comment stdlib.h
1400 @comment BSD
1401 @deftypefun {void *} setstate (void *@var{state})
1402 The @code{setstate} function restores the random number state
1403 information @var{state}.  The argument must have been the result of
1404 a previous call to @var{initstate} or @var{setstate}.
1405
1406 The return value is the previous value of the state information array.
1407 You can use this value later as an argument to @code{setstate} to
1408 restore that state.
1409 @end deftypefun
1410
1411 @node SVID Random
1412 @subsection SVID Random Number Function
1413
1414 The C library on SVID systems contains yet another kind of random number
1415 generator functions.  They use a state of 48 bits of data.  The user can
1416 choose among a collection of functions which return the random bits
1417 in different forms.
1418
1419 Generally there are two kinds of function.  The first uses a state of
1420 the random number generator which is shared among several functions and
1421 by all threads of the process.  The second requires the user to handle
1422 the state.
1423
1424 All functions have in common that they use the same congruential
1425 formula with the same constants.  The formula is
1426
1427 @smallexample
1428 Y = (a * X + c) mod m
1429 @end smallexample
1430
1431 @noindent
1432 where @var{X} is the state of the generator at the beginning and
1433 @var{Y} the state at the end.  @code{a} and @code{c} are constants
1434 determining the way the generator works.  By default they are
1435
1436 @smallexample
1437 a = 0x5DEECE66D = 25214903917
1438 c = 0xb = 11
1439 @end smallexample
1440
1441 @noindent
1442 but they can also be changed by the user.  @code{m} is of course 2^48
1443 since the state consists of a 48-bit array.
1444
1445
1446 @comment stdlib.h
1447 @comment SVID
1448 @deftypefun double drand48 (void)
1449 This function returns a @code{double} value in the range of @code{0.0}
1450 to @code{1.0} (exclusive).  The random bits are determined by the global
1451 state of the random number generator in the C library.
1452
1453 Since the @code{double} type according to @w{IEEE 754} has a 52-bit
1454 mantissa this means 4 bits are not initialized by the random number
1455 generator.  These are (of course) chosen to be the least significant
1456 bits and they are initialized to @code{0}.
1457 @end deftypefun
1458
1459 @comment stdlib.h
1460 @comment SVID
1461 @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
1462 This function returns a @code{double} value in the range of @code{0.0}
1463 to @code{1.0} (exclusive), similarly to @code{drand48}.  The argument is
1464 an array describing the state of the random number generator.
1465
1466 This function can be called subsequently since it updates the array to
1467 guarantee random numbers.  The array should have been initialized before
1468 initial use to obtain reproducible results.
1469 @end deftypefun
1470
1471 @comment stdlib.h
1472 @comment SVID
1473 @deftypefun {long int} lrand48 (void)
1474 The @code{lrand48} function returns an integer value in the range of
1475 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
1476 int} type can take more than 32 bits, no higher numbers are returned.
1477 The random bits are determined by the global state of the random number
1478 generator in the C library.
1479 @end deftypefun
1480
1481 @comment stdlib.h
1482 @comment SVID
1483 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
1484 This function is similar to the @code{lrand48} function in that it
1485 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1486 the state of the random number generator used to produce the random bits
1487 is determined by the array provided as the parameter to the function.
1488
1489 The numbers in the array are updated afterwards so that subsequent calls
1490 to this function yield different results (as is expected of a random
1491 number generator).  The array should have been initialized before the
1492 first call to obtain reproducible results.
1493 @end deftypefun
1494
1495 @comment stdlib.h
1496 @comment SVID
1497 @deftypefun {long int} mrand48 (void)
1498 The @code{mrand48} function is similar to @code{lrand48}.  The only
1499 difference is that the numbers returned are in the range @code{-2^31} to
1500 @code{2^31} (exclusive).
1501 @end deftypefun
1502
1503 @comment stdlib.h
1504 @comment SVID
1505 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
1506 The @code{jrand48} function is similar to @code{nrand48}.  The only
1507 difference is that the numbers returned are in the range @code{-2^31} to
1508 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
1509 requirements are necessary.
1510 @end deftypefun
1511
1512 The internal state of the random number generator can be initialized in
1513 several ways.  The methods differ in the completeness of the
1514 information provided.
1515
1516 @comment stdlib.h
1517 @comment SVID
1518 @deftypefun void srand48 (long int @var{seedval})
1519 The @code{srand48} function sets the most significant 32 bits of the
1520 internal state of the random number generator to the least
1521 significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
1522 are initialized to the value @code{0x330E}.  Even if the @code{long
1523 int} type contains more than 32 bits only the lower 32 bits are used.
1524
1525 Owing to this limitation, initialization of the state of this
1526 function is not very useful.  But it makes it easy to use a construct
1527 like @code{srand48 (time (0))}.
1528
1529 A side-effect of this function is that the values @code{a} and @code{c}
1530 from the internal state, which are used in the congruential formula,
1531 are reset to the default values given above.  This is of importance once
1532 the user has called the @code{lcong48} function (see below).
1533 @end deftypefun
1534
1535 @comment stdlib.h
1536 @comment SVID
1537 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
1538 The @code{seed48} function initializes all 48 bits of the state of the
1539 internal random number generator from the contents of the parameter
1540 @var{seed16v}.  Here the lower 16 bits of the first element of
1541 @var{see16v} initialize the least significant 16 bits of the internal
1542 state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
1543 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
1544 initialize the most significant 16 bits of the state.
1545
1546 Unlike @code{srand48} this function lets the user initialize all 48 bits
1547 of the state.
1548
1549 The value returned by @code{seed48} is a pointer to an array containing
1550 the values of the internal state before the change.  This might be
1551 useful to restart the random number generator at a certain state.
1552 Otherwise the value can simply be ignored.
1553
1554 As for @code{srand48}, the values @code{a} and @code{c} from the
1555 congruential formula are reset to the default values.
1556 @end deftypefun
1557
1558 There is one more function to initialize the random number generator
1559 which enables you to specify even more information by allowing you to
1560 change the parameters in the congruential formula.
1561
1562 @comment stdlib.h
1563 @comment SVID
1564 @deftypefun void lcong48 (unsigned short int @var{param}[7])
1565 The @code{lcong48} function allows the user to change the complete state
1566 of the random number generator.  Unlike @code{srand48} and
1567 @code{seed48}, this function also changes the constants in the
1568 congruential formula.
1569
1570 From the seven elements in the array @var{param} the least significant
1571 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
1572 determine the initial state, the least significant 16 bits of
1573 @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
1574 constant @code{a} and @code{@var{param}[6]} determines the 16-bit value
1575 @code{c}.
1576 @end deftypefun
1577
1578 All the above functions have in common that they use the global
1579 parameters for the congruential formula.  In multi-threaded programs it
1580 might sometimes be useful to have different parameters in different
1581 threads.  For this reason all the above functions have a counterpart
1582 which works on a description of the random number generator in the
1583 user-supplied buffer instead of the global state.
1584
1585 Please note that it is no problem if several threads use the global
1586 state if all threads use the functions which take a pointer to an array
1587 containing the state.  The random numbers are computed following the
1588 same loop but if the state in the array is different all threads will
1589 obtain an individual random number generator.
1590
1591 The user-supplied buffer must be of type @code{struct drand48_data}.
1592 This type should be regarded as opaque and not manipulated directly.
1593
1594 @comment stdlib.h
1595 @comment GNU
1596 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1597 This function is equivalent to the @code{drand48} function with the
1598 difference that it does not modify the global random number generator
1599 parameters but instead the parameters in the buffer supplied through the
1600 pointer @var{buffer}.  The random number is returned in the variable
1601 pointed to by @var{result}.
1602
1603 The return value of the function indicates whether the call succeeded.
1604 If the value is less than @code{0} an error occurred and @var{errno} is
1605 set to indicate the problem.
1606
1607 This function is a GNU extension and should not be used in portable
1608 programs.
1609 @end deftypefun
1610
1611 @comment stdlib.h
1612 @comment GNU
1613 @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
1614 The @code{erand48_r} function works like @code{erand48}, but in addition
1615 it takes an argument @var{buffer} which describes the random number
1616 generator.  The state of the random number generator is taken from the
1617 @code{xsubi} array, the parameters for the congruential formula from the
1618 global random number generator data.  The random number is returned in
1619 the variable pointed to by @var{result}.
1620
1621 The return value is non-negative if the call succeeded.
1622
1623 This function is a GNU extension and should not be used in portable
1624 programs.
1625 @end deftypefun
1626
1627 @comment stdlib.h
1628 @comment GNU
1629 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1630 This function is similar to @code{lrand48}, but in addition it takes a
1631 pointer to a buffer describing the state of the random number generator
1632 just like @code{drand48}.
1633
1634 If the return value of the function is non-negative the variable pointed
1635 to by @var{result} contains the result.  Otherwise an error occurred.
1636
1637 This function is a GNU extension and should not be used in portable
1638 programs.
1639 @end deftypefun
1640
1641 @comment stdlib.h
1642 @comment GNU
1643 @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1644 The @code{nrand48_r} function works like @code{nrand48} in that it
1645 produces a random number in the range @code{0} to @code{2^31}.  But instead
1646 of using the global parameters for the congruential formula it uses the
1647 information from the buffer pointed to by @var{buffer}.  The state is
1648 described by the values in @var{xsubi}.
1649
1650 If the return value is non-negative the variable pointed to by
1651 @var{result} contains the result.
1652
1653 This function is a GNU extension and should not be used in portable
1654 programs.
1655 @end deftypefun
1656
1657 @comment stdlib.h
1658 @comment GNU
1659 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1660 This function is similar to @code{mrand48} but like the other reentrant
1661 functions it uses the random number generator described by the value in
1662 the buffer pointed to by @var{buffer}.
1663
1664 If the return value is non-negative the variable pointed to by
1665 @var{result} contains the result.
1666
1667 This function is a GNU extension and should not be used in portable
1668 programs.
1669 @end deftypefun
1670
1671 @comment stdlib.h
1672 @comment GNU
1673 @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1674 The @code{jrand48_r} function is similar to @code{jrand48}.  Like the
1675 other reentrant functions of this function family it uses the
1676 congruential formula parameters from the buffer pointed to by
1677 @var{buffer}.
1678
1679 If the return value is non-negative the variable pointed to by
1680 @var{result} contains the result.
1681
1682 This function is a GNU extension and should not be used in portable
1683 programs.
1684 @end deftypefun
1685
1686 Before any of the above functions are used the buffer of type
1687 @code{struct drand48_data} should be initialized.  The easiest way to do
1688 this is to fill the whole buffer with null bytes, e.g. by
1689
1690 @smallexample
1691 memset (buffer, '\0', sizeof (struct drand48_data));
1692 @end smallexample
1693
1694 @noindent
1695 Using any of the reentrant functions of this family now will
1696 automatically initialize the random number generator to the default
1697 values for the state and the parameters of the congruential formula.
1698
1699 The other possibility is to use any of the functions which explicitly
1700 initialize the buffer.  Though it might be obvious how to initialize the
1701 buffer from looking at the parameter to the function, it is highly
1702 recommended to use these functions since the result might not always be
1703 what you expect.
1704
1705 @comment stdlib.h
1706 @comment GNU
1707 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1708 The description of the random number generator represented by the
1709 information in @var{buffer} is initialized similarly to what the function
1710 @code{srand48} does.  The state is initialized from the parameter
1711 @var{seedval} and the parameters for the congruential formula are
1712 initialized to their default values.
1713
1714 If the return value is non-negative the function call succeeded.
1715
1716 This function is a GNU extension and should not be used in portable
1717 programs.
1718 @end deftypefun
1719
1720 @comment stdlib.h
1721 @comment GNU
1722 @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
1723 This function is similar to @code{srand48_r} but like @code{seed48} it
1724 initializes all 48 bits of the state from the parameter @var{seed16v}.
1725
1726 If the return value is non-negative the function call succeeded.  It
1727 does not return a pointer to the previous state of the random number
1728 generator like the @code{seed48} function does.  If the user wants to
1729 preserve the state for a later re-run s/he can copy the whole buffer
1730 pointed to by @var{buffer}.
1731
1732 This function is a GNU extension and should not be used in portable
1733 programs.
1734 @end deftypefun
1735
1736 @comment stdlib.h
1737 @comment GNU
1738 @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
1739 This function initializes all aspects of the random number generator
1740 described in @var{buffer} with the data in @var{param}.  Here it is
1741 especially true that the function does more than just copying the
1742 contents of @var{param} and @var{buffer}.  More work is required and
1743 therefore it is important to use this function rather than initializing
1744 the random number generator directly.
1745
1746 If the return value is non-negative the function call succeeded.
1747
1748 This function is a GNU extension and should not be used in portable
1749 programs.
1750 @end deftypefun
1751
1752 @node FP Function Optimizations
1753 @section Is Fast Code or Small Code preferred?
1754 @cindex Optimization
1755
1756 If an application uses many floating point functions it is often the case
1757 that the cost of the function calls themselves is not negligible.
1758 Modern processors can often execute the operations themselves
1759 very fast, but the function call disrupts the instruction pipeline.
1760
1761 For this reason the GNU C Library provides optimizations for many of the
1762 frequently-used math functions.  When GNU CC is used and the user
1763 activates the optimizer, several new inline functions and macros are
1764 defined.  These new functions and macros have the same names as the
1765 library functions and so are used instead of the latter.  In the case of
1766 inline functions the compiler will decide whether it is reasonable to
1767 use them, and this decision is usually correct.
1768
1769 This means that no calls to the library functions may be necessary, and
1770 can increase the speed of generated code significantly.  The drawback is
1771 that code size will increase, and the increase is not always negligible.
1772
1773 There are two kind of inline functions: Those that give the same result
1774 as the library functions and others that might not set @code{errno} and
1775 might have a reduced precision and/or argument range in comparison with
1776 the library functions.  The latter inline functions are only available
1777 if the flag @code{-ffast-math} is given to GNU CC.
1778
1779 In cases where the inline functions and macros are not wanted the symbol
1780 @code{__NO_MATH_INLINES} should be defined before any system header is
1781 included.  This will ensure that only library functions are used.  Of
1782 course, it can be determined for each file in the project whether
1783 giving this option is preferable or not.
1784
1785 Not all hardware implements the entire @w{IEEE 754} standard, and even
1786 if it does there may be a substantial performance penalty for using some
1787 of its features.  For example, enabling traps on some processors forces
1788 the FPU to run un-pipelined, which can more than double calculation time.
1789 @c ***Add explanation of -lieee, -mieee.