Page History

Subclause 7.12.1 of the C Standard [ISO/IEC 9899:2011] defines two three types of errors that relate specifically to math functions in math.h:

A domain error occurs if an input argument is outside the domain over which the mathematical function is defined.
A pole error (also known as a singularity or infinitary) occurs if the mathematical function has an exact infinite result as the finite input argument(s) are approached in the limit
A range error occurs if the mathematical result of the function cannot be represented in an object of the specified type, due to extreme magnitude.

An example of a domain error is the square root of a negative number, such as sqrt(-1.0), which has no meaning in real arithmetic. On the other hand, 10 raised to the 1-millionth power, pow(10., 1e6), likely cannot be represented in an implementation's floating-point representation and consequently constitutes a range error. In both cases, the function will return some value, but the value returned is not the correct result of the computation.  An example of a pole error is log(0.0), which results in negative infinity.

Domain and pole errors can be prevented by carefully boundsDomain errors can be prevented by carefully bounds-checking the arguments before calling functions and taking alternative action if the bounds are violated.

...

The following table lists standard mathematical functions, along with any checks that should be performed on their performed to ensure a proper input domain, and indicates whether they can also throw result in range or pole errors, as reported by the C Standard. If a function has a specific domain over which it is defined, the programmer should check its input values, and if a function throws range errors, the programmer should detect whether a range error occurs. The standard math functions not listed in this table, such as atan(), have no domain restrictions and do not throw range cannot result in range or pole errors.

Domain and Pole Checking

The most reliable way to handle domain and pole errors is to prevent them by checking arguments beforehand, as in the following template:

if (/* Arguments that will cause a domain domainor pole error */) {
  /* Handle domain error */
}
 else {
  /* Perform computation */
}

...

The exact treatment of error conditions from math functions is quite complicated. Subclause 7.12.1 of paragraph 5 of the C Standard [ISO/IEC 9899:2011] defines the following behavior for floating-point overflow:

...

It is also difficult to check for math errors using errno because an implementation might not set it. For real functions, the programmer can tell whether the implementation sets errno by checking whether math_errhandling & MATH_ERRNO is nonzero. For complex functions, the C Standard, subclause 7.3.2 paragraph 1, simply states that "an implementation may set errno but is not required to" [ISO/IEC 9899:2011].

...

#include <math.h>
 
void func(double x) {
  double result;

  if (isless(x, 0.0)) {
    /* Handle domain error */
  }

  result = sqrt(x);
}

...

However, this code may produce a domain error if x is negative and y is not an integer or if x is 0 and y is 0. A domain error or range pole error may occur if x is 0 and y is negative, and a range error may occur if the result cannot be represented as a double.

...

Because the pow() function can produce both domain errors and , pole errors and range errors, the programmer must first check that x and y lie within the proper domain and do not generate a pole error, then detect whether a range error occurs and act accordingly:

#include <errno.h>
#include <math.h>
#if defined(math_errhandling) \
  && (math_errhandling & MATH_ERREXCEPT)
#include <fenv.h>
#endif

void func(double x, double y) {
  #if defined(math_errhandling) \
    && (math_errhandling & MATH_ERREXCEPT)
    feclearexcept(FE_ALL_EXCEPT);
  #endif
  errno = 0;

  double result;

  if (((x == 0.f0f) && islessequal(y, 0.0)) || (isless(x, 0).0)) {
    /* Handle domain or pole error */
  }

  result = pow(x, y);

  #if !defined(math_errhandling) \
    || (math_errhandling & MATH_ERRNO)
  if (errno != 0) {
    /* Handle range error */
  }
  #endif
  #if defined(math_errhandling) \
    && (math_errhandling & MATH_ERREXCEPT)
  if (fetestexcept(FE_INVALID
                 | FE_DIVBYZERO
                 | FE_OVERFLOW
                 | FE_UNDERFLOW) != 0) {
    /* Handle range error */
  }
  #endif
}

...

...