xref: /freebsd/lib/msun/man/math.3 (revision 6fd05b64b5b65dd4ba9b86482a0634a5f0b96c29)
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$
34.\"
35.Dd June 11, 2004
36.Dt MATH 3
37.Os
38.ds up \fIulp\fR
39.de If
40.if n \\
41\\$1Infinity\\$2
42.if t \\
43\\$1\\(if\\$2
44..
45.Sh NAME
46math \- introduction to mathematical library functions
47.Sh DESCRIPTION
48These functions constitute the C math library,
49.I libm.
50The link editor searches this library under the \*(lq\-lm\*(rq option.
51Declarations for these functions may be obtained from the include file
52.In math.h .
53.Sh "LIST OF FUNCTIONS"
54Each of the following
55.Vt double
56functions has a
57.Vt float
58counterpart with an
59.Ql f
60appended to the name and a
61.Vt long double
62counterpart with an
63.Ql l
64appended.
65As an example, the
66.Vt float
67and
68.Vt long double
69counterparts of
70.Ft double
71.Fn acos "double x"
72are
73.Ft float
74.Fn acosf "float x"
75and
76.Ft long double
77.Fn acosl "long double x" ,
78respectively.
79.sp 2
80.nf
81.ta \w'nexttoward'u+10n +\w'remainder with partial quot'u
82\fIName\fP	\fIDescription\fP	\fIError Bound (ULPs)\fP
83.ta \w'nexttoward'u+4n +\w'remainder with partial quotient'u+6nC
84.sp 5p
85.\" XXX Many of these error bounds are wrong for the current implementation!
86acos	inverse trigonometric function	3
87acosh	inverse hyperbolic function	3
88asin	inverse trigonometric function	3
89asinh	inverse hyperbolic function	3
90atan	inverse trigonometric function	1
91atanh	inverse hyperbolic function	3
92atan2	inverse trigonometric function	2
93cbrt	cube root	1
94ceil	integer no less than	0
95copysign	copy sign bit	0
96cos	trigonometric function	1
97cosh	hyperbolic function	3
98erf	error function	???
99erfc	complementary error function	???
100exp	exponential base e	1
101.\" exp2	exponential base 2	???
102expm1	exp(x)\-1	1
103fabs	absolute value	0
104.\" fdim	positive difference	???
105floor	integer no greater than	0
106.\" fma	multiply-add	???
107.\" fmax	maximum function	0
108.\" fmin	minimum function	0
109fmod	remainder function	???
110frexp	extract mantissa and exponent	0
111hypot	Euclidean distance	1
112ilogb	exponent extraction	0
113j0	bessel function	???
114j1	bessel function	???
115jn	bessel function	???
116ldexp	multiply by power of 2	0
117lgamma	log gamma function	???
118.\" llrint	round to integer	0
119.\" llround	round to nearest integer	0
120log	natural logarithm	1
121log10	logarithm to base 10	3
122log1p	log(1+x)	1
123.\" log2	base 2 logarithm	0
124logb	exponent extraction	0
125.\" lrint	round to integer	0
126.\" lround	round to nearest integer	0
127modf	extract fractional part	???
128.\" nan	return quiet \*(Na)	0
129.\" nearbyint	round to integer	0
130nextafter	next representable value	0
131.\" nexttoward	next representable value	0
132pow	exponential x**y	60\-500
133remainder	remainder	0
134.\" remquo	remainder with partial quotient	???
135rint	round to nearest integer	0
136round	round to nearest integer	0
137scalbln	exponent adjustment	0
138scalbn	exponent adjustment	0
139sin	trigonometric function	1
140sinh	hyperbolic function	3
141sqrt	square root	1
142tan	trigonometric function	3
143tanh	hyperbolic function	3
144tgamma	gamma function	???
145trunc	round towards zero	0
146y0	bessel function	???
147y1	bessel function	???
148yn	bessel function	???
149.ta
150.fi
151.Sh NOTES
152Virtually all modern floating-point units attempt to support
153IEEE Standard 754 for Binary Floating-Point Arithmetic.
154This standard does not cover particular routines in the math library
155except for the few documented in
156.Xr ieee 3 ;
157it primarily defines representations of numbers and abstract
158properties of arithmetic operations relating to precision, rounding,
159and exceptional cases, as described below.
160The programs are accurate to within the numbers
161of \*(ups tabulated above; an \*(up is one \fIU\fRnit in the \fIL\fRast
162\fIP\fRlace.
163.Pp
164\fBIEEE STANDARD 754 Floating\-Point Arithmetic:\fR
165.Pp
166Properties of IEEE 754 Double\-Precision:
167.Bd -filled -offset indent
168Wordsize: 64 bits, 8 bytes.  Radix: Binary.
169.br
170Precision: 53
171.if n \
172sig.
173.if t \
174significant
175bits, roughly like 16
176.if n \
177sig.
178.if t \
179significant
180decimals.
181.Bd -filled -offset indent -compact
182If x and x' are consecutive positive Double\-Precision
183numbers (they differ by 1 \*(up), then
184.br
1851.1e\-16 < 0.5**53 < (x'\-x)/x \(<= 0.5**52 < 2.3e\-16.
186.Ed
187.nf
188.ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**1024'u+1n
189Range:	Overflow threshold	= 2.0**1024	= 1.8e308
190	Underflow threshold	= 0.5**1022	= 2.2e\-308
191.ta
192.fi
193.Bd -filled -offset indent -compact
194Overflow goes by default to a signed
195.If "" .
196.br
197Underflow is \fIGradual,\fR rounding to the nearest
198integer multiple of 0.5**1074 = 4.9e\-324.
199.Ed
200Zero is represented ambiguously as +0 or \-0.
201.Bd -filled -offset indent -compact
202Its sign transforms correctly through multiplication or
203division, and is preserved by addition of zeros
204with like signs; but x\-x yields +0 for every
205finite x.  The only operations that reveal zero's
206sign are division by zero and copysign(x,\(+-0).
207In particular, comparison (x > y, x \(>= y, etc.)
208cannot be affected by the sign of zero; but if
209finite x = y then
210.If
211\&= 1/(x\-y)
212.if n \
213!=
214.if t \
215\(!=
216\-1/(y\-x) =
217.If \- .
218.Ed
219.If
220is signed.
221.Bd -filled -offset indent -compact
222it persists when added to itself
223or to any finite number.  Its sign transforms
224correctly through multiplication and division, and
225.If (finite)/\(+- \0=\0\(+-0
226(nonzero)/0 =
227.If \(+- .
228But
229.if n \
230Infinity\-Infinity, Infinity\(**0 and Infinity/Infinity
231.if t \
232\(if\-\(if, \(if\(**0 and \(if/\(if
233are, like 0/0 and sqrt(\-3),
234invalid operations that produce \*(Na. ...
235.Ed
236Reserved operands:
237.Bd -filled -offset indent -compact
238there are 2**53\-2 of them, all
239called \*(Na (\fIN\fRot \fIa N\fRumber).
240Some, called Signaling \*(Nas, trap any floating\-point operation
241performed upon them; they are used to mark missing
242or uninitialized values, or nonexistent elements
243of arrays.  The rest are Quiet \*(Nas; they are
244the default results of Invalid Operations, and
245propagate through subsequent arithmetic operations.
246If x
247.if n \
248!=
249.if t \
250\(!=
251x then x is \*(Na; every other predicate
252(x > y, x = y, x < y, ...) is FALSE if \*(Na is involved.
253.br
254NOTE: Trichotomy is violated by \*(Na.
255.Bd -filled -offset indent -compact
256Besides being FALSE, predicates that entail ordered
257comparison, rather than mere (in)equality,
258signal Invalid Operation when \*(Na is involved.
259.Ed
260.Ed
261Rounding:
262.Bd -filled -offset indent -compact
263Every algebraic operation (+, \-, \(**, /,
264.if n \
265sqrt)
266.if t \
267\(sr)
268is rounded by default to within half an \*(up, and
269when the rounding error is exactly half an \*(up then
270the rounded value's least significant bit is zero.
271This kind of rounding is usually the best kind,
272sometimes provably so; for instance, for every
273x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find
274(x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ...
275despite that both the quotients and the products
276have been rounded.  Only rounding like IEEE 754
277can do that.  But no single kind of rounding can be
278proved best for every circumstance, so IEEE 754
279provides rounding towards zero or towards
280.If +
281or towards
282.If \-
283at the programmer's option.  And the
284same kinds of rounding are specified for
285Binary\-Decimal Conversions, at least for magnitudes
286between roughly 1.0e\-10 and 1.0e37.
287.Ed
288Exceptions:
289.Bd -filled -offset indent -compact
290IEEE 754 recognizes five kinds of floating\-point exceptions,
291listed below in declining order of probable importance.
292.Bd -filled -offset indent -compact
293.nf
294.ta \w'Invalid Operation'u+6n +\w'Gradual Underflow'u+2n
295Exception	Default Result
296.tc \(ru
297
298.tc
299Invalid Operation	\*(Na, or FALSE
300.if n \{\
301Overflow	\(+-Infinity
302Divide by Zero	\(+-Infinity \}
303.if t \{\
304Overflow	\(+-\(if
305Divide by Zero	\(+-\(if \}
306Underflow	Gradual Underflow
307Inexact	Rounded value
308.ta
309.fi
310.Ed
311NOTE:  An Exception is not an Error unless handled
312badly.  What makes a class of exceptions exceptional
313is that no single default response can be satisfactory
314in every instance.  On the other hand, if a default
315response will serve most instances satisfactorily,
316the unsatisfactory instances cannot justify aborting
317computation every time the exception occurs.
318.Ed
319.Pp
320For each kind of floating\-point exception, IEEE 754
321provides a Flag that is raised each time its exception
322is signaled, and stays raised until the program resets
323it.  Programs may also test, save and restore a flag.
324Thus, IEEE 754 provides three ways by which programs
325may cope with exceptions for which the default result
326might be unsatisfactory:
327.Bl -enum
328.It
329Test for a condition that might cause an exception
330later, and branch to avoid the exception.
331.It
332Test a flag to see whether an exception has occurred
333since the program last reset its flag.
334.It
335Test a result to see whether it is a value that only
336an exception could have produced.
337.RS
338CAUTION: The only reliable ways to discover
339whether Underflow has occurred are to test whether
340products or quotients lie closer to zero than the
341underflow threshold, or to test the Underflow
342flag.  (Sums and differences cannot underflow in
343IEEE 754; if x
344.if n \
345!=
346.if t \
347\(!=
348y then x\-y is correct to
349full precision and certainly nonzero regardless of
350how tiny it may be.)  Products and quotients that
351underflow gradually can lose accuracy gradually
352without vanishing, so comparing them with zero
353(as one might on a VAX) will not reveal the loss.
354Fortunately, if a gradually underflowed value is
355destined to be added to something bigger than the
356underflow threshold, as is almost always the case,
357digits lost to gradual underflow will not be missed
358because they would have been rounded off anyway.
359So gradual underflows are usually \fIprovably\fR ignorable.
360The same cannot be said of underflows flushed to 0.
361.RE
362.El
363.Pp
364At the option of an implementor conforming to IEEE 754,
365other ways to cope with exceptions may be provided:
366.Bl -hang -width 3n
367.It 4.
368ABORT.  This mechanism classifies an exception in
369advance as an incident to be handled by means
370traditionally associated with error\-handling
371statements like "ON ERROR GO TO ...".  Different
372languages offer different forms of this statement,
373but most share the following characteristics:
374.Bl -dash
375.It
376No means is provided to substitute a value for
377the offending operation's result and resume
378computation from what may be the middle of an
379expression.  An exceptional result is abandoned.
380.It
381In a subprogram that lacks an error\-handling
382statement, an exception causes the subprogram to
383abort within whatever program called it, and so
384on back up the chain of calling subprograms until
385an error\-handling statement is encountered or the
386whole task is aborted and memory is dumped.
387.El
388.It 5.
389STOP.  This mechanism, requiring an interactive
390debugging environment, is more for the programmer
391than the program.  It classifies an exception in
392advance as a symptom of a programmer's error; the
393exception suspends execution as near as it can to
394the offending operation so that the programmer can
395look around to see how it happened.  Quite often
396the first several exceptions turn out to be quite
397unexceptionable, so the programmer ought ideally
398to be able to resume execution after each one as if
399execution had not been stopped.
400.It 6.
401\&... Other ways lie beyond the scope of this document.
402.El
403.Ed
404.Pp
405Ideally, each
406elementary function should act as if it were indivisible, or
407atomic, in the sense that ...
408.Bl -tag -width "iii)"
409.It i)
410No exception should be signaled that is not deserved by
411the data supplied to that function.
412.It ii)
413Any exception signaled should be identified with that
414function rather than with one of its subroutines.
415.It iii)
416The internal behavior of an atomic function should not
417be disrupted when a calling program changes from
418one to another of the five or so ways of handling
419exceptions listed above, although the definition
420of the function may be correlated intentionally
421with exception handling.
422.El
423.Pp
424The functions in \fIlibm\fR are only approximately atomic.
425They signal no inappropriate exception except possibly ...
426.Bd -filled -offset indent -compact
427Over/Underflow
428.Bd -filled -offset indent -compact
429when a result, if properly computed, might have lain barely within range, and
430.Ed
431Inexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR
432.Bd -filled -offset indent -compact
433when it happens to be exact, thanks to fortuitous cancellation of errors.
434.Ed
435.Ed
436Otherwise, ...
437.Bd -filled -offset indent -compact
438Invalid Operation is signaled only when
439.Bd -filled -offset indent -compact
440any result but \*(Na would probably be misleading.
441.Ed
442Overflow is signaled only when
443.Bd -filled -offset indent -compact
444the exact result would be finite but beyond the overflow threshold.
445.Ed
446Divide\-by\-Zero is signaled only when
447.Bd -filled -offset indent -compact
448a function takes exactly infinite values at finite operands.
449.Ed
450Underflow is signaled only when
451.Bd -filled -offset indent -compact
452the exact result would be nonzero but tinier than the underflow threshold.
453.Ed
454Inexact is signaled only when
455.Bd -filled -offset indent -compact
456greater range or precision would be needed to represent the exact result.
457.Ed
458.Ed
459.Sh BUGS
460Several functions required by
461.St -isoC-99
462are missing, and many functions are not available in their
463.Vt long double
464variants.
465.Sh SEE ALSO
466.Xr fenv 3 ,
467.Xr ieee 3
468.Pp
469An explanation of IEEE 754 and its proposed extension p854
470was published in the IEEE magazine MICRO in August 1984 under
471the title "A Proposed Radix\- and Word\-length\-independent
472Standard for Floating\-point Arithmetic" by W. J. Cody et al.
473The manuals for Pascal, C and BASIC on the Apple Macintosh
474document the features of IEEE 754 pretty well.
475Articles in the IEEE magazine COMPUTER vol. 14 no. 3 (Mar.\&
4761981), and in the ACM SIGNUM Newsletter Special Issue of
477Oct. 1979, may be helpful although they pertain to
478superseded drafts of the standard.
479.Sh HISTORY
480A math library with many of the present functions appeared in
481Version 7 AT&T UNIX.
482The library was substantially rewritten for 4.3BSD to provide
483better accuracy and speed on machines supporting either VAX
484or IEEE 754 floating-point.
485Most of this library was replaced with FDLIBM, developed at Sun
486Microsystems, in
487.Fx 1.1.5 .
488