diff options
author | das <das@FreeBSD.org> | 2005-01-27 05:46:17 +0000 |
---|---|---|
committer | das <das@FreeBSD.org> | 2005-01-27 05:46:17 +0000 |
commit | 783f4bf0c2c565c36458d9573a2c27e8958da1ae (patch) | |
tree | 687ff889319c52bb4bfdc6dace80fa3197cb1b66 /lib/msun/man/ieee.3 | |
parent | 8b8557483e752ce695905e41e5bd36bb85f9cb9c (diff) | |
download | FreeBSD-src-783f4bf0c2c565c36458d9573a2c27e8958da1ae.zip FreeBSD-src-783f4bf0c2c565c36458d9573a2c27e8958da1ae.tar.gz |
- Move the functions presently described in in ieee(3) to their own
manpages. They are not very related, so separating them makes it
easier to add meaningful cross-references and extend some of the
descriptions.
- Move the part of math(3) that discusses IEEE 754 to the ieee(3)
manpage.
Diffstat (limited to 'lib/msun/man/ieee.3')
-rw-r--r-- | lib/msun/man/ieee.3 | 568 |
1 files changed, 403 insertions, 165 deletions
diff --git a/lib/msun/man/ieee.3 b/lib/msun/man/ieee.3 index 676798c..291ccd8 100644 --- a/lib/msun/man/ieee.3 +++ b/lib/msun/man/ieee.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 1985, 1991 Regents of the University of California. +.\" Copyright (c) 1985 Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -32,181 +32,419 @@ .\" from: @(#)ieee.3 6.4 (Berkeley) 5/6/91 .\" $FreeBSD$ .\" -.Dd June 20, 2004 +.Dd January 26, 2005 .Dt IEEE 3 .Os .Sh NAME -.Nm copysign , -.Nm copysignf , -.Nm copysignl , -.Nm finite , -.Nm finitef , -.Nm ilogb , -.Nm ilogbf , -.Nm ilogbl , -.Nm nextafter , -.Nm nextafterf , -.Nm remainder , -.Nm remainderf , -.Nm scalbln , -.Nm scalblnf , -.Nm scalbn , -.Nm scalbnf -.Nd functions for IEEE arithmetic -.Sh LIBRARY -.Lb libm -.Sh SYNOPSIS -.In math.h -.Ft double -.Fn copysign "double x" "double y" -.Ft float -.Fn copysignf "float x" "float y" -.Ft long double -.Fn copysignl "long double x" "long double y" -.Ft int -.Fn finite "double x" -.Ft int -.Fn finitef "float x" -.Ft int -.Fn ilogb "double x" -.Ft int -.Fn ilogbf "float x" -.Ft int -.Fn ilogbl "long double x" -.Ft double -.Fn nextafter "double x" "double y" -.Ft float -.Fn nextafterf "float x" "float y" -.Ft double -.Fn remainder "double x" "double y" -.Ft float -.Fn remainderf "float x" "float y" -.Ft double -.Fn scalbln "double x" "long n" -.Ft float -.Fn scalblnf "float x" "long n" -.Ft double -.Fn scalbn "double x" "int n" -.Ft float -.Fn scalbnf "float x" "int n" +.Nm ieee +.Nd IEEE standard 754 for floating-point arithmetic .Sh DESCRIPTION -These functions are required or recommended by -.St -ieee754 . +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 -The -.Fn copysign , -.Fn copysignf -and -.Fn copysignl -functions -return -.Fa x -with its sign changed to -.Fa y Ns 's . -.Pp -.Fn finite -and -.Fn finitef -return the value 1 just when -\-\*(If \*(Lt -.Fa x -\*(Lt +\*(If; -otherwise a -zero is returned -(when -.Pf \\*(Ba Ns Fa x Ns \\*(Ba -= \*(If or -.Fa x -is \*(Na). -.Pp -.Fn ilogb , -.Fn ilogbf -and -.Fn ilogbl -return -.Fa x Ns 's exponent, -in integer format. -.Fn ilogb \*(Pm\*(If -returns -.Dv INT_MAX , -.Fn ilogb \*(Pm\*(Na -returns -.Dv FP_ILOGBNAN -and -.Fn ilogb 0 -returns -.Dv FP_ILOGB0 . +.Bl -column "" -compact +Overflow and underflow: +.El +.Bd -ragged -offset indent -compact +Overflow goes by default to a signed \*(If. +Underflow is +.Em gradual . +.Ed .Pp -.Fn nextafter -and -.Fn nextafterf -return the next machine representable number from -.Fa x -in direction -.Fa y . +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 -.Fn remainder -and -.Fn remainderf -return the remainder -.Fa r -:= -.Fa x -\- -.Fa n\(**y -where -.Fa n -is the integer nearest the exact value of -.Bk -words -.Fa x Ns / Ns Fa y ; -.Ek -moreover if -.Pf \\*(Ba Fa n -\- -.Sm off -.Fa x No / Fa y No \\*(Ba -.Sm on -= -1/2 -then -.Fa n -is even. -Consequently -the remainder is computed exactly and -.Sm off -.Pf \\*(Ba Fa r No \\*(Ba -.Sm on -\*(Le -.Sm off -.Pf \\*(Ba Fa y No \\*(Ba/2 . -.Sm on +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 -.Fn remainder x 0 -and -.Fn remainder \*(If 0 -are invalid operations that produce a \*(Na. +\*(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 -.Fn scalbln , -.Fn scalblnf , -.Fn scalbn , +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**16451 = 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 scalbnf -return -.Fa x Ns \(**(2** Ns Fa n ) -computed by exponent manipulation. +.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 -.Sh HISTORY -The -.Nm ieee -functions appeared in -.Bx 4.3 . -The -.Fn copysignl , -.Fn scalbln , -and -.Fn scalblnf -functions first appeared in -.Fx 5.3 . |