 |
|
|
Home :: International :: Manuals :: Howto :: FAQ :: Man Pages :: Email Login |
FENV
Section: Linux Programmer's Manual (3)Updated: 2000-08-12
IndexReturn to Main Contents
NAME
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,fetestexcept, fegetenv, fegetround, feholdexcept, fesetround,fesetenv, feupdateenv - C99 floating point rounding and exception handlingSYNOPSIS
#include <fenv.h>void feclearexcept(int excepts);
void fegetexceptflag(fexcept_t *flagp, int excepts);
void feraiseexcept(int excepts);
void fesetexceptflag(const fexcept_t *flagp, int excepts);
int fetestexcept(int excepts);int fegetround(void);
int fesetround(int rounding_mode);void fegetenv(fenv_t *envp);
int feholdexcept(fenv_t *envp);
void fesetenv(const fenv_t *envp);
void feupdateenv(const fenv_t *envp);
DESCRIPTION
These eleven functions were defined in C99, and describe the handlingof floating point rounding and exceptions (overflow, zero-divide etc.).Exceptions
The DivideByZero exception occurs when an operation on finite numbersproduces infinity as exact answer.The Overflow exception occurs when a result has to be represented as afloating point number, but has (much) larger absolute value than thelargest (finite) floating point number that is representable.
The Underflow exception occurs when a result has to be represented as afloating point number, but has smaller absolute value than the smallestpositive normalized floating point number (and would lose much accuracywhen represented as a denormalized number).
The Inexact exception occurs when the rounded result of an operationis not equal to the infinite precision result.It may occur whenever Overflow or Underflow occurs.
The Invalid exception occurs when there is no well-defined resultfor an operation, as for 0/0 or infinity - infinity or sqrt(-1).
Exception handling
Exceptions are represented in two ways: as a single bit(exception present/absent), and these bits correspond in someimplementation-defined way with bit positions in an integer,and also as an opaque structure that may contain more informationabout the exception (perhaps the code address where it occurred).Each of the macrosFE_DIVBYZERO,FE_INEXACT,FE_INVALID,FE_OVERFLOW,FE_UNDERFLOWis defined when the implementation supports handlingof the corresponding exception, and if so thendefines the corresponding bit(s), so that one can callexception handling functions e.g. using the integer argumentFE_OVERFLOW|FE_UNDERFLOW.Other exceptions may be supported. The macroFE_ALL_EXCEPTis the bitwise OR of all bits corresponding to supported exceptions.
Thefeclearexceptfunction clears the supported exceptions represented by the bitsin its argument.
Thefegetexceptflagfunction stores a representation of the state of the exception flagsrepresented by the argumentexceptsin the opaque object*flagp.
Theferaiseexceptfunction raises the supported exceptions represented by the bits inexcepts.
Thefesetexceptflagfunction sets the complete status for the exceptions represented byexceptsto the value*flagp.This value must have been obtained by an earlier call offegetexceptflagwith a last argument that contained all bits inexcepts.
Thefetestexceptfunction returns a word in which the bits are set that wereset in the argumentexceptsand for which the corresponding exception is currently set.
Rounding
Each of the macrosFE_DOWNWARD,FE_TONEAREST,FE_TOWARDZERO,FE_UPWARDis defined when the implementation supports getting and settingthe corresponding rounding direction.Thefegetroundfunction returns the macro corresponding to the currentrounding mode.
Thefesetroundfunction sets the rounding mode as specified by its argumentand returns zero when it was successful.
Floating point environment
The entire floating point environment, includingcontrol modes and status flags, can be handledas one opaque object, of typefenv_t.The default environment is denoted byFE_DFL_ENV(of typeconst fenv_t *).This is the environment setup at program start and it is defined byISO C to have round to nearest, all exceptions cleared and a non-stop(continue on exceptions) mode.Thefegetenvfunction saves the current floating point environment in the object*envp.
Thefeholdexceptfunction does the same, then clears all exception flags,and sets a non-stop (continue on exceptions) mode,if available. It returns zero when successful.
Thefesetenvfunction restores the floating point environment fromthe object*envp.This object must be known to be valid, e.g., the result of a call tofegetenvorfeholdexceptor equal toFE_DFL_ENV.This call does not raise exceptions.
Thefeupdateenvfunction installs the floating-point environment represented bythe object*envp,except that currently raised exceptions are not cleared.After calling this function, the raised exceptions will be a bitwise ORof those previously set with those in*envp.As before, the object*envpmust be known to be valid.
GNU DETAILS
If possible, the GNU C Library defines a macroFE_NOMASK_ENVwhich represents an environment where every exception raised causes atrap to occur. You can test for this macro using#ifdef.It is only defined if_GNU_SOURCEis defined.The C99 standard does not define a way to set individual bits in thefloating point mask, e.g. to trap on specific flags.glibc 2.2 will support the functionsfeenableexceptandfedisableexceptto set individual floating point traps, andfegetexceptto query the state.int feenableexcept (int excepts);
int fedisableexcept (int excepts);
int fegetexcept (void);
Thefeenableexceptandfedisableexceptfunctions enable (disable) traps for each of the exceptions represented byexceptsand return the previous set of enabled exceptions when successful,and -1 otherwise.Thefegetexceptfunction returns the set of all currently enabled exceptions.