Describe clog10.
[kopensolaris-gnu/glibc.git] / manual / math.texi
1 @c We need some definitions here.
2 @ifhtml
3 @set cdot ยท
4 @end ifhtml
5 @iftex
6 @set cdot @cdot
7 @end iftex
8 @ifclear cdot
9 @set cdot x
10 @end ifclear
11 @iftex
12 @set infty @infty
13 @end iftex
14 @ifclear infty
15 @set infty oo
16 @end ifclear
17 @macro mul
18 @value{cdot}
19 @end macro
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 devisor 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 safed.
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 exception 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 Pointed to objects which previously were initialized by a call to
451 @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 exception is masked and so each
462 raised exception causes a trap to occur.  Whether this macro is available can easily be tested using @code{#ifdef}.
463
464 Some platforms might define further predefined environments.
465 @end itemize
466
467 @noindent
468 To set any of the environments there are two functions defined.
469
470 @deftypefun void fesetenv (const fenv_t *@var{envp})
471 Establish the floating-point environment described in the object pointed
472 to by @var{envp}.  Even if one or more exceptions flags in the restored
473 environment are set no exception is raised.
474 @end deftypefun
475
476 In some situations the previous status of the exception flags must not
477 simply be discarded and so this function is useful:
478
479 @deftypefun void feupdateenv (const fenv_t *@var{envp})
480 The current status of the floating-point unit is preserved in some
481 automatic storage before the environment described by the object pointed
482 to by @var{envp} is installed.  Once this is finished all exceptions set
483 in the original environment which is saved in the automatic storage, is
484 raised.
485 @end deftypefun
486
487 This function can be used to execute a part of the program with an
488 environment which masks all exceptions and before switching back remove
489 unwanted exception and raise the remaining exceptions.
490
491
492 @node Rounding Modes
493 @subsection Rounding modes of the Floating-Point Unit
494
495 @w{IEEE 754} defines four different rounding modes.  If the rounding
496 mode is supported by the floating-point implementation the corresponding
497 of the following macros is defined:
498
499 @table @code
500 @comment fenv.h
501 @comment ISO
502 @vindex FE_TONEAREST
503 @item FE_TONEAREST
504 Round to nearest.  This is the default mode and should always be used
505 except when a different mode is explicitely required.  Only rounding to
506 nearest guarantees numeric stability of the computations.
507
508 @comment fenv.h
509 @comment ISO
510 @vindex FE_UPWARD
511 @item FE_UPWARD
512 Round toward @math{+@infinity{}}.
513
514 @comment fenv.h
515 @comment ISO
516 @vindex FE_DOWNWARD
517 @item FE_DOWNWARD
518 Round toward @math{-@infinity{}}.
519
520 @comment fenv.h
521 @comment ISO
522 @vindex FE_TOWARDZERO
523 @item FE_TOWARDZERO
524 Round toward zero.
525 @end table
526
527 At any time one of the above four rounding modes is selected.  To get
528 information about the currently selected mode one can use this function:
529
530 @comment fenv.h
531 @comment ISO
532 @deftypefun int fegetround (void)
533 Return the currently selected rounding mode, represented by one of the
534 values of the defined rounding mode macros.
535 @end deftypefun
536
537 @noindent
538 To set a specific rounding mode the next function can be used.
539
540 @comment fenv.h
541 @comment ISO
542 @deftypefun int fesetround (int @var{round})
543 Change the currently selected rounding mode to the mode described by the
544 parameter @var{round}.  If @var{round} does not correspond to one of the
545 supported rounding modes nothing is changed.
546
547 The function returns a nonzero value iff the requested rounding mode can
548 be established.  Otherwise zero is returned.
549 @end deftypefun
550
551 Changing the rounding mode might be necessary for various reasons.  But
552 changing the mode only to round a given number normally is no good idea.
553 The standard defines a set of functions which can be used to round an
554 argument according to some rules and for all of the rounding modes there
555 is a corresponding function.
556
557 If a large set of number has to be rounded it might be good to change
558 the rounding mode and to not use the function the library provides.  So
559 the perhaps necessary switching of the rounding mode in the library
560 function can be avoided.  But since not all rounding modes are
561 guaranteed to exist on any platform this possible implementation cannot
562 be portably used.  A default method has to be implemented as well.
563
564
565 @node Mathematical Constants
566 @section Predefined Mathematical Constants
567 @cindex constants
568 @cindex mathematical constants
569
570 The header @file{math.h} defines a series of mathematical constants if
571 @code{_BSD_SOURCE} or a more general feature select macro is defined
572 before including this file.  All values are defined as preprocessor
573 macros starting with @code{M_}.  The collection includes:
574
575 @vtable @code
576 @item M_E
577 The value is that of the base of the natural logarithm.
578 @item M_LOG2E
579 The value is computed as the logarithm to base @code{2} of @code{M_E}.
580 @item M_LOG10E
581 The value is computed as the logarithm to base @code{10} of @code{M_E}.
582 @item M_LN2
583 The value is computed as the natural logarithm of @code{2}.
584 @item M_LN10
585 The value is computed as the natural logarithm of @code{10}.
586 @item M_PI
587 The value is those of the number pi.
588 @item M_PI_2
589 The value is those of the number pi divided by two.
590 @item M_PI_4
591 The value is those of the number pi divided by four.
592 @item M_1_PI
593 The value is the reziprocal of the value of the number pi.
594 @item M_2_PI
595 The value is two times the reziprocal of the value of the number pi.
596 @item M_2_SQRTPI
597 The value is two times the reziprocal of the square root of the number pi.
598 @item M_SQRT2
599 The value is the square root of the value of the number pi.
600 @item M_SQRT1_2
601 The value is the reziprocal of the square root of the value of the number pi.
602 @end vtable
603
604 All values are defined as @code{long double} values unless the compiler
605 does not support this type or @code{__STDC__} is not defined (both is
606 unlikely).  Historically the numbers were @code{double} values and some
607 old code still relies on this so you might want to add explicit casts if
608 the extra precision of the @code{long double} value is not needed.  One
609 critical case are functions with a variable number of arguments, such as
610 @code{printf}.
611
612 @vindex PI
613 @emph{Note:} Some programs use a constant named @code{PI} which has the
614 same value as @code{M_PI}.  This probably derives from Stroustroup's
615 book about his C++ programming language where this value is used in
616 examples (and perhaps some AT&T headers contain this value).  But due to
617 possible name space problems (@code{PI} is a quite frequently used name)
618 this value is not added to @file{math.h}.  Every program should use
619 @code{M_PI} instead or add on the compiler command line
620 @code{-DPI=M_PI}.
621
622
623 @node FP Comparison Functions
624 @section Floating-Point Comparison Functions
625 @cindex unordered comparison
626
627 The @w{IEEE 754} standards defines a set of functions which allows to
628 compare even those numbers which normally would cause an exception to be
629 raised since they are unordered.  E.g., the expression
630
631 @smallexample
632 int v = a < 1.0;
633 @end smallexample
634
635 @noindent
636 would raise an exception if @var{a} would be a NaN.  Functions to
637 compare unordered numbers are part of the FORTRAN language for a long
638 time and the extensions in @w{ISO C 9X} finally introduce them as well
639 for the C programming language.
640
641 All of the operations are implemented as macros which allow their
642 arguments to be of either @code{float}, @code{double}, or @code{long
643 double} type.
644
645 @comment math.h
646 @comment ISO
647 @deftypefn {Macro} int isgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
648 This macro determines whether the argument @var{x} is greater than
649 @var{y}.  This is equivalent to @code{(@var{x}) > (@var{y})} but no
650 exception is raised if @var{x} or @var{y} are unordered.
651 @end deftypefn
652
653 @comment math.h
654 @comment ISO
655 @deftypefn {Macro} int isgreaterequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
656 This macro determines whether the argument @var{x} is greater than or
657 equal to @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 isless (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
664 This macro determines whether the argument @var{x} is less than @var{y}.
665 This is equivalent @code{(@var{x}) < (@var{y})} but no exception is raised if
666 @var{x} or @var{y} are unordered.
667 @end deftypefn
668
669 @comment math.h
670 @comment ISO
671 @deftypefn {Macro} int islessequal (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
672 This macro determines whether the argument @var{x} is less than or equal
673 to @var{y}.  This is equivalent to @code{(@var{x}) <= (@var{y})} but no
674 exception is raised if @var{x} or @var{y} are unordered.
675 @end deftypefn
676
677 @comment math.h
678 @comment ISO
679 @deftypefn {Macro} int islessgreater (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
680 This macro determines whether the argument @var{x} is less or greater
681 than @var{y}.  This is equivalent to @code{(@var{x}) < (@var{y}) ||
682 (@var{x}) > (@var{y})} (except that @var{x} and @var{y} are only
683 evaluated once) but no exception is raised if @var{x} or @var{y} are
684 unordered.
685 @end deftypefn
686
687 @comment math.h
688 @comment ISO
689 @deftypefn {Macro} int isunordered (@emph{real-floating} @var{x}, @emph{real-floating} @var{y})
690 This macro determines whether its arguments are unordered.
691 @end deftypefn
692
693 All the macros are defined in a way to ensure that both arguments are
694 evaluated exactly once and so they can be used exactly like the builtin
695 operators.
696
697 On several platform these macros are mapped to efficient instructions
698 the processor understands.  But on machines missing these functions, the
699 macros above might be rather slow.  So it is best to use the builtin
700 operators unless it is necessary to use unordered comparisons.
701
702 @strong{Note:} There are no macros @code{isequal} or @code{isunequal}.
703 These macros are not necessary since the @w{IEEE 754} standard requires
704 that the comparison for equality and unequality do @emph{not} throw an
705 exception if one of the arguments is an unordered value.
706
707
708 @node FP Function Optimizations
709 @section Is Fast Code or Small Code preferred?
710 @cindex Optimization
711
712 If an application uses many floating point function it is often the case
713 that the costs for the function calls itseld are not neglectable.
714 Modern processor implementation often can execute the operation itself
715 very fast but the call means a disturbance of the control flow.
716
717 For this reason the GNU C Library provides optimizations for many of the
718 frequently used math functions.  When the GNU CC is used and the user
719 activates the optimizer several new inline functions and macros get
720 defined.  These new functions and macros have the same names as the
721 library function and so get used instead of the later.  In case of
722 inline functions the compiler will decide whether it is reasonable to
723 use the inline function and this decision is usually correct.
724
725 For the generated code this means that no calls to the library functions
726 are necessary.  This increases the speed significantly.  But the
727 drawback is that the code size increases and this increase is not always
728 neglectable.
729
730 In cases where the inline functions and macros are not wanted the symbol
731 @code{__NO_MATH_INLINES} should be defined before any system header is
732 included.  This will make sure only library functions are used.  Of
733 course it can be determined for each single file in the project whether
734 giving this option is preferred or not.
735
736
737 @node Trig Functions
738 @section Trigonometric Functions
739 @cindex trigonometric functions
740
741 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
742 The arguments to all of these functions are in units of radians; recall
743 that pi radians equals 180 degrees.
744
745 @cindex pi (trigonometric constant)
746 The math library does define a symbolic constant for pi in @file{math.h}
747 (@pxref{Mathematical Constants}) when BSD compliance is required
748 (@pxref{Feature Test Macros}).  In case it is not possible to use this
749 predefined macro one easily can define it:
750
751 @smallexample
752 #define M_PI 3.14159265358979323846264338327
753 @end smallexample
754
755 @noindent
756 You can also compute the value of pi with the expression @code{acos
757 (-1.0)}.
758
759
760 @comment math.h
761 @comment ISO
762 @deftypefun double sin (double @var{x})
763 @deftypefunx float sinf (float @var{x})
764 @deftypefunx {long double} sinl (long double @var{x})
765 These functions return the sine of @var{x}, where @var{x} is given in
766 radians.  The return value is in the range @code{-1} to @code{1}.
767 @end deftypefun
768
769 @comment math.h
770 @comment ISO
771 @deftypefun double cos (double @var{x})
772 @deftypefunx float cosf (float @var{x})
773 @deftypefunx {long double} cosl (long double @var{x})
774 These functions return the cosine of @var{x}, where @var{x} is given in
775 radians.  The return value is in the range @code{-1} to @code{1}.
776 @end deftypefun
777
778 @comment math.h
779 @comment ISO
780 @deftypefun double tan (double @var{x})
781 @deftypefunx float tanf (float @var{x})
782 @deftypefunx {long double} tanl (long double @var{x})
783 These functions return the tangent of @var{x}, where @var{x} is given in
784 radians.
785
786 The following @code{errno} error conditions are defined for this function:
787
788 @table @code
789 @item ERANGE
790 Mathematically, the tangent function has singularities at odd multiples
791 of pi/2.  If the argument @var{x} is too close to one of these
792 singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
793 either positive or negative @code{HUGE_VAL}.
794 @end table
795 @end deftypefun
796
797 In many applications where @code{sin} and @code{cos} are used, the value
798 for the same argument of both of these functions is used at the same
799 time.  Since the algorithm to compute these values is very similar for
800 both functions there is an additional function which computes both values
801 at the same time.
802
803 @comment math.h
804 @comment GNU
805 @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
806 @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
807 @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
808 These functions return the sine of @var{x} in @code{*@var{sinx}} and the
809 cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
810 radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
811 the range of @code{-1} to @code{1}.
812
813 This function is a GNU extension.  It should be used whenever both sine
814 and cosine are needed but in protable applications there should be a
815 fallback method for systems without this function.
816 @end deftypefun
817
818 @cindex complex trigonometric functions
819
820 The trigonometric functions are in mathematics not only defined on real
821 numbers.  They can be extended to complex numbers and the @w{ISO C 9X}
822 standard introduces these variants in the standard math library.
823
824 @comment complex.h
825 @comment ISO
826 @deftypefun {complex double} csin (complex double @var{z})
827 @deftypefunx {complex float} csinf (complex float @var{z})
828 @deftypefunx {complex long double} csinl (complex long double @var{z})
829 These functions return the complex sine of the complex value in @var{z}.
830 The mathematical definition of the complex sine is
831
832 @ifinfo
833 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
834 @end ifinfo
835 @iftex
836 @tex
837 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
838 @end tex
839 @end iftex
840 @end deftypefun
841
842 @comment complex.h
843 @comment ISO
844 @deftypefun {complex double} ccos (complex double @var{z})
845 @deftypefunx {complex float} ccosf (complex float @var{z})
846 @deftypefunx {complex long double} ccosl (complex long double @var{z})
847 These functions return the complex cosine of the complex value in @var{z}.
848 The mathematical definition of the complex cosine is
849
850 @ifinfo
851 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
852 @end ifinfo
853 @iftex
854 @tex
855 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
856 @end tex
857 @end iftex
858 @end deftypefun
859
860 @comment complex.h
861 @comment ISO
862 @deftypefun {complex double} ctan (complex double @var{z})
863 @deftypefunx {complex float} ctanf (complex float @var{z})
864 @deftypefunx {complex long double} ctanl (complex long double @var{z})
865 These functions return the complex tangent of the complex value in @var{z}.
866 The mathematical definition of the complex tangent is
867
868 @ifinfo
869 @math{tan (z) = 1/i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
870 @end ifinfo
871 @iftex
872 @tex
873 $$\tan(z) = {1\over i} {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
874 @end tex
875 @end iftex
876 @end deftypefun
877
878
879 @node Inverse Trig Functions
880 @section Inverse Trigonometric Functions
881 @cindex inverse trigonometric functions
882
883 These are the usual arc sine, arc cosine and arc tangent functions,
884 which are the inverses of the sine, cosine and tangent functions,
885 respectively.
886
887 @comment math.h
888 @comment ISO
889 @deftypefun double asin (double @var{x})
890 @deftypefunx float asinf (float @var{x})
891 @deftypefunx {long double} asinl (long double @var{x})
892 These functions compute the arc sine of @var{x}---that is, the value whose
893 sine is @var{x}.  The value is in units of radians.  Mathematically,
894 there are infinitely many such values; the one actually returned is the
895 one between @code{-pi/2} and @code{pi/2} (inclusive).
896
897 @code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
898 out of range.  The arc sine function is defined mathematically only
899 over the domain @code{-1} to @code{1}.
900 @end deftypefun
901
902 @comment math.h
903 @comment ISO
904 @deftypefun double acos (double @var{x})
905 @deftypefunx float acosf (float @var{x})
906 @deftypefunx {long double} acosl (long double @var{x})
907 These functions compute the arc cosine of @var{x}---that is, the value
908 whose cosine is @var{x}.  The value is in units of radians.
909 Mathematically, there are infinitely many such values; the one actually
910 returned is the one between @code{0} and @code{pi} (inclusive).
911
912 @code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
913 out of range.  The arc cosine function is defined mathematically only
914 over the domain @code{-1} to @code{1}.
915 @end deftypefun
916
917
918 @comment math.h
919 @comment ISO
920 @deftypefun double atan (double @var{x})
921 @deftypefunx float atanf (float @var{x})
922 @deftypefunx {long double} atanl (long double @var{x})
923 These functions compute the arc tangent of @var{x}---that is, the value
924 whose tangent is @var{x}.  The value is in units of radians.
925 Mathematically, there are infinitely many such values; the one actually
926 returned is the one between @code{-pi/2} and @code{pi/2}
927 (inclusive).
928 @end deftypefun
929
930 @comment math.h
931 @comment ISO
932 @deftypefun double atan2 (double @var{y}, double @var{x})
933 @deftypefunx float atan2f (float @var{y}, float @var{x})
934 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
935 This is the two argument arc tangent function.  It is similar to computing
936 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
937 are used to determine the quadrant of the result, and @var{x} is
938 permitted to be zero.  The return value is given in radians and is in
939 the range @code{-pi} to @code{pi}, inclusive.
940
941 If @var{x} and @var{y} are coordinates of a point in the plane,
942 @code{atan2} returns the signed angle between the line from the origin
943 to that point and the x-axis.  Thus, @code{atan2} is useful for
944 converting Cartesian coordinates to polar coordinates.  (To compute the
945 radial coordinate, use @code{hypot}; see @ref{Exponents and
946 Logarithms}.)
947
948 The function @code{atan2} sets @code{errno} to @code{EDOM} if both
949 @var{x} and @var{y} are zero; the return value is not defined in this
950 case.
951 @end deftypefun
952
953 @cindex inverse complex trigonometric functions
954
955 The inverse trigonometric functions also exist is separate versions
956 which are usable with complex numbers.
957
958 @comment complex.h
959 @comment ISO
960 @deftypefun {complex double} casin (complex double @var{z})
961 @deftypefunx {complex float} casinf (complex float @var{z})
962 @deftypefunx {complex long double} casinl (complex long double @var{z})
963 These functions compute the complex arc sine of @var{z}---that is, the
964 value whose sine is @var{z}.  The value is in units of radians.
965
966 Unlike the real version of the arc sine function @code{casin} has no
967 limitation on the argument @var{z}.
968 @end deftypefun
969
970 @comment complex.h
971 @comment ISO
972 @deftypefun {complex double} cacos (complex double @var{z})
973 @deftypefunx {complex float} cacosf (complex float @var{z})
974 @deftypefunx {complex long double} cacosl (complex long double @var{z})
975 These functions compute the complex arc cosine of @var{z}---that is, the
976 value whose cosine is @var{z}.  The value is in units of radians.
977
978 Unlike the real version of the arc cosine function @code{cacos} has no
979 limitation on the argument @var{z}.
980 @end deftypefun
981
982
983 @comment complex.h
984 @comment ISO
985 @deftypefun {complex double} catan (complex double @var{z})
986 @deftypefunx {complex float} catanf (complex float @var{z})
987 @deftypefunx {complex long double} catanl (complex long double @var{z})
988 These functions compute the complex arc tangent of @var{z}---that is,
989 the value whose tangent is @var{z}.  The value is in units of radians.
990 @end deftypefun
991
992
993 @node Exponents and Logarithms
994 @section Exponentiation and Logarithms
995 @cindex exponentiation functions
996 @cindex power functions
997 @cindex logarithm functions
998
999 @comment math.h
1000 @comment ISO
1001 @deftypefun double exp (double @var{x})
1002 @deftypefunx float expf (float @var{x})
1003 @deftypefunx {long double} expl (long double @var{x})
1004 These functions return the value of @code{e} (the base of natural
1005 logarithms) raised to power @var{x}.
1006
1007 The function fails, and sets @code{errno} to @code{ERANGE}, if the
1008 magnitude of the result is too large to be representable.
1009 @end deftypefun
1010
1011 @comment math.h
1012 @comment ISO
1013 @deftypefun double exp10 (double @var{x})
1014 @deftypefunx float exp10f (float @var{x})
1015 @deftypefunx {long double} exp10l (long double @var{x})
1016 These functions return the value of @code{10} raised to the power @var{x}.
1017 Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
1018
1019 The function fails, and sets @code{errno} to @code{ERANGE}, if the
1020 magnitude of the result is too large to be representable.
1021 @end deftypefun
1022
1023 @comment math.h
1024 @comment ISO
1025 @deftypefun double exp2 (double @var{x})
1026 @deftypefunx float exp2f (float @var{x})
1027 @deftypefunx {long double} exp2l (long double @var{x})
1028 These functions return the value of @code{2} raised to the power @var{x}.
1029 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
1030
1031 The function fails, and sets @code{errno} to @code{ERANGE}, if the
1032 magnitude of the result is too large to be representable.
1033 @end deftypefun
1034
1035
1036 @comment math.h
1037 @comment ISO
1038 @deftypefun double log (double @var{x})
1039 @deftypefunx float logf (floatdouble @var{x})
1040 @deftypefunx {long double} logl (long double @var{x})
1041 These functions return the natural logarithm of @var{x}.  @code{exp (log
1042 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
1043 C.
1044
1045 The following @code{errno} error conditions are defined for this function:
1046
1047 @table @code
1048 @item EDOM
1049 The argument @var{x} is negative.  The log function is defined
1050 mathematically to return a real result only on positive arguments.
1051
1052 @item ERANGE
1053 The argument is zero.  The log of zero is not defined.
1054 @end table
1055 @end deftypefun
1056
1057 @comment math.h
1058 @comment ISO
1059 @deftypefun double log10 (double @var{x})
1060 @deftypefunx float log10f (float @var{x})
1061 @deftypefunx {long double} log10l (long double @var{x})
1062 These functions return the base-10 logarithm of @var{x}.  Except for the
1063 different base, it is similar to the @code{log} function.  In fact,
1064 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
1065 @end deftypefun
1066
1067 @comment math.h
1068 @comment ISO
1069 @deftypefun double log2 (double @var{x})
1070 @deftypefunx float log2f (float @var{x})
1071 @deftypefunx {long double} log2l (long double @var{x})
1072 These functions return the base-2 logarithm of @var{x}.  Except for the
1073 different base, it is similar to the @code{log} function.  In fact,
1074 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
1075 @end deftypefun
1076
1077 @comment math.h
1078 @comment ISO
1079 @deftypefun double logb (double @var{x})
1080 @deftypefunx float logbf (float @var{x})
1081 @deftypefunx {long double} logbl (long double @var{x})
1082 These functions extract the exponent of @var{x} and return it as a
1083 signed integer value.  If @var{x} is zero, a range error may occur.
1084
1085 A special case are subnormal numbers (if supported by the floating-point
1086 format).  The exponent returned is not the actual value from @var{x}.
1087 Instead the number is first normalized as if the range of the exponent
1088 field is large enough.
1089 @end deftypefun
1090
1091 @comment math.h
1092 @comment ISO
1093 @deftypefun int ilogb (double @var{x})
1094 @deftypefunx int ilogbf (float @var{x})
1095 @deftypefunx int ilogbl (long double @var{x})
1096 These functions are equivalent to the corresponding @code{logb}
1097 functions except that the values are returned as signed integer values.
1098 Since integer values cannot represent infinity and NaN, there are some
1099 special symbols defined to help detect these situations.
1100
1101 @vindex FP_ILOGB0
1102 @vindex FP_ILOGBNAN
1103 @code{ilogb} returns @code{FP_ILOGB0} if @var{x} is @code{0} and it
1104 returns @code{FP_ILOGBNAN} if @var{x} is @code{NaN}.  These values are
1105 system specific and no fixed value is assigned.  More concrete, these
1106 values might even have the same value.  So a piece of code handling the
1107 result of @code{ilogb} could look like this:
1108
1109 @smallexample
1110 i = ilogb (f);
1111 if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
1112   @{
1113     if (isnan (f))
1114       @{
1115         /* @r{Handle NaN.}  */
1116       @}
1117     else if (f  == 0.0)
1118       @{
1119         /* @r{Handle 0.0.}  */
1120       @}
1121     else
1122       @{
1123         /* @r{Some other value with large exponent,}
1124            @r{perhaps +Inf.}  */
1125       @}
1126   @}
1127 @end smallexample
1128
1129 @end deftypefun
1130
1131 @comment math.h
1132 @comment ISO
1133 @deftypefun double pow (double @var{base}, double @var{power})
1134 @deftypefunx float powf (float @var{base}, float @var{power})
1135 @deftypefunx {long double} powl (long double @var{base}, long double @var{power})
1136 These are general exponentiation functions, returning @var{base} raised
1137 to @var{power}.
1138
1139 @need 250
1140 The following @code{errno} error conditions are defined for this function:
1141
1142 @table @code
1143 @item EDOM
1144 The argument @var{base} is negative and @var{power} is not an integral
1145 value.  Mathematically, the result would be a complex number in this case.
1146
1147 @item ERANGE
1148 An underflow or overflow condition was detected in the result.
1149 @end table
1150 @end deftypefun
1151
1152 @cindex square root function
1153 @comment math.h
1154 @comment ISO
1155 @deftypefun double sqrt (double @var{x})
1156 @deftypefunx float sqrtf (float @var{x})
1157 @deftypefunx {long double} sqrtl (long double @var{x})
1158 These functions return the nonnegative square root of @var{x}.
1159
1160 The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
1161 @var{x} is negative.  Mathematically, the square root would be a complex
1162 number.
1163 @c (@pxref{csqrt})
1164 @end deftypefun
1165
1166 @cindex cube root function
1167 @comment math.h
1168 @comment BSD
1169 @deftypefun double cbrt (double @var{x})
1170 @deftypefunx float cbrtf (float @var{x})
1171 @deftypefunx {long double} cbrtl (long double @var{x})
1172 These functions return the cube root of @var{x}.  They cannot
1173 fail; every representable real value has a representable real cube root.
1174 @end deftypefun
1175
1176 @comment math.h
1177 @comment ISO
1178 @deftypefun double hypot (double @var{x}, double @var{y})
1179 @deftypefunx float hypotf (float @var{x}, float @var{y})
1180 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
1181 These functions return @code{sqrt (@var{x}*@var{x} +
1182 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
1183 triangle with sides of length @var{x} and @var{y}, or the distance
1184 of the point (@var{x}, @var{y}) from the origin.)  Using this function
1185 instead of the direct formula is highly appreciated since the error is
1186 much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
1187 @end deftypefun
1188
1189 @comment math.h
1190 @comment ISO
1191 @deftypefun double expm1 (double @var{x})
1192 @deftypefunx float expm1f (float @var{x})
1193 @deftypefunx {long double} expm1l (long double @var{x})
1194 These functions return a value equivalent to @code{exp (@var{x}) - 1}.
1195 It is computed in a way that is accurate even if the value of @var{x} is
1196 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
1197 to subtraction of two numbers that are nearly equal.
1198 @end deftypefun
1199
1200 @comment math.h
1201 @comment ISO
1202 @deftypefun double log1p (double @var{x})
1203 @deftypefunx float log1pf (float @var{x})
1204 @deftypefunx {long double} log1pl (long double @var{x})
1205 This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
1206 It is computed in a way that is accurate even if the value of @var{x} is
1207 near zero.
1208 @end deftypefun
1209
1210 @cindex complex exponentiation functions
1211 @cindex complex logarithm functions
1212
1213 @w{ISO C 9X} defines variants of some of the exponentiation and
1214 logarithm functions.  As for the other functions handlung complex
1215 numbers these functions are perhaps better optimized and provide better
1216 error checking than a direct use of the formulas of the mathematical
1217 definition.
1218
1219 @comment complex.h
1220 @comment ISO
1221 @deftypefun {complex double} cexp (complex double @var{z})
1222 @deftypefunx {complex float} cexpf (complex float @var{z})
1223 @deftypefunx {complex long double} cexpl (complex long double @var{z})
1224 These functions return the value of @code{e} (the base of natural
1225 logarithms) raised to power of the complex value @var{z}.
1226
1227 @noindent
1228 Mathematically this corresponds to the value
1229
1230 @ifinfo
1231 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
1232 @end ifinfo
1233 @iftex
1234 @tex
1235 $$\exp(z) = e^z = e^{{\rm Re} z} (\cos ({\rm Im} z) + i \sin ({\rm Im} z))$$
1236 @end tex
1237 @end iftex
1238 @end deftypefun
1239
1240 @comment complex.h
1241 @comment ISO
1242 @deftypefun {complex double} clog (complex double @var{z})
1243 @deftypefunx {complex float} clogf (complex float @var{z})
1244 @deftypefunx {complex long double} clogl (complex long double @var{z})
1245 These functions return the natural logarithm of the complex value
1246 @var{z}.  Unlike the real value version @code{log} and its variants,
1247 @code{clog} has no limit for the range of its argument @var{z}.
1248
1249 @noindent
1250 Mathematically this corresponds to the value
1251
1252 @ifinfo
1253 @math{log (z) = log (cabs (z)) + I * carg (z)}
1254 @end ifinfo
1255 @iftex
1256 @tex
1257 $$\log(z) = \log(|z|) + i \arg(z)$$
1258 @end tex
1259 @end iftex
1260 @end deftypefun
1261
1262
1263 @comment complex.h
1264 @comment GNU
1265 @deftypefun {complex double} clog10 (complex double @var{z})
1266 @deftypefunx {complex float} clog10f (complex float @var{z})
1267 @deftypefunx {complex long double} clog10l (complex long double @var{z})
1268 These functions return the base 10 logarithm of the complex value
1269 @var{z}.  Unlike the real value version @code{log} and its variants,
1270 @code{clog} has no limit for the range of its argument @var{z}.
1271
1272 @noindent
1273 Mathematically this corresponds to the value
1274
1275 @ifinfo
1276 @math{log (z) = log10 (cabs (z)) + I * carg (z)}
1277 @end ifinfo
1278 @iftex
1279 @tex
1280 $$\log_{10}(z) = \log_{10}(|z|) + i \arg(z)$$
1281 @end tex
1282 @end iftex
1283
1284 This function is a GNU extension.
1285 @end deftypefun
1286
1287 @comment complex.h
1288 @comment ISO
1289 @deftypefun {complex double} csqrt (complex double @var{z})
1290 @deftypefunx {complex float} csqrtf (complex float @var{z})
1291 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
1292 These functions return the complex root of the argument @var{z}.  Unlike
1293 the @code{sqrt} function these functions do not have any restriction on
1294 the value of the argument.
1295 @end deftypefun
1296
1297 @comment complex.h
1298 @comment ISO
1299 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
1300 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
1301 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
1302 These functions return the complex value @var{base} raised to the power of
1303 @var{power}.  This is computed as
1304
1305 @ifinfo
1306 @math{cpow (x, y) = cexp (y * clog (x))}
1307 @end ifinfo
1308 @iftex
1309 @tex
1310 $${\rm cpow}(x, y) = e^{y \log(x)}$$
1311 @end tex
1312 @end iftex
1313 @end deftypefun
1314
1315
1316 @node Hyperbolic Functions
1317 @section Hyperbolic Functions
1318 @cindex hyperbolic functions
1319
1320 The functions in this section are related to the exponential functions;
1321 see @ref{Exponents and Logarithms}.
1322
1323 @comment math.h
1324 @comment ISO
1325 @deftypefun double sinh (double @var{x})
1326 @deftypefunx float sinhf (float @var{x})
1327 @deftypefunx {long double} sinhl (long double @var{x})
1328 These functions return the hyperbolic sine of @var{x}, defined
1329 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  The
1330 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1331 @var{x} is too large; that is, if overflow occurs.
1332 @end deftypefun
1333
1334 @comment math.h
1335 @comment ISO
1336 @deftypefun double cosh (double @var{x})
1337 @deftypefunx float coshf (float @var{x})
1338 @deftypefunx {long double} coshl (long double @var{x})
1339 These function return the hyperbolic cosine of @var{x},
1340 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
1341 The function fails, and sets @code{errno} to @code{ERANGE}, if the value
1342 of @var{x} is too large; that is, if overflow occurs.
1343 @end deftypefun
1344
1345 @comment math.h
1346 @comment ISO
1347 @deftypefun double tanh (double @var{x})
1348 @deftypefunx float tanhf (float @var{x})
1349 @deftypefunx {long double} tanhl (long double @var{x})
1350 These functions return the hyperbolic tangent of @var{x}, whose
1351 mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
1352 @end deftypefun
1353
1354 @cindex hyperbolic functions
1355
1356 There are counterparts for these hyperbolic functions which work with
1357 complex valued arguments.  They should always be used instead of the
1358 obvious mathematical formula since the implementations in the math
1359 library are optimized for accuracy and speed.
1360
1361 @comment complex.h
1362 @comment ISO
1363 @deftypefun {complex double} csinh (complex double @var{z})
1364 @deftypefunx {complex float} csinhf (complex float @var{z})
1365 @deftypefunx {complex long double} csinhl (complex long double @var{z})
1366 These functions return the complex hyperbolic sine of @var{z}, defined
1367 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.  The
1368 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1369 result is too large.
1370 @end deftypefun
1371
1372 @comment complex.h
1373 @comment ISO
1374 @deftypefun {complex double} ccosh (complex double @var{z})
1375 @deftypefunx {complex float} ccoshf (complex float @var{z})
1376 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
1377 These functions return the complex hyperbolic cosine of @var{z}, defined
1378 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.  The
1379 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1380 result is too large.
1381 @end deftypefun
1382
1383 @comment complex.h
1384 @comment ISO
1385 @deftypefun {complex double} ctanh (complex double @var{z})
1386 @deftypefunx {complex float} ctanhf (complex float @var{z})
1387 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
1388 These functions return the complex hyperbolic tangent of @var{z}, whose
1389 mathematical definition is @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
1390 @end deftypefun
1391
1392
1393 @cindex inverse hyperbolic functions
1394
1395 @comment math.h
1396 @comment ISO
1397 @deftypefun double asinh (double @var{x})
1398 @deftypefunx float asinhf (float @var{x})
1399 @deftypefunx {long double} asinhl (long double @var{x})
1400 These functions return the inverse hyperbolic sine of @var{x}---the
1401 value whose hyperbolic sine is @var{x}.
1402 @end deftypefun
1403
1404 @comment math.h
1405 @comment ISO
1406 @deftypefun double acosh (double @var{x})
1407 @deftypefunx float acoshf (float @var{x})
1408 @deftypefunx {long double} acoshl (long double @var{x})
1409 These functions return the inverse hyperbolic cosine of @var{x}---the
1410 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
1411 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
1412 @end deftypefun
1413
1414 @comment math.h
1415 @comment ISO
1416 @deftypefun double atanh (double @var{x})
1417 @deftypefunx float atanhf (float @var{x})
1418 @deftypefunx {long double} atanhl (long double @var{x})
1419 These functions return the inverse hyperbolic tangent of @var{x}---the
1420 value whose hyperbolic tangent is @var{x}.  If the absolute value of
1421 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
1422 @code{HUGE_VAL}.
1423 @end deftypefun
1424
1425 @cindex inverse complex hyperbolic functions
1426
1427 @comment complex.h
1428 @comment ISO
1429 @deftypefun {complex double} casinh (complex double @var{z})
1430 @deftypefunx {complex float} casinhf (complex float @var{z})
1431 @deftypefunx {complex long double} casinhl (complex long double @var{z})
1432 These functions return the inverse complex hyperbolic sine of
1433 @var{z}---the value whose complex hyperbolic sine is @var{z}.
1434 @end deftypefun
1435
1436 @comment complex.h
1437 @comment ISO
1438 @deftypefun {complex double} cacosh (complex double @var{z})
1439 @deftypefunx {complex float} cacoshf (complex float @var{z})
1440 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
1441 These functions return the inverse complex hyperbolic cosine of
1442 @var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
1443 the real valued function @code{acosh} there is not limit for the range
1444 of the argument.
1445 @end deftypefun
1446
1447 @comment complex.h
1448 @comment ISO
1449 @deftypefun {complex double} catanh (complex double @var{z})
1450 @deftypefunx {complex float} catanhf (complex float @var{z})
1451 @deftypefunx {complex long double} catanhl (complex long double @var{z})
1452 These functions return the inverse complex hyperbolic tangent of
1453 @var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
1454 the real valued function @code{atanh} there is not limit for the range
1455 of the argument.
1456 @end deftypefun
1457
1458
1459 @node Pseudo-Random Numbers
1460 @section Pseudo-Random Numbers
1461 @cindex random numbers
1462 @cindex pseudo-random numbers
1463 @cindex seed (for random numbers)
1464
1465 This section describes the GNU facilities for generating a series of
1466 pseudo-random numbers.  The numbers generated are not truly random;
1467 typically, they form a sequence that repeats periodically, with a
1468 period so large that you can ignore it for ordinary purposes.  The
1469 random number generator works by remembering at all times a @dfn{seed}
1470 value which it uses to compute the next random number and also to
1471 compute a new seed.
1472
1473 Although the generated numbers look unpredictable within one run of a
1474 program, the sequence of numbers is @emph{exactly the same} from one run
1475 to the next.  This is because the initial seed is always the same.  This
1476 is convenient when you are debugging a program, but it is unhelpful if
1477 you want the program to behave unpredictably.  If you want truly random
1478 numbers, not just pseudo-random, specify a seed based on the current
1479 time.
1480
1481 You can get repeatable sequences of numbers on a particular machine type
1482 by specifying the same initial seed value for the random number
1483 generator.  There is no standard meaning for a particular seed value;
1484 the same seed, used in different C libraries or on different CPU types,
1485 will give you different random numbers.
1486
1487 The GNU library supports the standard @w{ISO C} random number functions
1488 plus two other sets derived from BSD and SVID.  We recommend you use the
1489 standard ones, @code{rand} and @code{srand} if only a small number of
1490 random bits are required.  The SVID functions provide an interface which
1491 allows better randon number generator algorithms and they return up to
1492 48 random bits in one calls and they also return random floating-point
1493 numbers if wanted.  The SVID function might not be available on some BSD
1494 derived systems but since they are required in the XPG they are
1495 available on all Unix-conformant systems.
1496
1497 @menu
1498 * ISO Random::       @code{rand} and friends.
1499 * BSD Random::       @code{random} and friends.
1500 * SVID Random::      @code{drand48} and friends.
1501 @end menu
1502
1503 @node ISO Random
1504 @subsection ISO C Random Number Functions
1505
1506 This section describes the random number functions that are part of
1507 the @w{ISO C} standard.
1508
1509 To use these facilities, you should include the header file
1510 @file{stdlib.h} in your program.
1511 @pindex stdlib.h
1512
1513 @comment stdlib.h
1514 @comment ISO
1515 @deftypevr Macro int RAND_MAX
1516 The value of this macro is an integer constant expression that
1517 represents the maximum possible value returned by the @code{rand}
1518 function.  In the GNU library, it is @code{037777777}, which is the
1519 largest signed integer representable in 32 bits.  In other libraries, it
1520 may be as low as @code{32767}.
1521 @end deftypevr
1522
1523 @comment stdlib.h
1524 @comment ISO
1525 @deftypefun int rand (void)
1526 The @code{rand} function returns the next pseudo-random number in the
1527 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
1528 @end deftypefun
1529
1530 @comment stdlib.h
1531 @comment ISO
1532 @deftypefun void srand (unsigned int @var{seed})
1533 This function establishes @var{seed} as the seed for a new series of
1534 pseudo-random numbers.  If you call @code{rand} before a seed has been
1535 established with @code{srand}, it uses the value @code{1} as a default
1536 seed.
1537
1538 To produce truly random numbers (not just pseudo-random), do @code{srand
1539 (time (0))}.
1540 @end deftypefun
1541
1542 A completely broken interface was designed by the POSIX.1 committee to
1543 support reproducible random numbers in multi-threaded programs.
1544
1545 @comment stdlib.h
1546 @comment POSIX.1
1547 @deftypefun int rand_r (unsigned int *@var{seed})
1548 This function returns a random number in the range 0 to @code{RAND_MAX}
1549 just as @code{rand} does.  But this function does not keep an internal
1550 state for the RNG.  Instead the @code{unsigned int} variable pointed to
1551 by the argument @var{seed} is the only state.  Before the value is
1552 returned the state will be updated so that the next call will return a
1553 new number.
1554
1555 I.e., the state of the RNG can only have as much bits as the type
1556 @code{unsigned int} has.  This is far too few to provide a good RNG.
1557 This interface is broken by design.
1558
1559 If the program requires reproducible random numbers in multi-threaded
1560 programs the reentrant SVID functions are probably a better choice.  But
1561 these functions are GNU extensions and therefore @code{rand_r}, as being
1562 standardized in POSIX.1, should always be kept as a default method.
1563 @end deftypefun
1564
1565
1566 @node BSD Random
1567 @subsection BSD Random Number Functions
1568
1569 This section describes a set of random number generation functions that
1570 are derived from BSD.  There is no advantage to using these functions
1571 with the GNU C library; we support them for BSD compatibility only.
1572
1573 The prototypes for these functions are in @file{stdlib.h}.
1574 @pindex stdlib.h
1575
1576 @comment stdlib.h
1577 @comment BSD
1578 @deftypefun {int32_t} random (void)
1579 This function returns the next pseudo-random number in the sequence.
1580 The range of values returned is from @code{0} to @code{RAND_MAX}.
1581
1582 @strong{Please note:} Historically this function returned a @code{long
1583 int} value.  But with the appearence of 64bit machines this could lead
1584 to severe compatibility problems and therefore the type now explicitly
1585 limits the return value to 32bit.
1586 @end deftypefun
1587
1588 @comment stdlib.h
1589 @comment BSD
1590 @deftypefun void srandom (unsigned int @var{seed})
1591 The @code{srandom} function sets the seed for the current random number
1592 state based on the integer @var{seed}.  If you supply a @var{seed} value
1593 of @code{1}, this will cause @code{random} to reproduce the default set
1594 of random numbers.
1595
1596 To produce truly random numbers (not just pseudo-random), do
1597 @code{srandom (time (0))}.
1598 @end deftypefun
1599
1600 @comment stdlib.h
1601 @comment BSD
1602 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1603 The @code{initstate} function is used to initialize the random number
1604 generator state.  The argument @var{state} is an array of @var{size}
1605 bytes, used to hold the state information.  The size must be at least 8
1606 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
1607 the @var{state} array, the better.
1608
1609 The return value is the previous value of the state information array.
1610 You can use this value later as an argument to @code{setstate} to
1611 restore that state.
1612 @end deftypefun
1613
1614 @comment stdlib.h
1615 @comment BSD
1616 @deftypefun {void *} setstate (void *@var{state})
1617 The @code{setstate} function restores the random number state
1618 information @var{state}.  The argument must have been the result of
1619 a previous call to @var{initstate} or @var{setstate}.
1620
1621 The return value is the previous value of the state information array.
1622 You can use thise value later as an argument to @code{setstate} to
1623 restore that state.
1624 @end deftypefun
1625
1626
1627 @node SVID Random
1628 @subsection SVID Random Number Function
1629
1630 The C library on SVID systems contains yet another kind of random number
1631 generator functions.  They use a state of 48 bits of data.  The user can
1632 choose among a collection of functions which all return the random bits
1633 in different forms.
1634
1635 Generally there are two kinds of functions: those which use a state of
1636 the random number generator which is shared among several functions and
1637 by all threads of the process.  The second group of functions require
1638 the user to handle the state.
1639
1640 All functions have in common that they use the same congruential
1641 formula with the same constants.  The formula is
1642
1643 @smallexample
1644 Y = (a * X + c) mod m
1645 @end smallexample
1646
1647 @noindent
1648 where @var{X} is the state of the generator at the beginning and
1649 @var{Y} the state at the end.  @code{a} and @code{c} are constants
1650 determining the way the generator work.  By default they are
1651
1652 @smallexample
1653 a = 0x5DEECE66D = 25214903917
1654 c = 0xb = 11
1655 @end smallexample
1656
1657 @noindent
1658 but they can also be changed by the user.  @code{m} is of course 2^48
1659 since the state consists of a 48 bit array.
1660
1661
1662 @comment stdlib.h
1663 @comment SVID
1664 @deftypefun double drand48 (void)
1665 This function returns a @code{double} value in the range of @code{0.0}
1666 to @code{1.0} (exclusive).  The random bits are determined by the global
1667 state of the random number generator in the C library.
1668
1669 Since the @code{double} type according to @w{IEEE 754} has a 52 bit
1670 mantissa this means 4 bits are not initialized by the random number
1671 generator.  These are (of course) chosen to be the least significant
1672 bits and they are initialized to @code{0}.
1673 @end deftypefun
1674
1675 @comment stdlib.h
1676 @comment SVID
1677 @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
1678 This function returns a @code{double} value in the range of @code{0.0}
1679 to @code{1.0} (exclusive), similar to @code{drand48}.  The argument is
1680 an array describing the state of the random number generator.
1681
1682 This function can be called subsequently since it updates the array to
1683 guarantee random numbers.  The array should have been initialized before
1684 using to get reproducible results.
1685 @end deftypefun
1686
1687 @comment stdlib.h
1688 @comment SVID
1689 @deftypefun {long int} lrand48 (void)
1690 The @code{lrand48} functions return an integer value in the range of
1691 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
1692 int} type can take more than 32 bits no higher numbers are returned.
1693 The random bits are determined by the global state of the random number
1694 generator in the C library.
1695 @end deftypefun
1696
1697 @comment stdlib.h
1698 @comment SVID
1699 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
1700 This function is similar to the @code{lrand48} function in that it
1701 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1702 the state of the random number generator used to produce the random bits
1703 is determined by the array provided as the parameter to the function.
1704
1705 The numbers in the array are afterwards updated so that subsequent calls
1706 to this function yield to different results (as it is expected by a
1707 random number generator).  The array should have been initialized before
1708 the first call to get reproducible results.
1709 @end deftypefun
1710
1711 @comment stdlib.h
1712 @comment SVID
1713 @deftypefun {long int} mrand48 (void)
1714 The @code{mrand48} function is similar to @code{lrand48}.  The only
1715 difference is that the numbers returned are in the range @code{-2^31} to
1716 @code{2^31} (exclusive).
1717 @end deftypefun
1718
1719 @comment stdlib.h
1720 @comment SVID
1721 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
1722 The @code{jrand48} function is similar to @code{nrand48}.  The only
1723 difference is that the numbers returned are in the range @code{-2^31} to
1724 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
1725 requirements are necessary.
1726 @end deftypefun
1727
1728 The internal state of the random number generator can be initialized in
1729 several ways.  The functions differ in the completeness of the
1730 information provided.
1731
1732 @comment stdlib.h
1733 @comment SVID
1734 @deftypefun void srand48 (long int @var{seedval}))
1735 The @code{srand48} function sets the most significant 32 bits of the
1736 state internal state of the random number generator to the least
1737 significant 32 bits of the @var{seedval} parameter.  The lower 16 bts
1738 are initilialized to the value @code{0x330E}.  Even if the @code{long
1739 int} type contains more the 32 bits only the lower 32 bits are used.
1740
1741 Due to this limitation the initialization of the state using this
1742 function of not very useful.  But it makes it easy to use a constrcut
1743 like @code{srand48 (time (0))}.
1744
1745 A side-effect of this function is that the values @code{a} and @code{c}
1746 from the internal state, which are used in the congruential formula,
1747 are reset to the default values given above.  This is of importance once
1748 the user called the @code{lcong48} function (see below).
1749 @end deftypefun
1750
1751 @comment stdlib.h
1752 @comment SVID
1753 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
1754 The @code{seed48} function initializes all 48 bits of the state of the
1755 internal random number generator from the content of the parameter
1756 @var{seed16v}.  Here the lower 16 bits of the first element of
1757 @var{see16v} initialize the least significant 16 bits of the internal
1758 state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
1759 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
1760 initialize the most significant 16 bits of the state.
1761
1762 Unlike @code{srand48} this function lets the user initialize all 48 bits
1763 of the state.
1764
1765 The value returned by @code{seed48} is a pointer to an array containing
1766 the values of the internal state before the change.  This might be
1767 useful to restart the random number generator at a certain state.
1768 Otherwise, the value can simply be ignored.
1769
1770 As for @code{srand48}, the values @code{a} and @code{c} from the
1771 congruential formula are reset to the default values.
1772 @end deftypefun
1773
1774 There is one more function to initialize the random number generator
1775 which allows to specify even more information by allowing to change the
1776 parameters in the congruential formula.
1777
1778 @comment stdlib.h
1779 @comment SVID
1780 @deftypefun void lcong48 (unsigned short int @var{param}[7])
1781 The @code{lcong48} function allows the user to change the complete state
1782 of the random number generator.  Unlike @code{srand48} and
1783 @code{seed48}, this function also changes the constants in the
1784 congruential formula.
1785
1786 From the seven elements in the array @var{param} the least significant
1787 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
1788 determine the the initial state, the least 16 bits of
1789 @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
1790 constant @code{a} and @code{@var{param}[6]} determines the 16 bit value
1791 @code{c}.
1792 @end deftypefun
1793
1794 All the above functions have in common that they use the global
1795 parameters for the congruential formula.  In multi-threaded programs it
1796 might sometimes be useful to have different parameters in different
1797 threads.  For this reason all the above functions have a counterpart
1798 which works on a description of the random number generator in the
1799 user-supplied buffer instead of the global state.
1800
1801 Please note that it is no problem if several threads use the global
1802 state if all threads use the functions which take a pointer to an array
1803 containing the state.  The random numbers are computed following the
1804 same loop but if the state in the array is different all threads will
1805 get an individuual random number generator.
1806
1807 The user supplied buffer must be of type @code{struct drand48_data}.
1808 This type should be regarded as opaque and no member should be used
1809 directly.
1810
1811 @comment stdlib.h
1812 @comment GNU
1813 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1814 This function is equivalent to the @code{drand48} function with the
1815 difference it does not modify the global random number generator
1816 parameters but instead the parameters is the buffer supplied by the
1817 buffer through the pointer @var{buffer}.  The random number is return in
1818 the variable pointed to by @var{result}.
1819
1820 The return value of the function indicate whether the call succeeded.
1821 If the value is less than @code{0} an error occurred and @var{errno} is
1822 set to indicate the problem.
1823
1824 This function is a GNU extension and should not be used in portable
1825 programs.
1826 @end deftypefun
1827
1828 @comment stdlib.h
1829 @comment GNU
1830 @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
1831 The @code{erand48_r} function works like the @code{erand48} and it takes
1832 an argument @var{buffer} which describes the random number generator.
1833 The state of the random number genertor is taken from the @code{xsubi}
1834 array, the parameters for the congruential formula from the global
1835 random number generator data.  The random number is return in the
1836 variable pointed to by @var{result}.
1837
1838 The return value is non-negative is the call succeeded.
1839
1840 This function is a GNU extension and should not be used in portable
1841 programs.
1842 @end deftypefun
1843
1844 @comment stdlib.h
1845 @comment GNU
1846 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1847 This function is similar to @code{lrand48} and it takes a pointer to a
1848 buffer describing the state of the random number generator as a
1849 parameter just like @code{drand48}.
1850
1851 If the return value of the function is non-negative the variable pointed
1852 to by @var{result} contains the result.  Otherwise an error occurred.
1853
1854 This function is a GNU extension and should not be used in portable
1855 programs.
1856 @end deftypefun
1857
1858 @comment stdlib.h
1859 @comment GNU
1860 @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1861 The @code{nrand48_r} function works like @code{nrand48} in that it
1862 produces a random number in range @code{0} to @code{2^31}.  But instead
1863 of using the global parameters for the congruential formula it uses the
1864 information from the buffer pointed to by @var{buffer}.  The state is
1865 described by the values in @var{xsubi}.
1866
1867 If the return value is non-negative the variable pointed to by
1868 @var{result} contains the result.
1869
1870 This function is a GNU extension and should not be used in portable
1871 programs.
1872 @end deftypefun
1873
1874 @comment stdlib.h
1875 @comment GNU
1876 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1877 This function is similar to @code{mrand48} but as the other reentrant
1878 function it uses the random number generator described by the value in
1879 the buffer pointed to by @var{buffer}.
1880
1881 If the return value is non-negative the variable pointed to by
1882 @var{result} contains the result.
1883
1884 This function is a GNU extension and should not be used in portable
1885 programs.
1886 @end deftypefun
1887
1888 @comment stdlib.h
1889 @comment GNU
1890 @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1891 The @code{jrand48_r} function is similar to @code{jrand48}.  But as the
1892 other reentrant functions of this function family it uses the
1893 congruential formula parameters from the buffer pointed to by
1894 @var{buffer}.
1895
1896 If the return value is non-negative the variable pointed to by
1897 @var{result} contains the result.
1898
1899 This function is a GNU extension and should not be used in portable
1900 programs.
1901 @end deftypefun
1902
1903 Before any of the above functions should be used the buffer of type
1904 @code{struct drand48_data} should initialized.  The easiest way is to
1905 fill the whole buffer with null bytes, e.g., using
1906
1907 @smallexample
1908 memset (buffer, '\0', sizeof (struct drand48_data));
1909 @end smallexample
1910
1911 @noindent
1912 Using any of the reetrant functions of this family now will
1913 automatically initialize the random number generator to the default
1914 values for the state and the parameters of the congruential formula.
1915
1916 The other possibility is too use any of the functions which explicitely
1917 initialize the buffer.  Though it might be obvious how to initialize the
1918 buffer from the data given as parameter from the function it is highly
1919 recommended to use these functions since the result might not always be
1920 what you expect.
1921
1922 @comment stdlib.h
1923 @comment GNU
1924 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1925 The description of the random number generator represented by the
1926 information in @var{buffer} is initialized similar to what the function
1927 @code{srand48} does.  The state is initialized from the paramter
1928 @var{seedval} and the paameters for the congruential formula are
1929 initialized to the default values.
1930
1931 If the return value is non-negative the function call succeeded.
1932
1933 This function is a GNU extension and should not be used in portable
1934 programs.
1935 @end deftypefun
1936
1937 @comment stdlib.h
1938 @comment GNU
1939 @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
1940 This function is similar to @code{srand48_r} but like @code{seed48} it
1941 initializes all 48 bits of the state from the parameter @var{seed16v}.
1942
1943 If the return value is non-negative the function call succeeded.  It
1944 does not return a pointer to the previous state of the random number
1945 generator like the @code{seed48} function does.  if the user wants to
1946 preserve the state for a later rerun s/he can copy the whole buffer
1947 pointed to by @var{buffer}.
1948
1949 This function is a GNU extension and should not be used in portable
1950 programs.
1951 @end deftypefun
1952
1953 @comment stdlib.h
1954 @comment GNU
1955 @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
1956 This function initializes all aspects of the random number generator
1957 described in @var{buffer} by the data in @var{param}.  Here it is
1958 especially true the function does more than just copying the contents of
1959 @var{param} of @var{buffer}.  Some more actions are required and
1960 therefore it is important to use this function and not initialized the
1961 random number generator directly.
1962
1963 If the return value is non-negative the function call succeeded.
1964
1965 This function is a GNU extension and should not be used in portable
1966 programs.
1967 @end deftypefun