Remove math(3). OK theo.

2 files changed, 2 insertions, 731 deletions

diff --git a/lib/libm/Makefile b/lib/libm/Makefile
index 783a2ea308c..08b143d08f8 100644
--- a/lib/libm/Makefile
+++ b/lib/libm/Makefile
@@ -1,4 +1,4 @@
-#  $OpenBSD: Makefile,v 1.85 2011/07/07 00:54:15 martynas Exp $
+#  $OpenBSD: Makefile,v 1.86 2011/07/07 01:20:24 martynas Exp $
 #  $NetBSD: Makefile,v 1.28 1995/11/20 22:06:19 jtc Exp $
 #
 #  @(#)Makefile 5.1beta 93/09/24 
@@ -193,7 +193,7 @@ MAN+=	acos.3 acosh.3 asin.3 asinh.3 atan.3 atan2.3 atanh.3 ceil.3 \
 	cimag.3 conj.3 copysign.3 cos.3 cosh.3 cproj.3 erf.3 exp.3 \
 	fabs.3 fdim.3 feclearexcept.3 feenableexcept.3 fegetenv.3 \
 	fegetround.3 floor.3 fmax.3 fmod.3 hypot.3 ilogb.3 j0.3 \
-	lgamma.3 logb.3 lrint.3 lround.3 math.3 nan.3 nextafter.3 \
+	lgamma.3 logb.3 lrint.3 lround.3 nan.3 nextafter.3 \
 	remainder.3 rint.3 round.3 scalbn.3 sin.3 sinh.3 sqrt.3 \
 	tan.3 tanh.3 trunc.3
 
@@ -278,7 +278,6 @@ MLINKS+=lrint.3 llrintf.3
 MLINKS+=lrint.3 lrintf.3
 MLINKS+=lround.3 llroundf.3
 MLINKS+=lround.3 lroundf.3
-MLINKS+=math.3 mathf.3
 MLINKS+=nan.3 nanf.3
 MLINKS+=nearbyint.3 nearbyintf.3
 MLINKS+=nextafter.3 nextafterf.3
diff --git a/lib/libm/man/math.3 b/lib/libm/man/math.3
deleted file mode 100644
index d3338ab3deb..00000000000
--- a/lib/libm/man/math.3
+++ /dev/null
@@ -1,728 +0,0 @@
-.\"	$OpenBSD: math.3,v 1.25 2010/02/20 20:37:51 schwarze Exp $
-.\" 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. 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: @(#)math.3	6.10 (Berkeley) 5/6/91
-.\"
-.Dd $Mdocdate: February 20 2010 $
-.Dt MATH 3
-.Os
-.Sh NAME
-.Nm math
-.Nd introduction to mathematical library functions
-.Sh DESCRIPTION
-These functions constitute the C math library,
-.Em libm .
-The link editor searches this library under the
-.Dq -lm
-option.
-Declarations for these functions may be obtained from the include file
-.Aq Pa math.h .
-.Sh LIST OF FUNCTIONS
-.Bl -column "copysign(3)" "inverse trigonometric function" "ULPs"
-.It \fIName\fP Ta \fIDescription\fP Ta "\fIULPs\fP"
-.It acos(3) Ta "inverse trigonometric function" Ta 3
-.It acosh(3) Ta "inverse hyperbolic function" Ta 3
-.It asin(3) Ta "inverse trigonometric function" Ta 3
-.It asinh(3) Ta "inverse hyperbolic function" Ta 3
-.It atan(3) Ta "inverse trigonometric function" Ta 1
-.It atan2(3) Ta "inverse trigonometric function" Ta 2
-.It atanh(3) Ta "inverse hyperbolic function" Ta 3
-.It cabs(3) Ta "complex absolute value" Ta 1
-.It cbrt(3) Ta "cube root" Ta 1
-.It ceil(3) Ta "integer no less than" Ta 0
-.It copysign(3) Ta "copy sign bit" Ta 0
-.It cos(3) Ta "trigonometric function" Ta 1
-.It cosh(3) Ta "hyperbolic function" Ta 3
-.It erf(3) Ta "error function" Ta 1
-.It erfc(3) Ta "complementary error function" Ta 1
-.It exp(3) Ta "exponential" Ta 1
-.It expm1(3) Ta "exp(x)-1" Ta 1
-.It fabs(3) Ta "absolute value" Ta 0
-.It floor(3) Ta "integer no greater than" Ta 0
-.It fmod(3) Ta "remainder" Ta 0
-.It fpclassify(3) Ta "classify real floating type" Ta 0
-.It hypot(3) Ta "Euclidean distance" Ta 1
-.It ilogb(3) Ta "exponent extraction" Ta 0
-.It isfinite(3) Ta "test for finite value" Ta 0
-.It isinf(3) Ta "check for infinity" Ta 0
-.It isnan(3) Ta "check for not-a-number" Ta 0
-.It isnormal(3) Ta "test for normal value" Ta 0
-.It j0(3) Ta "Bessel function" Ta ???
-.It j1(3) Ta "Bessel function" Ta ???
-.It jn(3) Ta "Bessel function" Ta ???
-.It lgamma(3) Ta "log gamma function" Ta 1
-.It log(3) Ta "natural logarithm" Ta 1
-.It log10(3) Ta "logarithm to base 10" Ta 3
-.It log1p(3) Ta "log(1+x)" Ta 1
-.It nan(3) Ta "generate NaN" Ta 0
-.It nextafter(3) Ta "next representable number" Ta 0
-.It pow(3) Ta "exponential x**y" Ta 60-500
-.It remainder(3) Ta "remainder" Ta 0
-.It remquo(3) Ta "remainder" Ta 0
-.It rint(3) Ta "round to nearest integer" Ta 0
-.It round(3) Ta "round to nearest integer" Ta 0
-.It scalbn(3) Ta "exponent adjustment" Ta 0
-.It signbit(3) Ta "test sign" Ta 0
-.It sin(3) Ta "trigonometric function" Ta 1
-.It sinh(3) Ta "hyperbolic function" Ta 3
-.It sqrt(3) Ta "square root" Ta 1
-.It tan(3) Ta "trigonometric function" Ta 3
-.It tanh(3) Ta "hyperbolic function" Ta 3
-.It tgamma(3) Ta "gamma function" Ta 4
-.It trunc(3) Ta "nearest integral value" Ta 3
-.It y0(3) Ta "Bessel function" Ta ???
-.It y1(3) Ta "Bessel function" Ta ???
-.It yn(3) Ta "Bessel function" Ta ???
-.El
-.Sh NOTES
-In
-.Bx 4.3 ,
-distributed from the University of California
-in late 1985, most of the foregoing functions come in two
-versions, one for the double-precision
-.Dq D
-format in the
-.Tn DEC VAX-11
-family of computers, another for double-precision
-arithmetic conforming to
-.St -ieee754 .
-The two versions behave very
-similarly, as should be expected from programs more accurate
-and robust than was the norm when
-.Ux
-was born.
-For
-instance, the programs are accurate to within the number of
-.Em ulp Ns s
-tabulated above; a
-.Em ulp
-is one
-.Em U Ns nit
-in the
-.Em L Ns ast
-.Em P Ns lace .
-The functions have been cured of anomalies that
-afflicted the older math library in which incidents like
-the following had been reported:
-.Bd -unfilled -offset indent
-sqrt(-1.0) = 0.0 and log(-1.0) = -1.7e38.
-cos(1.0e-11) \*(Gt cos(0.0) \*(Gt 1.0.
-pow(x,1.0) \*(Ne x when x = 2.0, 3.0, 4.0, ..., 9.0.
-pow(-1.0,1.0e10) trapped on Integer Overflow.
-sqrt(1.0e30) and sqrt(1.0e-30) were very slow.
-.Ed
-.Pp
-However, the two versions do differ in ways that have to be
-explained, to which end the following notes are provided.
-.Ss DEC VAX-11 D_floating-point:
-This is the format for which the original math library
-was developed, and to which this manual is still principally
-dedicated.
-It is
-.Em the
-double-precision format for the PDP-11
-and the earlier VAX-11 machines; VAX-11s after 1983 were
-provided with an optional
-.Dq G
-format closer to the
-.Tn IEEE
-double-precision format.
-The earlier
-.Tn DEC MicroVAXs
-have no D format, only G double-precision.
-(Why? Why not?)
-.Pp
-Properties of D_floating-point:
-.Bl -tag -width "Precision:" -offset indent -compact
-.It Wordsize:
-64 bits, 8 bytes.
-.It Radix:
-Binary.
-.It Precision:
-56 significant bits, roughly 17 significant decimal digits.
-If x and x' are consecutive positive D_floating-point
-numbers (they differ by 1 \fIulp\fR), then
-.Li 1.3e-17 \*(Lt 0.5**56 \*(Lt (x'-x)/x \*(Le 0.5**55 \*(Lt 2.8e-17.
-.It Range:
-Overflow threshold = 2.0**127 = 1.7e38.
-.br
-Underflow threshold = 0.5**128 = 2.9e-39.
-.br
-NOTE: THIS RANGE IS COMPARATIVELY NARROW.
-.br
-Overflow customarily stops computation.
-.br
-Underflow is customarily flushed quietly to zero.
-.br
-CAUTION:
-.Bd -filled -offset indent -compact
-It is possible to have x \*(Ne y and yet x-y = 0 because of underflow.
-Similarly x \*(Gt y \*(Gt 0 cannot prevent either x\(**y = 0
-or y/x = 0 from happening without warning.
-.Ed
-.It Zero is represented ambiguously.
-Although 2**55 different representations of zero are accepted by
-the hardware, only the obvious representation is ever produced.
-There is no -0 on a VAX.
-.It \*(If is not part of the VAX architecture.
-.It Reserved operands:
-Of the 2**55 that the hardware
-recognizes, only one of them is ever produced.
-Any floating-point operation upon a reserved
-operand, even a MOVF or MOVD, customarily stops
-computation, so they are not much used.
-.It Exceptions:
-Divisions by zero and operations that
-overflow are invalid operations that customarily
-stop computation or, in earlier machines, produce
-reserved operands that will stop computation.
-.It Rounding:
-Every rational operation (+, -, \(**, /) on a
-VAX (but not necessarily on a PDP-11), if not an
-over/underflow nor division by zero, is rounded to
-within half a \fIulp\fR, and when the rounding error is
-exactly half a \fIulp\fR then rounding is away from 0.
-.El
-.Pp
-Except for its narrow range, D_floating-point is one of the
-better computer arithmetics designed in the 1960's.
-Its properties are reflected fairly faithfully in the elementary
-functions for a VAX distributed in
-.Bx 4.3 .
-They over/underflow only if their results have to lie out of range
-or very nearly so, and then they behave much as any rational
-arithmetic operation that over/underflowed would behave.
-Similarly, expressions like log(0) and atanh(1) behave
-like 1/0; and sqrt(-3) and acos(3) behave like 0/0;
-they all produce reserved operands and/or stop computation!
-The situation is described in more detail in manual pages.
-.Bd -filled -offset indent
-\fIThis response seems excessively punitive, so it is destined
-to be replaced at some time in the foreseeable future by a
-more flexible but still uniform scheme being developed to
-handle all floating-point arithmetic exceptions neatly.
-See
-.Xr infnan 3
-for the present state of affairs.\fR
-.Ed
-.Pp
-How do the functions in
-.Bx 4.3 's
-new
-.Em libm
-for UNIX compare with their counterparts in
-.Tn DEC's VAX/VMS
-library?
-Some of the
-.Tn VMS
-functions are a little faster, some are
-a little more accurate, some are more puritanical about
-exceptions (like pow(0.0,0.0) and atan2(0.0,0.0)),
-and most occupy much more memory than their counterparts in
-.Em libm .
-The
-.Tn VMS
-implementations interpolate in large table to achieve
-speed and accuracy; the
-.Em libm
-implementations use tricky formulas compact enough that all of them may some
-day fit into a ROM.
-.Pp
-More importantly,
-.Tn DEC
-considers the
-.Tn VMS
-implementation proprietary and guards it zealously against unauthorized use.
-In contrast, the
-.Em libm
-included in
-.Bx 4.3
-is freely distributable;
-it may be copied freely provided their provenance is always
-acknowledged.
-Therefore, no user of
-.Ux
-on a machine whose arithmetic resembles VAX D_floating-point need use
-anything worse than the new
-.Em libm .
-.Ss IEEE STANDARD 754 Floating-Point Arithmetic:
-This is the most widely adopted standard for computer arithmetic.
-VLSI chips that conform to some version of that standard have been
-produced by a host of manufacturers, among them:
-.Pp
-.Bl -column -offset indent -compact "Intel i8070, i80287" "Western Electric (AT&T) WE32106"
-.It "Intel i8087, i80287" Ta "National Semiconductor 32081"
-.It "Motorola 68881" Ta "Weitek WTL-1032, ... , -1165"
-.It "Zilog Z8070" Ta "Western Electric (AT&T) WE32106"
-.El
-.Pp
-Other implementations range from software, done thoroughly
-for the Apple Macintosh, through VLSI in the Hewlett-Packard
-9000 series, to the ELXSI 6400 running ECL at 3 Megaflops.
-Several other companies have adopted the formats of
-.St -ieee754
-without, alas, adhering to the standard's method
-of handling rounding and exceptions such as over/underflow.
-The
-.Tn DEC VAX
-G_floating-point format is very similar to
-.St -ieee754
-Double format.
-It is so similar that the C programs for the
-.Tn IEEE
-versions of most of the elementary functions listed
-above could easily be converted to run on a
-.Tn MicroVAX ,
-though nobody has volunteered to do that yet.
-.Pp
-The code in
-.Bx 4.3 's
-.Em libm
-for machines that conform to
-.St -ieee754
-is intended primarily for the National Semi. 32081 and WTL 1164/65.
-To use this code with the Intel or Zilog chips, or with the Apple
-Macintosh or ELXSI 6400, is to forego the use of better code
-provided (perhaps for free) by those companies and designed by some
-of the authors of the code above.
-Except for
-.Fn atan ,
-.Fn cabs ,
-.Fn cbrt ,
-.Fn erf ,
-.Fn erfc ,
-.Fn hypot ,
-.Fn j0-jn ,
-.Fn lgamma ,
-.Fn pow
-and
-.Fn y0
--
-.Fn yn ,
-the Motorola 68881 has all the functions in
-.Em libm
-on chip, and is faster and more accurate to boot;
-it, Apple, the i8087, Z8070 and WE32106 all use 64 significant bits.
-The main virtue of
-.Bx 4.3 's
-.Em libm
-is that it is freely distributable;
-it may be copied freely provided its provenance is always acknowledged.
-Therefore no user of
-.Ux
-on a machine that conforms to
-.St -ieee754
-need use anything worse than the new
-.Em libm .
-.Pp
-Properties of
-.St -ieee754
-Double-Precision:
-.Bl -tag -width "Precision:" -offset indent -compact
-.It Wordsize:
-64 bits, 8 bytes.
-.It Radix:
-Binary.
-.It Precision:
-53 significant bits, roughly equivalent to 16 significant decimals.
-.br
-If x and x' are consecutive positive Double-Precision
-numbers (they differ by 1 \fIulp\fR, then
-.br
-.Li 1.1e-16 \*(Lt 0.5**53 \*(Lt (x'-x)/x \*(Le 0.5**52 \*(Lt 2.3e-16.
-.It Range:
-Overflow threshold = 2.0**1024 = 1.8e308
-.br
-Underflow threshold = 0.5**1022 = 2.2e-308
-.br
-Overflow goes by default to a signed \*(If.
-.br
-Underflow is
-.Em Gradual ,
-rounding to the nearest integer multiple of 0.5**1074 = 4.9e-324.
-.It Zero is represented ambiguously as +0 or -0.
-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 copysign(x,\*(Pm0).
-In particular, comparison (x \*(Gt y, x \*(Ge y, etc.)
-cannot be affected by the sign of zero; but if
-finite x = y then \*(If \&= 1/(x-y) \*(Ne -1/(y-x) = -\*(If.
-.It \*(If is signed.
-It persists when added to itself or to any finite number.
-Its sign transforms correctly through multiplication and division, and
-(finite)/\*(Pm\*(If \0=\0\*(Pm0 (nonzero)/0 = \*(Pm\*(If.
-But \*(If-\*(If, \*(If\(**0 and \*(If/\*(If are, like 0/0 and sqrt(-3),
-invalid operations that produce \*(Na.
-.It Reserved operands:
-There are 2**53-2 of them, all
-called \*(Na (\fIN\fRot \fIa N\fRumber).
-Some, 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 \*(Ne x then x is \*(Na; every other predicate
-(x \*(Gt y, x = y, x \*(Lt y, ...) is FALSE if \*(Na is involved.
-.br
-.Bl -tag -width "NOTE:" -compact
-.It NOTE:
-Trichotomy is violated by \*(Na.
-Besides being FALSE, predicates that entail ordered
-comparison, rather than mere (in)equality,
-signal Invalid Operation when \*(Na is involved.
-.El
-.It Rounding:
-Every algebraic operation (+, -, \(**, /, sqrt)
-is rounded by default to within half a \fIulp\fR, and
-when the rounding error is exactly half a \fIulp\fR then
-the rounded value's least significant bit is zero.
-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
-.St -ieee754
-can do that.
-But no single kind of rounding can be
-proved best for every circumstance, so
-.St -ieee754
-provides rounding towards zero or towards +\*(If or
-towards -\*(If at the programmer's discretion.
-The same kinds of rounding are specified for
-Binary-Decimal Conversions, at least for magnitudes
-between roughly 1.0e-10 and 1.0e37.
-.It Exceptions:
-.St -ieee754
-recognizes five kinds of floating-point exceptions,
-listed below in declining order of probable importance.
-.Bl -column -offset indent -compact "Invalid Operation" "Gradual Underflow"
-.It Em Exception Ta Em Default Result
-.It "Invalid Operation" Ta "\*(Na, or FALSE"
-.It "Overflow" Ta "\*(Pm\*(If"
-.It "Divide by Zero" Ta "\*(Pm\*(If"
-.It "Underflow" Ta "Gradual Underflow"
-.It "Inexact" Ta "Rounded value"
-.El
-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.
-.El
-.Pp
-For each kind of floating-point exception,
-.St -ieee754
-provides a
-.Em 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,
-.St -ieee754
-provides three ways by which programs may cope with exceptions for
-which the default result might be unsatisfactory:
-.Bl -tag -width XXX
-.It 1)
-Test for a condition that might cause an exception
-later, and branch to avoid the exception.
-.It 2)
-Test a flag to see whether an exception has occurred
-since the program last reset its flag.
-.It 3)
-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
-.St -ieee754 ;
-if x \*(Ne 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
-.Tn 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 \fIprovably\fR ignorable.
-The same cannot be said of underflows flushed to 0.
-.El
-.Pp
-At the option of an implementor conforming to
-.St -ieee754 ,
-other ways to cope with exceptions may be provided:
-.Bl -tag -width XXX
-.It 4)
-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 5)
-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.
-Often times 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 6)
-\&... Other ways lie beyond the scope of this document.
-.El
-.Pp
-The crucial problem for exception handling is the problem of
-Scope, and the problem's solution is understood, but not
-enough manpower was available to implement it fully in time
-to be distributed in
-.Bx 4.3 's
-.Em libm .
-Ideally, each elementary function should act as if it were indivisible,
-or atomic, in the sense that ...
-.Bl -tag -width Ds -offset XXXX
-.It i)
-No exception should be signaled that is not deserved by
-the data supplied to that function.
-.It ii)
-Any exception signaled should be identified with that
-function rather than with one of its subroutines.
-.It iii)
-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
-Ideally, every programmer should be able to
-.Em conveniently
-turn a debugged subprogram into one that appears atomic to its users.
-But simulating all three characteristics of an atomic function is still
-a tedious affair, entailing hosts of tests and saves-restores;
-work is under way to ameliorate the inconvenience.
-.Pp
-Meanwhile, the functions in
-.Em libm
-are only approximately atomic.
-They signal no inappropriate exception except possibly:
-.Pp
-.Bl -tag -width Ds -offset indent -compact
-.It Over/Underflow
-when a result, if properly computed, might have lain barely within range, and
-.It Inexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR
-when it happens to be exact, thanks to fortuitous cancellation of errors.
-.El
-.Pp
-Otherwise:
-.Pp
-.Bl -tag -width Ds -offset indent -compact
-.It Invalid Operation is signaled only when
-any result but \*(Na would probably be misleading.
-.It Overflow is signaled only when
-the exact result would be finite but beyond the overflow threshold.
-.It Divide-by-Zero is signaled only when
-a function takes exactly infinite values at finite operands.
-.It Underflow is signaled only when
-the exact result would be nonzero but tinier than the underflow threshold.
-.It Inexact is signaled only when
-greater range or precision would be needed to represent the exact result.
-.El
-.Pp
-Properties of
-.St -ieee754
-Single-Precision:
-.Bl -tag -width "Precision:" -offset indent -compact
-.It Wordsize:
-32 bits, 4 bytes.
-.It Radix:
-Binary.
-.It Precision:
-24 significant bits, roughly equivalent to 7 significant decimals.
-.br
-If x and x' are consecutive positive Double-Precision
-numbers (they differ by 1 \fIulp\fR, then
-.br
-.Li 6.0e-8 \*(Lt 0.5**24 \*(Lt (x'-x)/x \*(Le 0.5**23 \*(Lt 1.2e-7.
-.It Range:
-Overflow threshold = 2.0**128 = 3.4e38.
-.br
-Underflow threshold = 0.5**126 = 1.2e-38
-.br
-Overflow goes by default to a signed \*(If.
-.br
-Underflow is
-.Em Gradual ,
-rounding to the nearest integer multiple of 0.5**149 = 1.4e-45.
-.It Zero is represented ambiguously as +0 or -0.
-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 copysign(x,\*(Pm0).
-In particular, comparison (x \*(Gt y, x \*(Ge y, etc.)
-cannot be affected by the sign of zero; but if
-finite x = y then \*(If \&= 1/(x-y) \*(Ne -1/(y-x) = -\*(If.
-.It \*(If is signed.
-It persists when added to itself or to any finite number.
-Its sign transforms correctly through multiplication and division, and
-(finite)/\*(Pm\*(If \0=\0\*(Pm0 (nonzero)/0 = \*(Pm\*(If.
-But \*(If-\*(If, \*(If\(**0 and \*(If/\*(If are, like 0/0 and sqrt(-3),
-invalid operations that produce \*(Na.
-.It Reserved operands:
-There are 2**24-2 of them, all
-called \*(Na (\fIN\fRot \fIa N\fRumber).
-Some, 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 \*(Ne x then x is \*(Na; every other predicate
-(x \*(Gt y, x = y, x \*(Lt y, ...) is FALSE if \*(Na is involved.
-.br
-.Bl -tag -width "NOTE:" -compact
-.It NOTE:
-Trichotomy is violated by \*(Na.
-Besides being FALSE, predicates that entail ordered
-comparison, rather than mere (in)equality,
-signal Invalid Operation when \*(Na is involved.
-.El
-.It Rounding:
-Every algebraic operation (+, -, \(**, /, sqrt)
-is rounded by default to within half a \fIulp\fR, and
-when the rounding error is exactly half a \fIulp\fR then
-the rounded value's least significant bit is zero.
-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
-.St -ieee754
-can do that.
-But no single kind of rounding can be
-proved best for every circumstance, so
-.St -ieee754
-provides rounding towards zero or towards +\*(If or
-towards -\*(If at the programmer's discretion.
-The same kinds of rounding are specified for
-Binary-Decimal Conversions, at least for magnitudes
-between roughly 1.0e-10 and 1.0e37.
-.It Exceptions:
-.St -ieee754
-recognizes five kinds of floating-point exceptions,
-listed below in declining order of probable importance.
-.Bl -column -offset indent -compact "Invalid Operation" "Gradual Underflow"
-.It Em Exception Ta Em Default Result
-.It "Invalid Operation" Ta "\*(Na, or FALSE"
-.It "Overflow" Ta "\*(Pm\*(If"
-.It "Divide by Zero" Ta "\*(Pm\*(If"
-.It "Underflow" Ta "Gradual Underflow"
-.It "Inexact" Ta "Rounded value"
-.El
-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.
-.El
-.Sh SEE ALSO
-An explanation of
-.St -ieee754
-and its proposed extension p854
-was published in the
-.Tn IEEE
-magazine MICRO in August 1984 under
-the title "A Proposed Radix- and Word-length-independent
-Standard for Floating-point Arithmetic" by W. J. Cody et al.
-The manuals for Pascal, C and BASIC on the Apple Macintosh
-document the features of
-.St -ieee754
-pretty well.
-Articles in the
-.Tn IEEE
-magazine COMPUTER vol. 14 no. 3 (Mar. 1981), and in the
-.Tn ACM SIGNUM
-Newsletter Special Issue of Oct. 1979, may be helpful although they pertain to
-superseded drafts of the standard.
-.Sh BUGS
-When signals are appropriate, they are emitted by certain
-operations within
-.Em libm ,
-so a subroutine-trace may be needed to identify the function with its
-signal in case method 5) above is in use.
-All the code in
-.Em libm
-takes the
-.St -ieee754
-defaults for granted; this means that a decision to
-trap all divisions by zero could disrupt a function that would
-otherwise get a correct result despite division by zero.