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

FreeBSD Manual Pages


home | help
MATH(3)		       FreeBSD 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'
     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
     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
		 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.
		 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
		 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

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

FreeBSD	11.1			 June 11, 2004			  FreeBSD 11.1


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

home | help