libm/man/math.3 - android_bionic - Gitiles

 .\" Copyright (c) 1985 Regents of the University of California.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\" 3. All advertising materials mentioning features or use of this software
 .\"    must display the following acknowledgement:
 .\"	This product includes software developed by the University of
 .\"	California, Berkeley and its contributors.
 .\" 4. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
 .\"	from: @(#)math.3	6.10 (Berkeley) 5/6/91
 .\" $FreeBSD: src/lib/msun/man/math.3,v 1.27 2005/11/17 13:00:00 ru Exp $
 .\"
 .Dd November 6, 2005
 .Dt MATH 3
 .Os
 .if n \{\
 .char \[sr] "sqrt
 .\}
 .Sh NAME
 .Nm math
 .Nd "floating-point mathematical library"
 .Sh LIBRARY
 .Lb libm
 .Sh SYNOPSIS
 .In math.h
 .Sh DESCRIPTION
 These functions constitute the C math library.
 .Sh "LIST OF FUNCTIONS"
 Each of the following
 .Vt double
 functions has a
 .Vt float
 counterpart with an
 .Ql f
 appended to the name and a
 .Vt "long double"
 counterpart with an
 .Ql l
 appended.
 As an example, the
 .Vt float
 and
 .Vt "long double"
 counterparts of
 .Ft double
 .Fn acos "double x"
 are
 .Ft float
 .Fn acosf "float x"
 and
 .Ft "long double"
 .Fn acosl "long double x" ,
 respectively.
 .de Cl
 .Bl -column "isgreaterequal" "bessel function of the second kind of the order 0"
 .Em "Name	Description"
 ..
 .Ss Algebraic Functions
 .Cl
 cbrt	cube root
 fma	fused multiply-add
 hypot	Euclidean distance
 sqrt	square root
 .El
 .Ss Classification Functions
 .Cl
 fpclassify	classify a floating-point value
 isfinite	determine whether a value is finite
 isinf	determine whether a value is infinite
 isnan	determine whether a value is \*(Na
 isnormal	determine whether a value is normalized
 .El
 .Ss Exponent Manipulation Functions
 .Cl
 frexp	extract exponent and mantissa
 ilogb	extract exponent
 ldexp	multiply by power of 2
 logb	extract exponent
 scalbln	adjust exponent
 scalbn	adjust exponent
 .El
 .Ss Extremum- and Sign-Related Functions
 .Cl
 copysign	copy sign bit
 fabs	absolute value
 fdim	positive difference
 fmax	maximum function
 fmin	minimum function
 signbit	extract sign bit
 .El
 .\" .Ss Not a Number
 .\" .Cl
 .\" nan	return quiet \*(Na)	0
 .\" .El
 .Ss Residue and Rounding Functions
 .Cl
 ceil	integer no less than
 floor	integer no greater than
 fmod	positive remainder
 llrint	round to integer in fixed-point format
 llround	round to nearest integer in fixed-point format
 lrint	round to integer in fixed-point format
 lround	round to nearest integer in fixed-point format
 modf	extract integer and fractional parts
 nearbyint	round to integer (silent)
 nextafter	next representable value
 nexttoward	next representable value
 remainder	remainder
 remquo	remainder with partial quotient
 rint	round to integer
 round	round to nearest integer
 trunc	integer no greater in magnitude than
 .El
 .Pp
 The
 .Fn ceil ,
 .Fn floor ,
 .Fn llround ,
 .Fn lround ,
 .Fn round ,
 and
 .Fn trunc
 functions round in predetermined directions, whereas
 .Fn llrint ,
 .Fn lrint ,
 and
 .Fn rint
 round according to the current (dynamic) rounding mode.
 For more information on controlling the dynamic rounding mode, see
 .Xr fenv 3
 and
 .Xr fesetround 3 .
 .Ss Silent Order Predicates
 .Cl
 isgreater	greater than relation
 isgreaterequal	greater than or equal to relation
 isless	less than relation
 islessequal	less than or equal to relation
 islessgreater	less than or greater than relation
 isunordered	unordered relation
 .El
 .Ss Transcendental Functions
 .Cl
 acos	inverse cosine
 acosh	inverse hyperbolic cosine
 asin	inverse sine
 asinh	inverse hyperbolic sine
 atan	inverse tangent
 atanh	inverse hyperbolic tangent
 atan2	atan(y/x); complex argument
 cos	cosine
 cosh	hyperbolic cosine
 erf	error function
 erfc	complementary error function
 exp	exponential base e
 exp2	exponential base 2
 expm1	exp(x)\-1
 j0	Bessel function of the first kind of the order 0
 j1	Bessel function of the first kind of the order 1
 jn	Bessel function of the first kind of the order n
 lgamma	log gamma function
 log	natural logarithm
 log10	logarithm to base 10
 log1p	log(1+x)
 .\" log2	base 2 logarithm
 pow	exponential x**y
 sin	trigonometric function
 sinh	hyperbolic function
 tan	trigonometric function
 tanh	hyperbolic function
 tgamma	gamma function
 y0	Bessel function of the second kind of the order 0
 y1	Bessel function of the second kind of the order 1
 yn	Bessel function of the second kind of the order n
 .El
 .Pp
 Unlike the algebraic functions listed earlier, the routines
 in this section may not produce a result that is correctly rounded,
 so reproducible results cannot be guaranteed across platforms.
 For most of these functions, however, incorrect rounding occurs
 rarely, and then only in very-close-to-halfway cases.
 .Sh SEE ALSO
 .Xr fenv 3 ,
 .Xr ieee 3
 .Sh HISTORY
 A math library with many of the present functions appeared in
 .At v7 .
 The library was substantially rewritten for
 .Bx 4.3
 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
 .Fx 1.1.5 .
 Additional routines, including ones for
 .Vt float
 and
 .Vt long double
 values, were written for or imported into subsequent versions of FreeBSD.
 .Sh BUGS
 The
 .Fn log2
 and
 .Fn nan
 functions are missing, and many functions are not available in their
 .Vt "long double"
 variants.
 .Pp
 Many of the routines to compute transcendental functions produce
 inaccurate results in other than the default rounding mode.
 .Pp
 On some architectures, trigonometric argument reduction is not
 performed accurately, resulting in errors greater than 1
 .Em ulp
 for large arguments to
 .Fn cos ,
 .Fn sin ,
 and
 .Fn tan .
	.\" Copyright (c) 1985 Regents of the University of California.
	.\" All rights reserved.
	.\"
	.\" Redistribution and use in source and binary forms, with or without
	.\" modification, are permitted provided that the following conditions
	.\" are met:
	.\" 1. Redistributions of source code must retain the above copyright
	.\" notice, this list of conditions and the following disclaimer.
	.\" 2. Redistributions in binary form must reproduce the above copyright
	.\" notice, this list of conditions and the following disclaimer in the
	.\" documentation and/or other materials provided with the distribution.
	.\" 3. All advertising materials mentioning features or use of this software
	.\" must display the following acknowledgement:
	.\" This product includes software developed by the University of
	.\" California, Berkeley and its contributors.
	.\" 4. Neither the name of the University nor the names of its contributors
	.\" may be used to endorse or promote products derived from this software
	.\" without specific prior written permission.
	.\"
	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.
	.\"
	.\" from: @(#)math.3 6.10 (Berkeley) 5/6/91
	.\" $FreeBSD: src/lib/msun/man/math.3,v 1.27 2005/11/17 13:00:00 ru Exp $
	.\"
	.Dd November 6, 2005
	.Dt MATH 3
	.Os
	.if n \{\
	.char \[sr] "sqrt
	.\}
	.Sh NAME
	.Nm math
	.Nd "floating-point mathematical library"
	.Sh LIBRARY
	.Lb libm
	.Sh SYNOPSIS
	.In math.h
	.Sh DESCRIPTION
	These functions constitute the C math library.
	.Sh "LIST OF FUNCTIONS"
	Each of the following
	.Vt double
	functions has a
	.Vt float
	counterpart with an
	.Ql f
	appended to the name and a
	.Vt "long double"
	counterpart with an
	.Ql l
	appended.
	As an example, the
	.Vt float
	and
	.Vt "long double"
	counterparts of
	.Ft double
	.Fn acos "double x"
	are
	.Ft float
	.Fn acosf "float x"
	and
	.Ft "long double"
	.Fn acosl "long double x" ,
	respectively.
	.de Cl
	.Bl -column "isgreaterequal" "bessel function of the second kind of the order 0"
	.Em "Name Description"
	..
	.Ss Algebraic Functions
	.Cl
	cbrt cube root
	fma fused multiply-add
	hypot Euclidean distance
	sqrt square root
	.El
	.Ss Classification Functions
	.Cl
	fpclassify classify a floating-point value
	isfinite determine whether a value is finite
	isinf determine whether a value is infinite
	isnan determine whether a value is \*(Na
	isnormal determine whether a value is normalized
	.El
	.Ss Exponent Manipulation Functions
	.Cl
	frexp extract exponent and mantissa
	ilogb extract exponent
	ldexp multiply by power of 2
	logb extract exponent
	scalbln adjust exponent
	scalbn adjust exponent
	.El
	.Ss Extremum- and Sign-Related Functions
	.Cl
	copysign copy sign bit
	fabs absolute value
	fdim positive difference
	fmax maximum function
	fmin minimum function
	signbit extract sign bit
	.El
	.\" .Ss Not a Number
	.\" .Cl
	.\" nan return quiet \*(Na) 0
	.\" .El
	.Ss Residue and Rounding Functions
	.Cl
	ceil integer no less than
	floor integer no greater than
	fmod positive remainder
	llrint round to integer in fixed-point format
	llround round to nearest integer in fixed-point format
	lrint round to integer in fixed-point format
	lround round to nearest integer in fixed-point format
	modf extract integer and fractional parts
	nearbyint round to integer (silent)
	nextafter next representable value
	nexttoward next representable value
	remainder remainder
	remquo remainder with partial quotient
	rint round to integer
	round round to nearest integer
	trunc integer no greater in magnitude than
	.El
	.Pp
	The
	.Fn ceil ,
	.Fn floor ,
	.Fn llround ,
	.Fn lround ,
	.Fn round ,
	and
	.Fn trunc
	functions round in predetermined directions, whereas
	.Fn llrint ,
	.Fn lrint ,
	and
	.Fn rint
	round according to the current (dynamic) rounding mode.
	For more information on controlling the dynamic rounding mode, see
	.Xr fenv 3
	and
	.Xr fesetround 3 .
	.Ss Silent Order Predicates
	.Cl
	isgreater greater than relation
	isgreaterequal greater than or equal to relation
	isless less than relation
	islessequal less than or equal to relation
	islessgreater less than or greater than relation
	isunordered unordered relation
	.El
	.Ss Transcendental Functions
	.Cl
	acos inverse cosine
	acosh inverse hyperbolic cosine
	asin inverse sine
	asinh inverse hyperbolic sine
	atan inverse tangent
	atanh inverse hyperbolic tangent
	atan2 atan(y/x); complex argument
	cos cosine
	cosh hyperbolic cosine
	erf error function
	erfc complementary error function
	exp exponential base e
	exp2 exponential base 2
	expm1 exp(x)\-1
	j0 Bessel function of the first kind of the order 0
	j1 Bessel function of the first kind of the order 1
	jn Bessel function of the first kind of the order n
	lgamma log gamma function
	log natural logarithm
	log10 logarithm to base 10
	log1p log(1+x)
	.\" log2 base 2 logarithm
	pow exponential x**y
	sin trigonometric function
	sinh hyperbolic function
	tan trigonometric function
	tanh hyperbolic function
	tgamma gamma function
	y0 Bessel function of the second kind of the order 0
	y1 Bessel function of the second kind of the order 1
	yn Bessel function of the second kind of the order n
	.El
	.Pp
	Unlike the algebraic functions listed earlier, the routines
	in this section may not produce a result that is correctly rounded,
	so reproducible results cannot be guaranteed across platforms.
	For most of these functions, however, incorrect rounding occurs
	rarely, and then only in very-close-to-halfway cases.
	.Sh SEE ALSO
	.Xr fenv 3 ,
	.Xr ieee 3
	.Sh HISTORY
	A math library with many of the present functions appeared in
	.At v7 .
	The library was substantially rewritten for
	.Bx 4.3
	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
	.Fx 1.1.5 .
	Additional routines, including ones for
	.Vt float
	and
	.Vt long double
	values, were written for or imported into subsequent versions of FreeBSD.
	.Sh BUGS
	The
	.Fn log2
	and
	.Fn nan
	functions are missing, and many functions are not available in their
	.Vt "long double"
	variants.
	.Pp
	Many of the routines to compute transcendental functions produce
	inaccurate results in other than the default rounding mode.
	.Pp
	On some architectures, trigonometric argument reduction is not
	performed accurately, resulting in errors greater than 1
	.Em ulp
	for large arguments to
	.Fn cos ,
	.Fn sin ,
	and
	.Fn tan .