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

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 .