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 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  30 .\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no>
  31 .\" Modified 2002-07-27 by Walter Harms
  32 .\"     (walter.harms@informatik.uni-oldenburg.de)
  33 .TH POW 3  2010-09-12 "" "Linux Programmer's Manual"
  34 .SH NAME
  35 pow, powf, powl \- power functions
  36 .SH SYNOPSIS
  37 .nf
  38 .B #include <math.h>
  39 .sp
  40 .BI "double pow(double " x ", double " y );
  41 .br
  42 .BI "float powf(float " x ", float " y );
  43 .br
  44 .BI "long double powl(long double " x ", long double " y );
  45 .fi
  46 .sp
  47 Link with \fI\-lm\fP.
  48 .sp
  49 .in -4n
  50 Feature Test Macro Requirements for glibc (see
  51 .BR feature_test_macros (7)):
  52 .in
  53 .sp
  54 .ad l
  55 .BR powf (),
  56 .BR powl ():
  57 .RS 4
  58 _BSD_SOURCE || _SVID_SOURCE || _XOPEN_SOURCE\ >=\ 600 || _ISOC99_SOURCE ||
  59 _POSIX_C_SOURCE\ >=\ 200112L;
  60 .br
  61 or
  62 .I cc\ -std=c99
  63 .RE
  64 .ad
  65 .SH DESCRIPTION
  66 The
  67 .BR pow ()
  68 function returns the value of \fIx\fP raised to the
  69 power of \fIy\fP.
  70 .SH RETURN VALUE
  71 On success, these functions return the value of
  72 .I x
  73 to the power of
  74 .IR y .
  75
  76 If
  77 .I x
  78 is a finite value less than 0, and
  79 .I y
  80 is a finite noninteger, a domain error occurs,
  81 .\" The domain error is generated at least as far back as glibc 2.4
  82 and a NaN is returned.
  83
  84 If the result overflows,
  85 a range error occurs,
  86 .\" The range error is generated at least as far back as glibc 2.4
  87 and the functions return
  88 .BR HUGE_VAL ,
  89 .BR HUGE_VALF ,
  90 or
  91 .BR HUGE_VALL ,
  92 respectively, with the mathematically correct sign.
  93
  94 If result underflows, and is not representable,
  95 a range error occurs,
  96 and 0.0 is returned.
  97 .\" POSIX.1 does not specify the sign of the zero,
  98 .\" but http://sources.redhat.com/bugzilla/show_bug.cgi?id=2678
  99 .\" points out that the zero has the wrong sign in some cases.
 100
 101 Except as specified below, if
 102 .I x
 103 or
 104 .I y
 105 is a NaN, the result is a NaN.
 106
 107 If
 108 .I x
 109 is +1, the result is 1.0 (even if
 110 .I y
 111 is a NaN).
 112
 113 If
 114 .I y
 115 is 0, the result is 1.0 (even if
 116 .I x
 117 is a NaN).
 118
 119 If
 120 .I x
 121 is +0 (\-0),
 122 and
 123 .I y
 124 is an odd integer greater than 0,
 125 the result is +0 (\-0).
 126
 127 If
 128 .I x
 129 is 0,
 130 and
 131 .I y
 132 greater than 0 and not an odd integer,
 133 the result is +0.
 134
 135 If
 136 .I x
 137 is \-1,
 138 and
 139 .I y
 140 is positive infinity or negative infinity,
 141 the result is 1.0.
 142
 143 If the absolute value of
 144 .I x
 145 is less than 1,
 146 and
 147 .I y
 148 is negative infinity,
 149 the result is positive infinity.
 150
 151 If the absolute value of
 152 .I x
 153 is greater than 1,
 154 and
 155 .I y
 156 is negative infinity,
 157 the result is +0.
 158
 159 If the absolute value of
 160 .I x
 161 is less than 1,
 162 and
 163 .I y
 164 is positive infinity,
 165 the result is +0.
 166
 167 If the absolute value of
 168 .I x
 169 is greater than 1,
 170 and
 171 .I y
 172 is positive infinity,
 173 the result is positive infinity.
 174
 175 If
 176 .I x
 177 is negative infinity,
 178 and
 179 .I y
 180 is an odd integer less than 0,
 181 the result is \-0.
 182
 183 If
 184 .I x
 185 is negative infinity,
 186 and
 187 .I y
 188 less than 0 and not an odd integer,
 189 the result is +0.
 190
 191 If
 192 .I x
 193 is negative infinity,
 194 and
 195 .I y
 196 is an odd integer greater than 0,
 197 the result is negative infinity.
 198
 199 If
 200 .I x
 201 is negative infinity,
 202 and
 203 .I y
 204 greater than 0 and not an odd integer,
 205 the result is positive infinity.
 206
 207 If
 208 .I x
 209 is positive infinity,
 210 and
 211 .I y
 212 less than 0,
 213 the result is +0.
 214
 215 If
 216 .I x
 217 is positive infinity,
 218 and
 219 .I y
 220 greater than 0,
 221 the result is positive infinity.
 222
 223 If
 224 .I x
 225 is +0 or \-0,
 226 and
 227 .I y
 228 is an odd integer less than 0,
 229 a pole error occurs and
 230 .BR HUGE_VAL ,
 231 .BR HUGE_VALF ,
 232 or
 233 .BR HUGE_VALL ,
 234 is returned,
 235 with the same sign as
 236 .IR x .
 237
 238 If
 239 .I x
 240 is +0 or \-0,
 241 and
 242 .I y
 243 is less than 0 and not an odd integer,
 244 a pole error occurs and
 245 .\" The pole error is generated at least as far back as glibc 2.4
 246 .RB + HUGE_VAL ,
 247 .RB + HUGE_VALF ,
 248 or
 249 .RB + HUGE_VALL ,
 250 is returned.
 251 .SH ERRORS
 252 .\" FIXME . review status of this error
 253 .\" longstanding bug report for glibc:
 254 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=369
 255 .\" For negative x, and -large and +large y, glibc 2.8 gives incorrect
 256 .\" results
 257 .\" pow(-0.5,-DBL_MAX)=nan
 258 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
 259 .\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF)
 260 .\"
 261 .\" pow(-1.5,-DBL_MAX)=nan
 262 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
 263 .\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0)
 264 .\"
 265 .\" pow(-0.5,DBL_MAX)=nan
 266 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
 267 .\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0)
 268 .\"
 269 .\" pow(-1.5,DBL_MAX)=nan
 270 .\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
 271 .\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF)
 272 See
 273 .BR math_error (7)
 274 for information on how to determine whether an error has occurred
 275 when calling these functions.
 276 .PP
 277 The following errors can occur:
 278 .TP
 279 Domain error: \fIx\fP is negative, and \fIy\fP is a finite noninteger
 280 .I errno
 281 is set to
 282 .BR EDOM .
 283 An invalid floating-point exception
 284 .RB ( FE_INVALID )
 285 is raised.
 286 .TP
 287 Pole error: \fIx\fP is zero, and \fIy\fP is negative
 288 .I errno
 289 is set to
 290 .BR ERANGE
 291 (but see BUGS).
 292 A divide-by-zero floating-point exception
 293 .RB ( FE_DIVBYZERO )
 294 is raised.
 295 .TP
 296 Range error: the result overflows
 297 .I errno
 298 is set to
 299 .BR ERANGE .
 300 An overflow floating-point exception
 301 .RB ( FE_OVERFLOW )
 302 is raised.
 303 .TP
 304 Range error: the result underflows
 305 .I errno
 306 is set to
 307 .BR ERANGE .
 308 An underflow floating-point exception
 309 .RB ( FE_UNDERFLOW )
 310 is raised.
 311 .SH "CONFORMING TO"
 312 C99, POSIX.1-2001.
 313 The variant returning
 314 .I double
 315 also conforms to
 316 SVr4, 4.3BSD, C89.
 317 .SH BUGS
 318 In glibc 2.9 and earlier,
 319 .\"
 320 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=6776
 321 when a pole error occurs,
 322 .I errno
 323 is set to
 324 .BR EDOM
 325 instead of the POSIX-mandated
 326 .BR ERANGE .
 327 Since version 2.10,
 328 .\" or possibly 2.9, I haven't found the source code change
 329 .\" and I don't have a 2.9 system to test
 330 glibc does the right thing.
 331
 332 If
 333 .I x
 334 is negative,
 335 then large negative or positive
 336 .I y
 337 values yield a NaN as the function result, with
 338 .I errno
 339 set to
 340 .BR EDOM ,
 341 and an invalid
 342 .RB ( FE_INVALID )
 343 floating-point exception.
 344 For example, with
 345 .BR pow (),
 346 one sees this behavior when the absolute value of
 347 .I y
 348 is greater than about 9.223373e18.
 349 .\" see bug http://sources.redhat.com/bugzilla/show_bug.cgi?id=3866
 350 .\" and http://sources.redhat.com/bugzilla/show_bug.cgi?id=369
 351
 352 In version 2.3.2 and earlier,
 353 .\" FIXME . Actually, 2.3.2 is the earliest test result I have; so yet
 354 .\" to confirm if this error occurs only in 2.3.2.
 355 when an overflow or underflow error occurs, glibc's
 356 .BR pow ()
 357 generates a bogus invalid floating-point exception
 358 .RB ( FE_INVALID )
 359 in addition to the overflow or underflow exception.
 360 .SH "SEE ALSO"
 361 .BR cbrt (3),
 362 .BR cpow (3),
 363 .BR sqrt (3)