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