@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}.

@Theglibc{} also provides @code{_Float@var{N}} and

@code{_Float@var{N}x} types.  These types are defined in @w{ISO/IEC TS

18661-3}, which extends @w{ISO C} and defines floating-point types that

are not machine-dependent.  When such a type, such as @code{_Float128},

is supported by @theglibc{}, extra variants for most of the mathematical

functions provided for @code{double}, @code{float}, and @code{long

double} are also provided for the supported type.  Throughout this

manual, the @code{_Float@var{N}} and @code{_Float@var{N}x} variants of

these functions are described along with the @code{double},

@code{float}, and @code{long double} variants and they come from

@w{ISO/IEC TS 18661-3}, unless explicitly stated otherwise.

Support for @code{_Float@var{N}} or @code{_Float@var{N}x} types is

provided for @code{_Float32}, @code{_Float64} and @code{_Float32x} on

all platforms.

It is also provided for @code{_Float128} and @code{_Float64x} on

powerpc64le (PowerPC 64-bits little-endian), x86_64, x86, ia64,

aarch64, alpha, mips64, riscv, s390 and sparc.

@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.

Likewise, @theglibc{} also defines these constants with the types

@code{_Float@var{N}} and @code{_Float@var{N}x} for the machines that

have support for such types enabled (@pxref{Mathematics}) and if

@code{_GNU_SOURCE} is defined.  When available, the macros names are

appended with @samp{f@var{N}} or @samp{f@var{N}x}, such as @samp{f128}

for the type @code{_Float128}.

@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)}.

@deftypefun double sin (double @var{x})

@deftypefunx float sinf (float @var{x})

@deftypefunx {long double} sinl (long double @var{x})

@deftypefunx _FloatN sinfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx sinfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{sinfN, TS 18661-3:2015, math.h}

@standardsx{sinfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double cos (double @var{x})

@deftypefunx float cosf (float @var{x})

@deftypefunx {long double} cosl (long double @var{x})

@deftypefunx _FloatN cosfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx cosfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{cosfN, TS 18661-3:2015, math.h}

@standardsx{cosfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double tan (double @var{x})

@deftypefunx float tanf (float @var{x})

@deftypefunx {long double} tanl (long double @var{x})

@deftypefunx _FloatN tanfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx tanfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{tanfN, TS 18661-3:2015, math.h}

@standardsx{tanfNx, TS 18661-3:2015, math.h}

@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.

@deftypefun void sincos (double @var{x}, double *@var{sinx}, double *@var{cosx})

@deftypefunx void sincosf (float @var{x}, float *@var{sinx}, float *@var{cosx})

@deftypefunx void sincosl (long double @var{x}, long double *@var{sinx}, long double *@var{cosx})

@deftypefunx _FloatN sincosfN (_Float@var{N} @var{x}, _Float@var{N} *@var{sinx}, _Float@var{N} *@var{cosx})

@deftypefunx _FloatNx sincosfNx (_Float@var{N}x @var{x}, _Float@var{N}x *@var{sinx}, _Float@var{N}x *@var{cosx})

@standards{GNU, math.h}

@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}.

All these functions, including the @code{_Float@var{N}} and

@code{_Float@var{N}x} variants, are GNU extensions.  Portable programs

should be prepared to cope with their 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.)

@deftypefun {complex double} csin (complex double @var{z})

@deftypefunx {complex float} csinf (complex float @var{z})

@deftypefunx {complex long double} csinl (complex long double @var{z})

@deftypefunx {complex _FloatN} csinfN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} csinfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{csinfN, TS 18661-3:2015, complex.h}

@standardsx{csinfNx, TS 18661-3:2015, complex.h}

@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

@deftypefun {complex double} ccos (complex double @var{z})

@deftypefunx {complex float} ccosf (complex float @var{z})

@deftypefunx {complex long double} ccosl (complex long double @var{z})

@deftypefunx {complex _FloatN} ccosfN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} ccosfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{ccosfN, TS 18661-3:2015, complex.h}

@standardsx{ccosfNx, TS 18661-3:2015, complex.h}

@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

@deftypefun {complex double} ctan (complex double @var{z})

@deftypefunx {complex float} ctanf (complex float @var{z})

@deftypefunx {complex long double} ctanl (complex long double @var{z})

@deftypefunx {complex _FloatN} ctanfN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} ctanfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{ctanfN, TS 18661-3:2015, complex.h}

@standardsx{ctanfNx, TS 18661-3:2015, complex.h}

@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.

@deftypefun double asin (double @var{x})

@deftypefunx float asinf (float @var{x})

@deftypefunx {long double} asinl (long double @var{x})

@deftypefunx _FloatN asinfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx asinfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{asinfN, TS 18661-3:2015, math.h}

@standardsx{asinfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double acos (double @var{x})

@deftypefunx float acosf (float @var{x})

@deftypefunx {long double} acosl (long double @var{x})

@deftypefunx _FloatN acosfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx acosfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{acosfN, TS 18661-3:2015, math.h}

@standardsx{acosfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double atan (double @var{x})

@deftypefunx float atanf (float @var{x})

@deftypefunx {long double} atanl (long double @var{x})

@deftypefunx _FloatN atanfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx atanfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{atanfN, TS 18661-3:2015, math.h}

@standardsx{atanfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double atan2 (double @var{y}, double @var{x})

@deftypefunx float atan2f (float @var{y}, float @var{x})

@deftypefunx {long double} atan2l (long double @var{y}, long double @var{x})

@deftypefunx _FloatN atan2fN (_Float@var{N} @var{y}, _Float@var{N} @var{x})

@deftypefunx _FloatNx atan2fNx (_Float@var{N}x @var{y}, _Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{atan2fN, TS 18661-3:2015, math.h}

@standardsx{atan2fNx, TS 18661-3:2015, math.h}

@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.

@deftypefun {complex double} casin (complex double @var{z})

@deftypefunx {complex float} casinf (complex float @var{z})

@deftypefunx {complex long double} casinl (complex long double @var{z})

@deftypefunx {complex _FloatN} casinfN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} casinfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{casinfN, TS 18661-3:2015, complex.h}

@standardsx{casinfNx, TS 18661-3:2015, complex.h}

@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

@deftypefun {complex double} cacos (complex double @var{z})

@deftypefunx {complex float} cacosf (complex float @var{z})

@deftypefunx {complex long double} cacosl (complex long double @var{z})

@deftypefunx {complex _FloatN} cacosfN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} cacosfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{cacosfN, TS 18661-3:2015, complex.h}

@standardsx{cacosfNx, TS 18661-3:2015, complex.h}

@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

@deftypefun {complex double} catan (complex double @var{z})

@deftypefunx {complex float} catanf (complex float @var{z})

@deftypefunx {complex long double} catanl (complex long double @var{z})

@deftypefunx {complex _FloatN} catanfN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} catanfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{catanfN, TS 18661-3:2015, complex.h}

@standardsx{catanfNx, TS 18661-3:2015, complex.h}

@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

@deftypefun double exp (double @var{x})

@deftypefunx float expf (float @var{x})

@deftypefunx {long double} expl (long double @var{x})

@deftypefunx _FloatN expfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx expfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{expfN, TS 18661-3:2015, math.h}

@standardsx{expfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double exp2 (double @var{x})

@deftypefunx float exp2f (float @var{x})

@deftypefunx {long double} exp2l (long double @var{x})

@deftypefunx _FloatN exp2fN (_Float@var{N} @var{x})

@deftypefunx _FloatNx exp2fNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{exp2fN, TS 18661-3:2015, math.h}

@standardsx{exp2fNx, TS 18661-3:2015, math.h}

@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

@deftypefun double exp10 (double @var{x})

@deftypefunx float exp10f (float @var{x})

@deftypefunx {long double} exp10l (long double @var{x})

@deftypefunx _FloatN exp10fN (_Float@var{N} @var{x})

@deftypefunx _FloatNx exp10fNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{exp10fN, TS 18661-4:2015, math.h}

@standardsx{exp10fNx, TS 18661-4:2015, math.h}

@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.

@end deftypefun

@deftypefun double log (double @var{x})

@deftypefunx float logf (float @var{x})

@deftypefunx {long double} logl (long double @var{x})

@deftypefunx _FloatN logfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx logfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{logfN, TS 18661-3:2015, math.h}

@standardsx{logfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double log10 (double @var{x})

@deftypefunx float log10f (float @var{x})

@deftypefunx {long double} log10l (long double @var{x})

@deftypefunx _FloatN log10fN (_Float@var{N} @var{x})

@deftypefunx _FloatNx log10fNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{log10fN, TS 18661-3:2015, math.h}

@standardsx{log10fNx, TS 18661-3:2015, math.h}

@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

@deftypefun double log2 (double @var{x})

@deftypefunx float log2f (float @var{x})

@deftypefunx {long double} log2l (long double @var{x})

@deftypefunx _FloatN log2fN (_Float@var{N} @var{x})

@deftypefunx _FloatNx log2fNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{log2fN, TS 18661-3:2015, math.h}

@standardsx{log2fNx, TS 18661-3:2015, math.h}

@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

@deftypefun double logb (double @var{x})

@deftypefunx float logbf (float @var{x})

@deftypefunx {long double} logbl (long double @var{x})

@deftypefunx _FloatN logbfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx logbfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{logbfN, TS 18661-3:2015, math.h}

@standardsx{logbfNx, TS 18661-3:2015, math.h}

@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

@deftypefun int ilogb (double @var{x})

@deftypefunx int ilogbf (float @var{x})

@deftypefunx int ilogbl (long double @var{x})

@deftypefunx int ilogbfN (_Float@var{N} @var{x})

@deftypefunx int ilogbfNx (_Float@var{N}x @var{x})

@deftypefunx {long int} llogb (double @var{x})

@deftypefunx {long int} llogbf (float @var{x})

@deftypefunx {long int} llogbl (long double @var{x})

@deftypefunx {long int} llogbfN (_Float@var{N} @var{x})

@deftypefunx {long int} llogbfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{ilogbfN, TS 18661-3:2015, math.h}

@standardsx{ilogbfNx, TS 18661-3:2015, math.h}

@standardsx{llogbfN, TS 18661-3:2015, math.h}

@standardsx{llogbfNx, TS 18661-3:2015, math.h}

@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}, @code{ilogbf}, and @code{ilogbl} functions are from ISO

C99; the @code{llogb}, @code{llogbf}, @code{llogbl} functions are from

TS 18661-1:2014; the @code{ilogbfN}, @code{ilogbfNx}, @code{llogbfN},

and @code{llogbfNx} functions are from TS 18661-3:2015.

@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.

@deftypevr Macro int FP_ILOGB0

@standards{ISO, math.h}

@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

@deftypevr Macro {long int} FP_LLOGB0

@standards{ISO, math.h}

@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

@deftypevr Macro int FP_ILOGBNAN

@standards{ISO, math.h}

@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

@deftypevr Macro {long int} FP_LLOGBNAN

@standards{ISO, math.h}

@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

@deftypefun double pow (double @var{base}, double @var{power})

@deftypefunx float powf (float @var{base}, float @var{power})

@deftypefunx {long double} powl (long double @var{base}, long double @var{power})

@deftypefunx _FloatN powfN (_Float@var{N} @var{base}, _Float@var{N} @var{power})

@deftypefunx _FloatNx powfNx (_Float@var{N}x @var{base}, _Float@var{N}x @var{power})

@standards{ISO, math.h}

@standardsx{powfN, TS 18661-3:2015, math.h}

@standardsx{powfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double sqrt (double @var{x})

@deftypefunx float sqrtf (float @var{x})

@deftypefunx {long double} sqrtl (long double @var{x})

@deftypefunx _FloatN sqrtfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx sqrtfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{sqrtfN, TS 18661-3:2015, math.h}

@standardsx{sqrtfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double cbrt (double @var{x})

@deftypefunx float cbrtf (float @var{x})

@deftypefunx {long double} cbrtl (long double @var{x})

@deftypefunx _FloatN cbrtfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx cbrtfNx (_Float@var{N}x @var{x})

@standards{BSD, math.h}

@standardsx{cbrtfN, TS 18661-3:2015, math.h}

@standardsx{cbrtfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double hypot (double @var{x}, double @var{y})

@deftypefunx float hypotf (float @var{x}, float @var{y})

@deftypefunx {long double} hypotl (long double @var{x}, long double @var{y})

@deftypefunx _FloatN hypotfN (_Float@var{N} @var{x}, _Float@var{N} @var{y})

@deftypefunx _FloatNx hypotfNx (_Float@var{N}x @var{x}, _Float@var{N}x @var{y})

@standards{ISO, math.h}

@standardsx{hypotfN, TS 18661-3:2015, math.h}

@standardsx{hypotfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double expm1 (double @var{x})

@deftypefunx float expm1f (float @var{x})

@deftypefunx {long double} expm1l (long double @var{x})

@deftypefunx _FloatN expm1fN (_Float@var{N} @var{x})

@deftypefunx _FloatNx expm1fNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{expm1fN, TS 18661-3:2015, math.h}

@standardsx{expm1fNx, TS 18661-3:2015, math.h}

@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

@deftypefun double log1p (double @var{x})

@deftypefunx float log1pf (float @var{x})

@deftypefunx {long double} log1pl (long double @var{x})

@deftypefunx _FloatN log1pfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx log1pfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{log1pfN, TS 18661-3:2015, math.h}

@standardsx{log1pfNx, TS 18661-3:2015, math.h}

@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.

@deftypefun {complex double} cexp (complex double @var{z})

@deftypefunx {complex float} cexpf (complex float @var{z})

@deftypefunx {complex long double} cexpl (complex long double @var{z})

@deftypefunx {complex _FloatN} cexpfN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} cexpfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{cexpfN, TS 18661-3:2015, complex.h}

@standardsx{cexpfNx, TS 18661-3:2015, complex.h}

@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

@deftypefun {complex double} clog (complex double @var{z})

@deftypefunx {complex float} clogf (complex float @var{z})

@deftypefunx {complex long double} clogl (complex long double @var{z})

@deftypefunx {complex _FloatN} clogfN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} clogfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{clogfN, TS 18661-3:2015, complex.h}

@standardsx{clogfNx, TS 18661-3:2015, complex.h}

@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

@deftypefun {complex double} clog10 (complex double @var{z})

@deftypefunx {complex float} clog10f (complex float @var{z})

@deftypefunx {complex long double} clog10l (complex long double @var{z})

@deftypefunx {complex _FloatN} clog10fN (complex _Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} clog10fNx (complex _Float@var{N}x @var{z})

@standards{GNU, complex.h}

@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

All these functions, including the @code{_Float@var{N}} and

@code{_Float@var{N}x} variants, are GNU extensions.

@end deftypefun

@deftypefun {complex double} csqrt (complex double @var{z})

@deftypefunx {complex float} csqrtf (complex float @var{z})

@deftypefunx {complex long double} csqrtl (complex long double @var{z})

@deftypefunx {complex _FloatN} csqrtfN (_Float@var{N} @var{z})

@deftypefunx {complex _FloatNx} csqrtfNx (complex _Float@var{N}x @var{z})

@standards{ISO, complex.h}

@standardsx{csqrtfN, TS 18661-3:2015, complex.h}

@standardsx{csqrtfNx, TS 18661-3:2015, complex.h}

@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

@deftypefun {complex double} cpow (complex double @var{base}, complex double @var{power})

@deftypefunx {complex float} cpowf (complex float @var{base}, complex float @var{power})

@deftypefunx {complex long double} cpowl (complex long double @var{base}, complex long double @var{power})

@deftypefunx {complex _FloatN} cpowfN (complex _Float@var{N} @var{base}, complex _Float@var{N} @var{power})

@deftypefunx {complex _FloatNx} cpowfNx (complex _Float@var{N}x @var{base}, complex _Float@var{N}x @var{power})

@standards{ISO, complex.h}

@standardsx{cpowfN, TS 18661-3:2015, complex.h}

@standardsx{cpowfNx, TS 18661-3:2015, complex.h}

@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}.

@deftypefun double sinh (double @var{x})

@deftypefunx float sinhf (float @var{x})

@deftypefunx {long double} sinhl (long double @var{x})

@deftypefunx _FloatN sinhfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx sinhfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{sinhfN, TS 18661-3:2015, math.h}

@standardsx{sinhfNx, TS 18661-3:2015, math.h}

@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

@deftypefun double cosh (double @var{x})

@deftypefunx float coshf (float @var{x})

@deftypefunx {long double} coshl (long double @var{x})

@deftypefunx _FloatN coshfN (_Float@var{N} @var{x})

@deftypefunx _FloatNx coshfNx (_Float@var{N}x @var{x})

@standards{ISO, math.h}

@standardsx{coshfN, TS 18661-3:2015, math.h}

@standardsx{coshfNx, TS 18661-3:2015, math.h}

@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}}.