1 @c We need some definitions here.
2 @ifclear mult
3 @ifhtml
4 @set mult &middot;
5 @set infty &infin;
6 @set pie &pi;
7 @end ifhtml
8 @iftex
9 @set mult @cdot
10 @set infty @infty
11 @end iftex
12 @ifclear mult
13 @set mult *
14 @set infty oo
15 @set pie pi
16 @end ifclear
17 @macro mul
18 @value{mult}
19 @end macro
20 @macro infinity
21 @value{infty}
22 @end macro
23 @ifnottex
24 @macro pi
25 @value{pie}
26 @end macro
27 @end ifnottex
28 @end ifclear
30 @node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
31 @c %MENU% Math functions, useful constants, random numbers
32 @chapter Mathematics
34 This chapter contains information about functions for performing
35 mathematical computations, such as trigonometric functions.  Most of
36 these functions have prototypes declared in the header file
37 @file{math.h}.  The complex-valued functions are defined in
38 @file{complex.h}.
39 @pindex math.h
40 @pindex complex.h
42 All mathematical functions which take a floating-point argument
43 have three variants, one each for @code{double}, @code{float}, and
44 @code{long double} arguments.  The @code{double} versions are mostly
45 defined in @w{ISO C 89}.  The @code{float} and @code{long double}
46 versions are from the numeric extensions to C included in @w{ISO C 9X}.
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}.
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.
69 @node Mathematical Constants
70 @section Predefined Mathematical Constants
71 @cindex constants
72 @cindex mathematical constants
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:
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
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}.
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.
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.
128 @node Trig Functions
129 @section Trigonometric Functions
130 @cindex trigonometric functions
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.
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:
142 @smallexample
143 #define M_PI 3.14159265358979323846264338327
144 @end smallexample
146 @noindent
147 You can also compute the value of pi with the expression @code{acos
148 (-1.0)}.
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
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
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
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
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.
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}.
196 This function is a GNU extension.  Portable programs should be prepared
197 to cope with its absence.
198 @end deftypefun
200 @cindex complex trigonometric functions
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.)
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
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
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
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
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
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
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
264 @node Inverse Trig Functions
265 @section Inverse Trigonometric Functions
266 @cindex inverse trigonometric functions
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.
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).
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
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).
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
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
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.
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}.)
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
334 @cindex inverse complex trigonometric functions
335 @w{ISO C 9x} defines complex versions of the inverse trig functions.
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.
345 Unlike the real-valued functions, @code{casin} is defined for all
346 values of @var{z}.
347 @end deftypefun
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.
357 Unlike the real-valued functions, @code{cacos} is defined for all
358 values of @var{z}.
359 @end deftypefun
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
372 @node Exponents and Logarithms
373 @section Exponentiation and Logarithms
374 @cindex exponentiation functions
375 @cindex power functions
376 @cindex logarithm functions
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}.
386 If the magnitude of the result is too large to be representable,
387 @code{exp} signals overflow.
388 @end deftypefun
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
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))}.
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
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.
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
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)}.
437 @end deftypefun
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
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.
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
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
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.
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}.
483 This macro is defined in @w{ISO C 9X}.
484 @end deftypevr
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}.
492 This macro is defined in @w{ISO C 9X}.
493 @end deftypevr
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:
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
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}.
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
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}.
540 If @var{x} is negative, @code{sqrt} signals a domain error.
541 Mathematically, it should return a complex number.
542 @end deftypefun
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
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
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
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
588 @cindex complex exponentiation functions
589 @cindex complex logarithm functions
591 @w{ISO C 9X} defines complex variants of some of the exponentiation and
592 logarithm functions.
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
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
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
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
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
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
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
648 These functions are GNU extensions.
649 @end deftypefun
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
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
669 @node Hyperbolic Functions
670 @section Hyperbolic Functions
671 @cindex hyperbolic functions
673 The functions in this section are related to the exponential functions;
674 see @ref{Exponents and Logarithms}.
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
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
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
706 @cindex hyperbolic functions
708 There are counterparts for the hyperbolic functions which take
709 complex arguments.
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
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
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
739 @cindex inverse hyperbolic functions
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
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
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
771 @cindex inverse complex hyperbolic functions
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
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
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
803 @node Special Functions
804 @section Special Functions
805 @cindex special functions
806 @cindex Bessel functions
807 @cindex gamma function
809 These are some more exotic mathematical functions, which are sometimes
810 useful.  Currently they only have real-valued versions.
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
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
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
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.
860 You can compute the actual gamma function as follows:
861 @smallexample
862 lgam = lgamma(x);
863 gam  = signgam*exp(lgam);
864 @end smallexample
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
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
881 @ignore
882 @comment math.h
883 @comment SVID
884 @deftypefun double gamma (double @var{x})
885 @deftypefunx float gammaf (float @var{x})
886 @deftypefunx {long double} gammal (long double @var{x})
887 ??? _not_ exp(lgamma())*signgam - historical?
888 @end deftypefun
889 @end ignore
891 @comment math.h
892 @comment SVID
893 @deftypefun double j0 (double @var{x})
894 @deftypefunx float j0f (float @var{x})
895 @deftypefunx {long double} j0l (long double @var{x})
896 @code{j0} returns the Bessel function of the first kind of order 0 of
897 @var{x}.  It may signal underflow if @var{x} is too large.
898 @end deftypefun
900 @comment math.h
901 @comment SVID
902 @deftypefun double j1 (double @var{x})
903 @deftypefunx float j1f (float @var{x})
904 @deftypefunx {long double} j1l (long double @var{x})
905 @code{j1} returns the Bessel function of the first kind of order 1 of
906 @var{x}.  It may signal underflow if @var{x} is too large.
907 @end deftypefun
909 @comment math.h
910 @comment SVID
911 @deftypefun double jn (int n, double @var{x})
912 @deftypefunx float jnf (int n, float @var{x})
913 @deftypefunx {long double} jnl (int n, long double @var{x})
914 @code{jn} returns the Bessel function of the first kind of order
915 @var{n} of @var{x}.  It may signal underflow if @var{x} is too large.
916 @end deftypefun
918 @comment math.h
919 @comment SVID
920 @deftypefun double y0 (double @var{x})
921 @deftypefunx float y0f (float @var{x})
922 @deftypefunx {long double} y0l (long double @var{x})
923 @code{y0} returns the Bessel function of the second kind of order 0 of
924 @var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
925 is negative, @code{y0} signals a domain error; if it is zero,
926 @code{y0} signals overflow and returns @math{-@infinity}.
927 @end deftypefun
929 @comment math.h
930 @comment SVID
931 @deftypefun double y1 (double @var{x})
932 @deftypefunx float y1f (float @var{x})
933 @deftypefunx {long double} y1l (long double @var{x})
934 @code{y1} returns the Bessel function of the second kind of order 1 of
935 @var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
936 is negative, @code{y1} signals a domain error; if it is zero,
937 @code{y1} signals overflow and returns @math{-@infinity}.
938 @end deftypefun
940 @comment math.h
941 @comment SVID
942 @deftypefun double yn (int n, double @var{x})
943 @deftypefunx float ynf (int n, float @var{x})
944 @deftypefunx {long double} ynl (int n, long double @var{x})
945 @code{yn} returns the Bessel function of the second kind of order @var{n} of
946 @var{x}.  It may signal underflow if @var{x} is too large.  If @var{x}
947 is negative, @code{yn} signals a domain error; if it is zero,
948 @code{yn} signals overflow and returns @math{-@infinity}.
949 @end deftypefun
951 @node Pseudo-Random Numbers
952 @section Pseudo-Random Numbers
953 @cindex random numbers
954 @cindex pseudo-random numbers
955 @cindex seed (for random numbers)
957 This section describes the GNU facilities for generating a series of
958 pseudo-random numbers.  The numbers generated are not truly random;
959 typically, they form a sequence that repeats periodically, with a period
960 so large that you can ignore it for ordinary purposes.  The random
961 number generator works by remembering a @dfn{seed} value which it uses
962 to compute the next random number and also to compute a new seed.
964 Although the generated numbers look unpredictable within one run of a
965 program, the sequence of numbers is @emph{exactly the same} from one run
966 to the next.  This is because the initial seed is always the same.  This
967 is convenient when you are debugging a program, but it is unhelpful if
968 you want the program to behave unpredictably.  If you want a different
969 pseudo-random series each time your program runs, you must specify a
970 different seed each time.  For ordinary purposes, basing the seed on the
971 current time works well.
973 You can get repeatable sequences of numbers on a particular machine type
974 by specifying the same initial seed value for the random number
975 generator.  There is no standard meaning for a particular seed value;
976 the same seed, used in different C libraries or on different CPU types,
977 will give you different random numbers.
979 The GNU library supports the standard @w{ISO C} random number functions
980 plus two other sets derived from BSD and SVID.  The BSD and @w{ISO C}
981 functions provide identical, somewhat limited functionality.  If only a
982 small number of random bits are required, we recommend you use the
983 @w{ISO C} interface, @code{rand} and @code{srand}.  The SVID functions
984 provide a more flexible interface, which allows better random number
985 generator algorithms, provides more random bits (up to 48) per call, and
986 can provide random floating-point numbers.  These functions are required
987 by the XPG standard and therefore will be present in all modern Unix
988 systems.
991 * ISO Random::                  @code{rand} and friends.
992 * BSD Random::                  @code{random} and friends.
993 * SVID Random::                 @code{drand48} and friends.
996 @node ISO Random
997 @subsection ISO C Random Number Functions
999 This section describes the random number functions that are part of
1000 the @w{ISO C} standard.
1002 To use these facilities, you should include the header file
1003 @file{stdlib.h} in your program.
1004 @pindex stdlib.h
1006 @comment stdlib.h
1007 @comment ISO
1008 @deftypevr Macro int RAND_MAX
1009 The value of this macro is an integer constant representing the largest
1010 value the @code{rand} function can return.  In the GNU library, it is
1011 @code{2147483647}, which is the largest signed integer representable in
1012 32 bits.  In other libraries, it may be as low as @code{32767}.
1013 @end deftypevr
1015 @comment stdlib.h
1016 @comment ISO
1017 @deftypefun int rand (void)
1018 The @code{rand} function returns the next pseudo-random number in the
1019 series.  The value ranges from @code{0} to @code{RAND_MAX}.
1020 @end deftypefun
1022 @comment stdlib.h
1023 @comment ISO
1024 @deftypefun void srand (unsigned int @var{seed})
1025 This function establishes @var{seed} as the seed for a new series of
1026 pseudo-random numbers.  If you call @code{rand} before a seed has been
1027 established with @code{srand}, it uses the value @code{1} as a default
1028 seed.
1030 To produce a different pseudo-random series each time your program is
1031 run, do @code{srand (time (0))}.
1032 @end deftypefun
1034 POSIX.1 extended the C standard functions to support reproducible random
1036 designed and unsuitable for serious work.
1038 @comment stdlib.h
1039 @comment POSIX.1
1040 @deftypefun int rand_r (unsigned int *@var{seed})
1041 This function returns a random number in the range 0 to @code{RAND_MAX}
1042 just as @code{rand} does.  However, all its state is stored in the
1043 @var{seed} argument.  This means the RNG's state can only have as many
1044 bits as the type @code{unsigned int} has.  This is far too few to
1045 provide a good RNG.
1047 If your program requires a reentrant RNG, we recommend you use the
1048 reentrant GNU extensions to the SVID random number generator.  The
1049 POSIX.1 interface should only be used when the GNU extensions are not
1050 available.
1051 @end deftypefun
1054 @node BSD Random
1055 @subsection BSD Random Number Functions
1057 This section describes a set of random number generation functions that
1058 are derived from BSD.  There is no advantage to using these functions
1059 with the GNU C library; we support them for BSD compatibility only.
1061 The prototypes for these functions are in @file{stdlib.h}.
1062 @pindex stdlib.h
1064 @comment stdlib.h
1065 @comment BSD
1066 @deftypefun {int32_t} random (void)
1067 This function returns the next pseudo-random number in the sequence.
1068 The value returned ranges from @code{0} to @code{RAND_MAX}.
1070 @strong{Note:} Historically this function returned a @code{long
1071 int} value.  On 64bit systems @code{long int} would have been larger
1072 than programs expected, so @code{random} is now defined to return
1073 exactly 32 bits.
1074 @end deftypefun
1076 @comment stdlib.h
1077 @comment BSD
1078 @deftypefun void srandom (unsigned int @var{seed})
1079 The @code{srandom} function sets the state of the random number
1080 generator based on the integer @var{seed}.  If you supply a @var{seed} value
1081 of @code{1}, this will cause @code{random} to reproduce the default set
1082 of random numbers.
1084 To produce a different set of pseudo-random numbers each time your
1085 program runs, do @code{srandom (time (0))}.
1086 @end deftypefun
1088 @comment stdlib.h
1089 @comment BSD
1090 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1091 The @code{initstate} function is used to initialize the random number
1092 generator state.  The argument @var{state} is an array of @var{size}
1093 bytes, used to hold the state information.  It is initialized based on
1094 @var{seed}.  The size must be between 8 and 256 bytes, and should be a
1095 power of two.  The bigger the @var{state} array, the better.
1097 The return value is the previous value of the state information array.
1098 You can use this value later as an argument to @code{setstate} to
1099 restore that state.
1100 @end deftypefun
1102 @comment stdlib.h
1103 @comment BSD
1104 @deftypefun {void *} setstate (void *@var{state})
1105 The @code{setstate} function restores the random number state
1106 information @var{state}.  The argument must have been the result of
1107 a previous call to @var{initstate} or @var{setstate}.
1109 The return value is the previous value of the state information array.
1110 You can use this value later as an argument to @code{setstate} to
1111 restore that state.
1112 @end deftypefun
1114 @node SVID Random
1115 @subsection SVID Random Number Function
1117 The C library on SVID systems contains yet another kind of random number
1118 generator functions.  They use a state of 48 bits of data.  The user can
1119 choose among a collection of functions which return the random bits
1120 in different forms.
1122 Generally there are two kinds of functions: those which use a state of
1123 the random number generator which is shared among several functions and
1124 by all threads of the process.  The second group of functions require
1125 the user to handle the state.
1127 All functions have in common that they use the same congruential
1128 formula with the same constants.  The formula is
1130 @smallexample
1131 Y = (a * X + c) mod m
1132 @end smallexample
1134 @noindent
1135 where @var{X} is the state of the generator at the beginning and
1136 @var{Y} the state at the end.  @code{a} and @code{c} are constants
1137 determining the way the generator work.  By default they are
1139 @smallexample
1140 a = 0x5DEECE66D = 25214903917
1141 c = 0xb = 11
1142 @end smallexample
1144 @noindent
1145 but they can also be changed by the user.  @code{m} is of course 2^48
1146 since the state consists of a 48 bit array.
1149 @comment stdlib.h
1150 @comment SVID
1151 @deftypefun double drand48 (void)
1152 This function returns a @code{double} value in the range of @code{0.0}
1153 to @code{1.0} (exclusive).  The random bits are determined by the global
1154 state of the random number generator in the C library.
1156 Since the @code{double} type according to @w{IEEE 754} has a 52 bit
1157 mantissa this means 4 bits are not initialized by the random number
1158 generator.  These are (of course) chosen to be the least significant
1159 bits and they are initialized to @code{0}.
1160 @end deftypefun
1162 @comment stdlib.h
1163 @comment SVID
1164 @deftypefun double erand48 (unsigned short int @var{xsubi})
1165 This function returns a @code{double} value in the range of @code{0.0}
1166 to @code{1.0} (exclusive), similar to @code{drand48}.  The argument is
1167 an array describing the state of the random number generator.
1169 This function can be called subsequently since it updates the array to
1170 guarantee random numbers.  The array should have been initialized before
1171 using to get reproducible results.
1172 @end deftypefun
1174 @comment stdlib.h
1175 @comment SVID
1176 @deftypefun {long int} lrand48 (void)
1177 The @code{lrand48} functions return an integer value in the range of
1178 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
1179 int} type can take more than 32 bits no higher numbers are returned.
1180 The random bits are determined by the global state of the random number
1181 generator in the C library.
1182 @end deftypefun
1184 @comment stdlib.h
1185 @comment SVID
1186 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi})
1187 This function is similar to the @code{lrand48} function in that it
1188 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1189 the state of the random number generator used to produce the random bits
1190 is determined by the array provided as the parameter to the function.
1192 The numbers in the array are afterwards updated so that subsequent calls
1193 to this function yield to different results (as it is expected by a
1194 random number generator).  The array should have been initialized before
1195 the first call to get reproducible results.
1196 @end deftypefun
1198 @comment stdlib.h
1199 @comment SVID
1200 @deftypefun {long int} mrand48 (void)
1201 The @code{mrand48} function is similar to @code{lrand48}.  The only
1202 difference is that the numbers returned are in the range @code{-2^31} to
1203 @code{2^31} (exclusive).
1204 @end deftypefun
1206 @comment stdlib.h
1207 @comment SVID
1208 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi})
1209 The @code{jrand48} function is similar to @code{nrand48}.  The only
1210 difference is that the numbers returned are in the range @code{-2^31} to
1211 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
1212 requirements are necessary.
1213 @end deftypefun
1215 The internal state of the random number generator can be initialized in
1216 several ways.  The functions differ in the completeness of the
1217 information provided.
1219 @comment stdlib.h
1220 @comment SVID
1221 @deftypefun void srand48 (long int @var{seedval}))
1222 The @code{srand48} function sets the most significant 32 bits of the
1223 state internal state of the random number generator to the least
1224 significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
1225 are initialized to the value @code{0x330E}.  Even if the @code{long
1226 int} type contains more the 32 bits only the lower 32 bits are used.
1228 Due to this limitation the initialization of the state using this
1229 function of not very useful.  But it makes it easy to use a construct
1230 like @code{srand48 (time (0))}.
1232 A side-effect of this function is that the values @code{a} and @code{c}
1233 from the internal state, which are used in the congruential formula,
1234 are reset to the default values given above.  This is of importance once
1235 the user called the @code{lcong48} function (see below).
1236 @end deftypefun
1238 @comment stdlib.h
1239 @comment SVID
1240 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v})
1241 The @code{seed48} function initializes all 48 bits of the state of the
1242 internal random number generator from the content of the parameter
1243 @var{seed16v}.  Here the lower 16 bits of the first element of
1244 @var{see16v} initialize the least significant 16 bits of the internal
1245 state, the lower 16 bits of @code{@var{seed16v}} initialize the mid-order
1246 16 bits of the state and the 16 lower bits of @code{@var{seed16v}}
1247 initialize the most significant 16 bits of the state.
1249 Unlike @code{srand48} this function lets the user initialize all 48 bits
1250 of the state.
1252 The value returned by @code{seed48} is a pointer to an array containing
1253 the values of the internal state before the change.  This might be
1254 useful to restart the random number generator at a certain state.
1255 Otherwise, the value can simply be ignored.
1257 As for @code{srand48}, the values @code{a} and @code{c} from the
1258 congruential formula are reset to the default values.
1259 @end deftypefun
1261 There is one more function to initialize the random number generator
1262 which allows to specify even more information by allowing to change the
1263 parameters in the congruential formula.
1265 @comment stdlib.h
1266 @comment SVID
1267 @deftypefun void lcong48 (unsigned short int @var{param})
1268 The @code{lcong48} function allows the user to change the complete state
1269 of the random number generator.  Unlike @code{srand48} and
1270 @code{seed48}, this function also changes the constants in the
1271 congruential formula.
1273 From the seven elements in the array @var{param} the least significant
1274 16 bits of the entries @code{@var{param}} to @code{@var{param}}
1275 determine the initial state, the least 16 bits of
1276 @code{@var{param}} to @code{@var{param}} determine the 48 bit
1277 constant @code{a} and @code{@var{param}} determines the 16 bit value
1278 @code{c}.
1279 @end deftypefun
1281 All the above functions have in common that they use the global
1282 parameters for the congruential formula.  In multi-threaded programs it
1283 might sometimes be useful to have different parameters in different
1284 threads.  For this reason all the above functions have a counterpart
1285 which works on a description of the random number generator in the
1286 user-supplied buffer instead of the global state.
1288 Please note that it is no problem if several threads use the global
1289 state if all threads use the functions which take a pointer to an array
1290 containing the state.  The random numbers are computed following the
1291 same loop but if the state in the array is different all threads will
1292 get an individual random number generator.
1294 The user supplied buffer must be of type @code{struct drand48_data}.
1295 This type should be regarded as opaque and no member should be used
1296 directly.
1298 @comment stdlib.h
1299 @comment GNU
1300 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1301 This function is equivalent to the @code{drand48} function with the
1302 difference it does not modify the global random number generator
1303 parameters but instead the parameters is the buffer supplied by the
1304 buffer through the pointer @var{buffer}.  The random number is return in
1305 the variable pointed to by @var{result}.
1307 The return value of the function indicate whether the call succeeded.
1308 If the value is less than @code{0} an error occurred and @var{errno} is
1309 set to indicate the problem.
1311 This function is a GNU extension and should not be used in portable
1312 programs.
1313 @end deftypefun
1315 @comment stdlib.h
1316 @comment GNU
1317 @deftypefun int erand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, double *@var{result})
1318 The @code{erand48_r} function works like the @code{erand48} and it takes
1319 an argument @var{buffer} which describes the random number generator.
1320 The state of the random number generator is taken from the @code{xsubi}
1321 array, the parameters for the congruential formula from the global
1322 random number generator data.  The random number is return in the
1323 variable pointed to by @var{result}.
1325 The return value is non-negative is the call succeeded.
1327 This function is a GNU extension and should not be used in portable
1328 programs.
1329 @end deftypefun
1331 @comment stdlib.h
1332 @comment GNU
1333 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1334 This function is similar to @code{lrand48} and it takes a pointer to a
1335 buffer describing the state of the random number generator as a
1336 parameter just like @code{drand48}.
1338 If the return value of the function is non-negative the variable pointed
1339 to by @var{result} contains the result.  Otherwise an error occurred.
1341 This function is a GNU extension and should not be used in portable
1342 programs.
1343 @end deftypefun
1345 @comment stdlib.h
1346 @comment GNU
1347 @deftypefun int nrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
1348 The @code{nrand48_r} function works like @code{nrand48} in that it
1349 produces a random number in range @code{0} to @code{2^31}.  But instead
1350 of using the global parameters for the congruential formula it uses the
1351 information from the buffer pointed to by @var{buffer}.  The state is
1352 described by the values in @var{xsubi}.
1354 If the return value is non-negative the variable pointed to by
1355 @var{result} contains the result.
1357 This function is a GNU extension and should not be used in portable
1358 programs.
1359 @end deftypefun
1361 @comment stdlib.h
1362 @comment GNU
1363 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1364 This function is similar to @code{mrand48} but as the other reentrant
1365 function it uses the random number generator described by the value in
1366 the buffer pointed to by @var{buffer}.
1368 If the return value is non-negative the variable pointed to by
1369 @var{result} contains the result.
1371 This function is a GNU extension and should not be used in portable
1372 programs.
1373 @end deftypefun
1375 @comment stdlib.h
1376 @comment GNU
1377 @deftypefun int jrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
1378 The @code{jrand48_r} function is similar to @code{jrand48}.  But as the
1379 other reentrant functions of this function family it uses the
1380 congruential formula parameters from the buffer pointed to by
1381 @var{buffer}.
1383 If the return value is non-negative the variable pointed to by
1384 @var{result} contains the result.
1386 This function is a GNU extension and should not be used in portable
1387 programs.
1388 @end deftypefun
1390 Before any of the above functions should be used the buffer of type
1391 @code{struct drand48_data} should initialized.  The easiest way is to
1392 fill the whole buffer with null bytes, e.g., using
1394 @smallexample
1395 memset (buffer, '\0', sizeof (struct drand48_data));
1396 @end smallexample
1398 @noindent
1399 Using any of the reentrant functions of this family now will
1400 automatically initialize the random number generator to the default
1401 values for the state and the parameters of the congruential formula.
1403 The other possibility is too use any of the functions which explicitely
1404 initialize the buffer.  Though it might be obvious how to initialize the
1405 buffer from the data given as parameter from the function it is highly
1406 recommended to use these functions since the result might not always be
1407 what you expect.
1409 @comment stdlib.h
1410 @comment GNU
1411 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1412 The description of the random number generator represented by the
1413 information in @var{buffer} is initialized similar to what the function
1414 @code{srand48} does.  The state is initialized from the parameter
1415 @var{seedval} and the parameters for the congruential formula are
1416 initialized to the default values.
1418 If the return value is non-negative the function call succeeded.
1420 This function is a GNU extension and should not be used in portable
1421 programs.
1422 @end deftypefun
1424 @comment stdlib.h
1425 @comment GNU
1426 @deftypefun int seed48_r (unsigned short int @var{seed16v}, struct drand48_data *@var{buffer})
1427 This function is similar to @code{srand48_r} but like @code{seed48} it
1428 initializes all 48 bits of the state from the parameter @var{seed16v}.
1430 If the return value is non-negative the function call succeeded.  It
1431 does not return a pointer to the previous state of the random number
1432 generator like the @code{seed48} function does.  if the user wants to
1433 preserve the state for a later rerun s/he can copy the whole buffer
1434 pointed to by @var{buffer}.
1436 This function is a GNU extension and should not be used in portable
1437 programs.
1438 @end deftypefun
1440 @comment stdlib.h
1441 @comment GNU
1442 @deftypefun int lcong48_r (unsigned short int @var{param}, struct drand48_data *@var{buffer})
1443 This function initializes all aspects of the random number generator
1444 described in @var{buffer} by the data in @var{param}.  Here it is
1445 especially true the function does more than just copying the contents of
1446 @var{param} of @var{buffer}.  Some more actions are required and
1447 therefore it is important to use this function and not initialized the
1448 random number generator directly.
1450 If the return value is non-negative the function call succeeded.
1452 This function is a GNU extension and should not be used in portable
1453 programs.
1454 @end deftypefun
1456 @node FP Function Optimizations
1457 @section Is Fast Code or Small Code preferred?
1458 @cindex Optimization
1460 If an application uses many floating point function it is often the case
1461 that the costs for the function calls itselfs are not neglectable.
1462 Modern processor implementation often can execute the operation itself
1463 very fast but the call means a disturbance of the control flow.
1465 For this reason the GNU C Library provides optimizations for many of the
1466 frequently used math functions.  When the GNU CC is used and the user
1467 activates the optimizer several new inline functions and macros get
1468 defined.  These new functions and macros have the same names as the
1469 library function and so get used instead of the later.  In case of
1470 inline functions the compiler will decide whether it is reasonable to
1471 use the inline function and this decision is usually correct.
1473 For the generated code this means that no calls to the library functions
1474 are necessary.  This increases the speed significantly.  But the
1475 drawback is that the code size increases and this increase is not always
1476 neglectable.
1478 In cases where the inline functions and macros are not wanted the symbol
1479 @code{__NO_MATH_INLINES} should be defined before any system header is
1480 included.  This will make sure only library functions are used.  Of
1481 course it can be determined for each single file in the project whether
1482 giving this option is preferred or not.
1484 Not all hardware implements the entire @w{IEEE 754} standard, or if it
1485 does, there may be a substantial performance penalty for using some of
1486 its features.  For example, enabling traps on some processors forces
1487 the FPU to run unpipelined, which more than doubles calculation time.
1488 @c ***Add explanation of -lieee, -mieee.