1.\" Copyright (c) 1985 Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" from: @(#)math.3 6.10 (Berkeley) 5/6/91 33.\" $FreeBSD$ 34.\" 35.Dd June 11, 2004 36.Dt MATH 3 37.Os 38.ds up \fIulp\fR 39.de If 40.if n \\ 41\\$1Infinity\\$2 42.if t \\ 43\\$1\\(if\\$2 44.. 45.Sh NAME 46math \- introduction to mathematical library functions 47.Sh DESCRIPTION 48These functions constitute the C math library, 49.I libm. 50The link editor searches this library under the \*(lq\-lm\*(rq option. 51Declarations for these functions may be obtained from the include file 52.In math.h . 53.Sh "LIST OF FUNCTIONS" 54Each of the following 55.Vt double 56functions has a 57.Vt float 58counterpart with an 59.Ql f 60appended to the name and a 61.Vt long double 62counterpart with an 63.Ql l 64appended. 65As an example, the 66.Vt float 67and 68.Vt long double 69counterparts of 70.Ft double 71.Fn acos "double x" 72are 73.Ft float 74.Fn acosf "float x" 75and 76.Ft long double 77.Fn acosl "long double x" , 78respectively. 79.sp 2 80.nf 81.ta \w'nexttoward'u+10n +\w'remainder with partial quot'u 82\fIName\fP \fIDescription\fP \fIError Bound (ULPs)\fP 83.ta \w'nexttoward'u+4n +\w'remainder with partial quotient'u+6nC 84.sp 5p 85.\" XXX Many of these error bounds are wrong for the current implementation! 86acos inverse trigonometric function 3 87acosh inverse hyperbolic function 3 88asin inverse trigonometric function 3 89asinh inverse hyperbolic function 3 90atan inverse trigonometric function 1 91atanh inverse hyperbolic function 3 92atan2 inverse trigonometric function 2 93cbrt cube root 1 94ceil integer no less than 0 95copysign copy sign bit 0 96cos trigonometric function 1 97cosh hyperbolic function 3 98erf error function ??? 99erfc complementary error function ??? 100exp exponential base e 1 101.\" exp2 exponential base 2 ??? 102expm1 exp(x)\-1 1 103fabs absolute value 0 104.\" fdim positive difference ??? 105floor integer no greater than 0 106.\" fma multiply-add ??? 107.\" fmax maximum function 0 108.\" fmin minimum function 0 109fmod remainder function ??? 110frexp extract mantissa and exponent 0 111hypot Euclidean distance 1 112ilogb exponent extraction 0 113j0 bessel function ??? 114j1 bessel function ??? 115jn bessel function ??? 116ldexp multiply by power of 2 0 117lgamma log gamma function ??? 118.\" llrint round to integer 0 119.\" llround round to nearest integer 0 120log natural logarithm 1 121log10 logarithm to base 10 3 122log1p log(1+x) 1 123.\" log2 base 2 logarithm 0 124logb exponent extraction 0 125.\" lrint round to integer 0 126.\" lround round to nearest integer 0 127modf extract fractional part ??? 128.\" nan return quiet \*(Na) 0 129.\" nearbyint round to integer 0 130nextafter next representable value 0 131.\" nexttoward next representable value 0 132pow exponential x**y 60\-500 133remainder remainder 0 134.\" remquo remainder with partial quotient ??? 135rint round to nearest integer 0 136round round to nearest integer 0 137scalbln exponent adjustment 0 138scalbn exponent adjustment 0 139sin trigonometric function 1 140sinh hyperbolic function 3 141sqrt square root 1 142tan trigonometric function 3 143tanh hyperbolic function 3 144tgamma gamma function ??? 145trunc round towards zero 0 146y0 bessel function ??? 147y1 bessel function ??? 148yn bessel function ??? 149.ta 150.fi 151.Sh NOTES 152Virtually all modern floating-point units attempt to support 153IEEE Standard 754 for Binary Floating-Point Arithmetic. 154This standard does not cover particular routines in the math library 155except for the few documented in 156.Xr ieee 3 ; 157it primarily defines representations of numbers and abstract 158properties of arithmetic operations relating to precision, rounding, 159and exceptional cases, as described below. 160The programs are accurate to within the numbers 161of \*(ups tabulated above; an \*(up is one \fIU\fRnit in the \fIL\fRast 162\fIP\fRlace. 163.Pp 164\fBIEEE STANDARD 754 Floating\-Point Arithmetic:\fR 165.Pp 166Properties of IEEE 754 Double\-Precision: 167.Bd -filled -offset indent 168Wordsize: 64 bits, 8 bytes. Radix: Binary. 169.br 170Precision: 53 171.if n \ 172sig. 173.if t \ 174significant 175bits, roughly like 16 176.if n \ 177sig. 178.if t \ 179significant 180decimals. 181.Bd -filled -offset indent -compact 182If x and x' are consecutive positive Double\-Precision 183numbers (they differ by 1 \*(up), then 184.br 1851.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16. 186.Ed 187.nf 188.ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**1024'u+1n 189Range: Overflow threshold = 2.0**1024 = 1.8e308 190 Underflow threshold = 0.5**1022 = 2.2e\-308 191.ta 192.fi 193.Bd -filled -offset indent -compact 194Overflow goes by default to a signed 195.If "" . 196.br 197Underflow is \fIGradual,\fR rounding to the nearest 198integer multiple of 0.5**1074 = 4.9e\-324. 199.Ed 200Zero is represented ambiguously as +0 or \-0. 201.Bd -filled -offset indent -compact 202Its sign transforms correctly through multiplication or 203division, and is preserved by addition of zeros 204with like signs; but x\-x yields +0 for every 205finite x. The only operations that reveal zero's 206sign are division by zero and copysign(x,\(+-0). 207In particular, comparison (x > y, x \(>= y, etc.) 208cannot be affected by the sign of zero; but if 209finite x = y then 210.If 211\&= 1/(x\-y) 212.if n \ 213!= 214.if t \ 215\(!= 216\-1/(y\-x) = 217.If \- . 218.Ed 219.If 220is signed. 221.Bd -filled -offset indent -compact 222it persists when added to itself 223or to any finite number. Its sign transforms 224correctly through multiplication and division, and 225.If (finite)/\(+- \0=\0\(+-0 226(nonzero)/0 = 227.If \(+- . 228But 229.if n \ 230Infinity\-Infinity, Infinity\(**0 and Infinity/Infinity 231.if t \ 232\(if\-\(if, \(if\(**0 and \(if/\(if 233are, like 0/0 and sqrt(\-3), 234invalid operations that produce \*(Na. ... 235.Ed 236Reserved operands: 237.Bd -filled -offset indent -compact 238there are 2**53\-2 of them, all 239called \*(Na (\fIN\fRot \fIa N\fRumber). 240Some, called Signaling \*(Nas, trap any floating\-point operation 241performed upon them; they are used to mark missing 242or uninitialized values, or nonexistent elements 243of arrays. The rest are Quiet \*(Nas; they are 244the default results of Invalid Operations, and 245propagate through subsequent arithmetic operations. 246If x 247.if n \ 248!= 249.if t \ 250\(!= 251x then x is \*(Na; every other predicate 252(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved. 253.br 254NOTE: Trichotomy is violated by \*(Na. 255.Bd -filled -offset indent -compact 256Besides being FALSE, predicates that entail ordered 257comparison, rather than mere (in)equality, 258signal Invalid Operation when \*(Na is involved. 259.Ed 260.Ed 261Rounding: 262.Bd -filled -offset indent -compact 263Every algebraic operation (+, \-, \(**, /, 264.if n \ 265sqrt) 266.if t \ 267\(sr) 268is rounded by default to within half an \*(up, and 269when the rounding error is exactly half an \*(up then 270the rounded value's least significant bit is zero. 271This kind of rounding is usually the best kind, 272sometimes provably so; for instance, for every 273x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find 274(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ... 275despite that both the quotients and the products 276have been rounded. Only rounding like IEEE 754 277can do that. But no single kind of rounding can be 278proved best for every circumstance, so IEEE 754 279provides rounding towards zero or towards 280.If + 281or towards 282.If \- 283at the programmer's option. And the 284same kinds of rounding are specified for 285Binary\-Decimal Conversions, at least for magnitudes 286between roughly 1.0e\-10 and 1.0e37. 287.Ed 288Exceptions: 289.Bd -filled -offset indent -compact 290IEEE 754 recognizes five kinds of floating\-point exceptions, 291listed below in declining order of probable importance. 292.Bd -filled -offset indent -compact 293.nf 294.ta \w'Invalid Operation'u+6n +\w'Gradual Underflow'u+2n 295Exception Default Result 296.tc \(ru 297 298.tc 299Invalid Operation \*(Na, or FALSE 300.if n \{\ 301Overflow \(+-Infinity 302Divide by Zero \(+-Infinity \} 303.if t \{\ 304Overflow \(+-\(if 305Divide by Zero \(+-\(if \} 306Underflow Gradual Underflow 307Inexact Rounded value 308.ta 309.fi 310.Ed 311NOTE: An Exception is not an Error unless handled 312badly. What makes a class of exceptions exceptional 313is that no single default response can be satisfactory 314in every instance. On the other hand, if a default 315response will serve most instances satisfactorily, 316the unsatisfactory instances cannot justify aborting 317computation every time the exception occurs. 318.Ed 319.Pp 320For each kind of floating\-point exception, IEEE 754 321provides a Flag that is raised each time its exception 322is signaled, and stays raised until the program resets 323it. Programs may also test, save and restore a flag. 324Thus, IEEE 754 provides three ways by which programs 325may cope with exceptions for which the default result 326might be unsatisfactory: 327.Bl -enum 328.It 329Test for a condition that might cause an exception 330later, and branch to avoid the exception. 331.It 332Test a flag to see whether an exception has occurred 333since the program last reset its flag. 334.It 335Test a result to see whether it is a value that only 336an exception could have produced. 337.RS 338CAUTION: The only reliable ways to discover 339whether Underflow has occurred are to test whether 340products or quotients lie closer to zero than the 341underflow threshold, or to test the Underflow 342flag. (Sums and differences cannot underflow in 343IEEE 754; if x 344.if n \ 345!= 346.if t \ 347\(!= 348y then x\-y is correct to 349full precision and certainly nonzero regardless of 350how tiny it may be.) Products and quotients that 351underflow gradually can lose accuracy gradually 352without vanishing, so comparing them with zero 353(as one might on a VAX) will not reveal the loss. 354Fortunately, if a gradually underflowed value is 355destined to be added to something bigger than the 356underflow threshold, as is almost always the case, 357digits lost to gradual underflow will not be missed 358because they would have been rounded off anyway. 359So gradual underflows are usually \fIprovably\fR ignorable. 360The same cannot be said of underflows flushed to 0. 361.RE 362.El 363.Pp 364At the option of an implementor conforming to IEEE 754, 365other ways to cope with exceptions may be provided: 366.Bl -hang -width 3n 367.It 4. 368ABORT. This mechanism classifies an exception in 369advance as an incident to be handled by means 370traditionally associated with error\-handling 371statements like "ON ERROR GO TO ...". Different 372languages offer different forms of this statement, 373but most share the following characteristics: 374.Bl -dash 375.It 376No means is provided to substitute a value for 377the offending operation's result and resume 378computation from what may be the middle of an 379expression. An exceptional result is abandoned. 380.It 381In a subprogram that lacks an error\-handling 382statement, an exception causes the subprogram to 383abort within whatever program called it, and so 384on back up the chain of calling subprograms until 385an error\-handling statement is encountered or the 386whole task is aborted and memory is dumped. 387.El 388.It 5. 389STOP. This mechanism, requiring an interactive 390debugging environment, is more for the programmer 391than the program. It classifies an exception in 392advance as a symptom of a programmer's error; the 393exception suspends execution as near as it can to 394the offending operation so that the programmer can 395look around to see how it happened. Quite often 396the first several exceptions turn out to be quite 397unexceptionable, so the programmer ought ideally 398to be able to resume execution after each one as if 399execution had not been stopped. 400.It 6. 401\&... Other ways lie beyond the scope of this document. 402.El 403.Ed 404.Pp 405Ideally, each 406elementary function should act as if it were indivisible, or 407atomic, in the sense that ... 408.Bl -tag -width "iii)" 409.It i) 410No exception should be signaled that is not deserved by 411the data supplied to that function. 412.It ii) 413Any exception signaled should be identified with that 414function rather than with one of its subroutines. 415.It iii) 416The internal behavior of an atomic function should not 417be disrupted when a calling program changes from 418one to another of the five or so ways of handling 419exceptions listed above, although the definition 420of the function may be correlated intentionally 421with exception handling. 422.El 423.Pp 424The functions in \fIlibm\fR are only approximately atomic. 425They signal no inappropriate exception except possibly ... 426.Bd -filled -offset indent -compact 427Over/Underflow 428.Bd -filled -offset indent -compact 429when a result, if properly computed, might have lain barely within range, and 430.Ed 431Inexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR 432.Bd -filled -offset indent -compact 433when it happens to be exact, thanks to fortuitous cancellation of errors. 434.Ed 435.Ed 436Otherwise, ... 437.Bd -filled -offset indent -compact 438Invalid Operation is signaled only when 439.Bd -filled -offset indent -compact 440any result but \*(Na would probably be misleading. 441.Ed 442Overflow is signaled only when 443.Bd -filled -offset indent -compact 444the exact result would be finite but beyond the overflow threshold. 445.Ed 446Divide\-by\-Zero is signaled only when 447.Bd -filled -offset indent -compact 448a function takes exactly infinite values at finite operands. 449.Ed 450Underflow is signaled only when 451.Bd -filled -offset indent -compact 452the exact result would be nonzero but tinier than the underflow threshold. 453.Ed 454Inexact is signaled only when 455.Bd -filled -offset indent -compact 456greater range or precision would be needed to represent the exact result. 457.Ed 458.Ed 459.Sh BUGS 460Several functions required by 461.St -isoC-99 462are missing, and many functions are not available in their 463.Vt long double 464variants. 465.Sh SEE ALSO 466.Xr fenv 3 , 467.Xr ieee 3 468.Pp 469An explanation of IEEE 754 and its proposed extension p854 470was published in the IEEE magazine MICRO in August 1984 under 471the title "A Proposed Radix\- and Word\-length\-independent 472Standard for Floating\-point Arithmetic" by W. J. Cody et al. 473The manuals for Pascal, C and BASIC on the Apple Macintosh 474document the features of IEEE 754 pretty well. 475Articles in the IEEE magazine COMPUTER vol. 14 no. 3 (Mar.\& 4761981), and in the ACM SIGNUM Newsletter Special Issue of 477Oct. 1979, may be helpful although they pertain to 478superseded drafts of the standard. 479.Sh HISTORY 480A math library with many of the present functions appeared in 481Version 7 AT&T UNIX. 482The library was substantially rewritten for 4.3BSD to provide 483better accuracy and speed on machines supporting either VAX 484or IEEE 754 floating-point. 485Most of this library was replaced with FDLIBM, developed at Sun 486Microsystems, in 487.Fx 1.1.5 . 488