FENV(3) Library Functions Manual FENV(3)
NAME
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
fetestexcept, fegetround, fesetround, fegetenv, feholdexcept, fesetenv,
feupdateenv, feenableexcept, fedisableexcept, fegetexcept 
floatingpoint environment control
LIBRARY
Math Library (libm, lm)
SYNOPSIS
#include <<fenv.h>>
#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 <fenv.h> routines manipulate the floatingpoint environment, which
includes the exception flags and rounding modes defined in IEEE Std
7541985.
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 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().
Rounding Modes
IEEE Std 7541985 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 infinity.
FE_UPWARD Results are rounded towards positive infinity.
FE_TOWARDZERO Results are rounded towards zero.
The fegetround() and fesetround() functions query and set the rounding
mode.
Environment Control
The fegetenv() and fesetenv() functions save and restore the floating
point 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 non
standard mechanisms. The feupdateenv() function restores a saved
environment similarly to fesetenv(), but it also reraises any floating
point exceptions from the old environment.
The macro FE_DFL_ENV expands to a pointer to the default environment.
EXAMPLES
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);
}
SEE ALSO
c99(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)
STANDARDS
Except as noted below, <fenv.h> conforms to ISO/IEC 9899:1999
(``ISO C99''). The feenableexcept(), fedisableexcept(), and
fegetexcept() routines are extensions.
HISTORY
The <fenv.h> header first appeared in FreeBSD 5.3 and NetBSD 6.0. It
supersedes the nonstandard routines defined in <ieeefp.h> and documented
in fpgetround(3).
CAVEATS
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.
BUGS
The FENV_ACCESS pragma is unimplemented in the system compiler. However,
nonconstant expressions generally produce the correct sideeffects at
low optimization levels.
NetBSD 6.1.5 March 16, 2005 NetBSD 6.1.5
