LIBM(3) NEWLIB LIBM(3)NAMElibmSYNOPSIS
An ANSI-C conforming mathematical library.
DESCRIPTION
This file documents an ANSI-C conforming mathematical subroutine
library.
Copyright (C) 1992, 1993, 1995, 1996-2008 Red Hat, Inc.
`libm' includes software developed at SunPro, a Sun Microsystems,
Inc. business. Permission to use, copy, modify, and distribute this
software is freely granted, provided that this notice is preserved.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.
Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, subject to the
terms of the GNU General Public License, which includes the provision
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.
LIBM ****
* Menu:
* Math:: The mathematical functions (`math.h').
* Reentrancy:: The functions in libm are not reentrant by default.
* Long Double Functions:: The long double function support of libm.
* Index::
1 Mathematical Functions (`math.h') ***********************************
This chapter groups a wide variety of mathematical functions. The cor‐
responding definitions and declarations are in `math.h'. Two defini‐
tions from `math.h' are of particular interest.
1. The representation of infinity as a `double' is defined as
`HUGE_VAL'; this number is returned on overflow by many functions.
The macro `HUGE_VALF' is a corresponding value for `float'.
2. The structure `exception' is used when you write customized error
handlers for the mathematical functions. You can customize error
handling for most of these functions by defining your own version
of `matherr'; see the section on `matherr' for details.
Since the error handling code calls `fputs', the mathematical sub‐
routines require stubs or minimal implementations for the same list of
OS subroutines as `fputs': `close', `fstat', `isatty', `lseek', `read',
`sbrk', `write'. *Note System Calls: (libc.info)syscalls, for a dis‐
cussion and for sample minimal implementations of these support subrou‐
tines.
Alternative declarations of the mathematical functions, which
exploit specific machine capabilities to operate faster--but generally
have less error checking and may reflect additional limitations on some
machines--are available when you include `fastmath.h' instead of
`math.h'.
* Menu:
* version:: Version of library
* acos:: Arccosine
* acosh:: Inverse hyperbolic cosine
* asin:: Arcsine
* asinh:: Inverse hyperbolic sine
* atan:: Arctangent
* atan2:: Arctangent of y/x
* atanh:: Inverse hyperbolic tangent
* jN:: Bessel functions (jN, yN)
* cbrt:: Cube root
* copysign:: Sign of Y, magnitude of X
* cosh:: Hyperbolic cosine
* erf:: Error function (erf, erfc)
* exp:: Exponential, base e
* exp2:: Exponential, base 2
* expm1:: Exponential, base e, of x - 1
* fabs:: Absolute value (magnitude)
* fdim:: Positive difference
* floor:: Floor and ceiling (floor, ceil)
* fma:: Floating multiply add
* fmax:: Maximum
* fmin:: Minimum
* fmod:: Floating-point remainder (modulo)
* fpclassify:: Floating-point classification macro
* frexp:: Split floating-point number
* gamma:: Logarithmic gamma function
* hypot:: Distance from origin
* ilogb:: Get exponent
* infinity:: Floating infinity
* isgreater:: Comparison macros
* ldexp:: Scale by a power of 2
* log:: Natural logarithms
* log10:: Base 10 logarithms
* log1p:: Log of 1 + X
* log2:: Base 2 logarithms
* logb:: Get exponent
* lrint:: Round to integer
* lround:: Round to integer, away from zero (lround, llround)
* matherr:: Modifiable math error handler
* modf:: Split fractional and integer parts
* nan:: Floating Not a Number
* nearbyint:: Round to integer
* nextafter:: Get next representable number
* pow:: X to the power Y
* remainder:: remainder of X divided by Y
* remquo:: Remainder and part of quotient
* rint:: Round to integer
* round:: Round to integer, away from zero
* scalbn:: Scale by a power of FLT_RADIX (2)
* signbit:: Does floating-point number have negative sign?
* sin:: Sine or cosine (sin, cos)
* sinh:: Hyperbolic sine
* sqrt:: Positive square root
* tan:: Tangent
* tanh:: Hyperbolic tangent
* trunc:: Round to integer, towards zero
1.1 Error Handling
There are four different versions of the math library routines: IEEE,
POSIX, X/Open, or SVID. The version may be selected at runtime by set‐
ting the global variable `_LIB_VERSION', defined in `math.h'. It may
be set to one of the following constants defined in `math.h': `_IEEE_',
`_POSIX_', `_XOPEN_', or `_SVID_'. The `_LIB_VERSION' variable is not
specific to any thread, and changing it will affect all threads.
The versions of the library differ only in how errors are handled.
In IEEE mode, the `matherr' function is never called, no warning
messages are printed, and `errno' is never set.
In POSIX mode, `errno' is set correctly, but the `matherr' function
is never called and no warning messages are printed.
In X/Open mode, `errno' is set correctly, and `matherr' is called,
but warning message are not printed.
In SVID mode, functions which overflow return
3.40282346638528860e+38, the maximum single-precision floating-point
value, rather than infinity. Also, `errno' is set correctly, `matherr'
is called, and, if `matherr' returns 0, warning messages are printed
for some errors. For example, by default `log(-1.0)' writes this mes‐
sage on standard error output:
log: DOMAIN error
The library is set to X/Open mode by default.
The aforementioned error reporting is the supported Newlib libm
error handling method. However, the majority of the functions are
written so as to produce the floating-point exceptions (e.g. "invalid",
"divide-by-zero") as required by the C and POSIX standards, for float‐
ing-point implementations that support them. Newlib does not provide
the floating-point exception access routines defined in the standards
for fenv.h, though, which is why they are considered unsupported. It
is mentioned in case you have separately-provided access routines so
that you are aware that they can be caused.
1.2 Standards Compliance And Portability
Most of the individual function descriptions describe the standards to
which each function complies. However, these descriptions are mostly
out of date, having been written before C99 was released. One of these
days we'll get around to updating the rest of them. (If you'd like to
help, please let us know.)
"C99" refers to ISO/IEC 9899:1999, "Programming languages-C".
"POSIX" refers to IEEE Standard 1003.1. POSIX(R) is a registered
trademark of The IEEE.
2 Reentrancy Properties of `libm' *********************************
When a libm function detects an exceptional case, `errno' may be set,
the `matherr' function may be called, and a error message may be writ‐
ten to the standard error stream. This behavior may not be reentrant.
With reentrant C libraries like the Red Hat newlib C library,
`errno' is a macro which expands to the per-thread error value. This
makes it thread safe.
When the user provides his own `matherr' function it must be reen‐
trant for the math library as a whole to be reentrant.
In normal debugged programs, there are usually no math subroutine
errors--and therefore no assignments to `errno' and no `matherr' calls;
in that situation, the math functions behave reentrantly.
Index *****
[inde] * Menu:
* acos: acos. (line
6)
* acosf: acos. (line
6)
* acosh: acosh. (line
6)
* acoshf: acosh. (line
6)
* asin: asin. (line
6)
* asinf: asin. (line
6)
* asinh: asinh. (line
6)
* asinhf: asinh. (line
6)
* atan: atan. (line
6)
* atan2: atan2. (line
6)
* atan2f: atan2. (line
6)
* atanf: atan. (line
6)
* atanh: atanh. (line
6)
* atanhf: atanh. (line
6)
* cbrt: cbrt. (line
6)
* cbrtf: cbrt. (line
6)
* ceil: floor. (line
6)
* ceilf: floor. (line
6)
* copysign: copysign. (line
6)
* copysignf: copysign. (line
6)
* cos: sin. (line
6)
* cosf: sin. (line
6)
* erf: erf. (line
6)
* erfc: erf. (line
6)
* erfcf: erf. (line
6)
* erff: erf. (line
6)
* exp: exp. (line
6)
* exp2: exp2. (line
6)
* exp2f: exp2. (line
6)
* expf: exp. (line
6)
* expm1: expm1. (line
6)
* expm1f: expm1. (line
6)
* fabs: fabs. (line
6)
* fabsf: fabs. (line
6)
* fdim: fdim. (line
6)
* fdimf: fdim. (line
6)
* finite: fpclassify. (line
6)
* finitef: fpclassify. (line
6)
* floor: floor. (line
6)
* floorf: floor. (line
6)
* fma: fma. (line
6)
* fmaf: fma. (line
6)
* fmax: fmax. (line
6)
* fmaxf: fmax. (line
6)
* fmin: fmin. (line
6)
* fminf: fmin. (line
6)
* fmod: fmod. (line
6)
* fmodf: fmod. (line
6)
* fpclassify: fpclassify. (line
6)
* frexp: frexp. (line
6)
* frexpf: frexp. (line
6)
* gamma: gamma. (line
6)
* gamma_r: gamma. (line
6)
* gammaf: gamma. (line
6)
* gammaf_r: gamma. (line
6)
* hypot: hypot. (line
6)
* hypotf: hypot. (line
6)
* ilogb: ilogb. (line
6)
* ilogbf: ilogb. (line
6)
* infinity: infinity. (line
6)
* infinityf: infinity. (line
6)
* isfinite: fpclassify. (line
6)
* isgreater: isgreater. (line
6)
* isgreaterequal: isgreater. (line
6)
* isinf: fpclassify. (line
6)
* isinff: fpclassify. (line
6)
* isless: isgreater. (line
6)
* islessequal: isgreater. (line
6)
* islessgreater: isgreater. (line
6)
* isnan: fpclassify. (line
6)
* isnanf: fpclassify. (line
6)
* isnormal: fpclassify. (line
6)
* isunordered: isgreater. (line
6)
* j0: jN. (line
6)
* j0f: jN. (line
6)
* j1: jN. (line
6)
* j1f: jN. (line
6)
* jn: jN. (line
6)
* jnf: jN. (line
6)
* ldexp: ldexp. (line
6)
* ldexpf: ldexp. (line
6)
* lgamma: gamma. (line
6)
* lgamma_r: gamma. (line
6)
* lgammaf: gamma. (line
6)
* lgammaf_r: gamma. (line
6)
* llrint: lrint. (line
6)
* llrintf: lrint. (line
6)
* llround: lround. (line
6)
* llroundf: lround. (line
6)
* log: log. (line
6)
* log10: log10. (line
6)
* log10f: log10. (line
6)
* log1p: log1p. (line
6)
* log1pf: log1p. (line
6)
* log2: log2. (line
6)
* log2f: log2. (line
6)
* logb: logb. (line
6)
* logbf: logb. (line
6)
* logf: log. (line
6)
* lrint: lrint. (line
6)
* lrintf: lrint. (line
6)
* lround: lround. (line
6)
* lroundf: lround. (line
6)
* matherr: matherr. (line
6)
* matherr and reentrancy: Reentrancy. (line
6)
* modf: modf. (line
6)
* modff: modf. (line
6)
* nan: nan. (line
6)
* nanf: nan. (line
6)
* nearbyint: nearbyint. (line
6)
* nearbyintf: nearbyint. (line
6)
* nextafter: nextafter. (line
6)
* nextafterf: nextafter. (line
6)
* OS stubs: Math. (line
19)
* pow: pow. (line
6)
* powf: pow. (line
6)
* reentrancy: Reentrancy. (line
6)
* remainder: remainder. (line
6)
* remainderf: remainder. (line
6)
* remquo: remquo. (line
6)
* remquof: remquo. (line
6)
* rint: rint. (line
6)
* rintf: rint. (line
6)
* round: round. (line
6)
* roundf: round. (line
6)
* scalbln: scalbn. (line
6)
* scalblnf: scalbn. (line
6)
* scalbn: scalbn. (line
6)
* scalbnf: scalbn. (line
6)
* signbit: signbit. (line
6)
* sin: sin. (line
6)
* sinf: sin. (line
6)
* sinh: sinh. (line
6)
* sinhf: sinh. (line
6)
* sqrt: sqrt. (line
6)
* sqrtf: sqrt. (line
6)
* stubs: Math. (line
19)
* support subroutines: Math. (line
19)
* system calls: Math. (line
19)
* tan: tan. (line
6)
* tanf: tan. (line
6)
* tanh: tanh. (line
6)
* tanhf: tanh. (line
6)
* tgamma: gamma. (line
6)
* tgammaf: gamma. (line
6)
* trunc: trunc. (line
6)
* truncf: trunc. (line
6)
* y0: jN. (line
6)
* y0f: jN. (line
6)
* y1: jN. (line
6)
* y1f: jN. (line
6)
* yn: jN. (line
6)
* ynf: jN. (line
6)
SEE ALSO
The full documentation for is maintained as a Texinfo manual. If info
and are properly installed at your site, the command
info
will give you access to the complete manual.
NEWLIB April 2010 LIBM(3)
