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 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" References consulted:
  28 .\"     Linux libc source code
  29 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  30 .\"     386BSD man pages
  31 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  32 .\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no>
  33 .\" Modified 2002-07-27 by Walter Harms
  34 .\"     (walter.harms@informatik.uni-oldenburg.de)
  35 .TH POW 3  2021-03-22 "" "Linux Programmer's Manual"
  36 .SH NAME
  37 pow, powf, powl \- power functions
  38 .SH SYNOPSIS
  39 .nf
  40 .B #include <math.h>
  41 .PP
  42 .BI "double pow(double " x ", double " y );
  43 .BI "float powf(float " x ", float " y );
  44 .BI "long double powl(long double " x ", long double " y );
  45 .fi
  46 .PP
  47 Link with \fI\-lm\fP.
  48 .PP
  49 .RS -4
  50 Feature Test Macro Requirements for glibc (see
  51 .BR feature_test_macros (7)):
  52 .RE
  53 .PP
  54 .BR powf (),
  55 .BR powl ():
  56 .nf
  57     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  58         || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  59         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  60 .fi
  61 .SH DESCRIPTION
  62 These functions return the value of
  63 .I x
  64 raised to the
  65 power of
  66 .IR y .
  67 .SH RETURN VALUE
  68 On success, these functions return the value of
  69 .I x
  70 to the power of
  71 .IR y .
  72 .PP
  73 If
  74 .I x
  75 is a finite value less than 0, and
  76 .I y
  77 is a finite noninteger, a domain error occurs,
  78 .\" The domain error is generated at least as far back as glibc 2.4
  79 and a NaN is returned.
  80 .PP
  81 If the result overflows,
  82 a range error occurs,
  83 .\" The range error is generated at least as far back as glibc 2.4
  84 and the functions return
  85 .BR HUGE_VAL ,
  86 .BR HUGE_VALF ,
  87 or
  88 .BR HUGE_VALL ,
  89 respectively, with the mathematically correct sign.
  90 .PP
  91 If result underflows, and is not representable,
  92 a range error occurs,
  93 and 0.0 is returned.
  94 .\" POSIX.1 does not specify the sign of the zero,
  95 .\" but http://sources.redhat.com/bugzilla/show_bug.cgi?id=2678
  96 .\" points out that the zero has the wrong sign in some cases.
  97 .PP
  98 Except as specified below, if
  99 .I x
 100 or
 101 .I y
 102 is a NaN, the result is a NaN.
 103 .PP
 104 If
 105 .I x
 106 is +1, the result is 1.0 (even if
 107 .I y
 108 is a NaN).
 109 .PP
 110 If
 111 .I y
 112 is 0, the result is 1.0 (even if
 113 .I x
 114 is a NaN).
 115 .PP
 116 If
 117 .I x
 118 is +0 (\-0),
 119 and
 120 .I y
 121 is an odd integer greater than 0,
 122 the result is +0 (\-0).
 123 .PP
 124 If
 125 .I x
 126 is 0,
 127 and
 128 .I y
 129 greater than 0 and not an odd integer,
 130 the result is +0.
 131 .PP
 132 If
 133 .I x
 134 is \-1,
 135 and
 136 .I y
 137 is positive infinity or negative infinity,
 138 the result is 1.0.
 139 .PP
 140 If the absolute value of
 141 .I x
 142 is less than 1,
 143 and
 144 .I y
 145 is negative infinity,
 146 the result is positive infinity.
 147 .PP
 148 If the absolute value of
 149 .I x
 150 is greater than 1,
 151 and
 152 .I y
 153 is negative infinity,
 154 the result is +0.
 155 .PP
 156 If the absolute value of
 157 .I x
 158 is less than 1,
 159 and
 160 .I y
 161 is positive infinity,
 162 the result is +0.
 163 .PP
 164 If the absolute value of
 165 .I x
 166 is greater than 1,
 167 and
 168 .I y
 169 is positive infinity,
 170 the result is positive infinity.
 171 .PP
 172 If
 173 .I x
 174 is negative infinity,
 175 and
 176 .I y
 177 is an odd integer less than 0,
 178 the result is \-0.
 179 .PP
 180 If
 181 .I x
 182 is negative infinity,
 183 and
 184 .I y
 185 less than 0 and not an odd integer,
 186 the result is +0.
 187 .PP
 188 If
 189 .I x
 190 is negative infinity,
 191 and
 192 .I y
 193 is an odd integer greater than 0,
 194 the result is negative infinity.
 195 .PP
 196 If
 197 .I x
 198 is negative infinity,
 199 and
 200 .I y
 201 greater than 0 and not an odd integer,
 202 the result is positive infinity.
 203 .PP
 204 If
 205 .I x
 206 is positive infinity,
 207 and
 208 .I y
 209 less than 0,
 210 the result is +0.
 211 .PP
 212 If
 213 .I x
 214 is positive infinity,
 215 and
 216 .I y
 217 greater than 0,
 218 the result is positive infinity.
 219 .PP
 220 If
 221 .I x
 222 is +0 or \-0,
 223 and
 224 .I y
 225 is an odd integer less than 0,
 226 a pole error occurs and
 227 .BR HUGE_VAL ,
 228 .BR HUGE_VALF ,
 229 or
 230 .BR HUGE_VALL ,
 231 is returned,
 232 with the same sign as
 233 .IR x .
 234 .PP
 235 If
 236 .I x
 237 is +0 or \-0,
 238 and
 239 .I y
 240 is less than 0 and not an odd integer,
 241 a pole error occurs and
 242 .\" The pole error is generated at least as far back as glibc 2.4
 243 .RB + HUGE_VAL ,
 244 .RB + HUGE_VALF ,
 245 or
 246 .RB + HUGE_VALL ,
 247 is returned.
 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 .BR 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 CONFORMING TO
 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 .BR 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)