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