Man Page fesetenv.3m




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 (see below)|
    | MT-Level           |  MT-Safe                     |
    |____________________|______________________________|

     The feholdexcept function is defined by  the  C9X  standard.
     In  1996,  when  libm9x  was  initially implemented, the C9X
     draft defined feholdexcept to return a nonzero value if non-
     stop  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 stan-
     dard might change, libm9x  provided  an  alternate  function
     named  feholdexcept96  that  followed  the C9X draft at that
     time.  Moreover,  the  <fenv.h>  header  file  automatically
     redefined  the  name  feholdexcept to feholdexcept96 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  feholdexcept
     in addition to the alternate feholdexcept96, and <fenv.h> no
     longer  redefines  feholdexcept  to  feholdexcept96.   As  a
     result,  while  programs compiled with the original <fenv.h>
     may continue to rely on the return value defined by the ori-
     ginal  C9X  draft, such programs can fail if they are recom-
     piled.  In order to maintain compatibility with the original
     definition, programs may instead invoke the alternate fehol-
     dexcept96 function explicitly.  (This function  is  declared
     in the <fenv96.h> header file.)  The feholdexcept96 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  compati-
     ble behavior for existing programs that depend on the origi-
     nal C9X definition of feholdexcept; new programs  should  be
     written to use the standard function.


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.