lib/msun/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. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     from: @(#)exp.3 6.12 (Berkeley) 7/31/91
  33 .\" $FreeBSD: src/lib/msun/man/exp.3,v 1.9.2.4 2001/12/17 10:08:36 ru Exp $
  34 .\"
  35 .Dd July 31, 1991
  36 .Dt EXP 3
  37 .Os
  38 .Sh NAME
  39 .Nm exp ,
  40 .Nm expf ,
  41 .Nm exp10 ,
  42 .Nm exp10f ,
  43 .Nm expm1 ,
  44 .Nm expm1f ,
  45 .Nm log ,
  46 .Nm logf ,
  47 .Nm log10 ,
  48 .Nm log10f ,
  49 .Nm log1p ,
  50 .Nm log1pf ,
  51 .Nm pow ,
  52 .Nm powf
  53 .Nd exponential, logarithm, power functions
  54 .Sh LIBRARY
  55 .Lb libm
  56 .Sh SYNOPSIS
  57 .In math.h
  58 .Ft double
  59 .Fn exp "double x"
  60 .Ft float
  61 .Fn expf "float x"
  62 .Ft double
  63 .Fn expm1 "double x"
  64 .Ft float
  65 .Fn expm1f "float x"
  66 .Ft double
  67 .Fn log "double x"
  68 .Ft float
  69 .Fn logf "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 and the
  86 .Fn expf
  87 functions compute the exponential value of the given argument
  88 .Fa x .
  89 .Pp
  90 The
  91 .Fn expm1
  92 and the
  93 .Fn expm1f
  94 functions compute the value exp(x)\-1 accurately even for tiny argument
  95 .Fa x .
  96 .Pp
  97 The
  98 .Fn log
  99 and the
 100 .Fn logf
 101 functions compute the value of the natural logarithm of argument
 102 .Fa x .
 103 .Pp
 104 The
 105 .Fn log10
 106 and the
 107 .Fn log10f
 108 functions compute the value of the logarithm of argument
 109 .Fa x
 110 to base 10.
 111 .Pp
 112 The
 113 .Fn log1p
 114 and the
 115 .Fn log1pf
 116 functions compute
 117 the value of log(1+x) accurately even for tiny argument
 118 .Fa x .
 119 .Pp
 120 The
 121 .Fn pow
 122 and the
 123 .Fn powf
 124 functions compute the value
 125 of
 126 .Ar x
 127 to the exponent
 128 .Ar y .
 129 .Sh ERROR (due to Roundoff etc.)
 130 .Fn exp x ,
 131 .Fn log x ,
 132 .Fn expm1 x
 133 and
 134 .Fn log1p x
 135 are accurate to within
 136 an
 137 .Em ulp ,
 138 and
 139 .Fn log10 x
 140 to within about 2
 141 .Em ulps ;
 142 an
 143 .Em ulp
 144 is one
 145 .Em Unit
 146 in the
 147 .Em Last
 148 .Em Place .
 149 The error in
 150 .Fn pow x y
 151 is below about 2
 152 .Em ulps
 153 when its
 154 magnitude is moderate, but increases as
 155 .Fn pow x y
 156 approaches
 157 the over/underflow thresholds until almost as many bits could be
 158 lost as are occupied by the floating\-point format's exponent
 159 field; that is 8 bits for
 160 .Tn "VAX D"
 161 and 11 bits for IEEE 754 Double.
 162 No such drastic loss has been exposed by testing; the worst
 163 errors observed have been below 20
 164 .Em ulps
 165 for
 166 .Tn "VAX D" ,
 167 300
 168 .Em ulps
 169 for
 170 .Tn IEEE
 171 754 Double.
 172 Moderate values of
 173 .Fn pow
 174 are accurate enough that
 175 .Fn pow integer integer
 176 is exact until it is bigger than 2**56 on a
 177 .Tn VAX ,
 178 2**53 for
 179 .Tn IEEE
 180 754.
 181 .Sh RETURN VALUES
 182 These functions will return the appropriate computation unless an error
 183 occurs or an argument is out of range.
 184 The functions
 185 .Fn exp ,
 186 .Fn expm1 ,
 187 .Fn pow
 188 detect if the computed value will overflow,
 189 set the global variable
 190 .Va errno
 191 to
 192 .Er ERANGE
 193 and cause a reserved operand fault on a
 194 .Tn VAX
 195 or
 196 .Tn Tahoe .
 197 The functions
 198 .Fn pow x y
 199 checks to see if
 200 .Fa x
 201 < 0 and
 202 .Fa y
 203 is not an integer, in the event this is true,
 204 the global variable
 205 .Va errno
 206 is set to
 207 .Er EDOM
 208 and on the
 209 .Tn VAX
 210 and
 211 .Tn Tahoe
 212 generate a reserved operand fault.
 213 On a
 214 .Tn VAX
 215 and
 216 .Tn Tahoe ,
 217 .Va errno
 218 is set to
 219 .Er EDOM
 220 and the reserved operand is returned
 221 by log unless
 222 .Fa x
 223 > 0, by
 224 .Fn log1p
 225 unless
 226 .Fa x
 227 > \-1.
 228 .Sh NOTES
 229 The functions exp(x)\-1 and log(1+x) are called
 230 expm1 and logp1 in
 231 .Tn BASIC
 232 on the Hewlett\-Packard
 233 .Tn HP Ns \-71B
 234 and
 235 .Tn APPLE
 236 Macintosh,
 237 .Tn EXP1
 238 and
 239 .Tn LN1
 240 in Pascal, exp1 and log1 in C
 241 on
 242 .Tn APPLE
 243 Macintoshes, where they have been provided to make
 244 sure financial calculations of ((1+x)**n\-1)/x, namely
 245 expm1(n\(**log1p(x))/x, will be accurate when x is tiny.
 246 They also provide accurate inverse hyperbolic functions.
 247 .Pp
 248 The function
 249 .Fn pow x 0
 250 returns x**0 = 1 for all x including x = 0,
 251 .if n \
 252 Infinity
 253 .if t \
 254 \(if
 255 (not found on a
 256 .Tn VAX ) ,
 257 and
 258 .Em NaN
 259 (the reserved
 260 operand on a
 261 .Tn VAX ) .
 262 Previous implementations of pow may
 263 have defined x**0 to be undefined in some or all of these
 264 cases.  Here are reasons for returning x**0 = 1 always:
 265 .Bl -enum -width indent
 266 .It
 267 Any program that already tests whether x is zero (or
 268 infinite or \*(Na) before computing x**0 cannot care
 269 whether 0**0 = 1 or not.
 270 Any program that depends
 271 upon 0**0 to be invalid is dubious anyway since that
 272 expression's meaning and, if invalid, its consequences
 273 vary from one computer system to another.
 274 .It
 275 Some Algebra texts (e.g. Sigler's) define x**0 = 1 for
 276 all x, including x = 0.
 277 This is compatible with the convention that accepts a[0]
 278 as the value of polynomial
 279 .Bd -literal -offset indent
 280 p(x) = a[0]\(**x**0 + a[1]\(**x**1 + a[2]\(**x**2 +...+ a[n]\(**x**n
 281 .Ed
 282 .Pp
 283 at x = 0 rather than reject a[0]\(**0**0 as invalid.
 284 .It
 285 Analysts will accept 0**0 = 1 despite that x**y can
 286 approach anything or nothing as x and y approach 0
 287 independently.
 288 The reason for setting 0**0 = 1 anyway is this:
 289 .Bd -ragged -offset indent
 290 If x(z) and y(z) are
 291 .Em any
 292 functions analytic (expandable
 293 in power series) in z around z = 0, and if there
 294 x(0) = y(0) = 0, then x(z)**y(z) \(-> 1 as z \(-> 0.
 295 .Ed
 296 .It
 297 If 0**0 = 1, then
 298 .if n \
 299 infinity**0 = 1/0**0 = 1 too; and
 300 .if t \
 301 \(if**0 = 1/0**0 = 1 too; and
 302 then \*(Na**0 = 1 too because x**0 = 1 for all finite
 303 and infinite x, i.e., independently of x.
 304 .El
 305 .Sh SEE ALSO
 306 .Xr math 3
 307 .Sh HISTORY
 308 A
 309 .Fn exp ,
 310 .Fn log
 311 and
 312 .Fn pow
 313 functions
 314 appeared in
 315 .At v6 .
 316 A
 317 .Fn log10
 318 function
 319 appeared in
 320 .At v7 .
 321 The
 322 .Fn log1p
 323 and
 324 .Fn expm1
 325 functions appeared in
 326 .Bx 4.3 .