math.3m

来自「<B>Digital的Unix操作系统VAX 4.2源码</B>」· 3M 代码 · 共 550 行 · 第 1/2 页

.TH math 3m RISC
.ds up \fIulp\fR
.ds nn \fINaN\fR
.de If
.if n \\
\\$1Infinity\\$2
.if t \\
\\$1\\(if\\$2
..
.SH Name
math \- introduction to mathematical library functions
.SH Description
These functions constitute the C math library
.I libm.
There are two versions of the math library
.I libm.a
and
.I libm43.a.
.PP
The first,
.I libm.a,
contains routines written in MIPS assembly language and tuned for best
performance and includes many routines for the
.I float
data type. The routines in there are based on the algorithms of Cody and
Waite or those in the 4.3 BSD release, whichever provides the best performance
with acceptable error bounds.  Those routines with Cody and Waite
implementations are marked with a `*' in the list of functions below.
.PP
The second version of the math library,
.I libm43.a,
contains routines all based on the original codes in the 4.3 BSD release.
The difference between the two version's error bounds is typically around 1
unit in the last place, whereas the performance difference may be a factor
of two or more.
.PP
The link editor searches this library under the \*(lq\-lm\*(rq (or
\*(lq\-lm43\*(rq) option.
Declarations for these functions may be obtained from the include file
.RI < math.h >.
The Fortran math library is described in ``man 3f intro''.
.SS List Of Functions
The cycle counts of all functions are approximate; cycle counts often depend
on the value of argument. The error bound sometimes applies only to the
primary range.
.PP
.TS
tab(@);
l l lfHB s s s
lfHB lfHB lfHB lfHB lfHB lfHB
l l l l l l .
_
.sp 4p
@@Error Bound (ULPs) Cycles
Name@Description@libm.a@libm43.a@libm.a@libm43.a
.sp 4p
_
.sp 6p
acos@T{
inverse trig function
T}@3@3@?@?
acosh@T{
inverse hyperbolic function
T}@3@3@?@?
asin@T{
inverse trig function
T}@3@3@?@?
asinh@T{
inverse hyperbolic function
T}@3@3@?@?
atan@T{
inverse trig function
T}@1@1@152@260
atanh@T{
inverse hyperbolic function
T}@3@3@?@?
atan2@T{
inverse trig function
T}@2@2@?@?
cabs@T{
complex absolute value
T}@1@1@?@?
cbrt@cube root@1@1@?@?
ceil@T{
integer no less than
T}@0@0@?@?
copysign@copy sign bit@0@0@?@?
cos*@trig function@2@1@128@243
cosh*@hyperbolic function@?@3@142@294
drem@remainder@0@0@?@?
erf@error function@?@?@?@?
erfc@T{
complementary error function
T}@?@?@?@?
exp*@exponential@2@1@101@230
expm1@exp(x)\-1@1@1@281@281
fabs@absolute value@0@0@?@?
fatan*@T{
inverse trig function
T}@3@@64
fcos*@trig function@1@@87
fcosh*@hyperbolic function@?@@105
fexp*@exponential@1@@79
flog*@natural logarithm@1@@100
floor@T{
integer no greater than
T}@0@0@?@?
fsin*@trig function@1@@68
fsinh*@hyperbolic function@?@@44
fsqrt@square root@1@@95
ftan*@trig function@?@@61
ftanh*@hyperbolic function@?@@116
hypot@Euclidean distance@1@1@?@?
j0@bessel function@?@?@?@?
j1@bessel function@?@?@?@?
jn@bessel function@?@?@?@?
lgamma@log gamma function@?@?@?@?
log*@natural logarithm@2@1@119@217
logb@exponent extraction@0@0@?@?
log10*@logarithm to base 10@3@3@?@?
log1p@log(1+x)@1@1@269@269
pow@exponential x**y@60\-500@60\-500@?@?
rint@T{
round to nearest integer
T}@0@0@?@?
scalb@exponent adjustment@0@0@?@?
sin*@trig function@2@1@101@222
sinh*@hyperbolic function@?@3@79@292
sqrt@square root@1@1@133@133
tan*@trig function@?@3@92@287
tanh*@hyperbolic function@?@3@156@293
y0@bessel function@?@?@?@?
y1@bessel function@?@?@?@?
yn@bessel function@?@?@?@?
.sp 6p
_
.TE
.PP
In 4.3 BSD, distributed from the University of California
in late 1985, most of the foregoing functions come in two
versions, one for the double\-precision "D" format in the
DEC VAX\-11 family of computers, another for double\-precision
arithmetic conforming to the IEEE Standard 754 for Binary
Floating\-Point Arithmetic.  The two versions behave very
similarly, as should be expected from programs more accurate
and robust than was the norm when UNIX was born.  For
instance, the programs are accurate to within the numbers
of \*(ups tabulated above; an \*(up is one \fIU\fRnit in the \fIL\fRast
\fIP\fRlace.  And the programs have been cured of anomalies that
afflicted the older math library \fIlibm\fR in which incidents like
the following had been reported:
.sp
.RS
sqrt(\-1.0) = 0.0 and log(\-1.0) = \-1.7e38.
.br
cos(1.0e\-11) > cos(0.0) > 1.0.
.br
pow(x,1.0)
.if n \
!=
.if t \
\(!=
x when x = 2.0, 3.0, 4.0, ..., 9.0.
.br
pow(\-1.0,1.0e10) trapped on Integer Overflow.
.br
sqrt(1.0e30) and sqrt(1.0e\-30) were very slow.
.RE
.sp
RISC machines conform to the IEEE Standard 754 for Binary
Floating\-Point Arithmetic, to which only the notes for
IEEE floating-point apply and are included here.
.SS "BIEEE STANDARD 754 Floating\-Point Arithmetic:"
This standard is on its way to becoming more widely adopted
than any other design for computer arithmetic.
.PP
The main virtue of 4.3 BSD's
\fIlibm\fR 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 \fIlibm\fR.
.SS "Properties of IEEE 754 Double\-Precision:"
.RS
\fBWordsize:\fP 64 bits, 8 bytes.  \fBRadix:\fP Binary.
.br
\fBPrecision:\fP 53
.if n \
sig.
.if t \
significant
bits, roughly like 16
.if n \
sig.
.if t \
significant
decimals.
.RS
If x and x' are consecutive positive Double\-Precision
numbers (they differ by 1 \*(up), then
.br
1.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16.
.RE
.nf
.ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**1024'u+1n
\fBRange:\fP	Overflow threshold	= 2.0**1024	= 1.8e308
	Underflow threshold	= 0.5**1022	= 2.2e\-308
.ta
.fi
.RS
Overflow goes by default to a signed
.If "" .
.br
Underflow is \fIGradual,\fR rounding to the nearest
integer multiple of 0.5**1074 = 4.9e\-324.
.RE
Zero is represented ambiguously as +0 or \-0.
.RS
Its sign transforms correctly through multiplication or
division, and is preserved by addition of zeros
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
.If
\&= 1/(x\-y)
.if n \
!=
.if t \
\(!=
\-1/(y\-x) =
.If \- .
.RE
.If
is signed.
.RS
it persists when added to itself
or to any finite number.  Its sign transforms
correctly through multiplication and division, and
.If (finite)/\(+- \0=\0\(+-0
(nonzero)/0 =
.If \(+- .
But 
.if n \
Infinity\-Infinity, Infinity\(**0 and Infinity/Infinity
.if t \
\(if\-\(if, \(if\(**0 and \(if/\(if
are, like 0/0 and sqrt(\-3),
invalid operations that produce \*(nn. ...
.RE
\fBReserved operands:\fP
.RS
there are 2**53\-2 of them, all
called \*(nn (\fIN\fRot \fIa N\fRumber).
Some, called Signaling \*(nns, trap any floating\-point operation
performed upon them; they could be used to mark missing
or uninitialized values, or nonexistent elements
of arrays.  The rest are Quiet \*(nns; they are
the default results of Invalid Operations, and
propagate through subsequent arithmetic operations.
If x
.if n \
!=
.if t \
\(!=
x then x is \*(nn; every other predicate
(x > y, x = y, x < y, ...) is FALSE if \*(nn is involved.
.NT
Trichotomy is violated by \*(nn.
Besides being FALSE, predicates that entail ordered
comparison, rather than mere (in)equality,
signal Invalid Operation when \*(nn is involved.