man3/pow.3

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