feclearexcept(), fegetexceptflag(), feraiseexcept(), fesetexceptflag(), fetestexcept(), fegetround(), fesetround(), fegetenv(), feholdexcept(), fesetenv(), feupdateenv(), feenableexcept(), fedisableexcept(), fegetexcep() -- floating-point environment control

SYNOPSIS

#include <fenv.h>

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 floating-point environment, which includes the exception flags and rounding modes defined in IEEE Std 754-1985.

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 int representing the five standard floating-point exceptions.

FE_DIVBYZERO: Is the location where the resulting sign is stored. A divide-by-zero exception occurs when the exact result of a computation is infinite (according to the limit definition). For example, dividing a finite non-zero number by zero or computing log(0) raises a divide-by-zero exception.
FE_INEXACT: An inexact exception is raised whenever there is a loss of accuracy 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 like-signed infinities, division of zero by zero, ordered comparison involving NaNs, and taking the real square root of a negative number are all invalid operations.
FE_OVERFLOW: In contrast with divide-by-zero, an overflow exception occurs when an infinity is produced because the magnitude of the exact result is finite but too large to fit in the destination type. For example, computing DBL_MAX * 2 raises an overflow exception.
FE_UNDERFLOW: Underflow occurs when the result of a computation loses precision because it is too close to zero. The result is a subnormal number or zero.

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

IEEE Std 754-1985 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 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 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 feenableexcept() and fedisableexcept(). 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.

RETURN VALUES

fetestexcept() returns which of a specified subset of floating-point exceptions flags in except are currently set.

fegetround() returns zero in the rounding mask is not set, and non-zero if it is set.

feenableexcept(), fedisableexcept() and fegetexcept() return exceptions enabled.

All the other functions return zero for success and non-zero for failure.

EXAMPLE

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.

#define _BSD_SOURCE	/* for fenv extensions */
#include <float.h>
#include <math.h>
#include <fenv.h>

double fsqrt(double n) 
{
    double x = 1.0;
    fenv_t env;

    if (isnan(n) || n < 0.0) 
    {
    	/* If you expect this to throw an exception (SIGFPE) */
	/* call feenableexcept(FE_ALL_EXCEPT); somewhere */
        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);
}

feclearexcept(), fegetexceptflag(), feraiseexcept(), fesetexceptflag(), fetestexcept(), fegetround(), fesetround(), fegetenv(), feholdexcept(), fesetenv(), feupdateenv(), feenableexcept(), fedisableexcept(), fegetexcep()

Function

SYNOPSIS

DESCRIPTION

Exceptions

Rounding Modes

Environment Control

RETURN VALUES

EXAMPLE

CONFORMANCE

MULTITHREAD SAFETY LEVEL

PORTING ISSUES

AVAILABILITY

SEE ALSO