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