FENV (3)  C library functions  Unix Manual Pages  :man▋
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept, fegetround, fesetround, fegetenv, feholdexcept, fesetenv, feupdateenv, feenableexcept, fedisableexcept, fegetexcept  floatingpoint environment control
CONTENTS
Library Synopsis Description Exceptions Rounding Modes Environment Control Caveats Examples See Also Standards History Bugs
LIBRARY
.Lb libm
SYNOPSIS
.In fenv.h .Fd "#pragma STDC FENV_ACCESS ON" int feclearexcept "int excepts" int fegetexceptflag "fexcept_t *flagp" "int excepts" int feraiseexcept "int excepts" int fesetexceptflag "const fexcept_t *flagp" "int excepts" int fetestexcept "int excepts" int fegetround void int fesetround "int round" int fegetenv "fenv_t *envp" int feholdexcept "fenv_t *envp" int fesetenv "const fenv_t *envp" int feupdateenv "const fenv_t *envp" int feenableexcept "int excepts" int fedisableexcept "int excepts" int fegetexcept void
DESCRIPTION
The .In fenv.h routines manipulate the floatingpoint environment, which includes the exception flags and rounding modes defined in ieee754.
Exceptions
Exception flags are set as sideeffects of floatingpoint arithmetic operations and math library routines, and they remain set until explicitly cleared. The following macros expand to bit flags of type .Vt int representing the five standard floatingpoint exceptions. FE_DIVBYZERO  A dividebyzero exception occurs when the program attempts to divide a finite nonzero number by zero.  FE_INEXACT  An inexact exception is raised whenever there is a loss of precision due to rounding.  FE_INVALID  Invalid operation exceptions occur when a program attempts to perform calculations for which there is no reasonable representable answer. For instance, subtraction of infinities, division of zero by zero, ordered comparison involving NaNs, and taking the square root of a negative number are all invalid operations.  FE_OVERFLOW  An overflow exception occurs when the magnitude of the result of a computation is too large to fit in the destination type.  FE_UNDERFLOW  Underflow occurs when the result of a computation is too close to zero to be represented as a nonzero value in the destination type.  
Additionally, the FE_ALL_EXCEPT macro expands to the bitwise OR of the above flags and any architecturespecific flags. Combinations of these flags are passed to the feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, and fetestexcept functions to clear, save, raise, restore, and examine the processor’s floatingpoint exception flags, respectively. Exceptions may be unmasked with feenableexcept and masked with fedisableexcept. Unmasked exceptions cause a trap when they are produced, and all exceptions are masked by default. The current mask can be tested with fegetexcept.
ieee754 specifies four rounding modes. These modes control the direction in which results are rounded from their exact values in order to fit them into binary floatingpoint variables. The four modes correspond with the following symbolic constants. FE_TONEAREST  Results are rounded to the closest representable value. If the exact result is exactly half way between two representable values, the value whose last binary digit is even (zero) is chosen. This is the default mode.  FE_DOWNWARD  Results are rounded towards negative If].  FE_UPWARD  Results are rounded towards positive If].  FE_TOWARDZERO  Results are rounded towards zero.  
The fegetround and fesetround functions query and set the rounding mode.
The fegetenv and fesetenv functions save and restore the floatingpoint environment, which includes exception flags, the current exception mask, the rounding mode, and possibly other implementationspecific state. The feholdexcept function behaves like fegetenv, but with the additional effect of clearing the exception flags and installing a nonstop mode. In nonstop mode, floatingpoint operations will set exception flags as usual, but no SIGFPE signals will be generated as a result. Nonstop mode is the default, but it may be altered by nonstandard mechanisms. The feupdateenv function restores a saved environment similarly to fesetenv, but it also reraises any floatingpoint exceptions from the old environment. The macro FE_DFL_ENV expands to a pointer to the default environment.
The FENV_ACCESS pragma can be enabled with "#pragma STDC FENV_ACCESS ON" and disabled with the "#pragma STDC FENV_ACCESS OFF" directive. This lexicallyscoped annotation tells the compiler that the program may access the floatingpoint environment, so optimizations that would violate strict IEEE754 semantics are disabled. If execution reaches a block of code for which FENV_ACCESS is off, the floatingpoint environment will become undefined.
The following routine computes the square root function. It explicitly raises an invalid exception on appropriate inputs using feraiseexcept. It also defers inexact exceptions while it computes intermediate values, and then it allows an inexact exception to be raised only if the final answer is inexact.
#pragma STDC FENV_ACCESS ON
double sqrt(double n) {
double x = 1.0;
fenv_t env;
if (isnan(n)  n < 0.0) {
feraiseexcept(FE_INVALID);
return (NAN);
}
if (isinf(n)  n == 0.0)
return (n);
feholdexcept(&env);
while (fabs((x * x)  n) > DBL_EPSILON * 2 * x)
x = (x / 2) + (n / (2 * x));
if (x * x == n)
feclearexcept(FE_INEXACT);
feupdateenv(&env);
return (x);
}
cc(1), feclearexcept(3), fedisableexcept(3), feenableexcept(3), fegetenv(3), fegetexcept(3), fegetexceptflag(3), fegetround(3), feholdexcept(3), feraiseexcept(3), fesetenv(3), fesetexceptflag(3), fesetround(3), fetestexcept(3), feupdateenv(3), fpgetprec(3), fpsetprec(3)
STANDARDS
HISTORY
fpgetround(3).
BUGS
cc(1)
Share this page


Follow us

