mirror of
https://sourceware.org/git/glibc.git
synced 2024-12-13 14:50:17 +00:00
1748 lines
59 KiB
Plaintext
1748 lines
59 KiB
Plaintext
@c We need some definitions here.
|
|
@ifclear mult
|
|
@ifhtml
|
|
@set mult ·
|
|
@set infty ∞
|
|
@set pie π
|
|
@end ifhtml
|
|
@iftex
|
|
@set mult @cdot
|
|
@set infty @infty
|
|
@end iftex
|
|
@ifclear mult
|
|
@set mult *
|
|
@set infty oo
|
|
@set pie pi
|
|
@end ifclear
|
|
@macro mul
|
|
@value{mult}
|
|
@end macro
|
|
@macro infinity
|
|
@value{infty}
|
|
@end macro
|
|
@ifnottex
|
|
@macro pi
|
|
@value{pie}
|
|
@end macro
|
|
@end ifnottex
|
|
@end ifclear
|
|
|
|
@node Mathematics, Arithmetic, Low-Level Terminal Interface, Top
|
|
@c %MENU% Math functions, useful constants, random numbers
|
|
@chapter Mathematics
|
|
|
|
This chapter contains information about functions for performing
|
|
mathematical computations, such as trigonometric functions. Most of
|
|
these functions have prototypes declared in the header file
|
|
@file{math.h}. The complex-valued functions are defined in
|
|
@file{complex.h}.
|
|
@pindex math.h
|
|
@pindex complex.h
|
|
|
|
All mathematical functions which take a floating-point argument
|
|
have three variants, one each for @code{double}, @code{float}, and
|
|
@code{long double} arguments. The @code{double} versions are mostly
|
|
defined in @w{ISO C 89}. The @code{float} and @code{long double}
|
|
versions are from the numeric extensions to C included in @w{ISO C 9X}.
|
|
|
|
Which of the three versions of a function should be used depends on the
|
|
situation. For most calculations, the @code{float} functions are the
|
|
fastest. On the other hand, the @code{long double} functions have the
|
|
highest precision. @code{double} is somewhere in between. It is
|
|
usually wise to pick the narrowest type that can accomodate your data.
|
|
Not all machines have a distinct @code{long double} type; it may be the
|
|
same as @code{double}.
|
|
|
|
@menu
|
|
* Mathematical Constants:: Precise numeric values for often-used
|
|
constants.
|
|
* Trig Functions:: Sine, cosine, tangent, and friends.
|
|
* Inverse Trig Functions:: Arcsine, arccosine, etc.
|
|
* Exponents and Logarithms:: Also pow and sqrt.
|
|
* Hyperbolic Functions:: sinh, cosh, tanh, etc.
|
|
* Special Functions:: Bessel, gamma, erf.
|
|
* Pseudo-Random Numbers:: Functions for generating pseudo-random
|
|
numbers.
|
|
* FP Function Optimizations:: Fast code or small code.
|
|
@end menu
|
|
|
|
@node Mathematical Constants
|
|
@section Predefined Mathematical Constants
|
|
@cindex constants
|
|
@cindex mathematical constants
|
|
|
|
The header @file{math.h} defines several useful mathematical constants.
|
|
All values are defined as preprocessor macros starting with @code{M_}.
|
|
The values provided are:
|
|
|
|
@vtable @code
|
|
@item M_E
|
|
The base of natural logarithms.
|
|
@item M_LOG2E
|
|
The logarithm to base @code{2} of @code{M_E}.
|
|
@item M_LOG10E
|
|
The logarithm to base @code{10} of @code{M_E}.
|
|
@item M_LN2
|
|
The natural logarithm of @code{2}.
|
|
@item M_LN10
|
|
The natural logarithm of @code{10}.
|
|
@item M_PI
|
|
Pi, the ratio of a circle's circumrefence to its diameter.
|
|
@item M_PI_2
|
|
Pi divided by two.
|
|
@item M_PI_4
|
|
Pi divided by four.
|
|
@item M_1_PI
|
|
The reciprocal of pi (1/pi)
|
|
@item M_2_PI
|
|
Two times the reciprocal of pi.
|
|
@item M_2_SQRTPI
|
|
Two times the reciprocal of the square root of pi.
|
|
@item M_SQRT2
|
|
The square root of two.
|
|
@item M_SQRT1_2
|
|
The reciprocal of the square root of two (also the square root of 1/2).
|
|
@end vtable
|
|
|
|
These constants come from the Unix98 standard and were also available in
|
|
4.4BSD; therefore, they are only defined if @code{_BSD_SOURCE} or
|
|
@code{_XOPEN_SOURCE=500}, or a more general feature select macro, is
|
|
defined. The default set of features includes these constants.
|
|
@xref{Feature Test Macros}.
|
|
|
|
All values are of type @code{double}. As an extension, the GNU C
|
|
library also defines these constants with type @code{long double}. The
|
|
@code{long double} macros have a lowercase @samp{l} appended to their
|
|
names: @code{M_El}, @code{M_PIl}, and so forth. These are only
|
|
available if @code{_GNU_SOURCE} is defined.
|
|
|
|
@vindex PI
|
|
@emph{Note:} Some programs use a constant named @code{PI} which has the
|
|
same value as @code{M_PI}. This constant is not standard; it may have
|
|
appeared in some old AT&T headers, and is mentioned in Stroustrup's book
|
|
on C++. It infringes on the user's name space, so the GNU C library
|
|
does not define it. Fixing programs written to expect it is simple:
|
|
replace @code{PI} with @code{M_PI} throughout, or put @samp{-DPI=M_PI}
|
|
on the compiler command line.
|
|
|
|
@node Trig Functions
|
|
@section Trigonometric Functions
|
|
@cindex trigonometric functions
|
|
|
|
These are the familiar @code{sin}, @code{cos}, and @code{tan} functions.
|
|
The arguments to all of these functions are in units of radians; recall
|
|
that pi radians equals 180 degrees.
|
|
|
|
@cindex pi (trigonometric constant)
|
|
The math library normally defines @code{M_PI} to a @code{double}
|
|
approximation of pi. If strict ISO and/or POSIX compliance
|
|
are requested this constant is not defined, but you can easily define it
|
|
yourself:
|
|
|
|
@smallexample
|
|
#define M_PI 3.14159265358979323846264338327
|
|
@end smallexample
|
|
|
|
@noindent
|
|
You can also compute the value of pi with the expression @code{acos
|
|
(-1.0)}.
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double sin (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float sinf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} sinl (long double @var{x})
|
|
These functions return the sine of @var{x}, where @var{x} is given in
|
|
radians. The return value is in the range @code{-1} to @code{1}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double cos (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float cosf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} cosl (long double @var{x})
|
|
These functions return the cosine of @var{x}, where @var{x} is given in
|
|
radians. The return value is in the range @code{-1} to @code{1}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double tan (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float tanf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} tanl (long double @var{x})
|
|
These functions return the tangent of @var{x}, where @var{x} is given in
|
|
radians.
|
|
|
|
Mathematically, the tangent function has singularities at odd multiples
|
|
of pi/2. If the argument @var{x} is too close to one of these
|
|
singularities, @code{tan} will signal overflow.
|
|
@end deftypefun
|
|
|
|
In many applications where @code{sin} and @code{cos} are used, the sine
|
|
and cosine of the same angle are needed at the same time. It is more
|
|
efficient to compute them simultaneously, so the library provides a
|
|
function to do that.
|
|
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})
|
|
These functions return the sine of @var{x} in @code{*@var{sinx}} and the
|
|
cosine of @var{x} in @code{*@var{cos}}, where @var{x} is given in
|
|
radians. Both values, @code{*@var{sinx}} and @code{*@var{cosx}}, are in
|
|
the range of @code{-1} to @code{1}.
|
|
|
|
This function is a GNU extension. Portable programs should be prepared
|
|
to cope with its absence.
|
|
@end deftypefun
|
|
|
|
@cindex complex trigonometric functions
|
|
|
|
@w{ISO C 9x} defines variants of the trig functions which work on
|
|
complex numbers. The GNU C library provides these functions, but they
|
|
are only useful if your compiler supports the new complex types defined
|
|
by the standard.
|
|
@c Change this when gcc is fixed. -zw
|
|
(As of this writing GCC supports complex numbers, but there are bugs in
|
|
the implementation.)
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} csin (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} csinf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} csinl (complex long double @var{z})
|
|
These functions return the complex sine of @var{z}.
|
|
The mathematical definition of the complex sine is
|
|
|
|
@ifinfo
|
|
@math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}.
|
|
@end ifinfo
|
|
@tex
|
|
$$\sin(z) = {1\over 2i} (e^{zi} - e^{-zi})$$
|
|
@end tex
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} ccos (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} ccosf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} ccosl (complex long double @var{z})
|
|
These functions return the complex cosine of @var{z}.
|
|
The mathematical definition of the complex cosine is
|
|
|
|
@ifinfo
|
|
@math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))}
|
|
@end ifinfo
|
|
@tex
|
|
$$\cos(z) = {1\over 2} (e^{zi} + e^{-zi})$$
|
|
@end tex
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} ctan (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} ctanf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} ctanl (complex long double @var{z})
|
|
These functions return the complex tangent of @var{z}.
|
|
The mathematical definition of the complex tangent is
|
|
|
|
@ifinfo
|
|
@math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))}
|
|
@end ifinfo
|
|
@tex
|
|
$$\tan(z) = -i \cdot {e^{zi} - e^{-zi}\over e^{zi} + e^{-zi}}$$
|
|
@end tex
|
|
|
|
@noindent
|
|
The complex tangent has poles at @math{pi/2 + 2n}, where @math{n} is an
|
|
integer. @code{ctan} may signal overflow if @var{z} is too close to a
|
|
pole.
|
|
@end deftypefun
|
|
|
|
|
|
@node Inverse Trig Functions
|
|
@section Inverse Trigonometric Functions
|
|
@cindex inverse trigonometric functions
|
|
|
|
These are the usual arc sine, arc cosine and arc tangent functions,
|
|
which are the inverses of the sine, cosine and tangent functions,
|
|
respectively.
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double asin (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float asinf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} asinl (long double @var{x})
|
|
These functions compute the arc sine of @var{x}---that is, the value whose
|
|
sine is @var{x}. The value is in units of radians. Mathematically,
|
|
there are infinitely many such values; the one actually returned is the
|
|
one between @code{-pi/2} and @code{pi/2} (inclusive).
|
|
|
|
The arc sine function is defined mathematically only
|
|
over the domain @code{-1} to @code{1}. If @var{x} is outside the
|
|
domain, @code{asin} signals a domain error.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double acos (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float acosf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} acosl (long double @var{x})
|
|
These functions compute the arc cosine of @var{x}---that is, the value
|
|
whose cosine is @var{x}. The value is in units of radians.
|
|
Mathematically, there are infinitely many such values; the one actually
|
|
returned is the one between @code{0} and @code{pi} (inclusive).
|
|
|
|
The arc cosine function is defined mathematically only
|
|
over the domain @code{-1} to @code{1}. If @var{x} is outside the
|
|
domain, @code{acos} signals a domain error.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double atan (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float atanf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} atanl (long double @var{x})
|
|
These functions compute the arc tangent of @var{x}---that is, the value
|
|
whose tangent is @var{x}. The value is in units of radians.
|
|
Mathematically, there are infinitely many such values; the one actually
|
|
returned is the one between @code{-pi/2} and @code{pi/2} (inclusive).
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double atan2 (double @var{y}, double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float atan2f (float @var{y}, float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})
|
|
This function computes the arc tangent of @var{y}/@var{x}, but the signs
|
|
of both arguments are used to determine the quadrant of the result, and
|
|
@var{x} is permitted to be zero. The return value is given in radians
|
|
and is in the range @code{-pi} to @code{pi}, inclusive.
|
|
|
|
If @var{x} and @var{y} are coordinates of a point in the plane,
|
|
@code{atan2} returns the signed angle between the line from the origin
|
|
to that point and the x-axis. Thus, @code{atan2} is useful for
|
|
converting Cartesian coordinates to polar coordinates. (To compute the
|
|
radial coordinate, use @code{hypot}; see @ref{Exponents and
|
|
Logarithms}.)
|
|
|
|
@c This is experimentally true. Should it be so? -zw
|
|
If both @var{x} and @var{y} are zero, @code{atan2} returns zero.
|
|
@end deftypefun
|
|
|
|
@cindex inverse complex trigonometric functions
|
|
@w{ISO C 9x} defines complex versions of the inverse trig functions.
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} casin (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} casinf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} casinl (complex long double @var{z})
|
|
These functions compute the complex arc sine of @var{z}---that is, the
|
|
value whose sine is @var{z}. The value returned is in radians.
|
|
|
|
Unlike the real-valued functions, @code{casin} is defined for all
|
|
values of @var{z}.
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} cacos (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} cacosf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} cacosl (complex long double @var{z})
|
|
These functions compute the complex arc cosine of @var{z}---that is, the
|
|
value whose cosine is @var{z}. The value returned is in radians.
|
|
|
|
Unlike the real-valued functions, @code{cacos} is defined for all
|
|
values of @var{z}.
|
|
@end deftypefun
|
|
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} catan (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} catanf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} catanl (complex long double @var{z})
|
|
These functions compute the complex arc tangent of @var{z}---that is,
|
|
the value whose tangent is @var{z}. The value is in units of radians.
|
|
@end deftypefun
|
|
|
|
|
|
@node Exponents and Logarithms
|
|
@section Exponentiation and Logarithms
|
|
@cindex exponentiation functions
|
|
@cindex power functions
|
|
@cindex logarithm functions
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double exp (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float expf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} expl (long double @var{x})
|
|
These functions compute @code{e} (the base of natural logarithms) raised
|
|
to the power @var{x}.
|
|
|
|
If the magnitude of the result is too large to be representable,
|
|
@code{exp} signals overflow.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double exp2 (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float exp2f (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} exp2l (long double @var{x})
|
|
These functions compute @code{2} raised to the power @var{x}.
|
|
Mathematically, @code{exp2 (x)} is the same as @code{exp (x * log (2))}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefun double exp10 (double @var{x})
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefunx float exp10f (float @var{x})
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefunx {long double} exp10l (long double @var{x})
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefunx double pow10 (double @var{x})
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefunx float pow10f (float @var{x})
|
|
@comment math.h
|
|
@comment GNU
|
|
@deftypefunx {long double} pow10l (long double @var{x})
|
|
These functions compute @code{10} raised to the power @var{x}.
|
|
Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}.
|
|
|
|
These functions are GNU extensions. The name @code{exp10} is
|
|
preferred, since it is analogous to @code{exp} and @code{exp2}.
|
|
@end deftypefun
|
|
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double log (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float logf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} logl (long double @var{x})
|
|
These functions compute the natural logarithm of @var{x}. @code{exp (log
|
|
(@var{x}))} equals @var{x}, exactly in mathematics and approximately in
|
|
C.
|
|
|
|
If @var{x} is negative, @code{log} signals a domain error. If @var{x}
|
|
is zero, it returns negative infinity; if @var{x} is too close to zero,
|
|
it may signal overflow.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double log10 (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float log10f (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} log10l (long double @var{x})
|
|
These functions return the base-10 logarithm of @var{x}.
|
|
@code{log10 (@var{x})} equals @code{log (@var{x}) / log (10)}.
|
|
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double log2 (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float log2f (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} log2l (long double @var{x})
|
|
These functions return the base-2 logarithm of @var{x}.
|
|
@code{log2 (@var{x})} equals @code{log (@var{x}) / log (2)}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double logb (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float logbf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} logbl (long double @var{x})
|
|
These functions extract the exponent of @var{x} and return it as a
|
|
floating-point value. If @code{FLT_RADIX} is two, @code{logb} is equal
|
|
to @code{floor (log2 (x))}, except it's probably faster.
|
|
|
|
If @var{x} is denormalized, @code{logb} returns the exponent @var{x}
|
|
would have if it were normalized. If @var{x} is infinity (positive or
|
|
negative), @code{logb} returns @math{@infinity{}}. If @var{x} is zero,
|
|
@code{logb} returns @math{@infinity{}}. It does not signal.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun int ilogb (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx int ilogbf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx int ilogbl (long double @var{x})
|
|
These functions are equivalent to the corresponding @code{logb}
|
|
functions except that they return signed integer values.
|
|
@end deftypefun
|
|
|
|
@noindent
|
|
Since integers cannot represent infinity and NaN, @code{ilogb} instead
|
|
returns an integer that can't be the exponent of a normal floating-point
|
|
number. @file{math.h} defines constants so you can check for this.
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypevr Macro int FP_ILOGB0
|
|
@code{ilogb} returns this value if its argument is @code{0}. The
|
|
numeric value is either @code{INT_MIN} or @code{-INT_MAX}.
|
|
|
|
This macro is defined in @w{ISO C 9X}.
|
|
@end deftypevr
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypevr Macro int FP_ILOGBNAN
|
|
@code{ilogb} returns this value if its argument is @code{NaN}. The
|
|
numeric value is either @code{INT_MIN} or @code{INT_MAX}.
|
|
|
|
This macro is defined in @w{ISO C 9X}.
|
|
@end deftypevr
|
|
|
|
These values are system specific. They might even be the same. The
|
|
proper way to test the result of @code{ilogb} is as follows:
|
|
|
|
@smallexample
|
|
i = ilogb (f);
|
|
if (i == FP_ILOGB0 || i == FP_ILOGBNAN)
|
|
@{
|
|
if (isnan (f))
|
|
@{
|
|
/* @r{Handle NaN.} */
|
|
@}
|
|
else if (f == 0.0)
|
|
@{
|
|
/* @r{Handle 0.0.} */
|
|
@}
|
|
else
|
|
@{
|
|
/* @r{Some other value with large exponent,}
|
|
@r{perhaps +Inf.} */
|
|
@}
|
|
@}
|
|
@end smallexample
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double pow (double @var{base}, double @var{power})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float powf (float @var{base}, float @var{power})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} powl (long double @var{base}, long double @var{power})
|
|
These are general exponentiation functions, returning @var{base} raised
|
|
to @var{power}.
|
|
|
|
Mathematically, @code{pow} would return a complex number when @var{base}
|
|
is negative and @var{power} is not an integral value. @code{pow} can't
|
|
do that, so instead it signals a domain error. @code{pow} may also
|
|
underflow or overflow the destination type.
|
|
@end deftypefun
|
|
|
|
@cindex square root function
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double sqrt (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float sqrtf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} sqrtl (long double @var{x})
|
|
These functions return the nonnegative square root of @var{x}.
|
|
|
|
If @var{x} is negative, @code{sqrt} signals a domain error.
|
|
Mathematically, it should return a complex number.
|
|
@end deftypefun
|
|
|
|
@cindex cube root function
|
|
@comment math.h
|
|
@comment BSD
|
|
@deftypefun double cbrt (double @var{x})
|
|
@comment math.h
|
|
@comment BSD
|
|
@deftypefunx float cbrtf (float @var{x})
|
|
@comment math.h
|
|
@comment BSD
|
|
@deftypefunx {long double} cbrtl (long double @var{x})
|
|
These functions return the cube root of @var{x}. They cannot
|
|
fail; every representable real value has a representable real cube root.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double hypot (double @var{x}, double @var{y})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float hypotf (float @var{x}, float @var{y})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})
|
|
These functions return @code{sqrt (@var{x}*@var{x} +
|
|
@var{y}*@var{y})}. This is the length of the hypotenuse of a right
|
|
triangle with sides of length @var{x} and @var{y}, or the distance
|
|
of the point (@var{x}, @var{y}) from the origin. Using this function
|
|
instead of the direct formula is wise, since the error is
|
|
much smaller. See also the function @code{cabs} in @ref{Absolute Value}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double expm1 (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float expm1f (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} expm1l (long double @var{x})
|
|
These functions return a value equivalent to @code{exp (@var{x}) - 1}.
|
|
They are computed in a way that is accurate even if @var{x} is
|
|
near zero---a case where @code{exp (@var{x}) - 1} would be inaccurate due
|
|
to subtraction of two numbers that are nearly equal.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double log1p (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float log1pf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} log1pl (long double @var{x})
|
|
These functions returns a value equivalent to @w{@code{log (1 + @var{x})}}.
|
|
They are computed in a way that is accurate even if @var{x} is
|
|
near zero.
|
|
@end deftypefun
|
|
|
|
@cindex complex exponentiation functions
|
|
@cindex complex logarithm functions
|
|
|
|
@w{ISO C 9X} defines complex variants of some of the exponentiation and
|
|
logarithm functions.
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} cexp (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} cexpf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} cexpl (complex long double @var{z})
|
|
These functions return @code{e} (the base of natural
|
|
logarithms) raised to the power of @var{z}.
|
|
Mathematically this corresponds to the value
|
|
|
|
@ifinfo
|
|
@math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))}
|
|
@end ifinfo
|
|
@tex
|
|
$$\exp(z) = e^z = e^{{\rm Re}\,z} (\cos ({\rm Im}\,z) + i \sin ({\rm Im}\,z))$$
|
|
@end tex
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} clog (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} clogf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} clogl (complex long double @var{z})
|
|
These functions return the natural logarithm of @var{z}.
|
|
Mathematically this corresponds to the value
|
|
|
|
@ifinfo
|
|
@math{log (z) = log (cabs (z)) + I * carg (z)}
|
|
@end ifinfo
|
|
@tex
|
|
$$\log(z) = \log |z| + i \arg z$$
|
|
@end tex
|
|
|
|
@noindent
|
|
@code{clog} has a pole at 0, and will signal overflow if @var{z} equals
|
|
or is very close to 0. It is well-defined for all other values of
|
|
@var{z}.
|
|
@end deftypefun
|
|
|
|
|
|
@comment complex.h
|
|
@comment GNU
|
|
@deftypefun {complex double} clog10 (complex double @var{z})
|
|
@comment complex.h
|
|
@comment GNU
|
|
@deftypefunx {complex float} clog10f (complex float @var{z})
|
|
@comment complex.h
|
|
@comment GNU
|
|
@deftypefunx {complex long double} clog10l (complex long double @var{z})
|
|
These functions return the base 10 logarithm of the complex value
|
|
@var{z}. Mathematically this corresponds to the value
|
|
|
|
@ifinfo
|
|
@math{log (z) = log10 (cabs (z)) + I * carg (z)}
|
|
@end ifinfo
|
|
@tex
|
|
$$\log_{10}(z) = \log_{10}|z| + i \arg z$$
|
|
@end tex
|
|
|
|
These functions are GNU extensions.
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} csqrt (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} csqrtf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} csqrtl (complex long double @var{z})
|
|
These functions return the complex square root of the argument @var{z}. Unlike
|
|
the real-valued functions, they are defined for all values of @var{z}.
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})
|
|
These functions return @var{base} raised to the power of
|
|
@var{power}. This is equivalent to @w{@code{cexp (y * clog (x))}}
|
|
@end deftypefun
|
|
|
|
@node Hyperbolic Functions
|
|
@section Hyperbolic Functions
|
|
@cindex hyperbolic functions
|
|
|
|
The functions in this section are related to the exponential functions;
|
|
see @ref{Exponents and Logarithms}.
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double sinh (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float sinhf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} sinhl (long double @var{x})
|
|
These functions return the hyperbolic sine of @var{x}, defined
|
|
mathematically as @w{@code{(exp (@var{x}) - exp (-@var{x})) / 2}}. They
|
|
may signal overflow if @var{x} is too large.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double cosh (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float coshf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} coshl (long double @var{x})
|
|
These function return the hyperbolic cosine of @var{x},
|
|
defined mathematically as @w{@code{(exp (@var{x}) + exp (-@var{x})) / 2}}.
|
|
They may signal overflow if @var{x} is too large.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double tanh (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float tanhf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} tanhl (long double @var{x})
|
|
These functions return the hyperbolic tangent of @var{x},
|
|
defined mathematically as @w{@code{sinh (@var{x}) / cosh (@var{x})}}.
|
|
They may signal overflow if @var{x} is too large.
|
|
@end deftypefun
|
|
|
|
@cindex hyperbolic functions
|
|
|
|
There are counterparts for the hyperbolic functions which take
|
|
complex arguments.
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} csinh (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} csinhf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} csinhl (complex long double @var{z})
|
|
These functions return the complex hyperbolic sine of @var{z}, defined
|
|
mathematically as @w{@code{(exp (@var{z}) - exp (-@var{z})) / 2}}.
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} ccosh (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} ccoshf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} ccoshl (complex long double @var{z})
|
|
These functions return the complex hyperbolic cosine of @var{z}, defined
|
|
mathematically as @w{@code{(exp (@var{z}) + exp (-@var{z})) / 2}}.
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} ctanh (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} ctanhf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} ctanhl (complex long double @var{z})
|
|
These functions return the complex hyperbolic tangent of @var{z},
|
|
defined mathematically as @w{@code{csinh (@var{z}) / ccosh (@var{z})}}.
|
|
@end deftypefun
|
|
|
|
|
|
@cindex inverse hyperbolic functions
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double asinh (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float asinhf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} asinhl (long double @var{x})
|
|
These functions return the inverse hyperbolic sine of @var{x}---the
|
|
value whose hyperbolic sine is @var{x}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double acosh (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float acoshf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} acoshl (long double @var{x})
|
|
These functions return the inverse hyperbolic cosine of @var{x}---the
|
|
value whose hyperbolic cosine is @var{x}. If @var{x} is less than
|
|
@code{1}, @code{acosh} signals a domain error.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefun double atanh (double @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx float atanhf (float @var{x})
|
|
@comment math.h
|
|
@comment ISO
|
|
@deftypefunx {long double} atanhl (long double @var{x})
|
|
These functions return the inverse hyperbolic tangent of @var{x}---the
|
|
value whose hyperbolic tangent is @var{x}. If the absolute value of
|
|
@var{x} is greater than @code{1}, @code{atanh} signals a domain error;
|
|
if it is equal to 1, @code{atanh} returns infinity.
|
|
@end deftypefun
|
|
|
|
@cindex inverse complex hyperbolic functions
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} casinh (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} casinhf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} casinhl (complex long double @var{z})
|
|
These functions return the inverse complex hyperbolic sine of
|
|
@var{z}---the value whose complex hyperbolic sine is @var{z}.
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} cacosh (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} cacoshf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} cacoshl (complex long double @var{z})
|
|
These functions return the inverse complex hyperbolic cosine of
|
|
@var{z}---the value whose complex hyperbolic cosine is @var{z}. Unlike
|
|
the real-valued functions, there are no restrictions on the value of @var{z}.
|
|
@end deftypefun
|
|
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefun {complex double} catanh (complex double @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex float} catanhf (complex float @var{z})
|
|
@comment complex.h
|
|
@comment ISO
|
|
@deftypefunx {complex long double} catanhl (complex long double @var{z})
|
|
These functions return the inverse complex hyperbolic tangent of
|
|
@var{z}---the value whose complex hyperbolic tangent is @var{z}. Unlike
|
|
the real-valued functions, there are no restrictions on the value of
|
|
@var{z}.
|
|
@end deftypefun
|
|
|
|
@node Special Functions
|
|
@section Special Functions
|
|
@cindex special functions
|
|
@cindex Bessel functions
|
|
@cindex gamma function
|
|
|
|
These are some more exotic mathematical functions, which are sometimes
|
|
useful. Currently they only have real-valued versions.
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double erf (double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float erff (float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} erfl (long double @var{x})
|
|
@code{erf} returns the error function of @var{x}. The error
|
|
function is defined as
|
|
@tex
|
|
$$\hbox{erf}(x) = {2\over\sqrt{\pi}}\cdot\int_0^x e^{-t^2} \hbox{d}t$$
|
|
@end tex
|
|
@ifnottex
|
|
@smallexample
|
|
erf (x) = 2/sqrt(pi) * integral from 0 to x of exp(-t^2) dt
|
|
@end smallexample
|
|
@end ifnottex
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double erfc (double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float erfcf (float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} erfcl (long double @var{x})
|
|
@code{erfc} returns @code{1.0 - erf(@var{x})}, but computed in a
|
|
fashion that avoids round-off error when @var{x} is large.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double lgamma (double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float lgammaf (float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} lgammal (long double @var{x})
|
|
@code{lgamma} returns the natural logarithm of the absolute value of
|
|
the gamma function of @var{x}. The gamma function is defined as
|
|
@tex
|
|
$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
|
|
@end tex
|
|
@ifnottex
|
|
@smallexample
|
|
gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
|
|
@end smallexample
|
|
@end ifnottex
|
|
|
|
@vindex signgam
|
|
The sign of the gamma function is stored in the global variable
|
|
@var{signgam}, which is declared in @file{math.h}. It is @code{1} if
|
|
the intermediate result was positive or zero, and, @code{-1} if it was
|
|
negative.
|
|
|
|
To compute the real gamma function you can use the @code{tgamma}
|
|
function or you can compute the values as follows:
|
|
@smallexample
|
|
lgam = lgamma(x);
|
|
gam = signgam*exp(lgam);
|
|
@end smallexample
|
|
|
|
The gamma function has singularities at the nonpositive integers.
|
|
@code{lgamma} will raise the zero divide exception if evaluated at a
|
|
singularity.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment XPG
|
|
@deftypefun double lgamma_r (double @var{x}, int *@var{signp})
|
|
@comment math.h
|
|
@comment XPG
|
|
@deftypefunx float lgammaf_r (float @var{x}, int *@var{signp})
|
|
@comment math.h
|
|
@comment XPG
|
|
@deftypefunx {long double} lgammal_r (long double @var{x}, int *@var{signp})
|
|
@code{lgamma_r} is just like @code{lgamma}, but it stores the sign of
|
|
the intermediate result in the variable pointed to by @var{signp}
|
|
instead of in the @var{signgam} global.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double gamma (double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float gammaf (float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} gammal (long double @var{x})
|
|
These functions exist for compatibility reasons. They are equivalent to
|
|
@code{lgamma} etc. It is better to use @code{lgamma} since for one the
|
|
name reflects better the actual computation and @code{lgamma} is also
|
|
standardized in @w{ISO C 9x} while @code{gamma} is not.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment XPG
|
|
@deftypefun double tgamma (double @var{x})
|
|
@comment math.h
|
|
@comment XPG
|
|
@deftypefunx float tgammaf (float @var{x})
|
|
@comment math.h
|
|
@comment XPG
|
|
@deftypefunx {long double} tgammal (long double @var{x})
|
|
@code{tgamma} applies the gamma function to @var{x}. The gamma
|
|
function is defined as
|
|
@tex
|
|
$$\Gamma(x) = \int_0^\infty t^{x-1} e^{-t} \hbox{d}t$$
|
|
@end tex
|
|
@ifnottex
|
|
@smallexample
|
|
gamma (x) = integral from 0 to @infinity{} of t^(x-1) e^-t dt
|
|
@end smallexample
|
|
@end ifnottex
|
|
|
|
This function was introduced in @w{ISO C 9x}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double j0 (double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float j0f (float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} j0l (long double @var{x})
|
|
@code{j0} returns the Bessel function of the first kind of order 0 of
|
|
@var{x}. It may signal underflow if @var{x} is too large.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double j1 (double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float j1f (float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} j1l (long double @var{x})
|
|
@code{j1} returns the Bessel function of the first kind of order 1 of
|
|
@var{x}. It may signal underflow if @var{x} is too large.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double jn (int n, double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float jnf (int n, float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} jnl (int n, long double @var{x})
|
|
@code{jn} returns the Bessel function of the first kind of order
|
|
@var{n} of @var{x}. It may signal underflow if @var{x} is too large.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double y0 (double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float y0f (float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} y0l (long double @var{x})
|
|
@code{y0} returns the Bessel function of the second kind of order 0 of
|
|
@var{x}. It may signal underflow if @var{x} is too large. If @var{x}
|
|
is negative, @code{y0} signals a domain error; if it is zero,
|
|
@code{y0} signals overflow and returns @math{-@infinity}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double y1 (double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float y1f (float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} y1l (long double @var{x})
|
|
@code{y1} returns the Bessel function of the second kind of order 1 of
|
|
@var{x}. It may signal underflow if @var{x} is too large. If @var{x}
|
|
is negative, @code{y1} signals a domain error; if it is zero,
|
|
@code{y1} signals overflow and returns @math{-@infinity}.
|
|
@end deftypefun
|
|
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefun double yn (int n, double @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx float ynf (int n, float @var{x})
|
|
@comment math.h
|
|
@comment SVID
|
|
@deftypefunx {long double} ynl (int n, long double @var{x})
|
|
@code{yn} returns the Bessel function of the second kind of order @var{n} of
|
|
@var{x}. It may signal underflow if @var{x} is too large. If @var{x}
|
|
is negative, @code{yn} signals a domain error; if it is zero,
|
|
@code{yn} signals overflow and returns @math{-@infinity}.
|
|
@end deftypefun
|
|
|
|
@node Pseudo-Random Numbers
|
|
@section Pseudo-Random Numbers
|
|
@cindex random numbers
|
|
@cindex pseudo-random numbers
|
|
@cindex seed (for random numbers)
|
|
|
|
This section describes the GNU facilities for generating a series of
|
|
pseudo-random numbers. The numbers generated are not truly random;
|
|
typically, they form a sequence that repeats periodically, with a period
|
|
so large that you can ignore it for ordinary purposes. The random
|
|
number generator works by remembering a @dfn{seed} value which it uses
|
|
to compute the next random number and also to compute a new seed.
|
|
|
|
Although the generated numbers look unpredictable within one run of a
|
|
program, the sequence of numbers is @emph{exactly the same} from one run
|
|
to the next. This is because the initial seed is always the same. This
|
|
is convenient when you are debugging a program, but it is unhelpful if
|
|
you want the program to behave unpredictably. If you want a different
|
|
pseudo-random series each time your program runs, you must specify a
|
|
different seed each time. For ordinary purposes, basing the seed on the
|
|
current time works well.
|
|
|
|
You can get repeatable sequences of numbers on a particular machine type
|
|
by specifying the same initial seed value for the random number
|
|
generator. There is no standard meaning for a particular seed value;
|
|
the same seed, used in different C libraries or on different CPU types,
|
|
will give you different random numbers.
|
|
|
|
The GNU library supports the standard @w{ISO C} random number functions
|
|
plus two other sets derived from BSD and SVID. The BSD and @w{ISO C}
|
|
functions provide identical, somewhat limited functionality. If only a
|
|
small number of random bits are required, we recommend you use the
|
|
@w{ISO C} interface, @code{rand} and @code{srand}. The SVID functions
|
|
provide a more flexible interface, which allows better random number
|
|
generator algorithms, provides more random bits (up to 48) per call, and
|
|
can provide random floating-point numbers. These functions are required
|
|
by the XPG standard and therefore will be present in all modern Unix
|
|
systems.
|
|
|
|
@menu
|
|
* ISO Random:: @code{rand} and friends.
|
|
* BSD Random:: @code{random} and friends.
|
|
* SVID Random:: @code{drand48} and friends.
|
|
@end menu
|
|
|
|
@node ISO Random
|
|
@subsection ISO C Random Number Functions
|
|
|
|
This section describes the random number functions that are part of
|
|
the @w{ISO C} standard.
|
|
|
|
To use these facilities, you should include the header file
|
|
@file{stdlib.h} in your program.
|
|
@pindex stdlib.h
|
|
|
|
@comment stdlib.h
|
|
@comment ISO
|
|
@deftypevr Macro int RAND_MAX
|
|
The value of this macro is an integer constant representing the largest
|
|
value the @code{rand} function can return. In the GNU library, it is
|
|
@code{2147483647}, which is the largest signed integer representable in
|
|
32 bits. In other libraries, it may be as low as @code{32767}.
|
|
@end deftypevr
|
|
|
|
@comment stdlib.h
|
|
@comment ISO
|
|
@deftypefun int rand (void)
|
|
The @code{rand} function returns the next pseudo-random number in the
|
|
series. The value ranges from @code{0} to @code{RAND_MAX}.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment ISO
|
|
@deftypefun void srand (unsigned int @var{seed})
|
|
This function establishes @var{seed} as the seed for a new series of
|
|
pseudo-random numbers. If you call @code{rand} before a seed has been
|
|
established with @code{srand}, it uses the value @code{1} as a default
|
|
seed.
|
|
|
|
To produce a different pseudo-random series each time your program is
|
|
run, do @code{srand (time (0))}.
|
|
@end deftypefun
|
|
|
|
POSIX.1 extended the C standard functions to support reproducible random
|
|
numbers in multi-threaded programs. However, the extension is badly
|
|
designed and unsuitable for serious work.
|
|
|
|
@comment stdlib.h
|
|
@comment POSIX.1
|
|
@deftypefun int rand_r (unsigned int *@var{seed})
|
|
This function returns a random number in the range 0 to @code{RAND_MAX}
|
|
just as @code{rand} does. However, all its state is stored in the
|
|
@var{seed} argument. This means the RNG's state can only have as many
|
|
bits as the type @code{unsigned int} has. This is far too few to
|
|
provide a good RNG.
|
|
|
|
If your program requires a reentrant RNG, we recommend you use the
|
|
reentrant GNU extensions to the SVID random number generator. The
|
|
POSIX.1 interface should only be used when the GNU extensions are not
|
|
available.
|
|
@end deftypefun
|
|
|
|
|
|
@node BSD Random
|
|
@subsection BSD Random Number Functions
|
|
|
|
This section describes a set of random number generation functions that
|
|
are derived from BSD. There is no advantage to using these functions
|
|
with the GNU C library; we support them for BSD compatibility only.
|
|
|
|
The prototypes for these functions are in @file{stdlib.h}.
|
|
@pindex stdlib.h
|
|
|
|
@comment stdlib.h
|
|
@comment BSD
|
|
@deftypefun {int32_t} random (void)
|
|
This function returns the next pseudo-random number in the sequence.
|
|
The value returned ranges from @code{0} to @code{RAND_MAX}.
|
|
|
|
@strong{Note:} Historically this function returned a @code{long
|
|
int} value. On 64bit systems @code{long int} would have been larger
|
|
than programs expected, so @code{random} is now defined to return
|
|
exactly 32 bits.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment BSD
|
|
@deftypefun void srandom (unsigned int @var{seed})
|
|
The @code{srandom} function sets the state of the random number
|
|
generator based on the integer @var{seed}. If you supply a @var{seed} value
|
|
of @code{1}, this will cause @code{random} to reproduce the default set
|
|
of random numbers.
|
|
|
|
To produce a different set of pseudo-random numbers each time your
|
|
program runs, do @code{srandom (time (0))}.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment BSD
|
|
@deftypefun {void *} initstate (unsigned int @var{seed}, void *@var{state}, size_t @var{size})
|
|
The @code{initstate} function is used to initialize the random number
|
|
generator state. The argument @var{state} is an array of @var{size}
|
|
bytes, used to hold the state information. It is initialized based on
|
|
@var{seed}. The size must be between 8 and 256 bytes, and should be a
|
|
power of two. The bigger the @var{state} array, the better.
|
|
|
|
The return value is the previous value of the state information array.
|
|
You can use this value later as an argument to @code{setstate} to
|
|
restore that state.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment BSD
|
|
@deftypefun {void *} setstate (void *@var{state})
|
|
The @code{setstate} function restores the random number state
|
|
information @var{state}. The argument must have been the result of
|
|
a previous call to @var{initstate} or @var{setstate}.
|
|
|
|
The return value is the previous value of the state information array.
|
|
You can use this value later as an argument to @code{setstate} to
|
|
restore that state.
|
|
@end deftypefun
|
|
|
|
@node SVID Random
|
|
@subsection SVID Random Number Function
|
|
|
|
The C library on SVID systems contains yet another kind of random number
|
|
generator functions. They use a state of 48 bits of data. The user can
|
|
choose among a collection of functions which return the random bits
|
|
in different forms.
|
|
|
|
Generally there are two kinds of functions: those which use a state of
|
|
the random number generator which is shared among several functions and
|
|
by all threads of the process. The second group of functions require
|
|
the user to handle the state.
|
|
|
|
All functions have in common that they use the same congruential
|
|
formula with the same constants. The formula is
|
|
|
|
@smallexample
|
|
Y = (a * X + c) mod m
|
|
@end smallexample
|
|
|
|
@noindent
|
|
where @var{X} is the state of the generator at the beginning and
|
|
@var{Y} the state at the end. @code{a} and @code{c} are constants
|
|
determining the way the generator work. By default they are
|
|
|
|
@smallexample
|
|
a = 0x5DEECE66D = 25214903917
|
|
c = 0xb = 11
|
|
@end smallexample
|
|
|
|
@noindent
|
|
but they can also be changed by the user. @code{m} is of course 2^48
|
|
since the state consists of a 48 bit array.
|
|
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun double drand48 (void)
|
|
This function returns a @code{double} value in the range of @code{0.0}
|
|
to @code{1.0} (exclusive). The random bits are determined by the global
|
|
state of the random number generator in the C library.
|
|
|
|
Since the @code{double} type according to @w{IEEE 754} has a 52 bit
|
|
mantissa this means 4 bits are not initialized by the random number
|
|
generator. These are (of course) chosen to be the least significant
|
|
bits and they are initialized to @code{0}.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun double erand48 (unsigned short int @var{xsubi}[3])
|
|
This function returns a @code{double} value in the range of @code{0.0}
|
|
to @code{1.0} (exclusive), similar to @code{drand48}. The argument is
|
|
an array describing the state of the random number generator.
|
|
|
|
This function can be called subsequently since it updates the array to
|
|
guarantee random numbers. The array should have been initialized before
|
|
using to get reproducible results.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun {long int} lrand48 (void)
|
|
The @code{lrand48} functions return an integer value in the range of
|
|
@code{0} to @code{2^31} (exclusive). Even if the size of the @code{long
|
|
int} type can take more than 32 bits no higher numbers are returned.
|
|
The random bits are determined by the global state of the random number
|
|
generator in the C library.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun {long int} nrand48 (unsigned short int @var{xsubi}[3])
|
|
This function is similar to the @code{lrand48} function in that it
|
|
returns a number in the range of @code{0} to @code{2^31} (exclusive) but
|
|
the state of the random number generator used to produce the random bits
|
|
is determined by the array provided as the parameter to the function.
|
|
|
|
The numbers in the array are afterwards updated so that subsequent calls
|
|
to this function yield to different results (as it is expected by a
|
|
random number generator). The array should have been initialized before
|
|
the first call to get reproducible results.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun {long int} mrand48 (void)
|
|
The @code{mrand48} function is similar to @code{lrand48}. The only
|
|
difference is that the numbers returned are in the range @code{-2^31} to
|
|
@code{2^31} (exclusive).
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun {long int} jrand48 (unsigned short int @var{xsubi}[3])
|
|
The @code{jrand48} function is similar to @code{nrand48}. The only
|
|
difference is that the numbers returned are in the range @code{-2^31} to
|
|
@code{2^31} (exclusive). For the @code{xsubi} parameter the same
|
|
requirements are necessary.
|
|
@end deftypefun
|
|
|
|
The internal state of the random number generator can be initialized in
|
|
several ways. The functions differ in the completeness of the
|
|
information provided.
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun void srand48 (long int @var{seedval}))
|
|
The @code{srand48} function sets the most significant 32 bits of the
|
|
state internal state of the random number generator to the least
|
|
significant 32 bits of the @var{seedval} parameter. The lower 16 bits
|
|
are initialized to the value @code{0x330E}. Even if the @code{long
|
|
int} type contains more the 32 bits only the lower 32 bits are used.
|
|
|
|
Due to this limitation the initialization of the state using this
|
|
function of not very useful. But it makes it easy to use a construct
|
|
like @code{srand48 (time (0))}.
|
|
|
|
A side-effect of this function is that the values @code{a} and @code{c}
|
|
from the internal state, which are used in the congruential formula,
|
|
are reset to the default values given above. This is of importance once
|
|
the user called the @code{lcong48} function (see below).
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun {unsigned short int *} seed48 (unsigned short int @var{seed16v}[3])
|
|
The @code{seed48} function initializes all 48 bits of the state of the
|
|
internal random number generator from the content of the parameter
|
|
@var{seed16v}. Here the lower 16 bits of the first element of
|
|
@var{see16v} initialize the least significant 16 bits of the internal
|
|
state, the lower 16 bits of @code{@var{seed16v}[1]} initialize the mid-order
|
|
16 bits of the state and the 16 lower bits of @code{@var{seed16v}[2]}
|
|
initialize the most significant 16 bits of the state.
|
|
|
|
Unlike @code{srand48} this function lets the user initialize all 48 bits
|
|
of the state.
|
|
|
|
The value returned by @code{seed48} is a pointer to an array containing
|
|
the values of the internal state before the change. This might be
|
|
useful to restart the random number generator at a certain state.
|
|
Otherwise, the value can simply be ignored.
|
|
|
|
As for @code{srand48}, the values @code{a} and @code{c} from the
|
|
congruential formula are reset to the default values.
|
|
@end deftypefun
|
|
|
|
There is one more function to initialize the random number generator
|
|
which allows to specify even more information by allowing to change the
|
|
parameters in the congruential formula.
|
|
|
|
@comment stdlib.h
|
|
@comment SVID
|
|
@deftypefun void lcong48 (unsigned short int @var{param}[7])
|
|
The @code{lcong48} function allows the user to change the complete state
|
|
of the random number generator. Unlike @code{srand48} and
|
|
@code{seed48}, this function also changes the constants in the
|
|
congruential formula.
|
|
|
|
From the seven elements in the array @var{param} the least significant
|
|
16 bits of the entries @code{@var{param}[0]} to @code{@var{param}[2]}
|
|
determine the initial state, the least 16 bits of
|
|
@code{@var{param}[3]} to @code{@var{param}[5]} determine the 48 bit
|
|
constant @code{a} and @code{@var{param}[6]} determines the 16 bit value
|
|
@code{c}.
|
|
@end deftypefun
|
|
|
|
All the above functions have in common that they use the global
|
|
parameters for the congruential formula. In multi-threaded programs it
|
|
might sometimes be useful to have different parameters in different
|
|
threads. For this reason all the above functions have a counterpart
|
|
which works on a description of the random number generator in the
|
|
user-supplied buffer instead of the global state.
|
|
|
|
Please note that it is no problem if several threads use the global
|
|
state if all threads use the functions which take a pointer to an array
|
|
containing the state. The random numbers are computed following the
|
|
same loop but if the state in the array is different all threads will
|
|
get an individual random number generator.
|
|
|
|
The user supplied buffer must be of type @code{struct drand48_data}.
|
|
This type should be regarded as opaque and no member should be used
|
|
directly.
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result})
|
|
This function is equivalent to the @code{drand48} function with the
|
|
difference it does not modify the global random number generator
|
|
parameters but instead the parameters is the buffer supplied by the
|
|
buffer through the pointer @var{buffer}. The random number is return in
|
|
the variable pointed to by @var{result}.
|
|
|
|
The return value of the function indicate whether the call succeeded.
|
|
If the value is less than @code{0} an error occurred and @var{errno} is
|
|
set to indicate the problem.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int erand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, double *@var{result})
|
|
The @code{erand48_r} function works like the @code{erand48} and it takes
|
|
an argument @var{buffer} which describes the random number generator.
|
|
The state of the random number generator is taken from the @code{xsubi}
|
|
array, the parameters for the congruential formula from the global
|
|
random number generator data. The random number is return in the
|
|
variable pointed to by @var{result}.
|
|
|
|
The return value is non-negative is the call succeeded.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int lrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
|
|
This function is similar to @code{lrand48} and it takes a pointer to a
|
|
buffer describing the state of the random number generator as a
|
|
parameter just like @code{drand48}.
|
|
|
|
If the return value of the function is non-negative the variable pointed
|
|
to by @var{result} contains the result. Otherwise an error occurred.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int nrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
|
|
The @code{nrand48_r} function works like @code{nrand48} in that it
|
|
produces a random number in range @code{0} to @code{2^31}. But instead
|
|
of using the global parameters for the congruential formula it uses the
|
|
information from the buffer pointed to by @var{buffer}. The state is
|
|
described by the values in @var{xsubi}.
|
|
|
|
If the return value is non-negative the variable pointed to by
|
|
@var{result} contains the result.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int mrand48_r (struct drand48_data *@var{buffer}, double *@var{result})
|
|
This function is similar to @code{mrand48} but as the other reentrant
|
|
function it uses the random number generator described by the value in
|
|
the buffer pointed to by @var{buffer}.
|
|
|
|
If the return value is non-negative the variable pointed to by
|
|
@var{result} contains the result.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int jrand48_r (unsigned short int @var{xsubi}[3], struct drand48_data *@var{buffer}, long int *@var{result})
|
|
The @code{jrand48_r} function is similar to @code{jrand48}. But as the
|
|
other reentrant functions of this function family it uses the
|
|
congruential formula parameters from the buffer pointed to by
|
|
@var{buffer}.
|
|
|
|
If the return value is non-negative the variable pointed to by
|
|
@var{result} contains the result.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
Before any of the above functions should be used the buffer of type
|
|
@code{struct drand48_data} should initialized. The easiest way is to
|
|
fill the whole buffer with null bytes, e.g., using
|
|
|
|
@smallexample
|
|
memset (buffer, '\0', sizeof (struct drand48_data));
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Using any of the reentrant functions of this family now will
|
|
automatically initialize the random number generator to the default
|
|
values for the state and the parameters of the congruential formula.
|
|
|
|
The other possibility is too use any of the functions which explicitely
|
|
initialize the buffer. Though it might be obvious how to initialize the
|
|
buffer from the data given as parameter from the function it is highly
|
|
recommended to use these functions since the result might not always be
|
|
what you expect.
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int srand48_r (long int @var{seedval}, struct drand48_data *@var{buffer})
|
|
The description of the random number generator represented by the
|
|
information in @var{buffer} is initialized similar to what the function
|
|
@code{srand48} does. The state is initialized from the parameter
|
|
@var{seedval} and the parameters for the congruential formula are
|
|
initialized to the default values.
|
|
|
|
If the return value is non-negative the function call succeeded.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int seed48_r (unsigned short int @var{seed16v}[3], struct drand48_data *@var{buffer})
|
|
This function is similar to @code{srand48_r} but like @code{seed48} it
|
|
initializes all 48 bits of the state from the parameter @var{seed16v}.
|
|
|
|
If the return value is non-negative the function call succeeded. It
|
|
does not return a pointer to the previous state of the random number
|
|
generator like the @code{seed48} function does. if the user wants to
|
|
preserve the state for a later rerun s/he can copy the whole buffer
|
|
pointed to by @var{buffer}.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
@comment stdlib.h
|
|
@comment GNU
|
|
@deftypefun int lcong48_r (unsigned short int @var{param}[7], struct drand48_data *@var{buffer})
|
|
This function initializes all aspects of the random number generator
|
|
described in @var{buffer} by the data in @var{param}. Here it is
|
|
especially true the function does more than just copying the contents of
|
|
@var{param} of @var{buffer}. Some more actions are required and
|
|
therefore it is important to use this function and not initialized the
|
|
random number generator directly.
|
|
|
|
If the return value is non-negative the function call succeeded.
|
|
|
|
This function is a GNU extension and should not be used in portable
|
|
programs.
|
|
@end deftypefun
|
|
|
|
@node FP Function Optimizations
|
|
@section Is Fast Code or Small Code preferred?
|
|
@cindex Optimization
|
|
|
|
If an application uses many floating point function it is often the case
|
|
that the costs for the function calls itselfs are not neglectable.
|
|
Modern processor implementation often can execute the operation itself
|
|
very fast but the call means a disturbance of the control flow.
|
|
|
|
For this reason the GNU C Library provides optimizations for many of the
|
|
frequently used math functions. When the GNU CC is used and the user
|
|
activates the optimizer several new inline functions and macros get
|
|
defined. These new functions and macros have the same names as the
|
|
library function and so get used instead of the later. In case of
|
|
inline functions the compiler will decide whether it is reasonable to
|
|
use the inline function and this decision is usually correct.
|
|
|
|
For the generated code this means that no calls to the library functions
|
|
are necessary. This increases the speed significantly. But the
|
|
drawback is that the code size increases and this increase is not always
|
|
neglectable.
|
|
|
|
The speed increase has one drawback: the inline functions might not set
|
|
@code{errno} and might not have the same precission as the library
|
|
functions.
|
|
|
|
In cases where the inline functions and macros are not wanted the symbol
|
|
@code{__NO_MATH_INLINES} should be defined before any system header is
|
|
included. This will make sure only library functions are used. Of
|
|
course it can be determined for each single file in the project whether
|
|
giving this option is preferred or not.
|
|
|
|
Not all hardware implements the entire @w{IEEE 754} standard, or if it
|
|
does, there may be a substantial performance penalty for using some of
|
|
its features. For example, enabling traps on some processors forces
|
|
the FPU to run unpipelined, which more than doubles calculation time.
|
|
@c ***Add explanation of -lieee, -mieee.
|