| math.3 (140681) | math.3 (140890) |
|---|---|
| 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. --- 16 unchanged lines hidden (view full) --- 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 | 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. --- 16 unchanged lines hidden (view full) --- 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: head/lib/msun/man/math.3 140681 2005-01-23 22:05:33Z das $ | 33.\" $FreeBSD: head/lib/msun/man/math.3 140890 2005-01-27 05:46:17Z das $ |
| 34.\" 35.Dd January 11, 2005 36.Dt MATH 3 37.Os 38.if n \{\ 39.char \[sr] "sqrt 40.\} 41.Sh NAME --- 153 unchanged lines hidden (view full) --- 195yn Bessel function of the second kind of the order n 196.El 197.Pp 198Unlike the algebraic functions listed earlier, the routines 199in this section may not produce a result that is correctly rounded. 200In general, an unbounded number of digits of a value taken by a 201transcendental function may be needed to determine the correctly rounded 202result. | 34.\" 35.Dd January 11, 2005 36.Dt MATH 3 37.Os 38.if n \{\ 39.char \[sr] "sqrt 40.\} 41.Sh NAME --- 153 unchanged lines hidden (view full) --- 195yn Bessel function of the second kind of the order n 196.El 197.Pp 198Unlike the algebraic functions listed earlier, the routines 199in this section may not produce a result that is correctly rounded. 200In general, an unbounded number of digits of a value taken by a 201transcendental function may be needed to determine the correctly rounded 202result. |
| 203.Sh NOTES 204Virtually all modern floating-point units attempt to support 205IEEE Standard 754 for Binary Floating-Point Arithmetic. 206This standard does not cover particular routines in the math library 207except for the few documented in 208.Xr ieee 3 ; 209it primarily defines representations of numbers and abstract 210properties of arithmetic operations relating to precision, rounding, 211and exceptional cases, as described below. 212.Ss IEEE STANDARD 754 Floating-Point Arithmetic 213.\" XXX mention single- and extended-/quad- precisions 214Radix: Binary. 215.Pp 216.Bl -column "" -compact 217Overflow and underflow: 218.El 219.Bd -ragged -offset indent -compact 220Overflow goes by default to a signed \*(If. 221Underflow is 222.Em gradual . 223.Ed 224.Pp 225Zero is represented ambiguously as +0 or \-0. 226.Bd -ragged -offset indent -compact 227Its sign transforms correctly through multiplication or 228division, and is preserved by addition of zeros 229with like signs; but x\-x yields +0 for every 230finite x. 231The only operations that reveal zero's 232sign are division by zero and 233.Fn copysign x \(+-0 . 234In particular, comparison (x > y, x \(>= y, etc.)\& 235cannot be affected by the sign of zero; but if 236finite x = y then \*(If = 1/(x\-y) \(!= \-1/(y\-x) = \-\*(If. 237.Ed 238.Pp 239Infinity is signed. 240.Bd -ragged -offset indent -compact 241It persists when added to itself 242or to any finite number. 243Its sign transforms 244correctly through multiplication and division, and 245(finite)/\(+-\*(If\0=\0\(+-0 246(nonzero)/0 = \(+-\*(If. 247But 248\*(If\-\*(If, \*(If\(**0 and \*(If/\*(If 249are, like 0/0 and sqrt(\-3), 250invalid operations that produce \*(Na. ... 251.Ed 252.Pp 253Reserved operands (\*(Nas): 254.Bd -ragged -offset indent -compact 255An \*(Na is 256.Em ( N Ns ot Em a N Ns umber ) . 257Some \*(Nas, called Signaling \*(Nas, trap any floating-point operation 258performed upon them; they are used to mark missing 259or uninitialized values, or nonexistent elements 260of arrays. 261The rest are Quiet \*(Nas; they are 262the default results of Invalid Operations, and 263propagate through subsequent arithmetic operations. 264If x \(!= x then x is \*(Na; every other predicate 265(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved. 266.Ed 267.Pp 268Rounding: 269.Bd -ragged -offset indent -compact 270Every algebraic operation (+, \-, \(**, /, 271\(sr) 272is rounded by default to within half an 273.Em ulp , 274and when the rounding error is exactly half an 275.Em ulp 276then 277the rounded value's least significant bit is zero. 278(An 279.Em ulp 280is one 281.Em U Ns nit 282in the 283.Em L Ns ast 284.Em P Ns lace . ) 285This kind of rounding is usually the best kind, 286sometimes provably so; for instance, for every 287x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find 288(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ... 289despite that both the quotients and the products 290have been rounded. 291Only rounding like IEEE 754 can do that. 292But no single kind of rounding can be 293proved best for every circumstance, so IEEE 754 294provides rounding towards zero or towards 295+\*(If or towards \-\*(If 296at the programmer's option. 297.Ed 298.Pp 299Exceptions: 300.Bd -ragged -offset indent -compact 301IEEE 754 recognizes five kinds of floating-point exceptions, 302listed below in declining order of probable importance. 303.Bl -column -offset indent "Invalid Operation" "Gradual Underflow" 304.Em "Exception Default Result" 305Invalid Operation \*(Na, or FALSE 306Overflow \(+-\*(If 307Divide by Zero \(+-\*(If 308Underflow Gradual Underflow 309Inexact Rounded value 310.El 311.Pp 312NOTE: An Exception is not an Error unless handled 313badly. 314What makes a class of exceptions exceptional 315is that no single default response can be satisfactory 316in every instance. 317On the other hand, if a default 318response will serve most instances satisfactorily, 319the unsatisfactory instances cannot justify aborting 320computation every time the exception occurs. 321.Ed 322.Ss Data Formats 323Single-precision: 324.Bd -ragged -offset indent -compact 325Type name: 326.Vt float 327.Pp 328Wordsize: 32 bits. 329.Pp 330Precision: 24 significant bits, 331roughly like 7 significant decimals. 332.Bd -ragged -offset indent -compact 333If x and x' are consecutive positive single-precision 334numbers (they differ by 1 335.Em ulp ) , 336then 337.Bd -ragged -compact 3385.9e\-08 < 0.5**24 < (x'\-x)/x \(<= 0.5**23 < 1.2e\-07. 339.Ed 340.Ed 341.Pp 342.Bl -column "XXX" -compact 343Range: Overflow threshold = 2.0**128 = 3.4e38 344 Underflow threshold = 0.5**126 = 1.2e\-38 345.El 346.Bd -ragged -offset indent -compact 347Underflowed results round to the nearest 348integer multiple of 0.5**149 = 1.4e\-45. 349.Ed 350.Ed 351.Pp 352Double-precision: 353.Bd -ragged -offset indent -compact 354Type name: 355.Vt double 356.Bd -ragged -offset indent -compact 357On some architectures, 358.Vt long double 359is the the same as 360.Vt double . 361.Ed 362.Pp 363Wordsize: 64 bits. 364.Pp 365Precision: 53 significant bits, 366roughly like 16 significant decimals. 367.Bd -ragged -offset indent -compact 368If x and x' are consecutive positive double-precision 369numbers (they differ by 1 370.Em ulp ) , 371then 372.Bd -ragged -compact 3731.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16. 374.Ed 375.Ed 376.Pp 377.Bl -column "XXX" -compact 378Range: Overflow threshold = 2.0**1024 = 1.8e308 379 Underflow threshold = 0.5**1022 = 2.2e\-308 380.El 381.Bd -ragged -offset indent -compact 382Underflowed results round to the nearest 383integer multiple of 0.5**1074 = 4.9e\-324. 384.Ed 385.Ed 386.Pp 387Extended-precision: 388.Bd -ragged -offset indent -compact 389Type name: 390.Vt long double 391(when supported by the hardware) 392.Pp 393Wordsize: 96 bits. 394.Pp 395Precision: 64 significant bits, 396roughly like 19 significant decimals. 397.Bd -ragged -offset indent -compact 398If x and x' are consecutive positive double-precision 399numbers (they differ by 1 400.Em ulp ) , 401then 402.Bd -ragged -compact 4031.0e\-19 < 0.5**63 < (x'\-x)/x \(<= 0.5**62 < 2.2e\-19. 404.Ed 405.Ed 406.Pp 407.Bl -column "XXX" -compact 408Range: Overflow threshold = 2.0**16384 = 1.2e4932 409 Underflow threshold = 0.5**16382 = 3.4e\-4932 410.El 411.Bd -ragged -offset indent -compact 412Underflowed results round to the nearest 413integer multiple of 0.5**16451 = 5.7e\-4953. 414.Ed 415.Ed 416.Pp 417Quad-extended-precision: 418.Bd -ragged -offset indent -compact 419Type name: 420.Vt long double 421(when supported by the hardware) 422.Pp 423Wordsize: 128 bits. 424.Pp 425Precision: 113 significant bits, 426roughly like 34 significant decimals. 427.Bd -ragged -offset indent -compact 428If x and x' are consecutive positive double-precision 429numbers (they differ by 1 430.Em ulp ) , 431then 432.Bd -ragged -compact 4339.6e\-35 < 0.5**113 < (x'\-x)/x \(<= 0.5**112 < 2.0e\-34. 434.Ed 435.Ed 436.Pp 437.Bl -column "XXX" -compact 438Range: Overflow threshold = 2.0**16384 = 1.2e4932 439 Underflow threshold = 0.5**16382 = 3.4e\-4932 440.El 441.Bd -ragged -offset indent -compact 442Underflowed results round to the nearest 443integer multiple of 0.5**16494 = 6.5e\-4966. 444.Ed 445.Ed 446.Ss Additional Information Regarding Exceptions 447.Pp 448For each kind of floating-point exception, IEEE 754 449provides a Flag that is raised each time its exception 450is signaled, and stays raised until the program resets 451it. 452Programs may also test, save and restore a flag. 453Thus, IEEE 754 provides three ways by which programs 454may cope with exceptions for which the default result 455might be unsatisfactory: 456.Bl -enum 457.It 458Test for a condition that might cause an exception 459later, and branch to avoid the exception. 460.It 461Test a flag to see whether an exception has occurred 462since the program last reset its flag. 463.It 464Test a result to see whether it is a value that only 465an exception could have produced. 466.Pp 467CAUTION: The only reliable ways to discover 468whether Underflow has occurred are to test whether 469products or quotients lie closer to zero than the 470underflow threshold, or to test the Underflow 471flag. 472(Sums and differences cannot underflow in 473IEEE 754; if x \(!= y then x\-y is correct to 474full precision and certainly nonzero regardless of 475how tiny it may be.) 476Products and quotients that 477underflow gradually can lose accuracy gradually 478without vanishing, so comparing them with zero 479(as one might on a VAX) will not reveal the loss. 480Fortunately, if a gradually underflowed value is 481destined to be added to something bigger than the 482underflow threshold, as is almost always the case, 483digits lost to gradual underflow will not be missed 484because they would have been rounded off anyway. 485So gradual underflows are usually 486.Em provably 487ignorable. 488The same cannot be said of underflows flushed to 0. 489.El 490.Pp 491At the option of an implementor conforming to IEEE 754, 492other ways to cope with exceptions may be provided: 493.Bl -enum 494.It 495ABORT. 496This mechanism classifies an exception in 497advance as an incident to be handled by means 498traditionally associated with error-handling 499statements like "ON ERROR GO TO ...". 500Different 501languages offer different forms of this statement, 502but most share the following characteristics: 503.Bl -dash 504.It 505No means is provided to substitute a value for 506the offending operation's result and resume 507computation from what may be the middle of an 508expression. 509An exceptional result is abandoned. 510.It 511In a subprogram that lacks an error-handling 512statement, an exception causes the subprogram to 513abort within whatever program called it, and so 514on back up the chain of calling subprograms until 515an error-handling statement is encountered or the 516whole task is aborted and memory is dumped. 517.El 518.It 519STOP. 520This mechanism, requiring an interactive 521debugging environment, is more for the programmer 522than the program. 523It classifies an exception in 524advance as a symptom of a programmer's error; the 525exception suspends execution as near as it can to 526the offending operation so that the programmer can 527look around to see how it happened. 528Quite often 529the first several exceptions turn out to be quite 530unexceptionable, so the programmer ought ideally 531to be able to resume execution after each one as if 532execution had not been stopped. 533.It 534\&... Other ways lie beyond the scope of this document. 535.El 536.Pp 537Ideally, each 538elementary function should act as if it were indivisible, or 539atomic, in the sense that ... 540.Bl -enum 541.It 542No exception should be signaled that is not deserved by 543the data supplied to that function. 544.It 545Any exception signaled should be identified with that 546function rather than with one of its subroutines. 547.It 548The internal behavior of an atomic function should not 549be disrupted when a calling program changes from 550one to another of the five or so ways of handling 551exceptions listed above, although the definition 552of the function may be correlated intentionally 553with exception handling. 554.El 555.Pp 556The functions in 557.Nm libm 558are only approximately atomic. 559They signal no inappropriate exception except possibly ... 560.Bl -tag -width indent -offset indent -compact 561.It Xo 562Over/Underflow 563.Xc 564when a result, if properly computed, might have lain barely within range, and 565.It Xo 566Inexact in 567.Fn cabs , 568.Fn cbrt , 569.Fn hypot , 570.Fn log10 571and 572.Fn pow 573.Xc 574when it happens to be exact, thanks to fortuitous cancellation of errors. 575.El 576Otherwise, ... 577.Bl -tag -width indent -offset indent -compact 578.It Xo 579Invalid Operation is signaled only when 580.Xc 581any result but \*(Na would probably be misleading. 582.It Xo 583Overflow is signaled only when 584.Xc 585the exact result would be finite but beyond the overflow threshold. 586.It Xo 587Divide-by-Zero is signaled only when 588.Xc 589a function takes exactly infinite values at finite operands. 590.It Xo 591Underflow is signaled only when 592.Xc 593the exact result would be nonzero but tinier than the underflow threshold. 594.It Xo 595Inexact is signaled only when 596.Xc 597greater range or precision would be needed to represent the exact result. 598.El | |
| 599.Sh SEE ALSO 600.Xr fenv 3 , 601.Xr ieee 3 | 203.Sh SEE ALSO 204.Xr fenv 3 , 205.Xr ieee 3 |
| 602.Pp 603An explanation of IEEE 754 and its proposed extension p854 604was published in the IEEE magazine MICRO in August 1984 under 605the title "A Proposed Radix- and Word-length-independent 606Standard for Floating-point Arithmetic" by 607.An "W. J. Cody" 608et al. 609The manuals for Pascal, C and BASIC on the Apple Macintosh 610document the features of IEEE 754 pretty well. 611Articles in the IEEE magazine COMPUTER vol.\& 14 no.\& 3 (Mar.\& 6121981), and in the ACM SIGNUM Newsletter Special Issue of 613Oct.\& 1979, may be helpful although they pertain to 614superseded drafts of the standard. | |
| 615.Sh HISTORY 616A math library with many of the present functions appeared in 617.At v7 . 618The library was substantially rewritten for 619.Bx 4.3 620to provide 621better accuracy and speed on machines supporting either VAX 622or IEEE 754 floating-point. --- 23 unchanged lines hidden --- | 206.Sh HISTORY 207A math library with many of the present functions appeared in 208.At v7 . 209The library was substantially rewritten for 210.Bx 4.3 211to provide 212better accuracy and speed on machines supporting either VAX 213or IEEE 754 floating-point. --- 23 unchanged lines hidden --- |