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 16, 2007
  32 .Dt MATH 3
  33 .Os
  34 .if n \{\
  35 .char \[sr] "sqrt
  36 .\}
  37 .Sh NAME
  38 .Nm math
  39 .Nd "floating-point mathematical library"
  40 .Sh LIBRARY
  41 .Lb libm
  42 .Sh SYNOPSIS
  43 .In math.h
  44 .Sh DESCRIPTION
  45 These functions constitute the C math library.
  46 .Sh "LIST OF FUNCTIONS"
  47 Each of the following
  48 .Vt double
  49 functions has a
  50 .Vt float
  51 counterpart with an
  52 .Ql f
  53 appended to the name and a
  54 .Vt "long double"
  55 counterpart with an
  56 .Ql l
  57 appended.
  58 As an example, the
  59 .Vt float
  60 and
  61 .Vt "long double"
  62 counterparts of
  63 .Ft double
  64 .Fn acos "double x"
  65 are
  66 .Ft float
  67 .Fn acosf "float x"
  68 and
  69 .Ft "long double"
  70 .Fn acosl "long double x" ,
  71 respectively.
  72 The classification macros and silent order predicates are type generic and
  73 should not be suffixed with
  74 .Ql f
  75 or
  76 .Ql l .
  77 .de Cl
  78 .Bl -column "isgreaterequal" "bessel function of the second kind of the order 0"
  79 .Em "Name       Description"
  80 ..
  81 .Ss Algebraic Functions
  82 .Cl
  83 cbrt    cube root
  84 fma     fused multiply-add
  85 hypot   Euclidean distance
  86 sqrt    square root
  87 .El
  88 .Ss Classification Macros
  89 .Cl
  90 fpclassify      classify a floating-point value
  91 isfinite        determine whether a value is finite
  92 isinf   determine whether a value is infinite
  93 isnan   determine whether a value is \*(Na
  94 isnormal        determine whether a value is normalized
  95 .El
  96 .Ss Exponent Manipulation Functions
  97 .Cl
  98 frexp   extract exponent and mantissa
  99 ilogb   extract exponent
 100 ldexp   multiply by power of 2
 101 logb    extract exponent
 102 scalbln adjust exponent
 103 scalbn  adjust exponent
 104 .El
 105 .Ss Extremum- and Sign-Related Functions
 106 .Cl
 107 copysign        copy sign bit
 108 fabs    absolute value
 109 fdim    positive difference
 110 fmax    maximum function
 111 fmin    minimum function
 112 signbit extract sign bit
 113 .El
 114 .Ss Not a Number Functions
 115 .Cl
 116 nan     generate a quiet \*(Na
 117 .El
 118 .Ss Residue and Rounding Functions
 119 .Cl
 120 ceil    integer no less than
 121 floor   integer no greater than
 122 fmod    positive remainder
 123 llrint  round to integer in fixed-point format
 124 llround round to nearest integer in fixed-point format
 125 lrint   round to integer in fixed-point format
 126 lround  round to nearest integer in fixed-point format
 127 modf    extract integer and fractional parts
 128 nearbyint       round to integer (silent)
 129 nextafter       next representable value
 130 nexttoward      next representable value
 131 remainder       remainder
 132 remquo  remainder with partial quotient
 133 rint    round to integer
 134 round   round to nearest integer
 135 trunc   integer no greater in magnitude than
 136 .El
 137 .Pp
 138 The
 139 .Fn ceil ,
 140 .Fn floor ,
 141 .Fn llround ,
 142 .Fn lround ,
 143 .Fn round ,
 144 and
 145 .Fn trunc
 146 functions round in predetermined directions, whereas
 147 .Fn llrint ,
 148 .Fn lrint ,
 149 and
 150 .Fn rint
 151 round according to the current (dynamic) rounding mode.
 152 For more information on controlling the dynamic rounding mode, see
 153 .Xr fenv 3
 154 and
 155 .Xr fesetround 3 .
 156 .Ss Silent Order Predicates
 157 .Cl
 158 isgreater       greater than relation
 159 isgreaterequal  greater than or equal to relation
 160 isless  less than relation
 161 islessequal     less than or equal to relation
 162 islessgreater   less than or greater than relation
 163 isunordered     unordered relation
 164 .El
 165 .Ss Transcendental Functions
 166 .Cl
 167 acos    inverse cosine
 168 acosh   inverse hyperbolic cosine
 169 asin    inverse sine
 170 asinh   inverse hyperbolic sine
 171 atan    inverse tangent
 172 atanh   inverse hyperbolic tangent
 173 atan2   atan(y/x); complex argument
 174 cos     cosine
 175 cosh    hyperbolic cosine
 176 erf     error function
 177 erfc    complementary error function
 178 exp     exponential base e
 179 exp2    exponential base 2
 180 expm1   exp(x)\-1
 181 j0      Bessel function of the first kind of the order 0
 182 j1      Bessel function of the first kind of the order 1
 183 jn      Bessel function of the first kind of the order n
 184 lgamma  log gamma function
 185 log     natural logarithm
 186 log10   logarithm to base 10
 187 log1p   log(1+x)
 188 .\" log2        base 2 logarithm
 189 pow     exponential x**y
 190 sin     trigonometric function
 191 sinh    hyperbolic function
 192 tan     trigonometric function
 193 tanh    hyperbolic function
 194 tgamma  gamma function
 195 y0      Bessel function of the second kind of the order 0
 196 y1      Bessel function of the second kind of the order 1
 197 yn      Bessel function of the second kind of the order n
 198 .El
 199 .Pp
 200 Unlike the algebraic functions listed earlier, the routines
 201 in this section may not produce a result that is correctly rounded,
 202 so reproducible results cannot be guaranteed across platforms.
 203 For most of these functions, however, incorrect rounding occurs
 204 rarely, and then only in very-close-to-halfway cases.
 205 .Sh SEE ALSO
 206 .Xr fenv 3 ,
 207 .Xr ieee 3 ,
 208 .Xr tgmath 3
 209 .Sh HISTORY
 210 A math library with many of the present functions appeared in
 211 .At v7 .
 212 The library was substantially rewritten for
 213 .Bx 4.3
 214 to provide
 215 better accuracy and speed on machines supporting either VAX
 216 or IEEE 754 floating-point.
 217 Most of this library was replaced with FDLIBM, developed at Sun
 218 Microsystems, in
 219 .Fx 1.1.5 .
 220 Additional routines, including ones for
 221 .Vt float
 222 and
 223 .Vt long double
 224 values, were written for or imported into subsequent versions of FreeBSD.
 225 .Sh BUGS
 226 The
 227 .Fn log2
 228 function is missing, and many functions are not available in their
 229 .Vt "long double"
 230 variants.
 231 .Pp
 232 Many of the routines to compute transcendental functions produce
 233 inaccurate results in other than the default rounding mode.
 234 .Pp
 235 On some architectures, trigonometric argument reduction is not
 236 performed accurately, resulting in errors greater than 1
 237 .Em ulp
 238 for large arguments to
 239 .Fn cos ,
 240 .Fn sin ,
 241 and
 242 .Fn tan .