Debian Codegraph @

upstream/debian-unstable/man3/pow.3

raw
1 '\" t
2 .\" Copyright 1993, David Metcalfe <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH pow 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 pow, powf, powl \- power functions
10 .SH LIBRARY
11 Math library
12 .RI ( libm ,\~ \-lm )
13 .SH SYNOPSIS
14 .nf
15 .B #include <math.h>
16 .P
17 .BI "double pow(double " x ", double " y );
18 .BI "float powf(float " x ", float " y );
19 .BI "long double powl(long double " x ", long double " y );
20 .fi
21 .P
22 .RS -4
23 Feature Test Macro Requirements for glibc (see
24 .BR feature_test_macros (7)):
25 .RE
26 .P
27 .BR powf (),
28 .BR powl ():
29 .nf
30 _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
31 || /* Since glibc 2.19: */ _DEFAULT_SOURCE
32 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
33 .fi
34 .SH DESCRIPTION
35 These functions return the value of
36 .I x
37 raised to the
38 power of
39 .IR y .
40 .SH RETURN VALUE
41 On success, these functions return the value of
42 .I x
43 to the power of
44 .IR y .
45 .P
46 If the result overflows,
47 a range error occurs,
48 .\" The range error is generated at least as far back as glibc 2.4
49 and the functions return
50 .BR HUGE_VAL ,
51 .BR HUGE_VALF ,
52 or
53 .BR HUGE_VALL ,
54 respectively, with the mathematically correct sign.
55 .P
56 If result underflows, and is not representable,
57 a range error occurs,
58 and 0.0 with the appropriate sign is returned.
59 .\" POSIX.1 does not specify the sign of the zero,
60 .\" but https://www.sourceware.org/bugzilla/show_bug.cgi?id=2678
61 .\" points out that the zero has the wrong sign in some cases.
62 .P
63 .\" pow(\(+-0, <0 [[odd]]) = HUGE_VAL*
64 If
65 .I x
66 is +0 or \-0,
67 and
68 .I y
69 is an odd integer less than 0,
70 a pole error occurs and
71 .BR HUGE_VAL ,
72 .BR HUGE_VALF ,
73 or
74 .BR HUGE_VALL ,
75 is returned,
76 with the same sign as
77 .IR x .
78 .P
79 .\" pow(\(+-0, <0 [[!odd]]) = HUGE_VAL*
80 If
81 .I x
82 is +0 or \-0,
83 and
84 .I y
85 is less than 0 and not an odd integer,
86 a pole error occurs and
87 .\" The pole error is generated at least as far back as glibc 2.4
88 .RB + HUGE_VAL ,
89 .RB + HUGE_VALF ,
90 or
91 .RB + HUGE_VALL ,
92 is returned.
93 .P
94 .\" pow(\(+-0, >0 [[odd]]) = \(+-0
95 If
96 .I x
97 is +0 (\-0),
98 and
99 .I y
100 is an odd integer greater than 0,
101 the result is +0 (\-0).
102 .P
103 .\" pow(\(+-0, >0 [[!odd]]) = +0
104 If
105 .I x
106 is 0,
107 and
108 .I y
109 greater than 0 and not an odd integer,
110 the result is +0.
111 .P
112 .\" pow(-1, \(+-INFINITY) = 1.0
113 If
114 .I x
115 is \-1,
116 and
117 .I y
118 is positive infinity or negative infinity,
119 the result is 1.0.
120 .P
121 .\" pow(+1, y) = 1.0
122 If
123 .I x
124 is +1, the result is 1.0 (even if
125 .I y
126 is a NaN).
127 .P
128 .\" pow(x, \(+-0) = 1.0
129 If
130 .I y
131 is 0, the result is 1.0 (even if
132 .I x
133 is a NaN).
134 .P
135 .\" pow(<0, y) = NaN
136 If
137 .I x
138 is a finite value less than 0, and
139 .I y
140 is a finite noninteger, a domain error occurs,
141 .\" The domain error is generated at least as far back as glibc 2.4
142 and a NaN is returned.
143 .P
144 .\" pow(|x|<1, -INFINITY) = INFINITY
145 If the absolute value of
146 .I x
147 is less than 1,
148 and
149 .I y
150 is negative infinity,
151 the result is positive infinity.
152 .P
153 .\" pow(|x|>1, -INFINITY) = +0
154 If the absolute value of
155 .I x
156 is greater than 1,
157 and
158 .I y
159 is negative infinity,
160 the result is +0.
161 .P
162 .\" pow(|x|<1, INFINITY) = +0
163 If the absolute value of
164 .I x
165 is less than 1,
166 and
167 .I y
168 is positive infinity,
169 the result is +0.
170 .P
171 .\" pow(|x|>1, INFINITY) = INFINITY
172 If the absolute value of
173 .I x
174 is greater than 1,
175 and
176 .I y
177 is positive infinity,
178 the result is positive infinity.
179 .P
180 .\" pow(-INFINITY, <0 [[odd]]) = -0
181 If
182 .I x
183 is negative infinity,
184 and
185 .I y
186 is an odd integer less than 0,
187 the result is \-0.
188 .P
189 .\" pow(-INFINITY, <0 [[!odd]]) = +0
190 If
191 .I x
192 is negative infinity,
193 and
194 .I y
195 less than 0 and not an odd integer,
196 the result is +0.
197 .P
198 .\" pow(-INFINITY, >0 [[odd]]) = -INFINITY
199 If
200 .I x
201 is negative infinity,
202 and
203 .I y
204 is an odd integer greater than 0,
205 the result is negative infinity.
206 .P
207 .\" pow(-INFINITY, >0 [[!odd]]) = INFINITY
208 If
209 .I x
210 is negative infinity,
211 and
212 .I y
213 greater than 0 and not an odd integer,
214 the result is positive infinity.
215 .P
216 .\" pow(INFINITY, <0) = +0
217 If
218 .I x
219 is positive infinity,
220 and
221 .I y
222 less than 0,
223 the result is +0.
224 .P
225 .\" pow(INFINITY, >0) = INFINITY
226 If
227 .I x
228 is positive infinity,
229 and
230 .I y
231 greater than 0,
232 the result is positive infinity.
233 .P
234 .\" pow(NaN, y) or pow(x, NaN) = NaN
235 Except as specified above, if
236 .I x
237 or
238 .I y
239 is a NaN, the result is a NaN.
240 .SH ERRORS
241 .\" FIXME . review status of this error
242 .\" longstanding bug report for glibc:
243 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=369
244 .\" For negative x, and -large and +large y, glibc 2.8 gives incorrect
245 .\" results
246 .\" pow(-0.5,-DBL_MAX)=nan
247 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
248 .\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF)
249 .\"
250 .\" pow(-1.5,-DBL_MAX)=nan
251 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
252 .\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0)
253 .\"
254 .\" pow(-0.5,DBL_MAX)=nan
255 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
256 .\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0)
257 .\"
258 .\" pow(-1.5,DBL_MAX)=nan
259 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
260 .\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF)
261 See
262 .BR math_error (7)
263 for information on how to determine whether an error has occurred
264 when calling these functions.
265 .P
266 The following errors can occur:
267 .TP
268 Domain error: \f[I]x\f[] is negative, and \f[I]y\f[] is a finite noninteger
269 .I errno
270 is set to
271 .BR EDOM .
272 An invalid floating-point exception
273 .RB ( FE_INVALID )
274 is raised.
275 .TP
276 Pole error: \f[I]x\f[] is zero, and \f[I]y\f[] is negative
277 .I errno
278 is set to
279 .B ERANGE
280 (but see BUGS).
281 A divide-by-zero floating-point exception
282 .RB ( FE_DIVBYZERO )
283 is raised.
284 .TP
285 Range error: the result overflows
286 .I errno
287 is set to
288 .BR ERANGE .
289 An overflow floating-point exception
290 .RB ( FE_OVERFLOW )
291 is raised.
292 .TP
293 Range error: the result underflows
294 .I errno
295 is set to
296 .BR ERANGE .
297 An underflow floating-point exception
298 .RB ( FE_UNDERFLOW )
299 is raised.
300 .SH ATTRIBUTES
301 For an explanation of the terms used in this section, see
302 .BR attributes (7).
303 .TS
304 allbox;
305 lbx lb lb
306 l l l.
307 Interface Attribute Value
308 T{
309 .na
310 .nh
311 .BR pow (),
312 .BR powf (),
313 .BR powl ()
314 T} Thread safety MT-Safe
315 .TE
316 .SH STANDARDS
317 C11, POSIX.1-2008.
318 .SH HISTORY
319 C99, POSIX.1-2001.
320 .P
321 The variant returning
322 .I double
323 also conforms to
324 SVr4, 4.3BSD, C89.
325 .SH BUGS
326 .SS Historical bugs (now fixed)
327 Before glibc 2.28,
328 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=13932
329 on some architectures (e.g., x86-64)
330 .BR pow ()
331 may be more than 10,000 times slower for some inputs
332 than for other nearby inputs.
333 This affects only
334 .BR pow (),
335 and not
336 .BR powf ()
337 nor
338 .BR powl ().
339 This problem was fixed
340 .\" commit c3d466cba1692708a19c6ff829d0386c83a0c6e5
341 in glibc 2.28.
342 .P
343 A number of bugs
344 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=3866
345 in the glibc implementation of
346 .BR pow ()
347 were fixed in glibc 2.16.
348 .P
349 In glibc 2.9 and earlier,
350 .\"
351 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6776
352 when a pole error occurs,
353 .I errno
354 is set to
355 .B EDOM
356 instead of the POSIX-mandated
357 .BR ERANGE .
358 Since glibc 2.10,
359 .\" or possibly 2.9, I haven't found the source code change
360 .\" and I don't have a 2.9 system to test
361 glibc does the right thing.
362 .P
363 In glibc 2.3.2 and earlier,
364 .\" Actually, glibc 2.3.2 is the earliest test result I have; so yet
365 .\" to confirm if this error occurs only in glibc 2.3.2.
366 when an overflow or underflow error occurs, glibc's
367 .BR pow ()
368 generates a bogus invalid floating-point exception
369 .RB ( FE_INVALID )
370 in addition to the overflow or underflow exception.
371 .SH SEE ALSO
372 .BR cbrt (3),
373 .BR cpow (3),
374 .BR sqrt (3)