1@node Math 2@chapter Mathematical Functions (@file{math.h}) 3 4This chapter groups a wide variety of mathematical functions. The 5corresponding definitions and declarations are in @file{math.h}. 6Two definitions from @file{math.h} are of particular interest. 7 8@enumerate 9@item 10The representation of infinity as a @code{double} is defined as 11@code{HUGE_VAL}; this number is returned on overflow by many functions. 12The macro @code{HUGE_VALF} is a corresponding value for @code{float}. 13 14@item 15The structure @code{exception} is used when you write customized error 16handlers for the mathematical functions. You can customize error 17handling for most of these functions by defining your own version of 18@code{matherr}; see the section on @code{matherr} for details. 19@end enumerate 20 21@cindex system calls 22@cindex support subroutines 23@cindex stubs 24@cindex OS stubs 25Since the error handling code calls @code{fputs}, the mathematical 26subroutines require stubs or minimal implementations for the same list 27of OS subroutines as @code{fputs}: @code{close}, @code{fstat}, 28@code{isatty}, @code{lseek}, @code{read}, @code{sbrk}, @code{write}. 29@xref{syscalls,,System Calls, libc.info, The Red Hat newlib C Library}, 30for a discussion and for sample minimal implementations of these support 31subroutines. 32 33Alternative declarations of the mathematical functions, which exploit 34specific machine capabilities to operate faster---but generally have 35less error checking and may reflect additional limitations on some 36machines---are available when you include @file{fastmath.h} instead of 37@file{math.h}. 38 39@menu 40* version:: Version of library 41* acos:: Arccosine 42* acosh:: Inverse hyperbolic cosine 43* asin:: Arcsine 44* asinh:: Inverse hyperbolic sine 45* atan:: Arctangent 46* atan2:: Arctangent of y/x 47* atanh:: Inverse hyperbolic tangent 48* jN:: Bessel functions (jN, yN) 49* cbrt:: Cube root 50* copysign:: Sign of Y, magnitude of X 51* cosh:: Hyperbolic cosine 52* erf:: Error function (erf, erfc) 53* exp:: Exponential, base e 54* exp10:: Exponential, base 10 55* exp2:: Exponential, base 2 56* expm1:: Exponential, base e, of x - 1 57* fabs:: Absolute value (magnitude) 58* fdim:: Positive difference 59* floor:: Floor and ceiling (floor, ceil) 60* fma:: Floating multiply add 61* fmax:: Maximum 62* fmin:: Minimum 63* fmod:: Floating-point remainder (modulo) 64* fpclassify:: Floating-point classification macro 65* frexp:: Split floating-point number 66* gamma:: Logarithmic gamma function 67* hypot:: Distance from origin 68* ilogb:: Get exponent 69* infinity:: Floating infinity 70* isgreater:: Comparison macros 71* ldexp:: Scale by a power of 2 72* log:: Natural logarithms 73* log10:: Base 10 logarithms 74* log1p:: Log of 1 + X 75* log2:: Base 2 logarithms 76* logb:: Get exponent 77* lrint:: Round to integer 78* lround:: Round to integer, away from zero (lround, llround) 79* matherr:: Modifiable math error handler 80* modf:: Split fractional and integer parts 81* nan:: Floating Not a Number 82* nearbyint:: Round to integer 83* nextafter:: Get next representable number 84* pow:: X to the power Y 85* pow10:: 10 to the power X 86* remainder:: remainder of X divided by Y 87* remquo:: Remainder and part of quotient 88* rint:: Round to integer 89* round:: Round to integer, away from zero 90* scalbn:: Scale by a power of FLT_RADIX (2) 91* signbit:: Does floating-point number have negative sign? 92* sin:: Sine or cosine (sin, cos) 93* sinh:: Hyperbolic sine 94* sqrt:: Positive square root 95* tan:: Tangent 96* tanh:: Hyperbolic tangent 97* trunc:: Round to integer, towards zero 98@end menu 99 100@page 101@node version 102@section Error Handling 103 104There are four different versions of the math library routines: IEEE, 105POSIX, X/Open, or SVID. The version may be selected at runtime by 106setting the global variable @code{_LIB_VERSION}, defined in 107@file{math.h}. It may be set to one of the following constants defined 108in @file{math.h}: @code{_IEEE_}, @code{_POSIX_}, @code{_XOPEN_}, or 109@code{_SVID_}. The @code{_LIB_VERSION} variable is not specific to any 110thread, and changing it will affect all threads. 111 112The versions of the library differ only in how errors are handled. 113 114In IEEE mode, the @code{matherr} function is never called, no warning 115messages are printed, and @code{errno} is never set. 116 117In POSIX mode, @code{errno} is set correctly, but the @code{matherr} 118function is never called and no warning messages are printed. 119 120In X/Open mode, @code{errno} is set correctly, and @code{matherr} is 121called, but warning message are not printed. 122 123In SVID mode, functions which overflow return 3.40282346638528860e+38, 124the maximum single-precision floating-point value, rather than infinity. 125Also, @code{errno} is set correctly, @code{matherr} is called, and, if 126@code{matherr} returns 0, warning messages are printed for some errors. 127For example, by default @samp{log(-1.0)} writes this message on standard 128error output: 129 130@example 131log: DOMAIN error 132@end example 133 134The library is set to X/Open mode by default. 135 136The aforementioned error reporting is the supported Newlib libm error 137handling method. However, the majority of the functions are written 138so as to produce the floating-point exceptions (e.g. "invalid", 139"divide-by-zero") as required by the C and POSIX standards, for 140floating-point implementations that support them. Newlib does not provide 141the floating-point exception access routines defined in the standards 142for fenv.h, though, which is why they are considered unsupported. It is 143mentioned in case you have separately-provided access routines so that 144you are aware that they can be caused. 145 146@section Standards Compliance And Portability 147Most of the individual function descriptions describe the standards to which 148each function complies. However, these descriptions are mostly out of date, 149having been written before C99 was released. One of these days we'll get 150around to updating the rest of them. (If you'd like to help, please let us 151know.) 152 153``C99'' refers to ISO/IEC 9899:1999, ``Programming languages--C''. 154``POSIX'' refers to IEEE Standard 1003.1. POSIX@registeredsymbol{} is a 155registered trademark of The IEEE. 156 157@c To sort the include list easily, keep the indentation right because want to 158@c skip the s_|w_ at the start of most--but not all--of the file names. 159@c (e.g., isgreater.def does not have a leading s nor w.) Then, sort 160@c based on the column. For example: "sort -t@ -k3.17" 161@c A few hand-edits might be appropriate after a sort, although not necessary 162@c and are a nuisance as ought to be kept in sync with menu list above: 163@c atan2 after atan, exp2 after exp, log first in log list, and w_j0 to place 164@c to reflect function name of Bessel (as opposed to j; e.g. after atanh, 165@c before cbrt). 166 167@page 168@include math/w_acos.def 169@page 170@include math/w_acosh.def 171@page 172@include math/w_asin.def 173@page 174@include math/s_asinh.def 175@page 176@include math/s_atan.def 177@page 178@include math/w_atan2.def 179@page 180@include math/w_atanh.def 181@page 182@include math/w_j0.def 183@page 184@include common/s_cbrt.def 185@page 186@include common/s_copysign.def 187@page 188@include math/w_cosh.def 189@page 190@include math/s_erf.def 191@page 192@include math/w_exp.def 193@page 194@include common/s_exp10.def 195@page 196@include math/w_exp2.def 197@page 198@include common/s_expm1.def 199@page 200@include math/s_fabs.def 201@page 202@include common/s_fdim.def 203@page 204@include math/s_floor.def 205@page 206@include common/s_fma.def 207@page 208@include common/s_fmax.def 209@page 210@include common/s_fmin.def 211@page 212@include math/w_fmod.def 213@page 214@include math/s_frexp.def 215@page 216@include math/w_gamma.def 217@page 218@include math/w_hypot.def 219@page 220@include common/s_ilogb.def 221@page 222@include common/s_infinity.def 223@page 224@include common/isgreater.def 225@page 226@include common/s_isnan.def 227@page 228@include math/s_ldexp.def 229@page 230@include math/w_log.def 231@page 232@include math/w_log10.def 233@page 234@include common/s_log1p.def 235@page 236@include common/s_log2.def 237@page 238@include common/s_logb.def 239@page 240@include common/s_lrint.def 241@page 242@include common/s_lround.def 243@page 244@include common/s_matherr.def 245@page 246@include common/s_modf.def 247@page 248@include common/s_nan.def 249@page 250@include common/s_nearbyint.def 251@page 252@include common/s_nextafter.def 253@page 254@include math/w_pow.def 255@page 256@include common/s_pow10.def 257@page 258@include math/w_remainder.def 259@page 260@include common/s_remquo.def 261@page 262@include common/s_rint.def 263@page 264@include common/s_round.def 265@page 266@include common/s_scalbn.def 267@page 268@include common/s_signbit.def 269@page 270@include math/s_sin.def 271@page 272@include math/w_sinh.def 273@page 274@include math/w_sqrt.def 275@page 276@include math/s_tan.def 277@page 278@include math/s_tanh.def 279@page 280@include common/s_trunc.def 281