# FreeBSD Manual Pages

FENV(3) BSD Library Functions Manual FENV(3)NAMEfeclearexcept,fegetexceptflag,feraiseexcept,fesetexceptflag,fetestexcept,fegetround,fesetround,fegetenv,feholdexcept,fesetenv,feupdateenv,feenableexcept,fedisableexcept,fegetexcept-- floating- point environment controlLIBRARYMath Library (libm, -lm)SYNOPSIS#include<fenv.h>#pragmaSTDCFENV_ACCESSONintfeclearexcept(intexcepts);intfegetexceptflag(fexcept_t*flagp,intexcepts);intferaiseexcept(intexcepts);intfesetexceptflag(constfexcept_t*flagp,intexcepts);intfetestexcept(intexcepts);intfegetround(void);intfesetround(intround);intfegetenv(fenv_t*envp);intfeholdexcept(fenv_t*envp);intfesetenv(constfenv_t*envp);intfeupdateenv(constfenv_t*envp);intfeenableexcept(intexcepts);intfedisableexcept(intexcepts);intfegetexcept(void);DESCRIPTIONThe <fenv.h> routines manipulate the floating-point environment, which includes the exception flags and rounding modes defined in IEEE Std 754-1985.ExceptionsException flags are set as side-effects of floating-point arithmetic op- erations and math library routines, and they remain set until explicitly cleared. The following macros expand to bit flags of typeintrepresent- ing 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 infini- ties, division of zero by zero, ordered comparison involv- ingNaNs, and taking the square root of a negative number are all invalid operations. FE_OVERFLOW An overflow exception occurs when the magnitude of the re- sult of a computation is too large to fit in the destina- tion 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 thefeclearexcept(),fegetexceptflag(),feraiseexcept(),fesetexceptflag(), andfetestexcept() functions to clear, save, raise, restore, and examine the processor's floating-point exception flags, respectively. Exceptions may beunmaskedwithfeenableexcept() and masked withfedisableexcept(). Unmasked exceptions cause a trap when they are pro- duced, and all exceptions are masked by default. The current mask can be tested withfegetexcept().RoundingModesIEEE 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 corre- spond 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 repre- sentable 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. Thefegetround() andfesetround() functions query and set the rounding mode.EnvironmentControlThefegetenv() andfesetenv() 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. Thefeholdexcept() function behaves likefegetenv(), but with the additional effect of clearing the exception flags and installing anon-stopmode. In non-stop mode, floating-point operations will set ex- ception flags as usual, but no SIGFPE signals will be generated as a re- sult. Non-stop mode is the default, but it may be altered by non-stan- dard mechanisms. Thefeupdateenv() function restores a saved environment similarly tofesetenv(), but it also re-raises any floating-point excep- tions from the old environment. The macro FE_DFL_ENV expands to a pointer to the default environment.CAVEATSThe 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.EXAMPLESThe following routine computes the square root function. It explicitly raises an invalid exception on appropriate inputs usingferaiseexcept(). 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 ALSOcc(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)STANDARDSExcept as noted below, <fenv.h> conforms to ISO/IEC 9899:1999 ("ISO C99"). Thefeenableexcept(),fedisableexcept(), andfegetexcept() routines are extensions.HISTORYThe <fenv.h> header first appeared in FreeBSD 5.3. It supersedes the non-standard routines defined in <ieeefp.h> and documented in fpgetround(3).BUGSThe FENV_ACCESS pragma is unimplemented in the system compiler. However, non-constant expressions generally produce the correct side-effects at low optimization levels. On the Alpha platform, cc(1) must be passed the-mieee-with-inexact-mfp-rounding-mode=doptions in order to generate code that has the stan- dard side-effects and uses the specified rounding modes. BSD March 16, 2005 BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | CAVEATS | EXAMPLES | SEE ALSO | STANDARDS | HISTORY | BUGS

Want to link to this manual page? Use this URL:

<https://www.freebsd.org/cgi/man.cgi?query=fenv&sektion=3&manpath=FreeBSD+6.0-RELEASE+and+Ports>