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