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