lib/msun/man/math.3

   1 .\" Copyright (c) 1985 Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     from: @(#)math.3        6.10 (Berkeley) 5/6/91
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd December 5, 2010
  32 .Dt MATH 3
  33 .Os
  34 .Sh NAME
  35 .Nm math
  36 .Nd "floating-point mathematical library"
  37 .Sh LIBRARY
  38 .Lb libm
  39 .Sh SYNOPSIS
  40 .In math.h
  41 .Sh DESCRIPTION
  42 These functions constitute the C math library.
  43 .Sh "LIST OF FUNCTIONS"
  44 Each of the following
  45 .Vt double
  46 functions has a
  47 .Vt float
  48 counterpart with an
  49 .Ql f
  50 appended to the name and a
  51 .Vt "long double"
  52 counterpart with an
  53 .Ql l
  54 appended.
  55 As an example, the
  56 .Vt float
  57 and
  58 .Vt "long double"
  59 counterparts of
  60 .Ft double
  61 .Fn acos "double x"
  62 are
  63 .Ft float
  64 .Fn acosf "float x"
  65 and
  66 .Ft "long double"
  67 .Fn acosl "long double x" ,
  68 respectively.
  69 The classification macros and silent order predicates are type generic and
  70 should not be suffixed with
  71 .Ql f
  72 or
  73 .Ql l .
  74 .de Cl
  75 .Bl -column "isgreaterequal" "bessel function of the second kind of the order 0"
  76 .Em "Name       Description"
  77 ..
  78 .Ss Algebraic Functions
  79 .Cl
  80 cbrt    cube root
  81 fma     fused multiply-add
  82 hypot   Euclidean distance
  83 sqrt    square root
  84 .El
  85 .Ss Classification Macros
  86 .Cl
  87 fpclassify      classify a floating-point value
  88 isfinite        determine whether a value is finite
  89 isinf   determine whether a value is infinite
  90 isnan   determine whether a value is \*(Na
  91 isnormal        determine whether a value is normalized
  92 .El
  93 .Ss Exponent Manipulation Functions
  94 .Cl
  95 frexp   extract exponent and mantissa
  96 ilogb   extract exponent
  97 ldexp   multiply by power of 2
  98 logb    extract exponent
  99 scalbln adjust exponent
 100 scalbn  adjust exponent
 101 .El
 102 .Ss Extremum- and Sign-Related Functions
 103 .Cl
 104 copysign        copy sign bit
 105 fabs    absolute value
 106 fdim    positive difference
 107 fmax    maximum function
 108 fmin    minimum function
 109 signbit extract sign bit
 110 .El
 111 .Ss Not a Number Functions
 112 .Cl
 113 nan     generate a quiet \*(Na
 114 .El
 115 .Ss Residue and Rounding Functions
 116 .Cl
 117 ceil    integer no less than
 118 floor   integer no greater than
 119 fmod    positive remainder
 120 llrint  round to integer in fixed-point format
 121 llround round to nearest integer in fixed-point format
 122 lrint   round to integer in fixed-point format
 123 lround  round to nearest integer in fixed-point format
 124 modf    extract integer and fractional parts
 125 nearbyint       round to integer (silent)
 126 nextafter       next representable value
 127 nexttoward      next representable value
 128 remainder       remainder
 129 remquo  remainder with partial quotient
 130 rint    round to integer
 131 round   round to nearest integer
 132 trunc   integer no greater in magnitude than
 133 .El
 134 .Pp
 135 The
 136 .Fn ceil ,
 137 .Fn floor ,
 138 .Fn llround ,
 139 .Fn lround ,
 140 .Fn round ,
 141 and
 142 .Fn trunc
 143 functions round in predetermined directions, whereas
 144 .Fn llrint ,
 145 .Fn lrint ,
 146 and
 147 .Fn rint
 148 round according to the current (dynamic) rounding mode.
 149 For more information on controlling the dynamic rounding mode, see
 150 .Xr fenv 3
 151 and
 152 .Xr fesetround 3 .
 153 .Ss Silent Order Predicates
 154 .Cl
 155 isgreater       greater than relation
 156 isgreaterequal  greater than or equal to relation
 157 isless  less than relation
 158 islessequal     less than or equal to relation
 159 islessgreater   less than or greater than relation
 160 isunordered     unordered relation
 161 .El
 162 .Ss Transcendental Functions
 163 .Cl
 164 acos    inverse cosine
 165 acosh   inverse hyperbolic cosine
 166 asin    inverse sine
 167 asinh   inverse hyperbolic sine
 168 atan    inverse tangent
 169 atanh   inverse hyperbolic tangent
 170 atan2   atan(y/x); complex argument
 171 cos     cosine
 172 cosh    hyperbolic cosine
 173 erf     error function
 174 erfc    complementary error function
 175 exp     exponential base e
 176 exp2    exponential base 2
 177 expm1   exp(x)\-1
 178 j0      Bessel function of the first kind of the order 0
 179 j1      Bessel function of the first kind of the order 1
 180 jn      Bessel function of the first kind of the order n
 181 lgamma  log gamma function
 182 log     natural logarithm
 183 log10   logarithm to base 10
 184 log1p   log(1+x)
 185 log2    base 2 logarithm
 186 pow     exponential x**y
 187 sin     trigonometric function
 188 sinh    hyperbolic function
 189 tan     trigonometric function
 190 tanh    hyperbolic function
 191 tgamma  gamma function
 192 y0      Bessel function of the second kind of the order 0
 193 y1      Bessel function of the second kind of the order 1
 194 yn      Bessel function of the second kind of the order n
 195 .El
 196 .Pp
 197 The routines
 198 in this section might not produce a result that is correctly rounded,
 199 so reproducible results cannot be guaranteed across platforms.
 200 For most of these functions, however, incorrect rounding occurs
 201 rarely, and then only in very-close-to-halfway cases.
 202 .Sh SEE ALSO
 203 .Xr fenv 3 ,
 204 .Xr ieee 3 ,
 205 .Xr tgmath 3
 206 .Sh HISTORY
 207 A math library with many of the present functions appeared in
 208 .At v7 .
 209 The library was substantially rewritten for
 210 .Bx 4.3
 211 to provide
 212 better accuracy and speed on machines supporting either VAX
 213 or IEEE 754 floating-point.
 214 Most of this library was replaced with FDLIBM, developed at Sun
 215 Microsystems, in
 216 .Fx 1.1.5 .
 217 Additional routines, including ones for
 218 .Vt float
 219 and
 220 .Vt long double
 221 values, were written for or imported into subsequent versions of FreeBSD.
 222 .Sh BUGS
 223 Some of the
 224 .Vt "long double"
 225 math functions in
 226 .St -isoC-99
 227 are not available.
 228 .Pp
 229 Many of the routines to compute transcendental functions produce
 230 inaccurate results in other than the default rounding mode.
 231 .Pp
 232 On the i386 platform, trigonometric argument reduction is not
 233 performed accurately for huge arguments, resulting in
 234 large errors
 235 for such arguments to
 236 .Fn cos ,
 237 .Fn sin ,
 238 and
 239 .Fn tan .