Tribblix: manual page: libm.3lib

LIBM(3LIB) Interface Libraries LIBM(3LIB)

NAME

libm - C math library

SYNOPSIS

c99 [ flag... ] file... -lm [ library... ]

DESCRIPTION

Functions in this library provide common elementary mathematical
functions and floating point environment routines defined by System
V, ANSI C, POSIX, and so on. See standards(7). Additional functions
in this library provide extended support for handling floating point
exceptions.

INTERFACES

The shared object libm.so.2 provides the public interfaces defined
below. See Intro(3) for additional information on shared object
interfaces.

acos acosf
acosh acoshf
acoshl acosl
asin asinf
asinh asinhf
asinhl asinl
atan atan2
atan2f atan2l
atanf atanh
atanhf atanhl
atanl cabs
cabsf cabsl
cacos cacosf
cacosh cacoshf
cacoshl cacosl
carg cargf
cargl casin
casinf casinh
casinhf casinhl
casinl catan
catanf catanh
catanhf catanhl
catanl cbrt
cbrtf cbrtl
ccos ccosf
ccosh ccoshf
ccoshl ccosl
ceil ceilf
ceill cexp
cexpf cexpl
cimag cimagf
cimagl clog
clogf clogl
conj conjf
conjl copysign
copysignf copysignl
cos cosf
cosh coshf
coshl cosl
cpow cpowf
cpowl cproj
cprojf cprojl
creal crealf
creall csin
csinf csinh
csinhf csinhl
csinl csqrt
csqrtf csqrtl
ctan ctanf
ctanh ctanhf
ctanhl ctanl
erf erfc
erfcf erfcl
erff erfl
exp exp2
exp2f exp2l
expf expl
expm1 expm1f
expm1l fabs
fabsf fabsl
fdim fdimf
fdiml feclearexcept
fegetenv fegetexceptflag
fegetround feholdexcept
feraiseexcept fesetenv
fesetexceptflag fesetround
fetestexcept feupdateenv
fex_get_handling fex_get_log
fex_get_log_depth fex_getexcepthandler
fex_log_entry fex_merge_flags
fex_set_handling fex_set_log
fex_set_log_depth fex_setexcepthandler
floor floorf
floorl fma
fmaf fmal
fmax fmaxf
fmaxl fmin
fminf fminl
fmod fmodf
fmodl frexp
frexpf frexpl
gamma gamma_r
gammaf gammaf_r
gammal gammal_r
hypot hypotf
hypotl ilogb
ilogbf ilogbl
isnan j0
j0f j0l
j1 j1f
j1l jn
jnf jnl
ldexp ldexpf
ldexpl lgamma
lgamma_r lgammaf
lgammaf_r lgammal
lgammal_r llrint
llrintf llrintl
llround llroundf
llroundl log
log10 log10f
log10l log1p
log1pf log1pl
log2 log2f
log2l logb
logbf logbl
logf logl
lrint lrintf
lrintl lround
lroundf lroundl
matherr modf
modff modfl
nan nanf
nanl nearbyint
nearbyintf nearbyintl
nextafter nextafterf
nextafterl nexttoward
nexttowardf nexttowardl
pow powf
powl remainder
remainderf remainderl
remquo remquof
remquol rint
rintf rintl
round roundf
roundl scalb
scalbf scalbl
scalbln scalblnf
scalblnl scalbn
scalbnf scalbnl
signgam signgamf
signgaml significand
significandf significandl
sin sincos
sincosf sincosl
sinf sinh
sinhf sinhl
sinl sqrt
sqrtf sqrtl
tan tanf
tanh tanhf
tanhl tanl
tgamma tgammaf
tgammal trunc
truncf truncl
y0 y0f
y0l y1
y1f y1l
yn ynf
ynl

The following interfaces are unique to the x86 and amd64 versions of
this library:

fegetprec fesetprec

ACCURACY

ISO/IEC 9899:1999, also known as C99, specifies the functions listed
in the following tables and states that the accuracy of these
functions is "implementation-defined". The information below
characterizes the accuracy of these functions as implemented in
libm.so.2. For each function, the tables provide an upper bound on
the largest error possible for any argument and the largest error
actually observed among a large sample of arguments. Errors are
expressed in "units in the last place", or ulps, relative to the
exact function value for each argument (regarding the argument as
exact). Ulps depend on the precision of the floating point format: if
y is the exact function value, x and x' are adjacent floating point
numbers such that x < y < x', and x'' is the computed function value,
then provided x, x', and x'' all lie in the same binade, the error in
x'' is |y - x''| / |x - x'| ulps. In particular, when the error is
less than one ulp, the computed value is one of the two floating
point numbers adjacent to the exact value.

The bounds and observed errors listed below apply only in the default
floating point modes. Specifically, on SPARC, these bounds assume the
rounding direction is round-to-nearest and non-standard mode is
disabled. On x86, the bounds assume the rounding direction is round-
to-nearest and the rounding precision is round-to-64-bits. Moreover,
on x86, floating point function values are returned in a floating
point register in extended double precision format, but the bounds
below assume that the result value is then stored to memory in the
format corresponding to the function's type. On amd64, the bounds
assume the rounding direction in both the x87 floating point control
word and the MXCSR is round-to-nearest, the rounding precision in the
x87 control word is round-to-64-bits, and the FTZ and DAZ modes are
disabled.

The error bounds listed below are believed to be correct, but smaller
bounds might be proved later. The observed errors are the largest
ones currently known, but larger errors might be discovered later.
Numbers in the notes column refer to the notes following the tables.

Real Functions

Single precision real functions (SPARC, x86, and amd64)

error bound largest error
function (ulps) observed (ulps) notes
acosf 1.0 < 1
acoshf 1.0 < 1
asinf 1.0 < 1
asinhf 1.0 < 1
atanf 1.0 < 1
atan2f 1.0 < 1
atanhf 1.0 < 1
cbrtf 1.0 < 1
cosf 1.0 < 1
coshf 1.0 < 1
erff 1.0 < 1
erfcf 1.0 < 1
expf 1.0 < 1
exp2f 1.0 < 1
expm1f 1.0 < 1
hypotf 1.0 < 1
lgammaf 1.0 < 1
logf 1.0 < 1
log10f 1.0 < 1
log1pf 1.0 < 1
log2f 1.0 < 1
powf 1.0 < 1
sinf 1.0 < 1
sinhf 1.0 < 1
sqrtf 0.5 0.500 [1]
tanf 1.0 < 1
tanhf 1.0 < 1
tgammaf 1.0 < 1

Double precision real functions (SPARC and amd64)

error bound largest error
function (ulps) observed (ulps) notes
acos 1.0 < 1
acosh 4.0 1.878
asin 1.0 < 1
asinh 7.0 1.653
atan 1.0 <1
atan2 2.5 1.475
atanh 4.0 1.960
cbrt 1.0 < 1
cos 1.0 < 1
cosh 3.0 1.168
erf 4.0 0.959
erfc 6.0 2.816
exp 1.0 < 1
exp2 2.0 1.050
expm1 1.0 < 1
hypot 1.0 < 1
lgamma 61.5 5.629 [2]
log 1.0 < 1
log10 3.5 1.592
log1p 1.0 < 1
log2 1.0 < 1
pow 1.0 < 1
sin 1.0 < 1
sinh 4.0 2.078
sqrt 0.5 0.500 [1]
tan 1.0 < 1
tanh 3.5 2.136
tgamma 1.0 < 1

Double precision real functions (x86)

error bound largest error
function (ulps) observed (ulps) notes
acos 1.0 < 1
acosh 4.0 1.694
asin 1.0 < 1
asinh 7.0 1.493
atan 1.0 < 1
atan2 1.0 < 1
atanh 4.0 1.445
cbrt 1.0 < 1
cos 1.0 < 1
cosh 3.0 1.001
erf 4.0 0.932
erfc 6.0 2.728
exp 1.0 < 1
exp2 1.0 < 1
expm1 1.0 < 1
hypot 1.0 < 1
lgamma 61.5 2.654 [2]
log 1.0 < 1
log10 1.0 < 1
log1p 1.0 < 1
log2 1.0 < 1
pow 1.0 < 1
sin 1.0 < 1
sinh 4.0 1.458
sqrt 0.5003 0.500 [1]
tan 1.0 < 1
tanh 3.5 1.592
tgamma 1.0 < 1

Quadruple precision real functions (SPARC)

error bound largest error
function (ulps) observed (ulps) notes
acosl 3.5 1.771
acoshl 8.0 1.275
asinl 4.0 2.007
asinhl 9.0 1.823
atanl 1.0 < 1
atan2l 2.5 1.102
atanhl 4.0 1.970
cbrtl 1.0 < 1
cosl 1.0 < 1
coshl 3.5 0.985
erfl 2.0 0.779
erfcl 68.5 13.923
expl 1.0 < 1
exp2l 2.0 0.714
expm1l 2.0 1.020
hypotl 1.0 < 1
lgammal 18.5 2.916 [2]
logl 1.0 < 1
log10l 3.5 1.156
log1pl 2.0 1.216
log2l 3.5 1.675
powl 1.0 < 1
sinl 1.0 < 1
sinhl 4.5 1.589
sqrtl 0.5 0.500 [1]
tanl 4.5 2.380
tanhl 4.5 1.692
tgammal 1.0 < 1

Extended precision real functions (x86 and amd64)

error bound largest error
function (ulps) observed (ulps) notes
acosl 3.0 1.868
acoshl 8.0 2.352
asinl 3.0 1.716
asinhl 9.0 2.346
atanl 1.0 < 1
atan2l 1.0 < 1
atanhl 4.0 2.438
cbrtl 1.0 < 1
cosl 1.0 < 1
coshl 3.5 1.288
erfl 1.0 < 1
erfcl 78.5 13.407
expl 3.5 1.291
exp2l 1.5 0.807
expm1l 4.0 1.936
hypotl 3.5 2.087
lgammal 22.5 4.197 [2]
logl 2.0 0.881
log10l 2.0 1.284
log1pl 5.0 2.370
log2l 1.0 < 1
powl 32770.0 4478.132
sinl 1.0 < 1
sinhl 4.5 2.356
sqrtl 0.5 0.500 [1]
tanl 4.5 2.366
tanhl 4.5 2.417
tgammal 1.0 < 1

Notes:
[1]
On SPARC and amd64, sqrtf, sqrt, and sqrtl are correctly
rounded in accordance with IEEE 754. On x86, sqrtl is
correctly rounded, sqrtf is correctly rounded provided the
result is narrowed to single precision as discussed above, but
sqrt might not be correctly rounded due to "double rounding":
when the intermediate value computed to extended precision
lies exactly halfway between two representable numbers in
double precision, the result of rounding the intermediate
value to double precision is determined by the round-ties-to-
even rule. If this rule causes the second rounding to round in
the same direction as the first, the net rounding error can
exceed 0.5 ulps. (The error is bounded instead by 0.5*(1 +
2^-11) ulps.)

[2]
Error bounds for lgamma and lgammal apply only for positive
arguments.

Complex functions

The real-valued complex functions cabsf, cabs, cabsl, cargf, carg,
and cargl are equivalent to the real functions hypotf, hypot, hypotl,
atan2f, atan2, and atan2l, respectively. The error bounds and
observed errors given above for the latter functions also apply to
the former.

The complex functions listed below are complex-valued. For each
function, the error bound shown applies separately to both the real
and imaginary parts of the result. (For example, both the real and
imaginary parts of cacosf(z) are accurate to within 1 ulp regardless
of their magnitudes.) Similarly, the largest observed error shown is
the largest error found in either the real or the imaginary part of
the result.

Single precision complex functions (SPARC and amd64)

error bound largest error
function (ulps) observed (ulps) notes
cacosf, cacoshf 1 < 1 [1]
casinf, casinhf 1 < 1
catanf, catanhf 6 < 1
ccosf, ccoshf 10 2.012
cexpf 3 2.239
clogf 3 < 1
cpowf -- < 1 [2]
csinf, csinhf 10 2.009
csqrtf 4 < 1
ctanf, ctanhf 13 6.987

Single precision complex functions (x86)

error bound largest error
function (ulps) observed (ulps) notes
cacosf, cacoshf 1 < 1 [1]
casinf, casinhf 1 < 1
catanf, catanhf 6 < 1
ccosf, ccoshf 10 1.984
cexpf 3 1.984
clogf 3 < 1
cpowf -- < 1 [2]
csinf, csinhf 10 1.973
csqrtf 4 < 1
ctanf, ctanhf 13 4.657

Double precision complex functions (SPARC and amd64)

error bound largest error
function (ulps) observed (ulps) notes
cacos, cacosh 9 3.831 [1]
casin, casinh 9 3.732
catan, catanh 6 4.179
ccos, ccosh 10 3.832
cexp 3 2.255
clog 3 2.870
cpow - - [2]
csin, csinh 10 3.722
csqrt 4 3.204
ctan, ctanh 13 7.143

Double precision complex functions (x86)

error bound largest error
function (ulps) observed (ulps) notes
cacos, cacosh 9 3.624 [1]
casin, casinh 9 3.624
catan, catanh 6 2.500
ccos, ccosh 10 2.929
cexp 3 2.147
clog 3 1.927
cpow - - [2]
csin, csinh 10 2.918
csqrt 4 1.914
ctan, ctanh 13 4.630

Quadruple precision complex functions (SPARC)

error bound largest error
function (ulps) observed (ulps) notes
cacosl, cacoshl 9 3 [1]
casinl, casinhl 9 3
catanl, catanhl 6 3
ccosl, ccoshl 10 3
cexpl 3 2
clogl 3 2
cpowl - - [2]
csinl, csinhl 10 3
csqrtl 4 3
ctanl, ctanhl 13 5

Extended precision complex functions (x86 and amd64)

error bound largest error
function (ulps) observed (ulps) notes
cacosl, cacoshl 9 2 [1]
casinl, casinhl 9 2
catanl, catanhl 6 2
ccosl, ccoshl 10 3
cexpl 3 2.699
clogl 3 1
cpowl - - [2]
csinl, csinhl 10 3
csqrtl 4 1.452
ctanl, ctanhl 13 5

Notes:
[1]
The complex hyperbolic trigonometric functions are equivalent
by symmetries to their circular trigonometric counterparts.
Because the implementations of these functions exploit these
symmetries, corresponding functions have the same error bounds
and observed errors.

[2]
For large arguments, the results computed by cpowf, cpow, and
cpowl can have unbounded relative error. It might be possible
to give error bounds for specific domains, but no such bounds
are currently available. The observed errors shown are for
the domain {(z,w) : max(|Re z|, |Im z|, |Re w|, |Im w|) <= 1}.

FILES

/lib/libm.so.2
shared object

/lib/64/libm.so.2
64-bit shared object

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:

+----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+----------------------------+-----------------------------+
|MT-Level | Safe with exceptions |
+----------------------------+-----------------------------+

As described on the lgamma(3M) manual page, gamma() and lgamma() and
their float and long double counterparts are Unsafe. All other
functions in libm.so.2 are MT-Safe.