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