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