path: root/newlib/libm/math/math.tex

@node Math
@chapter Mathematical Functions (@file{math.h})

This chapter groups a wide variety of mathematical functions.  The
corresponding definitions and declarations are in @file{math.h}.  
The definition of HUGE_VAL from @file{math.h} is of particular interest.

@enumerate
@item
The representation of infinity as a @code{double} is defined as
@code{HUGE_VAL}; this number is returned on overflow by many functions.
The macro @code{HUGE_VALF} is a corresponding value for @code{float}.
@end enumerate

Alternative declarations of the mathematical functions, which exploit
specific machine capabilities to operate faster---but generally have
less error checking and may reflect additional limitations on some
machines---are available when you include @file{fastmath.h} instead of
@file{math.h}.

@menu 
* version::	Version of library
* Function acos::	Arccosine
* Function acosh::	Inverse hyperbolic cosine
* Function asin::	Arcsine
* Function asinh::	Inverse hyperbolic sine
* Function atan::	Arctangent
* Function atan2::	Arctangent of y/x
* Function atanh::	Inverse hyperbolic tangent
* Function jN::	        Bessel functions (jN, yN)
* Function cbrt::	Cube root
* Function copysign::	Sign of Y, magnitude of X
* Function cosh::	Hyperbolic cosine
* Function erf::		Error function (erf, erfc)
* Function exp::		Exponential, base e
* Function exp10::	Exponential, base 10
* Function exp2::	Exponential, base 2
* Function expm1::	Exponential, base e, of x - 1
* Function fabs::	Absolute value (magnitude)
* Function fdim::	Positive difference
* Function floor::	Floor and ceiling (floor, ceil)
* Function fma::		Floating multiply add
* Function fmax::	Maximum
* Function fmin::	Minimum
* Function fmod::	Floating-point remainder (modulo)
* Function fpclassify::	Floating-point classification macro
* Function frexp::	Split floating-point number
* Function gamma::	Logarithmic gamma function
* Function hypot::	Distance from origin
* Function ilogb::	Get exponent
* Function infinity::	Floating infinity
* Function isgreater::	Comparison macros
* Function ldexp::	Scale by a power of 2
* Function log::		Natural logarithms
* Function log10::	Base 10 logarithms
* Function log1p::	Log of 1 + X
* Function log2::	Base 2 logarithms
* Function logb::	Get exponent
* Function lrint::	Round to integer
* Function lround::	Round to integer, away from zero (lround, llround)
* Function modf::	Split fractional and integer parts
* Function nan::		Floating Not a Number
* Function nearbyint::	Round to integer
* Function nextafter::	Get next representable number
* Function pow::		X to the power Y
* Function pow10::	10 to the power X
* Function remainder::	remainder of X divided by Y
* Function remquo::	Remainder and part of quotient
* Function rint::	Round to integer
* Function round::	Round to integer, away from zero
* Function scalbn::	Scale by a power of FLT_RADIX (2)
* Function signbit::	Does floating-point number have negative sign?
* Function sin::		Sine or cosine (sin, cos)
* Function sinh::	Hyperbolic sine
* Function sqrt::	Positive square root
* Function tan::		Tangent
* Function tanh::	Hyperbolic tangent
* Function trunc::	Round to integer, towards zero
@end menu

@page
@node version
@section Error Handling

There are two different versions of the math library routines: IEEE
and POSIX.  The version may be selected at runtime by
setting the global variable @code{_LIB_VERSION}, defined in
@file{math.h}.  It may be set to one of the following constants defined
in @file{math.h}: @code{_IEEE_} or @code{_POSIX_}.
The @code{_LIB_VERSION} variable is not specific to any
thread, and changing it will affect all threads.

The versions of the library differ only in the setting of @code{errno}.

In IEEE mode, @code{errno} is never set.

In POSIX mode, @code{errno} is set correctly.

The library is set to IEEE mode by default.

The majority of the floating-point math functions are written
so as to produce the floating-point exceptions (e.g. "invalid",
"divide-by-zero") as required by the C and POSIX standards, for
floating-point implementations that support them.  Newlib does not provide
the floating-point exception access routines defined in the standards
for fenv.h, though, which is why they are considered unsupported.  It is
mentioned in case you have separately-provided access routines so that
you are aware that they can be caused.

@section Standards Compliance And Portability
Most of the individual function descriptions describe the standards to which
each function complies.  However, these descriptions are mostly out of date,
having been written before C99 was released.  One of these days we'll get
around to updating the rest of them.  (If you'd like to help, please let us
know.)

``C99'' refers to ISO/IEC 9899:1999, ``Programming languages--C''.
``POSIX'' refers to IEEE Standard 1003.1.  POSIX@registeredsymbol{} is a
registered trademark of The IEEE.

@c To sort the include list easily, keep the indentation right because want to
@c skip the s_|w_ at the start of most--but not all--of the file names.
@c (e.g., isgreater.def does not have a leading s nor w.)  Then, sort
@c based on the column.  For example:  "sort -t@ -k3.17"
@c A few hand-edits might be appropriate after a sort, although not necessary
@c and are a nuisance as ought to be kept in sync with menu list above:
@c atan2 after atan, exp2 after exp, log first in log list, and w_j0 to place
@c to reflect function name of Bessel (as opposed to j; e.g. after atanh,
@c before cbrt).

@page
@include   math/w_acos.def
@page
@include   math/w_acosh.def
@page
@include   math/w_asin.def
@page 
@include   math/s_asinh.def
@page
@include   math/s_atan.def
@page 
@include   math/w_atan2.def
@page
@include   math/w_atanh.def
@page 
@include   math/w_j0.def
@page
@include common/s_cbrt.def
@page
@include common/s_copysign.def
@page
@include   math/w_cosh.def
@page
@include   math/s_erf.def
@page
@include   math/w_exp.def
@page
@include   common/s_exp10.def
@page
@include   math/w_exp2.def
@page
@include common/s_expm1.def
@page
@include   math/s_fabs.def
@page
@include common/s_fdim.def
@page
@include   math/s_floor.def
@page
@include common/s_fma.def
@page
@include common/s_fmax.def
@page
@include common/s_fmin.def
@page
@include   math/w_fmod.def
@page
@include   math/s_frexp.def
@page
@include   math/w_gamma.def
@page
@include   math/w_hypot.def
@page
@include common/s_ilogb.def
@page
@include common/s_infinity.def
@page
@include   common/isgreater.def
@page
@include common/s_isnan.def
@page
@include   math/s_ldexp.def
@page
@include   math/w_log.def
@page
@include   math/w_log10.def
@page
@include common/s_log1p.def
@page
@include common/s_log2.def
@page
@include common/s_logb.def
@page
@include common/s_lrint.def
@page
@include common/s_lround.def
@page
@include common/s_modf.def
@page
@include common/s_nan.def
@page
@include common/s_nearbyint.def
@page
@include common/s_nextafter.def
@page
@include   math/w_pow.def
@page
@include   common/s_pow10.def
@page
@include   math/w_remainder.def
@page
@include common/s_remquo.def
@page
@include common/s_rint.def
@page
@include common/s_round.def
@page
@include common/s_scalbn.def
@page
@include common/s_signbit.def
@page
@include   math/s_sin.def
@page
@include   math/w_sinh.def
@page
@include   math/w_sqrt.def
@page
@include   math/s_tan.def
@page
@include   math/s_tanh.def
@page
@include common/s_trunc.def