Explain the use of the optimizing inline functions.
[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 @comment complex.h
1263 @comment ISO
1264 @deftypefun {complex double} csqrt (complex double @var{z})
1265 @deftypefunx {complex float} csqrtf (complex float @var{z})
1266 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
1267 These functions return the complex root of the argument @var{z}.  Unlike
1268 the @code{sqrt} function these functions do not have any restriction on
1269 the value of the argument.
1270 @end deftypefun
1271
1272 @comment complex.h
1273 @comment ISO
1274 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
1275 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
1276 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
1277 These functions return the complex value @var{BASE} raised to the power of
1278 @var{power}.  This is computed as
1279
1280 @ifinfo
1281 @math{cpow (x, y) = cexp (y * clog (x))}
1282 @end ifinfo
1283 @iftex
1284 @tex
1285 $${\rm cpow}(x, y) = e^{y \log(x)}$$
1286 @end tex
1287 @end iftex
1288 @end deftypefun
1289
1290
1291 @node Hyperbolic Functions
1292 @section Hyperbolic Functions
1293 @cindex hyperbolic functions
1294
1295 The functions in this section are related to the exponential functions;
1296 see @ref{Exponents and Logarithms}.
1297
1298 @comment math.h
1299 @comment ISO
1300 @deftypefun double sinh (double @var{x})
1301 @deftypefunx float sinhf (float @var{x})
1302 @deftypefunx {long double} sinhl (long double @var{x})
1303 These functions return the hyperbolic sine of @var{x}, defined
1304 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  The
1305 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1306 @var{x} is too large; that is, if overflow occurs.
1307 @end deftypefun
1308
1309 @comment math.h
1310 @comment ISO
1311 @deftypefun double cosh (double @var{x})
1312 @deftypefunx float coshf (float @var{x})
1313 @deftypefunx {long double} coshl (long double @var{x})
1314 These function return the hyperbolic cosine of @var{x},
1315 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
1316 The function fails, and sets @code{errno} to @code{ERANGE}, if the value
1317 of @var{x} is too large; that is, if overflow occurs.
1318 @end deftypefun
1319
1320 @comment math.h
1321 @comment ISO
1322 @deftypefun double tanh (double @var{x})
1323 @deftypefunx float tanhf (float @var{x})
1324 @deftypefunx {long double} tanhl (long double @var{x})
1325 These functions return the hyperbolic tangent of @var{x}, whose
1326 mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
1327 @end deftypefun
1328
1329 @cindex hyperbolic functions
1330
1331 There are counterparts for these hyperbolic functions which work with
1332 complex valued arguments.  They should always be used instead of the
1333 obvious mathematical formula since the implementations in the math
1334 library are optimized for accuracy and speed.
1335
1336 @comment complex.h
1337 @comment ISO
1338 @deftypefun {complex double} csinh (complex double @var{z})
1339 @deftypefunx {complex float} csinhf (complex float @var{z})
1340 @deftypefunx {complex long double} csinhl (complex long double @var{z})
1341 These functions return the complex hyperbolic sine of @var{z}, defined
1342 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.  The
1343 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1344 result is too large.
1345 @end deftypefun
1346
1347 @comment complex.h
1348 @comment ISO
1349 @deftypefun {complex double} ccosh (complex double @var{z})
1350 @deftypefunx {complex float} ccoshf (complex float @var{z})
1351 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
1352 These functions return the complex hyperbolic cosine of @var{z}, defined
1353 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.  The
1354 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1355 result is too large.
1356 @end deftypefun
1357
1358 @comment complex.h
1359 @comment ISO
1360 @deftypefun {complex double} ctanh (complex double @var{z})
1361 @deftypefunx {complex float} ctanhf (complex float @var{z})
1362 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
1363 These functions return the complex hyperbolic tangent of @var{z}, whose
1364 mathematical definition is @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
1365 @end deftypefun
1366
1367
1368 @cindex inverse hyperbolic functions
1369
1370 @comment math.h
1371 @comment ISO
1372 @deftypefun double asinh (double @var{x})
1373 @deftypefunx float asinhf (float @var{x})
1374 @deftypefunx {long double} asinhl (long double @var{x})
1375 These functions return the inverse hyperbolic sine of @var{x}---the
1376 value whose hyperbolic sine is @var{x}.
1377 @end deftypefun
1378
1379 @comment math.h
1380 @comment ISO
1381 @deftypefun double acosh (double @var{x})
1382 @deftypefunx float acoshf (float @var{x})
1383 @deftypefunx {long double} acoshl (long double @var{x})
1384 These functions return the inverse hyperbolic cosine of @var{x}---the
1385 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
1386 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
1387 @end deftypefun
1388
1389 @comment math.h
1390 @comment ISO
1391 @deftypefun double atanh (double @var{x})
1392 @deftypefunx float atanhf (float @var{x})
1393 @deftypefunx {long double} atanhl (long double @var{x})
1394 These functions return the inverse hyperbolic tangent of @var{x}---the
1395 value whose hyperbolic tangent is @var{x}.  If the absolute value of
1396 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
1397 @code{HUGE_VAL}.
1398 @end deftypefun
1399
1400 @cindex inverse complex hyperbolic functions
1401
1402 @comment complex.h
1403 @comment ISO
1404 @deftypefun {complex double} casinh (complex double @var{z})
1405 @deftypefunx {complex float} casinhf (complex float @var{z})
1406 @deftypefunx {complex long double} casinhl (complex long double @var{z})
1407 These functions return the inverse complex hyperbolic sine of
1408 @var{z}---the value whose complex hyperbolic sine is @var{z}.
1409 @end deftypefun
1410
1411 @comment complex.h
1412 @comment ISO
1413 @deftypefun {complex double} cacosh (complex double @var{z})
1414 @deftypefunx {complex float} cacoshf (complex float @var{z})
1415 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
1416 These functions return the inverse complex hyperbolic cosine of
1417 @var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
1418 the real valued function @code{acosh} there is not limit for the range
1419 of the argument.
1420 @end deftypefun
1421
1422 @comment complex.h
1423 @comment ISO
1424 @deftypefun {complex double} catanh (complex double @var{z})
1425 @deftypefunx {complex float} catanhf (complex float @var{z})
1426 @deftypefunx {complex long double} catanhl (complex long double @var{z})
1427 These functions return the inverse complex hyperbolic tangent of
1428 @var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
1429 the real valued function @code{atanh} there is not limit for the range
1430 of the argument.
1431 @end deftypefun
1432
1433
1434 @node Pseudo-Random Numbers
1435 @section Pseudo-Random Numbers
1436 @cindex random numbers
1437 @cindex pseudo-random numbers
1438 @cindex seed (for random numbers)
1439
1440 This section describes the GNU facilities for generating a series of
1441 pseudo-random numbers.  The numbers generated are not truly random;
1442 typically, they form a sequence that repeats periodically, with a
1443 period so large that you can ignore it for ordinary purposes.  The
1444 random number generator works by remembering at all times a @dfn{seed}
1445 value which it uses to compute the next random number and also to
1446 compute a new seed.
1447
1448 Although the generated numbers look unpredictable within one run of a
1449 program, the sequence of numbers is @emph{exactly the same} from one run
1450 to the next.  This is because the initial seed is always the same.  This
1451 is convenient when you are debugging a program, but it is unhelpful if
1452 you want the program to behave unpredictably.  If you want truly random
1453 numbers, not just pseudo-random, specify a seed based on the current
1454 time.
1455
1456 You can get repeatable sequences of numbers on a particular machine type
1457 by specifying the same initial seed value for the random number
1458 generator.  There is no standard meaning for a particular seed value;
1459 the same seed, used in different C libraries or on different CPU types,
1460 will give you different random numbers.
1461
1462 The GNU library supports the standard @w{ISO C} random number functions
1463 plus two other sets derived from BSD and SVID.  We recommend you use the
1464 standard ones, @code{rand} and @code{srand} if only a small number of
1465 random bits are required.  The SVID functions provide an interface which
1466 allows better randon number generator algorithms and they return up to
1467 48 random bits in one calls and they also return random floating-point
1468 numbers if wanted.  The SVID function might not be available on some BSD
1469 derived systems but since they are required in the XPG they are
1470 available on all Unix-conformant systems.
1471
1472 @menu
1473 * ISO Random::       @code{rand} and friends.
1474 * BSD Random::       @code{random} and friends.
1475 * SVID Random::      @code{drand48} and friends.
1476 @end menu
1477
1478 @node ISO Random
1479 @subsection ISO C Random Number Functions
1480
1481 This section describes the random number functions that are part of
1482 the @w{ISO C} standard.
1483
1484 To use these facilities, you should include the header file
1485 @file{stdlib.h} in your program.
1486 @pindex stdlib.h
1487
1488 @comment stdlib.h
1489 @comment ISO
1490 @deftypevr Macro int RAND_MAX
1491 The value of this macro is an integer constant expression that
1492 represents the maximum possible value returned by the @code{rand}
1493 function.  In the GNU library, it is @code{037777777}, which is the
1494 largest signed integer representable in 32 bits.  In other libraries, it
1495 may be as low as @code{32767}.
1496 @end deftypevr
1497
1498 @comment stdlib.h
1499 @comment ISO
1500 @deftypefun int rand (void)
1501 The @code{rand} function returns the next pseudo-random number in the
1502 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
1503 @end deftypefun
1504
1505 @comment stdlib.h
1506 @comment ISO
1507 @deftypefun void srand (unsigned int @var{seed})
1508 This function establishes @var{seed} as the seed for a new series of
1509 pseudo-random numbers.  If you call @code{rand} before a seed has been
1510 established with @code{srand}, it uses the value @code{1} as a default
1511 seed.
1512
1513 To produce truly random numbers (not just pseudo-random), do @code{srand
1514 (time (0))}.
1515 @end deftypefun
1516
1517 A completely broken interface was designed by the POSIX.1 committee to
1518 support reproducible random numbers in multi-threaded programs.
1519
1520 @comment stdlib.h
1521 @comment POSIX.1
1522 @deftypefun int rand_r (unsigned int *@var{seed})
1523 This function returns a random number in the range 0 to @code{RAND_MAX}
1524 just as @code{rand} does.  But this function does not keep an internal
1525 state for the RNG.  Instead the @code{unsigned int} variable pointed to
1526 by the argument @var{seed} is the only state.  Before the value is
1527 returned the state will be updated so that the next call will return a
1528 new number.
1529
1530 I.e., the state of the RNG can only have as much bits as the type
1531 @code{unsigned int} has.  This is far too few to provide a good RNG.
1532 This interface is broken by design.
1533
1534 If the program requires reproducible random numbers in multi-threaded
1535 programs the reentrant SVID functions are probably a better choice.  But
1536 these functions are GNU extensions and therefore @code{rand_r}, as being
1537 standardized in POSIX.1, should always be kept as a default method.
1538 @end deftypefun
1539
1540
1541 @node BSD Random
1542 @subsection BSD Random Number Functions
1543
1544 This section describes a set of random number generation functions that
1545 are derived from BSD.  There is no advantage to using these functions
1546 with the GNU C library; we support them for BSD compatibility only.
1547
1548 The prototypes for these functions are in @file{stdlib.h}.
1549 @pindex stdlib.h
1550
1551 @comment stdlib.h
1552 @comment BSD
1553 @deftypefun {int32_t} random (void)
1554 This function returns the next pseudo-random number in the sequence.
1555 The range of values returned is from @code{0} to @code{RAND_MAX}.
1556
1557 @strong{Please note:} Historically this function returned a @code{long
1558 int} value.  But with the appearence of 64bit machines this could lead
1559 to severe compatibility problems and therefore the type now explicitly
1560 limits the return value to 32bit.
1561 @end deftypefun
1562
1563 @comment stdlib.h
1564 @comment BSD
1565 @deftypefun void srandom (unsigned int @var{seed})
1566 The @code{srandom} function sets the seed for the current random number
1567 state based on the integer @var{seed}.  If you supply a @var{seed} value
1568 of @code{1}, this will cause @code{random} to reproduce the default set
1569 of random numbers.
1570
1571 To produce truly random numbers (not just pseudo-random), do
1572 @code{srandom (time (0))}.
1573 @end deftypefun
1574
1575 @comment stdlib.h
1576 @comment BSD
1577 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1578 The @code{initstate} function is used to initialize the random number
1579 generator state.  The argument @var{state} is an array of @var{size}
1580 bytes, used to hold the state information.  The size must be at least 8
1581 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
1582 the @var{state} array, the better.
1583
1584 The return value is the previous value of the state information array.
1585 You can use this value later as an argument to @code{setstate} to
1586 restore that state.
1587 @end deftypefun
1588
1589 @comment stdlib.h
1590 @comment BSD
1591 @deftypefun {void *} setstate (void *@var{state})
1592 The @code{setstate} function restores the random number state
1593 information @var{state}.  The argument must have been the result of
1594 a previous call to @var{initstate} or @var{setstate}.
1595
1596 The return value is the previous value of the state information array.
1597 You can use thise value later as an argument to @code{setstate} to
1598 restore that state.
1599 @end deftypefun
1600
1601
1602 @node SVID Random
1603 @subsection SVID Random Number Function
1604
1605 The C library on SVID systems contains yet another kind of random number
1606 generator functions.  They use a state of 48 bits of data.  The user can
1607 choose among a collection of functions which all return the random bits
1608 in different forms.
1609
1610 Generally there are two kinds of functions: those which use a state of
1611 the random number generator which is shared among several functions and
1612 by all threads of the process.  The second group of functions require
1613 the user to handle the state.
1614
1615 All functions have in common that they use the same congruential
1616 formula with the same constants.  The formula is
1617
1618 @smallexample
1619 Y = (a * X + c) mod m
1620 @end smallexample
1621
1622 @noindent
1623 where @var{X} is the state of the generator at the beginning and
1624 @var{Y} the state at the end.  @code{a} and @code{c} are constants
1625 determining the way the generator work.  By default they are
1626
1627 @smallexample
1628 a = 0x5DEECE66D = 25214903917
1629 c = 0xb = 11
1630 @end smallexample
1631
1632 @noindent
1633 but they can also be changed by the user.  @code{m} is of course 2^48
1634 since the state consists of a 48 bit array.
1635
1636
1637 @comment stdlib.h
1638 @comment SVID
1639 @deftypefun double drand48 (void)
1640 This function returns a @code{double} value in the range of @code{0.0}
1641 to @code{1.0} (exclusive).  The random bits are determined by the global
1642 state of the random number generator in the C library.
1643
1644 Since the @code{double} type according to @w{IEEE 754} has a 52 bit
1645 mantissa this means 4 bits are not initialized by the random number
1646 generator.  These are (of course) chosen to be the least significant
1647 bits and they are initialized to @code{0}.
1648 @end deftypefun
1649
1650 @comment stdlib.h
1651 @comment SVID
1652 @deftypefun double erand48 (unsigned short int @var{xsubi}[3])
1653 This function returns a @code{double} value in the range of @code{0.0}
1654 to @code{1.0} (exclusive), similar to @code{drand48}.  The argument is
1655 an array describing the state of the random number generator.
1656
1657 This function can be called subsequently since it updates the array to
1658 guarantee random numbers.  The array should have been initialized before
1659 using to get reproducible results.
1660 @end deftypefun
1661
1662 @comment stdlib.h
1663 @comment SVID
1664 @deftypefun {long int} lrand48 (void)
1665 The @code{lrand48} functions return an integer value in the range of
1666 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
1667 int} type can take more than 32 bits no higher numbers are returned.
1668 The random bits are determined by the global state of the random number
1669 generator in the C library.
1670 @end deftypefun
1671
1672 @comment stdlib.h
1673 @comment SVID
1674 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
1675 This function is similar to the @code{lrand48} function in that it
1676 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1677 the state of the random number generator used to produce the random bits
1678 is determined by the array provided as the parameter to the function.
1679
1680 The numbers in the array are afterwards updated so that subsequent calls
1681 to this function yield to different results (as it is expected by a
1682 random number generator).  The array should have been initialized before
1683 the first call to get reproducible results.
1684 @end deftypefun
1685
1686 @comment stdlib.h
1687 @comment SVID
1688 @deftypefun {long int} mrand48 (void)
1689 The @code{mrand48} function is similar to @code{lrand48}.  The only
1690 difference is that the numbers returned are in the range @code{-2^31} to
1691 @code{2^31} (exclusive).
1692 @end deftypefun
1693
1694 @comment stdlib.h
1695 @comment SVID
1696 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
1697 The @code{jrand48} function is similar to @code{nrand48}.  The only
1698 difference is that the numbers returned are in the range @code{-2^31} to
1699 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
1700 requirements are necessary.
1701 @end deftypefun
1702
1703 The internal state of the random number generator can be initialized in
1704 several ways.  The functions differ in the completeness of the
1705 information provided.
1706
1707 @comment stdlib.h
1708 @comment SVID
1709 @deftypefun void srand48 (long int @var{seedval}))
1710 The @code{srand48} function sets the most significant 32 bits of the
1711 state internal state of the random number generator to the least
1712 significant 32 bits of the @var{seedval} parameter.  The lower 16 bts
1713 are initilialized to the value @code{0x330E}.  Even if the @code{long
1714 int} type contains more the 32 bits only the lower 32 bits are used.
1715
1716 Due to this limitation the initialization of the state using this
1717 function of not very useful.  But it makes it easy to use a constrcut
1718 like @code{srand48 (time (0))}.
1719
1720 A side-effect of this function is that the values @code{a} and @code{c}
1721 from the internal state, which are used in the congruential formula,
1722 are reset to the default values given above.  This is of importance once
1723 the user called the @code{lcong48} function (see below).
1724 @end deftypefun
1725
1726 @comment stdlib.h
1727 @comment SVID
1728 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
1729 The @code{seed48} function initializes all 48 bits of the state of the
1730 internal random number generator from the content of the parameter
1731 @var{seed16v}.  Here the lower 16 bits of the first element of
1732 @var{see16v} initialize the least significant 16 bits of the internal
1733 state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
1734 16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
1735 initialize the most significant 16 bits of the state.
1736
1737 Unlike @code{srand48} this function lets the user initialize all 48 bits
1738 of the state.
1739
1740 The value returned by @code{seed48} is a pointer to an array containing
1741 the values of the internal state before the change.  This might be
1742 useful to restart the random number generator at a certain state.
1743 Otherwise, the value can simply be ignored.
1744
1745 As for @code{srand48}, the values @code{a} and @code{c} from the
1746 congruential formula are reset to the default values.
1747 @end deftypefun
1748
1749 There is one more function to initialize the random number generator
1750 which allows to specify even more information by allowing to change the
1751 parameters in the congruential formula.
1752
1753 @comment stdlib.h
1754 @comment SVID
1755 @deftypefun void lcong48 (unsigned short int @var{param}[7])
1756 The @code{lcong48} function allows the user to change the complete state
1757 of the random number generator.  Unlike @code{srand48} and
1758 @code{seed48}, this function also changes the constants in the
1759 congruential formula.
1760
1761 From the seven elements in the array @var{param} the least significant
1762 16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
1763 determine the the initial state, the least 16 bits of
1764 @code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
1765 constant @code{a} and @code{@var{param}[6]} determines the 16 bit value
1766 @code{c}.
1767 @end deftypefun
1768
1769 All the above functions have in common that they use the global
1770 parameters for the congruential formula.  In multi-threaded programs it
1771 might sometimes be useful to have different parameters in different
1772 threads.  For this reason all the above functions have a counterpart
1773 which works on a description of the random number generator in the
1774 user-supplied buffer instead of the global state.
1775
1776 Please note that it is no problem if several threads use the global
1777 state if all threads use the functions which take a pointer to an array
1778 containing the state.  The random numbers are computed following the
1779 same loop but if the state in the array is different all threads will
1780 get an individuual random number generator.
1781
1782 The user supplied buffer must be of type @code{struct drand48_data}.
1783 This type should be regarded as opaque and no member should be used
1784 directly.
1785
1786 @comment stdlib.h
1787 @comment GNU
1788 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1789 This function is equivalent to the @code{drand48} function with the
1790 difference it does not modify the global random number generator
1791 parameters but instead the parameters is the buffer supplied by the
1792 buffer through the pointer @var{buffer}.  The random number is return in
1793 the variable pointed to by @var{result}.
1794
1795 The return value of the function indicate whether the call succeeded.
1796 If the value is less than @code{0} an error occurred and @var{errno} is
1797 set to indicate the problem.
1798
1799 This function is a GNU extension and should not be used in portable
1800 programs.
1801 @end deftypefun
1802
1803 @comment stdlib.h
1804 @comment GNU
1805 @deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
1806 The @code{erand48_r} function works like the @code{erand48} and it takes
1807 an argument @var{buffer} which describes the random number generator.
1808 The state of the random number genertor is taken from the @code{xsubi}
1809 array, the parameters for the congruential formula from the global
1810 random number generator data.  The random number is return in the
1811 variable pointed to by @var{result}.
1812
1813 The return value is non-negative is the call succeeded.
1814
1815 This function is a GNU extension and should not be used in portable
1816 programs.
1817 @end deftypefun
1818
1819 @comment stdlib.h
1820 @comment GNU
1821 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1822 This function is similar to @code{lrand48} and it takes a pointer to a
1823 buffer describing the state of the random number generator as a
1824 parameter just like @code{drand48}.
1825
1826 If the return value of the function is non-negative the variable pointed
1827 to by @var{result} contains the result.  Otherwise an error occurred.
1828
1829 This function is a GNU extension and should not be used in portable
1830 programs.
1831 @end deftypefun
1832
1833 @comment stdlib.h
1834 @comment GNU
1835 @deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1836 The @code{nrand48_r} function works like @code{nrand48} in that it
1837 produces a random number in range @code{0} to @code{2^31}.  But instead
1838 of using the global parameters for the congruential formula it uses the
1839 information from the buffer pointed to by @var{buffer}.  The state is
1840 described by the values in @var{xsubi}.
1841
1842 If the return value is non-negative the variable pointed to by
1843 @var{result} contains the result.
1844
1845 This function is a GNU extension and should not be used in portable
1846 programs.
1847 @end deftypefun
1848
1849 @comment stdlib.h
1850 @comment GNU
1851 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1852 This function is similar to @code{mrand48} but as the other reentrant
1853 function it uses the random number generator described by the value in
1854 the buffer pointed to by @var{buffer}.
1855
1856 If the return value is non-negative the variable pointed to by
1857 @var{result} contains the result.
1858
1859 This function is a GNU extension and should not be used in portable
1860 programs.
1861 @end deftypefun
1862
1863 @comment stdlib.h
1864 @comment GNU
1865 @deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
1866 The @code{jrand48_r} function is similar to @code{jrand48}.  But as the
1867 other reentrant functions of this function family it uses the
1868 congruential formula parameters from the buffer pointed to by
1869 @var{buffer}.
1870
1871 If the return value is non-negative the variable pointed to by
1872 @var{result} contains the result.
1873
1874 This function is a GNU extension and should not be used in portable
1875 programs.
1876 @end deftypefun
1877
1878 Before any of the above functions should be used the buffer of type
1879 @code{struct drand48_data} should initialized.  The easiest way is to
1880 fill the whole buffer with null bytes, e.g., using
1881
1882 @smallexample
1883 memset (buffer, '\0', sizeof (struct drand48_data));
1884 @end smallexample
1885
1886 @noindent
1887 Using any of the reetrant functions of this family now will
1888 automatically initialize the random number generator to the default
1889 values for the state and the parameters of the congruential formula.
1890
1891 The other possibility is too use any of the functions which explicitely
1892 initialize the buffer.  Though it might be obvious how to initialize the
1893 buffer from the data given as parameter from the function it is highly
1894 recommended to use these functions since the result might not always be
1895 what you expect.
1896
1897 @comment stdlib.h
1898 @comment GNU
1899 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1900 The description of the random number generator represented by the
1901 information in @var{buffer} is initialized similar to what the function
1902 @code{srand48} does.  The state is initialized from the paramter
1903 @var{seedval} and the paameters for the congruential formula are
1904 initialized to the default values.
1905
1906 If the return value is non-negative the function call succeeded.
1907
1908 This function is a GNU extension and should not be used in portable
1909 programs.
1910 @end deftypefun
1911
1912 @comment stdlib.h
1913 @comment GNU
1914 @deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
1915 This function is similar to @code{srand48_r} but like @code{seed48} it
1916 initializes all 48 bits of the state from the parameter @var{seed16v}.
1917
1918 If the return value is non-negative the function call succeeded.  It
1919 does not return a pointer to the previous state of the random number
1920 generator like the @code{seed48} function does.  if the user wants to
1921 preserve the state for a later rerun s/he can copy the whole buffer
1922 pointed to by @var{buffer}.
1923
1924 This function is a GNU extension and should not be used in portable
1925 programs.
1926 @end deftypefun
1927
1928 @comment stdlib.h
1929 @comment GNU
1930 @deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
1931 This function initializes all aspects of the random number generator
1932 described in @var{buffer} by the data in @var{param}.  Here it is
1933 especially true the function does more than just copying the contents of
1934 @var{param} of @var{buffer}.  Some more actions are required and
1935 therefore it is important to use this function and not initialized the
1936 random number generator directly.
1937
1938 If the return value is non-negative the function call succeeded.
1939
1940 This function is a GNU extension and should not be used in portable
1941 programs.
1942 @end deftypefun