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