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