ieee.3 - OpenGrok cross reference for /freebsd/lib/msun/man/ieee.3

Deleted Added

sdiffudifftextold (24a0682c..)new (29bf6af8..)

ieee.3 (24a0682c6465290759ed0b09ea16e40e7cd47053)	ieee.3 (29bf6af8904f9833bbc9c0e5f2219f785defe550)
1.\" Copyright (c) 1985, 1991 Regents of the University of California.	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 --- 17 unchanged lines hidden (view full) --- 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: @(#)ieee.3 6.4 (Berkeley) 5/6/91 33.\" $FreeBSD$ 34.\"	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 --- 17 unchanged lines hidden (view full) --- 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: @(#)ieee.3 6.4 (Berkeley) 5/6/91 33.\" $FreeBSD$ 34.\"
35.Dd June 20, 2004	35.Dd January 26, 2005
36.Dt IEEE 3 37.Os 38.Sh NAME	36.Dt IEEE 3 37.Os 38.Sh NAME
39.Nm copysign , 40.Nm copysignf , 41.Nm copysignl , 42.Nm finite , 43.Nm finitef , 44.Nm ilogb , 45.Nm ilogbf , 46.Nm ilogbl , 47.Nm nextafter , 48.Nm nextafterf , 49.Nm remainder , 50.Nm remainderf , 51.Nm scalbln , 52.Nm scalblnf , 53.Nm scalbn , 54.Nm scalbnf 55.Nd functions for IEEE arithmetic 56.Sh LIBRARY 57.Lb libm 58.Sh SYNOPSIS 59.In math.h 60.Ft double 61.Fn copysign "double x" "double y" 62.Ft float 63.Fn copysignf "float x" "float y" 64.Ft long double 65.Fn copysignl "long double x" "long double y" 66.Ft int 67.Fn finite "double x" 68.Ft int 69.Fn finitef "float x" 70.Ft int 71.Fn ilogb "double x" 72.Ft int 73.Fn ilogbf "float x" 74.Ft int 75.Fn ilogbl "long double x" 76.Ft double 77.Fn nextafter "double x" "double y" 78.Ft float 79.Fn nextafterf "float x" "float y" 80.Ft double 81.Fn remainder "double x" "double y" 82.Ft float 83.Fn remainderf "float x" "float y" 84.Ft double 85.Fn scalbln "double x" "long n" 86.Ft float 87.Fn scalblnf "float x" "long n" 88.Ft double 89.Fn scalbn "double x" "int n" 90.Ft float 91.Fn scalbnf "float x" "int n"	39.Nm ieee 40.Nd IEEE standard 754 for floating-point arithmetic
92.Sh DESCRIPTION	41.Sh DESCRIPTION
93These functions are required or recommended by 94.St -ieee754 .	42The IEEE Standard 754 for Binary Floating-Point Arithmetic 43defines representations of floating-point numbers and abstract 44properties of arithmetic operations relating to precision, 45rounding, and exceptional cases, as described below. 46.Ss IEEE STANDARD 754 Floating-Point Arithmetic 47Radix: Binary.
95.Pp	48.Pp
96The 97.Fn copysign , 98.Fn copysignf 99and 100.Fn copysignl 101functions 102return 103.Fa x 104with its sign changed to 105.Fa y Ns 's .	49.Bl -column "" -compact 50Overflow and underflow: 51.El 52.Bd -ragged -offset indent -compact 53Overflow goes by default to a signed \*(If. 54Underflow is 55.Em gradual . 56.Ed
106.Pp	57.Pp
107.Fn finite 108and 109.Fn finitef 110return the value 1 just when 111\-\(If \(Lt 112.Fa x 113\(Lt +\(If; 114otherwise a 115zero is returned 116(when 117.Pf \\(Ba Ns Fa x Ns \\(Ba 118= \(If or 119.Fa x 120is \(Na).	58Zero is represented ambiguously as +0 or \-0. 59.Bd -ragged -offset indent -compact 60Its sign transforms correctly through multiplication or 61division, and is preserved by addition of zeros 62with like signs; but x\-x yields +0 for every 63finite x. 64The only operations that reveal zero's 65sign are division by zero and 66.Fn copysign x \(+-0 . 67In particular, comparison (x > y, x \(>= y, etc.)\& 68cannot be affected by the sign of zero; but if 69finite x = y then \(If = 1/(x\-y) \(!= \-1/(y\-x) = \-\(If. 70.Ed
121.Pp	71.Pp
122.Fn ilogb , 123.Fn ilogbf 124and 125.Fn ilogbl 126return 127.Fa x Ns 's exponent, 128in integer format. 129.Fn ilogb \(Pm\(If 130returns 131.Dv INT_MAX , 132.Fn ilogb \(Pm\(Na 133returns 134.Dv FP_ILOGBNAN 135and 136.Fn ilogb 0 137returns 138.Dv FP_ILOGB0 .	72Infinity is signed. 73.Bd -ragged -offset indent -compact 74It persists when added to itself 75or to any finite number. 76Its sign transforms 77correctly through multiplication and division, and 78(finite)/\(+-\(If\0=\0\(+-0 79(nonzero)/0 = \(+-\(If. 80But 81\(If\-\(If, \(If\(0 and \(If/\(If 82are, like 0/0 and sqrt(\-3), 83invalid operations that produce \(Na. ... 84.Ed
139.Pp	85.Pp
140.Fn nextafter 141and 142.Fn nextafterf 143return the next machine representable number from 144.Fa x 145in direction 146.Fa y .	86Reserved operands (\(Nas): 87.Bd -ragged -offset indent -compact 88An \(Na is 89.Em ( N Ns ot Em a N Ns umber ) . 90Some \(Nas, called Signaling \(Nas, trap any floating-point operation 91performed upon them; they are used to mark missing 92or uninitialized values, or nonexistent elements 93of arrays. 94The rest are Quiet \(Nas; they are 95the default results of Invalid Operations, and 96propagate through subsequent arithmetic operations. 97If x \(!= x then x is \(Na; every other predicate 98(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved. 99.Ed
147.Pp	100.Pp
148.Fn remainder 149and 150.Fn remainderf 151return the remainder 152.Fa r 153:= 154.Fa x 155\- 156.Fa n\(*y 157where 158.Fa n 159is the integer nearest the exact value of 160.Bk -words 161.Fa x Ns / Ns Fa y ; 162.Ek 163moreover if 164.Pf \\(Ba Fa n 165\- 166.Sm off 167.Fa x No / Fa y No \\*(Ba 168.Sm on 169= 1701/2	101Rounding: 102.Bd -ragged -offset indent -compact 103Every algebraic operation (+, \-, \(**, /, 104\(sr) 105is rounded by default to within half an 106.Em ulp , 107and when the rounding error is exactly half an 108.Em ulp
171then	109then
172.Fa n 173is even. 174Consequently 175the remainder is computed exactly and 176.Sm off 177.Pf \\(Ba Fa r No \\(Ba 178.Sm on 179\(Le 180.Sm off 181.Pf \\(Ba Fa y No \\(Ba/2 . 182.Sm on 183But 184.Fn remainder x 0 185and 186.Fn remainder \(If 0 187are invalid operations that produce a \*(Na.	110the rounded value's least significant bit is zero. 111(An 112.Em ulp 113is one 114.Em U Ns nit 115in the 116.Em L Ns ast 117.Em P Ns lace . ) 118This kind of rounding is usually the best kind, 119sometimes provably so; for instance, for every 120x = 1.0, 2.0, 3.0, 4.0, ..., 2.052, we find 121(x/3.0)\(3.0 == x and (x/10.0)\(*10.0 == x and ... 122despite that both the quotients and the products 123have been rounded. 124Only rounding like IEEE 754 can do that. 125But no single kind of rounding can be 126proved best for every circumstance, so IEEE 754 127provides rounding towards zero or towards 128+\(If or towards \-\*(If 129at the programmer's option. 130.Ed
188.Pp	131.Pp
189.Fn scalbln , 190.Fn scalblnf , 191.Fn scalbn ,	132Exceptions: 133.Bd -ragged -offset indent -compact 134IEEE 754 recognizes five kinds of floating-point exceptions, 135listed below in declining order of probable importance. 136.Bl -column -offset indent "Invalid Operation" "Gradual Underflow" 137.Em "Exception Default Result" 138Invalid Operation \(Na, or FALSE 139Overflow \(+-\(If 140Divide by Zero \(+-\(If 141Underflow Gradual Underflow 142Inexact Rounded value 143.El 144.Pp 145NOTE: An Exception is not an Error unless handled 146badly. 147What makes a class of exceptions exceptional 148is that no single default response can be satisfactory 149in every instance. 150On the other hand, if a default 151response will serve most instances satisfactorily, 152the unsatisfactory instances cannot justify aborting 153computation every time the exception occurs. 154.Ed 155.Ss Data Formats 156Single-precision: 157.Bd -ragged -offset indent -compact 158Type name: 159.Vt float 160.Pp 161Wordsize: 32 bits. 162.Pp 163Precision: 24 significant bits, 164roughly like 7 significant decimals. 165.Bd -ragged -offset indent -compact 166If x and x' are consecutive positive single-precision 167numbers (they differ by 1 168.Em ulp ) , 169then 170.Bd -ragged -compact 1715.9e\-08 < 0.524 < (x'\-x)/x \(<= 0.523 < 1.2e\-07. 172.Ed 173.Ed 174.Pp 175.Bl -column "XXX" -compact 176Range: Overflow threshold = 2.0128 = 3.4e38 177 Underflow threshold = 0.5126 = 1.2e\-38 178.El 179.Bd -ragged -offset indent -compact 180Underflowed results round to the nearest 181integer multiple of 0.5149 = 1.4e\-45. 182.Ed 183.Ed 184.Pp 185Double-precision: 186.Bd -ragged -offset indent -compact 187Type name: 188.Vt double 189.Bd -ragged -offset indent -compact 190On some architectures, 191.Vt long double 192is the the same as 193.Vt double . 194.Ed 195.Pp 196Wordsize: 64 bits. 197.Pp 198Precision: 53 significant bits, 199roughly like 16 significant decimals. 200.Bd -ragged -offset indent -compact 201If x and x' are consecutive positive double-precision 202numbers (they differ by 1 203.Em ulp ) , 204then 205.Bd -ragged -compact 2061.1e\-16 < 0.553 < (x'\-x)/x \(<= 0.552 < 2.3e\-16. 207.Ed 208.Ed 209.Pp 210.Bl -column "XXX" -compact 211Range: Overflow threshold = 2.01024 = 1.8e308 212 Underflow threshold = 0.51022 = 2.2e\-308 213.El 214.Bd -ragged -offset indent -compact 215Underflowed results round to the nearest 216integer multiple of 0.51074 = 4.9e\-324. 217.Ed 218.Ed 219.Pp 220Extended-precision: 221.Bd -ragged -offset indent -compact 222Type name: 223.Vt long double 224(when supported by the hardware) 225.Pp 226Wordsize: 96 bits. 227.Pp 228Precision: 64 significant bits, 229roughly like 19 significant decimals. 230.Bd -ragged -offset indent -compact 231If x and x' are consecutive positive double-precision 232numbers (they differ by 1 233.Em ulp ) , 234then 235.Bd -ragged -compact 2361.0e\-19 < 0.563 < (x'\-x)/x \(<= 0.562 < 2.2e\-19. 237.Ed 238.Ed 239.Pp 240.Bl -column "XXX" -compact 241Range: Overflow threshold = 2.016384 = 1.2e4932 242 Underflow threshold = 0.516382 = 3.4e\-4932 243.El 244.Bd -ragged -offset indent -compact 245Underflowed results round to the nearest 246integer multiple of 0.516451 = 5.7e\-4953. 247.Ed 248.Ed 249.Pp 250Quad-extended-precision: 251.Bd -ragged -offset indent -compact 252Type name: 253.Vt long double 254(when supported by the hardware) 255.Pp 256Wordsize: 128 bits. 257.Pp 258Precision: 113 significant bits, 259roughly like 34 significant decimals. 260.Bd -ragged -offset indent -compact 261If x and x' are consecutive positive double-precision 262numbers (they differ by 1 263.Em ulp ) , 264then 265.Bd -ragged -compact 2669.6e\-35 < 0.5113 < (x'\-x)/x \(<= 0.5112 < 2.0e\-34. 267.Ed 268.Ed 269.Pp 270.Bl -column "XXX" -compact 271Range: Overflow threshold = 2.016384 = 1.2e4932 272 Underflow threshold = 0.516382 = 3.4e\-4932 273.El 274.Bd -ragged -offset indent -compact 275Underflowed results round to the nearest 276integer multiple of 0.5*16494 = 6.5e\-4966. 277.Ed 278.Ed 279.Ss Additional Information Regarding Exceptions 280.Pp 281For each kind of floating-point exception, IEEE 754 282provides a Flag that is raised each time its exception 283is signaled, and stays raised until the program resets 284it. 285Programs may also test, save and restore a flag. 286Thus, IEEE 754 provides three ways by which programs 287may cope with exceptions for which the default result 288might be unsatisfactory: 289.Bl -enum 290.It 291Test for a condition that might cause an exception 292later, and branch to avoid the exception. 293.It 294Test a flag to see whether an exception has occurred 295since the program last reset its flag. 296.It 297Test a result to see whether it is a value that only 298an exception could have produced. 299.Pp 300CAUTION: The only reliable ways to discover 301whether Underflow has occurred are to test whether 302products or quotients lie closer to zero than the 303underflow threshold, or to test the Underflow 304flag. 305(Sums and differences cannot underflow in 306IEEE 754; if x \(!= y then x\-y is correct to 307full precision and certainly nonzero regardless of 308how tiny it may be.) 309Products and quotients that 310underflow gradually can lose accuracy gradually 311without vanishing, so comparing them with zero 312(as one might on a VAX) will not reveal the loss. 313Fortunately, if a gradually underflowed value is 314destined to be added to something bigger than the 315underflow threshold, as is almost always the case, 316digits lost to gradual underflow will not be missed 317because they would have been rounded off anyway. 318So gradual underflows are usually 319.Em provably 320ignorable. 321The same cannot be said of underflows flushed to 0. 322.El 323.Pp 324At the option of an implementor conforming to IEEE 754, 325other ways to cope with exceptions may be provided: 326.Bl -enum 327.It 328ABORT. 329This mechanism classifies an exception in 330advance as an incident to be handled by means 331traditionally associated with error-handling 332statements like "ON ERROR GO TO ...". 333Different 334languages offer different forms of this statement, 335but most share the following characteristics: 336.Bl -dash 337.It 338No means is provided to substitute a value for 339the offending operation's result and resume 340computation from what may be the middle of an 341expression. 342An exceptional result is abandoned. 343.It 344In a subprogram that lacks an error-handling 345statement, an exception causes the subprogram to 346abort within whatever program called it, and so 347on back up the chain of calling subprograms until 348an error-handling statement is encountered or the 349whole task is aborted and memory is dumped. 350.El 351.It 352STOP. 353This mechanism, requiring an interactive 354debugging environment, is more for the programmer 355than the program. 356It classifies an exception in 357advance as a symptom of a programmer's error; the 358exception suspends execution as near as it can to 359the offending operation so that the programmer can 360look around to see how it happened. 361Quite often 362the first several exceptions turn out to be quite 363unexceptionable, so the programmer ought ideally 364to be able to resume execution after each one as if 365execution had not been stopped. 366.It 367\&... Other ways lie beyond the scope of this document. 368.El 369.Pp 370Ideally, each 371elementary function should act as if it were indivisible, or 372atomic, in the sense that ... 373.Bl -enum 374.It 375No exception should be signaled that is not deserved by 376the data supplied to that function. 377.It 378Any exception signaled should be identified with that 379function rather than with one of its subroutines. 380.It 381The internal behavior of an atomic function should not 382be disrupted when a calling program changes from 383one to another of the five or so ways of handling 384exceptions listed above, although the definition 385of the function may be correlated intentionally 386with exception handling. 387.El 388.Pp 389The functions in 390.Nm libm 391are only approximately atomic. 392They signal no inappropriate exception except possibly ... 393.Bl -tag -width indent -offset indent -compact 394.It Xo 395Over/Underflow 396.Xc 397when a result, if properly computed, might have lain barely within range, and 398.It Xo 399Inexact in 400.Fn cabs , 401.Fn cbrt , 402.Fn hypot , 403.Fn log10
192and	404and
193.Fn scalbnf 194return 195.Fa x Ns \((2 Ns Fa n ) 196computed by exponent manipulation.	405.Fn pow 406.Xc 407when it happens to be exact, thanks to fortuitous cancellation of errors. 408.El 409Otherwise, ... 410.Bl -tag -width indent -offset indent -compact 411.It Xo 412Invalid Operation is signaled only when 413.Xc 414any result but \*(Na would probably be misleading. 415.It Xo 416Overflow is signaled only when 417.Xc 418the exact result would be finite but beyond the overflow threshold. 419.It Xo 420Divide-by-Zero is signaled only when 421.Xc 422a function takes exactly infinite values at finite operands. 423.It Xo 424Underflow is signaled only when 425.Xc 426the exact result would be nonzero but tinier than the underflow threshold. 427.It Xo 428Inexact is signaled only when 429.Xc 430greater range or precision would be needed to represent the exact result. 431.El
197.Sh SEE ALSO	432.Sh SEE ALSO
	433.Xr fenv 3 , 434.Xr ieee_test 3 ,
198.Xr math 3	435.Xr math 3
	436.Pp 437An explanation of IEEE 754 and its proposed extension p854 438was published in the IEEE magazine MICRO in August 1984 under 439the title "A Proposed Radix- and Word-length-independent 440Standard for Floating-point Arithmetic" by 441.An "W. J. Cody" 442et al. 443The manuals for Pascal, C and BASIC on the Apple Macintosh 444document the features of IEEE 754 pretty well. 445Articles in the IEEE magazine COMPUTER vol.\& 14 no.\& 3 (Mar.\& 4461981), and in the ACM SIGNUM Newsletter Special Issue of 447Oct.\& 1979, may be helpful although they pertain to 448superseded drafts of the standard.
199.Sh STANDARDS 200.St -ieee754	449.Sh STANDARDS 450.St -ieee754
201.Sh HISTORY 202The 203.Nm ieee 204functions appeared in 205.Bx 4.3 . 206The 207.Fn copysignl , 208.Fn scalbln , 209and 210.Fn scalblnf 211functions first appeared in 212.Fx 5.3 .