rsalz@uunet.uu.net (Rich Salz) (10/27/88)
Submitted-by: Thos Sumner <root@ccb.ucsf.edu> Posting-number: Volume 16, Issue 47 Archive-name: 4.3mathlib/part05 #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh <file", e.g.. If this archive is complete, you # will see the following message at the end: # "End of archive 5 (of 5)." # Contents: libm_math.3m PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'libm_math.3m' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'libm_math.3m'\" else echo shar: Extracting \"'libm_math.3m'\" \(20506 characters\) sed "s/^X//" >'libm_math.3m' <<'END_OF_FILE' X.\" Copyright (c) 1985 Regents of the University of California. X.\" All rights reserved. The Berkeley software License Agreement X.\" specifies the terms and conditions for redistribution. X.\" X.\" @(#)math.3m 6.8 (Berkeley) 5/27/86 X.\" X.TH MATH 3M "May 27, 1986" X.UC 4 X.ds up \fIulp\fR X.ds nn \fINaN\fR X.de If X.if n \\ X\\$1Infinity\\$2 X.if t \\ X\\$1\\(if\\$2 X.. X.SH NAME Xmath \- introduction to mathematical library functions X.SH DESCRIPTION XThese functions constitute the C math library, X.I libm. XThe link editor searches this library under the \*(lq\-lm\*(rq option. XDeclarations for these functions may be obtained from the include file X.RI < math.h >. XThe Fortran math library is described in ``man 3f intro''. X.SH "LIST OF FUNCTIONS" X.sp 2 X.nf X.ta \w'copysign'u+2n +\w'infnan.3m'u+10n +\w'inverse trigonometric func'u X\fIName\fP \fIAppears on Page\fP \fIDescription\fP \fIError Bound (ULPs)\fP X.ta \w'copysign'u+4n +\w'infnan.3m'u+4n +\w'inverse trigonometric function'u+6nC X.sp 5p Xacos sin.3m inverse trigonometric function 3 Xacosh asinh.3m inverse hyperbolic function 3 Xasin sin.3m inverse trigonometric function 3 Xasinh asinh.3m inverse hyperbolic function 3 Xatan sin.3m inverse trigonometric function 1 Xatanh asinh.3m inverse hyperbolic function 3 Xatan2 sin.3m inverse trigonometric function 2 Xcabs hypot.3m complex absolute value 1 Xcbrt sqrt.3m cube root 1 Xceil floor.3m integer no less than 0 Xcopysign ieee.3m copy sign bit 0 Xcos sin.3m trigonometric function 1 Xcosh sinh.3m hyperbolic function 3 Xdrem ieee.3m remainder 0 Xerf erf.3m error function ??? Xerfc erf.3m complementary error function ??? Xexp exp.3m exponential 1 Xexpm1 exp.3m exp(x)\-1 1 Xfabs floor.3m absolute value 0 Xfloor floor.3m integer no greater than 0 Xhypot hypot.3m Euclidean distance 1 Xinfnan infnan.3m signals exceptions Xj0 j0.3m bessel function ??? Xj1 j0.3m bessel function ??? Xjn j0.3m bessel function ??? Xlgamma lgamma.3m log gamma function; (formerly gamma.3m) Xlog exp.3m natural logarithm 1 Xlogb ieee.3m exponent extraction 0 Xlog10 exp.3m logarithm to base 10 3 Xlog1p exp.3m log(1+x) 1 Xpow exp.3m exponential x**y 60\-500 Xrint floor.3m round to nearest integer 0 Xscalb ieee.3m exponent adjustment 0 Xsin sin.3m trigonometric function 1 Xsinh sinh.3m hyperbolic function 3 Xsqrt sqrt.3m square root 1 Xtan sin.3m trigonometric function 3 Xtanh sinh.3m hyperbolic function 3 Xy0 j0.3m bessel function ??? Xy1 j0.3m bessel function ??? Xyn j0.3m bessel function ??? X.ta X.fi X.SH NOTES XIn 4.3 BSD, distributed from the University of California Xin late 1985, most of the foregoing functions come in two Xversions, one for the double\-precision "D" format in the XDEC VAX\-11 family of computers, another for double\-precision Xarithmetic conforming to the IEEE Standard 754 for Binary XFloating\-Point Arithmetic. The two versions behave very Xsimilarly, as should be expected from programs more accurate Xand robust than was the norm when UNIX was born. For Xinstance, the programs are accurate to within the numbers Xof \*(ups tabulated above; an \*(up is one \fIU\fRnit in the \fIL\fRast X\fIP\fRlace. And the programs have been cured of anomalies that Xafflicted the older math library \fIlibm\fR in which incidents like Xthe following had been reported: X.RS Xsqrt(\-1.0) = 0.0 and log(\-1.0) = \-1.7e38. X.br Xcos(1.0e\-11) > cos(0.0) > 1.0. X.br Xpow(x,1.0) X.if n \ X!= X.if t \ X\(!= Xx when x = 2.0, 3.0, 4.0, ..., 9.0. X.br Xpow(\-1.0,1.0e10) trapped on Integer Overflow. X.br Xsqrt(1.0e30) and sqrt(1.0e\-30) were very slow. X.RE XHowever the two versions do differ in ways that have to be Xexplained, to which end the following notes are provided. X.PP X\fBDEC VAX\-11 D_floating\-point:\fR X.PP XThis is the format for which the original math library \fIlibm\fR Xwas developed, and to which this manual is still principally Xdedicated. It is \fIthe\fR double\-precision format for the PDP\-11 Xand the earlier VAX\-11 machines; VAX\-11s after 1983 were Xprovided with an optional "G" format closer to the IEEE Xdouble\-precision format. The earlier DEC MicroVAXs have no XD format, only G double\-precision. (Why? Why not?) X.PP XProperties of D_floating\-point: X.RS XWordsize: 64 bits, 8 bytes. Radix: Binary. X.br XPrecision: 56 X.if n \ Xsig. X.if t \ Xsignificant Xbits, roughly like 17 X.if n \ Xsig. X.if t \ Xsignificant Xdecimals. X.RS XIf x and x' are consecutive positive D_floating\-point Xnumbers (they differ by 1 \*(up), then X.br X1.3e\-17 < 0.5**56 < (x'\-x)/x \(<= 0.5**55 < 2.8e\-17. X.RE X.nf X.ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**127'u+1n XRange: Overflow threshold = 2.0**127 = 1.7e38. X Underflow threshold = 0.5**128 = 2.9e\-39. X NOTE: THIS RANGE IS COMPARATIVELY NARROW. X.ta X.fi X.RS XOverflow customarily stops computation. X.br XUnderflow is customarily flushed quietly to zero. X.br XCAUTION: X.RS XIt is possible to have x X.if n \ X!= X.if t \ X\(!= Xy and yet Xx\-y = 0 because of underflow. Similarly Xx > y > 0 cannot prevent either x\(**y = 0 Xor y/x = 0 from happening without warning. X.RE X.RE XZero is represented ambiguously. X.RS XAlthough 2**55 different representations of zero are accepted by Xthe hardware, only the obvious representation is ever produced. XThere is no \-0 on a VAX. X.RE X.If Xis not part of the VAX architecture. X.br XReserved operands: X.RS Xof the 2**55 that the hardware Xrecognizes, only one of them is ever produced. XAny floating\-point operation upon a reserved Xoperand, even a MOVF or MOVD, customarily stops Xcomputation, so they are not much used. X.RE XExceptions: X.RS XDivisions by zero and operations that Xoverflow are invalid operations that customarily Xstop computation or, in earlier machines, produce Xreserved operands that will stop computation. X.RE XRounding: X.RS XEvery rational operation (+, \-, \(**, /) on a XVAX (but not necessarily on a PDP\-11), if not an Xover/underflow nor division by zero, is rounded to Xwithin half an \*(up, and when the rounding error is Xexactly half an \*(up then rounding is away from 0. X.RE X.RE X.PP XExcept for its narrow range, D_floating\-point is one of the Xbetter computer arithmetics designed in the 1960's. XIts properties are reflected fairly faithfully in the elementary Xfunctions for a VAX distributed in 4.3 BSD. XThey over/underflow only if their results have to lie out of range Xor very nearly so, and then they behave much as any rational Xarithmetic operation that over/underflowed would behave. XSimilarly, expressions like log(0) and atanh(1) behave Xlike 1/0; and sqrt(\-3) and acos(3) behave like 0/0; Xthey all produce reserved operands and/or stop computation! XThe situation is described in more detail in manual pages. X.RS X.ll -0.5i X\fIThis response seems excessively punitive, so it is destined Xto be replaced at some time in the foreseeable future by a Xmore flexible but still uniform scheme being developed to Xhandle all floating\-point arithmetic exceptions neatly. XSee infnan(3M) for the present state of affairs.\fR X.ll +0.5i X.RE X.PP XHow do the functions in 4.3 BSD's new \fIlibm\fR for UNIX Xcompare with their counterparts in DEC's VAX/VMS library? XSome of the VMS functions are a little faster, some are Xa little more accurate, some are more puritanical about Xexceptions (like pow(0.0,0.0) and atan2(0.0,0.0)), Xand most occupy much more memory than their counterparts in X\fIlibm\fR. XThe VMS codes interpolate in large table to achieve Xspeed and accuracy; the \fIlibm\fR codes use tricky formulas Xcompact enough that all of them may some day fit into a ROM. X.PP XMore important, DEC regards the VMS codes as proprietary Xand guards them zealously against unauthorized use. But the X\fIlibm\fR codes in 4.3 BSD are intended for the public domain; Xthey may be copied freely provided their provenance is always Xacknowledged, and provided users assist the authors in their Xresearches by reporting experience with the codes. XTherefore no user of UNIX on a machine whose arithmetic resembles XVAX D_floating\-point need use anything worse than the new \fIlibm\fR. X.PP X\fBIEEE STANDARD 754 Floating\-Point Arithmetic:\fR X.PP XThis standard is on its way to becoming more widely adopted Xthan any other design for computer arithmetic. XVLSI chips that conform to some version of that standard have been Xproduced by a host of manufacturers, among them ... X.nf X.ta 0.5i +\w'Intel i8070, i80287'u+6n X Intel i8087, i80287 National Semiconductor 32081 X Motorola 68881 Weitek WTL-1032, ... , -1165 X Zilog Z8070 Western Electric (AT&T) WE32106. X.ta X.fi XOther implementations range from software, done thoroughly Xin the Apple Macintosh, through VLSI in the Hewlett\-Packard X9000 series, to the ELXSI 6400 running ECL at 3 Megaflops. XSeveral other companies have adopted the formats Xof IEEE 754 without, alas, adhering to the standard's way Xof handling rounding and exceptions like over/underflow. XThe DEC VAX G_floating\-point format is very similar to the IEEE X754 Double format, so similar that the C programs for the XIEEE versions of most of the elementary functions listed Xabove could easily be converted to run on a MicroVAX, though Xnobody has volunteered to do that yet. X.PP XThe codes in 4.3 BSD's \fIlibm\fR for machines that conform to XIEEE 754 are intended primarily for the National Semi. 32081 Xand WTL 1164/65. To use these codes with the Intel or Zilog Xchips, or with the Apple Macintosh or ELXSI 6400, is to Xforego the use of better codes provided (perhaps freely) by Xthose companies and designed by some of the authors of the Xcodes above. XExcept for \fIatan\fR, \fIcabs\fR, \fIcbrt\fR, \fIerf\fR, X\fIerfc\fR, \fIhypot\fR, \fIj0\-jn\fR, \fIlgamma\fR, \fIpow\fR Xand \fIy0\-yn\fR, Xthe Motorola 68881 has all the functions in \fIlibm\fR on chip, Xand faster and more accurate; Xit, Apple, the i8087, Z8070 and WE32106 all use 64 X.if n \ Xsig. X.if t \ Xsignificant Xbits. XThe main virtue of 4.3 BSD's X\fIlibm\fR codes is that they are intended for the public domain; Xthey may be copied freely provided their provenance is always Xacknowledged, and provided users assist the authors in their Xresearches by reporting experience with the codes. XTherefore no user of UNIX on a machine that conforms to XIEEE 754 need use anything worse than the new \fIlibm\fR. X.PP XProperties of IEEE 754 Double\-Precision: X.RS XWordsize: 64 bits, 8 bytes. Radix: Binary. X.br XPrecision: 53 X.if n \ Xsig. X.if t \ Xsignificant Xbits, roughly like 16 X.if n \ Xsig. X.if t \ Xsignificant Xdecimals. X.RS XIf x and x' are consecutive positive Double\-Precision Xnumbers (they differ by 1 \*(up), then X.br X1.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16. X.RE X.nf X.ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**1024'u+1n XRange: Overflow threshold = 2.0**1024 = 1.8e308 X Underflow threshold = 0.5**1022 = 2.2e\-308 X.ta X.fi X.RS XOverflow goes by default to a signed X.If "" . X.br XUnderflow is \fIGradual,\fR rounding to the nearest Xinteger multiple of 0.5**1074 = 4.9e\-324. X.RE XZero is represented ambiguously as +0 or \-0. X.RS XIts sign transforms correctly through multiplication or Xdivision, and is preserved by addition of zeros Xwith like signs; but x\-x yields +0 for every Xfinite x. The only operations that reveal zero's Xsign are division by zero and copysign(x,\(+-0). XIn particular, comparison (x > y, x \(>= y, etc.) Xcannot be affected by the sign of zero; but if Xfinite x = y then X.If X\&= 1/(x\-y) X.if n \ X!= X.if t \ X\(!= X\-1/(y\-x) = X.If \- . X.RE X.If Xis signed. X.RS Xit persists when added to itself Xor to any finite number. Its sign transforms Xcorrectly through multiplication and division, and X.If (finite)/\(+- \0=\0\(+-0 X(nonzero)/0 = X.If \(+- . XBut X.if n \ XInfinity\-Infinity, Infinity\(**0 and Infinity/Infinity X.if t \ X\(if\-\(if, \(if\(**0 and \(if/\(if Xare, like 0/0 and sqrt(\-3), Xinvalid operations that produce \*(nn. ... X.RE XReserved operands: X.RS Xthere are 2**53\-2 of them, all Xcalled \*(nn (\fIN\fRot \fIa N\fRumber). XSome, called Signaling \*(nns, trap any floating\-point operation Xperformed upon them; they are used to mark missing Xor uninitialized values, or nonexistent elements Xof arrays. The rest are Quiet \*(nns; they are Xthe default results of Invalid Operations, and Xpropagate through subsequent arithmetic operations. XIf x X.if n \ X!= X.if t \ X\(!= Xx then x is \*(nn; every other predicate X(x > y, x = y, x < y, ...) is FALSE if \*(nn is involved. X.br XNOTE: Trichotomy is violated by \*(nn. X.RS XBesides being FALSE, predicates that entail ordered Xcomparison, rather than mere (in)equality, Xsignal Invalid Operation when \*(nn is involved. X.RE X.RE XRounding: X.RS XEvery algebraic operation (+, \-, \(**, /, X.if n \ Xsqrt) X.if t \ X\(sr) Xis rounded by default to within half an \*(up, and Xwhen the rounding error is exactly half an \*(up then Xthe rounded value's least significant bit is zero. XThis kind of rounding is usually the best kind, Xsometimes provably so; for instance, for every Xx = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find X(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ... Xdespite that both the quotients and the products Xhave been rounded. Only rounding like IEEE 754 Xcan do that. But no single kind of rounding can be Xproved best for every circumstance, so IEEE 754 Xprovides rounding towards zero or towards X.If + Xor towards X.If \- Xat the programmer's option. And the Xsame kinds of rounding are specified for XBinary\-Decimal Conversions, at least for magnitudes Xbetween roughly 1.0e\-10 and 1.0e37. X.RE XExceptions: X.RS XIEEE 754 recognizes five kinds of floating\-point exceptions, Xlisted below in declining order of probable importance. X.RS X.nf X.ta \w'Invalid Operation'u+6n +\w'Gradual Underflow'u+2n XException Default Result X.tc \(ru X X.tc XInvalid Operation \*(nn, or FALSE X.if n \{\ XOverflow \(+-Infinity XDivide by Zero \(+-Infinity \} X.if t \{\ XOverflow \(+-\(if XDivide by Zero \(+-\(if \} XUnderflow Gradual Underflow XInexact Rounded value X.ta X.fi X.RE XNOTE: An Exception is not an Error unless handled Xbadly. What makes a class of exceptions exceptional Xis that no single default response can be satisfactory Xin every instance. On the other hand, if a default Xresponse will serve most instances satisfactorily, Xthe unsatisfactory instances cannot justify aborting Xcomputation every time the exception occurs. X.RE X.PP XFor each kind of floating\-point exception, IEEE 754 Xprovides a Flag that is raised each time its exception Xis signaled, and stays raised until the program resets Xit. Programs may also test, save and restore a flag. XThus, IEEE 754 provides three ways by which programs Xmay cope with exceptions for which the default result Xmight be unsatisfactory: X.IP 1) \w'\0\0\0\0'u XTest for a condition that might cause an exception Xlater, and branch to avoid the exception. X.IP 2) \w'\0\0\0\0'u XTest a flag to see whether an exception has occurred Xsince the program last reset its flag. X.IP 3) \w'\0\0\0\0'u XTest a result to see whether it is a value that only Xan exception could have produced. X.RS XCAUTION: The only reliable ways to discover Xwhether Underflow has occurred are to test whether Xproducts or quotients lie closer to zero than the Xunderflow threshold, or to test the Underflow Xflag. (Sums and differences cannot underflow in XIEEE 754; if x X.if n \ X!= X.if t \ X\(!= Xy then x\-y is correct to Xfull precision and certainly nonzero regardless of Xhow tiny it may be.) Products and quotients that Xunderflow gradually can lose accuracy gradually Xwithout vanishing, so comparing them with zero X(as one might on a VAX) will not reveal the loss. XFortunately, if a gradually underflowed value is Xdestined to be added to something bigger than the Xunderflow threshold, as is almost always the case, Xdigits lost to gradual underflow will not be missed Xbecause they would have been rounded off anyway. XSo gradual underflows are usually \fIprovably\fR ignorable. XThe same cannot be said of underflows flushed to 0. X.RE X.PP XAt the option of an implementor conforming to IEEE 754, Xother ways to cope with exceptions may be provided: X.IP 4) \w'\0\0\0\0'u XABORT. This mechanism classifies an exception in Xadvance as an incident to be handled by means Xtraditionally associated with error\-handling Xstatements like "ON ERROR GO TO ...". Different Xlanguages offer different forms of this statement, Xbut most share the following characteristics: X.IP \(em \w'\0\0\0\0'u XNo means is provided to substitute a value for Xthe offending operation's result and resume Xcomputation from what may be the middle of an Xexpression. An exceptional result is abandoned. X.IP \(em \w'\0\0\0\0'u XIn a subprogram that lacks an error\-handling Xstatement, an exception causes the subprogram to Xabort within whatever program called it, and so Xon back up the chain of calling subprograms until Xan error\-handling statement is encountered or the Xwhole task is aborted and memory is dumped. X.IP 5) \w'\0\0\0\0'u XSTOP. This mechanism, requiring an interactive Xdebugging environment, is more for the programmer Xthan the program. It classifies an exception in Xadvance as a symptom of a programmer's error; the Xexception suspends execution as near as it can to Xthe offending operation so that the programmer can Xlook around to see how it happened. Quite often Xthe first several exceptions turn out to be quite Xunexceptionable, so the programmer ought ideally Xto be able to resume execution after each one as if Xexecution had not been stopped. X.IP 6) \w'\0\0\0\0'u X\&... Other ways lie beyond the scope of this document. X.RE X.PP XThe crucial problem for exception handling is the problem of XScope, and the problem's solution is understood, but not Xenough manpower was available to implement it fully in time Xto be distributed in 4.3 BSD's \fIlibm\fR. Ideally, each Xelementary function should act as if it were indivisible, or Xatomic, in the sense that ... X.IP i) \w'iii)'u+2n XNo exception should be signaled that is not deserved by Xthe data supplied to that function. X.IP ii) \w'iii)'u+2n XAny exception signaled should be identified with that Xfunction rather than with one of its subroutines. X.IP iii) \w'iii)'u+2n XThe internal behavior of an atomic function should not Xbe disrupted when a calling program changes from Xone to another of the five or so ways of handling Xexceptions listed above, although the definition Xof the function may be correlated intentionally Xwith exception handling. X.PP XIdeally, every programmer should be able \fIconveniently\fR to Xturn a debugged subprogram into one that appears atomic to Xits users. But simulating all three characteristics of an Xatomic function is still a tedious affair, entailing hosts Xof tests and saves\-restores; work is under way to ameliorate Xthe inconvenience. X.PP XMeanwhile, the functions in \fIlibm\fR are only approximately Xatomic. They signal no inappropriate exception except Xpossibly ... X.RS XOver/Underflow X.RS Xwhen a result, if properly computed, might have lain barely within range, and X.RE XInexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR X.RS Xwhen it happens to be exact, thanks to fortuitous cancellation of errors. X.RE X.RE XOtherwise, ... X.RS XInvalid Operation is signaled only when X.RS Xany result but \*(nn would probably be misleading. X.RE XOverflow is signaled only when X.RS Xthe exact result would be finite but beyond the overflow threshold. X.RE XDivide\-by\-Zero is signaled only when X.RS Xa function takes exactly infinite values at finite operands. X.RE XUnderflow is signaled only when X.RS Xthe exact result would be nonzero but tinier than the underflow threshold. X.RE XInexact is signaled only when X.RS Xgreater range or precision would be needed to represent the exact result. X.RE X.RE X.SH BUGS XWhen signals are appropriate, they are emitted by certain Xoperations within the codes, so a subroutine\-trace may be Xneeded to identify the function with its signal in case Xmethod 5) above is in use. And the codes all take the XIEEE 754 defaults for granted; this means that a decision to Xtrap all divisions by zero could disrupt a code that would Xotherwise get correct results despite division by zero. X.SH SEE ALSO XAn explanation of IEEE 754 and its proposed extension p854 Xwas published in the IEEE magazine MICRO in August 1984 under Xthe title "A Proposed Radix\- and Word\-length\-independent XStandard for Floating\-point Arithmetic" by W. J. Cody et al. XThe manuals for Pascal, C and BASIC on the Apple Macintosh Xdocument the features of IEEE 754 pretty well. XArticles in the IEEE magazine COMPUTER vol. 14 no. 3 (Mar. X1981), and in the ACM SIGNUM Newsletter Special Issue of XOct. 1979, may be helpful although they pertain to Xsuperseded drafts of the standard. X.SH AUTHOR XW. Kahan, with the help of Z\-S. Alex Liu, Stuart I. McDonald, XDr. Kwok\-Choi Ng, Peter Tang. END_OF_FILE if test 20506 -ne `wc -c <'libm_math.3m'`; then echo shar: \"'libm_math.3m'\" unpacked with wrong size! fi # end of 'libm_math.3m' fi echo shar: End of archive 5 \(of 5\). cp /dev/null ark5isdone MISSING="" for I in 1 2 3 4 5 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 5 archives. rm -f ark[1-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 -- Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.