FreeBSD Man Pages

fenv(3)

NAME

     feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
     fetestexcept, fegetround, fesetround, fegetenv, feholdexcept, fesetenv,
     feupdateenv -- floating-point 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);

DESCRIPTION

     The <fenv.h> routines manipulate the floating-point environment, which
     includes the exception flags and rounding modes defined in IEEE Std
     754-1985.

   Exceptions
     Exception flags are set as side-effects of floating-point arithmetic
     operations and math library routines, and they remain set until explic-
     itly cleared.  The following macros expand to bit flags of type int rep-
     resenting the five standard floating-point exceptions.

     FE_DIVBYZERO  A divide-by-zero exception occurs when the program attempts
		   ties, division of zero by zero, ordered comparison involv-
		   ing 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 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 the feclearexcept(), fegetexceptflag(),
     feraiseexcept(), fesetexceptflag(), and fetestexcept() functions to
     clear, save, raise, restore, and examine the processor's floating-point
     exception flags, respectively.

   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 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.

     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-stan-
     dard mechanisms.  The feupdateenv() function restores a saved environment
     similarly to fesetenv(), 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.

CAVEATS

     The FENV_ACCESS pragma can be enabled with
	   #pragma STDC FENV_ACCESS ON
     and disabled with the
     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

     cc(1), feclearexcept(3), fegetenv(3), fegetexceptflag(3), fegetround(3),
     feholdexcept(3), feraiseexcept(3), fesetenv(3), fesetexceptflag(3),
     fesetround(3), fetestexcept(3), feupdateenv(3), fpgetmask(3),
     fpgetprec(3), fpgetround(3), fpgetsticky(3), fpresetsticky(3),
     fpsetmask(3), fpsetprec(3), fpsetround(3)

STANDARDS

     Except as noted below, <fenv.h> conforms to ISO/IEC 9899:1999
     (``ISO C99'').

HISTORY

     The <fenv.h> header first appeared in FreeBSD 5.3.  It supersedes the
     non-standard routines defined in <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.

     On the Alpha platform, cc(1) must be passed the -mieee-with-inexact
     -mfp-rounding-mode=d options in order to generate code that has the stan-
     dard side-effects and uses the specified rounding modes.

FreeBSD 5.4			  May 8, 2004			   FreeBSD 5.4

SPONSORED LINKS