'\" t .\" @(#)fegetenv.3m 1.5 00/01/01 SMI .TH fegetenv 3M "01/01/00" .SH NAME fegetenv, fesetenv, feholdexcept, feupdateenv, fex_merge_flags \- manage the floating point environment .SH SYNOPSIS .LP .B cc .RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|." .B -R/opt/SUNWspro/lib -L/opt/SUNWspro/lib -lm9x .RI "[ " "library" " \|.\|.\|. ]" .LP .B #include .LP .BI "void fegetenv(fenv_t *" envp ); .LP .BI "void fesetenv(const fenv_t *" envp ); .LP .BI "int feholdexcept(fenv_t *" envp ); .LP .BI "void feupdateenv(const fenv_t *" envp ); .LP .BI "void fex_merge_flags(const fenv_t *" envp ); .LP .B #include .LP .BI "int feholdexcept96(fenv_t *" envp ); .SH DESCRIPTION .IX "fegetenv function" "" "\fLfegetenv()\fP function" .IX "fesetenv function" "" "\fLfesetenv()\fP function" .IX "feholdexcept function" "" "\fLfeholdexcept()\fP function" .IX "feupdateenv function" "" "\fLfeupdateenv()\fP function" .IX "fex_merge_flags function" "" "\fLfex_merge_flags()\fP function" .IX "feholdexcept96 function" "" "\fLfeholdexcept96()\fP function" .LP 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. .LP \f3fegetenv(\f2envp\f3)\f1 saves the current floating point environment in the object pointed to by \f2envp\f1. (The type \f3fenv_t\f1 is defined in \f3\f1.) .LP \f3fesetenv(\f2envp\f3)\f1 establishes the floating point environment represented by the object pointed to by \f2envp\f1. The argument \f2envp\f1 must point to an object set by a call to \f3fegetenv\f1 or \f3feholdexcept\f1 or equal the macro \s-1FE_DFL_ENV\s0 (also defined in \f3\f1). Note that \f3fesetenv\f1 merely installs the state of the exception flags represented through \f2envp\f1 and does not raise these exceptions. .LP (The macro \s-1FE_DFL_ENV\s0 expands to a pointer to a const-qualified object of type \f3fenv_t\f1 that represents the default floating point environment: all exception flags clear, \s-1FE_TONEAREST\s0 rounding direction mode, and \s-1FEX_NONSTOP\s0 handling mode for all exceptions. On SPARC systems, this environment also has the nonstandard arithmetic mode disabled. On Intel systems, this environment has \s-1FE_LDBLPREC\s0 rounding precision mode.) .LP \f3feholdexcept(\f2envp\f3)\f1 saves the current floating point environment in the object pointed to by \f2envp\f1, clears the exception flags, and installs \s-1FEX_NONSTOP\s0 exception handling mode for all exceptions. .LP \f3feupdateenv(\f2envp\f3)\f1 establishes the floating point environment represented by the object pointed to by \f2envp\f1 and then raises those exceptions corresponding to the flags that were set in the previous environment: for each such exception, if \s-1FEX_NONSTOP\s0 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 \f3fex_set_handling\f1(3M). The argument \f2envp\f1 must point to an object set by a call to \f3feholdexcept\f1 or \f3fegetenv\f1 or equal the macro \s-1FE_DFL_ENV\s0. .LP \f3fex_merge_flags(\f2envp\f3)\f1 copies into the current environment those exception flags that are set in the environment represented by the object pointed to by \f2envp\f1. The argument \f2envp\f1 must point to an object set by a call to \f3feholdexcept\f1 or \f3fegetenv\f1 or equal the macro \s-1FE_DFL_ENV\s0. (The \f3fex_merge_flags\f1 function does not raise any exceptions, but only sets their flags.) .SH "RETURN VALUES" \f3feholdexcept\f1 returns zero if \s-1FEX_NONSTOP\s0 exception handling mode is established for all exceptions and returns a nonzero value otherwise. .SH EXAMPLE The following code fragment computes a result in a way that hides spurious underflows but exposes all other exceptions: .LP .RS .nf .vs 11p .ft B .ne 12 #include /*...*/ { fenv_t save_env; feholdexcept(&save_env); /* computation that may raise spurious underflow */ if (fetestexcept(FE_UNDERFLOW)) feclearexcept(FE_UNDERFLOW); feupdateenv(&save_env); /*...*/ } .vs .fi .RE .LP .SH ATTRIBUTES See .BR attributes (5) for descriptions of the following attributes: .sp .ne 10 .TS box; cbp-1 | cbp-1 l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE = Availability SPROm9xs Interface Stability Standard, Stable (see below) MT-Level MT-Safe .TE .LP The \f3feholdexcept\f1 function is defined by the C9X standard. In 1996, when libm9x was initially implemented, the C9X draft defined \f3feholdexcept\f1 to return a nonzero value if nonstop exception handling is established and zero otherwise, i.e., the opposite of the final definition incorporated in the standard. To accommodate the possibility that the standard might change, libm9x provided an alternate function named \f3feholdexcept96\f1 that followed the C9X draft at that time. Moreover, the \f3\f1 header file automatically redefined the name \f3feholdexcept\f1 to \f3feholdexcept96\f1 so that programs using that header file would call the alternate function. Now that C9X has been officially completed, libm9x provides a conforming implementation of \f3feholdexcept\f1 in addition to the alternate \f3feholdexcept96\f1, and \f3\f1 no longer redefines \f3feholdexcept\f1 to \f3feholdexcept96\f1. As a result, while programs compiled with the original \f3\f1 may continue to rely on the return value defined by the original C9X draft, such programs can fail if they are recompiled. In order to maintain compatibility with the original definition, programs may instead invoke the alternate \f3feholdexcept96\f1 function explicitly. (This function is declared in the \f3\f1 header file.) The \f3feholdexcept96\f1 function is not part of C9X and so retains its original behavior. Its interface stability classification is Stable. Note, however, that this function is intended to provide compatible behavior for existing programs that depend on the original C9X definition of \f3feholdexcept\f1; new programs should be written to use the standard function. .SH "SEE ALSO" .BR feclearexcept (3M), .BR fesetround (3M), .BR fesetprec (3M), .BR fex_set_handling (3M), .BR fex_set_log (3M), .BR attributes (5) .LP .I Numerical Computation Guide .SH NOTES In a multi-threaded program, the preceding functions affect the floating point environment only for the calling thread. .LP When the \s-1FEX_CUSTOM\s0 handling mode is in effect for an exception, raising that exception via \f3feupdateenv\f1 will cause the handling function to be invoked. The handling function may then modify the exception flags to be set as described in \f3fex_set_handling\f1(3M). Any result value the handler supplies will be ignored. .LP The functions described on this page automatically install and deinstall \s-1SIGFPE\s0 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 \s-1SIGFPE\s0 handler or control the trap enable mode bits independently, the resulting behavior is not defined. .LP As described in \f3fex_set_handling\f1(3M), when a handling function installed in \s-1FEX_CUSTOM\s0 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 \f3fesetenv\f1 or \f3feupdateenv\f1 may not produce the expected results. .LP As shown in the synopsis, the recommended way to link with libm9x using \f3cc\f1 is to specify .LP .RS .BI -R install-path "/lib -L" install-path "/lib -lm9x" .RE .LP on the command line, where \f2install-path\f1 refers to the location in which the compilers are installed (/opt/SUNWspro by default). See the \f2Numerical Computation Guide\f1 for additional information about linking with libm9x.