powf(3) - f39

1pow(3)                     Library Functions Manual                     pow(3)
2
3
4

NAME

6       pow, powf, powl - power functions
7

LIBRARY

9       Math library (libm, -lm)
10

SYNOPSIS

12       #include <math.h>
13
14       double pow(double x, double y);
15       float powf(float x, float y);
16       long double powl(long double x, long double y);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       powf(), powl():
21           _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
22               || /* Since glibc 2.19: */ _DEFAULT_SOURCE
23               || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
24

DESCRIPTION

26       These functions return the value of x raised to the power of y.
27

RETURN VALUE

29       On success, these functions return the value of x to the power of y.
30
31       If the result overflows, a range error occurs, and the functions return
32       HUGE_VAL, HUGE_VALF, or HUGE_VALL, respectively,  with  the  mathemati‐
33       cally correct sign.
34
35       If  result  underflows, and is not representable, a range error occurs,
36       and 0.0 with the appropriate sign is returned.
37
38       If x is +0 or -0, and y is an odd integer less than 0, a pole error oc‐
39       curs  and HUGE_VAL, HUGE_VALF, or HUGE_VALL, is returned, with the same
40       sign as x.
41
42       If x is +0 or -0, and y is less than 0 and not an odd integer,  a  pole
43       error occurs and +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL, is returned.
44
45       If  x is +0 (-0), and y is an odd integer greater than 0, the result is
46       +0 (-0).
47
48       If x is 0, and y greater than 0 and not an odd integer, the  result  is
49       +0.
50
51       If x is -1, and y is positive infinity or negative infinity, the result
52       is 1.0.
53
54       If x is +1, the result is 1.0 (even if y is a NaN).
55
56       If y is 0, the result is 1.0 (even if x is a NaN).
57
58       If x is a finite value less than 0, and y is a finite noninteger, a do‐
59       main error occurs, and a NaN is returned.
60
61       If  the absolute value of x is less than 1, and y is negative infinity,
62       the result is positive infinity.
63
64       If the absolute value of x is greater than 1, and y is negative  infin‐
65       ity, the result is +0.
66
67       If  the absolute value of x is less than 1, and y is positive infinity,
68       the result is +0.
69
70       If the absolute value of x is greater than 1, and y is positive  infin‐
71       ity, the result is positive infinity.
72
73       If x is negative infinity, and y is an odd integer less than 0, the re‐
74       sult is -0.
75
76       If x is negative infinity, and y less than 0 and not  an  odd  integer,
77       the result is +0.
78
79       If  x is negative infinity, and y is an odd integer greater than 0, the
80       result is negative infinity.
81
82       If x is negative infinity, and y greater than 0 and not an odd integer,
83       the result is positive infinity.
84
85       If x is positive infinity, and y less than 0, the result is +0.
86
87       If x is positive infinity, and y greater than 0, the result is positive
88       infinity.
89
90       Except as specified above, if x or y is a NaN, the result is a NaN.
91

ERRORS

93       See math_error(7) for information on how to determine whether an  error
94       has occurred when calling these functions.
95
96       The following errors can occur:
97
98       Domain error: x is negative, and y is a finite noninteger
99              errno  is  set  to  EDOM.   An  invalid floating-point exception
100              (FE_INVALID) is raised.
101
102       Pole error: x is zero, and y is negative
103              errno is set to ERANGE (but see BUGS).  A divide-by-zero  float‐
104              ing-point exception (FE_DIVBYZERO) is raised.
105
106       Range error: the result overflows
107              errno  is  set  to ERANGE.  An overflow floating-point exception
108              (FE_OVERFLOW) is raised.
109
110       Range error: the result underflows
111              errno is set to ERANGE.  An underflow  floating-point  exception
112              (FE_UNDERFLOW) is raised.
113

ATTRIBUTES

115       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
116       tributes(7).
117
118       ┌────────────────────────────────────────────┬───────────────┬─────────┐
119       │Interface                                   │ Attribute     │ Value   │
120       ├────────────────────────────────────────────┼───────────────┼─────────┤
121       │pow(), powf(), powl()                       │ Thread safety │ MT-Safe │
122       └────────────────────────────────────────────┴───────────────┴─────────┘
123

STANDARDS

125       C11, POSIX.1-2008.
126

HISTORY

128       C99, POSIX.1-2001.
129
130       The variant returning double also conforms to SVr4, 4.3BSD, C89.
131

BUGS

133   Historical bugs (now fixed)
134       Before glibc 2.28, on some architectures (e.g., x86-64)  pow()  may  be
135       more  than  10,000  times  slower for some inputs than for other nearby
136       inputs.  This affects only pow(), and  not  powf()  nor  powl().   This
137       problem was fixed in glibc 2.28.
138
139       A  number  of  bugs  in the glibc implementation of pow() were fixed in
140       glibc 2.16.
141
142       In glibc 2.9 and earlier, when a pole error occurs,  errno  is  set  to
143       EDOM  instead  of  the  POSIX-mandated ERANGE.  Since glibc 2.10, glibc
144       does the right thing.
145
146       In glibc 2.3.2 and earlier, when an overflow or underflow error occurs,
147       glibc's  pow()  generates  a  bogus  invalid  floating-point  exception
148       (FE_INVALID) in addition to the overflow or underflow exception.
149