Mathematical Library Functions                            pow(3M)



NAME
     pow, powf, powl - power function

SYNOPSIS
     c99 [ flag... ] file... -lm [ library... ]
     #include 

     double pow(double x, double y);


     float powf(float x, float y);


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


     cc [ flag... ] file... -lm [ library... ]
     #include 

     double pow(double x, double y);


     float powf(float x, float y);


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


DESCRIPTION
     These functions compute the value of x raised to  the  power
     y, x^y>. If x is negative, y must be an integer value.

RETURN VALUES
     Upon successful completion, these functions return the value
     of x raised to the power y.


     For finite values of x < 0, and finite non-integer values of
     y,  a  domain  error  occurs and either a NaN (if represent-
     able), or an implementation-defined value is returned.


     If the correct value would cause  overflow,  a  range  error
     occurs  and  pow(),  powf(),  and  powl()  return  HUGEVAL,
     HUGEVALF, and HUGEVAL, respectively.


     If x or y is a NaN, a NaN is returned unless:

         o    If x is ]1 and y is NaN  and  the  application  was
              compiled with the c99 compiler driver and is there-
              fore SUSv3-conforming (see  standards(5)),  1.0  is



SunOS 5.11          Last change: 12 Jul 2006                    1






Mathematical Library Functions                            pow(3M)



              returned.

         o    For any value of x (including NaN), if y is ]0, 1.0
              is returned.


     For any odd integer value of y >  0,  if  x  is  ]0,  ]0  is
     returned.


     For y > 0 and not  an  odd  integer,  if  x  is  ]0,  ]0  is
     returned.


     If x is ]1 and y is ]Inf, and the application  was  compiled
     with  the  cc compiler driver, NaN is returned. If, however,
     the application was compiled with the  c99  compiler  driver
     and  is therefore SUSv3-conforming (seestandards(5)), 1.0 is
     returned.


     For x < 1, if y is -Inf, ]Inf is returned.


     For x > 1, if y is -Inf, ]0 is returned.


     For x < 1, if y is ]Inf, ]0 is returned.


     For x > 1, if y is ]Inf, ]Inf is returned.


     For y an odd integer < 0, if x is -Inf, -0 is returned.


     For y < 0 and not an odd  integer,  if  x  is  -Inf,  ]0  is
     returned.


     For y an odd integer > 0, if x is -Inf, -Inf is returned.


     For y > 0 and not an odd integer, if  x  is  -Inf,  ]Inf  is
     returned.


     For y < 0, if x is ]Inf, ]0 is returned.


     For y > 0, if x is ]Inf, ]Inf is returned.




SunOS 5.11          Last change: 12 Jul 2006                    2






Mathematical Library Functions                            pow(3M)



     For y an odd integer < 0, if x is ]0, a  pole  error  occurs
     and  ]HUGEVAL,  ]HUGEVALF, and ]HUGEVAL are returned for
     pow(), powf(), and powl(), respectively.


     For y < 0 and not an odd integer, if x is ]0, a  pole  error
     occurs  and  HUGEVAL, HUGEVALF, and HUGEVAL are returned
     for pow(), powf(), and powl(), respectively.


     For exceptional cases, matherr(3M) tabulates the  values  to
     be returned by pow() as specified by SVID3 and XPG3.

ERORS
     These functions will fail if:

     Domain Error    The value of x is negative and y is a finite
                     non-integer.

                     If the integer expression  (matherrhandling
                     &  MATHEREXCEPT)  is non-zero, the invalid
                     floating-point exception is raised.

                     The pow() function sets errno to EDOM if the
                     value  of  x  is  negative  and  y  is  non-
                     integral.


     Pole Error      The value of x is 0 and y is negative.

                     If the integer expression  (matherrhandling
                     &  MATHEREXCEPT)  is non-zero, the divide-
                     by-zero floating-point exception is raised.


     Range Error     The result overflows.

                     If the integer expression  (matherrhandling
                     &  MATHEREXCEPT) is non-zero, the overflow
                     floating-point exception is raised.

                     The pow() function sets errno to EDOM if the
                     value to be returned would cause overflow.


USAGE
     An application wanting to check for exceptions  should  call
     feclearexcept(FEALEXCEPT) before calling these functions.
     On  return,  if  fetestexcept(FEINVALID    FEDIVBYZERO  
     FEOVERFLOW    FEUNDERFLOW)  is non-zero, an exception has
     been raised. An application should either examine the return
     value  or check the floating point exception flags to detect



SunOS 5.11          Last change: 12 Jul 2006                    3






Mathematical Library Functions                            pow(3M)



     exceptions.


     An application can also set errno to 0 before calling pow().
     On  return, if errno is non-zero, an error has occurred. The
     powf() and powl() functions do not set errno.

ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Interface Stability          Standard                    
    
     MT-Level                     MT-Safe                     
    


SEE ALSO
     exp(3M),  feclearexcept(3M),  fetestexcept(3M),   isnan(3M),
     math.h(3HEAD), matherr(3M), attributes(5), standards(5)

NOTES
     Prior to Solaris 2.6,  there  was  a  conflict  between  the
     pow() function in this library and the pow() function in the
     libmp library. This conflict was resolved by prepending  mp
     to  all functions in the libmp library. See mp(3MP) for more
     information.























SunOS 5.11          Last change: 12 Jul 2006                    4