BSD 4_3_Net_2 release

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

diff --git a/usr/src/lib/libm/common_source/math.3 b/usr/src/lib/libm/common_source/math.3
index 29f7a3a..647bac7 100644 (file)
--- a/usr/src/lib/libm/common_source/math.3
+++ b/usr/src/lib/libm/common_source/math.3
@@ -1,4 +1,37 @@
-.TH INTRO 3M "19 August 1985"
+.\" 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. 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.
+.\"
+.\" 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.
+.\"
+.\"    @(#)math.3      6.10 (Berkeley) 5/6/91
+.\"
+.TH MATH 3M "May 6, 1991"

 .UC 4
 .ds up \fIulp\fR
 .ds nn \fINaN\fR
 .UC 4
 .ds up \fIulp\fR
 .ds nn \fINaN\fR


@@ -9,15 +42,14 @@
 \\$1\\(if\\$2
 ..
 .SH NAME
 \\$1\\(if\\$2
 ..
 .SH NAME

-intro \- introduction to mathematical library functions
+math \- introduction to mathematical library functions

 .SH DESCRIPTION
 .SH DESCRIPTION

-These functions constitute the math library,
+These functions constitute the C math library,

 .I libm.
 .I libm.

-They are automatically loaded as needed by the Fortran compiler
-.IR f77 (1).

 The link editor searches this library under the \*(lq\-lm\*(rq option.
 Declarations for these functions may be obtained from the include file
 .RI < math.h >.
 The link editor searches this library under the \*(lq\-lm\*(rq option.
 Declarations for these functions may be obtained from the include file
 .RI < math.h >.

+The Fortran math library is described in ``man 3f intro''.

 .SH "LIST OF FUNCTIONS"
 .sp 2
 .nf
 .SH "LIST OF FUNCTIONS"
 .sp 2
 .nf


@@ -50,12 +82,13 @@ infnan      infnan.3m       signals exceptions
 j0     j0.3m   bessel function ???
 j1     j0.3m   bessel function ???
 jn     j0.3m   bessel function ???
 j0     j0.3m   bessel function ???
 j1     j0.3m   bessel function ???
 jn     j0.3m   bessel function ???

-lgama  gamma.3m        log gamma function; NEW NAME!   ???
+lgamma lgamma.3m       log gamma function; (formerly gamma.3m)

 log    exp.3m  natural logarithm       1
 logb   ieee.3m exponent extraction     0
 log10  exp.3m  logarithm to base 10    3
 log1p  exp.3m  log(1+x)        1
 pow    exp.3m  exponential x**y        60\-500
 log    exp.3m  natural logarithm       1
 logb   ieee.3m exponent extraction     0
 log10  exp.3m  logarithm to base 10    3
 log1p  exp.3m  log(1+x)        1
 pow    exp.3m  exponential x**y        60\-500

+rint   floor.3m        round to nearest integer        0

 scalb  ieee.3m exponent adjustment     0
 sin    sin.3m  trigonometric function  1
 sinh   sinh.3m hyperbolic function     3
 scalb  ieee.3m exponent adjustment     0
 sin    sin.3m  trigonometric function  1
 sinh   sinh.3m hyperbolic function     3


@@ -114,7 +147,17 @@ Properties of D_floating\-point:
 .RS
 Wordsize: 64 bits, 8 bytes.  Radix: Binary.
 .br
 .RS
 Wordsize: 64 bits, 8 bytes.  Radix: Binary.
 .br

-Precision: 56 bits; equivalent to about 17 significant decimals.
+Precision: 56
+.if n \
+sig.
+.if t \
+significant
+bits, roughly like 17
+.if n \
+sig.
+.if t \
+significant
+decimals.

 .RS
 If x and x' are consecutive positive D_floating\-point
 numbers (they differ by 1 \*(up), then
 .RS
 If x and x' are consecutive positive D_floating\-point
 numbers (they differ by 1 \*(up), then


@@ -230,13 +273,13 @@ produced by a host of manufacturers, among them ...
 .nf
 .ta 0.5i +\w'Intel i8070, i80287'u+6n
        Intel i8087, i80287     National Semiconductor  32081
 .nf
 .ta 0.5i +\w'Intel i8070, i80287'u+6n
        Intel i8087, i80287     National Semiconductor  32081

-       Motorola 68881  Weitek WTL-1032, ... , -1065
-       Zilog Z8070     Western Electric (AT&T) 32106.
+       Motorola 68881  Weitek WTL-1032, ... , -1165
+       Zilog Z8070     Western Electric (AT&T) WE32106.

 .ta
 .fi
 Other implementations range from software, done thoroughly
 in the Apple Macintosh, through VLSI in the Hewlett\-Packard
 .ta
 .fi
 Other implementations range from software, done thoroughly
 in the Apple Macintosh, through VLSI in the Hewlett\-Packard

-9000 series, to the ELXSI 6400 running at 3 Megaflops.
+9000 series, to the ELXSI 6400 running ECL at 3 Megaflops.

 Several other companies have adopted the formats
 of IEEE 754 without, alas, adhering to the standard's way
 of handling rounding and exceptions like over/underflow.
 Several other companies have adopted the formats
 of IEEE 754 without, alas, adhering to the standard's way
 of handling rounding and exceptions like over/underflow.


@@ -248,13 +291,23 @@ nobody has volunteered to do that yet.
 .PP
 The codes in 4.3 BSD's \fIlibm\fR for machines that conform to
 IEEE 754 are intended primarily for the National Semi. 32081
 .PP
 The codes in 4.3 BSD's \fIlibm\fR for machines that conform to
 IEEE 754 are intended primarily for the National Semi. 32081

-and Weitek 1065.  To use these codes with the Intel or Zilog
+and WTL 1164/65.  To use these codes with the Intel or Zilog

 chips, or with the Apple Macintosh or ELXSI 6400, is to
 chips, or with the Apple Macintosh or ELXSI 6400, is to

-forego the use of better codes available (for a price) from
+forego the use of better codes provided (perhaps freely) by

 those companies and designed by some of the authors of the
 those companies and designed by some of the authors of the

-codes above.  The Motorola 68881 has all the \fIelementary\fR
-functions above except \fIpow\fR implemented on chip already,
-and faster and more accurate.  The main virtue of 4.3 BSD's
+codes above.
+Except for \fIatan\fR, \fIcabs\fR, \fIcbrt\fR, \fIerf\fR,
+\fIerfc\fR, \fIhypot\fR, \fIj0\-jn\fR, \fIlgamma\fR, \fIpow\fR
+and \fIy0\-yn\fR,
+the Motorola 68881 has all the functions in \fIlibm\fR on chip,
+and faster and more accurate;
+it, Apple, the i8087, Z8070 and WE32106 all use 64
+.if n \
+sig.
+.if t \
+significant
+bits.
+The main virtue of 4.3 BSD's

 \fIlibm\fR codes is that they are intended for the public domain;
 they may be copied freely provided their provenance is always
 acknowledged, and provided users assist the authors in their
 \fIlibm\fR codes is that they are intended for the public domain;
 they may be copied freely provided their provenance is always
 acknowledged, and provided users assist the authors in their


@@ -266,7 +319,17 @@ Properties of IEEE 754 Double\-Precision:
 .RS
 Wordsize: 64 bits, 8 bytes.  Radix: Binary.
 .br
 .RS
 Wordsize: 64 bits, 8 bytes.  Radix: Binary.
 .br

-Precision: 53 bits; equivalent to about 16 significant decimals.
+Precision: 53
+.if n \
+sig.
+.if t \
+significant
+bits, roughly like 16
+.if n \
+sig.
+.if t \
+significant
+decimals.

 .RS
 If x and x' are consecutive positive Double\-Precision
 numbers (they differ by 1 \*(up), then
 .RS
 If x and x' are consecutive positive Double\-Precision
 numbers (they differ by 1 \*(up), then


@@ -308,8 +371,8 @@ finite x = y then
 .If
 is signed.
 .RS
 .If
 is signed.
 .RS

-it persists after addition of itself
-or of any finite number.  Its sign transforms
+it persists when added to itself
+or to any finite number.  Its sign transforms

 correctly through multiplication and division, and
 .If (finite)/\(+- \0=\0\(+-0
 (nonzero)/0 =
 correctly through multiplication and division, and
 .If (finite)/\(+- \0=\0\(+-0
 (nonzero)/0 =


@@ -498,9 +561,9 @@ the data supplied to that function.
 Any exception signaled should be identified with that
 function rather than with one of its subroutines.
 .IP iii) \w'iii)'u+2n
 Any exception signaled should be identified with that
 function rather than with one of its subroutines.
 .IP iii) \w'iii)'u+2n

-The internal behavior of an atomic function cannot be
-disrupted when a calling program changes from one
-to another of the five or so ways of handling
+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.
 exceptions listed above, although the definition
 of the function may be correlated intentionally
 with exception handling.


@@ -520,9 +583,9 @@ Over/Underflow
 .RS
 when a result, if properly computed, might have lain barely within range, and
 .RE
 .RS
 when a result, if properly computed, might have lain barely within range, and
 .RE

-Inexact in pow(x,y)
+Inexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR

 .RS
 .RS

-when it happens to be exact thanks to fortuitous cancellation of errors.
+when it happens to be exact, thanks to fortuitous cancellation of errors.

 .RE
 .RE
 Otherwise, ...
 .RE
 .RE
 Otherwise, ...


@@ -552,7 +615,7 @@ greater range or precision would be needed to represent the exact result.
 When signals are appropriate, they are emitted by certain
 operations within the codes, so a subroutine\-trace may be
 needed to identify the function with its signal in case
 When signals are appropriate, they are emitted by certain
 operations within the codes, so a subroutine\-trace may be
 needed to identify the function with its signal in case

-method 6) above is in use.  And the codes all take the
+method 5) above is in use.  And the codes all take the

 IEEE 754 defaults for granted; this means that a decision to
 trap all divisions by zero could disrupt a code that would
 otherwise get correct results despite division by zero.
 IEEE 754 defaults for granted; this means that a decision to
 trap all divisions by zero could disrupt a code that would
 otherwise get correct results despite division by zero.


@@ -567,6 +630,3 @@ 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.
 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 AUTHOR
-W. Kahan, with the help of Alex Z\-S. Liu, Stuart I. McDonald,
-Dr. Kwok\-Choi Ng, Peter Tang.