7.6 Floating-point environment <fenv.h>
7.6.2 Floating-point exceptions
#pragma STDC FENV_ACCESS ON void g(double);
void h(double);
/* ... */
g(x + 1);
h(x + 1);
/* ... */
}
4 If the functiongmight depend on status flags set as a side effect of the firstx + 1, or if the secondx + 1might depend on control modes set as a side effect of the call to functiong, then the program has to contain an appropriately placed invocation of#pragma STDC FENV_ACCESS ONas shown.219)
7.6.2 Floating-point exceptions
1 The following functions provide access to the floating-point status flags.220) Theintinput argument for the functions represents a subset of floating-point exceptions, and can be zero or the bitwise OR of one or more floating-point exception macros, for exampleFE_OVERFLOW | FE_INEXACT. For other argument values, the behavior of these functions is undefined.
7.6.2.1 Thefeclearexceptfunction Synopsis
1 #include <fenv.h>
int feclearexcept(int excepts);
Description
2 Thefeclearexceptfunction attempts to clear the supported floating-point exceptions represented by its argument.
Returns
3 Thefeclearexceptfunction returns zero if theexceptsargument is zero or if all the specified exceptions were successfully cleared. Otherwise, it returns a nonzero value.
7.6.2.2 Thefegetexceptflagfunction Synopsis
1 #include <fenv.h>
int fegetexceptflag(fexcept_t *flagp, int excepts);
219)The side effects impose a temporal ordering that requires two evaluations ofx + 1. On the other hand, without the
#pragma STDC FENV_ACCESS ONpragma, and assuming the default state is "off", just one evaluation ofx + 1would suffice.
220)The functionsfetestexcept,feraiseexcept, andfeclearexceptsupport the basic abstraction of flags that are either set or clear. An implementation can endow floating-point status flags with more information — for example, the address of the code which first raised the floating-point exception; the functionsfegetexceptflagandfesetexceptflagdeal with the full content of flags.
ISO/IEC 9899:20172x::(E) diff:::::::::marks— November 6, 2018 N2310
Description
2 Thefegetexceptflagfunction attempts to store an implementation-defined representation of the states of the floating-point status flags indicated by the argumentexceptsin the object pointed to by the argumentflagp.
Returns
3 Thefegetexceptflagfunction returns zero if the representation was successfully stored. Otherwise, it returns a nonzero value.
7.6.2.3 Theferaiseexceptfunction Synopsis
1 #include <fenv.h>
int feraiseexcept(int excepts);
Description
2 Theferaiseexceptfunction attempts to raise the supported floating-point exceptions represented by its argument.221) The order in which these floating-point exceptions are raised is unspecified, except as stated in F.8.6. Whether theferaiseexceptfunction additionally raises the "inexact"
floating-point exception whenever it raises the "overflow" or "underflow" floating-point exception is implementation-defined.
Returns
3 Theferaiseexceptfunction returns zero if theexceptsargument is zero or if all the specified exceptions were successfully raised. Otherwise, it returns a nonzero value.
7.6.2.4 Thefesetexceptflagfunction Synopsis
1 #include <fenv.h>
int fesetexceptflag(const fexcept_t *flagp, int excepts);
Description
2 Thefesetexceptflag function attempts to set the floating-point status flags indicated by the argumentexceptsto the states stored in the object pointed to byflagp. The value of*flagp shall have been set by a previous call tofegetexceptflagwhose second argument represented at least those floating-point exceptions represented by the argumentexcepts. This function does not raise floating-point exceptions, but only sets the state of the flags.
Returns
3 Thefesetexceptflagfunction returns zero if theexceptsargument is zero or if all the specified flags were successfully set to the appropriate state. Otherwise, it returns a nonzero value.
7.6.2.5 Thefetestexceptfunction Synopsis
1 #include <fenv.h>
int fetestexcept(int excepts);
Description
2 Thefetestexceptfunction determines which of a specified subset of the floating-point excep-tion flags are currently set. Theexceptsargument specifies the floating-point status flags to be queried.222)
221)The effect is intended to be similar to that of floating-point exceptions raised by arithmetic operations. Hence, enabled traps for floating-point exceptions raised by this function are taken. The specification in F.8.6 is in the same spirit.
222)This mechanism allows testing several floating-point exceptions with just one function call.
Returns
3 Thefetestexceptfunction returns the value of the bitwise OR of the floating-point exception macros corresponding to the currently set floating-point exceptions included inexcepts.
4 EXAMPLE Callfif "invalid" is set, thengif "overflow" is set:
#include <fenv.h>
/* ... */
{
#pragma STDC FENV_ACCESS ON int set_excepts;
feclearexcept(FE_INVALID | FE_OVERFLOW);
// maybe raise exceptions
set_excepts = fetestexcept(FE_INVALID | FE_OVERFLOW);
if (set_excepts & FE_INVALID) f();
if (set_excepts & FE_OVERFLOW) g();
/* ... */
}
7.6.3 Rounding
1 Thefegetroundandfesetroundfunctions provide control of rounding direction modes.
7.6.3.1 Thefegetroundfunction Synopsis
1 #include <fenv.h>
int fegetround(void);
Description
2 Thefegetroundfunction gets the current rounding direction.
Returns
3 Thefegetroundfunction returns the value of the rounding direction macro representing the current rounding direction or a negative value if there is no such rounding direction macro or the current rounding direction is not determinable.
7.6.3.2 Thefesetroundfunction Synopsis
1 #include <fenv.h>
int fesetround(int round);
Description
2 Thefesetroundfunction establishes the rounding direction represented by its argumentround. If the argument is not equal to the value of a rounding direction macro, the rounding direction is not changed.
Returns
3 Thefesetroundfunction returns zero if and only if the requested rounding direction was estab-lished.
4 EXAMPLE Save, set, and restore the rounding direction. Report an error and abort if setting the rounding direction fails.
#include <fenv.h>
#include <assert.h>
void f(int round_dir) {
#pragma STDC FENV_ACCESS ON int save_round;
ISO/IEC 9899:20172x::(E) diff:::::::::marks— November 6, 2018 N2310
int setround_ok;
save_round = fegetround();
setround_ok = fesetround(round_dir);
assert(setround_ok == 0);
/* ... */
fesetround(save_round);
/* ... */
}
7.6.4 Environment
1 The functions in this section manage the floating-point environment — status flags and control modes — as one entity.
7.6.4.1 Thefegetenvfunction Synopsis
1 #include <fenv.h>
int fegetenv(fenv_t *envp);
Description
2 Thefegetenvfunction attempts to store the current floating-point environment in the object pointed to byenvp.
Returns
3 Thefegetenvfunction returns zero if the environment was successfully stored. Otherwise, it returns a nonzero value.
7.6.4.2 Thefeholdexceptfunction Synopsis
1 #include <fenv.h>
int feholdexcept(fenv_t *envp);
Description
2 Thefeholdexceptfunction saves the current floating-point environment in the object pointed to by envp, clears the floating-point status flags, and then installs a non-stop (continue on floating-point exceptions) mode, if available, for all floating-point exceptions.223)
Returns
3 Thefeholdexceptfunction returns zero if and only if non-stop floating-point exception handling was successfully installed.
7.6.4.3 Thefesetenvfunction Synopsis
1 #include <fenv.h>
int fesetenv(const fenv_t *envp);
Description
2 Thefesetenvfunction attempts to establish the floating-point environment represented by the object pointed to byenvp. The argumentenvpshall point to an object set by a call tofegetenvor feholdexcept, or equal a floating-point environment macro. Note thatfesetenvmerely installs
223)IEC 60559 systems have a default non-stop mode, and typically at least one other mode for trap handling or aborting; if the system provides only the non-stop mode then installing it is trivial. For such systems, thefeholdexceptfunction can be used in conjunction with thefeupdateenvfunction to write routines that hide spurious floating-point exceptions from their callers.
the state of the floating-point status flags represented through its argument, and does not raise these floating-point exceptions.
Returns
3 Thefesetenvfunction returns zero if the environment was successfully established. Otherwise, it returns a nonzero value.
7.6.4.4 Thefeupdateenvfunction Synopsis
1 #include <fenv.h>
int feupdateenv(const fenv_t *envp);
Description
2 Thefeupdateenvfunction attempts to save the currently raised floating-point exceptions in its automatic storage, install the floating-point environment represented by the object pointed to by envp, and then raise the saved floating-point exceptions. The argumentenvpshall point to an object set by a call tofeholdexceptorfegetenv, or equal a floating-point environment macro.
Returns
3 Thefeupdateenvfunction returns zero if all the actions were successfully carried out. Otherwise, it returns a nonzero value.
4 EXAMPLE Hide spurious underflow floating-point exceptions:
#include <fenv.h>
double f(double x) {
#pragma STDC FENV_ACCESS ON double result;
fenv_t save_env;
if (feholdexcept(&save_env))
return /* indication of an environmental problem */; // compute result
if (/* test spurious underflow */) if (feclearexcept(FE_UNDERFLOW))
return /* indication of an environmental problem */; if (feupdateenv(&save_env))
return /* indication of an environmental problem */; return result;
}
ISO/IEC 9899:20172x::(E) diff:::::::::marks— November 6, 2018 N2310
7.7 Characteristics of floating types
<float.h>1 The header<float.h>defines several macros that expand to various limits and parameters of the standard floating-point types.
2 The macros, their meanings, and the constraints (or restrictions) on their values are listed in 5.2.4.2.2.
A summary is given in Annex E.