xref: /freebsd/lib/msun/man/math.3 (revision 2a6bf1fadbdd19d76828e95c41532c283398eb90)
13a8617a8SJordan K. Hubbard.\" Copyright (c) 1985 Regents of the University of California.
23a8617a8SJordan K. Hubbard.\" All rights reserved.
33a8617a8SJordan K. Hubbard.\"
43a8617a8SJordan K. Hubbard.\" Redistribution and use in source and binary forms, with or without
53a8617a8SJordan K. Hubbard.\" modification, are permitted provided that the following conditions
63a8617a8SJordan K. Hubbard.\" are met:
73a8617a8SJordan K. Hubbard.\" 1. Redistributions of source code must retain the above copyright
83a8617a8SJordan K. Hubbard.\"    notice, this list of conditions and the following disclaimer.
93a8617a8SJordan K. Hubbard.\" 2. Redistributions in binary form must reproduce the above copyright
103a8617a8SJordan K. Hubbard.\"    notice, this list of conditions and the following disclaimer in the
113a8617a8SJordan K. Hubbard.\"    documentation and/or other materials provided with the distribution.
123a8617a8SJordan K. Hubbard.\" 3. All advertising materials mentioning features or use of this software
133a8617a8SJordan K. Hubbard.\"    must display the following acknowledgement:
143a8617a8SJordan K. Hubbard.\"	This product includes software developed by the University of
153a8617a8SJordan K. Hubbard.\"	California, Berkeley and its contributors.
163a8617a8SJordan K. Hubbard.\" 4. Neither the name of the University nor the names of its contributors
173a8617a8SJordan K. Hubbard.\"    may be used to endorse or promote products derived from this software
183a8617a8SJordan K. Hubbard.\"    without specific prior written permission.
193a8617a8SJordan K. Hubbard.\"
203a8617a8SJordan K. Hubbard.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
213a8617a8SJordan K. Hubbard.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
223a8617a8SJordan K. Hubbard.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
233a8617a8SJordan K. Hubbard.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
243a8617a8SJordan K. Hubbard.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
253a8617a8SJordan K. Hubbard.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
263a8617a8SJordan K. Hubbard.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
273a8617a8SJordan K. Hubbard.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
283a8617a8SJordan K. Hubbard.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
293a8617a8SJordan K. Hubbard.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
303a8617a8SJordan K. Hubbard.\" SUCH DAMAGE.
313a8617a8SJordan K. Hubbard.\"
323a8617a8SJordan K. Hubbard.\"	from: @(#)math.3	6.10 (Berkeley) 5/6/91
337f3dea24SPeter Wemm.\" $FreeBSD$
343a8617a8SJordan K. Hubbard.\"
352a6bf1faSDavid Schultz.Dd June 11, 2004
362a6bf1faSDavid Schultz.Dt MATH 3
372a6bf1faSDavid Schultz.Os
383a8617a8SJordan K. Hubbard.ds up \fIulp\fR
393a8617a8SJordan K. Hubbard.de If
403a8617a8SJordan K. Hubbard.if n \\
413a8617a8SJordan K. Hubbard\\$1Infinity\\$2
423a8617a8SJordan K. Hubbard.if t \\
433a8617a8SJordan K. Hubbard\\$1\\(if\\$2
443a8617a8SJordan K. Hubbard..
452a6bf1faSDavid Schultz.Sh NAME
463a8617a8SJordan K. Hubbardmath \- introduction to mathematical library functions
472a6bf1faSDavid Schultz.Sh DESCRIPTION
483a8617a8SJordan K. HubbardThese functions constitute the C math library,
493a8617a8SJordan K. Hubbard.I libm.
503a8617a8SJordan K. HubbardThe link editor searches this library under the \*(lq\-lm\*(rq option.
513a8617a8SJordan K. HubbardDeclarations for these functions may be obtained from the include file
522a6bf1faSDavid Schultz.In math.h .
532a6bf1faSDavid Schultz.Sh "LIST OF FUNCTIONS"
542a6bf1faSDavid SchultzEach of the following
552a6bf1faSDavid Schultz.Vt double
562a6bf1faSDavid Schultzfunctions has a
572a6bf1faSDavid Schultz.Vt float
582a6bf1faSDavid Schultzcounterpart with an
592a6bf1faSDavid Schultz.Ql f
602a6bf1faSDavid Schultzappended to the name and a
612a6bf1faSDavid Schultz.Vt long double
622a6bf1faSDavid Schultzcounterpart with an
632a6bf1faSDavid Schultz.Ql l
642a6bf1faSDavid Schultzappended.
652a6bf1faSDavid SchultzAs an example, the
662a6bf1faSDavid Schultz.Vt float
672a6bf1faSDavid Schultzand
682a6bf1faSDavid Schultz.Vt long double
692a6bf1faSDavid Schultzcounterparts of
702a6bf1faSDavid Schultz.Ft double
712a6bf1faSDavid Schultz.Fn acos "double x"
722a6bf1faSDavid Schultzare
732a6bf1faSDavid Schultz.Ft float
742a6bf1faSDavid Schultz.Fn acosf "float x"
752a6bf1faSDavid Schultzand
762a6bf1faSDavid Schultz.Ft long double
772a6bf1faSDavid Schultz.Fn acosl "long double x" ,
782a6bf1faSDavid Schultzrespectively.
793a8617a8SJordan K. Hubbard.sp 2
803a8617a8SJordan K. Hubbard.nf
812a6bf1faSDavid Schultz.ta \w'nexttoward'u+10n +\w'remainder with partial quot'u
822a6bf1faSDavid Schultz\fIName\fP	\fIDescription\fP	\fIError Bound (ULPs)\fP
832a6bf1faSDavid Schultz.ta \w'nexttoward'u+4n +\w'remainder with partial quotient'u+6nC
843a8617a8SJordan K. Hubbard.sp 5p
852a6bf1faSDavid Schultz.\" XXX Many of these error bounds are wrong for the current implementation!
862a6bf1faSDavid Schultzacos	inverse trigonometric function	3
872a6bf1faSDavid Schultzacosh	inverse hyperbolic function	3
882a6bf1faSDavid Schultzasin	inverse trigonometric function	3
892a6bf1faSDavid Schultzasinh	inverse hyperbolic function	3
902a6bf1faSDavid Schultzatan	inverse trigonometric function	1
912a6bf1faSDavid Schultzatanh	inverse hyperbolic function	3
922a6bf1faSDavid Schultzatan2	inverse trigonometric function	2
932a6bf1faSDavid Schultzcbrt	cube root	1
942a6bf1faSDavid Schultzceil	integer no less than	0
952a6bf1faSDavid Schultzcopysign	copy sign bit	0
962a6bf1faSDavid Schultzcos	trigonometric function	1
972a6bf1faSDavid Schultzcosh	hyperbolic function	3
982a6bf1faSDavid Schultzerf	error function	???
992a6bf1faSDavid Schultzerfc	complementary error function	???
1002a6bf1faSDavid Schultzexp	exponential base e	1
1012a6bf1faSDavid Schultz.\" exp2	exponential base 2	???
1022a6bf1faSDavid Schultzexpm1	exp(x)\-1	1
1032a6bf1faSDavid Schultzfabs	absolute value	0
1042a6bf1faSDavid Schultz.\" fdim	positive difference	???
1052a6bf1faSDavid Schultzfloor	integer no greater than	0
1062a6bf1faSDavid Schultz.\" fma	multiply-add	???
1072a6bf1faSDavid Schultz.\" fmax	maximum function	0
1082a6bf1faSDavid Schultz.\" fmin	minimum function	0
1092a6bf1faSDavid Schultzfmod	remainder function	???
1102a6bf1faSDavid Schultzfrexp	extract mantissa and exponent	0
1112a6bf1faSDavid Schultzhypot	Euclidean distance	1
1122a6bf1faSDavid Schultzilogb	exponent extraction	0
1132a6bf1faSDavid Schultzj0	bessel function	???
1142a6bf1faSDavid Schultzj1	bessel function	???
1152a6bf1faSDavid Schultzjn	bessel function	???
1162a6bf1faSDavid Schultzldexp	multiply by power of 2	0
1172a6bf1faSDavid Schultzlgamma	log gamma function	???
1182a6bf1faSDavid Schultz.\" llrint	round to integer	0
1192a6bf1faSDavid Schultz.\" llround	round to nearest integer	0
1202a6bf1faSDavid Schultzlog	natural logarithm	1
1212a6bf1faSDavid Schultzlog10	logarithm to base 10	3
1222a6bf1faSDavid Schultzlog1p	log(1+x)	1
1232a6bf1faSDavid Schultz.\" log2	base 2 logarithm	0
1242a6bf1faSDavid Schultzlogb	exponent extraction	0
1252a6bf1faSDavid Schultz.\" lrint	round to integer	0
1262a6bf1faSDavid Schultz.\" lround	round to nearest integer	0
1272a6bf1faSDavid Schultzmodf	extract fractional part	???
1282a6bf1faSDavid Schultz.\" nan	return quiet \*(Na)	0
1292a6bf1faSDavid Schultz.\" nearbyint	round to integer	0
1302a6bf1faSDavid Schultz.\" nextafter	next representable value	0
1312a6bf1faSDavid Schultz.\" nexttoward	next representable value	0
1322a6bf1faSDavid Schultzpow	exponential x**y	60\-500
1332a6bf1faSDavid Schultzremainder	remainder	0
1342a6bf1faSDavid Schultz.\" remquo	remainder with partial quotient	???
1352a6bf1faSDavid Schultzrint	round to nearest integer	0
1362a6bf1faSDavid Schultzround	round to nearest integer	0
1372a6bf1faSDavid Schultz.\" scalbln	exponent adjustment	0
1382a6bf1faSDavid Schultzscalbn	exponent adjustment	0
1392a6bf1faSDavid Schultzsin	trigonometric function	1
1402a6bf1faSDavid Schultzsinh	hyperbolic function	3
1412a6bf1faSDavid Schultzsqrt	square root	1
1422a6bf1faSDavid Schultztan	trigonometric function	3
1432a6bf1faSDavid Schultztanh	hyperbolic function	3
1442a6bf1faSDavid Schultztgamma	gamma function	???
1452a6bf1faSDavid Schultz.\" trunc	round towards zero	0
1462a6bf1faSDavid Schultzy0	bessel function	???
1472a6bf1faSDavid Schultzy1	bessel function	???
1482a6bf1faSDavid Schultzyn	bessel function	???
1493a8617a8SJordan K. Hubbard.ta
1503a8617a8SJordan K. Hubbard.fi
1512a6bf1faSDavid Schultz.Sh NOTES
1522a6bf1faSDavid SchultzVirtually all modern floating-point units attempt to support
1532a6bf1faSDavid SchultzIEEE Standard 754 for Binary Floating-Point Arithmetic.
1542a6bf1faSDavid SchultzThis standard does not cover particular routines in the math library
1552a6bf1faSDavid Schultzexcept for the few documented in
1562a6bf1faSDavid Schultz.Xr ieee 3 ;
1572a6bf1faSDavid Schultzit primarily defines representations of numbers and abstract
1582a6bf1faSDavid Schultzproperties of arithmetic operations relating to precision, rounding,
1592a6bf1faSDavid Schultzand exceptional cases, as described below.
1602a6bf1faSDavid SchultzThe programs are accurate to within the numbers
1613a8617a8SJordan K. Hubbardof \*(ups tabulated above; an \*(up is one \fIU\fRnit in the \fIL\fRast
1622a6bf1faSDavid Schultz\fIP\fRlace.
1632a6bf1faSDavid Schultz.Pp
1643a8617a8SJordan K. Hubbard\fBIEEE STANDARD 754 Floating\-Point Arithmetic:\fR
1652a6bf1faSDavid Schultz.Pp
1663a8617a8SJordan K. HubbardProperties of IEEE 754 Double\-Precision:
1672a6bf1faSDavid Schultz.Bd -filled -offset indent
1683a8617a8SJordan K. HubbardWordsize: 64 bits, 8 bytes.  Radix: Binary.
1693a8617a8SJordan K. Hubbard.br
1703a8617a8SJordan K. HubbardPrecision: 53
1713a8617a8SJordan K. Hubbard.if n \
1723a8617a8SJordan K. Hubbardsig.
1733a8617a8SJordan K. Hubbard.if t \
1743a8617a8SJordan K. Hubbardsignificant
1753a8617a8SJordan K. Hubbardbits, roughly like 16
1763a8617a8SJordan K. Hubbard.if n \
1773a8617a8SJordan K. Hubbardsig.
1783a8617a8SJordan K. Hubbard.if t \
1793a8617a8SJordan K. Hubbardsignificant
1803a8617a8SJordan K. Hubbarddecimals.
1812a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
1823a8617a8SJordan K. HubbardIf x and x' are consecutive positive Double\-Precision
1833a8617a8SJordan K. Hubbardnumbers (they differ by 1 \*(up), then
1843a8617a8SJordan K. Hubbard.br
1853a8617a8SJordan K. Hubbard1.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16.
1862a6bf1faSDavid Schultz.Ed
1873a8617a8SJordan K. Hubbard.nf
1883a8617a8SJordan K. Hubbard.ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**1024'u+1n
1893a8617a8SJordan K. HubbardRange:	Overflow threshold	= 2.0**1024	= 1.8e308
1903a8617a8SJordan K. Hubbard	Underflow threshold	= 0.5**1022	= 2.2e\-308
1913a8617a8SJordan K. Hubbard.ta
1923a8617a8SJordan K. Hubbard.fi
1932a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
1943a8617a8SJordan K. HubbardOverflow goes by default to a signed
1953a8617a8SJordan K. Hubbard.If "" .
1963a8617a8SJordan K. Hubbard.br
1973a8617a8SJordan K. HubbardUnderflow is \fIGradual,\fR rounding to the nearest
1983a8617a8SJordan K. Hubbardinteger multiple of 0.5**1074 = 4.9e\-324.
1992a6bf1faSDavid Schultz.Ed
2003a8617a8SJordan K. HubbardZero is represented ambiguously as +0 or \-0.
2012a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
2023a8617a8SJordan K. HubbardIts sign transforms correctly through multiplication or
2033a8617a8SJordan K. Hubbarddivision, and is preserved by addition of zeros
2043a8617a8SJordan K. Hubbardwith like signs; but x\-x yields +0 for every
2053a8617a8SJordan K. Hubbardfinite x.  The only operations that reveal zero's
2063a8617a8SJordan K. Hubbardsign are division by zero and copysign(x,\(+-0).
2073a8617a8SJordan K. HubbardIn particular, comparison (x > y, x \(>= y, etc.)
2083a8617a8SJordan K. Hubbardcannot be affected by the sign of zero; but if
2093a8617a8SJordan K. Hubbardfinite x = y then
2103a8617a8SJordan K. Hubbard.If
2113a8617a8SJordan K. Hubbard\&= 1/(x\-y)
2123a8617a8SJordan K. Hubbard.if n \
2133a8617a8SJordan K. Hubbard!=
2143a8617a8SJordan K. Hubbard.if t \
2153a8617a8SJordan K. Hubbard\(!=
2163a8617a8SJordan K. Hubbard\-1/(y\-x) =
2173a8617a8SJordan K. Hubbard.If \- .
2182a6bf1faSDavid Schultz.Ed
2193a8617a8SJordan K. Hubbard.If
2203a8617a8SJordan K. Hubbardis signed.
2212a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
2223a8617a8SJordan K. Hubbardit persists when added to itself
2233a8617a8SJordan K. Hubbardor to any finite number.  Its sign transforms
2243a8617a8SJordan K. Hubbardcorrectly through multiplication and division, and
2253a8617a8SJordan K. Hubbard.If (finite)/\(+- \0=\0\(+-0
2263a8617a8SJordan K. Hubbard(nonzero)/0 =
2273a8617a8SJordan K. Hubbard.If \(+- .
2283a8617a8SJordan K. HubbardBut
2293a8617a8SJordan K. Hubbard.if n \
2303a8617a8SJordan K. HubbardInfinity\-Infinity, Infinity\(**0 and Infinity/Infinity
2313a8617a8SJordan K. Hubbard.if t \
2323a8617a8SJordan K. Hubbard\(if\-\(if, \(if\(**0 and \(if/\(if
2333a8617a8SJordan K. Hubbardare, like 0/0 and sqrt(\-3),
2342a6bf1faSDavid Schultzinvalid operations that produce \*(Na. ...
2352a6bf1faSDavid Schultz.Ed
2363a8617a8SJordan K. HubbardReserved operands:
2372a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
2383a8617a8SJordan K. Hubbardthere are 2**53\-2 of them, all
2392a6bf1faSDavid Schultzcalled \*(Na (\fIN\fRot \fIa N\fRumber).
2402a6bf1faSDavid SchultzSome, called Signaling \*(Nas, trap any floating\-point operation
2413a8617a8SJordan K. Hubbardperformed upon them; they are used to mark missing
2423a8617a8SJordan K. Hubbardor uninitialized values, or nonexistent elements
2432a6bf1faSDavid Schultzof arrays.  The rest are Quiet \*(Nas; they are
2443a8617a8SJordan K. Hubbardthe default results of Invalid Operations, and
2453a8617a8SJordan K. Hubbardpropagate through subsequent arithmetic operations.
2463a8617a8SJordan K. HubbardIf x
2473a8617a8SJordan K. Hubbard.if n \
2483a8617a8SJordan K. Hubbard!=
2493a8617a8SJordan K. Hubbard.if t \
2503a8617a8SJordan K. Hubbard\(!=
2512a6bf1faSDavid Schultzx then x is \*(Na; every other predicate
2522a6bf1faSDavid Schultz(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved.
2533a8617a8SJordan K. Hubbard.br
2542a6bf1faSDavid SchultzNOTE: Trichotomy is violated by \*(Na.
2552a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
2563a8617a8SJordan K. HubbardBesides being FALSE, predicates that entail ordered
2573a8617a8SJordan K. Hubbardcomparison, rather than mere (in)equality,
2582a6bf1faSDavid Schultzsignal Invalid Operation when \*(Na is involved.
2592a6bf1faSDavid Schultz.Ed
2602a6bf1faSDavid Schultz.Ed
2613a8617a8SJordan K. HubbardRounding:
2622a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
2633a8617a8SJordan K. HubbardEvery algebraic operation (+, \-, \(**, /,
2643a8617a8SJordan K. Hubbard.if n \
2653a8617a8SJordan K. Hubbardsqrt)
2663a8617a8SJordan K. Hubbard.if t \
2673a8617a8SJordan K. Hubbard\(sr)
2683a8617a8SJordan K. Hubbardis rounded by default to within half an \*(up, and
2693a8617a8SJordan K. Hubbardwhen the rounding error is exactly half an \*(up then
2703a8617a8SJordan K. Hubbardthe rounded value's least significant bit is zero.
2713a8617a8SJordan K. HubbardThis kind of rounding is usually the best kind,
2723a8617a8SJordan K. Hubbardsometimes provably so; for instance, for every
2733a8617a8SJordan K. Hubbardx = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find
2743a8617a8SJordan K. Hubbard(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ...
2753a8617a8SJordan K. Hubbarddespite that both the quotients and the products
2763a8617a8SJordan K. Hubbardhave been rounded.  Only rounding like IEEE 754
2773a8617a8SJordan K. Hubbardcan do that.  But no single kind of rounding can be
2783a8617a8SJordan K. Hubbardproved best for every circumstance, so IEEE 754
2793a8617a8SJordan K. Hubbardprovides rounding towards zero or towards
2803a8617a8SJordan K. Hubbard.If +
2813a8617a8SJordan K. Hubbardor towards
2823a8617a8SJordan K. Hubbard.If \-
2833a8617a8SJordan K. Hubbardat the programmer's option.  And the
2843a8617a8SJordan K. Hubbardsame kinds of rounding are specified for
2853a8617a8SJordan K. HubbardBinary\-Decimal Conversions, at least for magnitudes
2863a8617a8SJordan K. Hubbardbetween roughly 1.0e\-10 and 1.0e37.
2872a6bf1faSDavid Schultz.Ed
2883a8617a8SJordan K. HubbardExceptions:
2892a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
2903a8617a8SJordan K. HubbardIEEE 754 recognizes five kinds of floating\-point exceptions,
2913a8617a8SJordan K. Hubbardlisted below in declining order of probable importance.
2922a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
2933a8617a8SJordan K. Hubbard.nf
2943a8617a8SJordan K. Hubbard.ta \w'Invalid Operation'u+6n +\w'Gradual Underflow'u+2n
2953a8617a8SJordan K. HubbardException	Default Result
2963a8617a8SJordan K. Hubbard.tc \(ru
2973a8617a8SJordan K. Hubbard
2983a8617a8SJordan K. Hubbard.tc
2992a6bf1faSDavid SchultzInvalid Operation	\*(Na, or FALSE
3003a8617a8SJordan K. Hubbard.if n \{\
3013a8617a8SJordan K. HubbardOverflow	\(+-Infinity
3023a8617a8SJordan K. HubbardDivide by Zero	\(+-Infinity \}
3033a8617a8SJordan K. Hubbard.if t \{\
3043a8617a8SJordan K. HubbardOverflow	\(+-\(if
3053a8617a8SJordan K. HubbardDivide by Zero	\(+-\(if \}
3063a8617a8SJordan K. HubbardUnderflow	Gradual Underflow
3073a8617a8SJordan K. HubbardInexact	Rounded value
3083a8617a8SJordan K. Hubbard.ta
3093a8617a8SJordan K. Hubbard.fi
3102a6bf1faSDavid Schultz.Ed
3113a8617a8SJordan K. HubbardNOTE:  An Exception is not an Error unless handled
3123a8617a8SJordan K. Hubbardbadly.  What makes a class of exceptions exceptional
3133a8617a8SJordan K. Hubbardis that no single default response can be satisfactory
3143a8617a8SJordan K. Hubbardin every instance.  On the other hand, if a default
3153a8617a8SJordan K. Hubbardresponse will serve most instances satisfactorily,
3163a8617a8SJordan K. Hubbardthe unsatisfactory instances cannot justify aborting
3173a8617a8SJordan K. Hubbardcomputation every time the exception occurs.
3182a6bf1faSDavid Schultz.Ed
3192a6bf1faSDavid Schultz.Pp
3203a8617a8SJordan K. HubbardFor each kind of floating\-point exception, IEEE 754
3213a8617a8SJordan K. Hubbardprovides a Flag that is raised each time its exception
3223a8617a8SJordan K. Hubbardis signaled, and stays raised until the program resets
3233a8617a8SJordan K. Hubbardit.  Programs may also test, save and restore a flag.
3243a8617a8SJordan K. HubbardThus, IEEE 754 provides three ways by which programs
3253a8617a8SJordan K. Hubbardmay cope with exceptions for which the default result
3263a8617a8SJordan K. Hubbardmight be unsatisfactory:
3272a6bf1faSDavid Schultz.Bl -enum
3282a6bf1faSDavid Schultz.It
3293a8617a8SJordan K. HubbardTest for a condition that might cause an exception
3303a8617a8SJordan K. Hubbardlater, and branch to avoid the exception.
3312a6bf1faSDavid Schultz.It
3323a8617a8SJordan K. HubbardTest a flag to see whether an exception has occurred
3333a8617a8SJordan K. Hubbardsince the program last reset its flag.
3342a6bf1faSDavid Schultz.It
3353a8617a8SJordan K. HubbardTest a result to see whether it is a value that only
3363a8617a8SJordan K. Hubbardan exception could have produced.
3373a8617a8SJordan K. Hubbard.RS
3383a8617a8SJordan K. HubbardCAUTION: The only reliable ways to discover
3393a8617a8SJordan K. Hubbardwhether Underflow has occurred are to test whether
3403a8617a8SJordan K. Hubbardproducts or quotients lie closer to zero than the
3413a8617a8SJordan K. Hubbardunderflow threshold, or to test the Underflow
3423a8617a8SJordan K. Hubbardflag.  (Sums and differences cannot underflow in
3433a8617a8SJordan K. HubbardIEEE 754; if x
3443a8617a8SJordan K. Hubbard.if n \
3453a8617a8SJordan K. Hubbard!=
3463a8617a8SJordan K. Hubbard.if t \
3473a8617a8SJordan K. Hubbard\(!=
3483a8617a8SJordan K. Hubbardy then x\-y is correct to
3493a8617a8SJordan K. Hubbardfull precision and certainly nonzero regardless of
3503a8617a8SJordan K. Hubbardhow tiny it may be.)  Products and quotients that
3513a8617a8SJordan K. Hubbardunderflow gradually can lose accuracy gradually
3523a8617a8SJordan K. Hubbardwithout vanishing, so comparing them with zero
3533a8617a8SJordan K. Hubbard(as one might on a VAX) will not reveal the loss.
3543a8617a8SJordan K. HubbardFortunately, if a gradually underflowed value is
3553a8617a8SJordan K. Hubbarddestined to be added to something bigger than the
3563a8617a8SJordan K. Hubbardunderflow threshold, as is almost always the case,
3573a8617a8SJordan K. Hubbarddigits lost to gradual underflow will not be missed
3583a8617a8SJordan K. Hubbardbecause they would have been rounded off anyway.
3593a8617a8SJordan K. HubbardSo gradual underflows are usually \fIprovably\fR ignorable.
3603a8617a8SJordan K. HubbardThe same cannot be said of underflows flushed to 0.
3613a8617a8SJordan K. Hubbard.RE
3622a6bf1faSDavid Schultz.El
3632a6bf1faSDavid Schultz.Pp
3643a8617a8SJordan K. HubbardAt the option of an implementor conforming to IEEE 754,
3653a8617a8SJordan K. Hubbardother ways to cope with exceptions may be provided:
3662a6bf1faSDavid Schultz.Bl -hang -width 3n
3672a6bf1faSDavid Schultz.It 4.
3683a8617a8SJordan K. HubbardABORT.  This mechanism classifies an exception in
3693a8617a8SJordan K. Hubbardadvance as an incident to be handled by means
3703a8617a8SJordan K. Hubbardtraditionally associated with error\-handling
3713a8617a8SJordan K. Hubbardstatements like "ON ERROR GO TO ...".  Different
3723a8617a8SJordan K. Hubbardlanguages offer different forms of this statement,
3733a8617a8SJordan K. Hubbardbut most share the following characteristics:
3742a6bf1faSDavid Schultz.Bl -dash
3752a6bf1faSDavid Schultz.It
3763a8617a8SJordan K. HubbardNo means is provided to substitute a value for
3773a8617a8SJordan K. Hubbardthe offending operation's result and resume
3783a8617a8SJordan K. Hubbardcomputation from what may be the middle of an
3793a8617a8SJordan K. Hubbardexpression.  An exceptional result is abandoned.
3802a6bf1faSDavid Schultz.It
3813a8617a8SJordan K. HubbardIn a subprogram that lacks an error\-handling
3823a8617a8SJordan K. Hubbardstatement, an exception causes the subprogram to
3833a8617a8SJordan K. Hubbardabort within whatever program called it, and so
3843a8617a8SJordan K. Hubbardon back up the chain of calling subprograms until
3853a8617a8SJordan K. Hubbardan error\-handling statement is encountered or the
3863a8617a8SJordan K. Hubbardwhole task is aborted and memory is dumped.
3872a6bf1faSDavid Schultz.El
3882a6bf1faSDavid Schultz.It 5.
3893a8617a8SJordan K. HubbardSTOP.  This mechanism, requiring an interactive
3903a8617a8SJordan K. Hubbarddebugging environment, is more for the programmer
3913a8617a8SJordan K. Hubbardthan the program.  It classifies an exception in
3923a8617a8SJordan K. Hubbardadvance as a symptom of a programmer's error; the
3933a8617a8SJordan K. Hubbardexception suspends execution as near as it can to
3943a8617a8SJordan K. Hubbardthe offending operation so that the programmer can
3953a8617a8SJordan K. Hubbardlook around to see how it happened.  Quite often
3963a8617a8SJordan K. Hubbardthe first several exceptions turn out to be quite
3973a8617a8SJordan K. Hubbardunexceptionable, so the programmer ought ideally
3983a8617a8SJordan K. Hubbardto be able to resume execution after each one as if
3993a8617a8SJordan K. Hubbardexecution had not been stopped.
4002a6bf1faSDavid Schultz.It 6.
4013a8617a8SJordan K. Hubbard\&... Other ways lie beyond the scope of this document.
4022a6bf1faSDavid Schultz.El
4032a6bf1faSDavid Schultz.Ed
4042a6bf1faSDavid Schultz.Pp
4052a6bf1faSDavid SchultzIdeally, each
4063a8617a8SJordan K. Hubbardelementary function should act as if it were indivisible, or
4073a8617a8SJordan K. Hubbardatomic, in the sense that ...
4082a6bf1faSDavid Schultz.Bl -tag -width "iii)"
4092a6bf1faSDavid Schultz.It i)
4103a8617a8SJordan K. HubbardNo exception should be signaled that is not deserved by
4113a8617a8SJordan K. Hubbardthe data supplied to that function.
4122a6bf1faSDavid Schultz.It ii)
4133a8617a8SJordan K. HubbardAny exception signaled should be identified with that
4143a8617a8SJordan K. Hubbardfunction rather than with one of its subroutines.
4152a6bf1faSDavid Schultz.It iii)
4163a8617a8SJordan K. HubbardThe internal behavior of an atomic function should not
4173a8617a8SJordan K. Hubbardbe disrupted when a calling program changes from
4183a8617a8SJordan K. Hubbardone to another of the five or so ways of handling
4193a8617a8SJordan K. Hubbardexceptions listed above, although the definition
4203a8617a8SJordan K. Hubbardof the function may be correlated intentionally
4213a8617a8SJordan K. Hubbardwith exception handling.
4222a6bf1faSDavid Schultz.El
4232a6bf1faSDavid Schultz.Pp
4242a6bf1faSDavid SchultzThe functions in \fIlibm\fR are only approximately atomic.
4252a6bf1faSDavid SchultzThey signal no inappropriate exception except possibly ...
4262a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4273a8617a8SJordan K. HubbardOver/Underflow
4282a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4293a8617a8SJordan K. Hubbardwhen a result, if properly computed, might have lain barely within range, and
4302a6bf1faSDavid Schultz.Ed
4313a8617a8SJordan K. HubbardInexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR
4322a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4333a8617a8SJordan K. Hubbardwhen it happens to be exact, thanks to fortuitous cancellation of errors.
4342a6bf1faSDavid Schultz.Ed
4352a6bf1faSDavid Schultz.Ed
4363a8617a8SJordan K. HubbardOtherwise, ...
4372a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4383a8617a8SJordan K. HubbardInvalid Operation is signaled only when
4392a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4402a6bf1faSDavid Schultzany result but \*(Na would probably be misleading.
4412a6bf1faSDavid Schultz.Ed
4423a8617a8SJordan K. HubbardOverflow is signaled only when
4432a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4443a8617a8SJordan K. Hubbardthe exact result would be finite but beyond the overflow threshold.
4452a6bf1faSDavid Schultz.Ed
4463a8617a8SJordan K. HubbardDivide\-by\-Zero is signaled only when
4472a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4483a8617a8SJordan K. Hubbarda function takes exactly infinite values at finite operands.
4492a6bf1faSDavid Schultz.Ed
4503a8617a8SJordan K. HubbardUnderflow is signaled only when
4512a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4523a8617a8SJordan K. Hubbardthe exact result would be nonzero but tinier than the underflow threshold.
4532a6bf1faSDavid Schultz.Ed
4543a8617a8SJordan K. HubbardInexact is signaled only when
4552a6bf1faSDavid Schultz.Bd -filled -offset indent -compact
4563a8617a8SJordan K. Hubbardgreater range or precision would be needed to represent the exact result.
4572a6bf1faSDavid Schultz.Ed
4582a6bf1faSDavid Schultz.Ed
4592a6bf1faSDavid Schultz.Sh BUGS
4602a6bf1faSDavid SchultzSeveral functions required by
4612a6bf1faSDavid Schultz.St -isoC-99
4622a6bf1faSDavid Schultzare missing, and many functions are not available in their
4632a6bf1faSDavid Schultz.Vt long double
4642a6bf1faSDavid Schultzvariants.
4652a6bf1faSDavid Schultz.Sh SEE ALSO
4662a6bf1faSDavid Schultz.Xr fenv 3 ,
4672a6bf1faSDavid Schultz.Xr ieee 3
4682a6bf1faSDavid Schultz.Pp
4693a8617a8SJordan K. HubbardAn explanation of IEEE 754 and its proposed extension p854
4703a8617a8SJordan K. Hubbardwas published in the IEEE magazine MICRO in August 1984 under
4713a8617a8SJordan K. Hubbardthe title "A Proposed Radix\- and Word\-length\-independent
4723a8617a8SJordan K. HubbardStandard for Floating\-point Arithmetic" by W. J. Cody et al.
4733a8617a8SJordan K. HubbardThe manuals for Pascal, C and BASIC on the Apple Macintosh
4743a8617a8SJordan K. Hubbarddocument the features of IEEE 754 pretty well.
4752a6bf1faSDavid SchultzArticles in the IEEE magazine COMPUTER vol. 14 no. 3 (Mar.\&
4763a8617a8SJordan K. Hubbard1981), and in the ACM SIGNUM Newsletter Special Issue of
4773a8617a8SJordan K. HubbardOct. 1979, may be helpful although they pertain to
4783a8617a8SJordan K. Hubbardsuperseded drafts of the standard.
4792a6bf1faSDavid Schultz.Sh HISTORY
4802a6bf1faSDavid SchultzA math library with many of the present functions appeared in
4812a6bf1faSDavid SchultzVersion 7 AT&T UNIX.
4822a6bf1faSDavid SchultzThe library was substantially rewritten for 4.3BSD to provide
4832a6bf1faSDavid Schultzbetter accuracy and speed on machines supporting either VAX
4842a6bf1faSDavid Schultzor IEEE 754 floating-point.
4852a6bf1faSDavid SchultzMost of this library was replaced with FDLIBM, developed at Sun
4862a6bf1faSDavid SchultzMicrosystems, in
4872a6bf1faSDavid Schultz.Fx 1.1.5 .
488