(SVID Random): Mention header the functions are declared in.
[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 {long int} 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:} Temporarily this function was defined to return a
1368 @code{int32_t} value to indicate that the return value always contains
1369 32 bits even if @code{long int} is wider.  The standard demands it
1370 differently.  Users must always be aware of the 32-bit limitation,
1371 though.
1372 @end deftypefun
1373
1374 @comment stdlib.h
1375 @comment BSD
1376 @deftypefun void srandom (unsigned int @var{seed})
1377 The @code{srandom} function sets the state of the random number
1378 generator based on the integer @var{seed}.  If you supply a @var{seed} value
1379 of @code{1}, this will cause @code{random} to reproduce the default set
1380 of random numbers.
1381
1382 To produce a different set of pseudo-random numbers each time your
1383 program runs, do @code{srandom (time (0))}.
1384 @end deftypefun
1385
1386 @comment stdlib.h
1387 @comment BSD
1388 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1389 The @code{initstate} function is used to initialize the random number
1390 generator state.  The argument @var{state} is an array of @var{size}
1391 bytes, used to hold the state information.  It is initialized based on
1392 @var{seed}.  The size must be between 8 and 256 bytes, and should be a
1393 power of two.  The bigger the @var{state} array, the better.
1394
1395 The return value is the previous value of the state information array.
1396 You can use this value later as an argument to @code{setstate} to
1397 restore that state.
1398 @end deftypefun
1399
1400 @comment stdlib.h
1401 @comment BSD
1402 @deftypefun {void *} setstate (void *@var{state})
1403 The @code{setstate} function restores the random number state
1404 information @var{state}.  The argument must have been the result of
1405 a previous call to @var{initstate} or @var{setstate}.
1406
1407 The return value is the previous value of the state information array.
1408 You can use this value later as an argument to @code{setstate} to
1409 restore that state.
1410
1411 If the function fails the return value is @code{NULL}.
1412 @end deftypefun
1413
1414 @node SVID Random
1415 @subsection SVID Random Number Function
1416
1417 The C library on SVID systems contains yet another kind of random number
1418 generator functions.  They use a state of 48 bits of data.  The user can
1419 choose among a collection of functions which return the random bits
1420 in different forms.
1421
1422 Generally there are two kinds of function.  The first uses a state of
1423 the random number generator which is shared among several functions and
1424 by all threads of the process.  The second requires the user to handle
1425 the state.
1426
1427 All functions have in common that they use the same congruential
1428 formula with the same constants.  The formula is
1429
1430 @smallexample
1431 Y = (a * X + c) mod m
1432 @end smallexample
1433
1434 @noindent
1435 where @var{X} is the state of the generator at the beginning and
1436 @var{Y} the state at the end.  @code{a} and @code{c} are constants
1437 determining the way the generator works.  By default they are
1438
1439 @smallexample
1440 a = 0x5DEECE66D = 25214903917
1441 c = 0xb = 11
1442 @end smallexample
1443
1444 @noindent
1445 but they can also be changed by the user.  @code{m} is of course 2^48
1446 since the state consists of a 48-bit array.
1447
1448 The prototypes for these functions are in @file{stdlib.h}.
1449 @pindex stdlib.h
1450
1451
1452 @comment stdlib.h
1453 @comment SVID
1454 @deftypefun double drand48 (void)
1455 This function returns a @code{double} value in the range of @code{0.0}
1456 to @code{1.0} (exclusive).  The random bits are determined by the global
1457 state of the random number generator in the C library.
1458
1459 Since the @code{double} type according to @w{IEEE 754} has a 52-bit
1460 mantissa this means 4 bits are not initialized by the random number
1461 generator.  These are (of course) chosen to be the least significant
1462 bits and they are initialized to @code{0}.
1463 @end deftypefun
1464
1465 @comment stdlib.h
1466 @comment SVID
1467 @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
1468 This function returns a @code{double} value in the range of @code{0.0}
1469 to @code{1.0} (exclusive), similarly to @code{drand48}.  The argument is
1470 an array describing the state of the random number generator.
1471
1472 This function can be called subsequently since it updates the array to
1473 guarantee random numbers.  The array should have been initialized before
1474 initial use to obtain reproducible results.
1475 @end deftypefun
1476
1477 @comment stdlib.h
1478 @comment SVID
1479 @deftypefun {long int} lrand48 (void)
1480 The @code{lrand48} function returns an integer value in the range of
1481 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
1482 int} type can take more than 32 bits, no higher numbers are returned.
1483 The random bits are determined by the global state of the random number
1484 generator in the C library.
1485 @end deftypefun
1486
1487 @comment stdlib.h
1488 @comment SVID
1489 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
1490 This function is similar to the @code{lrand48} function in that it
1491 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1492 the state of the random number generator used to produce the random bits
1493 is determined by the array provided as the parameter to the function.
1494
1495 The numbers in the array are updated afterwards so that subsequent calls
1496 to this function yield different results (as is expected of a random
1497 number generator).  The array should have been initialized before the
1498 first call to obtain reproducible results.
1499 @end deftypefun
1500
1501 @comment stdlib.h
1502 @comment SVID
1503 @deftypefun {long int} mrand48 (void)
1504 The @code{mrand48} function is similar to @code{lrand48}.  The only
1505 difference is that the numbers returned are in the range @code{-2^31} to
1506 @code{2^31} (exclusive).
1507 @end deftypefun
1508
1509 @comment stdlib.h
1510 @comment SVID
1511 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
1512 The @code{jrand48} function is similar to @code{nrand48}.  The only
1513 difference is that the numbers returned are in the range @code{-2^31} to
1514 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
1515 requirements are necessary.
1516 @end deftypefun
1517
1518 The internal state of the random number generator can be initialized in
1519 several ways.  The methods differ in the completeness of the
1520 information provided.
1521
1522 @comment stdlib.h
1523 @comment SVID
1524 @deftypefun void srand48 (long int @var{seedval})
1525 The @code{srand48} function sets the most significant 32 bits of the
1526 internal state of the random number generator to the least
1527 significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
1528 are initialized to the value @code{0x330E}.  Even if the @code{long
1529 int} type contains more than 32 bits only the lower 32 bits are used.
1530
1531 Owing to this limitation, initialization of the state of this
1532 function is not very useful.  But it makes it easy to use a construct
1533 like @code{srand48 (time (0))}.
1534
1535 A side-effect of this function is that the values @code{a} and @code{c}
1536 from the internal state, which are used in the congruential formula,
1537 are reset to the default values given above.  This is of importance once
1538 the user has called the @code{lcong48} function (see below).
1539 @end deftypefun
1540
1541 @comment stdlib.h
1542 @comment SVID
1543 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
1544 The @code{seed48} function initializes all 48 bits of the state of the
1545 internal random number generator from the contents of the parameter
1546 @var{seed16v}.  Here the lower 16 bits of the first element of
1547 @var{see16v} initialize the least significant 16 bits of the internal
1548 state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
1549 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
1550 initialize the most significant 16 bits of the state.
1551
1552 Unlike @code{srand48} this function lets the user initialize all 48 bits
1553 of the state.
1554
1555 The value returned by @code{seed48} is a pointer to an array containing
1556 the values of the internal state before the change.  This might be
1557 useful to restart the random number generator at a certain state.
1558 Otherwise the value can simply be ignored.
1559
1560 As for @code{srand48}, the values @code{a} and @code{c} from the
1561 congruential formula are reset to the default values.
1562 @end deftypefun
1563
1564 There is one more function to initialize the random number generator
1565 which enables you to specify even more information by allowing you to
1566 change the parameters in the congruential formula.
1567
1568 @comment stdlib.h
1569 @comment SVID
1570 @deftypefun void lcong48 (unsigned short int @var{param}[7])
1571 The @code{lcong48} function allows the user to change the complete state
1572 of the random number generator.  Unlike @code{srand48} and
1573 @code{seed48}, this function also changes the constants in the
1574 congruential formula.
1575
1576 From the seven elements in the array @var{param} the least significant
1577 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
1578 determine the initial state, the least significant 16 bits of
1579 @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
1580 constant @code{a} and @code{@var{param}[6]} determines the 16-bit value
1581 @code{c}.
1582 @end deftypefun
1583
1584 All the above functions have in common that they use the global
1585 parameters for the congruential formula.  In multi-threaded programs it
1586 might sometimes be useful to have different parameters in different
1587 threads.  For this reason all the above functions have a counterpart
1588 which works on a description of the random number generator in the
1589 user-supplied buffer instead of the global state.
1590
1591 Please note that it is no problem if several threads use the global
1592 state if all threads use the functions which take a pointer to an array
1593 containing the state.  The random numbers are computed following the
1594 same loop but if the state in the array is different all threads will
1595 obtain an individual random number generator.
1596
1597 The user-supplied buffer must be of type @code{struct drand48_data}.
1598 This type should be regarded as opaque and not manipulated directly.
1599
1600 @comment stdlib.h
1601 @comment GNU
1602 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1603 This function is equivalent to the @code{drand48} function with the
1604 difference that it does not modify the global random number generator
1605 parameters but instead the parameters in the buffer supplied through the
1606 pointer @var{buffer}.  The random number is returned in the variable
1607 pointed to by @var{result}.
1608
1609 The return value of the function indicates whether the call succeeded.
1610 If the value is less than @code{0} an error occurred and @var{errno} is
1611 set to indicate the problem.
1612
1613 This function is a GNU extension and should not be used in portable
1614 programs.
1615 @end deftypefun
1616
1617 @comment stdlib.h
1618 @comment GNU
1619 @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
1620 The @code{erand48_r} function works like @code{erand48}, but in addition
1621 it takes an argument @var{buffer} which describes the random number
1622 generator.  The state of the random number generator is taken from the
1623 @code{xsubi} array, the parameters for the congruential formula from the
1624 global random number generator data.  The random number is returned in
1625 the variable pointed to by @var{result}.
1626
1627 The return value is non-negative if the call succeeded.
1628
1629 This function is a GNU extension and should not be used in portable
1630 programs.
1631 @end deftypefun
1632
1633 @comment stdlib.h
1634 @comment GNU
1635 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1636 This function is similar to @code{lrand48}, but in addition it takes a
1637 pointer to a buffer describing the state of the random number generator
1638 just like @code{drand48}.
1639
1640 If the return value of the function is non-negative the variable pointed
1641 to by @var{result} contains the result.  Otherwise an error occurred.
1642
1643 This function is a GNU extension and should not be used in portable
1644 programs.
1645 @end deftypefun
1646
1647 @comment stdlib.h
1648 @comment GNU
1649 @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1650 The @code{nrand48_r} function works like @code{nrand48} in that it
1651 produces a random number in the range @code{0} to @code{2^31}.  But instead
1652 of using the global parameters for the congruential formula it uses the
1653 information from the buffer pointed to by @var{buffer}.  The state is
1654 described by the values in @var{xsubi}.
1655
1656 If the return value is non-negative the variable pointed to by
1657 @var{result} contains the result.
1658
1659 This function is a GNU extension and should not be used in portable
1660 programs.
1661 @end deftypefun
1662
1663 @comment stdlib.h
1664 @comment GNU
1665 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1666 This function is similar to @code{mrand48} but like the other reentrant
1667 functions it uses the random number generator described by the value in
1668 the buffer pointed to by @var{buffer}.
1669
1670 If the return value is non-negative the variable pointed to by
1671 @var{result} contains the result.
1672
1673 This function is a GNU extension and should not be used in portable
1674 programs.
1675 @end deftypefun
1676
1677 @comment stdlib.h
1678 @comment GNU
1679 @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1680 The @code{jrand48_r} function is similar to @code{jrand48}.  Like the
1681 other reentrant functions of this function family it uses the
1682 congruential formula parameters from the buffer pointed to by
1683 @var{buffer}.
1684
1685 If the return value is non-negative the variable pointed to by
1686 @var{result} contains the result.
1687
1688 This function is a GNU extension and should not be used in portable
1689 programs.
1690 @end deftypefun
1691
1692 Before any of the above functions are used the buffer of type
1693 @code{struct drand48_data} should be initialized.  The easiest way to do
1694 this is to fill the whole buffer with null bytes, e.g. by
1695
1696 @smallexample
1697 memset (buffer, '\0', sizeof (struct drand48_data));
1698 @end smallexample
1699
1700 @noindent
1701 Using any of the reentrant functions of this family now will
1702 automatically initialize the random number generator to the default
1703 values for the state and the parameters of the congruential formula.
1704
1705 The other possibility is to use any of the functions which explicitly
1706 initialize the buffer.  Though it might be obvious how to initialize the
1707 buffer from looking at the parameter to the function, it is highly
1708 recommended to use these functions since the result might not always be
1709 what you expect.
1710
1711 @comment stdlib.h
1712 @comment GNU
1713 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1714 The description of the random number generator represented by the
1715 information in @var{buffer} is initialized similarly to what the function
1716 @code{srand48} does.  The state is initialized from the parameter
1717 @var{seedval} and the parameters for the congruential formula are
1718 initialized to their default values.
1719
1720 If the return value is non-negative the function call succeeded.
1721
1722 This function is a GNU extension and should not be used in portable
1723 programs.
1724 @end deftypefun
1725
1726 @comment stdlib.h
1727 @comment GNU
1728 @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
1729 This function is similar to @code{srand48_r} but like @code{seed48} it
1730 initializes all 48 bits of the state from the parameter @var{seed16v}.
1731
1732 If the return value is non-negative the function call succeeded.  It
1733 does not return a pointer to the previous state of the random number
1734 generator like the @code{seed48} function does.  If the user wants to
1735 preserve the state for a later re-run s/he can copy the whole buffer
1736 pointed to by @var{buffer}.
1737
1738 This function is a GNU extension and should not be used in portable
1739 programs.
1740 @end deftypefun
1741
1742 @comment stdlib.h
1743 @comment GNU
1744 @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
1745 This function initializes all aspects of the random number generator
1746 described in @var{buffer} with the data in @var{param}.  Here it is
1747 especially true that the function does more than just copying the
1748 contents of @var{param} and @var{buffer}.  More work is required and
1749 therefore it is important to use this function rather than initializing
1750 the random number generator directly.
1751
1752 If the return value is non-negative the function call succeeded.
1753
1754 This function is a GNU extension and should not be used in portable
1755 programs.
1756 @end deftypefun
1757
1758 @node FP Function Optimizations
1759 @section Is Fast Code or Small Code preferred?
1760 @cindex Optimization
1761
1762 If an application uses many floating point functions it is often the case
1763 that the cost of the function calls themselves is not negligible.
1764 Modern processors can often execute the operations themselves
1765 very fast, but the function call disrupts the instruction pipeline.
1766
1767 For this reason the GNU C Library provides optimizations for many of the
1768 frequently-used math functions.  When GNU CC is used and the user
1769 activates the optimizer, several new inline functions and macros are
1770 defined.  These new functions and macros have the same names as the
1771 library functions and so are used instead of the latter.  In the case of
1772 inline functions the compiler will decide whether it is reasonable to
1773 use them, and this decision is usually correct.
1774
1775 This means that no calls to the library functions may be necessary, and
1776 can increase the speed of generated code significantly.  The drawback is
1777 that code size will increase, and the increase is not always negligible.
1778
1779 There are two kind of inline functions: Those that give the same result
1780 as the library functions and others that might not set @code{errno} and
1781 might have a reduced precision and/or argument range in comparison with
1782 the library functions.  The latter inline functions are only available
1783 if the flag @code{-ffast-math} is given to GNU CC.
1784
1785 In cases where the inline functions and macros are not wanted the symbol
1786 @code{__NO_MATH_INLINES} should be defined before any system header is
1787 included.  This will ensure that only library functions are used.  Of
1788 course, it can be determined for each file in the project whether
1789 giving this option is preferable or not.
1790
1791 Not all hardware implements the entire @w{IEEE 754} standard, and even
1792 if it does there may be a substantial performance penalty for using some
1793 of its features.  For example, enabling traps on some processors forces
1794 the FPU to run un-pipelined, which can more than double calculation time.
1795 @c ***Add explanation of -lieee, -mieee.