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>
int feholdexcept96(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 sys-
tems, the floating point environment also includes the non-
standard 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 han-
dling mode for all exceptions. On SPARC systems, this
environment also has the nonstandard arithmetic mode dis-
abled. On Intel systems, this environment has FE_LDBLPREC
rounding precision mode.)
feholdexcept(envp) saves the current floating point environ-
ment 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 esta-
blished environment, the exception's flag is set, and other-
wise 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 zero if FEX_NONSTOP exception handling
mode is established for all exceptions and returns a nonzero
value 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 attri-
butes:
______________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|____________________|________________________________________|
| Availability | SPROm9xs |
| Interface Stability| Standard, Stable, Obsolete (see below)|
| MT-Level | MT-Safe |
|____________________|________________________________________|
The fegetenv, fesetenv, feholdexcept, and feupdateenv func-
tions are defined by the C99 standard. Their interface sta-
bility classification is Standard.
The fex_merge_flags function is not defined by any standard.
Its interface stability classification is Stable.
In 1996, when these functions were initially implemented,
the C99 draft standard defined feholdexcept to return a
nonzero value if the requested rounding mode is established
and zero otherwise, i.e., the opposite of the definition in
the final standard. To accommodate the possibility that the
standard might change, libm9x provided an alternate function
named feholdexcept96 that followed the C99 draft at that
time. This and other functions with the "96" suffix were
declared in the <fenv96.h> header file. Now that C99 has
been finalized, these suffixed functions and the <fenv96.h>
header file are no longer necessary. Their interface sta-
bility classification is Obsolete.
The <fenv96.h> header file may be removed in a subsequent
release. Application programs should instead use the stan-
dard functions and the <fenv.h> header file.
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 excep-
tion, 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 func-
tion 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 loca-
tion in which the compilers are installed (/opt/SUNWspro by
default). See the Numerical Computation Guide for addi-
tional information about linking with libm9x.