diff options
Diffstat (limited to 'lib/msun/man/math.3')
| -rw-r--r-- | lib/msun/man/math.3 | 635 |
1 files changed, 0 insertions, 635 deletions
diff --git a/lib/msun/man/math.3 b/lib/msun/man/math.3 deleted file mode 100644 index a692b5f..0000000 --- a/lib/msun/man/math.3 +++ /dev/null @@ -1,635 +0,0 @@ -.\" 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. -.\" -.\" from: @(#)math.3 6.10 (Berkeley) 5/6/91 -.\" $Id$ -.\" -.TH MATH 3M "May 6, 1991" -.UC 4 -.ds up \fIulp\fR -.ds nn \fINaN\fR -.de If -.if n \\ -\\$1Infinity\\$2 -.if t \\ -\\$1\\(if\\$2 -.. -.SH NAME -math \- introduction to mathematical library functions -.SH DESCRIPTION -These functions constitute the C math library, -.I libm. -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" -Each of the following double functions has a float counterpart with the -name ending in f, as an example the float counterpart of double acos(double -x) is float acosf(float x). -.sp 2 -.nf -.ta \w'copysign'u+2n +\w'infnan.3m'u+10n +\w'inverse trigonometric func'u -\fIName\fP \fIAppears on Page\fP \fIDescription\fP \fIError Bound (ULPs)\fP -.ta \w'copysign'u+4n +\w'infnan.3m'u+4n +\w'inverse trigonometric function'u+6nC -.sp 5p -acos sin.3m inverse trigonometric function 3 -acosh asinh.3m inverse hyperbolic function 3 -asin sin.3m inverse trigonometric function 3 -asinh asinh.3m inverse hyperbolic function 3 -atan sin.3m inverse trigonometric function 1 -atanh asinh.3m inverse hyperbolic function 3 -atan2 sin.3m inverse trigonometric function 2 -cabs hypot.3m complex absolute value 1 -cbrt sqrt.3m cube root 1 -ceil floor.3m integer no less than 0 -copysign ieee.3m copy sign bit 0 -cos sin.3m trigonometric function 1 -cosh sinh.3m hyperbolic function 3 -erf erf.3m error function ??? -erfc erf.3m complementary error function ??? -exp exp.3m exponential 1 -expm1 exp.3m exp(x)\-1 1 -fabs floor.3m absolute value 0 -floor floor.3m integer no greater than 0 -hypot hypot.3m Euclidean distance 1 -ilogb ieee.3m exponent extraction 0 -j0 j0.3m bessel function ??? -j1 j0.3m bessel function ??? -jn j0.3m bessel function ??? -lgamma lgamma.3m log gamma function; (formerly gamma.3m) -log exp.3m natural logarithm 1 -log10 exp.3m logarithm to base 10 3 -log1p exp.3m log(1+x) 1 -pow exp.3m exponential x**y 60\-500 -remainder ieee.3m remainder 0 -rint floor.3m round to nearest integer 0 -scalbn ieee.3m exponent adjustment 0 -sin sin.3m trigonometric function 1 -sinh sinh.3m hyperbolic function 3 -sqrt sqrt.3m square root 1 -tan sin.3m trigonometric function 3 -tanh sinh.3m hyperbolic function 3 -y0 j0.3m bessel function ??? -y1 j0.3m bessel function ??? -yn j0.3m bessel function ??? -.ta -.fi -.SH NOTES -In 4.3 BSD, distributed from the University of California -in late 1985, most of the foregoing functions come in two -versions, one for the double\-precision "D" format in the -DEC VAX\-11 family of computers, another for double\-precision -arithmetic conforming to the IEEE Standard 754 for Binary -Floating\-Point Arithmetic. The two versions behave very -similarly, as should be expected from programs more accurate -and robust than was the norm when UNIX was born. For -instance, the programs are accurat ere accurn the numbers -of \*(ups tabulated above; an \*(up is one \fIU\fRnit in the \fIL\fRast -\fIP\fRlace. And the progrod the prbeen cured of anomalies that -afflicted the older mat` older math library \fIlibm\fR in which incidents like -the followineported: -.RS -sqrt(\-1.0) = 0.0 and log(\-1.0) = \-1.7e38. -.br -cos(1.0e\-11) > cos(0.0) > 1.0. -.br -pow(x,1.0) -.if n \ -!= -.if t \ -\(!= -x when x = 2.0, 3.0, 4.0, ..., 9.0. -.br -pow(\-1.0,1.0e10) trapped on Integer Overflow. -.br -sqrt(1.0e30) and sqrt(1.0e\-30) were very slow. -.RE -However the two versions do differ in ways that have to be -explained, to which end the following notes are provided. -.PP -\fBDEC VAX\-11 D_floating\-point:\fR -.PP -This is the format for which the original math library \fIlibm\fR -was developed, and to which this manual is still principally -dedicated. It is \fIthe\fR double\-precision format for the PDP\-11 -and the earlier VAX\-11 machines; VAX\-11s after 1983 were -provided with an optional "G" format closer to the IEEE -double\-precision format. The earlier DEC MicroVAXs have no -D format, only G double\-precision. (Why? Why not?) -.PP -Properties of D_floating\-point: -.RS -Wordsize: 64 bits, 8 bytes. Radix: Binary. -.br -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 -.br -1.3e\-17 < 0.5**56 < (x'\-x)/x \(<= 0.5**55 < 2.8e\-17. -.RE -.nf -.ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**127'u+1n -Range: Overflow threshold = 2.0**127 = 1.7e38. - Underflow threshold = 0.5**128 = 2.9e\-39. - NOTE: THIS RANGE IS COMPARATIVELY NARROW. -.ta -.fi -.RS -Overflow customarily stops computation. -.br -Underflow is customarily flushed quietly to zero. -.br -CAUTION: -.RS -It is possible to have x -.if n \ -!= -.if t \ -\(!= -y and yet -x\-y = 0 because of underflow. Similarly -x > y > 0 cannot prevent either x\(**y = 0 -or y/x = 0 from happening without warning. -.RE -.RE -Zero is represented ambiguously. -.RS -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. -.RE -.If -is not part of the VAX architecture. -.br -Reserved operands: -.RS -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. -.RE -Exceptions: -.RS -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. -.RE -Rounding: -.RS -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 an \*(up, and when the rounding error is -exactly half an \*(up then rounding is away from 0. -.RE -.RE -.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 4.3 BSD. -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. -.RS -.ll -0.5i -\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 infnan(3M) for the present state of affairs.\fR -.ll +0.5i -.RE -.PP -How do the functions in 4.3 BSD's new \fIlibm\fR for UNIX -compare with their counterparts in DEC's VAX/VMS library? -Some of the 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 -\fIlibm\fR. -The VMS codes interpolate in large table to achieve -speed and accuracy; the \fIlibm\fR codes use tricky formulas -compact enough that all of them may some day fit into a ROM. -.PP -More important, DEC regards the VMS codes as proprietary -and guards them zealously against unauthorized use. But the -\fIlibm\fR codes in 4.3 BSD 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 -researches by reporting experience with the codes. -Therefore no user of UNIX on a machine whose arithmetic resembles -VAX D_floating\-point need use anything worse than the new \fIlibm\fR. -.PP -\fBIEEE STANDARD 754 Floating\-Point Arithmetic:\fR -.PP -This standard is on its way to becoming more widely adopted -than any other design for computer arithmetic. -VLSI chips that conform to some version of that standard have been -produced by a host of manufacturers, among them ... -.nf -.ta 0.5i +\w'Intel i8070, i80287'u+6n - Intel i8087, i80287 National Semiconductor 32081 - 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 -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. -The DEC VAX G_floating\-point format is very similar to the IEEE -754 Double format, so similar that the C programs for the -IEEE versions of most of the elementary functions listed -above could easily be converted to run on a MicroVAX, though -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 -and WTL 1164/65. To use these codes with the Intel or Zilog -chips, or with the Apple Macintosh or ELXSI 6400, is to -forego the use of better codes provided (perhaps freely) by -those companies and designed by some of the authors of the -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 -researches by reporting experience with the codes. -Therefore no user of UNIX on a machine that conforms to -IEEE 754 need use anything worse than the new \fIlibm\fR. -.PP -Properties of IEEE 754 Double\-Precision: -.RS -Wordsize: 64 bits, 8 bytes. Radix: Binary. -.br -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 -.br -1.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16. -.RE -.nf -.ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**1024'u+1n -Range: Overflow threshold = 2.0**1024 = 1.8e308 - Underflow threshold = 0.5**1022 = 2.2e\-308 -.ta -.fi -.RS -Overflow goes by default to a signed -.If "" . -.br -Underflow is \fIGradual,\fR rounding to the nearest -integer multiple of 0.5**1074 = 4.9e\-324. -.RE -Zero is represented ambiguously as +0 or \-0. -.RS -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,\(+-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) -.if n \ -!= -.if t \ -\(!= -\-1/(y\-x) = -.If \- . -.RE -.If -is signed. -.RS -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 = -.If \(+- . -But -.if n \ -Infinity\-Infinity, Infinity\(**0 and Infinity/Infinity -.if t \ -\(if\-\(if, \(if\(**0 and \(if/\(if -are, like 0/0 and sqrt(\-3), -invalid operations that produce \*(nn. ... -.RE -Reserved operands: -.RS -there are 2**53\-2 of them, all -called \*(nn (\fIN\fRot \fIa N\fRumber). -Some, called Signaling \*(nns, 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 \*(nns; they are -the default results of Invalid Operations, and -propagate through subsequent arithmetic operations. -If x -.if n \ -!= -.if t \ -\(!= -x then x is \*(nn; every other predicate -(x > y, x = y, x < y, ...) is FALSE if \*(nn is involved. -.br -NOTE: Trichotomy is violated by \*(nn. -.RS -Besides being FALSE, predicates that entail ordered -comparison, rather than mere (in)equality, -signal Invalid Operation when \*(nn is involved. -.RE -.RE -Rounding: -.RS -Every algebraic operation (+, \-, \(**, /, -.if n \ -sqrt) -.if t \ -\(sr) -is rounded by default to within half an \*(up, and -when the rounding error is exactly half an \*(up 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 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. And the -same kinds of rounding are specified for -Binary\-Decimal Conversions, at least for magnitudes -between roughly 1.0e\-10 and 1.0e37. -.RE -Exceptions: -.RS -IEEE 754 recognizes five kinds of floating\-point exceptions, -listed below in declining order of probable importance. -.RS -.nf -.ta \w'Invalid Operation'u+6n +\w'Gradual Underflow'u+2n -Exception Default Result -.tc \(ru - -.tc -Invalid Operation \*(nn, or FALSE -.if n \{\ -Overflow \(+-Infinity -Divide by Zero \(+-Infinity \} -.if t \{\ -Overflow \(+-\(if -Divide by Zero \(+-\(if \} -Underflow Gradual Underflow -Inexact Rounded value -.ta -.fi -.RE -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. -.RE -.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: -.IP 1) \w'\0\0\0\0'u -Test for a condition that might cause an exception -later, and branch to avoid the exception. -.IP 2) \w'\0\0\0\0'u -Test a flag to see whether an exception has occurred -since the program last reset its flag. -.IP 3) \w'\0\0\0\0'u -Test a result to see whether it is a value that only -an exception could have produced. -.RS -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 -.if n \ -!= -.if t \ -\(!= -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 \fIprovably\fR ignorable. -The same cannot be said of underflows flushed to 0. -.RE -.PP -At the option of an implementor conforming to IEEE 754, -other ways to cope with exceptions may be provided: -.IP 4) \w'\0\0\0\0'u -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: -.IP \(em \w'\0\0\0\0'u -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. -.IP \(em \w'\0\0\0\0'u -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. -.IP 5) \w'\0\0\0\0'u -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. -.IP 6) \w'\0\0\0\0'u -\&... Other ways lie beyond the scope of this document. -.RE -.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 4.3 BSD's \fIlibm\fR. Ideally, each -elementary function should act as if it were indivisible, or -atomic, in the sense that ... -.IP i) \w'iii)'u+2n -No exception should be signaled that is not deserved by -the data supplied to that function. -.IP ii) \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 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. -.PP -Ideally, every programmer should be able \fIconveniently\fR to -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 \fIlibm\fR are only approximately -atomic. They signal no inappropriate exception except -possibly ... -.RS -Over/Underflow -.RS -when a result, if properly computed, might have lain barely within range, and -.RE -Inexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR -.RS -when it happens to be exact, thanks to fortuitous cancellation of errors. -.RE -.RE -Otherwise, ... -.RS -Invalid Operation is signaled only when -.RS -any result but \*(nn would probably be misleading. -.RE -Overflow is signaled only when -.RS -the exact result would be finite but beyond the overflow threshold. -.RE -Divide\-by\-Zero is signaled only when -.RS -a function takes exactly infinite values at finite operands. -.RE -Underflow is signaled only when -.RS -the exact result would be nonzero but tinier than the underflow threshold. -.RE -Inexact is signaled only when -.RS -greater range or precision would be needed to represent the exact result. -.RE -.RE -.SH BUGS -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 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. -.SH SEE ALSO -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 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. |
