# FreeBSD Manual Pages

```MATH(3)			 BSD Library Functions Manual		       MATH(3)

NAME
math - introduction to mathematical library functions

DESCRIPTION
These functions constitute	the C math library, The	link editor searches
this library under	the -lm	option.	 Declarations for these	functions may
be	obtained from the include file <math.h>.

LIST OF	FUNCTIONS
Each of the following double functions has	a float	counterpart with an
`f' appended to the name and a long double	counterpart with an `l'	ap-
pended.  As an example, the float and long	double counterparts of double
acos(double x) are	float acosf(float x) and long double acosl(long	double
x), respectively.

Name		 Description		    Error Bound	(ULPs)
acos	   inverse trigonometric function	3
acosh	   inverse hyperbolic function		3
asin	   inverse trigonometric function	3
asinh	   inverse hyperbolic function		3
atan	   inverse trigonometric function	1
atanh	   inverse hyperbolic function		3
atan2	   inverse trigonometric function	2
cbrt	   cube	root				1
ceil	   integer no less than			0
copysign	   copy	sign bit			0
cos	   trigonometric function		1
cosh	   hyperbolic function			3
erf	   error function		       ???
erfc	   complementary error function	       ???
exp	   exponential base e			1
expm1	   exp(x)-1				1
fabs	   absolute value			0
floor	   integer no greater than		0
fmod	   remainder function		       ???
frexp	   extract mantissa and	exponent	0
hypot	   Euclidean distance			1
ilogb	   exponent extraction			0
j0		   bessel function		       ???
j1		   bessel function		       ???
jn		   bessel function		       ???
ldexp	   multiply by power of	2		0
lgamma	   log gamma function		       ???
log	   natural logarithm			1
log10	   logarithm to	base 10			3
log1p	   log(1+x)				1
logb	   exponent extraction			0
modf	   extract fractional part	       ???
nextafter	   next	representable value		0
pow	   exponential x**y		     60-500
remainder	   remainder				0
rint	   round to nearest integer		0
round	   round to nearest integer		0
sin	   trigonometric function		1
sinh	   hyperbolic function			3
sqrt	   square root				1
tan	   trigonometric function		3
tanh	   hyperbolic function			3
tgamma	   gamma function		       ???
trunc	   round towards zero			0
y0		   bessel function		       ???
y1		   bessel function		       ???
yn		   bessel function		       ???

NOTES
Virtually all modern floating-point units attempt to support IEEE Stan-
dard 754 for Binary Floating-Point	Arithmetic.  This standard does	not
cover particular routines in the math library except for the few docu-
mented in ieee(3);	it primarily defines representations of	numbers	and
abstract properties of arithmetic operations relating to precision,
rounding, and exceptional cases, as described below.  The programs	are
accurate to within	the numbers of ulps tabulated above; an	ulp is one
Unit in the Last Place.

IEEE STANDARD 754 Floating-Point Arithmetic:

Properties	of IEEE	754 Double-Precision:

Wordsize: 64	bits, 8	bytes.	Radix: Binary.
Precision: 53 sig.  bits, roughly like 16 sig.  decimals.
If x and x' are consecutive positive Double-Precision numbers
(they differ by 1 ulp), then
1.1e-16 < 0.5**53 < (x'-x)/x <= 0.5**52 < 2.3e-16.
Range: Overflow threshold  =	2.0**1024 = 1.8e308
Underflow threshold =	0.5**1022 = 2.2e-308
Overflow goes by default to a signed Infinity.
Underflow  is Gradual,	rounding to the	nearest	integer	multi-
ple of	0.5**1074 = 4.9e-324.
Zero	is represented ambiguously as +0 or -0.
Its sign transforms correctly through multiplication or divi-
sion,	and is preserved by addition of	zeros with like	signs;
but x-x yields	+0 for every finite x.	 The  only  operations
that  reveal  zero's  sign  are  division  by	zero and copy-
sign(x,+-0).  In particular, comparison (x > y, x >= y, etc.)
cannot	 be  affected by the sign of zero; but if finite x = y
then Infinity = 1/(x-y) != -1/(y-x) = -Infinity.
Infinity is signed.
it persists when added	to itself or  to  any  finite  number.
Its  sign transforms correctly	through	multiplication and di-
vision, and (finite)/+-Infinity = +-0 (nonzero)/0 =  +-Infin-
ity.  But Infinity-Infinity, Infinity*0 and Infinity/Infinity
are, like 0/0 and sqrt(-3), invalid operations	 that  produce
NaN. ...
Reserved operands:
there	are  2**53-2  of  them,	all called NaN (Not a Number).
Some, called Signaling	NaNs, trap any	floating-point	opera-
tion  performed  upon	them; they are used to mark missing or
uninitialized values, or nonexistent elements of arrays.  The
rest  are Quiet NaNs; they are	the default results of Invalid
Operations, and propagate through subsequent arithmetic oper-
ations.   If x	!= x then x is NaN; every other	predicate (x >
y, x =	y, x < y, ...) is FALSE	if NaN is involved.
NOTE: Trichotomy is violated by NaN.
Besides being FALSE,  predicates	 that  entail  ordered
comparison,  rather  than mere (in)equality, signal In-
valid Operation when NaN	is involved.
Rounding:
Every algebraic operation (+, -, *, /,	sqrt)  is  rounded  by
default to within half	an ulp,	and when the rounding error is
exactly half an ulp then the rounded value's  least  signifi-
cant  bit is zero.  This kind of rounding is usually the best
kind, sometimes provably so; for instance, for	every x	= 1.0,
2.0,  3.0,  4.0,  ...,	 2.0**52, we find (x/3.0)*3.0 == x and
(x/10.0)*10.0 == x and	...  despite that both	the  quotients
and  the products have	been rounded.  Only rounding like IEEE
754 can do that.  But no  single  kind	 of  rounding  can  be
proved	 best  for  every  circumstance,  so IEEE 754 provides
rounding towards zero or towards +Infinity or towards -Infin-
ity at	the programmer's option.  And the same kinds of	round-
ing are specified for Binary-Decimal  Conversions,  at	 least
for magnitudes	between	roughly	1.0e-10	and 1.0e37.
Exceptions:
IEEE  754 recognizes five kinds of floating-point exceptions,
listed	below in declining order of probable importance.
Exception	      Default Result

Invalid Operation      NaN, or FALSE
Overflow		      +-Infinity
Divide by Zero	      +-Infinity
Inexact		      Rounded value
NOTE:	An Exception is	not an	Error  unless  handled	badly.
What  makes a class of	exceptions exceptional is that no sin-
gle default response can be satisfactory in  every  instance.
On  the other hand, if	a default response will	serve most in-
stances satisfactorily, the unsatisfactory  instances	cannot
justify aborting computation every time the exception occurs.

For each kind of floating-point exception, IEEE 754 provides	a Flag
that	is raised each time  its  exception  is	 signaled,  and	 stays
raised  until  the program resets it.  Programs may also test, save
and restore a flag.	Thus, IEEE 754 provides	three  ways  by	 which
programs  may  cope	with  exceptions  for which the	default	result
might be unsatisfactory:

1.	Test for a condition that might	cause an exception later,  and
branch to avoid	the exception.

2.	Test a flag to see whether an exception	has occurred since the
program	last reset its flag.

3.	Test a result to see whether it	is a value that	only an	excep-
tion  could have produced.  CAUTION: The only reliable ways to
discover whether Underflow has occurred	are  to	 test  whether
products  or  quotients	 lie closer to zero than the underflow
threshold, or to test the Underflow flag.  (Sums  and  differ-
ences cannot underflow in IEEE 754; if x != y then x-y is cor-
rect to	full precision and certainly nonzero regardless	of how
tiny it	may be.)  Products and quotients that underflow	gradu-
ally can lose accuracy gradually without vanishing, so compar-
ing them with zero (as one might on a VAX) will	not reveal the
loss.  Fortunately, if a gradually underflowed value  is  des-
tined  to  be  added  to  something  bigger than the underflow
threshold, as is almost	always the case, digits	lost to	 grad-
ual  underflow will not	be missed because they would have been
rounded	off anyway.  So	gradual	underflows are	usually	 prov-
ably ignorable.	 The same cannot be said of underflows flushed
to 0.

At the option of an implementor conforming to IEEE 754, other  ways
to cope with	exceptions may be provided:

4.	ABORT.	 This  mechanism classifies an exception in advance as
an incident to be handled by  means  traditionally  associated
with  error-handling  statements  like	"ON  ERROR GO TO ...".
Different languages offer different forms of  this  statement,
but most share the following characteristics:

-   No means is	provided to substitute a value for the offend-
ing	operation's result and resume  computation  from  what
may	be the middle of an expression.	 An exceptional	result
is abandoned.

-   In a subprogram that lacks an error-handling statement, an
exception  causes  the subprogram to abort within whatever
program called it, and so on back up the chain of  calling
subprograms	 until	an error-handling statement is encoun-
tered or the whole task is aborted and memory is dumped.

5.	STOP.  This mechanism, requiring an interactive	debugging  en-
vironment,  is	more  for the programmer than the program.  It
classifies an exception	in advance as a	symptom	of a  program-
mer's  error;  the  exception suspends execution as near as it
can to the offending operation so that the programmer can look
around	to see how it happened.	 Quite often the first several
exceptions turn	out to be quite	unexceptionable, so  the  pro-
grammer	 ought	ideally	 to  be	able to	resume execution after
each one as if execution had not been stopped.

6.	... Other ways lie beyond the scope of this document.

Ideally, each elementary function should act as if	it were	indivisible,
or	atomic,	in the sense that ...

i)	   No exception	should be signaled that	is not deserved	by the data
supplied to that function.

ii)   Any exception signaled should be identified with that function
rather than with one	of its subroutines.

iii)  The internal	behavior of an atomic function should not be disrupted
when	a calling program changes from one to another of the five or
so ways of handling exceptions listed above,	although the defini-
tion	of the function	may be correlated intentionally	with exception
handling.

The functions in libm are only approximately atomic.  They	signal no in-
appropriate exception except possibly ...
Over/Underflow
when a	result,	if properly computed, might have  lain	barely
within	range, and
Inexact in cabs, cbrt, hypot, log10 and pow
when  it  happens to be exact,	thanks to fortuitous cancella-
tion of errors.
Otherwise,	...
Invalid Operation is	signaled only when
any result but	NaN would probably be misleading.
Overflow is signaled	only when
the exact result would	be  finite  but	 beyond	 the  overflow
threshold.
Divide-by-Zero is signaled only when
a function takes exactly infinite values at finite operands.
Underflow is	signaled only when
the  exact result would be nonzero but	tinier than the	under-
flow threshold.
Inexact is signaled only when
greater range or precision would be needed to	represent  the
exact result.

BUGS
Several functions required	by ISO/IEC 9899:1999 ("ISO C99") are missing,
and many functions	are not	available in their long	double variants.

fenv(3), ieee(3)

An	explanation of IEEE 754	and its	proposed extension p854	was published
in	the IEEE magazine MICRO	in August 1984 under the title "A Proposed
Radix- and	Word-length-independent	Standard for Floating-point Arith-
metic" by W. J. Cody et al.  The manuals for Pascal, C and	BASIC on the
Apple Macintosh document the features of IEEE 754 pretty well.  Articles
in	the IEEE magazine COMPUTER vol.	14 no. 3 (Mar. 1981), and in the ACM
they pertain to superseded	drafts of the standard.

HISTORY
A math library with many of the present functions appeared	in Version 7
AT&T UNIX.	 The library was substantially rewritten for 4.3BSD to provide
better accuracy and speed on machines supporting either VAX or IEEE 754
floating-point.  Most of this library was replaced	with FDLIBM, developed
at	Sun Microsystems, in FreeBSD 1.1.5.

BSD				 June 11, 2004				   BSD
```

NAME | DESCRIPTION | LIST OF FUNCTIONS | NOTES | BUGS | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=math&sektion=3&manpath=FreeBSD+5.3-RELEASE>