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