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 53036 1999-11-09 00:18:22Z phantom $
| 33.\" $FreeBSD: head/lib/msun/man/exp.3 57686 2000-03-02 09:14:21Z sheldonh $
|
34.\"
35.Dd July 31, 1991
36.Dt EXP 3
37.Os BSD 4
38.Sh NAME
39.Nm exp ,
40.Nm expf ,
41.Nm exp2 ,
42.Nm exp2f ,
43.Nm exp10 ,
44.Nm exp10f ,
45.Nm expm1 ,
46.Nm expm1f ,
47.Nm log ,
48.Nm logf ,
49.Nm log10 ,
50.Nm log10f ,
51.Nm log1p ,
52.Nm log1pf ,
53.Nm pow ,
54.Nm powf
55.Nd exponential, logarithm, power functions
56.Sh SYNOPSIS
57.Fd #include <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 to
191.Er ERANGE
192and cause a reserved operand fault on a
193.Tn VAX
194or
195.Tn Tahoe .
196The functions
197.Fn pow x y
198checks to see if
199.Fa x
200< 0 and
201.Fa y
202is not an integer, in the event this is true,
203the global variable
204.Va errno
205is set to
206.Er EDOM
207and on the
208.Tn VAX
209and
210.Tn Tahoe
211generate a reserved operand fault.
212On a
213.Tn VAX
214and
215.Tn Tahoe ,
216.Va errno
217is set to
218.Er EDOM
219and the reserved operand is returned
220by log unless
221.Fa x
222> 0, by
223.Fn log1p
224unless
225.Fa x
226> \-1.
227.Sh NOTES
228The functions exp(x)\-1 and log(1+x) are called
229expm1 and logp1 in
230.Tn BASIC
231on the Hewlett\-Packard
232.Tn HP Ns \-71B
233and
234.Tn APPLE
235Macintosh,
236.Tn EXP1
237and
238.Tn LN1
239in Pascal, exp1 and log1 in C
240on
241.Tn APPLE
242Macintoshes, where they have been provided to make
243sure financial calculations of ((1+x)**n\-1)/x, namely
244expm1(n\(**log1p(x))/x, will be accurate when x is tiny.
245They also provide accurate inverse hyperbolic functions.
246.Pp
247The function
248.Fn pow x 0
249returns x**0 = 1 for all x including x = 0,
250.if n \
251Infinity
252.if t \
253\(if
254(not found on a
255.Tn VAX ) ,
256and
257.Em NaN
258(the reserved
259operand on a
260.Tn VAX ) . Previous 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
| 34.\"
35.Dd July 31, 1991
36.Dt EXP 3
37.Os BSD 4
38.Sh NAME
39.Nm exp ,
40.Nm expf ,
41.Nm exp2 ,
42.Nm exp2f ,
43.Nm exp10 ,
44.Nm exp10f ,
45.Nm expm1 ,
46.Nm expm1f ,
47.Nm log ,
48.Nm logf ,
49.Nm log10 ,
50.Nm log10f ,
51.Nm log1p ,
52.Nm log1pf ,
53.Nm pow ,
54.Nm powf
55.Nd exponential, logarithm, power functions
56.Sh SYNOPSIS
57.Fd #include <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 to
191.Er ERANGE
192and cause a reserved operand fault on a
193.Tn VAX
194or
195.Tn Tahoe .
196The functions
197.Fn pow x y
198checks to see if
199.Fa x
200< 0 and
201.Fa y
202is not an integer, in the event this is true,
203the global variable
204.Va errno
205is set to
206.Er EDOM
207and on the
208.Tn VAX
209and
210.Tn Tahoe
211generate a reserved operand fault.
212On a
213.Tn VAX
214and
215.Tn Tahoe ,
216.Va errno
217is set to
218.Er EDOM
219and the reserved operand is returned
220by log unless
221.Fa x
222> 0, by
223.Fn log1p
224unless
225.Fa x
226> \-1.
227.Sh NOTES
228The functions exp(x)\-1 and log(1+x) are called
229expm1 and logp1 in
230.Tn BASIC
231on the Hewlett\-Packard
232.Tn HP Ns \-71B
233and
234.Tn APPLE
235Macintosh,
236.Tn EXP1
237and
238.Tn LN1
239in Pascal, exp1 and log1 in C
240on
241.Tn APPLE
242Macintoshes, where they have been provided to make
243sure financial calculations of ((1+x)**n\-1)/x, namely
244expm1(n\(**log1p(x))/x, will be accurate when x is tiny.
245They also provide accurate inverse hyperbolic functions.
246.Pp
247The function
248.Fn pow x 0
249returns x**0 = 1 for all x including x = 0,
250.if n \
251Infinity
252.if t \
253\(if
254(not found on a
255.Tn VAX ) ,
256and
257.Em NaN
258(the reserved
259operand on a
260.Tn VAX ) . Previous 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. Any program that depends
| 267whether 0**0 = 1 or not.
268Any program that depends
|
268upon 0**0 to be invalid is dubious anyway since that
269expression's meaning and, if invalid, its consequences
270vary from one computer system to another.
271.It
272Some Algebra texts (e.g. Sigler's) define x**0 = 1 for
273all x, including x = 0.
274This is compatible with the convention that accepts a[0]
275as the value of polynomial
276.Bd -literal -offset indent
277p(x) = a[0]\(**x**0 + a[1]\(**x**1 + a[2]\(**x**2 +...+ a[n]\(**x**n
278.Ed
279.Pp
280at x = 0 rather than reject a[0]\(**0**0 as invalid.
281.It
282Analysts will accept 0**0 = 1 despite that x**y can
283approach anything or nothing as x and y approach 0
284independently.
285The reason for setting 0**0 = 1 anyway is this:
286.Bd -filled -offset indent
287If x(z) and y(z) are
288.Em any
289functions analytic (expandable
290in power series) in z around z = 0, and if there
291x(0) = y(0) = 0, then x(z)**y(z) \(-> 1 as z \(-> 0.
292.Ed
293.It
294If 0**0 = 1, then
295.if n \
296infinity**0 = 1/0**0 = 1 too; and
297.if t \
298\(if**0 = 1/0**0 = 1 too; and
299then \*(Na**0 = 1 too because x**0 = 1 for all finite
300and infinite x, i.e., independently of x.
301.El
302.Sh SEE ALSO
303.Xr math 3
304.Sh HISTORY
305A
306.Fn exp ,
307.Fn log
308and
309.Fn pow
310functions
311appeared in
312.At v6 .
313A
314.Fn log10
315function
316appeared in
317.At v7 .
318The
319.Fn log1p
320and
321.Fn expm1
322functions appeared in
323.Bx 4.3 .
| 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 -filled -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 .
|