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  2017-09-15 "" "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 .in -4n
  50 Feature Test Macro Requirements for glibc (see
  51 .BR feature_test_macros (7)):
  52 .in
  53 .PP
  54 .ad l
  55 .BR powf (),
  56 .BR powl ():
  57 .RS 4
  58 _ISOC99_SOURCE || _POSIX_C_SOURCE\ >=\ 200112L
  59     || /* Since glibc 2.19: */ _DEFAULT_SOURCE
  60     || /* Glibc versions <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  61 .RE
  62 .ad
  63 .SH DESCRIPTION
  64 These functions return the value of
  65 .I x
  66 raised to the
  67 power of
  68 .IR y .
  69 .SH RETURN VALUE
  70 On success, these functions return the value of
  71 .I x
  72 to the power of
  73 .IR y .
  74 .PP
  75 If
  76 .I x
  77 is a finite value less than 0, and
  78 .I y
  79 is a finite noninteger, a domain error occurs,
  80 .\" The domain error is generated at least as far back as glibc 2.4
  81 and a NaN is returned.
  82 .PP
  83 If the result overflows,
  84 a range error occurs,
  85 .\" The range error is generated at least as far back as glibc 2.4
  86 and the functions return
  87 .BR HUGE_VAL ,
  88 .BR HUGE_VALF ,
  89 or
  90 .BR HUGE_VALL ,
  91 respectively, with the mathematically correct sign.
  92 .PP
  93 If result underflows, and is not representable,
  94 a range error occurs,
  95 and 0.0 is returned.
  96 .\" POSIX.1 does not specify the sign of the zero,
  97 .\" but http://sources.redhat.com/bugzilla/show_bug.cgi?id=2678
  98 .\" points out that the zero has the wrong sign in some cases.
  99 .PP
 100 Except as specified below, if
 101 .I x
 102 or
 103 .I y
 104 is a NaN, the result is a NaN.
 105 .PP
 106 If
 107 .I x
 108 is +1, the result is 1.0 (even if
 109 .I y
 110 is a NaN).
 111 .PP
 112 If
 113 .I y
 114 is 0, the result is 1.0 (even if
 115 .I x
 116 is a NaN).
 117 .PP
 118 If
 119 .I x
 120 is +0 (\-0),
 121 and
 122 .I y
 123 is an odd integer greater than 0,
 124 the result is +0 (\-0).
 125 .PP
 126 If
 127 .I x
 128 is 0,
 129 and
 130 .I y
 131 greater than 0 and not an odd integer,
 132 the result is +0.
 133 .PP
 134 If
 135 .I x
 136 is \-1,
 137 and
 138 .I y
 139 is positive infinity or negative infinity,
 140 the result is 1.0.
 141 .PP
 142 If the absolute value of
 143 .I x
 144 is less than 1,
 145 and
 146 .I y
 147 is negative infinity,
 148 the result is positive infinity.
 149 .PP
 150 If the absolute value of
 151 .I x
 152 is greater than 1,
 153 and
 154 .I y
 155 is negative infinity,
 156 the result is +0.
 157 .PP
 158 If the absolute value of
 159 .I x
 160 is less than 1,
 161 and
 162 .I y
 163 is positive infinity,
 164 the result is +0.
 165 .PP
 166 If the absolute value of
 167 .I x
 168 is greater than 1,
 169 and
 170 .I y
 171 is positive infinity,
 172 the result is positive infinity.
 173 .PP
 174 If
 175 .I x
 176 is negative infinity,
 177 and
 178 .I y
 179 is an odd integer less than 0,
 180 the result is \-0.
 181 .PP
 182 If
 183 .I x
 184 is negative infinity,
 185 and
 186 .I y
 187 less than 0 and not an odd integer,
 188 the result is +0.
 189 .PP
 190 If
 191 .I x
 192 is negative infinity,
 193 and
 194 .I y
 195 is an odd integer greater than 0,
 196 the result is negative infinity.
 197 .PP
 198 If
 199 .I x
 200 is negative infinity,
 201 and
 202 .I y
 203 greater than 0 and not an odd integer,
 204 the result is positive infinity.
 205 .PP
 206 If
 207 .I x
 208 is positive infinity,
 209 and
 210 .I y
 211 less than 0,
 212 the result is +0.
 213 .PP
 214 If
 215 .I x
 216 is positive infinity,
 217 and
 218 .I y
 219 greater than 0,
 220 the result is positive infinity.
 221 .PP
 222 If
 223 .I x
 224 is +0 or \-0,
 225 and
 226 .I y
 227 is an odd integer less than 0,
 228 a pole error occurs and
 229 .BR HUGE_VAL ,
 230 .BR HUGE_VALF ,
 231 or
 232 .BR HUGE_VALL ,
 233 is returned,
 234 with the same sign as
 235 .IR x .
 236 .PP
 237 If
 238 .I x
 239 is +0 or \-0,
 240 and
 241 .I y
 242 is less than 0 and not an odd integer,
 243 a pole error occurs and
 244 .\" The pole error is generated at least as far back as glibc 2.4
 245 .RB + HUGE_VAL ,
 246 .RB + HUGE_VALF ,
 247 or
 248 .RB + HUGE_VALL ,
 249 is returned.
 250 .SH ERRORS
 251 .\" FIXME . review status of this error
 252 .\" longstanding bug report for glibc:
 253 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=369
 254 .\" For negative x, and -large and +large y, glibc 2.8 gives incorrect
 255 .\" results
 256 .\" pow(-0.5,-DBL_MAX)=nan
 257 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
 258 .\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF)
 259 .\"
 260 .\" pow(-1.5,-DBL_MAX)=nan
 261 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
 262 .\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0)
 263 .\"
 264 .\" pow(-0.5,DBL_MAX)=nan
 265 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
 266 .\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0)
 267 .\"
 268 .\" pow(-1.5,DBL_MAX)=nan
 269 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
 270 .\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF)
 271 See
 272 .BR math_error (7)
 273 for information on how to determine whether an error has occurred
 274 when calling these functions.
 275 .PP
 276 The following errors can occur:
 277 .TP
 278 Domain error: \fIx\fP is negative, and \fIy\fP is a finite noninteger
 279 .I errno
 280 is set to
 281 .BR EDOM .
 282 An invalid floating-point exception
 283 .RB ( FE_INVALID )
 284 is raised.
 285 .TP
 286 Pole error: \fIx\fP is zero, and \fIy\fP is negative
 287 .I errno
 288 is set to
 289 .BR ERANGE
 290 (but see BUGS).
 291 A divide-by-zero floating-point exception
 292 .RB ( FE_DIVBYZERO )
 293 is raised.
 294 .TP
 295 Range error: the result overflows
 296 .I errno
 297 is set to
 298 .BR ERANGE .
 299 An overflow floating-point exception
 300 .RB ( FE_OVERFLOW )
 301 is raised.
 302 .TP
 303 Range error: the result underflows
 304 .I errno
 305 is set to
 306 .BR ERANGE .
 307 An underflow floating-point exception
 308 .RB ( FE_UNDERFLOW )
 309 is raised.
 310 .SH ATTRIBUTES
 311 For an explanation of the terms used in this section, see
 312 .BR attributes (7).
 313 .TS
 314 allbox;
 315 lbw21 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 .SH CONFORMING TO
 325 C99, POSIX.1-2001, POSIX.1-2008.
 326 .PP
 327 The variant returning
 328 .I double
 329 also conforms to
 330 SVr4, 4.3BSD, C89.
 331 .SH BUGS
 332 Before glibc 2.28,
 333 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=13932
 334 on some architectures (e.g., x86-64)
 335 .BR pow ()
 336 may be more than 10,000 times slower for some (rare) inputs
 337 than for other nearby inputs.
 338 This affects only
 339 .BR pow (),
 340 and not
 341 .BR powf ()
 342 nor
 343 .BR powl ().
 344 This problem was fixed
 345 .\" commit c3d466cba1692708a19c6ff829d0386c83a0c6e5
 346 in glibc 2.28.
 347 .PP
 348 In glibc 2.9 and earlier,
 349 .\"
 350 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6776
 351 when a pole error occurs,
 352 .I errno
 353 is set to
 354 .BR EDOM
 355 instead of the POSIX-mandated
 356 .BR ERANGE .
 357 Since version 2.10,
 358 .\" or possibly 2.9, I haven't found the source code change
 359 .\" and I don't have a 2.9 system to test
 360 glibc does the right thing.
 361 .PP
 362 If
 363 .I x
 364 is negative,
 365 then large negative or positive
 366 .I y
 367 values yield a NaN as the function result, with
 368 .I errno
 369 set to
 370 .BR EDOM ,
 371 and an invalid
 372 .RB ( FE_INVALID )
 373 floating-point exception.
 374 For example, with
 375 .BR pow (),
 376 one sees this behavior when the absolute value of
 377 .I y
 378 is greater than about 9.223373e18.
 379 .\" see bug http://sources.redhat.com/bugzilla/show_bug.cgi?id=3866
 380 .\" and http://sources.redhat.com/bugzilla/show_bug.cgi?id=369
 381 .PP
 382 In version 2.3.2 and earlier,
 383 .\" FIXME . Actually, 2.3.2 is the earliest test result I have; so yet
 384 .\" to confirm if this error occurs only in 2.3.2.
 385 when an overflow or underflow error occurs, glibc's
 386 .BR pow ()
 387 generates a bogus invalid floating-point exception
 388 .RB ( FE_INVALID )
 389 in addition to the overflow or underflow exception.
 390 .SH SEE ALSO
 391 .BR cbrt (3),
 392 .BR cpow (3),
 393 .BR sqrt (3)