lib/libm/man/ieee.3

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