feclearexceptfegetexceptflagferaiseexceptfesetexceptflagfetestexceptfegetroundfesetroundfegetenvfeholdexceptfesetenvfeupdateenvfeenableexceptfedisableexceptfegetexcept
- floating-point environment control
LIBRARY
Lb libm
SYNOPSIS
#include <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
#include <fenv.h>
routines manipulate the floating-point environment,
which includes the exception flags and rounding modes defined in
St -ieee754 .
Exceptions
Exception flags are set as side-effects of floating-point 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 floating-point exceptions.
FE_DIVBYZERO
A divide-by-zero exception occurs when the program attempts to
divide a finite non-zero 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 s, 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 non-zero value in the destination type.
Additionally, the
FE_ALL_EXCEPT
macro expands to the bitwise OR of the above flags and any
architecture-specific 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 floating-point 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
St -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
floating-point 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.
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 implementation-specific
state.
The
feholdexcept ();
function behaves like
fegetenv (,);
but with the additional effect of clearing the exception flags and
installing a
non-stop
mode.
In non-stop mode, floating-point operations will set exception flags
as usual, but no
SIGFPE
signals will be generated as a result.
Non-stop 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 re-raises any floating-point exceptions from the old
environment.
The macro
FE_DFL_ENV
expands to a pointer to the default environment.
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 lexically-scoped annotation tells the compiler that the program
may access the floating-point environment, so optimizations that would
violate strict IEEE-754 semantics are disabled.
If execution reaches a block of code for which
FENV_ACCESS
is off, the floating-point environment will become undefined.
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);
}
Except as noted below,
#include <fenv.h>
conforms to
St -isoC-99 .
The
feenableexcept (,);
fedisableexcept (,);
and
fegetexcept ();
routines are extensions.
HISTORY
The
#include <fenv.h>
header first appeared in
Fx 5.3 .
It supersedes the non-standard routines defined in
#include <ieeefp.h>
and documented in
fpgetround(3).
BUGS
The
FENV_ACCESS
pragma is unimplemented in the system compiler.
However, non-constant expressions generally produce the correct
side-effects at low optimization levels.
