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$
  30 .\"
  31 .Dd December 21, 2011
  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 exp2l ,
  41 .Nm expm1 ,
  42 .Nm expm1f ,
  43 .Nm pow ,
  44 .Nm powf
  45 .Nd exponential and power functions
  46 .Sh LIBRARY
  47 .Lb libm
  48 .Sh SYNOPSIS
  49 .In math.h
  50 .Ft double
  51 .Fn exp "double x"
  52 .Ft float
  53 .Fn expf "float x"
  54 .Ft double
  55 .Fn exp2 "double x"
  56 .Ft float
  57 .Fn exp2f "float x"
  58 .Ft long double
  59 .Fn exp2l "long double x"
  60 .Ft double
  61 .Fn expm1 "double x"
  62 .Ft float
  63 .Fn expm1f "float x"
  64 .Ft double
  65 .Fn pow "double x" "double y"
  66 .Ft float
  67 .Fn powf "float x" "float y"
  68 .Sh DESCRIPTION
  69 The
  70 .Fn exp
  71 and the
  72 .Fn expf
  73 functions compute the base
  74 .Ms e
  75 exponential value of the given argument
  76 .Fa x .
  77 .Pp
  78 The
  79 .Fn exp2 ,
  80 .Fn exp2f ,
  81 and
  82 .Fn exp2l
  83 functions compute the base 2 exponential of the given argument
  84 .Fa x .
  85 .Pp
  86 The
  87 .Fn expm1
  88 and the
  89 .Fn expm1f
  90 functions compute the value exp(x)\-1 accurately even for tiny argument
  91 .Fa x .
  92 .Pp
  93 The
  94 .Fn pow
  95 and the
  96 .Fn powf
  97 functions compute the value
  98 of
  99 .Ar x
 100 to the exponent
 101 .Ar y .
 102 .Sh ERROR (due to Roundoff etc.)
 103 The values of
 104 .Fn exp 0 ,
 105 .Fn expm1 0 ,
 106 .Fn exp2 integer ,
 107 and
 108 .Fn pow integer integer
 109 are exact provided that they are representable.
 110 .\" XXX Is this really true for pow()?
 111 Otherwise the error in these functions is generally below one
 112 .Em ulp .
 113 .Sh RETURN VALUES
 114 These functions will return the appropriate computation unless an error
 115 occurs or an argument is out of range.
 116 The functions
 117 .Fn pow x y
 118 and
 119 .Fn powf x y
 120 raise an invalid exception and return an \*(Na if
 121 .Fa x
 122 < 0 and
 123 .Fa y
 124 is not an integer.
 125 .Sh NOTES
 126 The function
 127 .Fn pow x 0
 128 returns x**0 = 1 for all x including x = 0, \*(If, and \*(Na .
 129 Previous implementations of pow may
 130 have defined x**0 to be undefined in some or all of these
 131 cases.
 132 Here are reasons for returning x**0 = 1 always:
 133 .Bl -enum -width indent
 134 .It
 135 Any program that already tests whether x is zero (or
 136 infinite or \*(Na) before computing x**0 cannot care
 137 whether 0**0 = 1 or not.
 138 Any program that depends
 139 upon 0**0 to be invalid is dubious anyway since that
 140 expression's meaning and, if invalid, its consequences
 141 vary from one computer system to another.
 142 .It
 143 Some Algebra texts (e.g.\& Sigler's) define x**0 = 1 for
 144 all x, including x = 0.
 145 This is compatible with the convention that accepts a[0]
 146 as the value of polynomial
 147 .Bd -literal -offset indent
 148 p(x) = a[0]\(**x**0 + a[1]\(**x**1 + a[2]\(**x**2 +...+ a[n]\(**x**n
 149 .Ed
 150 .Pp
 151 at x = 0 rather than reject a[0]\(**0**0 as invalid.
 152 .It
 153 Analysts will accept 0**0 = 1 despite that x**y can
 154 approach anything or nothing as x and y approach 0
 155 independently.
 156 The reason for setting 0**0 = 1 anyway is this:
 157 .Bd -ragged -offset indent
 158 If x(z) and y(z) are
 159 .Em any
 160 functions analytic (expandable
 161 in power series) in z around z = 0, and if there
 162 x(0) = y(0) = 0, then x(z)**y(z) \(-> 1 as z \(-> 0.
 163 .Ed
 164 .It
 165 If 0**0 = 1, then
 166 \*(If**0 = 1/0**0 = 1 too; and
 167 then \*(Na**0 = 1 too because x**0 = 1 for all finite
 168 and infinite x, i.e., independently of x.
 169 .El
 170 .Sh SEE ALSO
 171 .Xr fenv 3 ,
 172 .Xr ldexp 3 ,
 173 .Xr log 3 ,
 174 .Xr math 3
 175 .Sh STANDARDS
 176 These functions conform to
 177 .St -isoC-99 .