NAME

fegetenv, fesetenv, feholdexcept, feupdateenv, fex_merge_flags − manage the floating point environment

SYNOPSIS

cc [ flag ... ] file ... -R/opt/SUNWspro/lib -L/opt/SUNWspro/lib -lm9x [ library ... ]

#include <fenv.h>

void fegetenv(fenv_t ∗envp);

void fesetenv(const fenv_t ∗envp);

int feholdexcept(fenv_t ∗envp);

void feupdateenv(const fenv_t ∗envp);

void fex_merge_flags(const fenv_t ∗envp);

#include <fenv96.h>

void fegetenv96(fenv_t ∗envp);

void fesetenv96(const fenv_t ∗envp);

int feholdexcept96(fenv_t ∗envp);

void feupdateenv96(const fenv_t ∗envp);

DESCRIPTION

These functions manage the floating point environment, comprising the exception flags, rounding direction mode, and exception handling modes, as a single entity.  On SPARC systems, the floating point environment also includes the nonstandard arithmetic mode.  On Intel systems, the floating point environment includes the rounding precision mode. 

fegetenv(envp) saves the current floating point environment in the object pointed to by envp.  (The type fenv_t is defined in <fenv.h>.) 

fesetenv(envp) establishes the floating point environment represented by the object pointed to by envp.  The argument envp must point to an object set by a call to fegetenv or feholdexcept or equal the macro FE_DFL_ENV (also defined in <fenv.h>).  Note that fesetenv merely installs the state of the exception flags represented through envp and does not raise these exceptions. 

(The macro FE_DFL_ENV expands to a pointer to a const-qualified object of type fenv_t that represents the default floating point environment: all exception flags clear, FE_TONEAREST rounding direction mode, and FEX_NONSTOP handling mode for all exceptions.  On SPARC systems, this environment also has the nonstandard arithmetic mode disabled.  On Intel systems, this environment has FE_LDBLPREC rounding precision mode.) 

feholdexcept(envp) saves the current floating point environment in the object pointed to by envp, clears the exception flags, and installs FEX_NONSTOP exception handling mode for all exceptions. 

feupdateenv(envp) establishes the floating point environment represented by the object pointed to by envp and then raises those exceptions corresponding to the flags that were set in the previous environment: for each such exception, if FEX_NONSTOP handling mode is in effect in the newly established environment, the exception’s flag is set, and otherwise the appropriate action is taken as described in fex_set_handling(3M).  The argument envp must point to an object set by a call to feholdexcept or fegetenv or equal the macro FE_DFL_ENV. 

fex_merge_flags(envp) copies into the current environment those exception flags that are set in the environment represented by the object pointed to by envp.  The argument envp must point to an object set by a call to feholdexcept or fegetenv or equal the macro FE_DFL_ENV.  (The fex_merge_flags function does not raise any exceptions, but only sets their flags.) 

RETURN VALUES

feholdexcept returns a nonzero value if FEX_NONSTOP exception handling mode is established for all exceptions and returns zero otherwise. 

EXAMPLE

The following code fragment computes a result in a way that hides spurious underflows but exposes all other exceptions:

#include <fenv.h>
/∗...∗/
{
fenv_t save_env;
 feholdexcept(&save_env);
/∗ computation that may raise spurious underflow ∗/
if (fetestexcept(FE_UNDERFLOW))
feclearexcept(FE_UNDERFLOW);
feupdateenv(&save_env);
/∗...∗/
}

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

The fegetenv, fesetenv, feholdexcept, and feupdateenv functions are defined by the C9X draft standard.  Should the final standard change the definitions of these functions, new conforming implementations will be provided in a subsequent major release.  Therefore, these functions should currently be considered Evolving. 

To maintain compatibility with the present C9X definitions, programs may instead use the fegetenv96, fesetenv96, feholdexcept96, and feupdateenv96 functions.  Each of these functions currently performs the same operation as its counterpart without the 96 suffix.  The suffixed functions, however, will retain their present definitions regardless of changes to the C9X draft.  These functions are Stable. 

Note that <fenv.h> currently redefines the names of the standard functions to their suffixed counterparts so that compiled programs will invoke the suffixed functions.  Once the C9X draft is adopted as a standard, those redefinitions will be removed from <fenv.h>.  Any program recompiled thereafter that uses the standard, unsuffixed names will then invoke the standard functions (with their final definitions), but previously compiled programs will be unaffected. 

SEE ALSO

feclearexcept(3M), fesetround(3M), fesetprec(3M), fex_set_handling(3M), fex_set_log(3M), attributes(5)

Numerical Computation Guide

NOTES

In a multi-threaded program, the preceding functions affect the floating point environment only for the calling thread. 

When the FEX_CUSTOM handling mode is in effect for an exception, raising that exception via feupdateenv will cause the handling function to be invoked.  The handling function may then modify the exception flags to be set as described in fex_set_handling(3M).  Any result value the handler supplies will be ignored. 

The functions described on this page automatically install and deinstall SIGFPE handlers and set and clear the trap enable mode bits in the floating point status register as needed.  If a program uses these functions and attempts to install a SIGFPE handler or control the trap enable mode bits independently, the resulting behavior is not defined. 

As described in fex_set_handling(3M), when a handling function installed in FEX_CUSTOM mode is invoked, all exception traps are disabled (and will not be reenabled while SIGFPE is blocked).  Thus, attempting to change the environment from within a handler by calling fesetenv or feupdateenv may not produce the expected results. 

As shown in the synopsis, the recommended way to link with libm9x using cc is to specify

-Rinstall-path/lib -Linstall-path/lib -lm9x

on the command line, where install-path refers to the location in which the compilers are installed (/opt/SUNWspro by default).  See the Numerical Computation Guide or the READMEs/math_libraries file in the compiler installation area for additional information about linking with libm9x. 

SunOS 5.0  —  Last change: 06/25/97