libm - man pages section 3: Library Interfaces and Headers

Language:

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 x64 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 x64, 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 x64)

	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 x64)

	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 x64)

	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 x64, 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 x64)

	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 x64)

	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 x64)

	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
Availability	system/library/math
MT-Level	Safe with exceptions
Interface Stability	Committed

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.

man pages section 3: Library Interfaces and Headers