1.\" Copyright (c) 1985 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91 33.\" $FreeBSD: src/lib/msun/man/ieee.3,v 1.22 2005/06/16 21:55:45 ru Exp $ 34.\" 35.Dd January 26, 2005 36.Dt IEEE 3 37.Os 38.Sh NAME 39.Nm ieee 40.Nd IEEE standard 754 for floating-point arithmetic 41.Sh DESCRIPTION 42The IEEE Standard 754 for Binary Floating-Point Arithmetic 43defines representations of floating-point numbers and abstract 44properties of arithmetic operations relating to precision, 45rounding, and exceptional cases, as described below. 46.Ss IEEE STANDARD 754 Floating-Point Arithmetic 47Radix: Binary. 48.Pp 49Overflow and underflow: 50.Bd -ragged -offset indent -compact 51Overflow goes by default to a signed \*(If. 52Underflow is 53.Em gradual . 54.Ed 55.Pp 56Zero is represented ambiguously as +0 or \-0. 57.Bd -ragged -offset indent -compact 58Its sign transforms correctly through multiplication or 59division, and is preserved by addition of zeros 60with like signs; but x\-x yields +0 for every 61finite x. 62The only operations that reveal zero's 63sign are division by zero and 64.Fn copysign x \(+-0 . 65In particular, comparison (x > y, x \(>= y, etc.)\& 66cannot be affected by the sign of zero; but if 67finite x = y then \*(If = 1/(x\-y) \(!= \-1/(y\-x) = \-\*(If. 68.Ed 69.Pp 70Infinity is signed. 71.Bd -ragged -offset indent -compact 72It persists when added to itself 73or to any finite number. 74Its sign transforms 75correctly through multiplication and division, and 76(finite)/\(+-\*(If\0=\0\(+-0 77(nonzero)/0 = \(+-\*(If. 78But 79\*(If\-\*(If, \*(If\(**0 and \*(If/\*(If 80are, like 0/0 and sqrt(\-3), 81invalid operations that produce \*(Na. ... 82.Ed 83.Pp 84Reserved operands (\*(Nas): 85.Bd -ragged -offset indent -compact 86An \*(Na is 87.Em ( N Ns ot Em a N Ns umber ) . 88Some \*(Nas, called Signaling \*(Nas, trap any floating-point operation 89performed upon them; they are used to mark missing 90or uninitialized values, or nonexistent elements 91of arrays. 92The rest are Quiet \*(Nas; they are 93the default results of Invalid Operations, and 94propagate through subsequent arithmetic operations. 95If x \(!= x then x is \*(Na; every other predicate 96(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved. 97.Ed 98.Pp 99Rounding: 100.Bd -ragged -offset indent -compact 101Every algebraic operation (+, \-, \(**, /, 102\(sr) 103is rounded by default to within half an 104.Em ulp , 105and when the rounding error is exactly half an 106.Em ulp 107then 108the rounded value's least significant bit is zero. 109(An 110.Em ulp 111is one 112.Em U Ns nit 113in the 114.Em L Ns ast 115.Em P Ns lace . ) 116This kind of rounding is usually the best kind, 117sometimes provably so; for instance, for every 118x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find 119(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ... 120despite that both the quotients and the products 121have been rounded. 122Only rounding like IEEE 754 can do that. 123But no single kind of rounding can be 124proved best for every circumstance, so IEEE 754 125provides rounding towards zero or towards 126+\*(If or towards \-\*(If 127at the programmer's option. 128.Ed 129.Pp 130Exceptions: 131.Bd -ragged -offset indent -compact 132IEEE 754 recognizes five kinds of floating-point exceptions, 133listed below in declining order of probable importance. 134.Bl -column -offset indent "Invalid Operation" "Gradual Underflow" 135.Em "Exception Default Result" 136Invalid Operation \*(Na, or FALSE 137Overflow \(+-\*(If 138Divide by Zero \(+-\*(If 139Underflow Gradual Underflow 140Inexact Rounded value 141.El 142.Pp 143NOTE: An Exception is not an Error unless handled 144badly. 145What makes a class of exceptions exceptional 146is that no single default response can be satisfactory 147in every instance. 148On the other hand, if a default 149response will serve most instances satisfactorily, 150the unsatisfactory instances cannot justify aborting 151computation every time the exception occurs. 152.Ed 153.Ss Data Formats 154Single-precision: 155.Bd -ragged -offset indent -compact 156Type name: 157.Vt float 158.Pp 159Wordsize: 32 bits. 160.Pp 161Precision: 24 significant bits, 162roughly like 7 significant decimals. 163.Bd -ragged -offset indent -compact 164If x and x' are consecutive positive single-precision 165numbers (they differ by 1 166.Em ulp ) , 167then 168.Bd -ragged -compact 1695.9e\-08 < 0.5**24 < (x'\-x)/x \(<= 0.5**23 < 1.2e\-07. 170.Ed 171.Ed 172.Pp 173.Bl -column "XXX" -compact 174Range: Overflow threshold = 2.0**128 = 3.4e38 175 Underflow threshold = 0.5**126 = 1.2e\-38 176.El 177.Bd -ragged -offset indent -compact 178Underflowed results round to the nearest 179integer multiple of 0.5**149 = 1.4e\-45. 180.Ed 181.Ed 182.Pp 183Double-precision: 184.Bd -ragged -offset indent -compact 185Type name: 186.Vt double 187.Bd -ragged -offset indent -compact 188On some architectures, 189.Vt long double 190is the the same as 191.Vt double . 192.Ed 193.Pp 194Wordsize: 64 bits. 195.Pp 196Precision: 53 significant bits, 197roughly like 16 significant decimals. 198.Bd -ragged -offset indent -compact 199If x and x' are consecutive positive double-precision 200numbers (they differ by 1 201.Em ulp ) , 202then 203.Bd -ragged -compact 2041.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16. 205.Ed 206.Ed 207.Pp 208.Bl -column "XXX" -compact 209Range: Overflow threshold = 2.0**1024 = 1.8e308 210 Underflow threshold = 0.5**1022 = 2.2e\-308 211.El 212.Bd -ragged -offset indent -compact 213Underflowed results round to the nearest 214integer multiple of 0.5**1074 = 4.9e\-324. 215.Ed 216.Ed 217.Pp 218Extended-precision: 219.Bd -ragged -offset indent -compact 220Type name: 221.Vt long double 222(when supported by the hardware) 223.Pp 224Wordsize: 96 bits. 225.Pp 226Precision: 64 significant bits, 227roughly like 19 significant decimals. 228.Bd -ragged -offset indent -compact 229If x and x' are consecutive positive double-precision 230numbers (they differ by 1 231.Em ulp ) , 232then 233.Bd -ragged -compact 2341.0e\-19 < 0.5**63 < (x'\-x)/x \(<= 0.5**62 < 2.2e\-19. 235.Ed 236.Ed 237.Pp 238.Bl -column "XXX" -compact 239Range: Overflow threshold = 2.0**16384 = 1.2e4932 240 Underflow threshold = 0.5**16382 = 3.4e\-4932 241.El 242.Bd -ragged -offset indent -compact 243Underflowed results round to the nearest 244integer multiple of 0.5**16445 = 5.7e\-4953. 245.Ed 246.Ed 247.Pp 248Quad-extended-precision: 249.Bd -ragged -offset indent -compact 250Type name: 251.Vt long double 252(when supported by the hardware) 253.Pp 254Wordsize: 128 bits. 255.Pp 256Precision: 113 significant bits, 257roughly like 34 significant decimals. 258.Bd -ragged -offset indent -compact 259If x and x' are consecutive positive double-precision 260numbers (they differ by 1 261.Em ulp ) , 262then 263.Bd -ragged -compact 2649.6e\-35 < 0.5**113 < (x'\-x)/x \(<= 0.5**112 < 2.0e\-34. 265.Ed 266.Ed 267.Pp 268.Bl -column "XXX" -compact 269Range: Overflow threshold = 2.0**16384 = 1.2e4932 270 Underflow threshold = 0.5**16382 = 3.4e\-4932 271.El 272.Bd -ragged -offset indent -compact 273Underflowed results round to the nearest 274integer multiple of 0.5**16494 = 6.5e\-4966. 275.Ed 276.Ed 277.Ss Additional Information Regarding Exceptions 278.Pp 279For each kind of floating-point exception, IEEE 754 280provides a Flag that is raised each time its exception 281is signaled, and stays raised until the program resets 282it. 283Programs may also test, save and restore a flag. 284Thus, IEEE 754 provides three ways by which programs 285may cope with exceptions for which the default result 286might be unsatisfactory: 287.Bl -enum 288.It 289Test for a condition that might cause an exception 290later, and branch to avoid the exception. 291.It 292Test a flag to see whether an exception has occurred 293since the program last reset its flag. 294.It 295Test a result to see whether it is a value that only 296an exception could have produced. 297.Pp 298CAUTION: The only reliable ways to discover 299whether Underflow has occurred are to test whether 300products or quotients lie closer to zero than the 301underflow threshold, or to test the Underflow 302flag. 303(Sums and differences cannot underflow in 304IEEE 754; if x \(!= y then x\-y is correct to 305full precision and certainly nonzero regardless of 306how tiny it may be.) 307Products and quotients that 308underflow gradually can lose accuracy gradually 309without vanishing, so comparing them with zero 310(as one might on a VAX) will not reveal the loss. 311Fortunately, if a gradually underflowed value is 312destined to be added to something bigger than the 313underflow threshold, as is almost always the case, 314digits lost to gradual underflow will not be missed 315because they would have been rounded off anyway. 316So gradual underflows are usually 317.Em provably 318ignorable. 319The same cannot be said of underflows flushed to 0. 320.El 321.Pp 322At the option of an implementor conforming to IEEE 754, 323other ways to cope with exceptions may be provided: 324.Bl -enum 325.It 326ABORT. 327This mechanism classifies an exception in 328advance as an incident to be handled by means 329traditionally associated with error-handling 330statements like "ON ERROR GO TO ...". 331Different 332languages offer different forms of this statement, 333but most share the following characteristics: 334.Bl -dash 335.It 336No means is provided to substitute a value for 337the offending operation's result and resume 338computation from what may be the middle of an 339expression. 340An exceptional result is abandoned. 341.It 342In a subprogram that lacks an error-handling 343statement, an exception causes the subprogram to 344abort within whatever program called it, and so 345on back up the chain of calling subprograms until 346an error-handling statement is encountered or the 347whole task is aborted and memory is dumped. 348.El 349.It 350STOP. 351This mechanism, requiring an interactive 352debugging environment, is more for the programmer 353than the program. 354It classifies an exception in 355advance as a symptom of a programmer's error; the 356exception suspends execution as near as it can to 357the offending operation so that the programmer can 358look around to see how it happened. 359Quite often 360the first several exceptions turn out to be quite 361unexceptionable, so the programmer ought ideally 362to be able to resume execution after each one as if 363execution had not been stopped. 364.It 365\&... Other ways lie beyond the scope of this document. 366.El 367.Pp 368Ideally, each 369elementary function should act as if it were indivisible, or 370atomic, in the sense that ... 371.Bl -enum 372.It 373No exception should be signaled that is not deserved by 374the data supplied to that function. 375.It 376Any exception signaled should be identified with that 377function rather than with one of its subroutines. 378.It 379The internal behavior of an atomic function should not 380be disrupted when a calling program changes from 381one to another of the five or so ways of handling 382exceptions listed above, although the definition 383of the function may be correlated intentionally 384with exception handling. 385.El 386.Pp 387The functions in 388.Nm libm 389are only approximately atomic. 390They signal no inappropriate exception except possibly ... 391.Bl -tag -width indent -offset indent -compact 392.It Xo 393Over/Underflow 394.Xc 395when a result, if properly computed, might have lain barely within range, and 396.It Xo 397Inexact in 398.Fn cabs , 399.Fn cbrt , 400.Fn hypot , 401.Fn log10 402and 403.Fn pow 404.Xc 405when it happens to be exact, thanks to fortuitous cancellation of errors. 406.El 407Otherwise, ... 408.Bl -tag -width indent -offset indent -compact 409.It Xo 410Invalid Operation is signaled only when 411.Xc 412any result but \*(Na would probably be misleading. 413.It Xo 414Overflow is signaled only when 415.Xc 416the exact result would be finite but beyond the overflow threshold. 417.It Xo 418Divide-by-Zero is signaled only when 419.Xc 420a function takes exactly infinite values at finite operands. 421.It Xo 422Underflow is signaled only when 423.Xc 424the exact result would be nonzero but tinier than the underflow threshold. 425.It Xo 426Inexact is signaled only when 427.Xc 428greater range or precision would be needed to represent the exact result. 429.El 430.Sh SEE ALSO 431.Xr fenv 3 , 432.Xr ieee_test 3 , 433.Xr math 3 434.Pp 435An explanation of IEEE 754 and its proposed extension p854 436was published in the IEEE magazine MICRO in August 1984 under 437the title "A Proposed Radix- and Word-length-independent 438Standard for Floating-point Arithmetic" by 439.An "W. J. Cody" 440et al. 441The manuals for Pascal, C and BASIC on the Apple Macintosh 442document the features of IEEE 754 pretty well. 443Articles in the IEEE magazine COMPUTER vol.\& 14 no.\& 3 (Mar.\& 4441981), and in the ACM SIGNUM Newsletter Special Issue of 445Oct.\& 1979, may be helpful although they pertain to 446superseded drafts of the standard. 447.Sh STANDARDS 448.St -ieee754 449