2b7cb82f5ecb452312758c10e4b3cf8655eac167
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
24 @node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
25 @chapter Mathematics
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
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.
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.
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.
65 @node Domain and Range Errors
66 @section Domain and Range Errors
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.
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.
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}).
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}.
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.
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.)
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.
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
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.
127 This macro is introduced in @w{ISO C 9X}.
128 @end deftypevr
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.
138 This macro is introduced in @w{ISO C 9X}.
139 @end deftypevr
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.
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}.
153 This macro is introduced in @w{ISO C 9X}.
154 @end deftypevr
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}.
162 This macro is introduced in @w{ISO C 9X}.
163 @end deftypevr
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.
172 @node Exceptions in Math Functions
173 @section Exceptions in Math Functions
174 @cindex exception
175 @cindex signal
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.
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.
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).
196 @noindent
197 The exceptions defined in @w{IEEE 754} are:
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{}}.
214 @item
215 Division: @math{0/0} or @math{@infinity{}/@infinity{}}.
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
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.
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.
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{}}.
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
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.
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.
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
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.
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.
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.
302 @node Status bit operations
303 @subsection Controlling the FPU status word
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.
311 number of macros:
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
336 The macro @code{FE_ALL_EXCEPT} is the bitwise OR of all exception macros
337 which are supported by the FP implementation.
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.
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
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.
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
362 @noindent
363 To restore the previously saved values one can use this function:
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
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.
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
388 @noindent
389 Code which uses the @code{fetestexcept} function could look like this:
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
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.
409 @node FPU environment
410 @subsection Controlling the Floating-Point environment
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.
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:
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
429 @noindent
430 Another possibility which is useful in several situations is
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.
440 If the floating-point implementation does not support such a non-stop
441 mode, the return value is zero.
442 @end deftypefun
444 The functions which allow a state of the floating-point unit to be
445 restored can take two kinds of arguments:
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_}.
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}.
463 Some platforms might define further predefined environments.
464 @end itemize
466 @noindent
467 To set any of the environments there are two functions defined.
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
475 In some situations the previous status of the exception flags must not
476 simply be discarded and so this function is useful:
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
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.
491 @node Rounding Modes
492 @subsection Rounding modes of the Floating-Point Unit
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:
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.
507 @comment fenv.h
508 @comment ISO
509 @vindex FE_UPWARD
510 @item FE_UPWARD
511 Round toward @math{+@infinity{}}.
513 @comment fenv.h
514 @comment ISO
515 @vindex FE_DOWNWARD
516 @item FE_DOWNWARD
517 Round toward @math{-@infinity{}}.
519 @comment fenv.h
520 @comment ISO
521 @vindex FE_TOWARDZERO
522 @item FE_TOWARDZERO
523 Round toward zero.
524 @end table
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:
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
536 @noindent
537 To set a specific rounding mode the next function can be used.
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.
546 The function returns a nonzero value iff the requested rounding mode can
547 be established.  Otherwise zero is returned.
548 @end deftypefun
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.
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.
564 @node Mathematical Constants
565 @section Predefined Mathematical Constants
566 @cindex constants
567 @cindex mathematical constants
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:
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
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}.
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
619 @code{-DPI=M_PI}.
622 @node FP Comparison Functions
623 @section Floating-Point Comparison Functions
624 @cindex unordered comparison
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
630 @smallexample
631 int v = a < 1.0;
632 @end smallexample
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.
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.
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
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
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
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
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
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
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.
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.
701 @strong{Note:} There are no macros @code{isequal} or @code{isunequal}.
702 These macros are not necessary since the @w{IEEE 754} standard requires
703 that the comparison for equality and unequality do @emph{not} throw an
704 exception if one of the arguments is an unordered value.
707 @node Trig Functions
708 @section Trigonometric Functions
709 @cindex trigonometric functions
711 These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
712 The arguments to all of these functions are in units of radians; recall
713 that pi radians equals 180 degrees.
715 @cindex pi (trigonometric constant)
716 The math library does define a symbolic constant for pi in @file{math.h}
717 (@pxref{Mathematical Constants}) when BSD compliance is required
718 (@pxref{Feature Test Macros}).  In case it is not possible to use this
719 predefined macro one easily can define it:
721 @smallexample
722 #define M_PI 3.14159265358979323846264338327
723 @end smallexample
725 @noindent
726 You can also compute the value of pi with the expression @code{acos
727 (-1.0)}.
730 @comment math.h
731 @comment ISO
732 @deftypefun double sin (double @var{x})
733 @deftypefunx float sinf (float @var{x})
734 @deftypefunx {long double} sinl (long double @var{x})
735 These functions return the sine of @var{x}, where @var{x} is given in
736 radians.  The return value is in the range @code{-1} to @code{1}.
737 @end deftypefun
739 @comment math.h
740 @comment ISO
741 @deftypefun double cos (double @var{x})
742 @deftypefunx float cosf (float @var{x})
743 @deftypefunx {long double} cosl (long double @var{x})
744 These functions return the cosine of @var{x}, where @var{x} is given in
745 radians.  The return value is in the range @code{-1} to @code{1}.
746 @end deftypefun
748 @comment math.h
749 @comment ISO
750 @deftypefun double tan (double @var{x})
751 @deftypefunx float tanf (float @var{x})
752 @deftypefunx {long double} tanl (long double @var{x})
753 These functions return the tangent of @var{x}, where @var{x} is given in
756 The following @code{errno} error conditions are defined for this function:
758 @table @code
759 @item ERANGE
760 Mathematically, the tangent function has singularities at odd multiples
761 of pi/2.  If the argument @var{x} is too close to one of these
762 singularities, @code{tan} sets @code{errno} to @code{ERANGE} and returns
763 either positive or negative @code{HUGE_VAL}.
764 @end table
765 @end deftypefun
767 In many applications where @code{sin} and @code{cos} are used, the value
768 for the same argument of both of these functions is used at the same
769 time.  Since the algorithm to compute these values is very similar for
770 both functions there is an additional function which computes both values
771 at the same time.
773 @comment math.h
774 @comment GNU
775 @deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
776 @deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
777 @deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
778 These functions return the sine of @var{x} in @code{*@var{sinx}} and the
779 cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
780 radians.  Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
781 the range of @code{-1} to @code{1}.
783 This function is a GNU extension.  It should be used whenever both sine
784 and cosine are needed but in protable applications there should be a
785 fallback method for systems without this function.
786 @end deftypefun
788 @cindex complex trigonometric functions
790 The trigonometric functions are in mathematics not only defined on real
791 numbers.  They can be extended to complex numbers and the @w{ISO C 9X}
792 standard introduces these variants in the standard math library.
794 @comment complex.h
795 @comment ISO
796 @deftypefun {complex double} csin (complex double @var{z})
797 @deftypefunx {complex float} csinf (complex float @var{z})
798 @deftypefunx {complex long double} csinl (complex long double @var{z})
799 These functions return the complex sine of the complex value in @var{z}.
800 The mathematical definition of the complex sine is
802 @ifinfo
803 @math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
804 @end ifinfo
805 @iftex
806 @tex
807 $$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
808 @end tex
809 @end iftex
810 @end deftypefun
812 @comment complex.h
813 @comment ISO
814 @deftypefun {complex double} ccos (complex double @var{z})
815 @deftypefunx {complex float} ccosf (complex float @var{z})
816 @deftypefunx {complex long double} ccosl (complex long double @var{z})
817 These functions return the complex cosine of the complex value in @var{z}.
818 The mathematical definition of the complex cosine is
820 @ifinfo
821 @math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
822 @end ifinfo
823 @iftex
824 @tex
825 $$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
826 @end tex
827 @end iftex
828 @end deftypefun
830 @comment complex.h
831 @comment ISO
832 @deftypefun {complex double} ctan (complex double @var{z})
833 @deftypefunx {complex float} ctanf (complex float @var{z})
834 @deftypefunx {complex long double} ctanl (complex long double @var{z})
835 These functions return the complex tangent of the complex value in @var{z}.
836 The mathematical definition of the complex tangent is
838 @ifinfo
839 @math{tan (z) = 1/i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
840 @end ifinfo
841 @iftex
842 @tex
843 $$\tan(z) = {1\over i} {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
844 @end tex
845 @end iftex
846 @end deftypefun
849 @node Inverse Trig Functions
850 @section Inverse Trigonometric Functions
851 @cindex inverse trigonometric functions
853 These are the usual arc sine, arc cosine and arc tangent functions,
854 which are the inverses of the sine, cosine and tangent functions,
855 respectively.
857 @comment math.h
858 @comment ISO
859 @deftypefun double asin (double @var{x})
860 @deftypefunx float asinf (float @var{x})
861 @deftypefunx {long double} asinl (long double @var{x})
862 These functions compute the arc sine of @var{x}---that is, the value whose
863 sine is @var{x}.  The value is in units of radians.  Mathematically,
864 there are infinitely many such values; the one actually returned is the
865 one between @code{-pi/2} and @code{pi/2} (inclusive).
867 @code{asin} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
868 out of range.  The arc sine function is defined mathematically only
869 over the domain @code{-1} to @code{1}.
870 @end deftypefun
872 @comment math.h
873 @comment ISO
874 @deftypefun double acos (double @var{x})
875 @deftypefunx float acosf (float @var{x})
876 @deftypefunx {long double} acosl (long double @var{x})
877 These functions compute the arc cosine of @var{x}---that is, the value
878 whose cosine is @var{x}.  The value is in units of radians.
879 Mathematically, there are infinitely many such values; the one actually
880 returned is the one between @code{0} and @code{pi} (inclusive).
882 @code{acos} fails, and sets @code{errno} to @code{EDOM}, if @var{x} is
883 out of range.  The arc cosine function is defined mathematically only
884 over the domain @code{-1} to @code{1}.
885 @end deftypefun
888 @comment math.h
889 @comment ISO
890 @deftypefun double atan (double @var{x})
891 @deftypefunx float atanf (float @var{x})
892 @deftypefunx {long double} atanl (long double @var{x})
893 These functions compute the arc tangent of @var{x}---that is, the value
894 whose tangent is @var{x}.  The value is in units of radians.
895 Mathematically, there are infinitely many such values; the one actually
896 returned is the one between @code{-pi/2} and @code{pi/2}
897 (inclusive).
898 @end deftypefun
900 @comment math.h
901 @comment ISO
902 @deftypefun double atan2 (double @var{y}, double @var{x})
903 @deftypefunx float atan2f (float @var{y}, float @var{x})
904 @deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
905 This is the two argument arc tangent function.  It is similar to computing
906 the arc tangent of @var{y}/@var{x}, except that the signs of both arguments
907 are used to determine the quadrant of the result, and @var{x} is
908 permitted to be zero.  The return value is given in radians and is in
909 the range @code{-pi} to @code{pi}, inclusive.
911 If @var{x} and @var{y} are coordinates of a point in the plane,
912 @code{atan2} returns the signed angle between the line from the origin
913 to that point and the x-axis.  Thus, @code{atan2} is useful for
914 converting Cartesian coordinates to polar coordinates.  (To compute the
915 radial coordinate, use @code{hypot}; see @ref{Exponents and
916 Logarithms}.)
918 The function @code{atan2} sets @code{errno} to @code{EDOM} if both
919 @var{x} and @var{y} are zero; the return value is not defined in this
920 case.
921 @end deftypefun
923 @cindex inverse complex trigonometric functions
925 The inverse trigonometric functions also exist is separate versions
926 which are usable with complex numbers.
928 @comment complex.h
929 @comment ISO
930 @deftypefun {complex double} casin (complex double @var{z})
931 @deftypefunx {complex float} casinf (complex float @var{z})
932 @deftypefunx {complex long double} casinl (complex long double @var{z})
933 These functions compute the complex arc sine of @var{z}---that is, the
934 value whose sine is @var{z}.  The value is in units of radians.
936 Unlike the real version of the arc sine function @code{casin} has no
937 limitation on the argument @var{z}.
938 @end deftypefun
940 @comment complex.h
941 @comment ISO
942 @deftypefun {complex double} cacos (complex double @var{z})
943 @deftypefunx {complex float} cacosf (complex float @var{z})
944 @deftypefunx {complex long double} cacosl (complex long double @var{z})
945 These functions compute the complex arc cosine of @var{z}---that is, the
946 value whose cosine is @var{z}.  The value is in units of radians.
948 Unlike the real version of the arc cosine function @code{cacos} has no
949 limitation on the argument @var{z}.
950 @end deftypefun
953 @comment complex.h
954 @comment ISO
955 @deftypefun {complex double} catan (complex double @var{z})
956 @deftypefunx {complex float} catanf (complex float @var{z})
957 @deftypefunx {complex long double} catanl (complex long double @var{z})
958 These functions compute the complex arc tangent of @var{z}---that is,
959 the value whose tangent is @var{z}.  The value is in units of radians.
960 @end deftypefun
963 @node Exponents and Logarithms
964 @section Exponentiation and Logarithms
965 @cindex exponentiation functions
966 @cindex power functions
967 @cindex logarithm functions
969 @comment math.h
970 @comment ISO
971 @deftypefun double exp (double @var{x})
972 @deftypefunx float expf (float @var{x})
973 @deftypefunx {long double} expl (long double @var{x})
974 These functions return the value of @code{e} (the base of natural
975 logarithms) raised to power @var{x}.
977 The function fails, and sets @code{errno} to @code{ERANGE}, if the
978 magnitude of the result is too large to be representable.
979 @end deftypefun
981 @comment math.h
982 @comment ISO
983 @deftypefun double exp10 (double @var{x})
984 @deftypefunx float exp10f (float @var{x})
985 @deftypefunx {long double} exp10l (long double @var{x})
986 These functions return the value of @code{10} raised to the power @var{x}.
987 Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
989 The function fails, and sets @code{errno} to @code{ERANGE}, if the
990 magnitude of the result is too large to be representable.
991 @end deftypefun
993 @comment math.h
994 @comment ISO
995 @deftypefun double exp2 (double @var{x})
996 @deftypefunx float exp2f (float @var{x})
997 @deftypefunx {long double} exp2l (long double @var{x})
998 These functions return the value of @code{2} raised to the power @var{x}.
999 Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
1001 The function fails, and sets @code{errno} to @code{ERANGE}, if the
1002 magnitude of the result is too large to be representable.
1003 @end deftypefun
1006 @comment math.h
1007 @comment ISO
1008 @deftypefun double log (double @var{x})
1009 @deftypefunx float logf (floatdouble @var{x})
1010 @deftypefunx {long double} logl (long double @var{x})
1011 These functions return the natural logarithm of @var{x}.  @code{exp (log
1012 (@var{x}))} equals @var{x}, exactly in mathematics and approximately in
1013 C.
1015 The following @code{errno} error conditions are defined for this function:
1017 @table @code
1018 @item EDOM
1019 The argument @var{x} is negative.  The log function is defined
1020 mathematically to return a real result only on positive arguments.
1022 @item ERANGE
1023 The argument is zero.  The log of zero is not defined.
1024 @end table
1025 @end deftypefun
1027 @comment math.h
1028 @comment ISO
1029 @deftypefun double log10 (double @var{x})
1030 @deftypefunx float log10f (float @var{x})
1031 @deftypefunx {long double} log10l (long double @var{x})
1032 These functions return the base-10 logarithm of @var{x}.  Except for the
1033 different base, it is similar to the @code{log} function.  In fact,
1034 @code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
1035 @end deftypefun
1037 @comment math.h
1038 @comment ISO
1039 @deftypefun double log2 (double @var{x})
1040 @deftypefunx float log2f (float @var{x})
1041 @deftypefunx {long double} log2l (long double @var{x})
1042 These functions return the base-2 logarithm of @var{x}.  Except for the
1043 different base, it is similar to the @code{log} function.  In fact,
1044 @code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
1045 @end deftypefun
1047 @comment math.h
1048 @comment ISO
1049 @deftypefun double logb (double @var{x})
1050 @deftypefunx float logbf (float @var{x})
1051 @deftypefunx {long double} logbl (long double @var{x})
1052 These functions extract the exponent of @var{x} and return it as a
1053 signed integer value.  If @var{x} is zero, a range error may occur.
1055 A special case are subnormal numbers (if supported by the floating-point
1056 format).  The exponent returned is not the actual value from @var{x}.
1057 Instead the number is first normalized as if the range of the exponent
1058 field is large enough.
1059 @end deftypefun
1061 @comment math.h
1062 @comment ISO
1063 @deftypefun int ilogb (double @var{x})
1064 @deftypefunx int ilogbf (float @var{x})
1065 @deftypefunx int ilogbl (long double @var{x})
1066 These functions are equivalent to the corresponding @code{logb}
1067 functions except that the values are returned as signed integer values.
1068 Since integer values cannot represent infinity and NaN, there are some
1069 special symbols defined to help detect these situations.
1071 @vindex FP_ILOGB0
1072 @vindex FP_ILOGBNAN
1073 @code{ilogb} returns @code{FP_ILOGB0} if @var{x} is @code{0} and it
1074 returns @code{FP_ILOGBNAN} if @var{x} is @code{NaN}.  These values are
1075 system specific and no fixed value is assigned.  More concrete, these
1076 values might even have the same value.  So a piece of code handling the
1077 result of @code{ilogb} could look like this:
1079 @smallexample
1080 i = ilogb (f);
1081 if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
1082   @{
1083     if (isnan (f))
1084       @{
1085         /* @r{Handle NaN.}  */
1086       @}
1087     else if (f  == 0.0)
1088       @{
1089         /* @r{Handle 0.0.}  */
1090       @}
1091     else
1092       @{
1093         /* @r{Some other value with large exponent,}
1094            @r{perhaps +Inf.}  */
1095       @}
1096   @}
1097 @end smallexample
1099 @end deftypefun
1101 @comment math.h
1102 @comment ISO
1103 @deftypefun double pow (double @var{base}, double @var{power})
1104 @deftypefunx float powf (float @var{base}, float @var{power})
1105 @deftypefunx {long double} powl (long double @var{base}, long double @var{power})
1106 These are general exponentiation functions, returning @var{base} raised
1107 to @var{power}.
1109 @need 250
1110 The following @code{errno} error conditions are defined for this function:
1112 @table @code
1113 @item EDOM
1114 The argument @var{base} is negative and @var{power} is not an integral
1115 value.  Mathematically, the result would be a complex number in this case.
1117 @item ERANGE
1118 An underflow or overflow condition was detected in the result.
1119 @end table
1120 @end deftypefun
1122 @cindex square root function
1123 @comment math.h
1124 @comment ISO
1125 @deftypefun double sqrt (double @var{x})
1126 @deftypefunx float sqrtf (float @var{x})
1127 @deftypefunx {long double} sqrtl (long double @var{x})
1128 These functions return the nonnegative square root of @var{x}.
1130 The @code{sqrt} function fails, and sets @code{errno} to @code{EDOM}, if
1131 @var{x} is negative.  Mathematically, the square root would be a complex
1132 number.
1133 @c (@pxref{csqrt})
1134 @end deftypefun
1136 @cindex cube root function
1137 @comment math.h
1138 @comment BSD
1139 @deftypefun double cbrt (double @var{x})
1140 @deftypefunx float cbrtf (float @var{x})
1141 @deftypefunx {long double} cbrtl (long double @var{x})
1142 These functions return the cube root of @var{x}.  They cannot
1143 fail; every representable real value has a representable real cube root.
1144 @end deftypefun
1146 @comment math.h
1147 @comment ISO
1148 @deftypefun double hypot (double @var{x}, double @var{y})
1149 @deftypefunx float hypotf (float @var{x}, float @var{y})
1150 @deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
1151 These functions return @code{sqrt (@var{x}*@var{x} +
1152 @var{y}*@var{y})}.  (This is the length of the hypotenuse of a right
1153 triangle with sides of length @var{x} and @var{y}, or the distance
1154 of the point (@var{x}, @var{y}) from the origin.)  Using this function
1155 instead of the direct formula is highly appreciated since the error is
1156 much smaller.  See also the function @code{cabs} in @ref{Absolute Value}.
1157 @end deftypefun
1159 @comment math.h
1160 @comment ISO
1161 @deftypefun double expm1 (double @var{x})
1162 @deftypefunx float expm1f (float @var{x})
1163 @deftypefunx {long double} expm1l (long double @var{x})
1164 These functions return a value equivalent to @code{exp (@var{x}) - 1}.
1165 It is computed in a way that is accurate even if the value of @var{x} is
1166 near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
1167 to subtraction of two numbers that are nearly equal.
1168 @end deftypefun
1170 @comment math.h
1171 @comment ISO
1172 @deftypefun double log1p (double @var{x})
1173 @deftypefunx float log1pf (float @var{x})
1174 @deftypefunx {long double} log1pl (long double @var{x})
1175 This function returns a value equivalent to @w{@code{log (1 + @var{x})}}.
1176 It is computed in a way that is accurate even if the value of @var{x} is
1177 near zero.
1178 @end deftypefun
1180 @cindex complex exponentiation functions
1181 @cindex complex logarithm functions
1183 @w{ISO C 9X} defines variants of some of the exponentiation and
1184 logarithm functions.  As for the other functions handlung complex
1185 numbers these functions are perhaps better optimized and provide better
1186 error checking than a direct use of the formulas of the mathematical
1187 definition.
1189 @comment complex.h
1190 @comment ISO
1191 @deftypefun {complex double} cexp (complex double @var{z})
1192 @deftypefunx {complex float} cexpf (complex float @var{z})
1193 @deftypefunx {complex long double} cexpl (complex long double @var{z})
1194 These functions return the value of @code{e} (the base of natural
1195 logarithms) raised to power of the complex value @var{z}.
1197 @noindent
1198 Mathematically this corresponds to the value
1200 @ifinfo
1201 @math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
1202 @end ifinfo
1203 @iftex
1204 @tex
1205 $$\exp(z) = e^z = e^{{\rm Re} z} (\cos ({\rm Im} z) + i \sin ({\rm Im} z))$$
1206 @end tex
1207 @end iftex
1208 @end deftypefun
1210 @comment complex.h
1211 @comment ISO
1212 @deftypefun {complex double} clog (complex double @var{z})
1213 @deftypefunx {complex float} clogf (complex float @var{z})
1214 @deftypefunx {complex long double} clogl (complex long double @var{z})
1215 These functions return the natural logarithm of the complex value
1216 @var{z}.  Unlike the real value version @code{log} and its variants,
1217 @code{clog} has no limit for the range of its argument @var{z}.
1219 @noindent
1220 Mathematically this corresponds to the value
1222 @ifinfo
1223 @math{log (z) = log (cabs (z)) + I * carg (z)}
1224 @end ifinfo
1225 @iftex
1226 @tex
1227 $$\log(z) = \log(|z|) + i \arg(z)$$
1228 @end tex
1229 @end iftex
1230 @end deftypefun
1232 @comment complex.h
1233 @comment ISO
1234 @deftypefun {complex double} csqrt (complex double @var{z})
1235 @deftypefunx {complex float} csqrtf (complex float @var{z})
1236 @deftypefunx {complex long double} csqrtl (complex long double @var{z})
1237 These functions return the complex root of the argument @var{z}.  Unlike
1238 the @code{sqrt} function these functions do not have any restriction on
1239 the value of the argument.
1240 @end deftypefun
1242 @comment complex.h
1243 @comment ISO
1244 @deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
1245 @deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
1246 @deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
1247 These functions return the complex value @var{BASE} raised to the power of
1248 @var{power}.  This is computed as
1250 @ifinfo
1251 @math{cpow (x, y) = cexp (y * clog (x))}
1252 @end ifinfo
1253 @iftex
1254 @tex
1255 $${\rm cpow}(x, y) = e^{y \log(x)}$$
1256 @end tex
1257 @end iftex
1258 @end deftypefun
1261 @node Hyperbolic Functions
1262 @section Hyperbolic Functions
1263 @cindex hyperbolic functions
1265 The functions in this section are related to the exponential functions;
1266 see @ref{Exponents and Logarithms}.
1268 @comment math.h
1269 @comment ISO
1270 @deftypefun double sinh (double @var{x})
1271 @deftypefunx float sinhf (float @var{x})
1272 @deftypefunx {long double} sinhl (long double @var{x})
1273 These functions return the hyperbolic sine of @var{x}, defined
1274 mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}.  The
1275 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1276 @var{x} is too large; that is, if overflow occurs.
1277 @end deftypefun
1279 @comment math.h
1280 @comment ISO
1281 @deftypefun double cosh (double @var{x})
1282 @deftypefunx float coshf (float @var{x})
1283 @deftypefunx {long double} coshl (long double @var{x})
1284 These function return the hyperbolic cosine of @var{x},
1285 defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
1286 The function fails, and sets @code{errno} to @code{ERANGE}, if the value
1287 of @var{x} is too large; that is, if overflow occurs.
1288 @end deftypefun
1290 @comment math.h
1291 @comment ISO
1292 @deftypefun double tanh (double @var{x})
1293 @deftypefunx float tanhf (float @var{x})
1294 @deftypefunx {long double} tanhl (long double @var{x})
1295 These functions return the hyperbolic tangent of @var{x}, whose
1296 mathematical definition is @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
1297 @end deftypefun
1299 @cindex hyperbolic functions
1301 There are counterparts for these hyperbolic functions which work with
1302 complex valued arguments.  They should always be used instead of the
1303 obvious mathematical formula since the implementations in the math
1304 library are optimized for accuracy and speed.
1306 @comment complex.h
1307 @comment ISO
1308 @deftypefun {complex double} csinh (complex double @var{z})
1309 @deftypefunx {complex float} csinhf (complex float @var{z})
1310 @deftypefunx {complex long double} csinhl (complex long double @var{z})
1311 These functions return the complex hyperbolic sine of @var{z}, defined
1312 mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.  The
1313 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1314 result is too large.
1315 @end deftypefun
1317 @comment complex.h
1318 @comment ISO
1319 @deftypefun {complex double} ccosh (complex double @var{z})
1320 @deftypefunx {complex float} ccoshf (complex float @var{z})
1321 @deftypefunx {complex long double} ccoshl (complex long double @var{z})
1322 These functions return the complex hyperbolic cosine of @var{z}, defined
1323 mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.  The
1324 function fails, and sets @code{errno} to @code{ERANGE}, if the value of
1325 result is too large.
1326 @end deftypefun
1328 @comment complex.h
1329 @comment ISO
1330 @deftypefun {complex double} ctanh (complex double @var{z})
1331 @deftypefunx {complex float} ctanhf (complex float @var{z})
1332 @deftypefunx {complex long double} ctanhl (complex long double @var{z})
1333 These functions return the complex hyperbolic tangent of @var{z}, whose
1334 mathematical definition is @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
1335 @end deftypefun
1338 @cindex inverse hyperbolic functions
1340 @comment math.h
1341 @comment ISO
1342 @deftypefun double asinh (double @var{x})
1343 @deftypefunx float asinhf (float @var{x})
1344 @deftypefunx {long double} asinhl (long double @var{x})
1345 These functions return the inverse hyperbolic sine of @var{x}---the
1346 value whose hyperbolic sine is @var{x}.
1347 @end deftypefun
1349 @comment math.h
1350 @comment ISO
1351 @deftypefun double acosh (double @var{x})
1352 @deftypefunx float acoshf (float @var{x})
1353 @deftypefunx {long double} acoshl (long double @var{x})
1354 These functions return the inverse hyperbolic cosine of @var{x}---the
1355 value whose hyperbolic cosine is @var{x}.  If @var{x} is less than
1356 @code{1}, @code{acosh} returns @code{HUGE_VAL}.
1357 @end deftypefun
1359 @comment math.h
1360 @comment ISO
1361 @deftypefun double atanh (double @var{x})
1362 @deftypefunx float atanhf (float @var{x})
1363 @deftypefunx {long double} atanhl (long double @var{x})
1364 These functions return the inverse hyperbolic tangent of @var{x}---the
1365 value whose hyperbolic tangent is @var{x}.  If the absolute value of
1366 @var{x} is greater than or equal to @code{1}, @code{atanh} returns
1367 @code{HUGE_VAL}.
1368 @end deftypefun
1370 @cindex inverse complex hyperbolic functions
1372 @comment complex.h
1373 @comment ISO
1374 @deftypefun {complex double} casinh (complex double @var{z})
1375 @deftypefunx {complex float} casinhf (complex float @var{z})
1376 @deftypefunx {complex long double} casinhl (complex long double @var{z})
1377 These functions return the inverse complex hyperbolic sine of
1378 @var{z}---the value whose complex hyperbolic sine is @var{z}.
1379 @end deftypefun
1381 @comment complex.h
1382 @comment ISO
1383 @deftypefun {complex double} cacosh (complex double @var{z})
1384 @deftypefunx {complex float} cacoshf (complex float @var{z})
1385 @deftypefunx {complex long double} cacoshl (complex long double @var{z})
1386 These functions return the inverse complex hyperbolic cosine of
1387 @var{z}---the value whose complex hyperbolic cosine is @var{z}.  Unlike
1388 the real valued function @code{acosh} there is not limit for the range
1389 of the argument.
1390 @end deftypefun
1392 @comment complex.h
1393 @comment ISO
1394 @deftypefun {complex double} catanh (complex double @var{z})
1395 @deftypefunx {complex float} catanhf (complex float @var{z})
1396 @deftypefunx {complex long double} catanhl (complex long double @var{z})
1397 These functions return the inverse complex hyperbolic tangent of
1398 @var{z}---the value whose complex hyperbolic tangent is @var{z}.  Unlike
1399 the real valued function @code{atanh} there is not limit for the range
1400 of the argument.
1401 @end deftypefun
1404 @node Pseudo-Random Numbers
1405 @section Pseudo-Random Numbers
1406 @cindex random numbers
1407 @cindex pseudo-random numbers
1408 @cindex seed (for random numbers)
1410 This section describes the GNU facilities for generating a series of
1411 pseudo-random numbers.  The numbers generated are not truly random;
1412 typically, they form a sequence that repeats periodically, with a
1413 period so large that you can ignore it for ordinary purposes.  The
1414 random number generator works by remembering at all times a @dfn{seed}
1415 value which it uses to compute the next random number and also to
1416 compute a new seed.
1418 Although the generated numbers look unpredictable within one run of a
1419 program, the sequence of numbers is @emph{exactly the same} from one run
1420 to the next.  This is because the initial seed is always the same.  This
1421 is convenient when you are debugging a program, but it is unhelpful if
1422 you want the program to behave unpredictably.  If you want truly random
1423 numbers, not just pseudo-random, specify a seed based on the current
1424 time.
1426 You can get repeatable sequences of numbers on a particular machine type
1427 by specifying the same initial seed value for the random number
1428 generator.  There is no standard meaning for a particular seed value;
1429 the same seed, used in different C libraries or on different CPU types,
1430 will give you different random numbers.
1432 The GNU library supports the standard @w{ISO C} random number functions
1433 plus another set derived from BSD.  We recommend you use the standard
1434 ones, @code{rand} and @code{srand}.
1437 * ISO Random::       @code{rand} and friends.
1438 * BSD Random::       @code{random} and friends.
1439 * SVID Random::      @code{drand48} and friends.
1442 @node ISO Random
1443 @subsection ISO C Random Number Functions
1445 This section describes the random number functions that are part of
1446 the @w{ISO C} standard.
1448 To use these facilities, you should include the header file
1449 @file{stdlib.h} in your program.
1450 @pindex stdlib.h
1452 @comment stdlib.h
1453 @comment ISO
1454 @deftypevr Macro int RAND_MAX
1455 The value of this macro is an integer constant expression that
1456 represents the maximum possible value returned by the @code{rand}
1457 function.  In the GNU library, it is @code{037777777}, which is the
1458 largest signed integer representable in 32 bits.  In other libraries, it
1459 may be as low as @code{32767}.
1460 @end deftypevr
1462 @comment stdlib.h
1463 @comment ISO
1464 @deftypefun int rand (void)
1465 The @code{rand} function returns the next pseudo-random number in the
1466 series.  The value is in the range from @code{0} to @code{RAND_MAX}.
1467 @end deftypefun
1469 @comment stdlib.h
1470 @comment ISO
1471 @deftypefun void srand (unsigned int @var{seed})
1472 This function establishes @var{seed} as the seed for a new series of
1473 pseudo-random numbers.  If you call @code{rand} before a seed has been
1474 established with @code{srand}, it uses the value @code{1} as a default
1475 seed.
1477 To produce truly random numbers (not just pseudo-random), do @code{srand
1478 (time (0))}.
1479 @end deftypefun
1481 @node BSD Random
1482 @subsection BSD Random Number Functions
1484 This section describes a set of random number generation functions that
1485 are derived from BSD.  There is no advantage to using these functions
1486 with the GNU C library; we support them for BSD compatibility only.
1488 The prototypes for these functions are in @file{stdlib.h}.
1489 @pindex stdlib.h
1491 @comment stdlib.h
1492 @comment BSD
1493 @deftypefun {int32_t} random (void)
1494 This function returns the next pseudo-random number in the sequence.
1495 The range of values returned is from @code{0} to @code{RAND_MAX}.
1497 @strong{Please note:} Historically this function returned a @code{long
1498 int} value.  But with the appearence of 64bit machines this could lead
1499 to severe compatibility problems and therefore the type now explicitly
1500 limits the return value to 32bit.
1501 @end deftypefun
1503 @comment stdlib.h
1504 @comment BSD
1505 @deftypefun void srandom (unsigned int @var{seed})
1506 The @code{srandom} function sets the seed for the current random number
1507 state based on the integer @var{seed}.  If you supply a @var{seed} value
1508 of @code{1}, this will cause @code{random} to reproduce the default set
1509 of random numbers.
1511 To produce truly random numbers (not just pseudo-random), do
1512 @code{srandom (time (0))}.
1513 @end deftypefun
1515 @comment stdlib.h
1516 @comment BSD
1517 @deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
1518 The @code{initstate} function is used to initialize the random number
1519 generator state.  The argument @var{state} is an array of @var{size}
1520 bytes, used to hold the state information.  The size must be at least 8
1521 bytes, and optimal sizes are 8, 16, 32, 64, 128, and 256.  The bigger
1522 the @var{state} array, the better.
1524 The return value is the previous value of the state information array.
1525 You can use this value later as an argument to @code{setstate} to
1526 restore that state.
1527 @end deftypefun
1529 @comment stdlib.h
1530 @comment BSD
1531 @deftypefun {void *} setstate (void *@var{state})
1532 The @code{setstate} function restores the random number state
1533 information @var{state}.  The argument must have been the result of
1534 a previous call to @var{initstate} or @var{setstate}.
1536 The return value is the previous value of the state information array.
1537 You can use thise value later as an argument to @code{setstate} to
1538 restore that state.
1539 @end deftypefun
1542 @node SVID Random
1543 @subsection SVID Random Number Function
1545 The C library on SVID systems contains yet another kind of random number
1546 generator functions.  They use a state of 48 bits of data.  The user can
1547 choose among a collection of functions which all return the random bits
1548 in different forms.
1550 Generally there are two kinds of functions: those which use a state of
1551 the random number generator which is shared among several functions and
1552 by all threads of the process.  The second group of functions require
1553 the user to handle the state.
1555 All functions have in common that they use the same congruential
1556 formula with the same constants.  The formula is
1558 @smallexample
1559 Y = (a * X + c) mod m
1560 @end smallexample
1562 @noindent
1563 where @var{X} is the state of the generator at the beginning and
1564 @var{Y} the state at the end.  @code{a} and @code{c} are constants
1565 determining the way the generator work.  By default they are
1567 @smallexample
1568 a = 0x5DEECE66D = 25214903917
1569 c = 0xb = 11
1570 @end smallexample
1572 @noindent
1573 but they can also be changed by the user.  @code{m} is of course 2^48
1574 since the state consists of a 48 bit array.
1577 @comment stdlib.h
1578 @comment SVID
1579 @deftypefun double drand48 (void)
1580 This function returns a @code{double} value in the range of @code{0.0}
1581 to @code{1.0} (exclusive).  The random bits are determined by the global
1582 state of the random number generator in the C library.
1584 Since the @code{double} type according to @w{IEEE 754} has a 52 bit
1585 mantissa this means 4 bits are not initialized by the random number
1586 generator.  These are (of course) chosen to be the least significant
1587 bits and they are initialized to @code{0}.
1588 @end deftypefun
1590 @comment stdlib.h
1591 @comment SVID
1592 @deftypefun double erand48 (unsigned short int @var{xsubi})
1593 This function returns a @code{double} value in the range of @code{0.0}
1594 to @code{1.0} (exclusive), similar to @code{drand48}.  The argument is
1595 an array describing the state of the random number generator.
1597 This function can be called subsequently since it updates the array to
1598 guarantee random numbers.  The array should have been initialized before
1599 using to get reproducible results.
1600 @end deftypefun
1602 @comment stdlib.h
1603 @comment SVID
1604 @deftypefun {long int} lrand48 (void)
1605 The @code{lrand48} functions return an integer value in the range of
1606 @code{0} to @code{2^31} (exclusive).  Even if the size of the @code{long
1607 int} type can take more than 32 bits no higher numbers are returned.
1608 The random bits are determined by the global state of the random number
1609 generator in the C library.
1610 @end deftypefun
1612 @comment stdlib.h
1613 @comment SVID
1614 @deftypefun {long int} nrand48 (unsigned short int @var{xsubi})
1615 This function is similar to the @code{lrand48} function in that it
1616 returns a number in the range of @code{0} to @code{2^31} (exclusive) but
1617 the state of the random number generator used to produce the random bits
1618 is determined by the array provided as the parameter to the function.
1620 The numbers in the array are afterwards updated so that subsequent calls
1621 to this function yield to different results (as it is expected by a
1622 random number generator).  The array should have been initialized before
1623 the first call to get reproducible results.
1624 @end deftypefun
1626 @comment stdlib.h
1627 @comment SVID
1628 @deftypefun {long int} mrand48 (void)
1629 The @code{mrand48} function is similar to @code{lrand48}.  The only
1630 difference is that the numbers returned are in the range @code{-2^31} to
1631 @code{2^31} (exclusive).
1632 @end deftypefun
1634 @comment stdlib.h
1635 @comment SVID
1636 @deftypefun {long int} jrand48 (unsigned short int @var{xsubi})
1637 The @code{jrand48} function is similar to @code{nrand48}.  The only
1638 difference is that the numbers returned are in the range @code{-2^31} to
1639 @code{2^31} (exclusive).  For the @code{xsubi} parameter the same
1640 requirements are necessary.
1641 @end deftypefun
1643 The internal state of the random number generator can be initialized in
1644 several ways.  The functions differ in the completeness of the
1645 information provided.
1647 @comment stdlib.h
1648 @comment SVID
1649 @deftypefun void srand48 (long int @var{seedval}))
1650 The @code{srand48} function sets the most significant 32 bits of the
1651 state internal state of the random number generator to the least
1652 significant 32 bits of the @var{seedval} parameter.  The lower 16 bts
1653 are initilialized to the value @code{0x330E}.  Even if the @code{long
1654 int} type contains more the 32 bits only the lower 32 bits are used.
1656 Due to this limitation the initialization of the state using this
1657 function of not very useful.  But it makes it easy to use a constrcut
1658 like @code{srand48 (time (0))}.
1660 A side-effect of this function is that the values @code{a} and @code{c}
1661 from the internal state, which are used in the congruential formula,
1662 are reset to the default values given above.  This is of importance once
1663 the user called the @code{lcong48} function (see below).
1664 @end deftypefun
1666 @comment stdlib.h
1667 @comment SVID
1668 @deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v})
1669 The @code{seed48} function initializes all 48 bits of the state of the
1670 internal random number generator from the content of the parameter
1671 @var{seed16v}.  Here the lower 16 bits of the first element of
1672 @var{see16v} initialize the least significant 16 bits of the internal
1673 state, the lower 16 bits of @code{@var{seed16v}} initialize the mid-order
1674 16 bits of the state and the 16 lower bits of @code{@var{seed16v}}
1675 initialize the most significant 16 bits of the state.
1677 Unlike @code{srand48} this function lets the user initialize all 48 bits
1678 of the state.
1680 The value returned by @code{seed48} is a pointer to an array containing
1681 the values of the internal state before the change.  This might be
1682 useful to restart the random number generator at a certain state.
1683 Otherwise, the value can simply be ignored.
1685 As for @code{srand48}, the values @code{a} and @code{c} from the
1686 congruential formula are reset to the default values.
1687 @end deftypefun
1689 There is one more function to initialize the random number generator
1690 which allows to specify even more information by allowing to change the
1691 parameters in the congruential formula.
1693 @comment stdlib.h
1694 @comment SVID
1695 @deftypefun void lcong48 (unsigned short int @var{param})
1696 The @code{lcong48} function allows the user to change the complete state
1697 of the random number generator.  Unlike @code{srand48} and
1698 @code{seed48}, this function also changes the constants in the
1699 congruential formula.
1701 From the seven elements in the array @var{param} the least significant
1702 16 bits of the entries @code{@var{param}} to @code{@var{param}}
1703 determine the the initial state, the least 16 bits of
1704 @code{@var{param}} to @code{@var{param}} determine the 48 bit
1705 constant @code{a} and @code{@var{param}} determines the 16 bit value
1706 @code{c}.
1707 @end deftypefun
1709 All the above functions have in common that they use the global
1710 parameters for the congruential formula.  In multi-threaded programs it
1711 might sometimes be useful to have different parameters in different
1712 threads.  For this reason all the above functions have a counterpart
1713 which works on a description of the random number generator in the
1714 user-supplied buffer instead of the global state.
1716 Please note that it is no problem if several threads use the global
1717 state if all threads use the functions which take a pointer to an array
1718 containing the state.  The random numbers are computed following the
1719 same loop but if the state in the array is different all threads will
1720 get an individuual random number generator.
1722 The user supplied buffer must be of type @code{struct drand48_data}.
1723 This type should be regarded as opaque and no member should be used
1724 directly.
1726 @comment stdlib.h
1727 @comment GNU
1728 @deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1729 This function is equivalent to the @code{drand48} function with the
1730 difference it does not modify the global random number generator
1731 parameters but instead the parameters is the buffer supplied by the
1732 buffer through the pointer @var{buffer}.  The random number is return in
1733 the variable pointed to by @var{result}.
1735 The return value of the function indicate whether the call succeeded.
1736 If the value is less than @code{0} an error occurred and @var{errno} is
1737 set to indicate the problem.
1739 This function is a GNU extension and should not be used in portable
1740 programs.
1741 @end deftypefun
1743 @comment stdlib.h
1744 @comment GNU
1745 @deftypefun int erand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, double *@var{result})
1746 The @code{erand48_r} function works like the @code{erand48} and it takes
1747 an argument @var{buffer} which describes the random number generator.
1748 The state of the random number genertor is taken from the @code{xsubi}
1749 array, the parameters for the congruential formula from the global
1750 random number generator data.  The random number is return in the
1751 variable pointed to by @var{result}.
1753 The return value is non-negative is the call succeeded.
1755 This function is a GNU extension and should not be used in portable
1756 programs.
1757 @end deftypefun
1759 @comment stdlib.h
1760 @comment GNU
1761 @deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1762 This function is similar to @code{lrand48} and it takes a pointer to a
1763 buffer describing the state of the random number generator as a
1764 parameter just like @code{drand48}.
1766 If the return value of the function is non-negative the variable pointed
1767 to by @var{result} contains the result.  Otherwise an error occurred.
1769 This function is a GNU extension and should not be used in portable
1770 programs.
1771 @end deftypefun
1773 @comment stdlib.h
1774 @comment GNU
1775 @deftypefun int nrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
1776 The @code{nrand48_r} function works like @code{nrand48} in that it
1777 produces a random number in range @code{0} to @code{2^31}.  But instead
1778 of using the global parameters for the congruential formula it uses the
1779 information from the buffer pointed to by @var{buffer}.  The state is
1780 described by the values in @var{xsubi}.
1782 If the return value is non-negative the variable pointed to by
1783 @var{result} contains the result.
1785 This function is a GNU extension and should not be used in portable
1786 programs.
1787 @end deftypefun
1789 @comment stdlib.h
1790 @comment GNU
1791 @deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
1792 This function is similar to @code{mrand48} but as the other reentrant
1793 function it uses the random number generator described by the value in
1794 the buffer pointed to by @var{buffer}.
1796 If the return value is non-negative the variable pointed to by
1797 @var{result} contains the result.
1799 This function is a GNU extension and should not be used in portable
1800 programs.
1801 @end deftypefun
1803 @comment stdlib.h
1804 @comment GNU
1805 @deftypefun int jrand48_r (unsigned short int @var{xsubi}, struct drand48_data *@var{buffer}, long int *@var{result})
1806 The @code{jrand48_r} function is similar to @code{jrand48}.  But as the
1807 other reentrant functions of this function family it uses the
1808 congruential formula parameters from the buffer pointed to by
1809 @var{buffer}.
1811 If the return value is non-negative the variable pointed to by
1812 @var{result} contains the result.
1814 This function is a GNU extension and should not be used in portable
1815 programs.
1816 @end deftypefun
1818 Before any of the above functions should be used the buffer of type
1819 @code{struct drand48_data} should initialized.  The easiest way is to
1820 fill the whole buffer with null bytes, e.g., using
1822 @smallexample
1823 memset (buffer, '\0', sizeof (struct drand48_data));
1824 @end smallexample
1826 @noindent
1827 Using any of the reetrant functions of this family now will
1828 automatically initialize the random number generator to the default
1829 values for the state and the parameters of the congruential formula.
1831 The other possibility is too use any of the functions which explicitely
1832 initialize the buffer.  Though it might be obvious how to initialize the
1833 buffer from the data given as parameter from the function it is highly
1834 recommended to use these functions since the result might not always be
1835 what you expect.
1837 @comment stdlib.h
1838 @comment GNU
1839 @deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
1840 The description of the random number generator represented by the
1841 information in @var{buffer} is initialized similar to what the function
1842 @code{srand48} does.  The state is initialized from the paramter
1843 @var{seedval} and the paameters for the congruential formula are
1844 initialized to the default values.
1846 If the return value is non-negative the function call succeeded.
1848 This function is a GNU extension and should not be used in portable
1849 programs.
1850 @end deftypefun
1852 @comment stdlib.h
1853 @comment GNU
1854 @deftypefun int seed48_r (unsigned short int @var{seed16v}, struct drand48_data *@var{buffer})
1855 This function is similar to @code{srand48_r} but like @code{seed48} it
1856 initializes all 48 bits of the state from the parameter @var{seed16v}.
1858 If the return value is non-negative the function call succeeded.  It
1859 does not return a pointer to the previous state of the random number
1860 generator like the @code{seed48} function does.  if the user wants to
1861 preserve the state for a later rerun s/he can copy the whole buffer
1862 pointed to by @var{buffer}.
1864 This function is a GNU extension and should not be used in portable
1865 programs.
1866 @end deftypefun
1868 @comment stdlib.h
1869 @comment GNU
1870 @deftypefun int lcong48_r (unsigned short int @var{param}, struct drand48_data *@var{buffer})
1871 This function initializes all aspects of the random number generator
1872 described in @var{buffer} by the data in @var{param}.  Here it is
1873 especially true the function does more than just copying the contents of
1874 @var{param} of @var{buffer}.  Some more actions are required and
1875 therefore it is important to use this function and not initialized the
1876 random number generator directly.
1878 If the return value is non-negative the function call succeeded.
1880 This function is a GNU extension and should not be used in portable
1881 programs.
1882 @end deftypefun