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 .\" 4. 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$
  30 .\"
  31 .Dd April 5, 2005
  32 .Dt EXP 3
  33 .Os
  34 .Sh NAME
  35 .Nm exp ,
  36 .Nm expf ,
  37 .\" The sorting error is intentional.  exp and expf should be adjacent.
  38 .Nm exp2 ,
  39 .Nm exp2f ,
  40 .Nm expm1 ,
  41 .Nm expm1f ,
  42 .Nm log ,
  43 .Nm logf ,
  44 .Nm log10 ,
  45 .Nm log10f ,
  46 .Nm log1p ,
  47 .Nm log1pf ,
  48 .Nm pow ,
  49 .Nm powf
  50 .Nd exponential, logarithm, power functions
  51 .Sh LIBRARY
  52 .Lb libm
  53 .Sh SYNOPSIS
  54 .In math.h
  55 .Ft double
  56 .Fn exp "double x"
  57 .Ft float
  58 .Fn expf "float x"
  59 .Ft double
  60 .Fn exp2 "double x"
  61 .Ft float
  62 .Fn exp2f "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 base
  89 .Ms e
  90 exponential value of the given argument
  91 .Fa x .
  92 .Pp
  93 The
  94 .Fn exp2
  95 and the
  96 .Fn exp2f
  97 functions compute the base 2 exponential of the given argument
  98 .Fa x .
  99 .Pp
 100 The
 101 .Fn expm1
 102 and the
 103 .Fn expm1f
 104 functions compute the value exp(x)\-1 accurately even for tiny argument
 105 .Fa x .
 106 .Pp
 107 The
 108 .Fn log
 109 and the
 110 .Fn logf
 111 functions compute the value of the natural logarithm of argument
 112 .Fa x .
 113 .Pp
 114 The
 115 .Fn log10
 116 and the
 117 .Fn log10f
 118 functions compute the value of the logarithm of argument
 119 .Fa x
 120 to base 10.
 121 .Pp
 122 The
 123 .Fn log1p
 124 and the
 125 .Fn log1pf
 126 functions compute
 127 the value of log(1+x) accurately even for tiny argument
 128 .Fa x .
 129 .Pp
 130 The
 131 .Fn pow
 132 and the
 133 .Fn powf
 134 functions compute the value
 135 of
 136 .Ar x
 137 to the exponent
 138 .Ar y .
 139 .Sh ERROR (due to Roundoff etc.)
 140 The values of
 141 .Fn exp 0 ,
 142 .Fn expm1 0 ,
 143 .Fn exp2 integer ,
 144 and
 145 .Fn pow integer integer
 146 are exact provided that they are representable.
 147 .\" XXX Is this really true for pow()?
 148 Otherwise the error in these functions is generally below one
 149 .Em ulp .
 150 .Sh RETURN VALUES
 151 These functions will return the appropriate computation unless an error
 152 occurs or an argument is out of range.
 153 The functions
 154 .Fn pow x y
 155 and
 156 .Fn powf x y
 157 raise an invalid exception and return an \*(Na if
 158 .Fa x
 159 < 0 and
 160 .Fa y
 161 is not an integer.
 162 An attempt to take the logarithm of \*(Pm0 will result in
 163 a divide-by-zero exception, and an infinity will be returned.
 164 An attempt to take the logarithm of a negative number will
 165 result in an invalid exception, and an \*(Na will be generated.
 166 .Sh NOTES
 167 The functions exp(x)\-1 and log(1+x) are called
 168 expm1 and logp1 in
 169 .Tn BASIC
 170 on the Hewlett\-Packard
 171 .Tn HP Ns \-71B
 172 and
 173 .Tn APPLE
 174 Macintosh,
 175 .Tn EXP1
 176 and
 177 .Tn LN1
 178 in Pascal, exp1 and log1 in C
 179 on
 180 .Tn APPLE
 181 Macintoshes, where they have been provided to make
 182 sure financial calculations of ((1+x)**n\-1)/x, namely
 183 expm1(n\(**log1p(x))/x, will be accurate when x is tiny.
 184 They also provide accurate inverse hyperbolic functions.
 185 .Pp
 186 The function
 187 .Fn pow x 0
 188 returns x**0 = 1 for all x including x = 0, \*(If, and \*(Na .
 189 Previous implementations of pow may
 190 have defined x**0 to be undefined in some or all of these
 191 cases.
 192 Here are reasons for returning x**0 = 1 always:
 193 .Bl -enum -width indent
 194 .It
 195 Any program that already tests whether x is zero (or
 196 infinite or \*(Na) before computing x**0 cannot care
 197 whether 0**0 = 1 or not.
 198 Any program that depends
 199 upon 0**0 to be invalid is dubious anyway since that
 200 expression's meaning and, if invalid, its consequences
 201 vary from one computer system to another.
 202 .It
 203 Some Algebra texts (e.g.\& Sigler's) define x**0 = 1 for
 204 all x, including x = 0.
 205 This is compatible with the convention that accepts a[0]
 206 as the value of polynomial
 207 .Bd -literal -offset indent
 208 p(x) = a[0]\(**x**0 + a[1]\(**x**1 + a[2]\(**x**2 +...+ a[n]\(**x**n
 209 .Ed
 210 .Pp
 211 at x = 0 rather than reject a[0]\(**0**0 as invalid.
 212 .It
 213 Analysts will accept 0**0 = 1 despite that x**y can
 214 approach anything or nothing as x and y approach 0
 215 independently.
 216 The reason for setting 0**0 = 1 anyway is this:
 217 .Bd -ragged -offset indent
 218 If x(z) and y(z) are
 219 .Em any
 220 functions analytic (expandable
 221 in power series) in z around z = 0, and if there
 222 x(0) = y(0) = 0, then x(z)**y(z) \(-> 1 as z \(-> 0.
 223 .Ed
 224 .It
 225 If 0**0 = 1, then
 226 \*(If**0 = 1/0**0 = 1 too; and
 227 then \*(Na**0 = 1 too because x**0 = 1 for all finite
 228 and infinite x, i.e., independently of x.
 229 .El
 230 .Sh SEE ALSO
 231 .Xr fenv 3 ,
 232 .Xr math 3