1 @node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
2 @chapter Mathematics
4 This chapter contains information about functions for performing
5 mathematical computations, such as trigonometric functions.  Most of
6 these functions have prototypes declared in the header file
7 @file{math.h}.
8 @pindex math.h
10 For all functions which take a single floating-point argument and for
11 several other functions as well there are three different functions
12 available for the type @code{double}, @code{float}, and @code{long
13 double}.  The @code{double} versions of the functions are mostly defined
14 even in the @w{ISO C 89} standard.  The @code{float} and @code{long
15 double} variants are introduced in the numeric extensions for the C
16 language which are part of the @w{ISO C 9X} standard.
18 Which of the three versions of the function should be used depends on
19 the situation.  For most functions and implementation it is true that
20 speed and precision do not go together.  I.e., the @code{float} versions
21 are normally faster than the @code{double} and @code{long double}
22 versions.  On the other hand the @code{long double} version has the
23 highest precision.  One should always think about the actual needs and
24 in case of double using @code{double} is a good compromise.
28 * Domain and Range Errors::     Detecting overflow conditions and the like.
29 * Trig Functions::              Sine, cosine, and tangent.
30 * Inverse Trig Functions::      Arc sine, arc cosine, and arc tangent.
31 * Exponents and Logarithms::    Also includes square root.
32 * Hyperbolic Functions::        Hyperbolic sine and friends.
33 * Pseudo-Random Numbers::       Functions for generating pseudo-random
34                                  numbers.
37 @node Domain and Range Errors
38 @section Domain and Range Errors
40 @cindex domain error
41 Many of the functions listed in this chapter are defined mathematically
42 over a domain that is only a subset of real numbers.  For example, the
43 @code{acos} function is defined over the domain between @code{-1} and
44 @code{1}.  If you pass an argument to one of these functions that is
45 outside the domain over which it is defined, the function sets
46 @code{errno} to @code{EDOM} to indicate a @dfn{domain error}.  On
47 machines that support @w{IEEE 754} floating point, functions reporting
48 error @code{EDOM} also return a NaN.
50 Some of these functions are defined mathematically to result in a
51 complex value over parts of their domains.  The most familiar example of
52 this is taking the square root of a negative number.  The functions in
53 this chapter take only real arguments and return only real values;
54 therefore, if the value ought to be nonreal, this is treated as a domain
55 error.
57 @cindex range error
58 A related problem is that the mathematical result of a function may not
59 be representable as a floating point number.  If magnitude of the
60 correct result is too large to be represented, the function sets
61 @code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
62 returns a particular very large value (named by the macro
63 @code{HUGE_VAL}) or its negation (@w{@code{- HUGE_VAL}}).
65 If the magnitude of the result is too small, a value of zero is returned
66 instead.  In this case, @code{errno} might or might not be
67 set to @code{ERANGE}.
69 The only completely reliable way to check for domain and range errors is
70 to set @code{errno} to @code{0} before you call the mathematical function
71 and test @code{errno} afterward.  As a consequence of this use of
72 @code{errno}, use of the mathematical functions is not reentrant if you
73 check for errors.
75 @c !!! this isn't always true at the moment....
76 None of the mathematical functions ever generates signals as a result of
77 domain or range errors.  In particular, this means that you won't see
78 @code{SIGFPE} signals generated within these functions.  (@xref{Signal
79 Handling}, for more information about signals.)
81 @comment math.h
82 @comment ISO
83 @deftypevr Macro double HUGE_VAL
84 An expression representing a particular very large number.  On machines
85 that use @w{IEEE 754}/@w{IEEE 854} floating point format, the value is
86 infinity''.  On other machines, it's typically the largest positive
87 number that can be represented.
89 The value of this macro is used as the return value from various
90 mathematical @code{double} returning functions in overflow situations.
91 @end deftypevr
93 @comment math.h
94 @comment ISO
95 @deftypevr Macro float HUGE_VALF
96 This macro is similar to the @code{HUGE_VAL} macro except that it is
97 used by functions returning @code{float} values.
99 This macro is introduced in @w{ISO C 9X}.
100 @end deftypevr
102 @comment math.h
103 @comment ISO
104 @deftypevr Macro {long double} HUGE_VALL
105 This macro is similar to the @code{HUGE_VAL} macro except that it is
106 used by functions returning @code{long double} values.  The value is
107 only different from @code{HUGE_VAL} if the architecture really supports
108 @code{long double} values.
110 This macro is introduced in @w{ISO C 9X}.
111 @end deftypevr
114 @comment
116 For more information about floating-point representations and limits,
117 see @ref{Floating Point Parameters}.  In particular, the macro
118 @code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many
119 uses other than testing for an error in a mathematical function.
121 @node Trig Functions
122 @section Trigonometric Functions
123 @cindex trigonometric functions
125 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
126 The arguments to all of these functions are in units of radians; recall
127 that pi radians equals 180 degrees.
129 @cindex pi (trigonometric constant)
130 The math library does define a symbolic constant for pi in @file{math.h}
131 when BSD compliance is required (@pxref{Feature Test Macros}).  Beside
132 pi several other constants are defined.
134 @noindent
135 In case it is not possible to use this macro one easily can define it:
137 @smallexample
138 #define M_PI 3.14159265358979323846264338327
139 @end smallexample
141 @noindent
142 You can also compute the value of pi with the expression @code{acos
143 (-1.0)}.
146 @comment math.h
147 @comment ISO
148 @deftypefun double sin (double @var{x})
149 @deftypefunx float sinf (float @var{x})
150 @deftypefunx {long double} sinl (long double @var{x})
151 These functions return the sine of @var{x}, where @var{x} is given in
152 radians.  The return value is in the range @code{-1} to @code{1}.
153 @end deftypefun
155 @comment math.h
156 @comment ISO
157 @deftypefun double cos (double @var{x})
158 @deftypefunx float cosf (float @var{x})
159 @deftypefunx {long double} cosl (long double @var{x})
160 These functions return the cosine of @var{x}, where @var{x} is given in
161 radians.  The return value is in the range @code{-1} to @code{1}.
162 @end deftypefun
164 @comment math.h
165 @comment ISO
166 @deftypefun double tan (double @var{x})
167 @deftypefunx float tanf (float @var{x})
168 @deftypefunx {long double} tanl (long double @var{x})
169 These functions return the tangent of @var{x}, where @var{x} is given in
172 The following @code{errno} error conditions are defined for this function:
174 @table @code
175 @item ERANGE
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} sets @code{errno} to @code{ERANGE} and returns
179 either positive or negative @code{HUGE_VAL}.
180 @end table
181 @end deftypefun
183 In many applications where @code{sin} and @code{cos} are used, the value
184 for the same argument of both of these functions is used at the same
185 time.  Since the algorithm to compute these values is very similar for
186 both functions there is an additional function which computes both values
187 at the same time.
189 @comment math.h
190 @comment GNU
191 @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
192 @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
193 @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
194 These functions return the sine of @var{x} in @code{*@var{sinx}} and the
195 cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
196 radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
197 the range of @code{-1} to @code{1}.
198 @end deftypefun
200 @cindex complex trigonometric functions
202 The trigonometric functions are in mathematics not only defined on real
203 numbers.  They can be extended to complex numbers and the @w{ISO C 9X}
204 standard introduces these variants in the standard math library.
206 @comment complex.h
207 @comment ISO
208 @deftypefun {complex double} csin (complex double @var{z})
209 @deftypefunx {complex float} csinf (complex float @var{z})
210 @deftypefunx {complex long double} csinl (complex long double @var{z})
211 These functions return the complex sine of the complex value in @var{z}.
212 The mathematical definition of the complex sine is
214 @ifinfo
215 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
216 @end ifinfo
217 @iftex
218 @tex
219 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
220 @end tex
221 @end iftex
222 @end deftypefun
224 @comment complex.h
225 @comment ISO
226 @deftypefun {complex double} ccos (complex double @var{z})
227 @deftypefunx {complex float} ccosf (complex float @var{z})
228 @deftypefunx {complex long double} ccosl (complex long double @var{z})
229 These functions return the complex cosine of the complex value in @var{z}.
230 The mathematical definition of the complex cosine is
232 @ifinfo
233 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
234 @end ifinfo
235 @iftex
236 @tex
237 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
238 @end tex
239 @end iftex
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 the complex value in @var{z}.
248 The mathematical definition of the complex tangent is
250 @ifinfo
251 @math{tan (z) = 1/i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
252 @end ifinfo
253 @iftex
254 @tex
255 $$\tan(z) = {1\over i} {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
256 @end tex
257 @end iftex
258 @end deftypefun
261 @node Inverse Trig Functions
262 @section Inverse Trigonometric Functions
263 @cindex inverse trigonometric functions
265 These are the usual arc sine, arc cosine and arc tangent functions,
266 which are the inverses of the sine, cosine and tangent functions,
267 respectively.
269 @comment math.h
270 @comment ISO
271 @deftypefun double asin (double @var{x})
272 @deftypefunx float asinf (float @var{x})
273 @deftypefunx {long double} asinl (long double @var{x})
274 These functions compute the arc sine of @var{x}---that is, the value whose
275 sine is @var{x}.  The value is in units of radians.  Mathematically,
276 there are infinitely many such values; the one actually returned is the
277 one between @code{-pi/2} and @code{pi/2} (inclusive).
279 @code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
280 out of range.  The arc sine function is defined mathematically only
281 over the domain @code{-1} to @code{1}.
282 @end deftypefun
284 @comment math.h
285 @comment ISO
286 @deftypefun double acos (double @var{x})
287 @deftypefunx float acosf (float @var{x})
288 @deftypefunx {long double} acosl (long double @var{x})
289 These functions compute the arc cosine of @var{x}---that is, the value
290 whose cosine is @var{x}.  The value is in units of radians.
291 Mathematically, there are infinitely many such values; the one actually
292 returned is the one between @code{0} and @code{pi} (inclusive).
294 @code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
295 out of range.  The arc cosine function is defined mathematically only
296 over the domain @code{-1} to @code{1}.
297 @end deftypefun
300 @comment math.h
301 @comment ISO
302 @deftypefun double atan (double @var{x})
303 @deftypefunx float atanf (float @var{x})
304 @deftypefunx {long double} atanl (long double @var{x})
305 These functions compute the arc tangent of @var{x}---that is, the value
306 whose tangent is @var{x}.  The value is in units of radians.
307 Mathematically, there are infinitely many such values; the one actually
308 returned is the one between @code{-pi/2} and @code{pi/2}
309 (inclusive).
310 @end deftypefun
312 @comment math.h
313 @comment ISO
314 @deftypefun double atan2 (double @var{y}, double @var{x})
315 @deftypefunx float atan2f (float @var{y}, float @var{x})
316 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
317 This is the two argument arc tangent function.  It is similar to computing
318 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
319 are used to determine the quadrant of the result, and @var{x} is
320 permitted to be zero.  The return value is given in radians and is in
321 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 The function @code{atan2} sets @code{errno} to @code{EDOM} if both
331 @var{x} and @var{y} are zero; the return value is not defined in this
332 case.
333 @end deftypefun
335 @cindex inverse complex trigonometric functions
337 The inverse trigonometric functions also exist is separate versions
338 which are usable with complex numbers.
340 @comment complex.h
341 @comment ISO
342 @deftypefun {complex double} casin (complex double @var{z})
343 @deftypefunx {complex float} casinf (complex float @var{z})
344 @deftypefunx {complex long double} casinl (complex long double @var{z})
345 These functions compute the complex arc sine of @var{z}---that is, the
346 value whose sine is @var{z}.  The value is in units of radians.
348 Unlike the real version of the arc sine function @code{casin} has no
349 limitation on the argument @var{z}.
350 @end deftypefun
352 @comment complex.h
353 @comment ISO
354 @deftypefun {complex double} cacos (complex double @var{z})
355 @deftypefunx {complex float} cacosf (complex float @var{z})
356 @deftypefunx {complex long double} cacosl (complex long double @var{z})
357 These functions compute the complex arc cosine of @var{z}---that is, the
358 value whose cosine is @var{z}.  The value is in units of radians.
360 Unlike the real version of the arc cosine function @code{cacos} has no
361 limitation on the argument @var{z}.
362 @end deftypefun
365 @comment complex.h
366 @comment ISO
367 @deftypefun {complex double} catan (complex double @var{z})
368 @deftypefunx {complex float} catanf (complex float @var{z})
369 @deftypefunx {complex long double} catanl (complex long double @var{z})
370 These functions compute the complex arc tangent of @var{z}---that is,
371 the value whose tangent is @var{z}.  The value is in units of radians.
372 @end deftypefun
375 @node Exponents and Logarithms
376 @section Exponentiation and Logarithms
377 @cindex exponentiation functions
378 @cindex power functions
379 @cindex logarithm functions
381 @comment math.h
382 @comment ISO
383 @deftypefun double exp (double @var{x})
384 @deftypefunx float expf (float @var{x})
385 @deftypefunx {long double} expl (long double @var{x})
386 These functions return the value of @code{e} (the base of natural
387 logarithms) raised to power @var{x}.
389 The function fails, and sets @code{errno} to @code{ERANGE}, if the
390 magnitude of the result is too large to be representable.
391 @end deftypefun
393 @comment math.h
394 @comment ISO
395 @deftypefun double exp10 (double @var{x})
396 @deftypefunx float exp10f (float @var{x})
397 @deftypefunx {long double} exp10l (long double @var{x})
398 These functions return the value of @code{10} raised to the power @var{x}.
399 Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
401 The function fails, and sets @code{errno} to @code{ERANGE}, if the
402 magnitude of the result is too large to be representable.
403 @end deftypefun
405 @comment math.h
406 @comment ISO
407 @deftypefun double exp2 (double @var{x})
408 @deftypefunx float exp2f (float @var{x})
409 @deftypefunx {long double} exp2l (long double @var{x})
410 These functions return the value of @code{2} raised to the power @var{x}.
411 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
413 The function fails, and sets @code{errno} to @code{ERANGE}, if the
414 magnitude of the result is too large to be representable.
415 @end deftypefun
418 @comment math.h
419 @comment ISO
420 @deftypefun double log (double @var{x})
421 @deftypefunx float logf (floatdouble @var{x})
422 @deftypefunx {long double} logl (long double @var{x})
423 These functions return the natural logarithm of @var{x}.  @code{exp (log
424 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
425 C.
427 The following @code{errno} error conditions are defined for this function:
429 @table @code
430 @item EDOM
431 The argument @var{x} is negative.  The log function is defined
432 mathematically to return a real result only on positive arguments.
434 @item ERANGE
435 The argument is zero.  The log of zero is not defined.
436 @end table
437 @end deftypefun
439 @comment math.h
440 @comment ISO
441 @deftypefun double log10 (double @var{x})
442 @deftypefunx float log10f (float @var{x})
443 @deftypefunx {long double} log10l (long double @var{x})
444 These functions return the base-10 logarithm of @var{x}.  Except for the
445 different base, it is similar to the @code{log} function.  In fact,
446 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
447 @end deftypefun
449 @comment math.h
450 @comment ISO
451 @deftypefun double log2 (double @var{x})
452 @deftypefunx float log2f (float @var{x})
453 @deftypefunx {long double} log2l (long double @var{x})
454 These functions return the base-2 logarithm of @var{x}.  Except for the
455 different base, it is similar to the @code{log} function.  In fact,
456 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
457 @end deftypefun
459 @comment math.h
460 @comment ISO
461 @deftypefun double pow (double @var{base}, double @var{power})
462 @deftypefunx float powf (float @var{base}, float @var{power})
463 @deftypefunx {long double} powl (long double @var{base}, long double @var{power})
464 These are general exponentiation functions, returning @var{base} raised
465 to @var{power}.
467 @need 250
468 The following @code{errno} error conditions are defined for this function:
470 @table @code
471 @item EDOM
472 The argument @var{base} is negative and @var{power} is not an integral
473 value.  Mathematically, the result would be a complex number in this case.
475 @item ERANGE
476 An underflow or overflow condition was detected in the result.
477 @end table
478 @end deftypefun
480 @cindex square root function
481 @comment math.h
482 @comment ISO
483 @deftypefun double sqrt (double @var{x})
484 @deftypefunx float sqrtf (float @var{x})
485 @deftypefunx {long double} sqrtl (long double @var{x})
486 These functions return the nonnegative square root of @var{x}.
488 The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
489 @var{x} is negative.  Mathematically, the square root would be a complex
490 number.
491 @c (@pxref{csqrt})
492 @end deftypefun
494 @cindex cube root function
495 @comment math.h
496 @comment BSD
497 @deftypefun double cbrt (double @var{x})
498 @deftypefunx float cbrtf (float @var{x})
499 @deftypefunx {long double} cbrtl (long double @var{x})
500 These functions return the cube root of @var{x}.  They cannot
501 fail; every representable real value has a representable real cube root.
502 @end deftypefun
504 @comment math.h
505 @comment ISO
506 @deftypefun double hypot (double @var{x}, double @var{y})
507 @deftypefunx float hypotf (float @var{x}, float @var{y})
508 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
509 These functions return @code{sqrt (@var{x}*@var{x} +
510 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
511 triangle with sides of length @var{x} and @var{y}, or the distance
512 of the point (@var{x}, @var{y}) from the origin.)  Using this function
513 instead of the direct formula is highly appreciated since the error is
514 much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
515 @end deftypefun
517 @comment math.h
518 @comment ISO
519 @deftypefun double expm1 (double @var{x})
520 @deftypefunx float expm1f (float @var{x})
521 @deftypefunx {long double} expm1l (long double @var{x})
522 These functions return a value equivalent to @code{exp (@var{x}) - 1}.
523 It is computed in a way that is accurate even if the value of @var{x} is
524 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
525 to subtraction of two numbers that are nearly equal.
526 @end deftypefun
528 @comment math.h
529 @comment ISO
530 @deftypefun double log1p (double @var{x})
531 @deftypefunx float log1pf (float @var{x})
532 @deftypefunx {long double} log1pl (long double @var{x})
533 This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
534 It is computed in a way that is accurate even if the value of @var{x} is
535 near zero.
536 @end deftypefun
538 @cindex complex exponentiation functions
539 @cindex complex logarithm functions
541 @w{ISO C 9X} defines variants of some of the exponentiation and
542 logarithm functions.  As for the other functions handlung complex
543 numbers these functions are perhaps better optimized and provide better
544 error checking than a direct use of the formulas of the mathematical
545 definition.
547 @comment complex.h
548 @comment ISO
549 @deftypefun {complex double} cexp (complex double @var{z})
550 @deftypefunx {complex float} cexpf (complex float @var{z})
551 @deftypefunx {complex long double} cexpl (complex long double @var{z})
552 These functions return the value of @code{e} (the base of natural
553 logarithms) raised to power of the complex value @var{z}.
555 @noindent
556 Mathematically this corresponds to the value
558 @ifinfo
559 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
560 @end ifinfo
561 @iftex
562 @tex
563 $$\exp(z) = e^z = e^{{\rm Re} z} (\cos ({\rm Im} z) + i \sin ({\rm Im} z))$$
564 @end tex
565 @end iftex
566 @end deftypefun
568 @comment complex.h
569 @comment ISO
570 @deftypefun {complex double} clog (complex double @var{z})
571 @deftypefunx {complex float} clogf (complex float @var{z})
572 @deftypefunx {complex long double} clogl (complex long double @var{z})
573 These functions return the natural logarithm of the complex value
574 @var{z}.  Unlike the real value version @code{log} and its variants,
575 @code{clog} has no limit for the range of its argument @var{z}.
577 @noindent
578 Mathematically this corresponds to the value
580 @ifinfo
581 @math{log (z) = log (cabs (z)) + I * carg (z)}
582 @end ifinfo
583 @iftex
584 @tex
585 $$\log(z) = \log(|z|) + i \arg(z)$$
586 @end tex
587 @end iftex
588 @end deftypefun
590 @comment complex.h
591 @comment ISO
592 @deftypefun {complex double} csqrt (complex double @var{z})
593 @deftypefunx {complex float} csqrtf (complex float @var{z})
594 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
595 These functions return the complex root of the argument @var{z}.  Unlike
596 the @code{sqrt} function these functions do not have any restriction on
597 the value of the argument.
598 @end deftypefun
600 @comment complex.h
601 @comment ISO
602 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
603 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
604 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
605 These functions return the complex value @var{BASE} raised to the power of
606 @var{power}.  This is computed as
608 @ifinfo
609 @math{cpow (x, y) = cexp (y * clog (x))}
610 @end ifinfo
611 @iftex
612 @tex
613 $${\rm cpow}(x, y) = e^{y \log(x)}$$
614 @end tex
615 @end iftex
616 @end deftypefun
619 @node Hyperbolic Functions
620 @section Hyperbolic Functions
621 @cindex hyperbolic functions
623 The functions in this section are related to the exponential functions;
624 see @ref{Exponents and Logarithms}.
626 @comment math.h
627 @comment ISO
628 @deftypefun double sinh (double @var{x})
629 @deftypefunx float sinhf (float @var{x})
630 @deftypefunx {long double} sinhl (long double @var{x})
631 These functions return the hyperbolic sine of @var{x}, defined
632 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  The
633 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
634 @var{x} is too large; that is, if overflow occurs.
635 @end deftypefun
637 @comment math.h
638 @comment ISO
639 @deftypefun double cosh (double @var{x})
640 @deftypefunx float coshf (float @var{x})
641 @deftypefunx {long double} coshl (long double @var{x})
642 These function return the hyperbolic cosine of @var{x},
643 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
644 The function fails, and sets @code{errno} to @code{ERANGE}, if the value
645 of @var{x} is too large; that is, if overflow occurs.
646 @end deftypefun
648 @comment math.h
649 @comment ISO
650 @deftypefun double tanh (double @var{x})
651 @deftypefunx float tanhf (float @var{x})
652 @deftypefunx {long double} tanhl (long double @var{x})
653 These functions return the hyperbolic tangent of @var{x}, whose
654 mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
655 @end deftypefun
657 @cindex hyperbolic functions
659 There are counterparts for these hyperbolic functions which work with
660 complex valued arguments.  They should always be used instead of the
661 obvious mathematical formula since the implementations in the math
662 library are optimized for accuracy and speed.
664 @comment complex.h
665 @comment ISO
666 @deftypefun {complex double} csinh (complex double @var{z})
667 @deftypefunx {complex float} csinhf (complex float @var{z})
668 @deftypefunx {complex long double} csinhl (complex long double @var{z})
669 These functions return the complex hyperbolic sine of @var{z}, defined
670 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.  The
671 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
672 result is too large.
673 @end deftypefun
675 @comment complex.h
676 @comment ISO
677 @deftypefun {complex double} ccosh (complex double @var{z})
678 @deftypefunx {complex float} ccoshf (complex float @var{z})
679 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
680 These functions return the complex hyperbolic cosine of @var{z}, defined
681 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.  The
682 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
683 result is too large.
684 @end deftypefun
686 @comment complex.h
687 @comment ISO
688 @deftypefun {complex double} ctanh (complex double @var{z})
689 @deftypefunx {complex float} ctanhf (complex float @var{z})
690 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
691 These functions return the complex hyperbolic tangent of @var{z}, whose
692 mathematical definition is @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
693 @end deftypefun
696 @cindex inverse hyperbolic functions
698 @comment math.h
699 @comment ISO
700 @deftypefun double asinh (double @var{x})
701 @deftypefunx float asinhf (float @var{x})
702 @deftypefunx {long double} asinhl (long double @var{x})
703 These functions return the inverse hyperbolic sine of @var{x}---the
704 value whose hyperbolic sine is @var{x}.
705 @end deftypefun
707 @comment math.h
708 @comment ISO
709 @deftypefun double acosh (double @var{x})
710 @deftypefunx float acoshf (float @var{x})
711 @deftypefunx {long double} acoshl (long double @var{x})
712 These functions return the inverse hyperbolic cosine of @var{x}---the
713 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
714 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
715 @end deftypefun
717 @comment math.h
718 @comment ISO
719 @deftypefun double atanh (double @var{x})
720 @deftypefunx float atanhf (float @var{x})
721 @deftypefunx {long double} atanhl (long double @var{x})
722 These functions return the inverse hyperbolic tangent of @var{x}---the
723 value whose hyperbolic tangent is @var{x}.  If the absolute value of
724 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
725 @code{HUGE_VAL}.
726 @end deftypefun
728 @cindex inverse complex hyperbolic functions
730 @comment complex.h
731 @comment ISO
732 @deftypefun {complex double} casinh (complex double @var{z})
733 @deftypefunx {complex float} casinhf (complex float @var{z})
734 @deftypefunx {complex long double} casinhl (complex long double @var{z})
735 These functions return the inverse complex hyperbolic sine of
736 @var{z}---the value whose complex hyperbolic sine is @var{z}.
737 @end deftypefun
739 @comment complex.h
740 @comment ISO
741 @deftypefun {complex double} cacosh (complex double @var{z})
742 @deftypefunx {complex float} cacoshf (complex float @var{z})
743 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
744 These functions return the inverse complex hyperbolic cosine of
745 @var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
746 the real valued function @code{acosh} there is not limit for the range
747 of the argument.
748 @end deftypefun
750 @comment complex.h
751 @comment ISO
752 @deftypefun {complex double} catanh (complex double @var{z})
753 @deftypefunx {complex float} catanhf (complex float @var{z})
754 @deftypefunx {complex long double} catanhl (complex long double @var{z})
755 These functions return the inverse complex hyperbolic tangent of
756 @var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
757 the real valued function @code{atanh} there is not limit for the range
758 of the argument.
759 @end deftypefun
761 @node Pseudo-Random Numbers
762 @section Pseudo-Random Numbers
763 @cindex random numbers
764 @cindex pseudo-random numbers
765 @cindex seed (for random numbers)
767 This section describes the GNU facilities for generating a series of
768 pseudo-random numbers.  The numbers generated are not truly random;
769 typically, they form a sequence that repeats periodically, with a
770 period so large that you can ignore it for ordinary purposes.  The
771 random number generator works by remembering at all times a @dfn{seed}
772 value which it uses to compute the next random number and also to
773 compute a new seed.
775 Although the generated numbers look unpredictable within one run of a
776 program, the sequence of numbers is @emph{exactly the same} from one run
777 to the next.  This is because the initial seed is always the same.  This
778 is convenient when you are debugging a program, but it is unhelpful if
779 you want the program to behave unpredictably.  If you want truly random
780 numbers, not just pseudo-random, specify a seed based on the current
781 time.
783 You can get repeatable sequences of numbers on a particular machine type
784 by specifying the same initial seed value for the random number
785 generator.  There is no standard meaning for a particular seed value;
786 the same seed, used in different C libraries or on different CPU types,
787 will give you different random numbers.
789 The GNU library supports the standard @w{ISO C} random number functions
790 plus another set derived from BSD.  We recommend you use the standard
791 ones, @code{rand} and @code{srand}.
794 * ISO Random::       @code{rand} and friends.
795 * BSD Random::       @code{random} and friends.
796 * SVID Random::      @code{drand48} and friends.
799 @node ISO Random
800 @subsection ISO C Random Number Functions
802 This section describes the random number functions that are part of
803 the @w{ISO C} standard.
805 To use these facilities, you should include the header file
806 @file{stdlib.h} in your program.
807 @pindex stdlib.h
809 @comment stdlib.h
810 @comment ISO
811 @deftypevr Macro int RAND_MAX
812 The value of this macro is an integer constant expression that
813 represents the maximum possible value returned by the @code{rand}
814 function.  In the GNU library, it is @code{037777777}, which is the
815 largest signed integer representable in 32 bits.  In other libraries, it
816 may be as low as @code{32767}.
817 @end deftypevr
819 @comment stdlib.h
820 @comment ISO
821 @deftypefun int rand ()
822 The @code{rand} function returns the next pseudo-random number in the
823 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
824 @end deftypefun
826 @comment stdlib.h
827 @comment ISO
828 @deftypefun void srand (unsigned int @var{seed})
829 This function establishes @var{seed} as the seed for a new series of
830 pseudo-random numbers.  If you call @code{rand} before a seed has been
831 established with @code{srand}, it uses the value @code{1} as a default
832 seed.
834 To produce truly random numbers (not just pseudo-random), do @code{srand
835 (time (0))}.
836 @end deftypefun
838 @node BSD Random
839 @subsection BSD Random Number Functions
841 This section describes a set of random number generation functions that
842 are derived from BSD.  There is no advantage to using these functions
843 with the GNU C library; we support them for BSD compatibility only.
845 The prototypes for these functions are in @file{stdlib.h}.
846 @pindex stdlib.h
848 @comment stdlib.h
849 @comment BSD
850 @deftypefun {long int} random ()
851 This function returns the next pseudo-random number in the sequence.
852 The range of values returned is from @code{0} to @code{RAND_MAX}.
853 @end deftypefun
855 @comment stdlib.h
856 @comment BSD
857 @deftypefun void srandom (unsigned int @var{seed})
858 The @code{srandom} function sets the seed for the current random number
859 state based on the integer @var{seed}.  If you supply a @var{seed} value
860 of @code{1}, this will cause @code{random} to reproduce the default set
861 of random numbers.
863 To produce truly random numbers (not just pseudo-random), do
864 @code{srandom (time (0))}.
865 @end deftypefun
867 @comment stdlib.h
868 @comment BSD
869 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
870 The @code{initstate} function is used to initialize the random number
871 generator state.  The argument @var{state} is an array of @var{size}
872 bytes, used to hold the state information.  The size must be at least 8
873 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
874 the @var{state} array, the better.
876 The return value is the previous value of the state information array.
877 You can use this value later as an argument to @code{setstate} to
878 restore that state.
879 @end deftypefun
881 @comment stdlib.h
882 @comment BSD
883 @deftypefun {void *} setstate (void *@var{state})
884 The @code{setstate} function restores the random number state
885 information @var{state}.  The argument must have been the result of
886 a previous call to @var{initstate} or @var{setstate}.
888 The return value is the previous value of the state information array.
889 You can use thise value later as an argument to @code{setstate} to
890 restore that state.
891 @end deftypefun
894 @node SVID Random
895 @subsection SVID Random Number Function
897 The C library on SVID systems contains yet another kind of random number
898 generator functions.  They use a state of 48 bits of data.  The user can
899 choose among a collection of functions which all return the random bits
900 in different forms.
902 Generally there are two kinds of functions: those which use a state of
903 the random number generator which is shared among several functions and
904 by all threads of the process.  The second group of functions require
905 the user to handle the state.
907 All functions have in common that they use the same congruential
908 formula with the same constants.  The formula is
910 @smallexample
911 Y = (a * X + c) mod m
912 @end smallexample
914 @noindent
915 where @var{X} is the state of the generator at the beginning and
916 @var{Y} the state at the end.  @code{a} and @code{c} are constants
917 determining the way the generator work.  By default they are
919 @smallexample
920 a = 0x5DEECE66D = 25214903917
921 c = 0xb = 11
922 @end smallexample
924 @noindent
925 but they can also be changed by the user.  @code{m} is of course 2^48
926 since the state consists of a 48 bit array.
929 @comment stdlib.h
930 @comment SVID
931 @deftypefun double drand48 ()
932 This function returns a @code{double} value in the range of @code{0.0}
933 to @code{1.0} (exclusive).  The random bits are determined by the global
934 state of the random number generator in the C library.
936 Since the @code{double} type according to @w{IEEE 754} has a 52 bit
937 mantissa this means 4 bits are not initialized by the random number
938 generator.  These are (of course) chosen to be the least significant
939 bits and they are initialized to @code{0}.
940 @end deftypefun
942 @comment stdlib.h
943 @comment SVID
944 @deftypefun double erand48 (unsigned short int @var{xsubi})
945 This function returns a @code{double} value in the range of @code{0.0}
946 to @code{1.0} (exclusive), similar to @code{drand48}.  The argument is
947 an array describing the state of the random number generator.
949 This function can be called subsequently since it updates the array to
950 guarantee random numbers.  The array should have been initialized before
951 using to get reproducible results.
952 @end deftypefun
954 @comment stdlib.h
955 @comment SVID
956 @deftypefun {long int} lrand48 ()
957 The @code{lrand48} functions return an integer value in the range of
958 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
959 int} type can take more than 32 bits no higher numbers are returned.
960 The random bits are determined by the global state of the random number
961 generator in the C library.
962 @end deftypefun
964 @comment stdlib.h
965 @comment SVID
966 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi})
967 This function is similar to the @code{lrand48} function in that it
968 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
969 the state of the random number generator used to produce the random bits
970 is determined by the array provided as the parameter to the function.
972 The numbers in the array are afterwards updated so that subsequent calls
973 to this function yield to different results (as it is expected by a
974 random number generator).  The array should have been initialized before
975 the first call to get reproducible results.
976 @end deftypefun
978 @comment stdlib.h
979 @comment SVID
980 @deftypefun {long int} mrand48 ()
981 The @code{mrand48} function is similar to @code{lrand48}.  The only
982 difference is that the numbers returned are in the range @code{-2^31} to
983 @code{2^31} (exclusive).
984 @end deftypefun
986 @comment stdlib.h
987 @comment SVID
988 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi})
989 The @code{jrand48} function is similar to @code{nrand48}.  The only
990 difference is that the numbers returned are in the range @code{-2^31} to
991 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
992 requirements are necessary.
993 @end deftypefun
995 The internal state of the random number generator can be initialized in
996 several ways.  The functions differ in the completeness of the
997 information provided.
999 @comment stdlib.h
1000 @comment SVID
1001 @deftypefun void srand48 (long int @var{seedval}))
1002 The @code{srand48} function sets the most significant 32 bits of the
1003 state internal state of the random number generator to the least
1004 significant 32 bits of the @var{seedval} parameter.  The lower 16 bts
1005 are initilialized to the value @code{0x330E}.  Even if the @code{long
1006 int} type contains more the 32 bits only the lower 32 bits are used.
1008 Due to this limitation the initialization of the state using this
1009 function of not very useful.  But it makes it easy to use a constrcut
1010 like @code{srand48 (time (0))}.
1012 A side-effect of this function is that the values @code{a} and @code{c}
1013 from the internal state, which are used in the congruential formula,
1014 are reset to the default values given above.  This is of importance once
1015 the user called the @code{lcong48} function (see below).
1016 @end deftypefun
1018 @comment stdlib.h
1019 @comment SVID
1020 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v})
1021 The @code{seed48} function initializes all 48 bits of the state of the
1022 internal random number generator from the content of the parameter
1023 @var{seed16v}.  Here the lower 16 bits of the first element of
1024 @var{see16v} initialize the least significant 16 bits of the internal
1025 state, the lower 16 bits of @code{@var{seed16v}} initialize the mid-order
1026 16 bits of the state and the 16 lower bits of @code{@var{seed16v}}
1027 initialize the most significant 16 bits of the state.
1029 Unlike @code{srand48} this function lets the user initialize all 48 bits
1030 of the state.
1032 The value returned by @code{seed48} is a pointer to an array containing
1033 the values of the internal state before the change.  This might be
1034 useful to restart the random number generator at a certain state.
1035 Otherwise, the value can simply be ignored.
1037 As for @code{srand48}, the values @code{a} and @code{c} from the
1038 congruential formula are reset to the default values.
1039 @end deftypefun
1041 There is one more function to initialize the random number generator
1042 which allows to specify even more information by allowing to change the
1043 parameters in the congruential formula.
1045 @comment stdlib.h
1046 @comment SVID
1047 @deftypefun void lcong48 (unsigned short int @var{param})
1048 The @code{lcong48} function allows the user to change the complete state
1049 of the random number generator.  Unlike @code{srand48} and
1050 @code{seed48}, this function also changes the constants in the
1051 congruential formula.
1053 From the seven elements in the array @var{param} the least significant
1054 16 bits of the entries @code{@var{param}} to @code{@var{param}}
1055 determine the the initial state, the least 16 bits of
1056 @code{@var{param}} to @code{@var{param}} determine the 48 bit
1057 constant @code{a} and @code{@var{param}} determines the 16 bit value
1058 @code{c}.
1059 @end deftypefun
1061 All the above functions have in common that they use the global
1062 parameters for the congruential formula.  In multi-threaded programs it
1063 might sometimes be useful to have different parameters in different
1064 threads.  For this reason all the above functions have a counterpart
1065 which works on a description of the random number generator in the
1066 user-supplied buffer instead of the global state.
1068 Please note that it is no problem if several threads use the global
1069 state if all threads use the functions which take a pointer to an array
1070 containing the state.  The random numbers are computed following the
1071 same loop but if the state in the array is different all threads will
1072 get an individuual random number generator.
1074 The user supplied buffer must be of type @code{struct drand48_data}.
1075 This type should be regarded as opaque and no member should be used
1076 directly.
1078 @comment stdlib.h
1079 @comment GNU
1080 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1081 This function is equivalent to the @code{drand48} function with the
1082 difference it does not modify the global random number generator
1083 parameters but instead the parameters is the buffer supplied by the
1084 buffer through the pointer @var{buffer}.  The random number is return in
1085 the variable pointed to by @var{result}.
1087 The return value of the function indicate whether the call succeeded.
1088 If the value is less than @code{0} an error occurred and @var{errno} is
1089 set to indicate the problem.
1091 This function is a GNU extension and should not be used in portable
1092 programs.
1093 @end deftypefun
1095 @comment stdlib.h
1096 @comment GNU
1097 @deftypefun int erand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, double *@var{result})
1098 The @code{erand48_r} function works like the @code{erand48} and it takes
1099 an argument @var{buffer} which describes the random number generator.
1100 The state of the random number genertor is taken from the @code{xsubi}
1101 array, the parameters for the congruential formula from the global
1102 random number generator data.  The random number is return in the
1103 variable pointed to by @var{result}.
1105 The return value is non-negative is the call succeeded.
1107 This function is a GNU extension and should not be used in portable
1108 programs.
1109 @end deftypefun
1111 @comment stdlib.h
1112 @comment GNU
1113 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1114 This function is similar to @code{lrand48} and it takes a pointer to a
1115 buffer describing the state of the random number generator as a
1116 parameter just like @code{drand48}.
1118 If the return value of the function is non-negative the variable pointed
1119 to by @var{result} contains the result.  Otherwise an error occurred.
1121 This function is a GNU extension and should not be used in portable
1122 programs.
1123 @end deftypefun
1125 @comment stdlib.h
1126 @comment GNU
1127 @deftypefun int nrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
1128 The @code{nrand48_r} function works like @code{nrand48} in that it
1129 produces a random number in range @code{0} to @code{2^31}.  But instead
1130 of using the global parameters for the congruential formula it uses the
1131 information from the buffer pointed to by @var{buffer}.  The state is
1132 described by the values in @var{xsubi}.
1134 If the return value is non-negative the variable pointed to by
1135 @var{result} contains the result.
1137 This function is a GNU extension and should not be used in portable
1138 programs.
1139 @end deftypefun
1141 @comment stdlib.h
1142 @comment GNU
1143 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1144 This function is similar to @code{mrand48} but as the other reentrant
1145 function it uses the random number generator described by the value in
1146 the buffer pointed to by @var{buffer}.
1148 If the return value is non-negative the variable pointed to by
1149 @var{result} contains the result.
1151 This function is a GNU extension and should not be used in portable
1152 programs.
1153 @end deftypefun
1155 @comment stdlib.h
1156 @comment GNU
1157 @deftypefun int jrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
1158 The @code{jrand48_r} function is similar to @code{jrand48}.  But as the
1159 other reentrant functions of this function family it uses the
1160 congruential formula parameters from the buffer pointed to by
1161 @var{buffer}.
1163 If the return value is non-negative the variable pointed to by
1164 @var{result} contains the result.
1166 This function is a GNU extension and should not be used in portable
1167 programs.
1168 @end deftypefun
1170 Before any of the above functions should be used the buffer of type
1171 @code{struct drand48_data} should initialized.  The easiest way is to
1172 fill the whole buffer with null bytes, e.g., using
1174 @smallexample
1175 memset (buffer, '\0', sizeof (struct drand48_data));
1176 @end smallexample
1178 @noindent
1179 Using any of the reetrant functions of this family now will
1180 automatically initialize the random number generator to the default
1181 values for the state and the parameters of the congruential formula.
1183 The other possibility is too use any of the functions which explicitely
1184 initialize the buffer.  Though it might be obvious how to initialize the
1185 buffer from the data given as parameter from the function it is highly
1186 recommended to use these functions since the result might not always be
1187 what you expect.
1189 @comment stdlib.h
1190 @comment GNU
1191 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1192 The description of the random number generator represented by the
1193 information in @var{buffer} is initialized similar to what the function
1194 @code{srand48} does.  The state is initialized from the paramter
1195 @var{seedval} and the paameters for the congruential formula are
1196 initialized to the default values.
1198 If the return value is non-negative the function call succeeded.
1200 This function is a GNU extension and should not be used in portable
1201 programs.
1202 @end deftypefun
1204 @comment stdlib.h
1205 @comment GNU
1206 @deftypefun int seed48_r (unsigned short int @var{seed16v}, struct drand48_data *@var{buffer})
1207 This function is similar to @code{srand48_r} but like @code{seed48} it
1208 initializes all 48 bits of the state from the parameter @var{seed16v}.
1210 If the return value is non-negative the function call succeeded.  It
1211 does not return a pointer to the previous state of the random number
1212 generator like the @code{seed48} function does.  if the user wants to
1213 preserve the state for a later rerun s/he can copy the whole buffer
1214 pointed to by @var{buffer}.
1216 This function is a GNU extension and should not be used in portable
1217 programs.
1218 @end deftypefun
1220 @comment stdlib.h
1221 @comment GNU
1222 @deftypefun int lcong48_r (unsigned short int @var{param}, struct drand48_data *@var{buffer})
1223 This function initializes all aspects of the random number generator
1224 described in @var{buffer} by the data in @var{param}.  Here it is
1225 especially true the function does more than just copying the contents of
1226 @var{param} of @var{buffer}.  Some more actions are required and
1227 therefore it is important to use this function and not initialized the
1228 random number generator directly.
1230 If the return value is non-negative the function call succeeded.
1232 This function is a GNU extension and should not be used in portable
1233 programs.
1234 @end deftypefun