1 .\" Copyright (c) 1985 Regents of the University of California.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
28 .\" from: @(#)math.3 6.10 (Berkeley) 5/6/91
29 .\" $NetBSD: math.3,v 1.18 2003/12/03 23:31:21 jschauma Exp $
31 .TH MATH 3 "July 12, 2009"
42 math \- introduction to mathematical library functions
44 These functions constitute the C math library,
46 The link editor searches this library under the \*(lq\-lm\*(rq option.
47 Declarations for these functions may be obtained from the include file
48 .RI \*[Lt] math.h \*[Gt].
49 .\" The Fortran math library is described in ``man 3f intro''.
50 .SH "LIST OF FUNCTIONS"
53 .ta \w'copysign'u+2n +\w'lgamma.3'u+10n +\w'inverse trigonometric func'u
54 \fIName\fP \fIAppears on Page\fP \fIDescription\fP \fIError Bound (ULPs)\fP
55 .ta \w'copysign'u+4n +\w'lgamma.3'u+4n +\w'inverse trigonometric function'u+6nC
57 acos acos.3 inverse trigonometric function 3
58 acosh acosh.3 inverse hyperbolic function 3
59 asin asin.3 inverse trigonometric function 3
60 asinh asinh.3 inverse hyperbolic function 3
61 atan atan.3 inverse trigonometric function 1
62 atanh atanh.3 inverse hyperbolic function 3
63 atan2 atan2.3 inverse trigonometric function 2
64 cabs hypot.3 complex absolute value 1
65 cbrt sqrt.3 cube root 1
66 ceil ceil.3 integer no less than 0
67 copysign ieee.3 copy sign bit 0
68 cos cos.3 trigonometric function 1
69 cosh cosh.3 hyperbolic function 3
70 erf erf.3 error function ???
71 erfc erf.3 complementary error function ???
72 exp exp.3 exponential 1
73 expm1 exp.3 exp(x)\-1 1
74 fabs fabs.3 absolute value 0
75 fdim fdim.3 positive difference ???
76 finite ieee.3 test for finity 0
77 floor floor.3 integer no greater than 0
78 fmax fmax.3 maximum function ???
79 fmin fmin.3 minimum function ???
80 fmod fmod.3 remainder ???
81 hypot hypot.3 Euclidean distance 1
82 ilogb ieee.3 exponent extraction 0
83 isinf isinf.3 test for infinity 0
84 isnan isnan.3 test for not-a-number 0
85 j0 j0.3 Bessel function ???
86 j1 j0.3 Bessel function ???
87 jn j0.3 Bessel function ???
88 lgamma lgamma.3 log gamma function ???
89 log exp.3 natural logarithm 1
90 log10 exp.3 logarithm to base 10 3
91 log1p exp.3 log(1+x) 1
92 nan nan.3 return quiet \*(nn 0
93 nextafter ieee.3 next representable number 0
94 pow exp.3 exponential x**y 60\-500
95 remainder ieee.3 remainder 0
96 rint rint.3 round to nearest integer 0
97 scalbn ieee.3 exponent adjustment 0
98 sin sin.3 trigonometric function 1
99 sinh sinh.3 hyperbolic function 3
100 sqrt sqrt.3 square root 1
101 tan tan.3 trigonometric function 3
102 tanh tanh.3 hyperbolic function 3
103 trunc trunc.3 nearest integral value 3
104 y0 j0.3 Bessel function ???
105 y1 j0.3 Bessel function ???
106 yn j0.3 Bessel function ???
109 .SH "LIST OF DEFINED VALUES"
112 .ta \w'M_2_SQRTPI'u+2n +\w'1.12837916709551257390'u+4n +\w'2/sqrt(pi)'u+6nC
113 \fIName\fP \fIValue\fP \fIDescription\fP
114 .ta \w'M_2_SQRTPI'u+2n +\w'1.12837916709551257390'u+4n +\w'2/sqrt(pi)'u+6nC
116 M_E 2.7182818284590452354 e
117 M_LOG2E 1.4426950408889634074 log 2e
118 M_LOG10E 0.43429448190325182765 log 10e
119 M_LN2 0.69314718055994530942 log e2
120 M_LN10 2.30258509299404568402 log e10
121 M_PI 3.14159265358979323846 pi
122 M_PI_2 1.57079632679489661923 pi/2
123 M_PI_4 0.78539816339744830962 pi/4
124 M_1_PI 0.31830988618379067154 1/pi
125 M_2_PI 0.63661977236758134308 2/pi
126 M_2_SQRTPI 1.12837916709551257390 2/sqrt(pi)
127 M_SQRT2 1.41421356237309504880 sqrt(2)
128 M_SQRT1_2 0.70710678118654752440 1/sqrt(2)
132 In 4.3 BSD, distributed from the University of California
133 in late 1985, most of the foregoing functions come in two
134 versions, one for the double\-precision "D" format in the
135 DEC VAX\-11 family of computers, another for double\-precision
136 arithmetic conforming to the IEEE Standard 754 for Binary
137 Floating\-Point Arithmetic.
138 The two versions behave very
139 similarly, as should be expected from programs more accurate
140 and robust than was the norm when UNIX was born.
141 For instance, the programs are accurate to within the numbers
142 of \*(ups tabulated above; an \*(up is one \fIU\fRnit in the \fIL\fRast
144 And the programs have been cured of anomalies that
145 afflicted the older math library \fIlibm\fR in which incidents like
146 the following had been reported:
148 sqrt(\-1.0) = 0.0 and log(\-1.0) = \-1.7e38.
150 cos(1.0e\-11) \*[Gt] cos(0.0) \*[Gt] 1.0.
157 x when x = 2.0, 3.0, 4.0, ..., 9.0.
159 pow(\-1.0,1.0e10) trapped on Integer Overflow.
161 sqrt(1.0e30) and sqrt(1.0e\-30) were very slow.
163 However the two versions do differ in ways that have to be
164 explained, to which end the following notes are provided.
166 \fBDEC VAX\-11 D_floating\-point:\fR
168 This is the format for which the original math library \fIlibm\fR
169 was developed, and to which this manual is still principally dedicated.
170 It is \fIthe\fR double\-precision format for the PDP\-11
171 and the earlier VAX\-11 machines; VAX\-11s after 1983 were
172 provided with an optional "G" format closer to the IEEE
173 double\-precision format.
174 The earlier DEC MicroVAXs have no D format, only G double\-precision.
178 Properties of D_floating\-point:
180 Wordsize: 64 bits, 8 bytes.
188 bits, roughly like 17
195 If x and x' are consecutive positive D_floating\-point
196 numbers (they differ by 1 \*(up), then
198 1.3e\-17 \*[Lt] 0.5**56 \*[Lt] (x'\-x)/x \*[Le] 0.5**55 \*[Lt] 2.8e\-17.
201 .ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**127'u+1n
202 Range: Overflow threshold = 2.0**127 = 1.7e38.
203 Underflow threshold = 0.5**128 = 2.9e\-39.
204 NOTE: THIS RANGE IS COMPARATIVELY NARROW.
208 Overflow customarily stops computation.
210 Underflow is customarily flushed quietly to zero.
214 It is possible to have x
220 x\-y = 0 because of underflow.
221 Similarly x \*[Gt] y \*[Gt] 0 cannot prevent either x\(**y = 0
222 or y/x = 0 from happening without warning.
225 Zero is represented ambiguously.
227 Although 2**55 different representations of zero are accepted by
228 the hardware, only the obvious representation is ever produced.
229 There is no \-0 on a VAX.
232 is not part of the VAX architecture.
236 of the 2**55 that the hardware
237 recognizes, only one of them is ever produced.
238 Any floating\-point operation upon a reserved
239 operand, even a MOVF or MOVD, customarily stops
240 computation, so they are not much used.
244 Divisions by zero and operations that
245 overflow are invalid operations that customarily
246 stop computation or, in earlier machines, produce
247 reserved operands that will stop computation.
251 Every rational operation (+, \-, \(**, /) on a
252 VAX (but not necessarily on a PDP\-11), if not an
253 over/underflow nor division by zero, is rounded to
254 within half an \*(up, and when the rounding error is
255 exactly half an \*(up then rounding is away from 0.
259 Except for its narrow range, D_floating\-point is one of the
260 better computer arithmetics designed in the 1960's.
261 Its properties are reflected fairly faithfully in the elementary
262 functions for a VAX distributed in 4.3 BSD.
263 They over/underflow only if their results have to lie out of range
264 or very nearly so, and then they behave much as any rational
265 arithmetic operation that over/underflowed would behave.
266 Similarly, expressions like log(0) and atanh(1) behave
267 like 1/0; and sqrt(\-3) and acos(3) behave like 0/0;
268 they all produce reserved operands and/or stop computation!
269 The situation is described in more detail in manual pages.
272 \fIThis response seems excessively punitive, so it is destined
273 to be replaced at some time in the foreseeable future by a
274 more flexible but still uniform scheme being developed to
275 handle all floating\-point arithmetic exceptions neatly.\fR
279 How do the functions in 4.3 BSD's new \fIlibm\fR for UNIX
280 compare with their counterparts in DEC's VAX/VMS library?
281 Some of the VMS functions are a little faster, some are
282 a little more accurate, some are more puritanical about
283 exceptions (like pow(0.0,0.0) and atan2(0.0,0.0)),
284 and most occupy much more memory than their counterparts in
286 The VMS codes interpolate in large table to achieve
287 speed and accuracy; the \fIlibm\fR codes use tricky formulas
288 compact enough that all of them may some day fit into a ROM.
290 More important, DEC regards the VMS codes as proprietary
291 and guards them zealously against unauthorized use.
292 But the \fIlibm\fR codes in 4.3 BSD are intended for the public domain;
293 they may be copied freely provided their provenance is always
294 acknowledged, and provided users assist the authors in their
295 researches by reporting experience with the codes.
296 Therefore no user of UNIX on a machine whose arithmetic resembles
297 VAX D_floating\-point need use anything worse than the new \fIlibm\fR.
299 \fBIEEE STANDARD 754 Floating\-Point Arithmetic:\fR
301 This standard is on its way to becoming more widely adopted
302 than any other design for computer arithmetic.
303 VLSI chips that conform to some version of that standard have been
304 produced by a host of manufacturers, among them ...
306 .ta 0.5i +\w'Intel i8070, i80287'u+6n
307 Intel i8087, i80287 National Semiconductor 32081
308 Motorola 68881 Weitek WTL-1032, ... , -1165
309 Zilog Z8070 Western Electric (AT\*[Am]T) WE32106.
312 Other implementations range from software, done thoroughly
313 in the Apple Macintosh, through VLSI in the Hewlett\-Packard
314 9000 series, to the ELXSI 6400 running ECL at 3 Megaflops.
315 Several other companies have adopted the formats
316 of IEEE 754 without, alas, adhering to the standard's way
317 of handling rounding and exceptions like over/underflow.
318 The DEC VAX G_floating\-point format is very similar to the IEEE
319 754 Double format, so similar that the C programs for the
320 IEEE versions of most of the elementary functions listed
321 above could easily be converted to run on a MicroVAX, though
322 nobody has volunteered to do that yet.
324 The codes in 4.3 BSD's \fIlibm\fR for machines that conform to
325 IEEE 754 are intended primarily for the National Semi. 32081
327 To use these codes with the Intel or Zilog
328 chips, or with the Apple Macintosh or ELXSI 6400, is to
329 forego the use of better codes provided (perhaps freely) by
330 those companies and designed by some of the authors of the
332 Except for \fIatan\fR, \fIcabs\fR, \fIcbrt\fR, \fIerf\fR,
333 \fIerfc\fR, \fIhypot\fR, \fIj0\-jn\fR, \fIlgamma\fR, \fIpow\fR
335 the Motorola 68881 has all the functions in \fIlibm\fR on chip,
336 and faster and more accurate;
337 it, Apple, the i8087, Z8070 and WE32106 all use 64
343 The main virtue of 4.3 BSD's
344 \fIlibm\fR codes is that they are intended for the public domain;
345 they may be copied freely provided their provenance is always
346 acknowledged, and provided users assist the authors in their
347 researches by reporting experience with the codes.
348 Therefore no user of UNIX on a machine that conforms to
349 IEEE 754 need use anything worse than the new \fIlibm\fR.
351 Properties of IEEE 754 Double\-Precision:
353 Wordsize: 64 bits, 8 bytes.
361 bits, roughly like 16
368 If x and x' are consecutive positive Double\-Precision
369 numbers (they differ by 1 \*(up), then
371 1.1e\-16 \*[Lt] 0.5**53 \*[Lt] (x'\-x)/x \*[Le] 0.5**52 \*[Lt] 2.3e\-16.
374 .ta \w'Range:'u+1n +\w'Underflow threshold'u+1n +\w'= 2.0**1024'u+1n
375 Range: Overflow threshold = 2.0**1024 = 1.8e308
376 Underflow threshold = 0.5**1022 = 2.2e\-308
380 Overflow goes by default to a signed
383 Underflow is \fIGradual,\fR rounding to the nearest
384 integer multiple of 0.5**1074 = 4.9e\-324.
386 Zero is represented ambiguously as +0 or \-0.
388 Its sign transforms correctly through multiplication or
389 division, and is preserved by addition of zeros
390 with like signs; but x\-x yields +0 for every
392 The only operations that reveal zero's
393 sign are division by zero and copysign(x,\(+-0).
394 In particular, comparison (x \*[Gt] y, x \*[Ge] y, etc.)
395 cannot be affected by the sign of zero; but if
409 it persists when added to itself
410 or to any finite number.
412 correctly through multiplication and division, and
413 .If (finite)/\(+- \0=\0\(+-0
418 Infinity\-Infinity, Infinity\(**0 and Infinity/Infinity
420 \(if\-\(if, \(if\(**0 and \(if/\(if
421 are, like 0/0 and sqrt(\-3),
422 invalid operations that produce \*(nn. ...
426 there are 2**53\-2 of them, all
427 called \*(nn (\fIN\fRot \fIa N\fRumber).
428 Some, called Signaling \*(nns, trap any floating\-point operation
429 performed upon them; they are used to mark missing
430 or uninitialized values, or nonexistent elements of arrays.
431 The rest are Quiet \*(nns; they are
432 the default results of Invalid Operations, and
433 propagate through subsequent arithmetic operations.
439 x then x is \*(nn; every other predicate
440 (x \*[Gt] y, x = y, x \*[Lt] y, ...) is FALSE if \*(nn is involved.
442 NOTE: Trichotomy is violated by \*(nn.
444 Besides being FALSE, predicates that entail ordered
445 comparison, rather than mere (in)equality,
446 signal Invalid Operation when \*(nn is involved.
451 Every algebraic operation (+, \-, \(**, /,
456 is rounded by default to within half an \*(up, and
457 when the rounding error is exactly half an \*(up then
458 the rounded value's least significant bit is zero.
459 This kind of rounding is usually the best kind,
460 sometimes provably so; for instance, for every
461 x = 1.0, 2.0, 3.0, 4.0, ..., 2.0**52, we find
462 (x/3.0)\(**3.0 == x and (x/10.0)\(**10.0 == x and ...
463 despite that both the quotients and the products
465 Only rounding like IEEE 754 can do that.
466 But no single kind of rounding can be
467 proved best for every circumstance, so IEEE 754
468 provides rounding towards zero or towards
472 at the programmer's option.
473 And the same kinds of rounding are specified for
474 Binary\-Decimal Conversions, at least for magnitudes
475 between roughly 1.0e\-10 and 1.0e37.
479 IEEE 754 recognizes five kinds of floating\-point exceptions,
480 listed below in declining order of probable importance.
483 .ta \w'Invalid Operation'u+6n +\w'Gradual Underflow'u+2n
484 Exception Default Result
488 Invalid Operation \*(nn, or FALSE
490 Overflow \(+-Infinity
491 Divide by Zero \(+-Infinity \}
494 Divide by Zero \(+-\(if \}
495 Underflow Gradual Underflow
496 Inexact Rounded value
500 NOTE: An Exception is not an Error unless handled badly.
501 What makes a class of exceptions exceptional
502 is that no single default response can be satisfactory
504 On the other hand, if a default
505 response will serve most instances satisfactorily,
506 the unsatisfactory instances cannot justify aborting
507 computation every time the exception occurs.
510 For each kind of floating\-point exception, IEEE 754
511 provides a Flag that is raised each time its exception
512 is signaled, and stays raised until the program resets it.
513 Programs may also test, save and restore a flag.
514 Thus, IEEE 754 provides three ways by which programs
515 may cope with exceptions for which the default result
516 might be unsatisfactory:
518 Test for a condition that might cause an exception
519 later, and branch to avoid the exception.
521 Test a flag to see whether an exception has occurred
522 since the program last reset its flag.
524 Test a result to see whether it is a value that only
525 an exception could have produced.
527 CAUTION: The only reliable ways to discover
528 whether Underflow has occurred are to test whether
529 products or quotients lie closer to zero than the
530 underflow threshold, or to test the Underflow flag.
531 (Sums and differences cannot underflow in
537 y then x\-y is correct to
538 full precision and certainly nonzero regardless of
540 Products and quotients that
541 underflow gradually can lose accuracy gradually
542 without vanishing, so comparing them with zero
543 (as one might on a VAX) will not reveal the loss.
544 Fortunately, if a gradually underflowed value is
545 destined to be added to something bigger than the
546 underflow threshold, as is almost always the case,
547 digits lost to gradual underflow will not be missed
548 because they would have been rounded off anyway.
549 So gradual underflows are usually \fIprovably\fR ignorable.
550 The same cannot be said of underflows flushed to 0.
553 At the option of an implementor conforming to IEEE 754,
554 other ways to cope with exceptions may be provided:
557 This mechanism classifies an exception in
558 advance as an incident to be handled by means
559 traditionally associated with error\-handling
560 statements like "ON ERROR GO TO ...".
561 Different languages offer different forms of this statement,
562 but most share the following characteristics:
563 .IP \(em \w'\0\0\0\0'u
564 No means is provided to substitute a value for
565 the offending operation's result and resume
566 computation from what may be the middle of an expression.
567 An exceptional result is abandoned.
568 .IP \(em \w'\0\0\0\0'u
569 In a subprogram that lacks an error\-handling
570 statement, an exception causes the subprogram to
571 abort within whatever program called it, and so
572 on back up the chain of calling subprograms until
573 an error\-handling statement is encountered or the
574 whole task is aborted and memory is dumped.
577 This mechanism, requiring an interactive
578 debugging environment, is more for the programmer
580 It classifies an exception in
581 advance as a symptom of a programmer's error; the
582 exception suspends execution as near as it can to
583 the offending operation so that the programmer can
584 look around to see how it happened.
586 the first several exceptions turn out to be quite
587 unexceptionable, so the programmer ought ideally
588 to be able to resume execution after each one as if
589 execution had not been stopped.
591 \&... Other ways lie beyond the scope of this document.
594 The crucial problem for exception handling is the problem of
595 Scope, and the problem's solution is understood, but not
596 enough manpower was available to implement it fully in time
597 to be distributed in 4.3 BSD's \fIlibm\fR.
598 Ideally, each elementary function should act
599 as if it were indivisible, or atomic, in the sense that ...
601 No exception should be signaled that is not deserved by
602 the data supplied to that function.
604 Any exception signaled should be identified with that
605 function rather than with one of its subroutines.
606 .IP iii) \w'iii)'u+2n
607 The internal behavior of an atomic function should not
608 be disrupted when a calling program changes from
609 one to another of the five or so ways of handling
610 exceptions listed above, although the definition
611 of the function may be correlated intentionally
612 with exception handling.
614 Ideally, every programmer should be able \fIconveniently\fR to
615 turn a debugged subprogram into one that appears atomic to
617 But simulating all three characteristics of an
618 atomic function is still a tedious affair, entailing hosts
619 of tests and saves\-restores; work is under way to ameliorate
622 Meanwhile, the functions in \fIlibm\fR are only approximately atomic.
623 They signal no inappropriate exception except possibly ...
627 when a result, if properly computed, might have lain barely within range, and
629 Inexact in \fIcabs\fR, \fIcbrt\fR, \fIhypot\fR, \fIlog10\fR and \fIpow\fR
631 when it happens to be exact, thanks to fortuitous cancellation of errors.
636 Invalid Operation is signaled only when
638 any result but \*(nn would probably be misleading.
640 Overflow is signaled only when
642 the exact result would be finite but beyond the overflow threshold.
644 Divide\-by\-Zero is signaled only when
646 a function takes exactly infinite values at finite operands.
648 Underflow is signaled only when
650 the exact result would be nonzero but tinier than the underflow threshold.
652 Inexact is signaled only when
654 greater range or precision would be needed to represent the exact result.
658 .\" .Bl -tag -width /usr/lib/profile/libm.a -compact
659 .\" .It Pa /usr/lib/libm.a
660 .\" the static math library
661 .\" .It Pa /usr/lib/libm.so
662 .\" the dynamic math library
663 .\" .It Pa /usr/lib/profile/libm.a
664 .\" the static math library compiled for profiling
667 An explanation of IEEE 754 and its proposed extension p854
668 was published in the IEEE magazine MICRO in August 1984 under
669 the title "A Proposed Radix\- and Word\-length\-independent
670 Standard for Floating\-point Arithmetic" by W. J. Cody et al.
671 The manuals for Pascal, C and BASIC on the Apple Macintosh
672 document the features of IEEE 754 pretty well.
673 Articles in the IEEE magazine COMPUTER vol. 14 no. 3 (Mar. 1981),
674 and in the ACM SIGNUM Newsletter Special Issue of
675 Oct. 1979, may be helpful although they pertain to
676 superseded drafts of the standard.
678 When signals are appropriate, they are emitted by certain
679 operations within the codes, so a subroutine\-trace may be
680 needed to identify the function with its signal in case
681 method 5) above is in use.
682 And the codes all take the
683 IEEE 754 defaults for granted; this means that a decision to
684 trap all divisions by zero could disrupt a code that would
685 otherwise get correct results despite division by zero.