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