newlib/libm/mathfp/mathfp.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 Red Hat newlib C 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 * Function acos::       Arccosine
  41 * Function acosh::      Inverse hyperbolic cosine
  42 * Function asin::       Arcsine
  43 * Function asinh::      Inverse hyperbolic sine
  44 * Function atan::       Arctangent
  45 * Function atan2::      Arctangent of y/x
  46 * Function atanh::      Inverse hyperbolic tangent
  47 * Function jN::         Bessel functions  (jN, yN)
  48 * Function cbrt::       Cube root
  49 * Function copysign::   Sign of Y, magnitude of X
  50 * Function cosh::       Hyperbolic cosine
  51 * Function erf::                Error function  (erf, erfc)
  52 * Function exp::                Exponential
  53 * Function expm1::      Exponential of x, - 1
  54 * Function fabs::       Absolute value (magnitude)
  55 * Function floor::      Floor and ceiling  (floor, ceil)
  56 * Function fmod::       Floating-point remainder (modulo)
  57 * Function frexp::      Split floating-point number
  58 * Function gamma::      Logarithmic gamma function
  59 * Function hypot::      Distance from origin
  60 * Function ilogb::      Get exponent
  61 * Function infinity::   Floating infinity
  62 * Function isnan::      Check type of number
  63 * Function ldexp::      Load exponent
  64 * Function log::                Natural logarithms
  65 * Function log10::      Base 10 logarithms
  66 * Function log1p::      Log of 1 + X
  67 * Function matherr::    Modifiable math error handler
  68 * Function modf::       Split fractional and integer parts
  69 * Function nan::                Floating Not a Number
  70 * Function nextafter::  Get next representable number
  71 * Function pow::                X to the power Y
  72 * Function remainder::  remainder of X divided by Y
  73 * Function scalbn::     scalbn
  74 * Function sin::                Sine or cosine (sin, cos)
  75 * Function sinh::       Hyperbolic sine
  76 * Function sqrt::       Positive square root
  77 * Function tan::                Tangent
  78 * Function 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 mathfp/sacos.def
 119
 120 @page
 121 @include mathfp/eacosh.def
 122
 123 @page
 124 @include mathfp/sasine.def
 125
 126 @page
 127 @include mathfp/sasinh.def
 128
 129 @page
 130 @include mathfp/satan.def
 131
 132 @page
 133 @include mathfp/satan2.def
 134
 135 @page
 136 @include mathfp/eatanh.def
 137
 138 @page
 139 @include mathfp/wjn.def
 140
 141 @page
 142 @include common/scbrt.def
 143
 144 @page
 145 @include common/scopysign.def
 146
 147 @page
 148 @include mathfp/scosh.def
 149
 150 @page
 151 @include mathfp/serf.def
 152
 153 @page
 154 @include mathfp/sexp.def
 155
 156 @page
 157 @include common/sexpm1.def
 158
 159 @page
 160 @include mathfp/sfabs.def
 161
 162 @page
 163 @include mathfp/sfloor.def
 164
 165 @page
 166 @include mathfp/sfmod.def
 167
 168 @page
 169 @include mathfp/sfrexp.def
 170
 171 @page
 172 @include mathfp/erlgamma.def
 173
 174 @page
 175 @include mathfp/ehypot.def
 176
 177 @page
 178 @include common/silogb.def
 179
 180 @page
 181 @include common/sinfinity.def
 182
 183 @page
 184 @include common/sisnan.def
 185
 186 @page
 187 @include mathfp/sldexp.def
 188
 189 @page
 190 @include mathfp/slogarithm.def
 191
 192 @page
 193 @include mathfp/slog10.def
 194
 195 @page
 196 @include common/slog1p.def
 197
 198 @page
 199 @include common/smatherr.def
 200
 201 @page
 202 @include common/smodf.def
 203
 204 @page
 205 @include common/snan.def
 206
 207 @page
 208 @include common/snextafter.def
 209
 210 @page
 211 @include mathfp/spow.def
 212
 213 @page
 214 @include mathfp/eremainder.def
 215
 216 @page
 217 @include common/sscalbn.def
 218
 219 @page
 220 @include mathfp/ssqrt.def
 221
 222 @page
 223 @include mathfp/ssine.def
 224
 225 @page
 226 @include mathfp/ssineh.def
 227
 228 @page
 229 @include mathfp/stan.def
 230
 231 @page
 232 @include mathfp/stanh.def