toolchain/gcc/newlib/libm/math/math.tex

   1 @node Math
   2 @chapter Mathematical Functions (@file{math.h})
   3
   4 This chapter groups a wide variety of mathematical functions.  The
   5 corresponding definitions and declarations are in @file{math.h}.
   6 Two definitions from @file{math.h} are of particular interest.
   7
   8 @enumerate
   9 @item
  10 The representation of infinity as a @code{double} is defined as
  11 @code{HUGE_VAL}; this number is returned on overflow by many functions.
  12
  13 @item
  14 The structure @code{exception} is used when you write customized error
  15 handlers for the mathematical functions.  You can customize error
  16 handling for most of these functions by defining your own version of
  17 @code{matherr}; see the section on @code{matherr} for details.
  18 @end enumerate
  19
  20 @cindex system calls
  21 @cindex support subroutines
  22 @cindex stubs
  23 @cindex OS stubs
  24 Since the error handling code calls @code{fputs}, the mathematical
  25 subroutines require stubs or minimal implementations for the same list
  26 of OS subroutines as @code{fputs}: @code{close}, @code{fstat},
  27 @code{isatty}, @code{lseek}, @code{read}, @code{sbrk}, @code{write}.
  28 @xref{syscalls,,System Calls, libc.info, The Cygnus C Support Library},
  29 for a discussion and for sample minimal implementations of these support
  30 subroutines.
  31
  32 Alternative declarations of the mathematical functions, which exploit
  33 specific machine capabilities to operate faster---but generally have
  34 less error checking and may reflect additional limitations on some
  35 machines---are available when you include @file{fastmath.h} instead of
  36 @file{math.h}.
  37
  38 @menu
  39 * version::     Version of library
  40 * acos::        Arccosine
  41 * acosh::       Inverse hyperbolic cosine
  42 * asin::        Arcsine
  43 * asinh::       Inverse hyperbolic sine
  44 * atan::        Arctangent
  45 * atan2::       Arctangent of y/x
  46 * atanh::       Inverse hyperbolic tangent
  47 * jN::          Bessel functions  (jN, yN)
  48 * cbrt::        Cube root
  49 * copysign::    Sign of Y, magnitude of X
  50 * cosh::        Hyperbolic cosine
  51 * erf::         Error function  (erf, erfc)
  52 * exp::         Exponential
  53 * expm1::       Exponential of x, - 1
  54 * fabs::        Absolute value (magnitude)
  55 * floor::       Floor and ceiling  (floor, ceil)
  56 * fmod::        Floating-point remainder (modulo)
  57 * frexp::       Split floating-point number
  58 * gamma::       Logarithmic gamma function
  59 * hypot::       Distance from origin
  60 * ilogb::       Get exponent
  61 * infinity::    Floating infinity
  62 * isnan::       Check type of number
  63 * ldexp::       Load exponent
  64 * log::         Natural logarithms
  65 * log10::       Base 10 logarithms
  66 * log1p::       Log of 1 + X
  67 * matherr::     Modifiable math error handler
  68 * modf::        Split fractional and integer parts
  69 * nan::         Floating Not a Number
  70 * nextafter::   Get next representable number
  71 * pow::         X to the power Y
  72 * remainder::   remainder of X divided by Y
  73 * scalbn::      scalbn
  74 * sin::         Sine or cosine (sin, cos)
  75 * sinh::        Hyperbolic sine
  76 * sqrt::        Positive square root
  77 * tan::         Tangent
  78 * tanh::        Hyperbolic tangent
  79 @end menu
  80
  81 @page
  82 @node version
  83 @section Version of library
  84
  85 There are four different versions of the math library routines: IEEE,
  86 POSIX, X/Open, or SVID.  The version may be selected at runtime by
  87 setting the global variable @code{_LIB_VERSION}, defined in
  88 @file{math.h}.  It may be set to one of the following constants defined
  89 in @file{math.h}: @code{_IEEE_}, @code{_POSIX_}, @code{_XOPEN_}, or
  90 @code{_SVID_}.  The @code{_LIB_VERSION} variable is not specific to any
  91 thread, and changing it will affect all threads.
  92
  93 The versions of the library differ only in how errors are handled.
  94
  95 In IEEE mode, the @code{matherr} function is never called, no warning
  96 messages are printed, and @code{errno} is never set.
  97
  98 In POSIX mode, @code{errno} is set correctly, but the @code{matherr}
  99 function is never called and no warning messages are printed.
 100
 101 In X/Open mode, @code{errno} is set correctly, and @code{matherr} is
 102 called, but warning message are not printed.
 103
 104 In SVID mode, functions which overflow return 3.40282346638528860e+38,
 105 the maximum single-precision floating-point value, rather than infinity.
 106 Also, @code{errno} is set correctly, @code{matherr} is called, and, if
 107 @code{matherr} returns 0, warning messages are printed for some errors.
 108 For example, by default @samp{log(-1.0)} writes this message on standard
 109 error output:
 110
 111 @example
 112 log: DOMAIN error
 113 @end example
 114
 115 The library is set to X/Open mode by default.
 116
 117 @page
 118 @include math/wacos.def
 119
 120 @page
 121 @include math/wacosh.def
 122
 123 @page
 124 @include math/wasin.def
 125
 126 @page
 127 @include math/sasinh.def
 128
 129 @page
 130 @include math/satan.def
 131
 132 @page
 133 @include math/watan2.def
 134
 135 @page
 136 @include math/watanh.def
 137
 138 @page
 139 @include math/wj0.def
 140
 141 @page
 142 @include math/wcosh.def
 143
 144 @page
 145 @include math/serf.def
 146
 147 @page
 148 @include math/wexp.def
 149
 150 @page
 151 @include math/sfabs.def
 152
 153 @page
 154 @include math/sfloor.def
 155
 156 @page
 157 @include math/wfmod.def
 158
 159 @page
 160 @include math/sfrexp.def
 161
 162 @page
 163 @include math/wgamma.def
 164
 165 @page
 166 @include math/whypot.def
 167
 168 @page
 169 @include math/sisnan.def
 170
 171 @page
 172 @include math/sldexp.def
 173
 174 @page
 175 @include math/wlog.def
 176
 177 @page
 178 @include math/wlog10.def
 179
 180 @page
 181 @include math/wpow.def
 182
 183 @page
 184 @include math/wremainder.def
 185
 186 @page
 187 @include math/wsqrt.def
 188
 189 @page
 190 @include math/ssin.def
 191
 192 @page
 193 @include math/wsinh.def
 194
 195 @page
 196 @include math/stan.def
 197
 198 @page
 199 @include math/stanh.def