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