MATH(3) BSD Programmer's Manual MATH(3)NAMEmath - introduction to mathematical library functions
SYNOPSIS
cc ... -lm ...
#include <math.h>
DESCRIPTION
These functions constitute the C math library, libm. The link editor
ld(1) searches this library under the -lm option. Declarations for these
functions may be obtained from the header file <math.h>.
The header <math.h> also declares the macro HUGE_VAL. On current archi-
tectures, this value is a constant IEEE 754 positive infinity.
LIST OF FUNCTIONS
See the individual manual pages for the meanings of the various func-
tions:
double acos(double);
float acosf(float);
double acosh(double);
float acoshf(float);
double asin(double);
float asinf(float);
double asinh(double);
float asinhf(float);
double atan(double);
double atan2(double, double);
float atan2f(float, float);
float atanf(float);
double atanh(double);
float atanhf(float);
double cabs(struct {double x, y;});
float cabsf(struct {float x, y;});
double cbrt(double);
float cbrtf(float);
double ceil(double);
float ceilf(float);
double copysign(double, double);
float copysignf(float, float);
double cos(double);
float cosf(float);
double cosh(double);
float coshf(float);
double drem(double, double);
float dremf(float, float);
double erf(double);
double erfc(double);
float erfcf(float);
float erff(float);
double exp(double);
float expf(float);
double expm1(double);
float expm1f(float);
double fabs(double);
float fabsf(float);
int finite(double);
int finitef(float);
double floor(double);
float floorf(float);
double fmod(double, double);
float fmodf(float, float);
double frexp(double, int *);
float frexpf(float, int *);
double gamma(double);
double gamma_r(double, int *);
float gammaf(float);
float gammaf_r(float, int *);
double hypot(double, double);
float hypotf(float, float);
int ilogb(double);
int ilogbf(float);
int isinf(double);
int isnan(double);
int isnanf(float);
double j0(double);
float j0f(float);
double j1(double);
float j1f(float);
double jn(int, double);
float jnf(int, float);
double ldexp(double, int);
float ldexpf(float, int);
double lgamma(double);
double lgamma_r(double, int *);
float lgammaf(float);
float lgammaf_r(float, int *);
double log(double);
double log10(double);
float log10f(float);
double log1p(double);
float log1pf(float);
double logb(double);
float logbf(float);
float logf(float);
int matherr(struct exception *);
double modf(double, double *);
float modff(float, float *);
double nextafter(double, double);
float nextafterf(float, float);
double pow(double, double);
float powf(float, float);
double remainder(double, double);
float remainderf(float, float);
double rint(double);
float rintf(float);
double scalb(double, double);
float scalbf(float, float);
double scalbn(double, int);
float scalbnf(float, int);
double significand(double);
float significandf(float);
double sin(double);
float sinf(float);
double sinh(double);
float sinhf(float);
double sqrt(double);
float sqrtf(float);
double tan(double);
float tanf(float);
double tanh(double);
float tanhf(float);
double y0(double);
float y0f(float);
double y1(double);
float y1f(float);
double yn(int, double);
float ynf(int, float);
HARDWARE-DEPENDENT LIBRARIES
On some architectures, such as the Intel architecture family, there are
separate versions of the math library for systems that have hardware
floating point support and those without. The hardware-dependent library
is named after the architecture; for example, -lmi386 refers explicitly
to the hardware-dependent library on the Intel architecture. A hardware-
dependent library is geared toward fast execution; it typically supports
only IEEE 754 error semantics and it may use instructions that are not
included in the system's floating point emulation.
The generic library is named -lmstd and it provides standard-conforming
error semantics. The external variable _LIB_VERSION sets the specific
error semantics:
typedef enum {
_IEEE_ = -1,
_SVID_,
_XOPEN_,
_POSIX_
} _LIB_VERSION_TYPE;
extern _LIB_VERSION_TYPE _LIB_VERSION;
When _LIB_VERSION is assigned one of the following values, it has the in-
dicated effect on error reporting:
_IEEE_ If exceptions are masked (see fpsetmask(3)), an appropriate
IEEE 754 value is returned (Inf, NaN, 0, ...) and a ``sticky''
bit is set (see fpgetsticky(3)). If exceptions are unmasked,
then an unmasked exception generates a SIGFPE signal (see
sigaction(2)). Note that returning from a SIGFPE signal han-
dler will normally just repeat the faulting operation; the
longjmp(3) function is typically used in the SIGFPE handler to
avoid re-executing the failing operation. The errno variable
is unaffected.
_SVID_ On encountering an error, the library calls the function
matherr(3). If matherr() returns 0, a message is usually
printed on stderr and the global variable errno is set appro-
priately (see below). Unless you redefine matherr(), the de-
fault matherr() function returns 0.
_XOPEN_ This mode works much like _SVID_ except no messages are print-
ed.
_POSIX_ In this mode, errno is always set appropriately for errors.
Matherr() is ignored.
For those situations that set errno on error, errno is set to EDOM if the
input argument was outside of the domain in which the operation is de-
fined, or to ERANGE if the result is out of range (for example, if it
would overflow or underflow).
IEEE 754 semantics are the default. See fpsetmask(3) for information on
configuring IEEE 754 exceptions.
The script mathlink(8) runs at boot time and sets up hard links such that
-lm refers to the hardware-dependent library if the hardware supports it,
and to the generic library otherwise. System administrators can force a
particular choice by editing the file /etc/rc.configure/0.math.0 appro-
priately. Users may select a specific version of the library by provid-
ing the corresponding link flags (-lmi386 or -lmstd, for example).
SEE ALSOfpsetmask(3), matherr(3)BUGS
If you link against static shared libraries, only the useless default
matherr() function can be used. If you need to provide your own math-
err(), link non-shared or dynamically.
On the Intel architecture, floating point calculations are traditionally
performed in double precision even for single precision arguments. Sin-
gle precision library functions are no faster than double precision func-
tions for this reason.
IEEE 754
Properties of IEEE 754 Double Precision:
o Wordsize: 64 bits, 8 bytes. Radix: Binary.
o Precision: 53 significant bits, roughly like 16 significant decimals.
If x and x' are consecutive positive double precision numbers (they
differ by 1 ulp), then:
1.1e-16 < 0.5**53 < (x'-x)/x <= 0.5**52 < 2.3e-16
o Range: Overflow threshold = 2.0**1024 = 1.8e308; underflow threshold
= 0.5**1022 = 2.2e-308.
Overflow goes by default to a signed infinity, usually written as
Inf.
Underflow is gradual, rounding to the nearest integer multiple of
0.5**1074 = 4.9e-324.
Zero is represented ambiguously as +0 or -0. Its sign transforms correct-
ly through multiplication or division, and is preserved by addition of
zeroes with like signs; but x-x yields +0 for every finite x. The only
operations that reveal zero's sign are division by zero and
copysign(x,+-0). In particular, comparison (x > y, x >= y, etc.) cannot
be affected by the sign of zero; but if finite x = y then
Inf = 1/(x-y) != -1/(y-x) = -Inf
Inf is signed. It persists when added to itself or to any finite number.
Its sign transforms correctly through multiplication and division, and
(finite)/+-Inf = +-0
(nonzero)/0 = +-Inf
But Inf-Inf, Inf**0 and Inf/Inf, like 0/0 and sqrt(-3), are invalid oper-
ations that produce a non-numerical result, or a NaN (``not a number'').
There are 2**53-2 reserved operands, all called NaN. Some, called
signaling NaNs, trap any floating-point operation performed upon them;
they are used to mark missing or uninitialized values, or nonexistent el-
ements of arrays. The rest are quiet NaNs; they are the default results
of invalid operations, and propagate through subsequent arithmetic opera-
tions. If x != x then x is NaN; every other predicate (x > y, x = y, x <
y, ...) is false if NaN is involved. (NOTE: Trichotomy is violated by
NaN.)
Besides being false, predicates that entail ordered comparison, rather
than mere (in)equality, signal ``invalid operation'' when NaN is in-
volved.
Every algebraic operation (+, -, *, /, \/) is rounded by default to with-
in half an ulp, and when the rounding error is exactly half an ulp then
the rounded value's least significant bit is zero. This kind of rounding
is usually the best kind, sometimes provably so; for instance, for every
x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find (x/3.0)*3.0 == x and
(x/10.0)*10.0 == x and so on despite the fact that both the quotients and
the products have been rounded. Only rounding like IEEE 754 can do that.
But no single kind of rounding can be proved best for every circumstance,
so IEEE 754 provides rounding towards zero or towards +Inf or towards
-Inf at the programmer's option.
IEEE 754 recognizes five kinds of floating-point exceptions, listed below
in declining order of probable importance.
Exception Default Result
Invalid Operation NaN, or false
Overflow +-Inf
Divide by Zero +-Inf
Underflow Gradual Underflow
Inexact Rounded value
NOTE: An exception is not an error unless handled badly. What makes a
class of exceptions exceptional is that no single default response can be
satisfactory in every instance. On the other hand, if a default response
will serve most instances satisfactorily, the unsatisfactory instances
cannot justify aborting computation every time the exception occurs.
For each kind of floating-point exception, IEEE 754 provides a flag that
is raised each time its exception is signaled, and stays raised until the
program resets it. Programs may test, save and restore a flag (see
fpgetsticky(3)). Thus, IEEE 754 provides three ways by which programs
may cope with exceptions for which the default result might be unsatis-
factory:
1. Test for a condition that might cause an exception later, and branch
to avoid the exception.
2. Test a flag to see whether an exception has occurred since the pro-
gram last reset its flag.
3. Test a result to see whether it is a value that only an exception
could have produced.
CAUTION: The only reliable ways to discover whether underflow has oc-
curred are to test whether products or quotients lie closer to zero than
the underflow threshold, or to test the underflow flag. (Sums and dif-
ferences cannot underflow in IEEE 754; if x != y then x-y is correct to
full precision and certainly nonzero regardless of how tiny it may be.)
Products and quotients that underflow gradually can lose accuracy gradu-
ally without vanishing, so comparing them with zero will not reveal the
loss. Fortunately, if a gradually underflowed value is destined to be
added to something bigger than the underflow threshold, as is almost al-
ways the case, digits lost to gradual underflow will not be missed be-
cause they would have been rounded off anyway. So gradual underflows are
usually provably ignorable. The same cannot be said of underflows
flushed to 0.
Other ways to cope with exceptions may be provided by IEEE 754 compliant
architectures. Most commonly, the floating point unit can cause a hard-
ware fault, which the operating system can propagate to the program. On
BSD/OS, various types of exceptions may be unmasked so that the occur-
rence of an unmasked exception results in a SIGFPE signal being sent to
the process (see sigaction(3)). Masking is controlled by the fpset-
mask(3) function.
BSDI BSD/OS February 17, 1998 5
