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