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