MATH(3) | Library Functions Manual | MATH(3) |
math
—
#include <math.h>
<math.h>
.
Name | Man page | Description | Error Bound
(ULP s) |
acos | acos(3) | inverse trigonometric function | 3 |
acosh | acosh(3) | inverse hyperbolic function | 3 |
asin | asin(3) | inverse trigonometric function | 3 |
asinh | asinh(3) | inverse hyperbolic function | 3 |
atan | atan(3) | inverse trigonometric function | 1 |
atanh | atanh(3) | inverse hyperbolic function | 3 |
atan2 | atan2(3) | inverse trigonometric function | 2 |
cbrt | sqrt(3) | cube root | 1 |
ceil | ceil(3) | integer no less than | 0 |
copysign | copysign(3) | copy sign bit | 0 |
cos | cos(3) | trigonometric function | 1 |
cosh | cosh(3) | hyperbolic function | 3 |
erf | erf(3) | error function | ??? |
erfc | erf(3) | complementary error function | ??? |
exp | exp(3) | base e exponential | 1 |
exp2 | exp2(3) | base 2 exponential | ??? |
expm1 | expm1(3) | exp(x)-1 | 1 |
fabs | fabs(3) | absolute value | 0 |
fdim | erf(3) | positive difference | ??? |
finite | finite(3) | test for finity | 0 |
floor | floor(3) | integer no greater than | 0 |
fma | fmod(3) | fused multiply-add | ??? |
fmax | fmax(3) | maximum | 0 |
fmin | fmin(3) | minimum | 0 |
fmod | fmod(3) | remainder | ??? |
hypot | hypot(3) | Euclidean distance | 1 |
ilogb | ilogb(3) | exponent extraction | 0 |
isinf | isinf(3) | test for infinity | 0 |
isnan | isnan(3) | test for not-a-number | 0 |
j0 | j0(3) | Bessel function | ??? |
j1 | j0(3) | Bessel function | ??? |
jn | j0(3) | Bessel function | ??? |
lgamma | lgamma(3) | log gamma function | ??? |
log | log(3) | natural logarithm | 1 |
log10 | log(3) | logarithm to base 10 | 3 |
log1p | log(3) | log(1+x) | 1 |
nan | nan(3) | return quiet NaN | 0 |
nextafter | nextafter(3) | next representable number | 0 |
pow | pow(3) | exponential x**y | 60-500 |
remainder | remainder(3) | remainder | 0 |
rint | rint(3) | round to nearest integer | 0 |
scalbn | scalbn(3) | exponent adjustment | 0 |
sin | sin(3) | trigonometric function | 1 |
sinh | sinh(3) | hyperbolic function | 3 |
sqrt | sqrt(3) | square root | 1 |
tan | tan(3) | trigonometric function | 3 |
tanh | tanh(3) | hyperbolic function | 3 |
trunc | trunc(3) | nearest integral value | 3 |
y0 | j0(3) | Bessel function | ??? |
y1 | j0(3) | Bessel function | ??? |
yn | j0(3) | Bessel function | ??? |
Name | Value | Description |
M_E | 2.7182818284590452354 | e |
M_LOG2E | 1.4426950408889634074 | log 2e |
M_LOG10E | 0.43429448190325182765 | log 10e |
M_LN2 | 0.69314718055994530942 | log e2 |
M_LN10 | 2.30258509299404568402 | log e10 |
M_PI | 3.14159265358979323846 | pi |
M_PI_2 | 1.57079632679489661923 | pi/2 |
M_PI_4 | 0.78539816339744830962 | pi/4 |
M_1_PI | 0.31830988618379067154 | 1/pi |
M_2_PI | 0.63661977236758134308 | 2/pi |
M_2_SQRTPI | 1.12837916709551257390 | 2/sqrt(pi) |
M_SQRT2 | 1.41421356237309504880 | sqrt(2) |
M_SQRT1_2 | 0.70710678118654752440 | 1/sqrt(2) |
ULPs
tabulated above; an ULP
is one Unit in the Last Place. And the programs have been cured of anomalies
that afflicted the older math library in which incidents like the following
had been reported:
sqrt(-1.0) = 0.0 and log(-1.0) = -1.7e38. cos(1.0e-11) > cos(0.0) > 1.0. pow(x,1.0) ≠ x when x = 2.0, 3.0, 4.0, ..., 9.0. pow(-1.0,1.0e10) trapped on Integer Overflow. sqrt(1.0e30) and sqrt(1.0e-30) were very slow.
Properties of D_floating-point:
ULP
), then
1.3e-17 < 0.5**56 <
(x'-x)/x ≤ 0.5**55 < 2.8e-17.
Overflow threshold | = 2.0**127 | = 1.7e38. |
Underflow threshold | = 0.5**128 | = 2.9e-39. |
Overflow customarily stops computation. Underflow is customarily flushed quietly to zero. CAUTION: It is possible to have x ≠ y and yet x-y = 0 because of underflow. Similarly x > y > 0 cannot prevent either x∗y = 0 or y/x = 0 from happening without warning.
ULP
, and when the rounding error is
exactly half an ULP
then rounding is away from
0.Except for its narrow range, D_floating-point is one of the better computer arithmetics designed in the 1960's. Its properties are reflected fairly faithfully in the elementary functions for a VAX distributed in 4.3 BSD. They over/underflow only if their results have to lie out of range or very nearly so, and then they behave much as any rational arithmetic operation that over/underflowed would behave. Similarly, expressions like log(0) and atanh(1) behave like 1/0; and sqrt(-3) and acos(3) behave like 0/0; they all produce reserved operands and/or stop computation! The situation is described in more detail in manual pages.
This response seems excessively punitive, so it is destined to be replaced at some time in the foreseeable future by a more flexible but still uniform scheme being developed to handle all floating-point arithmetic exceptions neatly.
How do the functions in 4.3 BSD's new math library for UNIX compare with their counterparts in DEC's VAX/VMS library? Some of the VMS functions are a little faster, some are a little more accurate, some are more puritanical about exceptions (like pow(0.0,0.0) and atan2(0.0,0.0)), and most occupy much more memory than their counterparts in libm. The VMS codes interpolate in large table to achieve speed and accuracy; the libm codes use tricky formulas compact enough that all of them may some day fit into a ROM.
More important, DEC regards the VMS codes as proprietary and guards them zealously against unauthorized use. But the libm codes in 4.3 BSD are intended for the public domain; they may be copied freely provided their provenance is always acknowledged, and provided users assist the authors in their researches by reporting experience with the codes. Therefore no user of UNIX on a machine whose arithmetic resembles VAX D_floating-point need use anything worse than the new libm.
Intel i8087, i80287 | National Semiconductor 32081 |
68881 | Weitek WTL-1032, ..., -1165 |
Zilog Z8070 | Western Electric (AT&T) WE32106. |
The codes in 4.3 BSD's libm for machines that conform to IEEE 754
are intended primarily for the National Semiconductor 32081 and WTL 1164/65.
To use these codes with the Intel or Zilog chips, or with the Apple
Macintosh or ELXSI 6400, is to forego the use of better codes provided
(perhaps freely) by those companies and designed by some of the authors of
the codes above. Except for atan
(),
cbrt
(), erf
(),
erfc
(), hypot
(),
j0-jn
(), lgamma
(),
pow
(), and y0-yn
(), the
Motorola 68881 has all the functions in libm on chip, and faster and more
accurate; it, Apple, the i8087, Z8070 and WE32106 all use 64 significant
bits. The main virtue of 4.3 BSD's libm codes is that they are intended for
the public domain; they may be copied freely provided their provenance is
always acknowledged, and provided users assist the authors in their
researches by reporting experience with the codes. Therefore no user of UNIX
on a machine that conforms to IEEE 754 need use anything worse than the new
libm.
Properties of IEEE 754 Double-Precision:
ULP
), then
1.1e-16 < 0.5**53 <
(x'-x)/x ≤ 0.5**52 < 2.3e-16.
Overflow threshold | = 2.0**1024 | = 1.8e308 |
Underflow threshold | = 0.5**1022 | = 2.2e-308 |
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 involved.
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 ... despite 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 +infinity or towards
-infinity at the programmer's option. And the same kinds of rounding are
specified for Binary-Decimal Conversions, at least for magnitudes between
roughly 1.0e-10 and 1.0e37.Exception | Default Result |
Invalid Operation | NaN, or FALSE |
Overflow | ±∞ |
Divide by Zero | ±∞ |
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 also test, save and restore a flag. Thus, IEEE 754 provides three ways by which programs may cope with exceptions for which the default result might be unsatisfactory:
At the option of an implementor conforming to IEEE 754, other ways to cope with exceptions may be provided:
The crucial problem for exception handling is the problem of Scope, and the problem's solution is understood, but not enough manpower was available to implement it fully in time to be distributed in 4.3 BSD's libm. Ideally, each elementary function should act as if it were indivisible, or atomic, in the sense that ...
Ideally, every programmer should be able conveniently to turn a debugged subprogram into one that appears atomic to its users. But simulating all three characteristics of an atomic function is still a tedious affair, entailing hosts of tests and saves-restores; work is under way to ameliorate the inconvenience.
Meanwhile, the functions in libm are only approximately atomic. They signal no inappropriate exception except possibly ...
cbrt
(),
hypot
(), log10
()
and pow
()September 28, 2017 | NetBSD 9.2 |