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