Man Page feupdateenv.3m


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


     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);


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


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


     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;

               /* computation that may raise spurious underflow */
               if (fetestexcept(FE_UNDERFLOW))


     See attributes(5) for descriptions of the  following  attri-

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


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

     Numerical Computation Guide


     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.