Change definition of mul macro.
[kopensolaris-gnu/glibc.git] / manual / math.texi
1 @c We need some definitions here.
2 @ifclear cdot
3 @ifhtml
4 @set cdot ·
5 @macro mul
6 ·
7 @end macro
8 @end ifhtml
9 @iftex
10 @set cdot ·
11 @macro mul
12 @cdot
13 @end macro
14 @end iftex
15 @ifclear cdot
16 @set cdot x
17 @macro mul
18 x
19 @end macro
20 @end ifclear
21 @end ifclear
22 @iftex
23 @set infty @infty
24 @end iftex
25 @ifclear infty
26 @set infty oo
27 @end ifclear
28 @macro infinity
29 @value{infty}
30 @end macro
31
32 @node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
33 @chapter Mathematics
34
35 This chapter contains information about functions for performing
36 mathematical computations, such as trigonometric functions.  Most of
37 these functions have prototypes declared in the header file
38 @file{math.h}.
39 @pindex math.h
40
41 For all functions which take a single floating-point argument and for
42 several other functions as well there are three different functions
43 available for the type @code{double}, @code{float}, and @code{long
44 double}.  The @code{double} versions of the functions are mostly defined
45 even in the @w{ISO C 89} standard.  The @code{float} and @code{long
46 double} variants are introduced in the numeric extensions for the C
47 language which are part of the @w{ISO C 9X} standard.
48
49 Which of the three versions of the function should be used depends on
50 the situation.  For most functions and implementation it is true that
51 speed and precision do not go together.  I.e., the @code{float} versions
52 are normally faster than the @code{double} and @code{long double}
53 versions.  On the other hand the @code{long double} version has the
54 highest precision.  One should always think about the actual needs and
55 in case of double using @code{double} is a good compromise.
56
57
58 @menu
59 * Domain and Range Errors::      Detecting overflow conditions and the like.
60 * Exceptions in Math Functions:: Signalling exception in math functions.
61 * Mathematical Constants::       Precise numeric values for often used
62                                   constant.
63 * FP Comparison Functions::      Special functions to compare floating-point
64                                   numbers.
65 * FP Function Optimizations::    Fast code or small code.
66 * Trig Functions::               Sine, cosine, and tangent.
67 * Inverse Trig Functions::       Arc sine, arc cosine, and arc tangent.
68 * Exponents and Logarithms::     Also includes square root.
69 * Hyperbolic Functions::         Hyperbolic sine and friends.
70 * Pseudo-Random Numbers::        Functions for generating pseudo-random
71                                   numbers.
72 @end menu
73
74 @node Domain and Range Errors
75 @section Domain and Range Errors
76
77 @cindex domain error
78 Many of the functions listed in this chapter are defined mathematically
79 over a domain that is only a subset of real numbers.  For example, the
80 @code{acos} function is defined over the domain between @code{@minus{}1} and
81 @code{1}.  If you pass an argument to one of these functions that is
82 outside the domain over which it is defined, the function sets
83 @code{errno} to @code{EDOM} to indicate a @dfn{domain error}.  On
84 machines that support @w{IEEE 754} floating point, functions reporting
85 error @code{EDOM} also return a NaN.
86
87 Some of these functions are defined mathematically to result in a
88 complex value over parts of their domains.  The most familiar example of
89 this is taking the square root of a negative number.  The functions in
90 this chapter take only real arguments and return only real values;
91 therefore, if the value ought to be nonreal, this is treated as a domain
92 error.
93
94 @cindex range error
95 A related problem is that the mathematical result of a function may not
96 be representable as a floating point number.  If magnitude of the
97 correct result is too large to be represented, the function sets
98 @code{errno} to @code{ERANGE} to indicate a @dfn{range error}, and
99 returns a particular very large value (named by the macro
100 @code{HUGE_VAL}) or its negation (@code{@minus{}HUGE_VAL}).
101
102 If the magnitude of the result is too small, a value of zero is returned
103 instead.  In this case, @code{errno} might or might not be
104 set to @code{ERANGE}.
105
106 The only completely reliable way to check for domain and range errors is
107 to set @code{errno} to @code{0} before you call the mathematical function
108 and test @code{errno} afterward.  As a consequence of this use of
109 @code{errno}, use of the mathematical functions is not reentrant if you
110 check for errors.
111
112 @c ### This is no longer true.  --drepper
113 @c None of the mathematical functions ever generates signals as a result of
114 @c domain or range errors.  In particular, this means that you won't see
115 @c @code{SIGFPE} signals generated within these functions.  (@xref{Signal
116 @c Handling}, for more information about signals.)
117
118 @comment math.h
119 @comment ISO
120 @deftypevr Macro double HUGE_VAL
121 An expression representing a particular very large number.  On machines
122 that use @w{IEEE 754}/@w{IEEE 854} floating point format, the value is
123 ``infinity''.  On other machines, it's typically the largest positive
124 number that can be represented.
125
126 The value of this macro is used as the return value from various
127 mathematical @code{double} returning functions in overflow situations.
128 @end deftypevr
129
130 @comment math.h
131 @comment ISO
132 @deftypevr Macro float HUGE_VALF
133 This macro is similar to the @code{HUGE_VAL} macro except that it is
134 used by functions returning @code{float} values.
135
136 This macro is introduced in @w{ISO C 9X}.
137 @end deftypevr
138
139 @comment math.h
140 @comment ISO
141 @deftypevr Macro {long double} HUGE_VALL
142 This macro is similar to the @code{HUGE_VAL} macro except that it is
143 used by functions returning @code{long double} values.  The value is
144 only different from @code{HUGE_VAL} if the architecture really supports
145 @code{long double} values.
146
147 This macro is introduced in @w{ISO C 9X}.
148 @end deftypevr
149
150
151 A special case is the @code{ilogb} function @pxref{Exponents and
152 Logarithms}.  Since the return value is an integer value, one cannot
153 compare with @code{HUGE_VAL} etc.  Therefore two further values are
154 defined.
155
156 @comment math.h
157 @comment ISO
158 @deftypevr Macro int FP_ILOGB0
159 This value is returned by @code{ilogb} if the argument is @code{0}.  The
160 numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
161
162 This macro is introduced in @w{ISO C 9X}.
163 @end deftypevr
164
165 @comment math.h
166 @comment ISO
167 @deftypevr Macro int FP_ILOGBNAN
168 This value is returned by @code{ilogb} if the argument is @code{NaN}.  The
169 numeric value is either @code{INT_MIN} or @code{INT_MAX}.
170
171 This macro is introduced in @w{ISO C 9X}.
172 @end deftypevr
173
174
175 For more information about floating-point representations and limits,
176 see @ref{Floating Point Parameters}.  In particular, the macro
177 @code{DBL_MAX} might be more appropriate than @code{HUGE_VAL} for many
178 uses other than testing for an error in a mathematical function.
179
180
181 @node Exceptions in Math Functions
182 @section Exceptions in Math Functions
183 @cindex exception
184 @cindex signal
185
186 Due to the restrictions in the size of the floating-point number
187 representation or the limitation of the input range of certain functions
188 some of the mathematical operations and functions have to signal
189 exceptional situations.  The @w{IEEE 754} standard specifies which
190 exceptions have to be supported and how they can be handled.
191
192 @w{IEEE 754} specifies two actions for floating-point exception: taking
193 a trap or continuing without doing so.  If the trap is taken a
194 (possibly) user defined trap handler is called and this function can
195 correct the argument or react somehow else on the call.  If the trap
196 handler returns, its return value is taken as the result of the
197 operation.
198
199 If no trap handler is called each of the known exceptions has a default
200 action.  This consists of setting a corresponding bit in the
201 floating-point status word to indicate which kind of exception was
202 raised and to return a default value, which depends on the exception
203 (see the table below).
204
205 @noindent
206 The exceptions defined in @w{IEEE 754} are:
207
208 @table @samp
209 @item Invalid Operation
210 This exception is raised if the given operands are invalid for the
211 operation to be performed.  Examples are
212 (see @w{IEEE 754}, @w{section 7}):
213 @enumerate
214 @item
215 Any operation on a signalling NaN.
216 @item
217 Addition or subtraction; magnitude subtraction of infinities such as
218 @math{(+@infinity{}) + (-@infinity{})}.
219 @item
220 Multiplication:
221 @math{0 @mul{} @infinity{}}.
222
223 @item
224 Division: @math{0/0} or @math{@infinity{}/@infinity{}}.
225
226 @item
227 Remainder: @math{x} REM @math{y}, where @math{y} is zero or @math{x} is
228 infinite.
229 @item
230 Square root if the operand is less then zero.
231 @item
232 Conversion of an internal floating-point number to an integer or to a
233 decimal string when overflow, infinity, or NaN precludes a faithful
234 representation in that format and this cannot otherwise be signaled.
235 @item
236 Conversion of an unrecognizable input string.
237 @item
238 Comparison via predicates involving @math{<} or @math{>}, without
239 @code{?}, when the operands are @dfn{unordered}.  (@math{?>} means the
240 unordered greater relation, @xref{FP Comparison Functions}).
241 @end enumerate
242
243 If the exception does not cause a trap handler to be called the result
244 of the operation is taken as a quiet NaN.
245
246 @item Division by Zero
247 This exception is raised if the divisor is zero and the dividend is a
248 finite nonzero number.  If no trap occurs the result is either
249 @math{+@infinity{}} or @math{-@infinity{}}, depending on the
250 signs of the operands.
251
252 @item Overflow
253 This exception is signalled whenever the result cannot be represented
254 as a finite value in the precision format of the destination.  If no trap
255 occurs the result depends on the sign of the intermediate result and the
256 current rounding mode (@w{IEEE 754}, @w{section 7.3}):
257 @enumerate
258 @item
259 Round to nearest carries all overflows to @math{@infinity{}}
260 with the sign of the intermediate result.
261 @item
262 Round toward @math{0} carries all overflows to the precision's largest
263 finite number with the sign of the intermediate result.
264 @item
265 Round toward @math{-@infinity{}} carries positive overflows to the
266 precision's largest finite number and carries negative overflows to
267 @math{-@infinity{}}.
268
269 @item
270 Round toward @math{@infinity{}} carries negative overflows to the
271 precision's most negative finite number and carries positive overflows
272 to @math{@infinity{}}.
273 @end enumerate
274
275 @item Underflow
276 The underflow exception is created when an intermediate result is too
277 small for the operation or if the operations result rounded to the
278 destination precision causes a loss of accuracy by approximating the
279 result by denormalized numbers.
280
281 When no trap is installed for the underflow exception, underflow shall
282 be signaled (via the underflow flag) only when both tininess and loss of
283 accuracy have been detected.  If no trap handler is installed the
284 operation continues with an inprecise small value or zero if the
285 destination precision cannot hold the small exact result.
286
287 @item Inexact
288 This exception is signalled if the rounded result is not exact (such as
289 computing the square root of two) or the result overflows without an
290 overflow trap.
291 @end table
292
293 To control whether an exception causes a trap to occur all @w{IEEE 754}
294 conformant floating-point implementations (either hardware or software)
295 have a control word.  By setting specific bits for each exception in
296 this control word the programmer can decide whether a trap is wanted or
297 not.
298
299 @w{ISO C 9X} introduces a set of function which can be used to control
300 exceptions.  There are functions to manipulate the control word, to
301 query the status word or to save and restore the whole state of the
302 floating-point unit.  There are also functions to control the rounding
303 mode used.
304
305 @menu
306 * Status bit operations::       Manipulate the FP status word.
307 * FPU environment::             Controlling the status of the FPU.
308 * Rounding Modes::              Controlling the rounding mode.
309 @end menu
310
311 @node Status bit operations
312 @subsection Controlling the FPU status word
313
314 To control the five types of exceptions defined in @w{IEEE 754} some
315 functions are defined which abstract the interface to the FPU.  The
316 actual implementation can be very different, depending on the underlying
317 hardware or software.
318
319 To address the single exception the @file{fenv.h} headers defines a
320 number of macros:
321
322 @vtable @code
323 @comment fenv.h
324 @comment ISO
325 @item FE_INEXACT
326 Represents the inexact exception iff the FPU supports this exception.
327 @comment fenv.h
328 @comment ISO
329 @item FE_DIVBYZERO
330 Represents the divide by zero exception iff the FPU supports this exception.
331 @comment fenv.h
332 @comment ISO
333 @item FE_UNDERFLOW
334 Represents the underflow exception iff the FPU supports this exception.
335 @comment fenv.h
336 @comment ISO
337 @item FE_OVERFLOW
338 Represents the overflow exception iff the FPU supports this exception.
339 @comment fenv.h
340 @comment ISO
341 @item FE_INVALID
342 Represents the invalid exception iff the FPU supports this exception.
343 @end vtable
344
345 The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros
346 which are supported by the FP implementation.
347
348 Each of the supported exception flags can either be set or unset.  The
349 @w{ISO C 9X} standard defines functions to set, unset and test the
350 status of the flags.
351
352 @comment fenv.h
353 @comment ISO
354 @deftypefun void feclearexcept (int @var{excepts})
355 This function clears all of the supported exception flags denoted by
356 @var{excepts} in the status word.
357 @end deftypefun
358
359 To safe the current status of the flags in the status word @file{fenv.h}
360 defines the type @code{fexcept_t} which can hold all the information.
361 The following function can be used to retrieve the current setting.
362
363 @comment fenv.h
364 @comment ISO
365 @deftypefun void fegetexceptflag (fexcept_t *@var{flagp}, int @var{excepts})
366 Store in the variable pointed to by @var{flagp} an
367 implementation-defined value representing the current setting of the
368 exception flags indicated by the parameter @var{excepts}.
369 @end deftypefun
370
371 @noindent
372 To restore the previously saved values one can use this function:
373
374 @comment fenv.h
375 @comment ISO
376 @deftypefun void fesetexceptflag (const fexcept_t *@var{flagp}, int @var{excepts})
377 Restore from the variable pointed to by @var{flagp} the setting of the
378 flags for the exceptions denoted by the value of the parameter
379 @var{excepts}.
380 @end deftypefun
381
382 The last function allows to query the current status of the flags.  The
383 flags can be set either explicitely (using @code{fesetexceptflag} or
384 @code{feclearexcept}) or by a floating-point operation which happened
385 before.  Since the flags are accumulative, the flags must be explicitely
386 reset using @code{feclearexcept} if one wants to test for a certain
387 exceptions raised by a specific piece of code.
388
389 @comment fenv.h
390 @comment ISO
391 @deftypefun int fetestexcept (int @var{excepts})
392 Test whether a subset of the flags indicated by the parameter
393 @var{except} is currently set.  If yes, a nonzero value is returned
394 which specifies which exceptions are set.  Otherwise the result is zero.
395 @end deftypefun
396
397 @noindent
398 Code which uses the @code{fetestexcept} function could look like this:
399
400 @smallexample
401 @{
402   double f;
403   int raised;
404   feclearexcept (FE_ALL_EXCEPT);
405   f = compute ();
406   raised = fetestexcept (FE_OVERFLOW | FE_INVALID);
407   if (raised & FE_OVERFLOW) @{ /* ... */ @}
408   if (raised & FE_INVALID) @{ /* ... */ @}
409   /* ... */
410 @}
411 @end smallexample
412
413 Please note that the return value of @code{fetestexcept} is @code{int}
414 but this does not mean that the @code{fexcept_t} type is generally
415 representable as an integer.  These are completely independent types.
416
417
418 @node FPU environment
419 @subsection Controlling the Floating-Point environment
420
421 It is sometimes necessary so save the complete status of the
422 floating-point unit for a certain time to perform some completely
423 different actions.  Beside the status of the exception flags, the
424 control word for the exceptions and the rounding mode can be saved.
425
426 The file @file{fenv.h} defines the type @code{fenv_t}.  The layout of a
427 variable of this type is implementation defined but the variable is able
428 to contain the complete status information.  To fill a variable of this
429 type one can use this function:
430
431 @comment fenv.h
432 @comment ISO
433 @deftypefun void fegetenv (fenv_t *@var{envp})
434 Store the current floating-point environment in the object pointed to by
435 @var{envp}.
436 @end deftypefun
437
438 @noindent
439 Another possibility which is useful in several situations is
440
441 @comment fenv.h
442 @comment ISO
443 @deftypefun int feholdexcept (fenv_t *@var{envp})
444 Store the current floating-point environment in the object pointed to by
445 @var{envp}.  Afterwards, all exception flags are cleared and if
446 available a mode is installed which continues on all exception and does
447 not cause a trap to occur.  In this case a nonzero value is returned.
448
449 If the floating-point implementation does not support such a non-stop
450 mode, the return value is zero.
451 @end deftypefun
452
453 The functions which allow a state of the floating-point unit to be
454 restored can take two kinds of arguments:
455
456 @itemize @bullet
457 @item
458 Pointed to objects which previously were initialized by a call to
459 @code{fegetenv} or @code{feholdexcept}.
460 @item
461 @vindex FE_DFL_ENV
462 The special macro @code{FE_DFL_ENV} which represents the floating-point
463 environment as it was available at program start.
464 @item
465 Implementation defined macros with names starting with @code{FE_}.
466
467 @vindex FE_NOMASK_ENV
468 If possible, the GNU C Library defines a macro @code{FE_NOMASK_ENV}
469 which represents an environment where no exception is masked and so each
470 raised exception causes a trap to occur.  Whether this macro is available can easily be tested using @code{#ifdef}.
471
472 Some platforms might define further predefined environments.
473 @end itemize
474
475 @noindent
476 To set any of the environments there are two functions defined.
477
478 @deftypefun void fesetenv (const fenv_t *@var{envp})
479 Establish the floating-point environment described in the object pointed
480 to by @var{envp}.  Even if one or more exceptions flags in the restored
481 environment are set no exception is raised.
482 @end deftypefun
483
484 In some situations the previous status of the exception flags must not
485 simply be discarded and so this function is useful:
486
487 @deftypefun void feupdateenv (const fenv_t *@var{envp})
488 The current status of the floating-point unit is preserved in some
489 automatic storage before the environment described by the object pointed
490 to by @var{envp} is installed.  Once this is finished all exceptions set
491 in the original environment which is saved in the automatic storage, is
492 raised.
493 @end deftypefun
494
495 This function can be used to execute a part of the program with an
496 environment which masks all exceptions and before switching back remove
497 unwanted exception and raise the remaining exceptions.
498
499
500 @node Rounding Modes
501 @subsection Rounding modes of the Floating-Point Unit
502
503 @w{IEEE 754} defines four different rounding modes.  If the rounding
504 mode is supported by the floating-point implementation the corresponding
505 of the following macros is defined:
506
507 @table @code
508 @comment fenv.h
509 @comment ISO
510 @vindex FE_TONEAREST
511 @item FE_TONEAREST
512 Round to nearest.  This is the default mode and should always be used
513 except when a different mode is explicitely required.  Only rounding to
514 nearest guarantees numeric stability of the computations.
515
516 @comment fenv.h
517 @comment ISO
518 @vindex FE_UPWARD
519 @item FE_UPWARD
520 Round toward @math{+@infinity{}}.
521
522 @comment fenv.h
523 @comment ISO
524 @vindex FE_DOWNWARD
525 @item FE_DOWNWARD
526 Round toward @math{-@infinity{}}.
527
528 @comment fenv.h
529 @comment ISO
530 @vindex FE_TOWARDZERO
531 @item FE_TOWARDZERO
532 Round toward zero.
533 @end table
534
535 At any time one of the above four rounding modes is selected.  To get
536 information about the currently selected mode one can use this function:
537
538 @comment fenv.h
539 @comment ISO
540 @deftypefun int fegetround (void)
541 Return the currently selected rounding mode, represented by one of the
542 values of the defined rounding mode macros.
543 @end deftypefun
544
545 @noindent
546 To set a specific rounding mode the next function can be used.
547
548 @comment fenv.h
549 @comment ISO
550 @deftypefun int fesetround (int @var{round})
551 Change the currently selected rounding mode to the mode described by the
552 parameter @var{round}.  If @var{round} does not correspond to one of the
553 supported rounding modes nothing is changed.
554
555 The function returns a nonzero value iff the requested rounding mode can
556 be established.  Otherwise zero is returned.
557 @end deftypefun
558
559 Changing the rounding mode might be necessary for various reasons.  But
560 changing the mode only to round a given number normally is no good idea.
561 The standard defines a set of functions which can be used to round an
562 argument according to some rules and for all of the rounding modes there
563 is a corresponding function.
564
565 If a large set of number has to be rounded it might be good to change
566 the rounding mode and to not use the function the library provides.  So
567 the perhaps necessary switching of the rounding mode in the library
568 function can be avoided.  But since not all rounding modes are
569 guaranteed to exist on any platform this possible implementation cannot
570 be portably used.  A default method has to be implemented as well.
571
572
573 @node Mathematical Constants
574 @section Predefined Mathematical Constants
575 @cindex constants
576 @cindex mathematical constants
577
578 The header @file{math.h} defines a series of mathematical constants if
579 @code{_BSD_SOURCE} or a more general feature select macro is defined
580 before including this file.  All values are defined as preprocessor
581 macros starting with @code{M_}.  The collection includes:
582
583 @vtable @code
584 @item M_E
585 The value is that of the base of the natural logarithm.
586 @item M_LOG2E
587 The value is computed as the logarithm to base @code{2} of @code{M_E}.
588 @item M_LOG10E
589 The value is computed as the logarithm to base @code{10} of @code{M_E}.
590 @item M_LN2
591 The value is computed as the natural logarithm of @code{2}.
592 @item M_LN10
593 The value is computed as the natural logarithm of @code{10}.
594 @item M_PI
595 The value is those of the number pi.
596 @item M_PI_2
597 The value is those of the number pi divided by two.
598 @item M_PI_4
599 The value is those of the number pi divided by four.
600 @item M_1_PI
601 The value is the reziprocal of the value of the number pi.
602 @item M_2_PI
603 The value is two times the reziprocal of the value of the number pi.
604 @item M_2_SQRTPI
605 The value is two times the reziprocal of the square root of the number pi.
606 @item M_SQRT2
607 The value is the square root of the value of the number pi.
608 @item M_SQRT1_2
609 The value is the reziprocal of the square root of the value of the number pi.
610 @end vtable
611
612 All values are defined as @code{long double} values unless the compiler
613 does not support this type or @code{__STDC__} is not defined (both is
614 unlikely).  Historically the numbers were @code{double} values and some
615 old code still relies on this so you might want to add explicit casts if
616 the extra precision of the @code{long double} value is not needed.  One
617 critical case are functions with a variable number of arguments, such as
618 @code{printf}.
619
620 @vindex PI
621 @emph{Note:} Some programs use a constant named @code{PI} which has the
622 same value as @code{M_PI}.  This probably derives from Stroustroup's
623 book about his C++ programming language where this value is used in
624 examples (and perhaps some AT&T headers contain this value).  But due to
625 possible name space problems (@code{PI} is a quite frequently used name)
626 this value is not added to @file{math.h}.  Every program should use
627 @code{M_PI} instead or add on the compiler command line
628 @code{-DPI=M_PI}.
629
630
631 @node FP Comparison Functions
632 @section Floating-Point Comparison Functions
633 @cindex unordered comparison
634
635 The @w{IEEE 754} standards defines a set of functions which allows to
636 compare even those numbers which normally would cause an exception to be
637 raised since they are unordered.  E.g., the expression
638
639 @smallexample
640 int v = a < 1.0;
641 @end smallexample
642
643 @noindent
644 would raise an exception if @var{a} would be a NaN.  Functions to
645 compare unordered numbers are part of the FORTRAN language for a long
646 time and the extensions in @w{ISO C 9X} finally introduce them as well
647 for the C programming language.
648
649 All of the operations are implemented as macros which allow their
650 arguments to be of either @code{float}, @code{double}, or @code{long
651 double} type.
652
653 @comment math.h
654 @comment ISO
655 @deftypefn {Macro} int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
656 This macro determines whether the argument @var{x} is greater than
657 @var{y}.  This is equivalent to @code{(@var{x}) > (@var{y})} but no
658 exception is raised if @var{x} or @var{y} are unordered.
659 @end deftypefn
660
661 @comment math.h
662 @comment ISO
663 @deftypefn {Macro} int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
664 This macro determines whether the argument @var{x} is greater than or
665 equal to @var{y}.  This is equivalent to @code{(@var{x}) >= (@var{y})} but no
666 exception is raised if @var{x} or @var{y} are unordered.
667 @end deftypefn
668
669 @comment math.h
670 @comment ISO
671 @deftypefn {Macro} int isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
672 This macro determines whether the argument @var{x} is less than @var{y}.
673 This is equivalent @code{(@var{x}) < (@var{y})} but no exception is raised if
674 @var{x} or @var{y} are unordered.
675 @end deftypefn
676
677 @comment math.h
678 @comment ISO
679 @deftypefn {Macro} int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
680 This macro determines whether the argument @var{x} is less than or equal
681 to @var{y}.  This is equivalent to @code{(@var{x}) <= (@var{y})} but no
682 exception is raised if @var{x} or @var{y} are unordered.
683 @end deftypefn
684
685 @comment math.h
686 @comment ISO
687 @deftypefn {Macro} int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
688 This macro determines whether the argument @var{x} is less or greater
689 than @var{y}.  This is equivalent to @code{(@var{x}) < (@var{y}) ||
690 (@var{x}) > (@var{y})} (except that @var{x} and @var{y} are only
691 evaluated once) but no exception is raised if @var{x} or @var{y} are
692 unordered.
693 @end deftypefn
694
695 @comment math.h
696 @comment ISO
697 @deftypefn {Macro} int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
698 This macro determines whether its arguments are unordered.
699 @end deftypefn
700
701 All the macros are defined in a way to ensure that both arguments are
702 evaluated exactly once and so they can be used exactly like the builtin
703 operators.
704
705 On several platform these macros are mapped to efficient instructions
706 the processor understands.  But on machines missing these functions, the
707 macros above might be rather slow.  So it is best to use the builtin
708 operators unless it is necessary to use unordered comparisons.
709
710 @strong{Note:} There are no macros @code{isequal} or @code{isunequal}.
711 These macros are not necessary since the @w{IEEE 754} standard requires
712 that the comparison for equality and unequality do @emph{not} throw an
713 exception if one of the arguments is an unordered value.
714
715
716 @node FP Function Optimizations
717 @section Is Fast Code or Small Code preferred?
718 @cindex Optimization
719
720 If an application uses many floating point function it is often the case
721 that the costs for the function calls itselfs are not neglectable.
722 Modern processor implementation often can execute the operation itself
723 very fast but the call means a disturbance of the control flow.
724
725 For this reason the GNU C Library provides optimizations for many of the
726 frequently used math functions.  When the GNU CC is used and the user
727 activates the optimizer several new inline functions and macros get
728 defined.  These new functions and macros have the same names as the
729 library function and so get used instead of the later.  In case of
730 inline functions the compiler will decide whether it is reasonable to
731 use the inline function and this decision is usually correct.
732
733 For the generated code this means that no calls to the library functions
734 are necessary.  This increases the speed significantly.  But the
735 drawback is that the code size increases and this increase is not always
736 neglectable.
737
738 In cases where the inline functions and macros are not wanted the symbol
739 @code{__NO_MATH_INLINES} should be defined before any system header is
740 included.  This will make sure only library functions are used.  Of
741 course it can be determined for each single file in the project whether
742 giving this option is preferred or not.
743
744
745 @node Trig Functions
746 @section Trigonometric Functions
747 @cindex trigonometric functions
748
749 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
750 The arguments to all of these functions are in units of radians; recall
751 that pi radians equals 180 degrees.
752
753 @cindex pi (trigonometric constant)
754 The math library does define a symbolic constant for pi in @file{math.h}
755 (@pxref{Mathematical Constants}) when BSD compliance is required
756 (@pxref{Feature Test Macros}).  In case it is not possible to use this
757 predefined macro one easily can define it:
758
759 @smallexample
760 #define M_PI 3.14159265358979323846264338327
761 @end smallexample
762
763 @noindent
764 You can also compute the value of pi with the expression @code{acos
765 (-1.0)}.
766
767
768 @comment math.h
769 @comment ISO
770 @deftypefun double sin (double @var{x})
771 @deftypefunx float sinf (float @var{x})
772 @deftypefunx {long double} sinl (long double @var{x})
773 These functions return the sine of @var{x}, where @var{x} is given in
774 radians.  The return value is in the range @code{-1} to @code{1}.
775 @end deftypefun
776
777 @comment math.h
778 @comment ISO
779 @deftypefun double cos (double @var{x})
780 @deftypefunx float cosf (float @var{x})
781 @deftypefunx {long double} cosl (long double @var{x})
782 These functions return the cosine of @var{x}, where @var{x} is given in
783 radians.  The return value is in the range @code{-1} to @code{1}.
784 @end deftypefun
785
786 @comment math.h
787 @comment ISO
788 @deftypefun double tan (double @var{x})
789 @deftypefunx float tanf (float @var{x})
790 @deftypefunx {long double} tanl (long double @var{x})
791 These functions return the tangent of @var{x}, where @var{x} is given in
792 radians.
793
794 The following @code{errno} error conditions are defined for this function:
795
796 @table @code
797 @item ERANGE
798 Mathematically, the tangent function has singularities at odd multiples
799 of pi/2.  If the argument @var{x} is too close to one of these
800 singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
801 either positive or negative @code{HUGE_VAL}.
802 @end table
803 @end deftypefun
804
805 In many applications where @code{sin} and @code{cos} are used, the value
806 for the same argument of both of these functions is used at the same
807 time.  Since the algorithm to compute these values is very similar for
808 both functions there is an additional function which computes both values
809 at the same time.
810
811 @comment math.h
812 @comment GNU
813 @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
814 @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
815 @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
816 These functions return the sine of @var{x} in @code{*@var{sinx}} and the
817 cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
818 radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
819 the range of @code{-1} to @code{1}.
820
821 This function is a GNU extension.  It should be used whenever both sine
822 and cosine are needed but in portable applications there should be a
823 fallback method for systems without this function.
824 @end deftypefun
825
826 @cindex complex trigonometric functions
827
828 The trigonometric functions are in mathematics not only defined on real
829 numbers.  They can be extended to complex numbers and the @w{ISO C 9X}
830 standard introduces these variants in the standard math library.
831
832 @comment complex.h
833 @comment ISO
834 @deftypefun {complex double} csin (complex double @var{z})
835 @deftypefunx {complex float} csinf (complex float @var{z})
836 @deftypefunx {complex long double} csinl (complex long double @var{z})
837 These functions return the complex sine of the complex value in @var{z}.
838 The mathematical definition of the complex sine is
839
840 @ifinfo
841 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
842 @end ifinfo
843 @iftex
844 @tex
845 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
846 @end tex
847 @end iftex
848 @end deftypefun
849
850 @comment complex.h
851 @comment ISO
852 @deftypefun {complex double} ccos (complex double @var{z})
853 @deftypefunx {complex float} ccosf (complex float @var{z})
854 @deftypefunx {complex long double} ccosl (complex long double @var{z})
855 These functions return the complex cosine of the complex value in @var{z}.
856 The mathematical definition of the complex cosine is
857
858 @ifinfo
859 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
860 @end ifinfo
861 @iftex
862 @tex
863 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
864 @end tex
865 @end iftex
866 @end deftypefun
867
868 @comment complex.h
869 @comment ISO
870 @deftypefun {complex double} ctan (complex double @var{z})
871 @deftypefunx {complex float} ctanf (complex float @var{z})
872 @deftypefunx {complex long double} ctanl (complex long double @var{z})
873 These functions return the complex tangent of the complex value in @var{z}.
874 The mathematical definition of the complex tangent is
875
876 @ifinfo
877 @math{tan (z) = 1/i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
878 @end ifinfo
879 @iftex
880 @tex
881 $$\tan(z) = {1\over i} {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
882 @end tex
883 @end iftex
884 @end deftypefun
885
886
887 @node Inverse Trig Functions
888 @section Inverse Trigonometric Functions
889 @cindex inverse trigonometric functions
890
891 These are the usual arc sine, arc cosine and arc tangent functions,
892 which are the inverses of the sine, cosine and tangent functions,
893 respectively.
894
895 @comment math.h
896 @comment ISO
897 @deftypefun double asin (double @var{x})
898 @deftypefunx float asinf (float @var{x})
899 @deftypefunx {long double} asinl (long double @var{x})
900 These functions compute the arc sine of @var{x}---that is, the value whose
901 sine is @var{x}.  The value is in units of radians.  Mathematically,
902 there are infinitely many such values; the one actually returned is the
903 one between @code{-pi/2} and @code{pi/2} (inclusive).
904
905 @code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
906 out of range.  The arc sine function is defined mathematically only
907 over the domain @code{-1} to @code{1}.
908 @end deftypefun
909
910 @comment math.h
911 @comment ISO
912 @deftypefun double acos (double @var{x})
913 @deftypefunx float acosf (float @var{x})
914 @deftypefunx {long double} acosl (long double @var{x})
915 These functions compute the arc cosine of @var{x}---that is, the value
916 whose cosine is @var{x}.  The value is in units of radians.
917 Mathematically, there are infinitely many such values; the one actually
918 returned is the one between @code{0} and @code{pi} (inclusive).
919
920 @code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
921 out of range.  The arc cosine function is defined mathematically only
922 over the domain @code{-1} to @code{1}.
923 @end deftypefun
924
925
926 @comment math.h
927 @comment ISO
928 @deftypefun double atan (double @var{x})
929 @deftypefunx float atanf (float @var{x})
930 @deftypefunx {long double} atanl (long double @var{x})
931 These functions compute the arc tangent of @var{x}---that is, the value
932 whose tangent is @var{x}.  The value is in units of radians.
933 Mathematically, there are infinitely many such values; the one actually
934 returned is the one between @code{-pi/2} and @code{pi/2}
935 (inclusive).
936 @end deftypefun
937
938 @comment math.h
939 @comment ISO
940 @deftypefun double atan2 (double @var{y}, double @var{x})
941 @deftypefunx float atan2f (float @var{y}, float @var{x})
942 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
943 This is the two argument arc tangent function.  It is similar to computing
944 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
945 are used to determine the quadrant of the result, and @var{x} is
946 permitted to be zero.  The return value is given in radians and is in
947 the range @code{-pi} to @code{pi}, inclusive.
948
949 If @var{x} and @var{y} are coordinates of a point in the plane,
950 @code{atan2} returns the signed angle between the line from the origin
951 to that point and the x-axis.  Thus, @code{atan2} is useful for
952 converting Cartesian coordinates to polar coordinates.  (To compute the
953 radial coordinate, use @code{hypot}; see @ref{Exponents and
954 Logarithms}.)
955
956 The function @code{atan2} sets @code{errno} to @code{EDOM} if both
957 @var{x} and @var{y} are zero; the return value is not defined in this
958 case.
959 @end deftypefun
960
961 @cindex inverse complex trigonometric functions
962
963 The inverse trigonometric functions also exist is separate versions
964 which are usable with complex numbers.
965
966 @comment complex.h
967 @comment ISO
968 @deftypefun {complex double} casin (complex double @var{z})
969 @deftypefunx {complex float} casinf (complex float @var{z})
970 @deftypefunx {complex long double} casinl (complex long double @var{z})
971 These functions compute the complex arc sine of @var{z}---that is, the
972 value whose sine is @var{z}.  The value is in units of radians.
973
974 Unlike the real version of the arc sine function @code{casin} has no
975 limitation on the argument @var{z}.
976 @end deftypefun
977
978 @comment complex.h
979 @comment ISO
980 @deftypefun {complex double} cacos (complex double @var{z})
981 @deftypefunx {complex float} cacosf (complex float @var{z})
982 @deftypefunx {complex long double} cacosl (complex long double @var{z})
983 These functions compute the complex arc cosine of @var{z}---that is, the
984 value whose cosine is @var{z}.  The value is in units of radians.
985
986 Unlike the real version of the arc cosine function @code{cacos} has no
987 limitation on the argument @var{z}.
988 @end deftypefun
989
990
991 @comment complex.h
992 @comment ISO
993 @deftypefun {complex double} catan (complex double @var{z})
994 @deftypefunx {complex float} catanf (complex float @var{z})
995 @deftypefunx {complex long double} catanl (complex long double @var{z})
996 These functions compute the complex arc tangent of @var{z}---that is,
997 the value whose tangent is @var{z}.  The value is in units of radians.
998 @end deftypefun
999
1000
1001 @node Exponents and Logarithms
1002 @section Exponentiation and Logarithms
1003 @cindex exponentiation functions
1004 @cindex power functions
1005 @cindex logarithm functions
1006
1007 @comment math.h
1008 @comment ISO
1009 @deftypefun double exp (double @var{x})
1010 @deftypefunx float expf (float @var{x})
1011 @deftypefunx {long double} expl (long double @var{x})
1012 These functions return the value of @code{e} (the base of natural
1013 logarithms) raised to power @var{x}.
1014
1015 The function fails, and sets @code{errno} to @code{ERANGE}, if the
1016 magnitude of the result is too large to be representable.
1017 @end deftypefun
1018
1019 @comment math.h
1020 @comment ISO
1021 @deftypefun double exp10 (double @var{x})
1022 @deftypefunx float exp10f (float @var{x})
1023 @deftypefunx {long double} exp10l (long double @var{x})
1024 These functions return the value of @code{10} raised to the power @var{x}.
1025 Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
1026
1027 The function fails, and sets @code{errno} to @code{ERANGE}, if the
1028 magnitude of the result is too large to be representable.
1029 @end deftypefun
1030
1031 @comment math.h
1032 @comment ISO
1033 @deftypefun double exp2 (double @var{x})
1034 @deftypefunx float exp2f (float @var{x})
1035 @deftypefunx {long double} exp2l (long double @var{x})
1036 These functions return the value of @code{2} raised to the power @var{x}.
1037 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
1038
1039 The function fails, and sets @code{errno} to @code{ERANGE}, if the
1040 magnitude of the result is too large to be representable.
1041 @end deftypefun
1042
1043
1044 @comment math.h
1045 @comment ISO
1046 @deftypefun double log (double @var{x})
1047 @deftypefunx float logf (float @var{x})
1048 @deftypefunx {long double} logl (long double @var{x})
1049 These functions return the natural logarithm of @var{x}.  @code{exp (log
1050 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
1051 C.
1052
1053 The following @code{errno} error conditions are defined for this function:
1054
1055 @table @code
1056 @item EDOM
1057 The argument @var{x} is negative.  The log function is defined
1058 mathematically to return a real result only on positive arguments.
1059
1060 @item ERANGE
1061 The argument is zero.  The log of zero is not defined.
1062 @end table
1063 @end deftypefun
1064
1065 @comment math.h
1066 @comment ISO
1067 @deftypefun double log10 (double @var{x})
1068 @deftypefunx float log10f (float @var{x})
1069 @deftypefunx {long double} log10l (long double @var{x})
1070 These functions return the base-10 logarithm of @var{x}.  Except for the
1071 different base, it is similar to the @code{log} function.  In fact,
1072 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
1073 @end deftypefun
1074
1075 @comment math.h
1076 @comment ISO
1077 @deftypefun double log2 (double @var{x})
1078 @deftypefunx float log2f (float @var{x})
1079 @deftypefunx {long double} log2l (long double @var{x})
1080 These functions return the base-2 logarithm of @var{x}.  Except for the
1081 different base, it is similar to the @code{log} function.  In fact,
1082 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
1083 @end deftypefun
1084
1085 @comment math.h
1086 @comment ISO
1087 @deftypefun double logb (double @var{x})
1088 @deftypefunx float logbf (float @var{x})
1089 @deftypefunx {long double} logbl (long double @var{x})
1090 These functions extract the exponent of @var{x} and return it as a
1091 signed integer value.  If @var{x} is zero, a range error may occur.
1092
1093 A special case are subnormal numbers (if supported by the floating-point
1094 format).  The exponent returned is not the actual value from @var{x}.
1095 Instead the number is first normalized as if the range of the exponent
1096 field is large enough.
1097 @end deftypefun
1098
1099 @comment math.h
1100 @comment ISO
1101 @deftypefun int ilogb (double @var{x})
1102 @deftypefunx int ilogbf (float @var{x})
1103 @deftypefunx int ilogbl (long double @var{x})
1104 These functions are equivalent to the corresponding @code{logb}
1105 functions except that the values are returned as signed integer values.
1106 Since integer values cannot represent infinity and NaN, there are some
1107 special symbols defined to help detect these situations.
1108
1109 @vindex FP_ILOGB0
1110 @vindex FP_ILOGBNAN
1111 @code{ilogb} returns @code{FP_ILOGB0} if @var{x} is @code{0} and it
1112 returns @code{FP_ILOGBNAN} if @var{x} is @code{NaN}.  These values are
1113 system specific and no fixed value is assigned.  More concrete, these
1114 values might even have the same value.  So a piece of code handling the
1115 result of @code{ilogb} could look like this:
1116
1117 @smallexample
1118 i = ilogb (f);
1119 if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
1120   @{
1121     if (isnan (f))
1122       @{
1123         /* @r{Handle NaN.}  */
1124       @}
1125     else if (f  == 0.0)
1126       @{
1127         /* @r{Handle 0.0.}  */
1128       @}
1129     else
1130       @{
1131         /* @r{Some other value with large exponent,}
1132            @r{perhaps +Inf.}  */
1133       @}
1134   @}
1135 @end smallexample
1136
1137 @end deftypefun
1138
1139 @comment math.h
1140 @comment ISO
1141 @deftypefun double pow (double @var{base}, double @var{power})
1142 @deftypefunx float powf (float @var{base}, float @var{power})
1143 @deftypefunx {long double} powl (long double @var{base}, long double @var{power})
1144 These are general exponentiation functions, returning @var{base} raised
1145 to @var{power}.
1146
1147 @need 250
1148 The following @code{errno} error conditions are defined for this function:
1149
1150 @table @code
1151 @item EDOM
1152 The argument @var{base} is negative and @var{power} is not an integral
1153 value.  Mathematically, the result would be a complex number in this case.
1154
1155 @item ERANGE
1156 An underflow or overflow condition was detected in the result.
1157 @end table
1158 @end deftypefun
1159
1160 @cindex square root function
1161 @comment math.h
1162 @comment ISO
1163 @deftypefun double sqrt (double @var{x})
1164 @deftypefunx float sqrtf (float @var{x})
1165 @deftypefunx {long double} sqrtl (long double @var{x})
1166 These functions return the nonnegative square root of @var{x}.
1167
1168 The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
1169 @var{x} is negative.  Mathematically, the square root would be a complex
1170 number.
1171 @c (@pxref{csqrt})
1172 @end deftypefun
1173
1174 @cindex cube root function
1175 @comment math.h
1176 @comment BSD
1177 @deftypefun double cbrt (double @var{x})
1178 @deftypefunx float cbrtf (float @var{x})
1179 @deftypefunx {long double} cbrtl (long double @var{x})
1180 These functions return the cube root of @var{x}.  They cannot
1181 fail; every representable real value has a representable real cube root.
1182 @end deftypefun
1183
1184 @comment math.h
1185 @comment ISO
1186 @deftypefun double hypot (double @var{x}, double @var{y})
1187 @deftypefunx float hypotf (float @var{x}, float @var{y})
1188 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
1189 These functions return @code{sqrt (@var{x}*@var{x} +
1190 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
1191 triangle with sides of length @var{x} and @var{y}, or the distance
1192 of the point (@var{x}, @var{y}) from the origin.)  Using this function
1193 instead of the direct formula is highly appreciated since the error is
1194 much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
1195 @end deftypefun
1196
1197 @comment math.h
1198 @comment ISO
1199 @deftypefun double expm1 (double @var{x})
1200 @deftypefunx float expm1f (float @var{x})
1201 @deftypefunx {long double} expm1l (long double @var{x})
1202 These functions return a value equivalent to @code{exp (@var{x}) - 1}.
1203 It is computed in a way that is accurate even if the value of @var{x} is
1204 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
1205 to subtraction of two numbers that are nearly equal.
1206 @end deftypefun
1207
1208 @comment math.h
1209 @comment ISO
1210 @deftypefun double log1p (double @var{x})
1211 @deftypefunx float log1pf (float @var{x})
1212 @deftypefunx {long double} log1pl (long double @var{x})
1213 This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
1214 It is computed in a way that is accurate even if the value of @var{x} is
1215 near zero.
1216 @end deftypefun
1217
1218 @cindex complex exponentiation functions
1219 @cindex complex logarithm functions
1220
1221 @w{ISO C 9X} defines variants of some of the exponentiation and
1222 logarithm functions.  As for the other functions handling complex
1223 numbers these functions are perhaps better optimized and provide better
1224 error checking than a direct use of the formulas of the mathematical
1225 definition.
1226
1227 @comment complex.h
1228 @comment ISO
1229 @deftypefun {complex double} cexp (complex double @var{z})
1230 @deftypefunx {complex float} cexpf (complex float @var{z})
1231 @deftypefunx {complex long double} cexpl (complex long double @var{z})
1232 These functions return the value of @code{e} (the base of natural
1233 logarithms) raised to power of the complex value @var{z}.
1234
1235 @noindent
1236 Mathematically this corresponds to the value
1237
1238 @ifinfo
1239 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
1240 @end ifinfo
1241 @iftex
1242 @tex
1243 $$\exp(z) = e^z = e^{{\rm Re} z} (\cos ({\rm Im} z) + i \sin ({\rm Im} z))$$
1244 @end tex
1245 @end iftex
1246 @end deftypefun
1247
1248 @comment complex.h
1249 @comment ISO
1250 @deftypefun {complex double} clog (complex double @var{z})
1251 @deftypefunx {complex float} clogf (complex float @var{z})
1252 @deftypefunx {complex long double} clogl (complex long double @var{z})
1253 These functions return the natural logarithm of the complex value
1254 @var{z}.  Unlike the real value version @code{log} and its variants,
1255 @code{clog} has no limit for the range of its argument @var{z}.
1256
1257 @noindent
1258 Mathematically this corresponds to the value
1259
1260 @ifinfo
1261 @math{log (z) = log (cabs (z)) + I * carg (z)}
1262 @end ifinfo
1263 @iftex
1264 @tex
1265 $$\log(z) = \log(|z|) + i \arg(z)$$
1266 @end tex
1267 @end iftex
1268 @end deftypefun
1269
1270
1271 @comment complex.h
1272 @comment GNU
1273 @deftypefun {complex double} clog10 (complex double @var{z})
1274 @deftypefunx {complex float} clog10f (complex float @var{z})
1275 @deftypefunx {complex long double} clog10l (complex long double @var{z})
1276 These functions return the base 10 logarithm of the complex value
1277 @var{z}.  Unlike the real value version @code{log} and its variants,
1278 @code{clog} has no limit for the range of its argument @var{z}.
1279
1280 @noindent
1281 Mathematically this corresponds to the value
1282
1283 @ifinfo
1284 @math{log (z) = log10 (cabs (z)) + I * carg (z)}
1285 @end ifinfo
1286 @iftex
1287 @tex
1288 $$\log_{10}(z) = \log_{10}(|z|) + i \arg(z)$$
1289 @end tex
1290 @end iftex
1291
1292 This function is a GNU extension.
1293 @end deftypefun
1294
1295 @comment complex.h
1296 @comment ISO
1297 @deftypefun {complex double} csqrt (complex double @var{z})
1298 @deftypefunx {complex float} csqrtf (complex float @var{z})
1299 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
1300 These functions return the complex root of the argument @var{z}.  Unlike
1301 the @code{sqrt} function these functions do not have any restriction on
1302 the value of the argument.
1303 @end deftypefun
1304
1305 @comment complex.h
1306 @comment ISO
1307 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
1308 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
1309 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
1310 These functions return the complex value @var{base} raised to the power of
1311 @var{power}.  This is computed as
1312
1313 @ifinfo
1314 @math{cpow (x, y) = cexp (y * clog (x))}
1315 @end ifinfo
1316 @iftex
1317 @tex
1318 $${\rm cpow}(x, y) = e^{y \log(x)}$$
1319 @end tex
1320 @end iftex
1321 @end deftypefun
1322
1323
1324 @node Hyperbolic Functions
1325 @section Hyperbolic Functions
1326 @cindex hyperbolic functions
1327
1328 The functions in this section are related to the exponential functions;
1329 see @ref{Exponents and Logarithms}.
1330
1331 @comment math.h
1332 @comment ISO
1333 @deftypefun double sinh (double @var{x})
1334 @deftypefunx float sinhf (float @var{x})
1335 @deftypefunx {long double} sinhl (long double @var{x})
1336 These functions return the hyperbolic sine of @var{x}, defined
1337 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  The
1338 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1339 @var{x} is too large; that is, if overflow occurs.
1340 @end deftypefun
1341
1342 @comment math.h
1343 @comment ISO
1344 @deftypefun double cosh (double @var{x})
1345 @deftypefunx float coshf (float @var{x})
1346 @deftypefunx {long double} coshl (long double @var{x})
1347 These function return the hyperbolic cosine of @var{x},
1348 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
1349 The function fails, and sets @code{errno} to @code{ERANGE}, if the value
1350 of @var{x} is too large; that is, if overflow occurs.
1351 @end deftypefun
1352
1353 @comment math.h
1354 @comment ISO
1355 @deftypefun double tanh (double @var{x})
1356 @deftypefunx float tanhf (float @var{x})
1357 @deftypefunx {long double} tanhl (long double @var{x})
1358 These functions return the hyperbolic tangent of @var{x}, whose
1359 mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
1360 @end deftypefun
1361
1362 @cindex hyperbolic functions
1363
1364 There are counterparts for these hyperbolic functions which work with
1365 complex valued arguments.  They should always be used instead of the
1366 obvious mathematical formula since the implementations in the math
1367 library are optimized for accuracy and speed.
1368
1369 @comment complex.h
1370 @comment ISO
1371 @deftypefun {complex double} csinh (complex double @var{z})
1372 @deftypefunx {complex float} csinhf (complex float @var{z})
1373 @deftypefunx {complex long double} csinhl (complex long double @var{z})
1374 These functions return the complex hyperbolic sine of @var{z}, defined
1375 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.  The
1376 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1377 result is too large.
1378 @end deftypefun
1379
1380 @comment complex.h
1381 @comment ISO
1382 @deftypefun {complex double} ccosh (complex double @var{z})
1383 @deftypefunx {complex float} ccoshf (complex float @var{z})
1384 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
1385 These functions return the complex hyperbolic cosine of @var{z}, defined
1386 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.  The
1387 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1388 result is too large.
1389 @end deftypefun
1390
1391 @comment complex.h
1392 @comment ISO
1393 @deftypefun {complex double} ctanh (complex double @var{z})
1394 @deftypefunx {complex float} ctanhf (complex float @var{z})
1395 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
1396 These functions return the complex hyperbolic tangent of @var{z}, whose
1397 mathematical definition is @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
1398 @end deftypefun
1399
1400
1401 @cindex inverse hyperbolic functions
1402
1403 @comment math.h
1404 @comment ISO
1405 @deftypefun double asinh (double @var{x})
1406 @deftypefunx float asinhf (float @var{x})
1407 @deftypefunx {long double} asinhl (long double @var{x})
1408 These functions return the inverse hyperbolic sine of @var{x}---the
1409 value whose hyperbolic sine is @var{x}.
1410 @end deftypefun
1411
1412 @comment math.h
1413 @comment ISO
1414 @deftypefun double acosh (double @var{x})
1415 @deftypefunx float acoshf (float @var{x})
1416 @deftypefunx {long double} acoshl (long double @var{x})
1417 These functions return the inverse hyperbolic cosine of @var{x}---the
1418 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
1419 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
1420 @end deftypefun
1421
1422 @comment math.h
1423 @comment ISO
1424 @deftypefun double atanh (double @var{x})
1425 @deftypefunx float atanhf (float @var{x})
1426 @deftypefunx {long double} atanhl (long double @var{x})
1427 These functions return the inverse hyperbolic tangent of @var{x}---the
1428 value whose hyperbolic tangent is @var{x}.  If the absolute value of
1429 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
1430 @code{HUGE_VAL}.
1431 @end deftypefun
1432
1433 @cindex inverse complex hyperbolic functions
1434
1435 @comment complex.h
1436 @comment ISO
1437 @deftypefun {complex double} casinh (complex double @var{z})
1438 @deftypefunx {complex float} casinhf (complex float @var{z})
1439 @deftypefunx {complex long double} casinhl (complex long double @var{z})
1440 These functions return the inverse complex hyperbolic sine of
1441 @var{z}---the value whose complex hyperbolic sine is @var{z}.
1442 @end deftypefun
1443
1444 @comment complex.h
1445 @comment ISO
1446 @deftypefun {complex double} cacosh (complex double @var{z})
1447 @deftypefunx {complex float} cacoshf (complex float @var{z})
1448 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
1449 These functions return the inverse complex hyperbolic cosine of
1450 @var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
1451 the real valued function @code{acosh} there is not limit for the range
1452 of the argument.
1453 @end deftypefun
1454
1455 @comment complex.h
1456 @comment ISO
1457 @deftypefun {complex double} catanh (complex double @var{z})
1458 @deftypefunx {complex float} catanhf (complex float @var{z})
1459 @deftypefunx {complex long double} catanhl (complex long double @var{z})
1460 These functions return the inverse complex hyperbolic tangent of
1461 @var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
1462 the real valued function @code{atanh} there is not limit for the range
1463 of the argument.
1464 @end deftypefun
1465
1466
1467 @node Pseudo-Random Numbers
1468 @section Pseudo-Random Numbers
1469 @cindex random numbers
1470 @cindex pseudo-random numbers
1471 @cindex seed (for random numbers)
1472
1473 This section describes the GNU facilities for generating a series of
1474 pseudo-random numbers.  The numbers generated are not truly random;
1475 typically, they form a sequence that repeats periodically, with a
1476 period so large that you can ignore it for ordinary purposes.  The
1477 random number generator works by remembering at all times a @dfn{seed}
1478 value which it uses to compute the next random number and also to
1479 compute a new seed.
1480
1481 Although the generated numbers look unpredictable within one run of a
1482 program, the sequence of numbers is @emph{exactly the same} from one run
1483 to the next.  This is because the initial seed is always the same.  This
1484 is convenient when you are debugging a program, but it is unhelpful if
1485 you want the program to behave unpredictably.  If you want truly random
1486 numbers, not just pseudo-random, specify a seed based on the current
1487 time.
1488
1489 You can get repeatable sequences of numbers on a particular machine type
1490 by specifying the same initial seed value for the random number
1491 generator.  There is no standard meaning for a particular seed value;
1492 the same seed, used in different C libraries or on different CPU types,
1493 will give you different random numbers.
1494
1495 The GNU library supports the standard @w{ISO C} random number functions
1496 plus two other sets derived from BSD and SVID.  We recommend you use the
1497 standard ones, @code{rand} and @code{srand} if only a small number of
1498 random bits are required.  The SVID functions provide an interface which
1499 allows better random number generator algorithms and they return up to
1500 48 random bits in one calls and they also return random floating-point
1501 numbers if wanted.  The SVID function might not be available on some BSD
1502 derived systems but since they are required in the XPG they are
1503 available on all Unix-conformant systems.
1504
1505 @menu
1506 * ISO Random::       @code{rand} and friends.
1507 * BSD Random::       @code{random} and friends.
1508 * SVID Random::      @code{drand48} and friends.
1509 @end menu
1510
1511 @node ISO Random
1512 @subsection ISO C Random Number Functions
1513
1514 This section describes the random number functions that are part of
1515 the @w{ISO C} standard.
1516
1517 To use these facilities, you should include the header file
1518 @file{stdlib.h} in your program.
1519 @pindex stdlib.h
1520
1521 @comment stdlib.h
1522 @comment ISO
1523 @deftypevr Macro int RAND_MAX
1524 The value of this macro is an integer constant expression that
1525 represents the maximum possible value returned by the @code{rand}
1526 function.  In the GNU library, it is @code{037777777}, which is the
1527 largest signed integer representable in 32 bits.  In other libraries, it
1528 may be as low as @code{32767}.
1529 @end deftypevr
1530
1531 @comment stdlib.h
1532 @comment ISO
1533 @deftypefun int rand (void)
1534 The @code{rand} function returns the next pseudo-random number in the
1535 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
1536 @end deftypefun
1537
1538 @comment stdlib.h
1539 @comment ISO
1540 @deftypefun void srand (unsigned int @var{seed})
1541 This function establishes @var{seed} as the seed for a new series of
1542 pseudo-random numbers.  If you call @code{rand} before a seed has been
1543 established with @code{srand}, it uses the value @code{1} as a default
1544 seed.
1545
1546 To produce truly random numbers (not just pseudo-random), do @code{srand
1547 (time (0))}.
1548 @end deftypefun
1549
1550 A completely broken interface was designed by the POSIX.1 committee to
1551 support reproducible random numbers in multi-threaded programs.
1552
1553 @comment stdlib.h
1554 @comment POSIX.1
1555 @deftypefun int rand_r (unsigned int *@var{seed})
1556 This function returns a random number in the range 0 to @code{RAND_MAX}
1557 just as @code{rand} does.  But this function does not keep an internal
1558 state for the RNG.  Instead the @code{unsigned int} variable pointed to
1559 by the argument @var{seed} is the only state.  Before the value is
1560 returned the state will be updated so that the next call will return a
1561 new number.
1562
1563 I.e., the state of the RNG can only have as much bits as the type
1564 @code{unsigned int} has.  This is far too few to provide a good RNG.
1565 This interface is broken by design.
1566
1567 If the program requires reproducible random numbers in multi-threaded
1568 programs the reentrant SVID functions are probably a better choice.  But
1569 these functions are GNU extensions and therefore @code{rand_r}, as being
1570 standardized in POSIX.1, should always be kept as a default method.
1571 @end deftypefun
1572
1573
1574 @node BSD Random
1575 @subsection BSD Random Number Functions
1576
1577 This section describes a set of random number generation functions that
1578 are derived from BSD.  There is no advantage to using these functions
1579 with the GNU C library; we support them for BSD compatibility only.
1580
1581 The prototypes for these functions are in @file{stdlib.h}.
1582 @pindex stdlib.h
1583
1584 @comment stdlib.h
1585 @comment BSD
1586 @deftypefun {int32_t} random (void)
1587 This function returns the next pseudo-random number in the sequence.
1588 The range of values returned is from @code{0} to @code{RAND_MAX}.
1589
1590 @strong{Please note:} Historically this function returned a @code{long
1591 int} value.  But with the appearance of 64bit machines this could lead
1592 to severe compatibility problems and therefore the type now explicitly
1593 limits the return value to 32bit.
1594 @end deftypefun
1595
1596 @comment stdlib.h
1597 @comment BSD
1598 @deftypefun void srandom (unsigned int @var{seed})
1599 The @code{srandom} function sets the seed for the current random number
1600 state based on the integer @var{seed}.  If you supply a @var{seed} value
1601 of @code{1}, this will cause @code{random} to reproduce the default set
1602 of random numbers.
1603
1604 To produce truly random numbers (not just pseudo-random), do
1605 @code{srandom (time (0))}.
1606 @end deftypefun
1607
1608 @comment stdlib.h
1609 @comment BSD
1610 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1611 The @code{initstate} function is used to initialize the random number
1612 generator state.  The argument @var{state} is an array of @var{size}
1613 bytes, used to hold the state information.  The size must be at least 8
1614 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
1615 the @var{state} array, the better.
1616
1617 The return value is the previous value of the state information array.
1618 You can use this value later as an argument to @code{setstate} to
1619 restore that state.
1620 @end deftypefun
1621
1622 @comment stdlib.h
1623 @comment BSD
1624 @deftypefun {void *} setstate (void *@var{state})
1625 The @code{setstate} function restores the random number state
1626 information @var{state}.  The argument must have been the result of
1627 a previous call to @var{initstate} or @var{setstate}.
1628
1629 The return value is the previous value of the state information array.
1630 You can use this value later as an argument to @code{setstate} to
1631 restore that state.
1632 @end deftypefun
1633
1634
1635 @node SVID Random
1636 @subsection SVID Random Number Function
1637
1638 The C library on SVID systems contains yet another kind of random number
1639 generator functions.  They use a state of 48 bits of data.  The user can
1640 choose among a collection of functions which all return the random bits
1641 in different forms.
1642
1643 Generally there are two kinds of functions: those which use a state of
1644 the random number generator which is shared among several functions and
1645 by all threads of the process.  The second group of functions require
1646 the user to handle the state.
1647
1648 All functions have in common that they use the same congruential
1649 formula with the same constants.  The formula is
1650
1651 @smallexample
1652 Y = (a * X + c) mod m
1653 @end smallexample
1654
1655 @noindent
1656 where @var{X} is the state of the generator at the beginning and
1657 @var{Y} the state at the end.  @code{a} and @code{c} are constants
1658 determining the way the generator work.  By default they are
1659
1660 @smallexample
1661 a = 0x5DEECE66D = 25214903917
1662 c = 0xb = 11
1663 @end smallexample
1664
1665 @noindent
1666 but they can also be changed by the user.  @code{m} is of course 2^48
1667 since the state consists of a 48 bit array.
1668
1669
1670 @comment stdlib.h
1671 @comment SVID
1672 @deftypefun double drand48 (void)
1673 This function returns a @code{double} value in the range of @code{0.0}
1674 to @code{1.0} (exclusive).  The random bits are determined by the global
1675 state of the random number generator in the C library.
1676
1677 Since the @code{double} type according to @w{IEEE 754} has a 52 bit
1678 mantissa this means 4 bits are not initialized by the random number
1679 generator.  These are (of course) chosen to be the least significant
1680 bits and they are initialized to @code{0}.
1681 @end deftypefun
1682
1683 @comment stdlib.h
1684 @comment SVID
1685 @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
1686 This function returns a @code{double} value in the range of @code{0.0}
1687 to @code{1.0} (exclusive), similar to @code{drand48}.  The argument is
1688 an array describing the state of the random number generator.
1689
1690 This function can be called subsequently since it updates the array to
1691 guarantee random numbers.  The array should have been initialized before
1692 using to get reproducible results.
1693 @end deftypefun
1694
1695 @comment stdlib.h
1696 @comment SVID
1697 @deftypefun {long int} lrand48 (void)
1698 The @code{lrand48} functions return an integer value in the range of
1699 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
1700 int} type can take more than 32 bits no higher numbers are returned.
1701 The random bits are determined by the global state of the random number
1702 generator in the C library.
1703 @end deftypefun
1704
1705 @comment stdlib.h
1706 @comment SVID
1707 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
1708 This function is similar to the @code{lrand48} function in that it
1709 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1710 the state of the random number generator used to produce the random bits
1711 is determined by the array provided as the parameter to the function.
1712
1713 The numbers in the array are afterwards updated so that subsequent calls
1714 to this function yield to different results (as it is expected by a
1715 random number generator).  The array should have been initialized before
1716 the first call to get reproducible results.
1717 @end deftypefun
1718
1719 @comment stdlib.h
1720 @comment SVID
1721 @deftypefun {long int} mrand48 (void)
1722 The @code{mrand48} function is similar to @code{lrand48}.  The only
1723 difference is that the numbers returned are in the range @code{-2^31} to
1724 @code{2^31} (exclusive).
1725 @end deftypefun
1726
1727 @comment stdlib.h
1728 @comment SVID
1729 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
1730 The @code{jrand48} function is similar to @code{nrand48}.  The only
1731 difference is that the numbers returned are in the range @code{-2^31} to
1732 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
1733 requirements are necessary.
1734 @end deftypefun
1735
1736 The internal state of the random number generator can be initialized in
1737 several ways.  The functions differ in the completeness of the
1738 information provided.
1739
1740 @comment stdlib.h
1741 @comment SVID
1742 @deftypefun void srand48 (long int @var{seedval}))
1743 The @code{srand48} function sets the most significant 32 bits of the
1744 state internal state of the random number generator to the least
1745 significant 32 bits of the @var{seedval} parameter.  The lower 16 bits
1746 are initialized to the value @code{0x330E}.  Even if the @code{long
1747 int} type contains more the 32 bits only the lower 32 bits are used.
1748
1749 Due to this limitation the initialization of the state using this
1750 function of not very useful.  But it makes it easy to use a construct
1751 like @code{srand48 (time (0))}.
1752
1753 A side-effect of this function is that the values @code{a} and @code{c}
1754 from the internal state, which are used in the congruential formula,
1755 are reset to the default values given above.  This is of importance once
1756 the user called the @code{lcong48} function (see below).
1757 @end deftypefun
1758
1759 @comment stdlib.h
1760 @comment SVID
1761 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
1762 The @code{seed48} function initializes all 48 bits of the state of the
1763 internal random number generator from the content of the parameter
1764 @var{seed16v}.  Here the lower 16 bits of the first element of
1765 @var{see16v} initialize the least significant 16 bits of the internal
1766 state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
1767 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
1768 initialize the most significant 16 bits of the state.
1769
1770 Unlike @code{srand48} this function lets the user initialize all 48 bits
1771 of the state.
1772
1773 The value returned by @code{seed48} is a pointer to an array containing
1774 the values of the internal state before the change.  This might be
1775 useful to restart the random number generator at a certain state.
1776 Otherwise, the value can simply be ignored.
1777
1778 As for @code{srand48}, the values @code{a} and @code{c} from the
1779 congruential formula are reset to the default values.
1780 @end deftypefun
1781
1782 There is one more function to initialize the random number generator
1783 which allows to specify even more information by allowing to change the
1784 parameters in the congruential formula.
1785
1786 @comment stdlib.h
1787 @comment SVID
1788 @deftypefun void lcong48 (unsigned short int @var{param}[7])
1789 The @code{lcong48} function allows the user to change the complete state
1790 of the random number generator.  Unlike @code{srand48} and
1791 @code{seed48}, this function also changes the constants in the
1792 congruential formula.
1793
1794 From the seven elements in the array @var{param} the least significant
1795 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
1796 determine the the initial state, the least 16 bits of
1797 @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
1798 constant @code{a} and @code{@var{param}[6]} determines the 16 bit value
1799 @code{c}.
1800 @end deftypefun
1801
1802 All the above functions have in common that they use the global
1803 parameters for the congruential formula.  In multi-threaded programs it
1804 might sometimes be useful to have different parameters in different
1805 threads.  For this reason all the above functions have a counterpart
1806 which works on a description of the random number generator in the
1807 user-supplied buffer instead of the global state.
1808
1809 Please note that it is no problem if several threads use the global
1810 state if all threads use the functions which take a pointer to an array
1811 containing the state.  The random numbers are computed following the
1812 same loop but if the state in the array is different all threads will
1813 get an individual random number generator.
1814
1815 The user supplied buffer must be of type @code{struct drand48_data}.
1816 This type should be regarded as opaque and no member should be used
1817 directly.
1818
1819 @comment stdlib.h
1820 @comment GNU
1821 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1822 This function is equivalent to the @code{drand48} function with the
1823 difference it does not modify the global random number generator
1824 parameters but instead the parameters is the buffer supplied by the
1825 buffer through the pointer @var{buffer}.  The random number is return in
1826 the variable pointed to by @var{result}.
1827
1828 The return value of the function indicate whether the call succeeded.
1829 If the value is less than @code{0} an error occurred and @var{errno} is
1830 set to indicate the problem.
1831
1832 This function is a GNU extension and should not be used in portable
1833 programs.
1834 @end deftypefun
1835
1836 @comment stdlib.h
1837 @comment GNU
1838 @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
1839 The @code{erand48_r} function works like the @code{erand48} and it takes
1840 an argument @var{buffer} which describes the random number generator.
1841 The state of the random number generator is taken from the @code{xsubi}
1842 array, the parameters for the congruential formula from the global
1843 random number generator data.  The random number is return in the
1844 variable pointed to by @var{result}.
1845
1846 The return value is non-negative is the call succeeded.
1847
1848 This function is a GNU extension and should not be used in portable
1849 programs.
1850 @end deftypefun
1851
1852 @comment stdlib.h
1853 @comment GNU
1854 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1855 This function is similar to @code{lrand48} and it takes a pointer to a
1856 buffer describing the state of the random number generator as a
1857 parameter just like @code{drand48}.
1858
1859 If the return value of the function is non-negative the variable pointed
1860 to by @var{result} contains the result.  Otherwise an error occurred.
1861
1862 This function is a GNU extension and should not be used in portable
1863 programs.
1864 @end deftypefun
1865
1866 @comment stdlib.h
1867 @comment GNU
1868 @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1869 The @code{nrand48_r} function works like @code{nrand48} in that it
1870 produces a random number in range @code{0} to @code{2^31}.  But instead
1871 of using the global parameters for the congruential formula it uses the
1872 information from the buffer pointed to by @var{buffer}.  The state is
1873 described by the values in @var{xsubi}.
1874
1875 If the return value is non-negative the variable pointed to by
1876 @var{result} contains the result.
1877
1878 This function is a GNU extension and should not be used in portable
1879 programs.
1880 @end deftypefun
1881
1882 @comment stdlib.h
1883 @comment GNU
1884 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1885 This function is similar to @code{mrand48} but as the other reentrant
1886 function it uses the random number generator described by the value in
1887 the buffer pointed to by @var{buffer}.
1888
1889 If the return value is non-negative the variable pointed to by
1890 @var{result} contains the result.
1891
1892 This function is a GNU extension and should not be used in portable
1893 programs.
1894 @end deftypefun
1895
1896 @comment stdlib.h
1897 @comment GNU
1898 @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1899 The @code{jrand48_r} function is similar to @code{jrand48}.  But as the
1900 other reentrant functions of this function family it uses the
1901 congruential formula parameters from the buffer pointed to by
1902 @var{buffer}.
1903
1904 If the return value is non-negative the variable pointed to by
1905 @var{result} contains the result.
1906
1907 This function is a GNU extension and should not be used in portable
1908 programs.
1909 @end deftypefun
1910
1911 Before any of the above functions should be used the buffer of type
1912 @code{struct drand48_data} should initialized.  The easiest way is to
1913 fill the whole buffer with null bytes, e.g., using
1914
1915 @smallexample
1916 memset (buffer, '\0', sizeof (struct drand48_data));
1917 @end smallexample
1918
1919 @noindent
1920 Using any of the reentrant functions of this family now will
1921 automatically initialize the random number generator to the default
1922 values for the state and the parameters of the congruential formula.
1923
1924 The other possibility is too use any of the functions which explicitely
1925 initialize the buffer.  Though it might be obvious how to initialize the
1926 buffer from the data given as parameter from the function it is highly
1927 recommended to use these functions since the result might not always be
1928 what you expect.
1929
1930 @comment stdlib.h
1931 @comment GNU
1932 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1933 The description of the random number generator represented by the
1934 information in @var{buffer} is initialized similar to what the function
1935 @code{srand48} does.  The state is initialized from the parameter
1936 @var{seedval} and the parameters for the congruential formula are
1937 initialized to the default values.
1938
1939 If the return value is non-negative the function call succeeded.
1940
1941 This function is a GNU extension and should not be used in portable
1942 programs.
1943 @end deftypefun
1944
1945 @comment stdlib.h
1946 @comment GNU
1947 @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
1948 This function is similar to @code{srand48_r} but like @code{seed48} it
1949 initializes all 48 bits of the state from the parameter @var{seed16v}.
1950
1951 If the return value is non-negative the function call succeeded.  It
1952 does not return a pointer to the previous state of the random number
1953 generator like the @code{seed48} function does.  if the user wants to
1954 preserve the state for a later rerun s/he can copy the whole buffer
1955 pointed to by @var{buffer}.
1956
1957 This function is a GNU extension and should not be used in portable
1958 programs.
1959 @end deftypefun
1960
1961 @comment stdlib.h
1962 @comment GNU
1963 @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
1964 This function initializes all aspects of the random number generator
1965 described in @var{buffer} by the data in @var{param}.  Here it is
1966 especially true the function does more than just copying the contents of
1967 @var{param} of @var{buffer}.  Some more actions are required and
1968 therefore it is important to use this function and not initialized the
1969 random number generator directly.
1970
1971 If the return value is non-negative the function call succeeded.
1972
1973 This function is a GNU extension and should not be used in portable
1974 programs.
1975 @end deftypefun