lib/msun/man/math.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. 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: src/lib/msun/man/math.3,v 1.9.2.1 2001/07/22 12:07:20 dd Exp $
  34 .\" $DragonFly: src/lib/msun/man/Attic/math.3,v 1.2 2003/06/17 04:26:52 dillon Exp $
  35 .\"
  36 .TH MATH 3M "May 6, 1991"
  37 .UC 4
  38 .ds up \fIulp\fR
  39 .ds nn \fINaN\fR
  40 .de If
  41 .if n \\
  42 \\$1Infinity\\$2
  43 .if t \\
  44 \\$1\\(if\\$2
  45 ..
  46 .SH NAME
  47 math \- introduction to mathematical library functions
  48 .SH DESCRIPTION
  49 These functions constitute the C math library,
  50 .I libm.
  51 The link editor searches this library under the \*(lq\-lm\*(rq option.
  52 Declarations for these functions may be obtained from the include file
  53 .RI < math.h >.
  54 .\" The Fortran math library is described in ``man 3f intro''.
  55 .SH "LIST OF FUNCTIONS"
  56 Each of the following double functions has a float counterpart with the
  57 name ending in f, as an example the float counterpart of double acos(double
  58 x) is float acosf(float x).
  59 .sp 2
  60 .nf
  61 .ta \w'copysign'u+2n +\w'infnan.3m'u+10n +\w'inverse trigonometric func'u
  62 \fIName\fP      \fIAppears on Page\fP   \fIDescription\fP       \fIError Bound (ULPs)\fP
  63 .ta \w'copysign'u+4n +\w'infnan.3m'u+4n +\w'inverse trigonometric function'u+6nC
  64 .sp 5p
  65 acos    sin.3m  inverse trigonometric function  3
  66 acosh   asinh.3m        inverse hyperbolic function     3
  67 asin    sin.3m  inverse trigonometric function  3
  68 asinh   asinh.3m        inverse hyperbolic function     3
  69 atan    sin.3m  inverse trigonometric function  1
  70 atanh   asinh.3m        inverse hyperbolic function     3
  71 atan2   sin.3m  inverse trigonometric function  2
  72 cabs    hypot.3m        complex absolute value  1
  73 cbrt    sqrt.3m cube root       1
  74 ceil    floor.3m        integer no less than    0
  75 copysign        ieee.3m copy sign bit   0
  76 cos     sin.3m  trigonometric function  1
  77 cosh    sinh.3m hyperbolic function     3
  78 erf     erf.3m  error function  ???
  79 erfc    erf.3m  complementary error function    ???
  80 exp     exp.3m  exponential     1
  81 expm1   exp.3m  exp(x)\-1       1
  82 fabs    floor.3m        absolute value  0
  83 floor   floor.3m        integer no greater than 0
  84 hypot   hypot.3m        Euclidean distance      1
  85 ilogb   ieee.3m exponent extraction     0
  86 j0      j0.3m   bessel function ???
  87 j1      j0.3m   bessel function ???
  88 jn      j0.3m   bessel function ???
  89 lgamma  lgamma.3m       log gamma function; (formerly gamma.3m)
  90 log     exp.3m  natural logarithm       1
  91 log10   exp.3m  logarithm to base 10    3
  92 log1p   exp.3m  log(1+x)        1
  93 pow     exp.3m  exponential x**y        60\-500
  94 remainder       ieee.3m remainder       0
  95 rint    floor.3m        round to nearest integer        0
  96 scalbn  ieee.3m exponent adjustment     0
  97 sin     sin.3m  trigonometric function  1
  98 sinh    sinh.3m hyperbolic function     3
  99 sqrt    sqrt.3m square root     1
 100 tan     sin.3m  trigonometric function  3
 101 tanh    sinh.3m hyperbolic function     3
 102 y0      j0.3m   bessel function ???
 103 y1      j0.3m   bessel function ???
 104 yn      j0.3m   bessel function ???
 105 .ta
 106 .fi
 107 .SH NOTES
 108 In 4.3 BSD, distributed from the University of California
 109 in late 1985, most of the foregoing functions come in two
 110 versions, one for the double\-precision "D" format in the
 111 DEC VAX\-11 family of computers, another for double\-precision
 112 arithmetic conforming to the IEEE Standard 754 for Binary
 113 Floating\-Point Arithmetic.  The two versions behave very
 114 similarly, as should be expected from programs more accurate
 115 and robust than was the norm when UNIX was born.  For
 116 instance, the programs are accurate to within the numbers
 117 of \*(ups tabulated above; an \*(up is one \fIU\fRnit in the \fIL\fRast
 118 \fIP\fRlace.  And the programs have been cured of anomalies that
 119 afflicted the older math library \fIlibm\fR in which incidents like
 120 the following had been reported:
 121 .RS
 122 sqrt(\-1.0) = 0.0 and log(\-1.0) = \-1.7e38.
 123 .br
 124 cos(1.0e\-11) > cos(0.0) > 1.0.
 125 .br
 126 pow(x,1.0)
 127 .if n \
 128 !=
 129 .if t \
 130 \(!=
 131 x when x = 2.0, 3.0, 4.0, ..., 9.0.
 132 .br
 133 pow(\-1.0,1.0e10) trapped on Integer Overflow.
 134 .br
 135 sqrt(1.0e30) and sqrt(1.0e\-30) were very slow.
 136 .RE
 137 However the two versions do differ in ways that have to be
 138 explained, to which end the following notes are provided.
 139 .PP
 140 \fBDEC VAX\-11 D_floating\-point:\fR
 141 .PP
 142 This is the format for which the original math library \fIlibm\fR
 143 was developed, and to which this manual is still principally
 144 dedicated.  It is \fIthe\fR double\-precision format for the PDP\-11
 145 and the earlier VAX\-11 machines; VAX\-11s after 1983 were
 146 provided with an optional "G" format closer to the IEEE
 147 double\-precision format.  The earlier DEC MicroVAXs have no
 148 D format, only G double\-precision.
 149 (Why?  Why not?)
 150 .PP
 151 Properties of D_floating\-point:
 152 .RS
 153 Wordsize: 64 bits, 8 bytes.  Radix: Binary.
 154 .br
 155 Precision: 56
 156 .if n \
 157 sig.
 158 .if t \
 159 significant
 160 bits, roughly like 17
 161 .if n \
 162 sig.
 163 .if t \
 164 significant
 165 decimals.
 166 .RS
 167 If x and x' are consecutive positive D_floating\-point
 168 numbers (they differ by 1 \*(up), then
 169 .br
 170 1.3e\-17 < 0.5**56 < (x'\-x)/x \(<= 0.5**55 < 2.8e\-17.
 171 .RE
 172 .nf
 173 .ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**127'u+1n
 174 Range:  Overflow threshold      = 2.0**127      = 1.7e38.
 175         Underflow threshold     = 0.5**128      = 2.9e\-39.
 176         NOTE:  THIS RANGE IS COMPARATIVELY NARROW.
 177 .ta
 178 .fi
 179 .RS
 180 Overflow customarily stops computation.
 181 .br
 182 Underflow is customarily flushed quietly to zero.
 183 .br
 184 CAUTION:
 185 .RS
 186 It is possible to have x
 187 .if n \
 188 !=
 189 .if t \
 190 \(!=
 191 y and yet
 192 x\-y = 0 because of underflow.  Similarly
 193 x > y > 0 cannot prevent either x\(**y = 0
 194 or  y/x = 0 from happening without warning.
 195 .RE
 196 .RE
 197 Zero is represented ambiguously.
 198 .RS
 199 Although 2**55 different representations of zero are accepted by
 200 the hardware, only the obvious representation is ever produced.
 201 There is no \-0 on a VAX.
 202 .RE
 203 .If
 204 is not part of the VAX architecture.
 205 .br
 206 Reserved operands:
 207 .RS
 208 of the 2**55 that the hardware
 209 recognizes, only one of them is ever produced.
 210 Any floating\-point operation upon a reserved
 211 operand, even a MOVF or MOVD, customarily stops
 212 computation, so they are not much used.
 213 .RE
 214 Exceptions:
 215 .RS
 216 Divisions by zero and operations that
 217 overflow are invalid operations that customarily
 218 stop computation or, in earlier machines, produce
 219 reserved operands that will stop computation.
 220 .RE
 221 Rounding:
 222 .RS
 223 Every rational operation  (+, \-, \(**, /) on a
 224 VAX (but not necessarily on a PDP\-11), if not an
 225 over/underflow nor division by zero, is rounded to
 226 within half an \*(up, and when the rounding error is
 227 exactly half an \*(up then rounding is away from 0.
 228 .RE
 229 .RE
 230 .PP
 231 Except for its narrow range, D_floating\-point is one of the
 232 better computer arithmetics designed in the 1960's.
 233 Its properties are reflected fairly faithfully in the elementary
 234 functions for a VAX distributed in 4.3 BSD.
 235 They over/underflow only if their results have to lie out of range
 236 or very nearly so, and then they behave much as any rational
 237 arithmetic operation that over/underflowed would behave.
 238 Similarly, expressions like log(0) and atanh(1) behave
 239 like 1/0; and sqrt(\-3) and acos(3) behave like 0/0;
 240 they all produce reserved operands and/or stop computation!
 241 The situation is described in more detail in manual pages.
 242 .RS
 243 .ll -0.5i
 244 \fIThis response seems excessively punitive, so it is destined
 245 to be replaced at some time in the foreseeable future by a
 246 more flexible but still uniform scheme being developed to
 247 handle all floating\-point arithmetic exceptions neatly.
 248 .\" See infnan(3M) for the present state of affairs.\fR
 249 .ll +0.5i
 250 .RE
 251 .PP
 252 How do the functions in 4.3 BSD's new \fIlibm\fR for UNIX
 253 compare with their counterparts in DEC's VAX/VMS library?
 254 Some of the VMS functions are a little faster, some are
 255 a little more accurate, some are more puritanical about
 256 exceptions (like pow(0.0,0.0) and atan2(0.0,0.0)),
 257 and most occupy much more memory than their counterparts in
 258 \fIlibm\fR.
 259 The VMS codes interpolate in large table to achieve
 260 speed and accuracy; the \fIlibm\fR codes use tricky formulas
 261 compact enough that all of them may some day fit into a ROM.
 262 .PP
 263 More important, DEC regards the VMS codes as proprietary
 264 and guards them zealously against unauthorized use.  But the
 265 \fIlibm\fR codes in 4.3 BSD are intended for the public domain;
 266 they may be copied freely provided their provenance is always
 267 acknowledged, and provided users assist the authors in their
 268 researches by reporting experience with the codes.
 269 Therefore no user of UNIX on a machine whose arithmetic resembles
 270 VAX D_floating\-point need use anything worse than the new \fIlibm\fR.
 271 .PP
 272 \fBIEEE STANDARD 754 Floating\-Point Arithmetic:\fR
 273 .PP
 274 This standard is on its way to becoming more widely adopted
 275 than any other design for computer arithmetic.
 276 VLSI chips that conform to some version of that standard have been
 277 produced by a host of manufacturers, among them ...
 278 .nf
 279 .ta 0.5i +\w'Intel i8070, i80287'u+6n
 280         Intel i8087, i80287     National Semiconductor  32081
 281         Motorola 68881  Weitek WTL-1032, ... , -1165
 282         Zilog Z8070     Western Electric (AT&T) WE32106.
 283 .ta
 284 .fi
 285 Other implementations range from software, done thoroughly
 286 in the Apple Macintosh, through VLSI in the Hewlett\-Packard
 287 9000 series, to the ELXSI 6400 running ECL at 3 Megaflops.
 288 Several other companies have adopted the formats
 289 of IEEE 754 without, alas, adhering to the standard's way
 290 of handling rounding and exceptions like over/underflow.
 291 The DEC VAX G_floating\-point format is very similar to the IEEE
 292 754 Double format, so similar that the C programs for the
 293 IEEE versions of most of the elementary functions listed
 294 above could easily be converted to run on a MicroVAX, though
 295 nobody has volunteered to do that yet.
 296 .PP
 297 The codes in 4.3 BSD's \fIlibm\fR for machines that conform to
 298 IEEE 754 are intended primarily for the National Semi. 32081
 299 and WTL 1164/65.  To use these codes with the Intel or Zilog
 300 chips, or with the Apple Macintosh or ELXSI 6400, is to
 301 forego the use of better codes provided (perhaps freely) by
 302 those companies and designed by some of the authors of the
 303 codes above.
 304 Except for \fIatan\fR, \fIcabs\fR, \fIcbrt\fR, \fIerf\fR,
 305 \fIerfc\fR, \fIhypot\fR, \fIj0\-jn\fR, \fIlgamma\fR, \fIpow\fR
 306 and \fIy0\-yn\fR,
 307 the Motorola 68881 has all the functions in \fIlibm\fR on chip,
 308 and faster and more accurate;
 309 it, Apple, the i8087, Z8070 and WE32106 all use 64
 310 .if n \
 311 sig.
 312 .if t \
 313 significant
 314 bits.
 315 The main virtue of 4.3 BSD's
 316 \fIlibm\fR codes is that they are intended for the public domain;
 317 they may be copied freely provided their provenance is always
 318 acknowledged, and provided users assist the authors in their
 319 researches by reporting experience with the codes.
 320 Therefore no user of UNIX on a machine that conforms to
 321 IEEE 754 need use anything worse than the new \fIlibm\fR.
 322 .PP
 323 Properties of IEEE 754 Double\-Precision:
 324 .RS
 325 Wordsize: 64 bits, 8 bytes.  Radix: Binary.
 326 .br
 327 Precision: 53
 328 .if n \
 329 sig.
 330 .if t \
 331 significant
 332 bits, roughly like 16
 333 .if n \
 334 sig.
 335 .if t \
 336 significant
 337 decimals.
 338 .RS
 339 If x and x' are consecutive positive Double\-Precision
 340 numbers (they differ by 1 \*(up), then
 341 .br
 342 1.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16.
 343 .RE
 344 .nf
 345 .ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**1024'u+1n
 346 Range:  Overflow threshold      = 2.0**1024     = 1.8e308
 347         Underflow threshold     = 0.5**1022     = 2.2e\-308
 348 .ta
 349 .fi
 350 .RS
 351 Overflow goes by default to a signed
 352 .If "" .
 353 .br
 354 Underflow is \fIGradual,\fR rounding to the nearest
 355 integer multiple of 0.5**1074 = 4.9e\-324.
 356 .RE
 357 Zero is represented ambiguously as +0 or \-0.
 358 .RS
 359 Its sign transforms correctly through multiplication or
 360 division, and is preserved by addition of zeros
 361 with like signs; but x\-x yields +0 for every
 362 finite x.  The only operations that reveal zero's
 363 sign are division by zero and copysign(x,\(+-0).
 364 In particular, comparison (x > y, x \(>= y, etc.)
 365 cannot be affected by the sign of zero; but if
 366 finite x = y then
 367 .If
 368 \&= 1/(x\-y)
 369 .if n \
 370 !=
 371 .if t \
 372 \(!=
 373 \-1/(y\-x) =
 374 .If \- .
 375 .RE
 376 .If
 377 is signed.
 378 .RS
 379 it persists when added to itself
 380 or to any finite number.  Its sign transforms
 381 correctly through multiplication and division, and
 382 .If (finite)/\(+- \0=\0\(+-0
 383 (nonzero)/0 =
 384 .If \(+- .
 385 But
 386 .if n \
 387 Infinity\-Infinity, Infinity\(**0 and Infinity/Infinity
 388 .if t \
 389 \(if\-\(if, \(if\(**0 and \(if/\(if
 390 are, like 0/0 and sqrt(\-3),
 391 invalid operations that produce \*(nn. ...
 392 .RE
 393 Reserved operands:
 394 .RS
 395 there are 2**53\-2 of them, all
 396 called \*(nn (\fIN\fRot \fIa N\fRumber).
 397 Some, called Signaling \*(nns, trap any floating\-point operation
 398 performed upon them; they are used to mark missing
 399 or uninitialized values, or nonexistent elements
 400 of arrays.  The rest are Quiet \*(nns; they are
 401 the default results of Invalid Operations, and
 402 propagate through subsequent arithmetic operations.
 403 If x
 404 .if n \
 405 !=
 406 .if t \
 407 \(!=
 408 x then x is \*(nn; every other predicate
 409 (x > y, x = y, x < y, ...) is FALSE if \*(nn is involved.
 410 .br
 411 NOTE: Trichotomy is violated by \*(nn.
 412 .RS
 413 Besides being FALSE, predicates that entail ordered
 414 comparison, rather than mere (in)equality,
 415 signal Invalid Operation when \*(nn is involved.
 416 .RE
 417 .RE
 418 Rounding:
 419 .RS
 420 Every algebraic operation (+, \-, \(**, /,
 421 .if n \
 422 sqrt)
 423 .if t \
 424 \(sr)
 425 is rounded by default to within half an \*(up, and
 426 when the rounding error is exactly half an \*(up then
 427 the rounded value's least significant bit is zero.
 428 This kind of rounding is usually the best kind,
 429 sometimes provably so; for instance, for every
 430 x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find
 431 (x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ...
 432 despite that both the quotients and the products
 433 have been rounded.  Only rounding like IEEE 754
 434 can do that.  But no single kind of rounding can be
 435 proved best for every circumstance, so IEEE 754
 436 provides rounding towards zero or towards
 437 .If +
 438 or towards
 439 .If \-
 440 at the programmer's option.  And the
 441 same kinds of rounding are specified for
 442 Binary\-Decimal Conversions, at least for magnitudes
 443 between roughly 1.0e\-10 and 1.0e37.
 444 .RE
 445 Exceptions:
 446 .RS
 447 IEEE 754 recognizes five kinds of floating\-point exceptions,
 448 listed below in declining order of probable importance.
 449 .RS
 450 .nf
 451 .ta \w'Invalid Operation'u+6n +\w'Gradual Underflow'u+2n
 452 Exception       Default Result
 453 .tc \(ru
 454
 455 .tc
 456 Invalid Operation       \*(nn, or FALSE
 457 .if n \{\
 458 Overflow        \(+-Infinity
 459 Divide by Zero  \(+-Infinity \}
 460 .if t \{\
 461 Overflow        \(+-\(if
 462 Divide by Zero  \(+-\(if \}
 463 Underflow       Gradual Underflow
 464 Inexact Rounded value
 465 .ta
 466 .fi
 467 .RE
 468 NOTE:  An Exception is not an Error unless handled
 469 badly.  What makes a class of exceptions exceptional
 470 is that no single default response can be satisfactory
 471 in every instance.  On the other hand, if a default
 472 response will serve most instances satisfactorily,
 473 the unsatisfactory instances cannot justify aborting
 474 computation every time the exception occurs.
 475 .RE
 476 .PP
 477 For each kind of floating\-point exception, IEEE 754
 478 provides a Flag that is raised each time its exception
 479 is signaled, and stays raised until the program resets
 480 it.  Programs may also test, save and restore a flag.
 481 Thus, IEEE 754 provides three ways by which programs
 482 may cope with exceptions for which the default result
 483 might be unsatisfactory:
 484 .IP 1) \w'\0\0\0\0'u
 485 Test for a condition that might cause an exception
 486 later, and branch to avoid the exception.
 487 .IP 2) \w'\0\0\0\0'u
 488 Test a flag to see whether an exception has occurred
 489 since the program last reset its flag.
 490 .IP 3) \w'\0\0\0\0'u
 491 Test a result to see whether it is a value that only
 492 an exception could have produced.
 493 .RS
 494 CAUTION: The only reliable ways to discover
 495 whether Underflow has occurred are to test whether
 496 products or quotients lie closer to zero than the
 497 underflow threshold, or to test the Underflow
 498 flag.  (Sums and differences cannot underflow in
 499 IEEE 754; if x
 500 .if n \
 501 !=
 502 .if t \
 503 \(!=
 504 y then x\-y is correct to
 505 full precision and certainly nonzero regardless of
 506 how tiny it may be.)  Products and quotients that
 507 underflow gradually can lose accuracy gradually
 508 without vanishing, so comparing them with zero
 509 (as one might on a VAX) will not reveal the loss.
 510 Fortunately, if a gradually underflowed value is
 511 destined to be added to something bigger than the
 512 underflow threshold, as is almost always the case,
 513 digits lost to gradual underflow will not be missed
 514 because they would have been rounded off anyway.
 515 So gradual underflows are usually \fIprovably\fR ignorable.
 516 The same cannot be said of underflows flushed to 0.
 517 .RE
 518 .PP
 519 At the option of an implementor conforming to IEEE 754,
 520 other ways to cope with exceptions may be provided:
 521 .IP 4) \w'\0\0\0\0'u
 522 ABORT.  This mechanism classifies an exception in
 523 advance as an incident to be handled by means
 524 traditionally associated with error\-handling
 525 statements like "ON ERROR GO TO ...".  Different
 526 languages offer different forms of this statement,
 527 but most share the following characteristics:
 528 .IP \(em \w'\0\0\0\0'u
 529 No means is provided to substitute a value for
 530 the offending operation's result and resume
 531 computation from what may be the middle of an
 532 expression.  An exceptional result is abandoned.
 533 .IP \(em \w'\0\0\0\0'u
 534 In a subprogram that lacks an error\-handling
 535 statement, an exception causes the subprogram to
 536 abort within whatever program called it, and so
 537 on back up the chain of calling subprograms until
 538 an error\-handling statement is encountered or the
 539 whole task is aborted and memory is dumped.
 540 .IP 5) \w'\0\0\0\0'u
 541 STOP.  This mechanism, requiring an interactive
 542 debugging environment, is more for the programmer
 543 than the program.  It classifies an exception in
 544 advance as a symptom of a programmer's error; the
 545 exception suspends execution as near as it can to
 546 the offending operation so that the programmer can
 547 look around to see how it happened.  Quite often
 548 the first several exceptions turn out to be quite
 549 unexceptionable, so the programmer ought ideally
 550 to be able to resume execution after each one as if
 551 execution had not been stopped.
 552 .IP 6) \w'\0\0\0\0'u
 553 \&... Other ways lie beyond the scope of this document.
 554 .RE
 555 .PP
 556 The crucial problem for exception handling is the problem of
 557 Scope, and the problem's solution is understood, but not
 558 enough manpower was available to implement it fully in time
 559 to be distributed in 4.3 BSD's \fIlibm\fR.  Ideally, each
 560 elementary function should act as if it were indivisible, or
 561 atomic, in the sense that ...
 562 .IP i) \w'iii)'u+2n
 563 No exception should be signaled that is not deserved by
 564 the data supplied to that function.
 565 .IP ii) \w'iii)'u+2n
 566 Any exception signaled should be identified with that
 567 function rather than with one of its subroutines.
 568 .IP iii) \w'iii)'u+2n
 569 The internal behavior of an atomic function should not
 570 be disrupted when a calling program changes from
 571 one to another of the five or so ways of handling
 572 exceptions listed above, although the definition
 573 of the function may be correlated intentionally
 574 with exception handling.
 575 .PP
 576 Ideally, every programmer should be able \fIconveniently\fR to
 577 turn a debugged subprogram into one that appears atomic to
 578 its users.  But simulating all three characteristics of an
 579 atomic function is still a tedious affair, entailing hosts
 580 of tests and saves\-restores; work is under way to ameliorate
 581 the inconvenience.
 582 .PP
 583 Meanwhile, the functions in \fIlibm\fR are only approximately
 584 atomic.  They signal no inappropriate exception except
 585 possibly ...
 586 .RS
 587 Over/Underflow
 588 .RS
 589 when a result, if properly computed, might have lain barely within range, and
 590 .RE
 591 Inexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR
 592 .RS
 593 when it happens to be exact, thanks to fortuitous cancellation of errors.
 594 .RE
 595 .RE
 596 Otherwise, ...
 597 .RS
 598 Invalid Operation is signaled only when
 599 .RS
 600 any result but \*(nn would probably be misleading.
 601 .RE
 602 Overflow is signaled only when
 603 .RS
 604 the exact result would be finite but beyond the overflow threshold.
 605 .RE
 606 Divide\-by\-Zero is signaled only when
 607 .RS
 608 a function takes exactly infinite values at finite operands.
 609 .RE
 610 Underflow is signaled only when
 611 .RS
 612 the exact result would be nonzero but tinier than the underflow threshold.
 613 .RE
 614 Inexact is signaled only when
 615 .RS
 616 greater range or precision would be needed to represent the exact result.
 617 .RE
 618 .RE
 619 .SH BUGS
 620 When signals are appropriate, they are emitted by certain
 621 operations within the codes, so a subroutine\-trace may be
 622 needed to identify the function with its signal in case
 623 method 5) above is in use.  And the codes all take the
 624 IEEE 754 defaults for granted; this means that a decision to
 625 trap all divisions by zero could disrupt a code that would
 626 otherwise get correct results despite division by zero.
 627 .SH SEE ALSO
 628 \fBfpgetround\fR(3),
 629 \fBfpsetround\fR(3),
 630 \fBfpgetprec\fR(3),
 631 \fBfpsetprec\fR(3),
 632 \fBfpgetmask\fR(3),
 633 \fBfpsetmask\fR(3),
 634 \fBfpgetsticky\fR(3),
 635 \fBfpresetsticky\fR(3) - IEEE floating point interface
 636 .SH NOTES
 637 An explanation of IEEE 754 and its proposed extension p854
 638 was published in the IEEE magazine MICRO in August 1984 under
 639 the title "A Proposed Radix\- and Word\-length\-independent
 640 Standard for Floating\-point Arithmetic" by W. J. Cody et al.
 641 The manuals for Pascal, C and BASIC on the Apple Macintosh
 642 document the features of IEEE 754 pretty well.
 643 Articles in the IEEE magazine COMPUTER vol. 14 no. 3 (Mar.
 644 1981), and in the ACM SIGNUM Newsletter Special Issue of
 645 Oct. 1979, may be helpful although they pertain to
 646 superseded drafts of the standard.