man3/pow.3

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