From 90232fdf166bed3f534f1c1c43e29c1f17d4b51d Mon Sep 17 00:00:00 2001
From: David Schultz <das@FreeBSD.org>
Date: Tue, 5 Apr 2005 02:57:28 +0000
Subject: [PATCH] Document exp2() and exp2f(), and make other minor tweaks and
 updates.

---
 lib/msun/man/exp.3  | 107 +++++++++++---------------------------------
 lib/msun/man/math.3 |  18 ++++----
 2 files changed, 37 insertions(+), 88 deletions(-)

diff --git a/lib/msun/man/exp.3 b/lib/msun/man/exp.3
index d1ba7da800ee..0fb5878f0f0f 100644
--- a/lib/msun/man/exp.3
+++ b/lib/msun/man/exp.3
@@ -32,12 +32,15 @@
 .\"     from: @(#)exp.3	6.12 (Berkeley) 7/31/91
 .\" $FreeBSD$
 .\"
-.Dd January 14, 2005
+.Dd April 5, 2005
 .Dt EXP 3
 .Os
 .Sh NAME
 .Nm exp ,
 .Nm expf ,
+.\" The sorting error is intentional.  exp and expf should be adjacent.
+.Nm exp2 ,
+.Nm exp2f ,
 .Nm expm1 ,
 .Nm expm1f ,
 .Nm log ,
@@ -58,6 +61,10 @@
 .Ft float
 .Fn expf "float x"
 .Ft double
+.Fn exp2 "double x"
+.Ft float
+.Fn exp2f "float x"
+.Ft double
 .Fn expm1 "double x"
 .Ft float
 .Fn expm1f "float x"
@@ -82,7 +89,16 @@ The
 .Fn exp
 and the
 .Fn expf
-functions compute the exponential value of the given argument
+functions compute the base
+.Ms e
+exponential value of the given argument
+.Fa x .
+.Pp
+The
+.Fn exp2
+and the
+.Fn exp2f
+functions compute the base 2 exponential of the given argument
 .Fa x .
 .Pp
 The
@@ -125,57 +141,16 @@ of
 to the exponent
 .Ar y .
 .Sh ERROR (due to Roundoff etc.)
-.Fn exp x ,
-.Fn log x ,
-.Fn expm1 x
+The values of
+.Fn exp 0 ,
+.Fn expm1 0 ,
+.Fn exp2 integer ,
 and
-.Fn log1p x
-are accurate to within
-an
-.Em ulp ,
-and
-.Fn log10 x
-to within about 2
-.Em ulps ;
-an
-.Em ulp
-is one
-.Em Unit
-in the
-.Em Last
-.Em Place .
-The error in
-.Fn pow x y
-is below about 2
-.Em ulps
-when its
-magnitude is moderate, but increases as
-.Fn pow x y
-approaches
-the over/underflow thresholds until almost as many bits could be
-lost as are occupied by the floating\-point format's exponent
-field; that is 8 bits for
-.Tn "VAX D"
-and 11 bits for IEEE 754 Double.
-No such drastic loss has been exposed by testing; the worst
-errors observed have been below 20
-.Em ulps
-for
-.Tn "VAX D" ,
-300
-.Em ulps
-for
-.Tn IEEE
-754 Double.
-Moderate values of
-.Fn pow
-are accurate enough that
 .Fn pow integer integer
-is exact until it is bigger than 2**56 on a
-.Tn VAX ,
-2**53 for
-.Tn IEEE
-754.
+are exact provided that they are representable.
+.\" XXX Is this really true for pow()?
+Otherwise the error in these functions is generally below one
+.Em ulp .
 .Sh RETURN VALUES
 These functions will return the appropriate computation unless an error
 occurs or an argument is out of range.
@@ -214,15 +189,7 @@ They also provide accurate inverse hyperbolic functions.
 .Pp
 The function
 .Fn pow x 0
-returns x**0 = 1 for all x including x = 0,
-\*(If
-(not found on a
-.Tn VAX ) ,
-and
-.Em NaN
-(the reserved
-operand on a
-.Tn VAX ) .
+returns x**0 = 1 for all x including x = 0, \*(If, and \*(Na .
 Previous implementations of pow may
 have defined x**0 to be undefined in some or all of these
 cases.
@@ -267,23 +234,3 @@ and infinite x, i.e., independently of x.
 .Sh SEE ALSO
 .Xr fenv 3 ,
 .Xr math 3
-.Sh HISTORY
-A
-.Fn exp ,
-.Fn log
-and
-.Fn pow
-functions
-appeared in
-.At v6 .
-A
-.Fn log10
-function
-appeared in
-.At v7 .
-The
-.Fn log1p
-and
-.Fn expm1
-functions appeared in
-.Bx 4.3 .
diff --git a/lib/msun/man/math.3 b/lib/msun/man/math.3
index 142f75e99a4a..1c83bf8ec60d 100644
--- a/lib/msun/man/math.3
+++ b/lib/msun/man/math.3
@@ -32,7 +32,7 @@
 .\"	from: @(#)math.3	6.10 (Berkeley) 5/6/91
 .\" $FreeBSD$
 .\"
-.Dd March 24, 2005
+.Dd April 5, 2005
 .Dt MATH 3
 .Os
 .if n \{\
@@ -174,7 +174,7 @@ cosh	hyperbolic cosine
 erf	error function
 erfc	complementary error function
 exp	exponential base e
-.\" exp2	exponential base 2
+exp2	exponential base 2
 expm1	exp(x)\-1
 j0	Bessel function of the first kind of the order 0
 j1	Bessel function of the first kind of the order 1
@@ -196,10 +196,10 @@ yn	Bessel function of the second kind of the order n
 .El
 .Pp
 Unlike the algebraic functions listed earlier, the routines
-in this section may not produce a result that is correctly rounded.
-In general, an unbounded number of digits of a value taken by a
-transcendental function may be needed to determine the correctly rounded
-result.
+in this section may not produce a result that is correctly rounded,
+so reproducible results cannot be guaranteed across platforms.
+For most of these functions, however, incorrect rounding occurs
+rarely, and then only in very-close-to-halfway cases.
 .Sh SEE ALSO
 .Xr fenv 3 ,
 .Xr ieee 3
@@ -221,14 +221,16 @@ and
 values, were written for or imported into subsequent versions of FreeBSD.
 .Sh BUGS
 The
-.Fn exp2 ,
-.Fn log2 ,
+.Fn log2
 and
 .Fn nan
 functions are missing, and many functions are not available in their
 .Vt "long double"
 variants.
 .Pp
+Many of the routines to compute transcendental functions produce
+inaccurate results in other than the default rounding mode.
+.Pp
 On some architectures, trigonometric argument reduction is not
 performed accurately, resulting in errors greater than 1
 .Em ulp