| blob | c63f2554d84f27749aee4cf3988e43164d78297a |
1 .\" $OpenBSD: exp.3,v 1.29 2015/01/15 19:06:31 schwarze Exp $
2 .\"
3 .\" Copyright (c) 1985, 1991 Regents of the University of California.
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" from: @(#)exp.3 6.12 (Berkeley) 7/31/91
31 .\"
32 .Dd $Mdocdate: January 15 2015 $
33 .Dt EXP 3
34 .Os
35 .Sh NAME
36 .Nm exp ,
37 .Nm expf ,
38 .Nm expl ,
39 .Nm exp2 ,
40 .Nm exp2f ,
41 .Nm exp2l ,
42 .Nm expm1 ,
43 .Nm expm1f ,
44 .Nm expm1l ,
45 .Nm log ,
46 .Nm logf ,
47 .Nm logl ,
48 .Nm log2 ,
49 .Nm log2f ,
50 .Nm log2l ,
51 .Nm log10 ,
52 .Nm log10f ,
53 .Nm log10l ,
54 .Nm log1p ,
55 .Nm log1pf ,
56 .Nm log1pl ,
57 .Nm pow ,
58 .Nm powf ,
59 .Nm powl
60 .Nd exponential, logarithm, power functions
61 .Sh SYNOPSIS
62 .In math.h
63 .Ft double
64 .Fn exp "double x"
65 .Ft float
66 .Fn expf "float x"
67 .Ft long double
68 .Fn expl "long double x"
69 .Ft double
70 .Fn exp2 "double x"
71 .Ft float
72 .Fn exp2f "float x"
73 .Ft long double
74 .Fn exp2l "long double x"
75 .Ft double
76 .Fn expm1 "double x"
77 .Ft float
78 .Fn expm1f "float x"
79 .Ft long double
80 .Fn expm1l "long double x"
81 .Ft double
82 .Fn log "double x"
83 .Ft float
84 .Fn logf "float x"
85 .Ft long double
86 .Fn logl "long double x"
87 .Ft double
88 .Fn log2 "double x"
89 .Ft float
90 .Fn log2f "float x"
91 .Ft long double
92 .Fn log2l "long double x"
93 .Ft double
94 .Fn log10 "double x"
95 .Ft float
96 .Fn log10f "float x"
97 .Ft long double
98 .Fn log10l "long double x"
99 .Ft double
100 .Fn log1p "double x"
101 .Ft float
102 .Fn log1pf "float x"
103 .Ft long double
104 .Fn log1pl "long double x"
105 .Ft double
106 .Fn pow "double x" "double y"
107 .Ft float
108 .Fn powf "float x" "float y"
109 .Ft long double
110 .Fn powl "long double x" "long double y"
111 .Sh DESCRIPTION
112 The
113 .Fn exp
114 function computes the base
115 .Ms e
116 exponential value of the given argument
117 .Fa x .
118 The
119 .Fn expf
120 function is a single precision version of
121 .Fn exp .
122 The
123 .Fn expl
124 function is an extended precision version of
125 .Fn exp .
126 .Pp
127 The
128 .Fn exp2
129 function computes the base 2 exponential of the given argument
130 .Fa x .
131 The
132 .Fn exp2f
133 function is a single precision version of
134 .Fn exp2 .
135 The
136 .Fn exp2l
137 function is an extended precision version of
138 .Fn exp2 .
139 .Pp
140 The
141 .Fn expm1
142 function computes the value exp(x)\-1 accurately even for tiny argument
143 .Fa x .
144 The
145 .Fn expm1f
146 function is a single precision version of
147 .Fn expm1 .
148 The
149 .Fn expm1l
150 function is an extended precision version of
151 .Fn expm1 .
152 .Pp
153 The
154 .Fn log
155 function computes the value of the natural logarithm of argument
156 .Fa x .
157 The
158 .Fn logf
159 function is a single precision version of
160 .Fn log .
161 The
162 .Fn logl
163 function is an extended precision version of
164 .Fn log .
165 .Pp
166 The
167 .Fn log2
168 function computes the value of the logarithm of argument
169 .Fa x
170 to base 2.
171 The
172 .Fn log2f
173 function is a single precision version of
174 .Fn log2 .
175 The
176 .Fn log2l
177 function is an extended precision version of
178 .Fn log2 .
179 .Pp
180 The
181 .Fn log10
182 function computes the value of the logarithm of argument
183 .Fa x
184 to base 10.
185 The
186 .Fn log10f
187 function is a single precision version of
188 .Fn log10 .
189 The
190 .Fn log10l
191 function is an extended precision version of
192 .Fn log10 .
193 .Pp
194 The
195 .Fn log1p
196 function computes
197 the value of log(1+x) accurately even for tiny argument
198 .Fa x .
199 The
200 .Fn log1pf
201 function is a single precision version of
202 .Fn log1p .
203 The
204 .Fn log1pl
205 function is an extended precision version of
206 .Fn log1p .
207 .Pp
208 The
209 .Fn pow
210 function computes the value of
211 .Ar x
212 to the exponent
213 .Ar y .
214 The
215 .Fn powf
216 function is a single precision version of
217 .Fn pow .
218 The
219 .Fn powl
220 function is an extended precision version of
221 .Fn pow .
222 .Sh RETURN VALUES
223 These functions will return the appropriate computation unless an error
224 occurs or an argument is out of range.
225 The functions
226 .Fn exp ,
227 .Fn expm1
228 and
229 .Fn pow
230 detect if the computed value will overflow,
231 set the global variable
232 .Va errno
233 to
234 .Er ERANGE
235 and cause a reserved operand fault on a VAX or Tahoe.
236 The function
237 .Fn pow x y
238 checks to see if
239 .Fa x
240 < 0 and
241 .Fa y
242 is not an integer, in the event this is true,
243 the global variable
244 .Va errno
245 is set to
246 .Er EDOM
247 and on the VAX and Tahoe generate a reserved operand fault.
248 On a VAX and Tahoe,
249 .Va errno
250 is set to
251 .Er EDOM
252 and the reserved operand is returned
253 by log unless
254 .Fa x
255 > 0, by
256 .Fn log1p
257 unless
258 .Fa x
259 > \-1.
260 .Sh ERRORS (due to Roundoff etc.)
261 exp(x), log(x), expm1(x) and log1p(x) are accurate to within
262 an
263 .Em ulp ,
264 and log10(x) to within about 2
265 .Em ulps ;
266 an
267 .Em ulp
268 is one
269 .Em Unit
270 in the
271 .Em Last
272 .Em Place .
273 The error in
274 .Fn pow x y
275 is below about 2
276 .Em ulps
277 when its
278 magnitude is moderate, but increases as
279 .Fn pow x y
280 approaches
281 the over/underflow thresholds until almost as many bits could be
282 lost as are occupied by the floating\-point format's exponent
283 field; that is 8 bits for
284 .Dq VAX D
285 and 11 bits for IEEE 754 Double.
286 No such drastic loss has been exposed by testing; the worst
287 errors observed have been below 20
288 .Em ulps
289 for
290 .Dq VAX D ,
291 300
292 .Em ulps
293 for IEEE 754 Double.
294 Moderate values of
295 .Fn pow
296 are accurate enough that
297 .Fn pow integer integer
298 is exact until it is bigger than 2**56 on a VAX,
299 2**53 for IEEE 754.
300 .Sh NOTES
301 The functions exp(x)\-1 and log(1+x) are called
302 expm1 and logp1 in BASIC on the Hewlett\-Packard HP-71B
303 and APPLE Macintosh, EXP1 and LN1 in Pascal, exp1 and log1 in C
304 on APPLE Macintoshes, where they have been provided to make
305 sure financial calculations of ((1+x)**n\-1)/x, namely
306 expm1(n\(**log1p(x))/x, will be accurate when x is tiny.
307 They also provide accurate inverse hyperbolic functions.
308 .Pp
309 The function
310 .Fn pow x 0
311 returns x**0 = 1 for all x including x = 0,
312 .if n \
313 \*(If
314 .if t \
315 \(if
316 (not found on a VAX),
317 and
318 .Em \*(Na
319 (the reserved operand on a VAX).
320 Previous implementations of
321 .Fn pow
322 may have defined x**0 to be undefined in some or all of these cases.
323 Here are reasons for returning x**0 = 1 always:
324 .Bl -enum -width indent
325 .It
326 Any program that already tests whether x is zero (or
327 infinite or \*(Na) before computing x**0 cannot care
328 whether 0**0 = 1 or not.
329 Any program that depends upon 0**0 to be invalid is dubious anyway since that
330 expression's meaning and, if invalid, its consequences
331 vary from one computer system to another.
332 .It
333 Some Algebra texts (e.g., Sigler's) define x**0 = 1 for
334 all x, including x = 0.
335 This is compatible with the convention that accepts a[0]
336 as the value of polynomial
337 .Bd -literal -offset indent
338 p(x) = a[0]\(**x**0 + a[1]\(**x**1 + a[2]\(**x**2 +...+ a[n]\(**x**n
339 .Ed
340 .Pp
341 at x = 0 rather than reject a[0]\(**0**0 as invalid.
342 .It
343 Analysts will accept 0**0 = 1 despite that x**y can
344 approach anything or nothing as x and y approach 0
345 independently.
346 The reason for setting 0**0 = 1 anyway is this:
347 .Bd -filled -offset indent
348 If x(z) and y(z) are
349 .Em any
350 functions analytic (expandable
351 in power series) in z around z = 0, and if there
352 x(0) = y(0) = 0, then x(z)**y(z) \(-> 1 as z \(-> 0.
353 .Ed
354 .It
355 If 0**0 = 1, then
356 .if n \
357 \*(If**0 = 1/0**0 = 1 too; and
358 .if t \
359 \(if**0 = 1/0**0 = 1 too; and
360 then \*(Na**0 = 1 too because x**0 = 1 for all finite
361 and infinite x, i.e., independently of x.
362 .El
363 .Sh SEE ALSO
364 .Xr ilogb 3 ,
365 .Xr infnan 3
366 .Sh HISTORY
367 The
368 .Fn exp
369 and
370 .Fn log
371 functions first appeared in
372 .At v1 ;
373 .Fn pow
374 in
375 .At v3 ;
376 .Fn log10
377 in
378 .At v7 ;
379 .Fn log1p
380 and
381 .Fn expm1
382 in
383 .Bx 4.3 .