@node Math
|
@node Math
|
@chapter Mathematical Functions (@file{math.h})
|
@chapter Mathematical Functions (@file{math.h})
|
|
|
This chapter groups a wide variety of mathematical functions. The
|
This chapter groups a wide variety of mathematical functions. The
|
corresponding definitions and declarations are in @file{math.h}.
|
corresponding definitions and declarations are in @file{math.h}.
|
Two definitions from @file{math.h} are of particular interest.
|
Two definitions from @file{math.h} are of particular interest.
|
|
|
@enumerate
|
@enumerate
|
@item
|
@item
|
The representation of infinity as a @code{double} is defined as
|
The representation of infinity as a @code{double} is defined as
|
@code{HUGE_VAL}; this number is returned on overflow by many functions.
|
@code{HUGE_VAL}; this number is returned on overflow by many functions.
|
The macro @code{HUGE_VALF} is a corresponding value for @code{float}.
|
The macro @code{HUGE_VALF} is a corresponding value for @code{float}.
|
|
|
@item
|
@item
|
The structure @code{exception} is used when you write customized error
|
The structure @code{exception} is used when you write customized error
|
handlers for the mathematical functions. You can customize error
|
handlers for the mathematical functions. You can customize error
|
handling for most of these functions by defining your own version of
|
handling for most of these functions by defining your own version of
|
@code{matherr}; see the section on @code{matherr} for details.
|
@code{matherr}; see the section on @code{matherr} for details.
|
@end enumerate
|
@end enumerate
|
|
|
@cindex system calls
|
@cindex system calls
|
@cindex support subroutines
|
@cindex support subroutines
|
@cindex stubs
|
@cindex stubs
|
@cindex OS stubs
|
@cindex OS stubs
|
Since the error handling code calls @code{fputs}, the mathematical
|
Since the error handling code calls @code{fputs}, the mathematical
|
subroutines require stubs or minimal implementations for the same list
|
subroutines require stubs or minimal implementations for the same list
|
of OS subroutines as @code{fputs}: @code{close}, @code{fstat},
|
of OS subroutines as @code{fputs}: @code{close}, @code{fstat},
|
@code{isatty}, @code{lseek}, @code{read}, @code{sbrk}, @code{write}.
|
@code{isatty}, @code{lseek}, @code{read}, @code{sbrk}, @code{write}.
|
@xref{syscalls,,System Calls, libc.info, The Red Hat newlib C Library},
|
@xref{syscalls,,System Calls, libc.info, The Red Hat newlib C Library},
|
for a discussion and for sample minimal implementations of these support
|
for a discussion and for sample minimal implementations of these support
|
subroutines.
|
subroutines.
|
|
|
Alternative declarations of the mathematical functions, which exploit
|
Alternative declarations of the mathematical functions, which exploit
|
specific machine capabilities to operate faster---but generally have
|
specific machine capabilities to operate faster---but generally have
|
less error checking and may reflect additional limitations on some
|
less error checking and may reflect additional limitations on some
|
machines---are available when you include @file{fastmath.h} instead of
|
machines---are available when you include @file{fastmath.h} instead of
|
@file{math.h}.
|
@file{math.h}.
|
|
|
@menu
|
@menu
|
* version:: Version of library
|
* version:: Version of library
|
* acos:: Arccosine
|
* acos:: Arccosine
|
* acosh:: Inverse hyperbolic cosine
|
* acosh:: Inverse hyperbolic cosine
|
* asin:: Arcsine
|
* asin:: Arcsine
|
* asinh:: Inverse hyperbolic sine
|
* asinh:: Inverse hyperbolic sine
|
* atan:: Arctangent
|
* atan:: Arctangent
|
* atan2:: Arctangent of y/x
|
* atan2:: Arctangent of y/x
|
* atanh:: Inverse hyperbolic tangent
|
* atanh:: Inverse hyperbolic tangent
|
* jN:: Bessel functions (jN, yN)
|
* jN:: Bessel functions (jN, yN)
|
* cbrt:: Cube root
|
* cbrt:: Cube root
|
* copysign:: Sign of Y, magnitude of X
|
* copysign:: Sign of Y, magnitude of X
|
* cosh:: Hyperbolic cosine
|
* cosh:: Hyperbolic cosine
|
* erf:: Error function (erf, erfc)
|
* erf:: Error function (erf, erfc)
|
* exp:: Exponential, base e
|
* exp:: Exponential, base e
|
* exp2:: Exponential, base 2
|
* exp2:: Exponential, base 2
|
* expm1:: Exponential, base e, of x - 1
|
* expm1:: Exponential, base e, of x - 1
|
* fabs:: Absolute value (magnitude)
|
* fabs:: Absolute value (magnitude)
|
* fdim:: Positive difference
|
* fdim:: Positive difference
|
* floor:: Floor and ceiling (floor, ceil)
|
* floor:: Floor and ceiling (floor, ceil)
|
* fma:: Floating multiply add
|
* fma:: Floating multiply add
|
* fmax:: Maximum
|
* fmax:: Maximum
|
* fmin:: Minimum
|
* fmin:: Minimum
|
* fmod:: Floating-point remainder (modulo)
|
* fmod:: Floating-point remainder (modulo)
|
* fpclassify:: Floating-point classification macro
|
* fpclassify:: Floating-point classification macro
|
* frexp:: Split floating-point number
|
* frexp:: Split floating-point number
|
* gamma:: Logarithmic gamma function
|
* gamma:: Logarithmic gamma function
|
* hypot:: Distance from origin
|
* hypot:: Distance from origin
|
* ilogb:: Get exponent
|
* ilogb:: Get exponent
|
* infinity:: Floating infinity
|
* infinity:: Floating infinity
|
* isgreater:: Comparison macros
|
* isgreater:: Comparison macros
|
* ldexp:: Scale by a power of 2
|
* ldexp:: Scale by a power of 2
|
* log:: Natural logarithms
|
* log:: Natural logarithms
|
* log10:: Base 10 logarithms
|
* log10:: Base 10 logarithms
|
* log1p:: Log of 1 + X
|
* log1p:: Log of 1 + X
|
* log2:: Base 2 logarithms
|
* log2:: Base 2 logarithms
|
* logb:: Get exponent
|
* logb:: Get exponent
|
* lrint:: Round to integer
|
* lrint:: Round to integer
|
* lround:: Round to integer, away from zero (lround, llround)
|
* lround:: Round to integer, away from zero (lround, llround)
|
* matherr:: Modifiable math error handler
|
* matherr:: Modifiable math error handler
|
* modf:: Split fractional and integer parts
|
* modf:: Split fractional and integer parts
|
* nan:: Floating Not a Number
|
* nan:: Floating Not a Number
|
* nearbyint:: Round to integer
|
* nearbyint:: Round to integer
|
* nextafter:: Get next representable number
|
* nextafter:: Get next representable number
|
* pow:: X to the power Y
|
* pow:: X to the power Y
|
* remainder:: remainder of X divided by Y
|
* remainder:: remainder of X divided by Y
|
* remquo:: Remainder and part of quotient
|
* remquo:: Remainder and part of quotient
|
* rint:: Round to integer
|
* rint:: Round to integer
|
* round:: Round to integer, away from zero
|
* round:: Round to integer, away from zero
|
* scalbn:: Scale by a power of FLT_RADIX (2)
|
* scalbn:: Scale by a power of FLT_RADIX (2)
|
* signbit:: Does floating-point number have negative sign?
|
* signbit:: Does floating-point number have negative sign?
|
* sin:: Sine or cosine (sin, cos)
|
* sin:: Sine or cosine (sin, cos)
|
* sinh:: Hyperbolic sine
|
* sinh:: Hyperbolic sine
|
* sqrt:: Positive square root
|
* sqrt:: Positive square root
|
* tan:: Tangent
|
* tan:: Tangent
|
* tanh:: Hyperbolic tangent
|
* tanh:: Hyperbolic tangent
|
* trunc:: Round to integer, towards zero
|
* trunc:: Round to integer, towards zero
|
@end menu
|
@end menu
|
|
|
@page
|
@page
|
@node version
|
@node version
|
@section Error Handling
|
@section Error Handling
|
|
|
There are four different versions of the math library routines: IEEE,
|
There are four different versions of the math library routines: IEEE,
|
POSIX, X/Open, or SVID. The version may be selected at runtime by
|
POSIX, X/Open, or SVID. The version may be selected at runtime by
|
setting the global variable @code{_LIB_VERSION}, defined in
|
setting the global variable @code{_LIB_VERSION}, defined in
|
@file{math.h}. It may be set to one of the following constants defined
|
@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
|
in @file{math.h}: @code{_IEEE_}, @code{_POSIX_}, @code{_XOPEN_}, or
|
@code{_SVID_}. The @code{_LIB_VERSION} variable is not specific to any
|
@code{_SVID_}. The @code{_LIB_VERSION} variable is not specific to any
|
thread, and changing it will affect all threads.
|
thread, and changing it will affect all threads.
|
|
|
The versions of the library differ only in how errors are handled.
|
The versions of the library differ only in how errors are handled.
|
|
|
In IEEE mode, the @code{matherr} function is never called, no warning
|
In IEEE mode, the @code{matherr} function is never called, no warning
|
messages are printed, and @code{errno} is never set.
|
messages are printed, and @code{errno} is never set.
|
|
|
In POSIX mode, @code{errno} is set correctly, but the @code{matherr}
|
In POSIX mode, @code{errno} is set correctly, but the @code{matherr}
|
function is never called and no warning messages are printed.
|
function is never called and no warning messages are printed.
|
|
|
In X/Open mode, @code{errno} is set correctly, and @code{matherr} is
|
In X/Open mode, @code{errno} is set correctly, and @code{matherr} is
|
called, but warning message are not printed.
|
called, but warning message are not printed.
|
|
|
In SVID mode, functions which overflow return 3.40282346638528860e+38,
|
In SVID mode, functions which overflow return 3.40282346638528860e+38,
|
the maximum single-precision floating-point value, rather than infinity.
|
the maximum single-precision floating-point value, rather than infinity.
|
Also, @code{errno} is set correctly, @code{matherr} is called, and, if
|
Also, @code{errno} is set correctly, @code{matherr} is called, and, if
|
@code{matherr} returns 0, warning messages are printed for some errors.
|
@code{matherr} returns 0, warning messages are printed for some errors.
|
For example, by default @samp{log(-1.0)} writes this message on standard
|
For example, by default @samp{log(-1.0)} writes this message on standard
|
error output:
|
error output:
|
|
|
@example
|
@example
|
log: DOMAIN error
|
log: DOMAIN error
|
@end example
|
@end example
|
|
|
The library is set to X/Open mode by default.
|
The library is set to X/Open mode by default.
|
|
|
The aforementioned error reporting is the supported Newlib libm error
|
The aforementioned error reporting is the supported Newlib libm error
|
handling method. However, the majority of the functions are written
|
handling method. However, the majority of the functions are written
|
so as to produce the floating-point exceptions (e.g. "invalid",
|
so as to produce the floating-point exceptions (e.g. "invalid",
|
"divide-by-zero") as required by the C and POSIX standards, for
|
"divide-by-zero") as required by the C and POSIX standards, for
|
floating-point implementations that support them. Newlib does not provide
|
floating-point implementations that support them. Newlib does not provide
|
the floating-point exception access routines defined in the standards
|
the floating-point exception access routines defined in the standards
|
for fenv.h, though, which is why they are considered unsupported. It is
|
for fenv.h, though, which is why they are considered unsupported. It is
|
mentioned in case you have separately-provided access routines so that
|
mentioned in case you have separately-provided access routines so that
|
you are aware that they can be caused.
|
you are aware that they can be caused.
|
|
|
@section Standards Compliance And Portability
|
@section Standards Compliance And Portability
|
Most of the individual function descriptions describe the standards to which
|
Most of the individual function descriptions describe the standards to which
|
each function complies. However, these descriptions are mostly out of date,
|
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
|
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
|
around to updating the rest of them. (If you'd like to help, please let us
|
know.)
|
know.)
|
|
|
``C99'' refers to ISO/IEC 9899:1999, ``Programming languages--C''.
|
``C99'' refers to ISO/IEC 9899:1999, ``Programming languages--C''.
|
``POSIX'' refers to IEEE Standard 1003.1. POSIX@registeredsymbol{} is a
|
``POSIX'' refers to IEEE Standard 1003.1. POSIX@registeredsymbol{} is a
|
registered trademark of The IEEE.
|
registered trademark of The IEEE.
|
|
|
@c To sort the include list easily, keep the indentation right because want to
|
@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 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 (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 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 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 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 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 to reflect function name of Bessel (as opposed to j; e.g. after atanh,
|
@c before cbrt).
|
@c before cbrt).
|
|
|
@page @include math/w_acos.def
|
@page @include math/w_acos.def
|
@page @include math/w_acosh.def
|
@page @include math/w_acosh.def
|
@page @include math/w_asin.def
|
@page @include math/w_asin.def
|
@page @include math/s_asinh.def
|
@page @include math/s_asinh.def
|
@page @include math/s_atan.def
|
@page @include math/s_atan.def
|
@page @include math/w_atan2.def
|
@page @include math/w_atan2.def
|
@page @include math/w_atanh.def
|
@page @include math/w_atanh.def
|
@page @include math/w_j0.def
|
@page @include math/w_j0.def
|
@page @include common/s_cbrt.def
|
@page @include common/s_cbrt.def
|
@page @include common/s_copysign.def
|
@page @include common/s_copysign.def
|
@page @include math/w_cosh.def
|
@page @include math/w_cosh.def
|
@page @include math/s_erf.def
|
@page @include math/s_erf.def
|
@page @include math/w_exp.def
|
@page @include math/w_exp.def
|
@page @include math/w_exp2.def
|
@page @include math/w_exp2.def
|
@page @include common/s_expm1.def
|
@page @include common/s_expm1.def
|
@page @include math/s_fabs.def
|
@page @include math/s_fabs.def
|
@page @include common/s_fdim.def
|
@page @include common/s_fdim.def
|
@page @include math/s_floor.def
|
@page @include math/s_floor.def
|
@page @include common/s_fma.def
|
@page @include common/s_fma.def
|
@page @include common/s_fmax.def
|
@page @include common/s_fmax.def
|
@page @include common/s_fmin.def
|
@page @include common/s_fmin.def
|
@page @include math/w_fmod.def
|
@page @include math/w_fmod.def
|
@page @include math/s_frexp.def
|
@page @include math/s_frexp.def
|
@page @include math/w_gamma.def
|
@page @include math/w_gamma.def
|
@page @include math/w_hypot.def
|
@page @include math/w_hypot.def
|
@page @include common/s_ilogb.def
|
@page @include common/s_ilogb.def
|
@page @include common/s_infinity.def
|
@page @include common/s_infinity.def
|
@page @include common/isgreater.def
|
@page @include common/isgreater.def
|
@page @include common/s_isnan.def
|
@page @include common/s_isnan.def
|
@page @include math/s_ldexp.def
|
@page @include math/s_ldexp.def
|
@page @include math/w_log.def
|
@page @include math/w_log.def
|
@page @include math/w_log10.def
|
@page @include math/w_log10.def
|
@page @include common/s_log1p.def
|
@page @include common/s_log1p.def
|
@page @include common/s_log2.def
|
@page @include common/s_log2.def
|
@page @include common/s_logb.def
|
@page @include common/s_logb.def
|
@page @include common/s_lrint.def
|
@page @include common/s_lrint.def
|
@page @include common/s_lround.def
|
@page @include common/s_lround.def
|
@page @include common/s_matherr.def
|
@page @include common/s_matherr.def
|
@page @include common/s_modf.def
|
@page @include common/s_modf.def
|
@page @include common/s_nan.def
|
@page @include common/s_nan.def
|
@page @include common/s_nearbyint.def
|
@page @include common/s_nearbyint.def
|
@page @include common/s_nextafter.def
|
@page @include common/s_nextafter.def
|
@page @include math/w_pow.def
|
@page @include math/w_pow.def
|
@page @include math/w_remainder.def
|
@page @include math/w_remainder.def
|
@page @include common/s_remquo.def
|
@page @include common/s_remquo.def
|
@page @include common/s_rint.def
|
@page @include common/s_rint.def
|
@page @include common/s_round.def
|
@page @include common/s_round.def
|
@page @include common/s_scalbn.def
|
@page @include common/s_scalbn.def
|
@page @include common/s_signbit.def
|
@page @include common/s_signbit.def
|
@page @include math/s_sin.def
|
@page @include math/s_sin.def
|
@page @include math/w_sinh.def
|
@page @include math/w_sinh.def
|
@page @include math/w_sqrt.def
|
@page @include math/w_sqrt.def
|
@page @include math/s_tan.def
|
@page @include math/s_tan.def
|
@page @include math/s_tanh.def
|
@page @include math/s_tanh.def
|
@page @include common/s_trunc.def
|
@page @include common/s_trunc.def
|
|
|
