'\" t .\" @(#)fegetenv.3m 1.4 97/06/25 SMI .TH fegetenv 3M "06/25/97" .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 "void fegetenv96(fenv_t *" envp ); .LP .BI "void fesetenv96(const fenv_t *" envp ); .LP .BI "int feholdexcept96(fenv_t *" envp ); .LP .BI "void feupdateenv96(const 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 "fegetenv96 function" "" "\fLfegetenv96()\fP function" .IX "fesetenv96 function" "" "\fLfesetenv96()\fP function" .IX "feholdexcept96 function" "" "\fLfeholdexcept96()\fP function" .IX "feupdateenv96 function" "" "\fLfeupdateenv96()\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 a nonzero value if \s-1FEX_NONSTOP\s0 exception handling mode is established for all exceptions and returns zero 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 Stable (see below) MT-Level MT-Safe .TE .LP The \f3fegetenv\f1, \f3fesetenv\f1, \f3feholdexcept\f1, and \f3feupdateenv\f1 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. .LP To maintain compatibility with the present C9X definitions, programs may instead use the \f3fegetenv96\f1, \f3fesetenv96\f1, \f3feholdexcept96\f1, and \f3feupdateenv96\f1 functions. Each of these functions currently performs the same operation as its counterpart without the \f396\f1 suffix. The suffixed functions, however, will retain their present definitions regardless of changes to the C9X draft. These functions are Stable. .LP Note that \f3\f1 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 \f3\f1. 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. .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 \f3Numerical Computation Guide\f1 or the READMEs/math_libraries file in the compiler installation area for additional information about linking with libm9x.