.\" 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 |