path: root/newlib/libm/mathfp/mathfp.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}.  
Two definitions from @file{math.h} are 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.

@item
The structure @code{exception} is used when you write customized error
handlers for the mathematical functions.  You can customize error
handling for most of these functions by defining your own version of
@code{matherr}; see the section on @code{matherr} for details.
@end enumerate

@cindex system calls
@cindex support subroutines
@cindex stubs
@cindex OS stubs
Since the error handling code calls @code{fputs}, the mathematical
subroutines require stubs or minimal implementations for the same list
of OS subroutines as @code{fputs}: @code{close}, @code{fstat},
@code{isatty}, @code{lseek}, @code{read}, @code{sbrk}, @code{write}.
@xref{syscalls,,System Calls, libc.info, The Red Hat newlib C Library},
for a discussion and for sample minimal implementations of these support
subroutines.

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
* Function expm1::	Exponential of x, - 1
* Function fabs::	Absolute value (magnitude)
* Function floor::	Floor and ceiling  (floor, ceil)
* Function fmod::	Floating-point remainder (modulo)
* 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 isnan::	Check type of number
* Function ldexp::	Load exponent
* Function log::		Natural logarithms
* Function log10::	Base 10 logarithms
* Function log1p::	Log of 1 + X
* Function matherr::	Modifiable math error handler
* Function modf::	Split fractional and integer parts
* Function nan::		Floating Not a Number
* Function nextafter::	Get next representable number
* Function pow::		X to the power Y
* Function remainder::	remainder of X divided by Y
* Function scalbn::	scalbn
* Function sin::		Sine or cosine (sin, cos)
* Function sinh::	Hyperbolic sine
* Function sqrt::	Positive square root
* Function tan::		Tangent
* Function tanh::	Hyperbolic tangent
@end menu

@page
@node version
@section Version of library

There are four different versions of the math library routines: IEEE,
POSIX, X/Open, or SVID.  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_}, @code{_POSIX_}, @code{_XOPEN_}, or
@code{_SVID_}.  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 how errors are handled.

In IEEE mode, the @code{matherr} function is never called, no warning
messages are printed, and @code{errno} is never set.

In POSIX mode, @code{errno} is set correctly, but the @code{matherr}
function is never called and no warning messages are printed.

In X/Open mode, @code{errno} is set correctly, and @code{matherr} is
called, but warning message are not printed.

In SVID mode, functions which overflow return 3.40282346638528860e+38,
the maximum single-precision floating-point value, rather than infinity.
Also, @code{errno} is set correctly, @code{matherr} is called, and, if
@code{matherr} returns 0, warning messages are printed for some errors.
For example, by default @samp{log(-1.0)} writes this message on standard
error output:

@example
log: DOMAIN error
@end example

The library is set to X/Open mode by default.

@page
@include mathfp/sacos.def

@page
@include mathfp/eacosh.def

@page
@include mathfp/sasine.def

@page
@include mathfp/sasinh.def

@page
@include mathfp/satan.def

@page
@include mathfp/satan2.def

@page
@include mathfp/eatanh.def

@page
@include mathfp/wjn.def

@page
@include common/scbrt.def

@page
@include common/scopysign.def

@page
@include mathfp/scosh.def

@page
@include mathfp/serf.def

@page
@include mathfp/sexp.def

@page
@include common/sexpm1.def

@page
@include mathfp/sfabs.def

@page
@include mathfp/sfloor.def

@page
@include mathfp/sfmod.def

@page
@include mathfp/sfrexp.def

@page
@include mathfp/erlgamma.def

@page
@include mathfp/ehypot.def

@page
@include common/silogb.def

@page
@include common/sinfinity.def

@page
@include common/sisnan.def

@page
@include mathfp/sldexp.def

@page
@include mathfp/slogarithm.def

@page
@include mathfp/slog10.def

@page
@include common/slog1p.def

@page
@include common/smatherr.def

@page
@include common/smodf.def

@page
@include common/snan.def

@page
@include common/snextafter.def

@page
@include mathfp/spow.def

@page
@include mathfp/eremainder.def

@page
@include common/sscalbn.def

@page
@include mathfp/ssqrt.def

@page
@include mathfp/ssine.def

@page
@include mathfp/ssineh.def

@page
@include mathfp/stan.def

@page
@include mathfp/stanh.def