BSD 4_3_Net_2 release

[unix-history] / usr / src / lib / libm / common_source / ieee.3

diff --git a/usr/src/lib/libm/common_source/ieee.3 b/usr/src/lib/libm/common_source/ieee.3
index e13f845..7883cfa 100644 (file)
--- a/usr/src/lib/libm/common_source/ieee.3
+++ b/usr/src/lib/libm/common_source/ieee.3
@@ -1,128 +1,269 @@
-From Prof. Kahan at UC at Berkeley
-.\" Copyright (c) 1985 Regents of the University of California.
-.\" All rights reserved.  The Berkeley software License Agreement
-.\" specifies the terms and conditions for redistribution.
+.\" Copyright (c) 1985, 1991 Regents of the University of California.
+.\" All rights reserved.

 .\"
 .\"

-.\"    @(#)ieee.3      6.2 (Berkeley) %G%
+.\" 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.

 .\"
 .\"

-.TH IEEE 3M  ""
-.UC 6
-.ds nn \fINaN\fR
-.SH NAME
-copysign, drem, finite, logb, scalb \- copysign, remainder,
-exponent manipulations
-.SH SYNOPSIS
-.nf
-.B #include <math.h>
-.PP
-.B double copysign(x,y)
-.B double x,y;
-.PP
-.B double drem(x,y)
-.B double x,y;
-.PP
-.B int finite(x)
-.B double x;
-.PP
-.B double logb(x)
-.B double x;
-.PP
-.B double scalb(x,n)
-.B double x;
-.B int n;
-.fi
-.SH DESCRIPTION
-These functions are required for, or recommended by the IEEE standard
+.\" 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.
+.\"
+.\"     @(#)ieee.3     6.4 (Berkeley) 5/6/91
+.\"
+.Dd May 6, 1991
+.Dt IEEE 3
+.Os BSD 4.3
+.Sh NAME
+.Nm copysign ,
+.Nm drem ,
+.Nm finite ,
+.Nm logb ,
+.Nm scalb
+.Nm copysign ,
+.Nm remainder,
+.Nd exponent manipulations
+.Sh SYNOPSIS
+.Fd #include <math.h>
+.Ft double 
+.Fn copysign "double x" "double y"
+.Ft double 
+.Fn drem "double x" "double y"
+.Ft int 
+.Fn finite "double x"
+.Ft double 
+.Fn logb "double x"
+.Ft double 
+.Fn scalb "double x" "int n"
+.Sh DESCRIPTION
+These functions are required for, or recommended by the
+.Tn IEEE
+standard

 754 for floating\-point arithmetic.
 754 for floating\-point arithmetic.

-.PP
-Copysign(x,y)
-returns x with its sign changed to y's.
-.PP
-Drem(x,y) returns the remainder r := x \- n\(**y
-where n is the integer nearest the exact value of x/y;
-moreover if |n\|\-\|x/y|\|=\|1/2 then n is even.  Consequently
-the remainder is computed exactly and |r| \(<= |y|/2.  But
-drem(x,0) is exceptional; see below under DIAGNOSTICS.
-.PP
-.nf
-.ta \w'Finite(x)'u+1n +\w'= 0 otherwise'u+1n
-.if n \
-Finite(x)      = 1 just when \-infinity < x < +infinity,
-.if t \
-Finite(x)      = 1 just when \-\(if < x < +\(if,
-.if n \
-       = 0 otherwise   (when |x| = infinity or x is \*(nn or
-.if t \
-       = 0 otherwise   (when |x| = \(if or x is \*(nn or
-               \0x is the VAX's reserved operand.)
-.ta
-.fi
-.PP
-Logb(x) returns x's exponent n,
+.Pp
+The
+.Fn copysign
+function
+returns
+.Fa x
+with its sign changed to
+.Fa y Ns 's.
+.Pp
+The
+.Fn drem
+function
+returns 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
+But
+.Fn drem x 0
+is exceptional.
+(See below under
+.Sx DIAGNOSTICS . )
+.Pp
+The
+.Fn finite
+function returns 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 or
+is the
+.Tn VAX Ns 's
+reserved operand).
+.Pp
+The
+.Fn logb
+function returns
+.Fa x Ns 's exponent
+.Fa n ,

 a signed integer converted to double\-precision floating\-point and so
 a signed integer converted to double\-precision floating\-point and so

-chosen that 1\0\(<=\0|x|/2**n\0<\02 unless x = 0 or
-(only on machines that conform to IEEE 754)
+chosen that
+1 (<=
+.Pf \\*(Ba Ns Fa x Ns \\*(Ba2** Ns Fa n
+< 2
+unless
+.Fa x
+= 0 or
+(only on machines that conform to
+.Tn IEEE
+754)
+.Pf \\*(Ba Fa x Ns \\*(Ba
+= \*(If
+or
+.Fa x
+lies between 0 and the Underflow Threshold.
+(See below under
+.Sx BUGS . )
+.Pp
+The
+Fn calb
+returns
+.Fa x Ns \(**(2** Ns Fa n )
+computed, for integer n, without first computing
+.Pf 2\(** Fa n .
+.Sh RETURN VALUES
+The
+.Tn IEEE
+standard
+754 defines
+.Fn drem x 0
+and
+.Fn drem \\*(If y
+to be invalid operations that produce a \*(Na.
+On the
+.Tn VAX , 
+.Fn drem x 0
+generates a reserved operand fault.  No \*(If
+exists on a
+.Tn VAX . 
+.Pp
+.Tn IEEE
+754 defines

 .if n \
 .if n \

-|x| = infinity
-.if t \
-|x| = \(if
-or x lies between 0 and the Underflow Threshold; see below under "BUGS".
-.PP
-Scalb(x,n) = x\(**(2**n) computed, for integer n, without first computing
-2**n.
-.SH DIAGNOSTICS
-IEEE 754 defines drem(x,0) and
-.if n \
-drem(infinity,y)
-.if t \
-drem(\(if,y)
-to be invalid operations that produce a \*(nn.
-On a VAX, drem(x,0) returns the reserved operand.  No
-.if n \
-infinity
-.if t \
-\(if
-exists on a VAX.
-.PP
-IEEE 754 defines
-.if n \
-logb(\(+-infinity) = +infinity and logb(0) = \-infinity,
-.if t \
-logb(\(+-\(if) = +\(if and logb(0) = \-\(if, and
+.Fn logb \(+-\\*(If
+= \*(If and
+.Fn logb 0
+= \-\*(If, and

 requires the latter to signal Division\-by\-Zero.
 requires the latter to signal Division\-by\-Zero.

-But on a VAX, logb(0) = 1.0 \- 2.0**31 = \-2,147,483,647.0.
-And if the correct value of scalb(x,n) would overflow on a VAX,
-it returns the reserved operand and sets \fIerrno\fR to ERANGE.
-.SH SEE ALSO
-floor(3M), math(3M), infnan(3M)
-.SH AUTHOR
-Kwok\-Choi Ng
-.SH BUGS
-Should drem(x,0) and logb(0) on a VAX signal invalidity 
-by setting \fIerrno\fR = EDOM?  Should  logb(0) return  \-1.7e38?
-.PP
-IEEE 754 currently specifies that
-logb(denormalized no.) = logb(tiniest normalized no. > 0)
+But on a
+.Tn VAX , 
+.Fn logb 0
+= 1.0 \- 2.0**31 = \-2,147,483,647.0.
+And if the correct value of
+.Fn scalb
+would overflow on a
+.Tn VAX , 
+it generates a reserved operand fault and sets the global variable
+.Va errno
+to
+.Dv ERANGE . 
+.Sh SEE ALSO
+.Xr floor 3 ,
+.Xr math 3 ,
+.Xr infnan 3
+.Sh HISTORY
+The
+.Nm ieee
+functions appeared in 
+.Bx 4.3 .
+.Sh BUGS
+Should
+.Fn drem x 0
+and
+.Fn logb 0
+on a
+.Tn VAX
+signal invalidity 
+by setting
+.Va errno No = Dv EDOM ?
+Should
+.Fn logb 0
+return  \-1.7e38?
+.Pp
+.Tn IEEE
+754 currently specifies that
+.Fn logb "denormalized no."
+=
+.Fn logb "tiniest normalized no. > 0"

 but the consensus has changed to the specification in the new 
 but the consensus has changed to the specification in the new 

-proposed IEEE standard p854, namely that logb(x) satisfy 
-.RS
-1 \(<= scalb(|x|,\-logb(x)) < Radix\0\0\0... = 2 for IEEE 754
-.RE
+proposed
+.Tn IEEE
+standard p854, namely that
+.Fn logb x
+satisfy 
+.Bd -filled -offset indent
+1 \(<=
+.Fn scalb \\*(Bax\\*(Ba \-logb(x)
+<
+Radix\0 ... = 2
+for
+.Tn IEEE
+754
+.Ed
+.Pp

 for every x except 0, 
 for every x except 0, 

-.if n \
-infinity
-.if t \
-\(if
-and \*(nn.
+\*(If
+and \*(Na.

 Almost every program that assumes 754's specification will work
 Almost every program that assumes 754's specification will work

-correctly if logb follows 854's specification instead.
-.PP
-IEEE 754 requires copysign(x,\*(nn) = \(+-x  but says nothing
-else about the sign of a \*(nn.  A \*(nn (\fIN\fRot \fIa\fR \fIN\fRumber) is
-similar in spirit to the VAX's reserved operand, but very
+correctly if
+.Fn logb
+follows 854's specification instead.
+.Pp
+.Tn IEEE
+754 requires
+.Fn copysign x \\*(Na)
+=
+.Pf \(+- Ns Fa x
+but says nothing
+else about the sign of a \*(Na.  A \*(Na
+.Em N Ns ot
+.Em a
+.Em N Ns umber )
+is
+similar in spirit to the
+.Tn VAX Ns 's
+reserved operand, but very

 different in important details.  Since the sign bit of a
 reserved operand makes it look negative,  
 different in important details.  Since the sign bit of a
 reserved operand makes it look negative,  

-.RS
-copysign(x,reserved operand) = \-x;
-.RE
+.Bd -filled -offset indent
+.Fn copysign x "reserved operand"
+=
+.Pf \- Fa x ;
+.Ed
+.Pp

 should this return the reserved operand instead?
 should this return the reserved operand instead?