Subversion Repositories openrisc_2011-10-31

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

The macro @code{HUGE_VALF} is a corresponding value for @code{float}.

@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

* acos::        Arccosine

* acosh::       Inverse hyperbolic cosine

* asin::        Arcsine

* asinh::       Inverse hyperbolic sine

* atan::        Arctangent

* atan2::       Arctangent of y/x

* atanh::       Inverse hyperbolic tangent

* jN::          Bessel functions (jN, yN)

* cbrt::        Cube root

* copysign::    Sign of Y, magnitude of X

* cosh::        Hyperbolic cosine

* erf::         Error function (erf, erfc)

* exp::         Exponential, base e

* exp2::        Exponential, base 2

* expm1::       Exponential, base e, of x - 1

* fabs::        Absolute value (magnitude)

* fdim::        Positive difference

* floor::       Floor and ceiling (floor, ceil)

* fma::         Floating multiply add

* fmax::        Maximum

* fmin::        Minimum

* fmod::        Floating-point remainder (modulo)

* fpclassify::  Floating-point classification macro

* frexp::       Split floating-point number

* gamma::       Logarithmic gamma function

* hypot::       Distance from origin

* ilogb::       Get exponent

* infinity::    Floating infinity

* isgreater::   Comparison macros

* ldexp::       Scale by a power of 2

* log::         Natural logarithms

* log10::       Base 10 logarithms

* log1p::       Log of 1 + X

* log2::        Base 2 logarithms

* logb::        Get exponent

* lrint::       Round to integer

* lround::      Round to integer, away from zero (lround, llround)

* matherr::     Modifiable math error handler

* modf::        Split fractional and integer parts

* nan::         Floating Not a Number

* nearbyint::   Round to integer

* nextafter::   Get next representable number

* pow::         X to the power Y

* remainder::   remainder of X divided by Y

* remquo::      Remainder and part of quotient

* rint::        Round to integer

* round::       Round to integer, away from zero

* scalbn::      Scale by a power of FLT_RADIX (2)

* signbit::     Does floating-point number have negative sign?

* sin::         Sine or cosine (sin, cos)

* sinh::        Hyperbolic sine

* sqrt::        Positive square root

* tan::         Tangent

* tanh::        Hyperbolic tangent

* trunc::       Round to integer, towards zero

@end menu

@page

@node version

@section Error Handling

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.

The aforementioned error reporting is the supported Newlib libm error

handling method.  However, the majority of the 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   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_matherr.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   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