Control Functions (The GNU C Library)

### 20.7 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 Signal Handling.

NB: 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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  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.

TS 18661-1:2014 defines additional functions to save and restore floating-point control modes (such as the rounding mode and whether traps are enabled) while leaving other status (such as raised flags) unchanged.

The special macro `FE_DFL_MODE` may be passed to `fesetmode`. It represents the floating-point control modes at program start.

Function: `int` fegetmode `(femode_t *modep)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  Store the floating-point control modes in the variable pointed to by modep.

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

Function: `int` fesetmode `(const femode_t *modep)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  Set the floating-point control modes to those described by modep.

  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)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This function enables traps for each of the exceptions as indicated by the parameter excepts. The individual exceptions are described in Examining the FPU status word. 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.

  Note: Enabling traps for an exception for which the exception flag is currently already set (see Examining the FPU status word) has unspecified consequences: it may or may not trigger a trap immediately.

Function: `int` fedisableexcept `(int excepts)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  This function disables traps for each of the exceptions as indicated by the parameter excepts. The individual exceptions are described in Examining the FPU status word. 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 `(void)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  The function returns a bitmask of all currently enabled exceptions. It returns `-1` in case of failure.