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