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