C floating point exception handling

Question

The manual pages for fenv.h (feraiseexcept and its ilk) are unusually uninformative; the examples I find online (cppreference.com and others) are very minimal.

How are they supposed to be used? In particular, does feraiseexcept(...) always return? What should one return from a function that gets an illegal argument, like sqrt(-1)? I assume NAN.

Should one get and restore the original state in a function? For example, one might compute a starting point for some iterative algorithm, if that computation turns out inaccurate is of no consequence as presumably, the iteration can converge to full precision.

How should one use this in a program calling e.g. library functions?

(I'd prefer not to have to dive into random math library sources to answer the above.)

Answer 1

The manual pages for fenv.h (feraisexceptionand [its] ilk) are unusually uninformative, the examples I find on line (cppreference.com and others) are very minimal.

<fenv.h> is specified by the C standard. The Unix manual pages are useful only insofar as they extend the C specification. Regard cppreference.com with skepticism; it is known to have errors.

How are they supposed to be used?

Discussing all of <fenv.h> is too broad a question for Stack Overflow.

In particular, does feraisexception(...) always return?

Per C 2018 7.6.2.3 2 and footnote 221, feraiseexcept attempts to cause floating-point exceptions as if they had been generated by arithmetic instructions. Thus, if it raises an exception for which a trap is enabled, it will cause a trap.

In contrast, fesetexceptflag merely sets floating-point exception flags without generating actual exceptions. Per 7.6.2.4 2, “… This function does not raise floating-point exceptions, but only sets the state of the flags.”

What should one return from a function that gets an illegal argument, like sqrt(-1)? I assume NAN.

This is outside the domain of <fenv.h>. sqrt is specified in 7.12, covering <math.h>. Per 7.12.7.5 2, a sqrt domain error occurs if the argument is less than zero. Per 7.12.1, 2, “… On a domain error, the function returns an implementation-defined value…” and it may also set errno and/or raise the “invalid” floating-point exception. Commonly, implementations will return a quiet NaN.

Should one get and restore the original state in a function?

This is up to the person who is specifying or implementing a function. Routines that provide “elementary” mathematical functions, as for the standard math library, may be required to affect the floating-point state only as called for by the ideal function being provided, concealing any internal operations. For example, if log10(100) is implemented by using an engineered polynomial to approximate the logarithm, the evaluation of the polynomial might use arithmetic operations that have very high precision and accuracy, so high that the final result, when rounded to the final format, is exactly two. But the intermediate calculations might involve some operations that were inexact. Thus, the inexact exception would be raised. If the routine merely evaluated the polynomial and returned the exact result, 2, it would have raised the inexact flag. Ideally, the routine would suppress floating-point traps, save the exception flags, do its calculations, restore originally enabled traps, set the proper exception flags if any, and return the result. (Alternately, the routine might be implemented to use only integer arithmetic, avoiding the floating-point issues.)

Outside of specialized library routines, floating-point subroutines rarely go to this extent. It is up to each application how it wants its routines to behave.

For example, one might compute a starting point for some iterative algorithm, if that computation turns out inaccurate is of no consecuence as pressumably the iteration can converge to full precision.

This paragraph is unclear and may be ungrammatical. I am unable to answer it as written.

How should one use this in a program calling e.g. library functions?

This question is unclear, possibly due to the lack of clarity of the preceding paragraph. The antecedent of “this” is unclear.