GNU Info

(libc.info)Control Functions

---

Next: Arithmetic Functions Prev: Rounding Up: Arithmetic

---

Enter node , (file) or (file)node

Floating-Point Control Functions
================================

   IEEE 754 floating-point implementations allow the programmer to
decide whether traps will occur for each of the exceptions, by setting
bits in the "control word".  In C, traps result in the program
receiving the `SIGFPE' signal; see Note: Signal Handling.

   *Note:* IEEE 754 says that trap handlers are given details of the
exceptional situation, and can set the result value.  C signals do not
provide any mechanism to pass this information back and forth.
Trapping exceptions in C is therefore not very useful.

   It is sometimes necessary to save the state of the floating-point
unit while you perform some calculation.  The library provides functions
which save and restore the exception flags, the set of exceptions that
generate traps, and the rounding mode.  This information is known as the
"floating-point environment".

   The functions to save and restore the floating-point environment all
use a variable of type `fenv_t' to store information.  This type is
defined in `fenv.h'.  Its size and contents are implementation-defined.
You should not attempt to manipulate a variable of this type directly.

   To save the state of the FPU, use one of these functions:

 - Function: int fegetenv (fenv_t *ENVP)
     Store the floating-point environment in the variable pointed to by
     ENVP.

     The function returns zero in case the operation was successful, a
     non-zero value otherwise.

 - Function: int feholdexcept (fenv_t *ENVP)
     Store the current floating-point environment in the object pointed
     to by ENVP.  Then clear all exception flags, and set the FPU to
     trap no exceptions.  Not all FPUs support trapping no exceptions;
     if `feholdexcept' cannot set this mode, it returns nonzero value.
     If it succeeds, it returns zero.

   The functions which restore the floating-point environment can take
these kinds of arguments:

   * Pointers to `fenv_t' objects, which were initialized previously by
     a call to `fegetenv' or `feholdexcept'.

   * The special macro `FE_DFL_ENV' which represents the floating-point
     environment as it was available at program start.

   * Implementation defined macros with names starting with `FE_' and
     having type `fenv_t *'.

     If possible, the GNU C Library defines a macro `FE_NOMASK_ENV'
     which represents an environment where every exception raised
     causes a trap to occur.  You can test for this macro using
     `#ifdef'.  It is only defined if `_GNU_SOURCE' is defined.

     Some platforms might define other predefined environments.

To set the floating-point environment, you can use either of these
functions:

 - Function: int fesetenv (const fenv_t *ENVP)
     Set the floating-point environment to that described by ENVP.

     The function returns zero in case the operation was successful, a
     non-zero value otherwise.

 - Function: int feupdateenv (const fenv_t *ENVP)
     Like `fesetenv', this function sets the floating-point environment
     to that described by ENVP.  However, if any exceptions were
     flagged in the status word before `feupdateenv' was called, they
     remain flagged after the call.  In other words, after `feupdateenv'
     is called, the status word is the bitwise OR of the previous
     status word and the one saved in ENVP.

     The function returns zero in case the operation was successful, a
     non-zero value otherwise.

To control for individual exceptions if raising them causes a trap to
occur, you can use the following two functions.

   *Portability Note:* These functions are all GNU extensions.

 - Function: int feenableexcept (int EXCEPTS)
     This functions enables traps for each of the exceptions as
     indicated by the parameter EXCEPT.  The individual excepetions are
     described in Note: Status bit operations.  Only the specified
     exceptions are enabled, the status of the other exceptions is not
     changed.

     The function returns the previous enabled exceptions in case the
     operation was successful, `-1' otherwise.

 - Function: int fedisableexcept (int EXCEPTS)
     This functions disables traps for each of the exceptions as
     indicated by the parameter EXCEPT.  The individual excepetions are
     described in Note: Status bit operations.  Only the specified
     exceptions are disabled, the status of the other exceptions is not
     changed.

     The function returns the previous enabled exceptions in case the
     operation was successful, `-1' otherwise.

 - Function: int fegetexcept (int EXCEPTS)
     The function returns a bitmask of all currently enabled
     exceptions.  It returns `-1' in case of failure.