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