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