diff options
Diffstat (limited to 'manual/math.texi')
| -rw-r--r-- | manual/math.texi | 2078 |
1 files changed, 0 insertions, 2078 deletions
diff --git a/manual/math.texi b/manual/math.texi deleted file mode 100644 index 69a0acec9b..0000000000 --- a/manual/math.texi +++ /dev/null @@ -1,2078 +0,0 @@ -@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, Syslog, 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 C89}. The @code{float} and @code{long double} -versions are from the numeric extensions to C included in @w{ISO C99}. - -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 accommodate 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. -* Errors in Math Functions:: Known Maximum Errors in Math Functions. -* 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 circumference 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{_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, @theglibc{} -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 @theglibc{} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions return the sine of @var{x} in @code{*@var{sinx}} and the -cosine of @var{x} in @code{*@var{cosx}}, 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 C99} defines variants of the trig functions which work on -complex numbers. @Theglibc{} provides these functions, but they -are only useful if your compiler supports the new complex types defined -by the standard. -@c XXX 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@c There are calls to nan* that could trigger @mtslocale if they didn't get -@c empty strings. -These functions return the complex sine of @var{z}. -The mathematical definition of the complex sine is - -@ifnottex -@math{sin (z) = 1/(2*i) * (exp (z*i) - exp (-z*i))}. -@end ifnottex -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions return the complex cosine of @var{z}. -The mathematical definition of the complex cosine is - -@ifnottex -@math{cos (z) = 1/2 * (exp (z*i) + exp (-z*i))} -@end ifnottex -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions return the complex tangent of @var{z}. -The mathematical definition of the complex tangent is - -@ifnottex -@math{tan (z) = -i * (exp (z*i) - exp (-z*i)) / (exp (z*i) + exp (-z*i))} -@end ifnottex -@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 arcsine, arccosine and arctangent 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions compute the arcsine 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 arcsine 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions compute the arccosine 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 arccosine 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions compute the arctangent 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -This function computes the arctangent 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 C99} 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions compute the complex arcsine 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions compute the complex arccosine 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions compute the complex arctangent 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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 ISO -@deftypefun double exp10 (double @var{x}) -@comment math.h -@comment ISO -@deftypefunx float exp10f (float @var{x}) -@comment math.h -@comment ISO -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions compute @code{10} raised to the power @var{x}. -Mathematically, @code{exp10 (x)} is the same as @code{exp (x * log (10))}. - -The @code{exp10} functions are from TS 18661-4:2015; the @code{pow10} -names 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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 de-normalized, @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}) -@comment math.h -@comment ISO -@deftypefunx {long int} llogb (double @var{x}) -@comment math.h -@comment ISO -@deftypefunx {long int} llogbf (float @var{x}) -@comment math.h -@comment ISO -@deftypefunx {long int} llogbl (long double @var{x}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions are equivalent to the corresponding @code{logb} -functions except that they return signed integer values. The -@code{ilogb} functions are from ISO C99; the @code{llogb} functions -are from TS 18661-1:2014. -@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 C99}. -@end deftypevr - -@comment math.h -@comment ISO -@deftypevr Macro {long int} FP_LLOGB0 -@code{llogb} returns this value if its argument is @code{0}. The -numeric value is either @code{LONG_MIN} or @code{-LONG_MAX}. - -This macro is defined in TS 18661-1:2014. -@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 C99}. -@end deftypevr - -@comment math.h -@comment ISO -@deftypevr Macro {long int} FP_LLOGBNAN -@code{llogb} returns this value if its argument is @code{NaN}. The -numeric value is either @code{LONG_MIN} or @code{LONG_MAX}. - -This macro is defined in TS 18661-1:2014. -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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 owing -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions return 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 C99} 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions return @code{e} (the base of natural -logarithms) raised to the power of @var{z}. -Mathematically, this corresponds to the value - -@ifnottex -@math{exp (z) = exp (creal (z)) * (cos (cimag (z)) + I * sin (cimag (z)))} -@end ifnottex -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions return the natural logarithm of @var{z}. -Mathematically, this corresponds to the value - -@ifnottex -@math{log (z) = log (cabs (z)) + I * carg (z)} -@end ifnottex -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions return the base 10 logarithm of the complex value -@var{z}. Mathematically, this corresponds to the value - -@ifnottex -@math{log10 (z) = log10 (cabs (z)) + I * carg (z) / log (10)} -@end ifnottex -@tex -$$\log_{10}(z) = \log_{10}|z| + i \arg z / \log (10)$$ -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -These functions 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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}) -@safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}} -@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, or @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 non-positive 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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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. This means it is reentrant. -@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}) -@safety{@prelim{}@mtunsafe{@mtasurace{:signgam}}@asunsafe{}@acsafe{}} -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 moreover @code{lgamma} is -standardized in @w{ISO C99} while @code{gamma} is not. -@end deftypefun - -@comment math.h -@comment XPG, ISO -@deftypefun double tgamma (double @var{x}) -@comment math.h -@comment XPG, ISO -@deftypefunx float tgammaf (float @var{x}) -@comment math.h -@comment XPG, ISO -@deftypefunx {long double} tgammal (long double @var{x}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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 C99}. -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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 @var{n}, double @var{x}) -@comment math.h -@comment SVID -@deftypefunx float jnf (int @var{n}, float @var{x}) -@comment math.h -@comment SVID -@deftypefunx {long double} jnl (int @var{n}, long double @var{x}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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 @var{n}, double @var{x}) -@comment math.h -@comment SVID -@deftypefunx float ynf (int @var{n}, float @var{x}) -@comment math.h -@comment SVID -@deftypefunx {long double} ynl (int @var{n}, long double @var{x}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -@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 Errors in Math Functions -@section Known Maximum Errors in Math Functions -@cindex math errors -@cindex ulps - -This section lists the known errors of the functions in the math -library. Errors are measured in ``units of the last place''. This is a -measure for the relative error. For a number @math{z} with the -representation @math{d.d@dots{}d@mul{}2^e} (we assume IEEE -floating-point numbers with base 2) the ULP is represented by - -@tex -$${|d.d\dots d - (z/2^e)|}\over {2^{p-1}}$$ -@end tex -@ifnottex -@smallexample -|d.d...d - (z / 2^e)| / 2^(p - 1) -@end smallexample -@end ifnottex - -@noindent -where @math{p} is the number of bits in the mantissa of the -floating-point number representation. Ideally the error for all -functions is always less than 0.5ulps in round-to-nearest mode. Using -rounding bits this is also -possible and normally implemented for the basic operations. Except -for certain functions such as @code{sqrt}, @code{fma} and @code{rint} -whose results are fully specified by reference to corresponding IEEE -754 floating-point operations, and conversions between strings and -floating point, @theglibc{} does not aim for correctly rounded results -for functions in the math library, and does not aim for correctness in -whether ``inexact'' exceptions are raised. Instead, the goals for -accuracy of functions without fully specified results are as follows; -some functions have bugs meaning they do not meet these goals in all -cases. In the future, @theglibc{} may provide some other correctly -rounding functions under the names such as @code{crsin} proposed for -an extension to ISO C. - -@itemize @bullet - -@item -Each function with a floating-point result behaves as if it computes -an infinite-precision result that is within a few ulp (in both real -and complex parts, for functions with complex results) of the -mathematically correct value of the function (interpreted together -with ISO C or POSIX semantics for the function in question) at the -exact value passed as the input. Exceptions are raised appropriately -for this value and in accordance with IEEE 754 / ISO C / POSIX -semantics, and it is then rounded according to the current rounding -direction to the result that is returned to the user. @code{errno} -may also be set (@pxref{Math Error Reporting}). (The ``inexact'' -exception may be raised, or not raised, even if this is inconsistent -with the infinite-precision value.) - -@item -For the IBM @code{long double} format, as used on PowerPC GNU/Linux, -the accuracy goal is weaker for input values not exactly representable -in 106 bits of precision; it is as if the input value is some value -within 0.5ulp of the value actually passed, where ``ulp'' is -interpreted in terms of a fixed-precision 106-bit mantissa, but not -necessarily the exact value actually passed with discontiguous -mantissa bits. - -@item -For the IBM @code{long double} format, functions whose results are -fully specified by reference to corresponding IEEE 754 floating-point -operations have the same accuracy goals as other functions, but with -the error bound being the same as that for division (3ulp). -Furthermore, ``inexact'' and ``underflow'' exceptions may be raised -for all functions for any inputs, even where such exceptions are -inconsistent with the returned value, since the underlying -floating-point arithmetic has that property. - -@item -Functions behave as if the infinite-precision result computed is zero, -infinity or NaN if and only if that is the mathematically correct -infinite-precision result. They behave as if the infinite-precision -result computed always has the same sign as the mathematically correct -result. - -@item -If the mathematical result is more than a few ulp above the overflow -threshold for the current rounding direction, the value returned is -the appropriate overflow value for the current rounding direction, -with the overflow exception raised. - -@item -If the mathematical result has magnitude well below half the least -subnormal magnitude, the returned value is either zero or the least -subnormal (in each case, with the correct sign), according to the -current rounding direction and with the underflow exception raised. - -@item -Where the mathematical result underflows (before rounding) and is not -exactly representable as a floating-point value, the function does not -behave as if the computed infinite-precision result is an exact value -in the subnormal range. This means that the underflow exception is -raised other than possibly for cases where the mathematical result is -very close to the underflow threshold and the function behaves as if -it computes an infinite-precision result that does not underflow. (So -there may be spurious underflow exceptions in cases where the -underflowing result is exact, but not missing underflow exceptions in -cases where it is inexact.) - -@item -@Theglibc{} does not aim for functions to satisfy other properties of -the underlying mathematical function, such as monotonicity, where not -implied by the above goals. - -@item -All the above applies to both real and complex parts, for complex -functions. - -@end itemize - -Therefore many of the functions in the math library have errors. The -table lists the maximum error for each function which is exposed by one -of the existing tests in the test suite. The table tries to cover as much -as possible and list the actual maximum error (or at least a ballpark -figure) but this is often not achieved due to the large search space. - -The table lists the ULP values for different architectures. Different -architectures have different results since their hardware support for -floating-point operations varies and also the existing hardware support -is different. Only the round-to-nearest rounding mode is covered by -this table, and vector versions of functions are not covered. -Functions not listed do not have known errors. - -@page -@c This multitable does not fit on a single page -@include libm-err.texi - -@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. For random numbers in cryptography, -@pxref{Unpredictable Bytes}. - -You can obtain 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. - -@Theglibc{} 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 @theglibc{}, 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) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -@c Just calls random. -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}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -@c Alias to srandom. -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}) -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} -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 @theglibc{}; 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 {long int} random (void) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -@c Takes a lock and calls random_r with an automatic variable and the -@c global state, while holding a lock. -This function returns the next pseudo-random number in the sequence. -The value returned ranges from @code{0} to @code{2147483647}. - -@strong{NB:} Temporarily this function was defined to return a -@code{int32_t} value to indicate that the return value always contains -32 bits even if @code{long int} is wider. The standard demands it -differently. Users must always be aware of the 32-bit limitation, -though. -@end deftypefun - -@comment stdlib.h -@comment BSD -@deftypefun void srandom (unsigned int @var{seed}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -@c Takes a lock and calls srandom_r with an automatic variable and a -@c static buffer. There's no MT-safety issue because the static buffer -@c is internally protected by a lock, although other threads may modify -@c the set state before it is used. -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 {char *} initstate (unsigned int @var{seed}, char *@var{state}, size_t @var{size}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -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 {char *} setstate (char *@var{state}) -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}} -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. - -If the function fails the return value is @code{NULL}. -@end deftypefun - -The four functions described so far in this section all work on a state -which is shared by all threads. The state is not directly accessible to -the user and can only be modified by these functions. This makes it -hard to deal with situations where each thread should have its own -pseudo-random number generator. - -@Theglibc{} contains four additional functions which contain the -state as an explicit parameter and therefore make it possible to handle -thread-local PRNGs. Besides this there is no difference. In fact, the -four functions already discussed are implemented internally using the -following interfaces. - -The @file{stdlib.h} header contains a definition of the following type: - -@comment stdlib.h -@comment GNU -@deftp {Data Type} {struct random_data} - -Objects of type @code{struct random_data} contain the information -necessary to represent the state of the PRNG. Although a complete -definition of the type is present the type should be treated as opaque. -@end deftp - -The functions modifying the state follow exactly the already described -functions. - -@comment stdlib.h -@comment GNU -@deftypefun int random_r (struct random_data *restrict @var{buf}, int32_t *restrict @var{result}) -@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} -The @code{random_r} function behaves exactly like the @code{random} -function except that it uses and modifies the state in the object -pointed to by the first parameter instead of the global state. -@end deftypefun - -@comment stdlib.h -@comment GNU -@deftypefun int srandom_r (unsigned int @var{seed}, struct random_data *@var{buf}) -@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} -The @code{srandom_r} function behaves exactly like the @code{srandom} -function except that it uses and modifies the state in the object -pointed to by the second parameter instead of the global state. -@end deftypefun - -@comment stdlib.h -@comment GNU -@deftypefun int initstate_r (unsigned int @var{seed}, char *restrict @var{statebuf}, size_t @var{statelen}, struct random_data *restrict @var{buf}) -@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} -The @code{initstate_r} function behaves exactly like the @code{initstate} -function except that it uses and modifies the state in the object -pointed to by the fourth parameter instead of the global state. -@end deftypefun - -@comment stdlib.h -@comment GNU -@deftypefun int setstate_r (char *restrict @var{statebuf}, struct random_data *restrict @var{buf}) -@safety{@prelim{}@mtsafe{@mtsrace{:buf}}@assafe{}@acunsafe{@acucorrupt{}}} -The @code{setstate_r} function behaves exactly like the @code{setstate} -function except that it uses and modifies the state in the object -pointed to by the first parameter instead of the global 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 function. The first uses a state of -the random number generator which is shared among several functions and -by all threads of the process. The second requires 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 works. 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. - -The prototypes for these functions are in @file{stdlib.h}. -@pindex stdlib.h - - -@comment stdlib.h -@comment SVID -@deftypefun double drand48 (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -@c Uses of the static state buffer are not guarded by a lock (thus -@c @mtasurace:drand48), so they may be found or left at a -@c partially-updated state in case of calls from within signal handlers -@c or cancellation. None of this will break safety rules or invoke -@c undefined behavior, but it may affect randomness. -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]) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -@c The static buffer is just initialized with default parameters, which -@c are later read to advance the state held in xsubi. -This function returns a @code{double} value in the range of @code{0.0} -to @code{1.0} (exclusive), similarly 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 -initial use to obtain reproducible results. -@end deftypefun - -@comment stdlib.h -@comment SVID -@deftypefun {long int} lrand48 (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -The @code{lrand48} function returns 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]) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -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 updated afterwards so that subsequent calls -to this function yield different results (as is expected of a random -number generator). The array should have been initialized before the -first call to obtain reproducible results. -@end deftypefun - -@comment stdlib.h -@comment SVID -@deftypefun {long int} mrand48 (void) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -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]) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -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 methods differ in the completeness of the -information provided. - -@comment stdlib.h -@comment SVID -@deftypefun void srand48 (long int @var{seedval}) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -The @code{srand48} function sets the most significant 32 bits of the -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 than 32 bits only the lower 32 bits are used. - -Owing to this limitation, initialization of the state of this -function is 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 has 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]) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -The @code{seed48} function initializes all 48 bits of the state of the -internal random number generator from the contents of the parameter -@var{seed16v}. Here the lower 16 bits of the first element of -@var{seed16v} 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 enables you to specify even more information by allowing you to -change the parameters in the congruential formula. - -@comment stdlib.h -@comment SVID -@deftypefun void lcong48 (unsigned short int @var{param}[7]) -@safety{@prelim{}@mtunsafe{@mtasurace{:drand48}}@asunsafe{}@acunsafe{@acucorrupt{}}} -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 significant 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 -obtain 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 not manipulated directly. - -@comment stdlib.h -@comment GNU -@deftypefun int drand48_r (struct drand48_data *@var{buffer}, double *@var{result}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -This function is equivalent to the @code{drand48} function with the -difference that it does not modify the global random number generator -parameters but instead the parameters in the buffer supplied through the -pointer @var{buffer}. The random number is returned in the variable -pointed to by @var{result}. - -The return value of the function indicates 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}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -The @code{erand48_r} function works like @code{erand48}, but in addition -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 returned in -the variable pointed to by @var{result}. - -The return value is non-negative if 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}, long int *@var{result}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -This function is similar to @code{lrand48}, but in addition it takes a -pointer to a buffer describing the state of the random number generator -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}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -The @code{nrand48_r} function works like @code{nrand48} in that it -produces a random number in the 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}, long int *@var{result}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -This function is similar to @code{mrand48} but like the other reentrant -functions 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}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -The @code{jrand48_r} function is similar to @code{jrand48}. Like 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 are used the buffer of type -@code{struct drand48_data} should be initialized. The easiest way to do -this is to fill the whole buffer with null bytes, e.g. by - -@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 to use any of the functions which explicitly -initialize the buffer. Though it might be obvious how to initialize the -buffer from looking at the parameter to 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}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -The description of the random number generator represented by the -information in @var{buffer} is initialized similarly 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 their 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}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -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 re-run 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}) -@safety{@prelim{}@mtsafe{@mtsrace{:buffer}}@assafe{}@acunsafe{@acucorrupt{}}} -This function initializes all aspects of the random number generator -described in @var{buffer} with the data in @var{param}. Here it is -especially true that the function does more than just copying the -contents of @var{param} and @var{buffer}. More work is required and -therefore it is important to use this function rather than initializing -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 functions it is often the case -that the cost of the function calls themselves is not negligible. -Modern processors can often execute the operations themselves -very fast, but the function call disrupts the instruction pipeline. - -For this reason @theglibc{} provides optimizations for many of the -frequently-used math functions. When GNU CC is used and the user -activates the optimizer, several new inline functions and macros are -defined. These new functions and macros have the same names as the -library functions and so are used instead of the latter. In the case of -inline functions the compiler will decide whether it is reasonable to -use them, and this decision is usually correct. - -This means that no calls to the library functions may be necessary, and -can increase the speed of generated code significantly. The drawback is -that code size will increase, and the increase is not always negligible. - -There are two kinds of inline functions: those that give the same result -as the library functions and others that might not set @code{errno} and -might have a reduced precision and/or argument range in comparison with -the library functions. The latter inline functions are only available -if the flag @code{-ffast-math} is given to GNU CC. - -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 ensure that only library functions are used. Of -course, it can be determined for each file in the project whether -giving this option is preferable or not. - -Not all hardware implements the entire @w{IEEE 754} standard, and even -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 un-pipelined, which can more than double calculation time. -@c ***Add explanation of -lieee, -mieee. |