lib/libm/man/exp.3

   1 .\" Copyright (c) 1985, 1991 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 .\" 3. 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: @(#)exp.3 6.12 (Berkeley) 7/31/91
  29 .\"     $NetBSD: exp.3,v 1.23 2005/07/21 12:58:22 wiz Exp $
  30 .\"     $DragonFly: src/lib/libm/man/exp.3,v 1.2 2007/06/16 22:26:53 pavalos Exp $
  31 .\"
  32 .Dd July 21, 2005
  33 .Dt EXP 3
  34 .Os
  35 .Sh NAME
  36 .Nm exp ,
  37 .Nm expf ,
  38 .Nm expm1 ,
  39 .Nm expm1f ,
  40 .Nm log ,
  41 .Nm logf ,
  42 .Nm log2 ,
  43 .Nm log2f ,
  44 .Nm log10 ,
  45 .Nm log10f ,
  46 .Nm log1p ,
  47 .Nm log1pf ,
  48 .Nm pow ,
  49 .Nm powf
  50 .Nd exponential, logarithm, power functions
  51 .Sh LIBRARY
  52 .Lb libm
  53 .Sh SYNOPSIS
  54 .In math.h
  55 .Ft double
  56 .Fn exp "double x"
  57 .Ft float
  58 .Fn expf "float x"
  59 .Ft double
  60 .Fn expm1 "double x"
  61 .Ft float
  62 .Fn expm1f "float x"
  63 .Ft double
  64 .Fn log "double x"
  65 .Ft float
  66 .Fn logf "float x"
  67 .Ft double
  68 .Fn log2 "double x"
  69 .Ft float
  70 .Fn log2f "float x"
  71 .Ft double
  72 .Fn log10 "double x"
  73 .Ft float
  74 .Fn log10f "float x"
  75 .Ft double
  76 .Fn log1p "double x"
  77 .Ft float
  78 .Fn log1pf "float x"
  79 .Ft double
  80 .Fn pow "double x" "double y"
  81 .Ft float
  82 .Fn powf "float x" "float y"
  83 .Sh DESCRIPTION
  84 The
  85 .Fn exp
  86 function computes the exponential value of the given argument
  87 .Fa x .
  88 .Pp
  89 The
  90 .Fn expm1
  91 function computes the value exp(x)\-1 accurately even for tiny argument
  92 .Fa x .
  93 .Pp
  94 The
  95 .Fn log
  96 function computes the value of the natural logarithm of argument
  97 .Fa x .
  98 .Pp
  99 The
 100 .Fn log10
 101 function computes the value of the logarithm of argument
 102 .Fa x
 103 to base 10.
 104 .Pp
 105 The
 106 .Fn log1p
 107 function computes
 108 the value of log(1+x) accurately even for tiny argument
 109 .Fa x .
 110 .Pp
 111 The
 112 .Fn log2
 113 and the
 114 .Fn log2f
 115 functions compute the value of the logarithm of argument
 116 .Fa x
 117 to base 2.
 118 .Pp
 119 The
 120 .Fn pow
 121 computes the value
 122 of
 123 .Ar x
 124 to the exponent
 125 .Ar y .
 126 .Sh RETURN VALUES
 127 These functions will return the appropriate computation unless an error
 128 occurs or an argument is out of range.
 129 The functions
 130 .Fn exp ,
 131 .Fn expm1
 132 and
 133 .Fn pow
 134 detect if the computed value will overflow,
 135 set the global variable
 136 .Va errno
 137 to
 138 .Er ERANGE
 139 and cause a reserved operand fault on a
 140 .Tn VAX .
 141 The function
 142 .Fn pow x y
 143 checks to see if
 144 .Fa x
 145 \*[Lt] 0 and
 146 .Fa y
 147 is not an integer, in the event this is true,
 148 the global variable
 149 .Va errno
 150 is set to
 151 .Er EDOM
 152 and on the
 153 .Tn VAX
 154 generate a reserved operand fault.
 155 On a
 156 .Tn VAX ,
 157 .Va errno
 158 is set to
 159 .Er EDOM
 160 and the reserved operand is returned
 161 by log unless
 162 .Fa x
 163 \*[Gt] 0, by
 164 .Fn log1p
 165 unless
 166 .Fa x
 167 \*[Gt] \-1.
 168 .Sh ERRORS
 169 exp(x), log(x), expm1(x) and log1p(x) are accurate to within
 170 an
 171 .Em ulp ,
 172 and log10(x) to within about 2
 173 .Em ulps ;
 174 an
 175 .Em ulp
 176 is one
 177 .Em Unit
 178 in the
 179 .Em Last
 180 .Em Place .
 181 The error in
 182 .Fn pow x y
 183 is below about 2
 184 .Em ulps
 185 when its
 186 magnitude is moderate, but increases as
 187 .Fn pow x y
 188 approaches
 189 the over/underflow thresholds until almost as many bits could be
 190 lost as are occupied by the floating\-point format's exponent
 191 field; that is 8 bits for
 192 .Tn "VAX D"
 193 and 11 bits for IEEE 754 Double.
 194 No such drastic loss has been exposed by testing; the worst
 195 errors observed have been below 20
 196 .Em ulps
 197 for
 198 .Tn "VAX D" ,
 199 300
 200 .Em ulps
 201 for
 202 .Tn IEEE
 203 754 Double.
 204 Moderate values of
 205 .Fn pow
 206 are accurate enough that
 207 .Fn pow integer integer
 208 is exact until it is bigger than 2**56 on a
 209 .Tn VAX ,
 210 2**53 for
 211 .Tn IEEE
 212 754.
 213 .Sh NOTES
 214 The functions exp(x)\-1 and log(1+x) are called
 215 expm1 and logp1 in
 216 .Tn BASIC
 217 on the Hewlett\-Packard
 218 .Tn HP Ns \-71B
 219 and
 220 .Tn APPLE
 221 Macintosh,
 222 .Tn EXP1
 223 and
 224 .Tn LN1
 225 in Pascal, exp1 and log1 in C
 226 on
 227 .Tn APPLE
 228 Macintoshes, where they have been provided to make
 229 sure financial calculations of ((1+x)**n\-1)/x, namely
 230 expm1(n\(**log1p(x))/x, will be accurate when x is tiny.
 231 They also provide accurate inverse hyperbolic functions.
 232 .Pp
 233 The function
 234 .Fn pow x 0
 235 returns x**0 = 1 for all x including x = 0,
 236 .if n \
 237 Infinity
 238 .if t \
 239 \(if
 240 (not found on a
 241 .Tn VAX ) ,
 242 and
 243 .Em NaN
 244 (the reserved
 245 operand on a
 246 .Tn VAX ) .
 247 Previous implementations of pow may
 248 have defined x**0 to be undefined in some or all of these
 249 cases.
 250 Here are reasons for returning x**0 = 1 always:
 251 .Bl -enum -width indent
 252 .It
 253 Any program that already tests whether x is zero (or
 254 infinite or \*(Na) before computing x**0 cannot care
 255 whether 0**0 = 1 or not.
 256 Any program that depends
 257 upon 0**0 to be invalid is dubious anyway since that
 258 expression's meaning and, if invalid, its consequences
 259 vary from one computer system to another.
 260 .It
 261 Some Algebra texts (e.g. Sigler's) define x**0 = 1 for
 262 all x, including x = 0.
 263 This is compatible with the convention that accepts a[0]
 264 as the value of polynomial
 265 .Bd -literal -offset indent
 266 p(x) = a[0]\(**x**0 + a[1]\(**x**1 + a[2]\(**x**2 +...+ a[n]\(**x**n
 267 .Ed
 268 .Pp
 269 at x = 0 rather than reject a[0]\(**0**0 as invalid.
 270 .It
 271 Analysts will accept 0**0 = 1 despite that x**y can
 272 approach anything or nothing as x and y approach 0
 273 independently.
 274 The reason for setting 0**0 = 1 anyway is this:
 275 .Bd -filled -offset indent
 276 If x(z) and y(z) are
 277 .Em any
 278 functions analytic (expandable
 279 in power series) in z around z = 0, and if there
 280 x(0) = y(0) = 0, then x(z)**y(z) \(-\*[Gt] 1 as z \(-\*[Gt] 0.
 281 .Ed
 282 .It
 283 If 0**0 = 1, then
 284 .if n \
 285 infinity**0 = 1/0**0 = 1 too; and
 286 .if t \
 287 \(if**0 = 1/0**0 = 1 too; and
 288 then \*(Na**0 = 1 too because x**0 = 1 for all finite
 289 and infinite x, i.e., independently of x.
 290 .El
 291 .Sh SEE ALSO
 292 .Xr math 3
 293 .Sh STANDARDS
 294 The
 295 .Fn exp ,
 296 .Fn log ,
 297 .Fn log10
 298 and
 299 .Fn pow
 300 functions conform to
 301 .St -ansiC .
 302 .Sh HISTORY
 303 A
 304 .Fn exp ,
 305 .Fn log
 306 and
 307 .Fn pow
 308 functions
 309 appeared in
 310 .At v6 .
 311 A
 312 .Fn log10
 313 function
 314 appeared in
 315 .At v7 .
 316 The
 317 .Fn log1p
 318 and
 319 .Fn expm1
 320 functions appeared in
 321 .Bx 4.3 .