# FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
```MATH(3)		       FreeBSD 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'
appended.	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
division,   and   (finite)/+-Infinity = +-0   (nonzero)/0   =
+-Infinity.   But  Infinity-Infinity,	Infinity*0  and	Infin-
ity/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
Invalid 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
instances 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
environment, 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
inappropriate 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 miss-
ing, 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.

FreeBSD	10.3			 June 11, 2004			  FreeBSD 10.3
```

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>

home | help