| .\" 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. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. 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: @(#)ieee.3 6.4 (Berkeley) 5/6/91 |
| .\" $FreeBSD: src/lib/msun/man/ieee.3,v 1.22 2005/06/16 21:55:45 ru Exp $ |
| .\" |
| .Dd January 26, 2005 |
| .Dt IEEE 3 |
| .Os |
| .Sh NAME |
| .Nm ieee |
| .Nd IEEE standard 754 for floating-point arithmetic |
| .Sh DESCRIPTION |
| The IEEE Standard 754 for Binary Floating-Point Arithmetic |
| defines representations of floating-point numbers and abstract |
| properties of arithmetic operations relating to precision, |
| rounding, and exceptional cases, as described below. |
| .Ss IEEE STANDARD 754 Floating-Point Arithmetic |
| Radix: Binary. |
| .Pp |
| Overflow and underflow: |
| .Bd -ragged -offset indent -compact |
| Overflow goes by default to a signed \*(If. |
| Underflow is |
| .Em gradual . |
| .Ed |
| .Pp |
| Zero is represented ambiguously as +0 or \-0. |
| .Bd -ragged -offset indent -compact |
| 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 |
| .Fn copysign x \(+-0 . |
| In particular, comparison (x > y, x \(>= y, etc.)\& |
| cannot be affected by the sign of zero; but if |
| finite x = y then \*(If = 1/(x\-y) \(!= \-1/(y\-x) = \-\*(If. |
| .Ed |
| .Pp |
| Infinity is signed. |
| .Bd -ragged -offset indent -compact |
| It persists when added to itself |
| or to any finite number. |
| Its sign transforms |
| correctly through multiplication and division, and |
| (finite)/\(+-\*(If\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. ... |
| .Ed |
| .Pp |
| Reserved operands (\*(Nas): |
| .Bd -ragged -offset indent -compact |
| An \*(Na is |
| .Em ( N Ns ot Em a N Ns umber ) . |
| Some \*(Nas, called Signaling \*(Nas, 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 \*(Nas; 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 > y, x = y, x < y, ...) is FALSE if \*(Na is involved. |
| .Ed |
| .Pp |
| Rounding: |
| .Bd -ragged -offset indent -compact |
| Every algebraic operation (+, \-, \(**, /, |
| \(sr) |
| is rounded by default to within half an |
| .Em ulp , |
| and when the rounding error is exactly half an |
| .Em ulp |
| then |
| the rounded value's least significant bit is zero. |
| (An |
| .Em ulp |
| is one |
| .Em U Ns nit |
| in the |
| .Em L Ns ast |
| .Em P Ns lace . ) |
| 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. |
| .Ed |
| .Pp |
| Exceptions: |
| .Bd -ragged -offset indent -compact |
| IEEE 754 recognizes five kinds of floating-point exceptions, |
| listed below in declining order of probable importance. |
| .Bl -column -offset indent "Invalid Operation" "Gradual Underflow" |
| .Em "Exception Default Result" |
| Invalid Operation \*(Na, or FALSE |
| Overflow \(+-\*(If |
| Divide by Zero \(+-\*(If |
| Underflow Gradual Underflow |
| Inexact Rounded value |
| .El |
| .Pp |
| 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. |
| .Ed |
| .Ss Data Formats |
| Single-precision: |
| .Bd -ragged -offset indent -compact |
| Type name: |
| .Vt float |
| .Pp |
| Wordsize: 32 bits. |
| .Pp |
| Precision: 24 significant bits, |
| roughly like 7 significant decimals. |
| .Bd -ragged -offset indent -compact |
| If x and x' are consecutive positive single-precision |
| numbers (they differ by 1 |
| .Em ulp ) , |
| then |
| .Bd -ragged -compact |
| 5.9e\-08 < 0.5**24 < (x'\-x)/x \(<= 0.5**23 < 1.2e\-07. |
| .Ed |
| .Ed |
| .Pp |
| .Bl -column "XXX" -compact |
| Range: Overflow threshold = 2.0**128 = 3.4e38 |
| Underflow threshold = 0.5**126 = 1.2e\-38 |
| .El |
| .Bd -ragged -offset indent -compact |
| Underflowed results round to the nearest |
| integer multiple of 0.5**149 = 1.4e\-45. |
| .Ed |
| .Ed |
| .Pp |
| Double-precision: |
| .Bd -ragged -offset indent -compact |
| Type name: |
| .Vt double |
| .Bd -ragged -offset indent -compact |
| On some architectures, |
| .Vt long double |
| is the the same as |
| .Vt double . |
| .Ed |
| .Pp |
| Wordsize: 64 bits. |
| .Pp |
| Precision: 53 significant bits, |
| roughly like 16 significant decimals. |
| .Bd -ragged -offset indent -compact |
| If x and x' are consecutive positive double-precision |
| numbers (they differ by 1 |
| .Em ulp ) , |
| then |
| .Bd -ragged -compact |
| 1.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16. |
| .Ed |
| .Ed |
| .Pp |
| .Bl -column "XXX" -compact |
| Range: Overflow threshold = 2.0**1024 = 1.8e308 |
| Underflow threshold = 0.5**1022 = 2.2e\-308 |
| .El |
| .Bd -ragged -offset indent -compact |
| Underflowed results round to the nearest |
| integer multiple of 0.5**1074 = 4.9e\-324. |
| .Ed |
| .Ed |
| .Pp |
| Extended-precision: |
| .Bd -ragged -offset indent -compact |
| Type name: |
| .Vt long double |
| (when supported by the hardware) |
| .Pp |
| Wordsize: 96 bits. |
| .Pp |
| Precision: 64 significant bits, |
| roughly like 19 significant decimals. |
| .Bd -ragged -offset indent -compact |
| If x and x' are consecutive positive double-precision |
| numbers (they differ by 1 |
| .Em ulp ) , |
| then |
| .Bd -ragged -compact |
| 1.0e\-19 < 0.5**63 < (x'\-x)/x \(<= 0.5**62 < 2.2e\-19. |
| .Ed |
| .Ed |
| .Pp |
| .Bl -column "XXX" -compact |
| Range: Overflow threshold = 2.0**16384 = 1.2e4932 |
| Underflow threshold = 0.5**16382 = 3.4e\-4932 |
| .El |
| .Bd -ragged -offset indent -compact |
| Underflowed results round to the nearest |
| integer multiple of 0.5**16445 = 5.7e\-4953. |
| .Ed |
| .Ed |
| .Pp |
| Quad-extended-precision: |
| .Bd -ragged -offset indent -compact |
| Type name: |
| .Vt long double |
| (when supported by the hardware) |
| .Pp |
| Wordsize: 128 bits. |
| .Pp |
| Precision: 113 significant bits, |
| roughly like 34 significant decimals. |
| .Bd -ragged -offset indent -compact |
| If x and x' are consecutive positive double-precision |
| numbers (they differ by 1 |
| .Em ulp ) , |
| then |
| .Bd -ragged -compact |
| 9.6e\-35 < 0.5**113 < (x'\-x)/x \(<= 0.5**112 < 2.0e\-34. |
| .Ed |
| .Ed |
| .Pp |
| .Bl -column "XXX" -compact |
| Range: Overflow threshold = 2.0**16384 = 1.2e4932 |
| Underflow threshold = 0.5**16382 = 3.4e\-4932 |
| .El |
| .Bd -ragged -offset indent -compact |
| Underflowed results round to the nearest |
| integer multiple of 0.5**16494 = 6.5e\-4966. |
| .Ed |
| .Ed |
| .Ss Additional Information Regarding Exceptions |
| .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. |
| .Pp |
| 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. |
| .El |
| .Pp |
| At the option of an implementor conforming to IEEE 754, |
| other ways to cope with exceptions may be provided: |
| .Bl -enum |
| .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 |
| 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 |
| The functions in |
| .Nm libm |
| are only approximately atomic. |
| They signal no inappropriate exception except possibly ... |
| .Bl -tag -width indent -offset indent -compact |
| .It Xo |
| Over/Underflow |
| .Xc |
| when a result, if properly computed, might have lain barely within range, and |
| .It Xo |
| Inexact in |
| .Fn cabs , |
| .Fn cbrt , |
| .Fn hypot , |
| .Fn log10 |
| and |
| .Fn pow |
| .Xc |
| when it happens to be exact, thanks to fortuitous cancellation of errors. |
| .El |
| Otherwise, ... |
| .Bl -tag -width indent -offset indent -compact |
| .It Xo |
| Invalid Operation is signaled only when |
| .Xc |
| any result but \*(Na would probably be misleading. |
| .It Xo |
| Overflow is signaled only when |
| .Xc |
| the exact result would be finite but beyond the overflow threshold. |
| .It Xo |
| Divide-by-Zero is signaled only when |
| .Xc |
| a function takes exactly infinite values at finite operands. |
| .It Xo |
| Underflow is signaled only when |
| .Xc |
| the exact result would be nonzero but tinier than the underflow threshold. |
| .It Xo |
| Inexact is signaled only when |
| .Xc |
| greater range or precision would be needed to represent the exact result. |
| .El |
| .Sh SEE ALSO |
| .Xr fenv 3 , |
| .Xr ieee_test 3 , |
| .Xr math 3 |
| .Pp |
| 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 |
| .An "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 STANDARDS |
| .St -ieee754 |