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