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