lib/libm/common_source/exp.3

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