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