This work is based in part on code from NetBSD libm, libc and kernel. The library is partly public domain and partly BSD-style licensed.
583 lines
22 KiB
Groff
583 lines
22 KiB
Groff
.\" $NetBSD: math.3,v 1.25 2011/09/22 18:14:09 njoly Exp $
|
|
.\"
|
|
.\" Copyright (c) 1985 Regents of the University of California.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" from: @(#)math.3 6.10 (Berkeley) 5/6/91
|
|
.\"
|
|
.Dd February 23, 2007
|
|
.Dt MATH 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm math
|
|
.Nd introduction to mathematical library functions
|
|
.Sh LIBRARY
|
|
.Lb libm
|
|
.Sh SYNOPSIS
|
|
.In math.h
|
|
.Sh DESCRIPTION
|
|
These functions constitute the C
|
|
.Lb libm .
|
|
Declarations for these functions may be obtained from the include file
|
|
.In math.h .
|
|
.\" The Fortran math library is described in ``man 3f intro''.
|
|
.Ss List of Functions
|
|
.Bl -column "copysignX" "gammaX3XX" "inverse trigonometric funcX"
|
|
.It Sy Name Ta Sy Man page Ta Sy Description Ta Sy Error Bound Dv ( ULP Ns No s)
|
|
.It acos Ta Xr acos 3 Ta inverse trigonometric function Ta 3
|
|
.It acosh Ta Xr acosh 3 Ta inverse hyperbolic function Ta 3
|
|
.It asin Ta Xr asin 3 Ta inverse trigonometric function Ta 3
|
|
.It asinh Ta Xr asinh 3 Ta inverse hyperbolic function Ta 3
|
|
.It atan Ta Xr atan 3 Ta inverse trigonometric function Ta 1
|
|
.It atanh Ta Xr atanh 3 Ta inverse hyperbolic function Ta 3
|
|
.It atan2 Ta Xr atan2 3 Ta inverse trigonometric function Ta 2
|
|
.It cbrt Ta Xr sqrt 3 Ta cube root Ta 1
|
|
.It ceil Ta Xr ceil 3 Ta integer no less than Ta 0
|
|
.It copysign Ta Xr copysign 3 Ta copy sign bit Ta 0
|
|
.It cos Ta Xr cos 3 Ta trigonometric function Ta 1
|
|
.It cosh Ta Xr cosh 3 Ta hyperbolic function Ta 3
|
|
.It erf Ta Xr erf 3 Ta error function Ta ???
|
|
.It erfc Ta Xr erf 3 Ta complementary error function Ta ???
|
|
.It exp Ta Xr exp 3 Ta exponential Ta 1
|
|
.It expm1 Ta Xr exp 3 Ta exp(x)\-1 Ta 1
|
|
.It fabs Ta Xr fabs 3 Ta absolute value Ta 0
|
|
.It finite Ta Xr finite 3 Ta test for finity Ta 0
|
|
.It floor Ta Xr floor 3 Ta integer no greater than Ta 0
|
|
.It fmod Ta Xr fmod 3 Ta remainder Ta ???
|
|
.It hypot Ta Xr hypot 3 Ta Euclidean distance Ta 1
|
|
.It ilogb Ta Xr ilogb 3 Ta exponent extraction Ta 0
|
|
.It isinf Ta Xr isinf 3 Ta test for infinity Ta 0
|
|
.It isnan Ta Xr isnan 3 Ta test for not-a-number Ta 0
|
|
.It j0 Ta Xr j0 3 Ta Bessel function Ta ???
|
|
.It j1 Ta Xr j0 3 Ta Bessel function Ta ???
|
|
.It jn Ta Xr j0 3 Ta Bessel function Ta ???
|
|
.It lgamma Ta Xr lgamma 3 Ta log gamma function Ta ???
|
|
.It log Ta Xr log 3 Ta natural logarithm Ta 1
|
|
.It log10 Ta Xr log 3 Ta logarithm to base 10 Ta 3
|
|
.It log1p Ta Xr log 3 Ta log(1+x) Ta 1
|
|
.It nan Ta Xr nan 3 Ta return quiet \*(Na Ta 0
|
|
.It nextafter Ta Xr nextafter 3 Ta next representable number Ta 0
|
|
.It pow Ta Xr pow 3 Ta exponential x**y Ta 60\-500
|
|
.It remainder Ta Xr remainder 3 Ta remainder Ta 0
|
|
.It rint Ta Xr rint 3 Ta round to nearest integer Ta 0
|
|
.It scalbn Ta Xr scalbn 3 Ta exponent adjustment Ta 0
|
|
.It sin Ta Xr sin 3 Ta trigonometric function Ta 1
|
|
.It sinh Ta Xr sinh 3 Ta hyperbolic function Ta 3
|
|
.It sqrt Ta Xr sqrt 3 Ta square root Ta 1
|
|
.It tan Ta Xr tan 3 Ta trigonometric function Ta 3
|
|
.It tanh Ta Xr tanh 3 Ta hyperbolic function Ta 3
|
|
.It trunc Ta Xr trunc 3 Ta nearest integral value Ta 3
|
|
.It y0 Ta Xr j0 3 Ta Bessel function Ta ???
|
|
.It y1 Ta Xr j0 3 Ta Bessel function Ta ???
|
|
.It yn Ta Xr j0 3 Ta Bessel function Ta ???
|
|
.El
|
|
.Ss List of Defined Values
|
|
.Bl -column "M_2_SQRTPIXX" "1.12837916709551257390XX" "2/sqrt(pi)XXX"
|
|
.It Sy Name Ta Sy Value Ta Sy Description
|
|
.It M_E 2.7182818284590452354 e
|
|
.It M_LOG2E 1.4426950408889634074 log 2e
|
|
.It M_LOG10E 0.43429448190325182765 log 10e
|
|
.It M_LN2 0.69314718055994530942 log e2
|
|
.It M_LN10 2.30258509299404568402 log e10
|
|
.It M_PI 3.14159265358979323846 pi
|
|
.It M_PI_2 1.57079632679489661923 pi/2
|
|
.It M_PI_4 0.78539816339744830962 pi/4
|
|
.It M_1_PI 0.31830988618379067154 1/pi
|
|
.It M_2_PI 0.63661977236758134308 2/pi
|
|
.It M_2_SQRTPI 1.12837916709551257390 2/sqrt(pi)
|
|
.It M_SQRT2 1.41421356237309504880 sqrt(2)
|
|
.It M_SQRT1_2 0.70710678118654752440 1/sqrt(2)
|
|
.El
|
|
.Sh NOTES
|
|
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
|
|
.Dv ULPs
|
|
tabulated above; an
|
|
.Dv 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:
|
|
.Bd -literal -offset indent
|
|
sqrt(\-1.0) = 0.0 and log(\-1.0) = \-1.7e38.
|
|
cos(1.0e\-11) \*[Gt] cos(0.0) \*[Gt] 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.
|
|
.Ed
|
|
However the two versions do differ in ways that have to be
|
|
explained, to which end the following notes are provided.
|
|
.Ss DEC VAX\-11 D_floating\-point
|
|
This is the format for which the original math library
|
|
was developed, and to which this manual is still principally dedicated.
|
|
It is
|
|
.Em the
|
|
double\-precision format for the PDP\-11
|
|
and the earlier VAX\-11 machines; VAX\-11s after 1983 were
|
|
provided with an optional "G" format closer to the IEEE
|
|
double\-precision format.
|
|
The earlier DEC MicroVAXs have no D format, only G double\-precision.
|
|
(Why?
|
|
Why not?)
|
|
.Pp
|
|
Properties of D_floating\-point:
|
|
.Bl -hang -offset indent
|
|
.It Wordsize :
|
|
64 bits, 8 bytes.
|
|
.It Radix :
|
|
Binary.
|
|
.It Precision :
|
|
56 significant bits, roughly like 17 significant decimals.
|
|
If x and x' are consecutive positive D_floating\-point
|
|
numbers (they differ by 1
|
|
.Dv ULP ) ,
|
|
then
|
|
.Dl 1.3e\-17 \*[Lt] 0.5**56 \*[Lt] (x'\-x)/x \*[Le] 0.5**55 \*[Lt] 2.8e\-17.
|
|
.It Range :
|
|
.Bl -column "Underflow thresholdX" "2.0**127X"
|
|
.It Overflow threshold = 2.0**127 = 1.7e38.
|
|
.It Underflow threshold = 0.5**128 = 2.9e\-39.
|
|
.El
|
|
.Em NOTE: THIS RANGE IS COMPARATIVELY NARROW.
|
|
.Pp
|
|
Overflow customarily stops computation.
|
|
Underflow is customarily flushed quietly to zero.
|
|
.Em CAUTION :
|
|
It is possible to have x
|
|
\(!=
|
|
y and yet x\-y = 0 because of underflow.
|
|
Similarly x \*[Gt] y \*[Gt] 0 cannot prevent either x\(**y = 0
|
|
or y/x = 0 from happening without warning.
|
|
.It Zero is represented ambiguously :
|
|
Although 2**55 different representations of zero are accepted by
|
|
the hardware, only the obvious representation is ever produced.
|
|
There is no \-0 on a VAX.
|
|
.It \*(If is not part of the VAX architecture .
|
|
.It Reserved operands :
|
|
of the 2**55 that the hardware
|
|
recognizes, only one of them is ever produced.
|
|
Any floating\-point operation upon a reserved
|
|
operand, even a MOVF or MOVD, customarily stops
|
|
computation, so they are not much used.
|
|
.It Exceptions :
|
|
Divisions by zero and operations that
|
|
overflow are invalid operations that customarily
|
|
stop computation or, in earlier machines, produce
|
|
reserved operands that will stop computation.
|
|
.It Rounding :
|
|
Every rational operation (+, \-, \(**, /) on a
|
|
VAX (but not necessarily on a PDP\-11), if not an
|
|
over/underflow nor division by zero, is rounded to
|
|
within half an
|
|
.Dv ULP ,
|
|
and when the rounding error is
|
|
exactly half an
|
|
.Dv ULP
|
|
then rounding is away from 0.
|
|
.El
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.Em This response seems excessively punitive, so it is destined
|
|
.Em to be replaced at some time in the foreseeable future by a
|
|
.Em more flexible but still uniform scheme being developed to
|
|
.Em handle all floating\-point arithmetic exceptions neatly.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Ss IEEE STANDARD 754 Floating\-Point Arithmetic
|
|
This standard is on its way to becoming more widely adopted
|
|
than any other design for computer arithmetic.
|
|
VLSI chips that conform to some version of that standard have been
|
|
produced by a host of manufacturers, among them ...
|
|
.Bl -column "Intel i8070, i80287XX"
|
|
.It Intel i8087, i80287 National Semiconductor 32081
|
|
.It 68881 Weitek WTL-1032, ... , -1165
|
|
.It Zilog Z8070 Western Electric (AT\*[Am]T) WE32106.
|
|
.El
|
|
Other implementations range from software, done thoroughly
|
|
in the Apple Macintosh, through VLSI in the Hewlett\-Packard
|
|
9000 series, to the ELXSI 6400 running ECL at 3 Megaflops.
|
|
Several other companies have adopted the formats
|
|
of IEEE 754 without, alas, adhering to the standard's way
|
|
of handling rounding and exceptions like over/underflow.
|
|
The DEC VAX G_floating\-point format is very similar to the IEEE
|
|
754 Double format, so similar that the C programs for the
|
|
IEEE versions of most of the elementary functions listed
|
|
above could easily be converted to run on a MicroVAX, though
|
|
nobody has volunteered to do that yet.
|
|
.Pp
|
|
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
|
|
.Fn atan ,
|
|
.Fn cbrt ,
|
|
.Fn erf ,
|
|
.Fn erfc ,
|
|
.Fn hypot ,
|
|
.Fn j0-jn ,
|
|
.Fn lgamma ,
|
|
.Fn pow ,
|
|
and
|
|
.Fn 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.
|
|
.Pp
|
|
Properties of IEEE 754 Double\-Precision:
|
|
.Bl -hang -offset indent
|
|
.It Wordsize :
|
|
64 bits, 8 bytes.
|
|
.It Radix :
|
|
Binary.
|
|
.It Precision :
|
|
53 significant bits, roughly like 16 significant decimals.
|
|
If x and x' are consecutive positive Double\-Precision
|
|
numbers (they differ by 1
|
|
.Dv ULP ) ,
|
|
then
|
|
.Dl 1.1e\-16 \*[Lt] 0.5**53 \*[Lt] (x'\-x)/x \*[Le] 0.5**52 \*[Lt] 2.3e\-16.
|
|
.It Range :
|
|
.Bl -column "Underflow thresholdX" "2.0**1024X"
|
|
.It Overflow threshold = 2.0**1024 = 1.8e308
|
|
.It Underflow threshold = 0.5**1022 = 2.2e\-308
|
|
.El
|
|
Overflow goes by default to a signed \*(If.
|
|
Underflow is
|
|
.Sy Gradual ,
|
|
rounding to the nearest
|
|
integer multiple of 0.5**1074 = 4.9e\-324.
|
|
.It Zero is represented ambiguously as +0 or \-0:
|
|
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 \*[Gt] y, x \*[Ge] y, etc.)
|
|
cannot be affected by the sign of zero; but if
|
|
finite x = y then \*(If
|
|
\&= 1/(x\-y)
|
|
\(!=
|
|
\-1/(y\-x) =
|
|
\- \*(If .
|
|
.It \*(If is signed :
|
|
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\-\(if, \(if\(**0 and \(if/\(if
|
|
are, like 0/0 and sqrt(\-3),
|
|
invalid operations that produce \*(Na.
|
|
.It Reserved operands :
|
|
there are 2**53\-2 of them, all
|
|
called \*(Na (Not A Number).
|
|
Some, called Signaling \*[Na]s, trap any floating\-point operation
|
|
performed upon them; they are used to mark missing
|
|
or uninitialized values, or nonexistent elements of arrays.
|
|
The rest are Quiet \*[Na]s; they are
|
|
the default results of Invalid Operations, and
|
|
propagate through subsequent arithmetic operations.
|
|
If x
|
|
\(!=
|
|
x then x is \*(Na; every other predicate
|
|
(x \*[Gt] y, x = y, x \*[Lt] y, ...) is FALSE if \*(Na is involved.
|
|
.Pp
|
|
.Em NOTE :
|
|
Trichotomy is violated by \*(Na.
|
|
Besides being FALSE, predicates that entail ordered
|
|
comparison, rather than mere (in)equality,
|
|
signal Invalid Operation when \*(Na is involved.
|
|
.It Rounding :
|
|
Every algebraic operation (+, \-, \(**, /,
|
|
\(sr)
|
|
is rounded by default to within half an
|
|
.Dv ULP ,
|
|
and when the rounding error is exactly half an
|
|
.Dv 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
|
|
+\*(If
|
|
or towards
|
|
\-\*(If
|
|
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.
|
|
.It Exceptions :
|
|
IEEE 754 recognizes five kinds of floating\-point exceptions,
|
|
listed below in declining order of probable importance.
|
|
.Bl -column "Invalid OperationX" "Gradual OverflowX"
|
|
.It Sy Exception Ta Sy Default Result
|
|
.It Invalid Operation \*(Na, or FALSE
|
|
.It Overflow \(+-\(if
|
|
.It Divide by Zero \(+-\(if \}
|
|
.It Underflow Gradual Underflow
|
|
.It Inexact Rounded value
|
|
.El
|
|
.Pp
|
|
.Em 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.
|
|
.El
|
|
.Pp
|
|
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:
|
|
.Bl -enum
|
|
.It
|
|
Test for a condition that might cause an exception
|
|
later, and branch to avoid the exception.
|
|
.It
|
|
Test a flag to see whether an exception has occurred
|
|
since the program last reset its flag.
|
|
.It
|
|
Test a result to see whether it is a value that only
|
|
an exception could have produced.
|
|
.Em CAUTION :
|
|
The only reliable ways to discover
|
|
whether Underflow has occurred are to test whether
|
|
products or quotients lie closer to zero than the
|
|
underflow threshold, or to test the Underflow flag.
|
|
(Sums and differences 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 gradually
|
|
without vanishing, so comparing them with zero
|
|
(as one might on a VAX) 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 always the case,
|
|
digits lost to gradual underflow will not be missed
|
|
because they would have been rounded off anyway.
|
|
So gradual underflows are usually
|
|
.Em provably
|
|
ignorable.
|
|
The same cannot be said of underflows flushed to 0.
|
|
.Pp
|
|
At the option of an implementor conforming to IEEE 754,
|
|
other ways to cope with exceptions may be provided:
|
|
.It
|
|
ABORT.
|
|
This mechanism classifies an exception in
|
|
advance as an incident to be handled by means
|
|
traditionally associated with error\-handling
|
|
statements like "ON ERROR GO TO ...".
|
|
Different languages offer different forms of this statement,
|
|
but most share the following characteristics:
|
|
.Bl -dash
|
|
.It
|
|
No means is provided to substitute a value for
|
|
the offending operation's result and resume
|
|
computation from what may be the middle of an expression.
|
|
An exceptional result is abandoned.
|
|
.It
|
|
In a subprogram that lacks an error\-handling
|
|
statement, an exception causes the subprogram to
|
|
abort within whatever program called it, and so
|
|
on back up the chain of calling subprograms until
|
|
an error\-handling statement is encountered or the
|
|
whole task is aborted and memory is dumped.
|
|
.El
|
|
.It
|
|
STOP.
|
|
This mechanism, requiring an interactive
|
|
debugging environment, is more for the programmer
|
|
than the program.
|
|
It classifies an exception in
|
|
advance as a symptom of a programmer's error; the
|
|
exception suspends execution as near as it can to
|
|
the offending operation so that the programmer can
|
|
look around to see how it happened.
|
|
Quite often
|
|
the first several exceptions turn out to be quite
|
|
unexceptionable, so the programmer ought ideally
|
|
to be able to resume execution after each one as if
|
|
execution had not been stopped.
|
|
.It
|
|
\&... Other ways lie beyond the scope of this document.
|
|
.El
|
|
.Pp
|
|
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 ...
|
|
.Bl -enum
|
|
.It
|
|
No exception should be signaled that is not deserved by
|
|
the data supplied to that function.
|
|
.It
|
|
Any exception signaled should be identified with that
|
|
function rather than with one of its subroutines.
|
|
.It
|
|
The internal behavior of an atomic function should not
|
|
be disrupted when a calling program changes from
|
|
one to another of the five or so ways of handling
|
|
exceptions listed above, although the definition
|
|
of the function may be correlated intentionally
|
|
with exception handling.
|
|
.El
|
|
.Pp
|
|
Ideally, every programmer should be able
|
|
.Em 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.
|
|
.Pp
|
|
Meanwhile, the functions in libm are only approximately atomic.
|
|
They signal no inappropriate exception except possibly ...
|
|
.Bl -ohang -offset indent
|
|
.It Over/Underflow
|
|
when a result, if properly computed, might have lain barely within range, and
|
|
.It Inexact in Fn cbrt , Fn hypot , Fn log10 and Fn pow
|
|
when it happens to be exact, thanks to fortuitous cancellation of errors.
|
|
.El
|
|
Otherwise, ...
|
|
.Bl -ohang -offset indent
|
|
.It Invalid Operation is signaled only when
|
|
any result but \*(Na would probably be misleading.
|
|
.It Overflow is signaled only when
|
|
the exact result would be finite but beyond the overflow threshold.
|
|
.It Divide\-by\-Zero is signaled only when
|
|
a function takes exactly infinite values at finite operands.
|
|
.It Underflow is signaled only when
|
|
the exact result would be nonzero but tinier than the underflow threshold.
|
|
.It Inexact is signaled only when
|
|
greater range or precision would be needed to represent the exact result.
|
|
.El
|
|
.\" .Sh FILES
|
|
.\" .Bl -tag -width /usr/lib/libm_p.a -compact
|
|
.\" .It Pa /usr/lib/libm.a
|
|
.\" the static math library
|
|
.\" .It Pa /usr/lib/libm.so
|
|
.\" the dynamic math library
|
|
.\" .It Pa /usr/lib/libm_p.a
|
|
.\" the static math library compiled for profiling
|
|
.\" .El
|
|
.Sh SEE ALSO
|
|
An explanation of IEEE 754 and its proposed extension p854
|
|
was published in the IEEE magazine MICRO in August 1984 under
|
|
the title "A Proposed Radix\- and Word\-length\-independent
|
|
Standard for Floating\-point Arithmetic" by W. J. Cody et al.
|
|
The manuals for Pascal, C and BASIC on the Apple Macintosh
|
|
document the features of IEEE 754 pretty well.
|
|
Articles in the IEEE magazine COMPUTER vol. 14 no. 3 (Mar. 1981),
|
|
and in the ACM SIGNUM Newsletter Special Issue of
|
|
Oct. 1979, may be helpful although they pertain to
|
|
superseded drafts of the standard.
|
|
.Sh BUGS
|
|
When signals are appropriate, they are emitted by certain
|
|
operations within the codes, so a subroutine\-trace may be
|
|
needed to identify the function with its signal in case
|
|
method 5) above is in use.
|
|
And the codes all take the
|
|
IEEE 754 defaults for granted; this means that a decision to
|
|
trap all divisions by zero could disrupt a code that would
|
|
otherwise get correct results despite division by zero.
|