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