summaryrefslogtreecommitdiffstats
path: root/man/man3/pow.3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3/pow.3')
-rw-r--r--man/man3/pow.3383
1 files changed, 383 insertions, 0 deletions
diff --git a/man/man3/pow.3 b/man/man3/pow.3
new file mode 100644
index 000000000..6735d35ba
--- /dev/null
+++ b/man/man3/pow.3
@@ -0,0 +1,383 @@
+'\" t
+.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
+.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
+.\" <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\" Linux libc source code
+.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\" 386BSD man pages
+.\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
+.\" Modified 1995-08-14 by Arnt Gulbrandsen <agulbra@troll.no>
+.\" Modified 2002-07-27 by Walter Harms
+.\" (walter.harms@informatik.uni-oldenburg.de)
+.TH pow 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+pow, powf, powl \- power functions
+.SH LIBRARY
+Math library
+.RI ( libm ", " \-lm )
+.SH SYNOPSIS
+.nf
+.B #include <math.h>
+.P
+.BI "double pow(double " x ", double " y );
+.BI "float powf(float " x ", float " y );
+.BI "long double powl(long double " x ", long double " y );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR powf (),
+.BR powl ():
+.nf
+ _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
+ || /* Since glibc 2.19: */ _DEFAULT_SOURCE
+ || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
+.fi
+.SH DESCRIPTION
+These functions return the value of
+.I x
+raised to the
+power of
+.IR y .
+.SH RETURN VALUE
+On success, these functions return the value of
+.I x
+to the power of
+.IR y .
+.P
+If the result overflows,
+a range error occurs,
+.\" The range error is generated at least as far back as glibc 2.4
+and the functions return
+.BR HUGE_VAL ,
+.BR HUGE_VALF ,
+or
+.BR HUGE_VALL ,
+respectively, with the mathematically correct sign.
+.P
+If result underflows, and is not representable,
+a range error occurs,
+and 0.0 with the appropriate sign is returned.
+.\" POSIX.1 does not specify the sign of the zero,
+.\" but https://www.sourceware.org/bugzilla/show_bug.cgi?id=2678
+.\" points out that the zero has the wrong sign in some cases.
+.P
+.\" pow(\(+-0, <0 [[odd]]) = HUGE_VAL*
+If
+.I x
+is +0 or \-0,
+and
+.I y
+is an odd integer less than 0,
+a pole error occurs and
+.BR HUGE_VAL ,
+.BR HUGE_VALF ,
+or
+.BR HUGE_VALL ,
+is returned,
+with the same sign as
+.IR x .
+.P
+.\" pow(\(+-0, <0 [[!odd]]) = HUGE_VAL*
+If
+.I x
+is +0 or \-0,
+and
+.I y
+is less than 0 and not an odd integer,
+a pole error occurs and
+.\" The pole error is generated at least as far back as glibc 2.4
+.RB + HUGE_VAL ,
+.RB + HUGE_VALF ,
+or
+.RB + HUGE_VALL ,
+is returned.
+.P
+.\" pow(\(+-0, >0 [[odd]]) = \(+-0
+If
+.I x
+is +0 (\-0),
+and
+.I y
+is an odd integer greater than 0,
+the result is +0 (\-0).
+.P
+.\" pow(\(+-0, >0 [[!odd]]) = +0
+If
+.I x
+is 0,
+and
+.I y
+greater than 0 and not an odd integer,
+the result is +0.
+.P
+.\" pow(-1, \(+-INFINITY) = 1.0
+If
+.I x
+is \-1,
+and
+.I y
+is positive infinity or negative infinity,
+the result is 1.0.
+.P
+.\" pow(+1, y) = 1.0
+If
+.I x
+is +1, the result is 1.0 (even if
+.I y
+is a NaN).
+.P
+.\" pow(x, \(+-0) = 1.0
+If
+.I y
+is 0, the result is 1.0 (even if
+.I x
+is a NaN).
+.P
+.\" pow(<0, y) = NaN
+If
+.I x
+is a finite value less than 0, and
+.I y
+is a finite noninteger, a domain error occurs,
+.\" The domain error is generated at least as far back as glibc 2.4
+and a NaN is returned.
+.P
+.\" pow(|x|<1, -INFINITY) = INFINITY
+If the absolute value of
+.I x
+is less than 1,
+and
+.I y
+is negative infinity,
+the result is positive infinity.
+.P
+.\" pow(|x|>1, -INFINITY) = +0
+If the absolute value of
+.I x
+is greater than 1,
+and
+.I y
+is negative infinity,
+the result is +0.
+.P
+.\" pow(|x|<1, INFINITY) = +0
+If the absolute value of
+.I x
+is less than 1,
+and
+.I y
+is positive infinity,
+the result is +0.
+.P
+.\" pow(|x|>1, INFINITY) = INFINITY
+If the absolute value of
+.I x
+is greater than 1,
+and
+.I y
+is positive infinity,
+the result is positive infinity.
+.P
+.\" pow(-INFINITY, <0 [[odd]]) = -0
+If
+.I x
+is negative infinity,
+and
+.I y
+is an odd integer less than 0,
+the result is \-0.
+.P
+.\" pow(-INFINITY, <0 [[!odd]]) = +0
+If
+.I x
+is negative infinity,
+and
+.I y
+less than 0 and not an odd integer,
+the result is +0.
+.P
+.\" pow(-INFINITY, >0 [[odd]]) = -INFINITY
+If
+.I x
+is negative infinity,
+and
+.I y
+is an odd integer greater than 0,
+the result is negative infinity.
+.P
+.\" pow(-INFINITY, >0 [[!odd]]) = INFINITY
+If
+.I x
+is negative infinity,
+and
+.I y
+greater than 0 and not an odd integer,
+the result is positive infinity.
+.P
+.\" pow(INFINITY, <0) = +0
+If
+.I x
+is positive infinity,
+and
+.I y
+less than 0,
+the result is +0.
+.P
+.\" pow(INFINITY, >0) = INFINITY
+If
+.I x
+is positive infinity,
+and
+.I y
+greater than 0,
+the result is positive infinity.
+.P
+.\" pow(NaN, y) or pow(x, NaN) = NaN
+Except as specified above, if
+.I x
+or
+.I y
+is a NaN, the result is a NaN.
+.SH ERRORS
+.\" FIXME . review status of this error
+.\" longstanding bug report for glibc:
+.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=369
+.\" For negative x, and -large and +large y, glibc 2.8 gives incorrect
+.\" results
+.\" pow(-0.5,-DBL_MAX)=nan
+.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
+.\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF)
+.\"
+.\" pow(-1.5,-DBL_MAX)=nan
+.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
+.\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0)
+.\"
+.\" pow(-0.5,DBL_MAX)=nan
+.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
+.\" FAIL (expected: range-error-underflow (ERANGE, FE_UNDERFLOW); +0)
+.\"
+.\" pow(-1.5,DBL_MAX)=nan
+.\" EDOM FE_INVALID nan; fail-errno fail-except fail-result;
+.\" FAIL (expected: range-error-overflow (ERANGE, FE_OVERFLOW); +INF)
+See
+.BR math_error (7)
+for information on how to determine whether an error has occurred
+when calling these functions.
+.P
+The following errors can occur:
+.TP
+Domain error: \fIx\fP is negative, and \fIy\fP is a finite noninteger
+.I errno
+is set to
+.BR EDOM .
+An invalid floating-point exception
+.RB ( FE_INVALID )
+is raised.
+.TP
+Pole error: \fIx\fP is zero, and \fIy\fP is negative
+.I errno
+is set to
+.B ERANGE
+(but see BUGS).
+A divide-by-zero floating-point exception
+.RB ( FE_DIVBYZERO )
+is raised.
+.TP
+Range error: the result overflows
+.I errno
+is set to
+.BR ERANGE .
+An overflow floating-point exception
+.RB ( FE_OVERFLOW )
+is raised.
+.TP
+Range error: the result underflows
+.I errno
+is set to
+.BR ERANGE .
+An underflow floating-point exception
+.RB ( FE_UNDERFLOW )
+is raised.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR pow (),
+.BR powf (),
+.BR powl ()
+T} Thread safety MT-Safe
+.TE
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+C99, POSIX.1-2001.
+.P
+The variant returning
+.I double
+also conforms to
+SVr4, 4.3BSD, C89.
+.SH BUGS
+.SS Historical bugs (now fixed)
+Before glibc 2.28,
+.\" https://sourceware.org/bugzilla/show_bug.cgi?id=13932
+on some architectures (e.g., x86-64)
+.BR pow ()
+may be more than 10,000 times slower for some inputs
+than for other nearby inputs.
+This affects only
+.BR pow (),
+and not
+.BR powf ()
+nor
+.BR powl ().
+This problem was fixed
+.\" commit c3d466cba1692708a19c6ff829d0386c83a0c6e5
+in glibc 2.28.
+.P
+A number of bugs
+.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=3866
+in the glibc implementation of
+.BR pow ()
+were fixed in glibc 2.16.
+.P
+In glibc 2.9 and earlier,
+.\"
+.\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=6776
+when a pole error occurs,
+.I errno
+is set to
+.B EDOM
+instead of the POSIX-mandated
+.BR ERANGE .
+Since glibc 2.10,
+.\" or possibly 2.9, I haven't found the source code change
+.\" and I don't have a 2.9 system to test
+glibc does the right thing.
+.P
+In glibc 2.3.2 and earlier,
+.\" Actually, glibc 2.3.2 is the earliest test result I have; so yet
+.\" to confirm if this error occurs only in glibc 2.3.2.
+when an overflow or underflow error occurs, glibc's
+.BR pow ()
+generates a bogus invalid floating-point exception
+.RB ( FE_INVALID )
+in addition to the overflow or underflow exception.
+.SH SEE ALSO
+.BR cbrt (3),
+.BR cpow (3),
+.BR sqrt (3)
generated by cgit v1.2.3 (git 2.39.1) at 2024-06-01 13:44:26 +0000