Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MATH(3)			 BSD Library Functions Manual		       MATH(3)

     math - introduction to mathematical library functions

     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>.

     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
     scalbln	   exponent adjustment			0
     scalbn	   exponent adjustment			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		       ???

     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.
		 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.
		 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
		       Underflow	      Gradual Underflow
		       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

     The functions in libm are only approximately atomic.  They	signal no in-
     appropriate exception except possibly ...
		 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
	   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.

     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
     SIGNUM Newsletter Special Issue of	Oct. 1979, may be helpful although
     they pertain to superseded	drafts of the standard.

     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


Want to link to this manual page? Use this URL:

home | help