pow(), powf(), powl()

Raise a number to a given power

Synopsis:

#include <math.h>

double pow( double x, 
            double y );

float powf( float x, 
            float y );

long double powl( long double x,
                  long double y );

Arguments:

x
The number you want to raise.
y
The power you want to raise the number to.

Library:

libm

Use the -l m option to qcc to link against this library.

Description:

The pow(), powf(), and powl() functions compute x raised to the power of y.

A domain error occurs if x = 0, and y is less than or equal to 0, or if x is negative, and y isn't an integer. A range error may also occur.

To check for error situations, use feclearexcept() and fetestexcept():

Returns:

The value of xy.

For finite values of x < 0, and finite non-integer values of y, a domain error occurs, and the functions return NaN.

If the correct value would cause an overflow, a range error occurs, and these functions return ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL, respectively, with the same sign as the correct value of the function.

If the correct value would cause underflow, and is not representable, a range error may occur, and the functions return 0.0.

For y < 0, if x is zero, a pole error may occur, and pow(), powf(), and powl() return ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL, respectively. On systems that support the IEC 60559 Floating-Point option, if x is ±0, a pole error occurs, and these functions return ±HUGE_VAL, ±HUGE_VALF, and ±HUGE_VALL, respectively if y is an odd integer, or HUGE_VAL, HUGE_VALF, and HUGE_VALL, respectively if y isn't an odd integer.

If x is: And y is: These functions return:
+1 Any value, including NaN 1.0
Any value, including NaN ±0 1.0
±0 Any odd integer > 0 ±0
±0 Any non-odd integer > 0 +0
-1 ±Inf 1.0
|x| < 1 -Inf +Inf
|x| > 1 -Inf 0
|x| < 1 +Inf +0
|x| > 1 +Inf +Inf
-Inf An odd integer < 0 -0
-Inf A non-odd integer < 0 +0
-Inf An odd integer > 0 -Inf
-Inf A non-odd integer > 0 +Inf
+Inf < 0 +0
+Inf > 0 +Inf

If x or y is NaN, NaN is returned, except as noted above.

If the correct value would cause an underflow and is representable, a range error may occur, and the correct value is returned.

Examples:

#include <stdio.h>
#include <math.h>
#include <fenv.h>
#include <stdlib.h>

int main( void )
{
    int except_flags;

    feclearexcept(FE_ALL_EXCEPT);

    printf( "%f\n", pow( 1.5, 2.5 ) );

    except_flags = fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW | FE_UNDERFLOW);
    if(except_flags) {
        /* An error occurred; handle it appropriately. */
    }

    return EXIT_SUCCESS;
}

produces the output:

2.755676

Classification:

ANSI, POSIX 1003.1

Safety:  
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes