7.6 Floating-point environment <fenv.h>

• 7.6.1 The FENV_ACCESS pragma
• 7.6.2 Floating-point exceptions
  • 7.6.2.1 The feclearexcept function
  • 7.6.2.2 The fegetexceptflag function
  • 7.6.2.3 The feraiseexcept function
  • 7.6.2.4 The fesetexceptflag function
  • 7.6.2.5 The fetestexcept function
• 7.6.3 Rounding
  • 7.6.3.1 The fegetround function
  • 7.6.3.2 The fesetround function
• 7.6.4 Environment
  • 7.6.4.1 The fegetenv function
  • 7.6.4.2 The feholdexcept function
  • 7.6.4.3 The fesetenv function
  • 7.6.4.4 The feupdateenv function

1

The header <fenv.h> declares two types and several macros and functions to provide access to the floating-point environment. The floating-point environment refers collectively to any floating-point status flags and control modes supported by the implementation.[1] A floating-point status flag is a system variable whose value is set (but never cleared) when a floating-point exception is raised, which occurs as a side effect of exceptional floating-point arithmetic to provide auxiliary information.[2] A floating- point control mode is a system variable whose value may be set by the user to affect the subsequent behavior of floating-point arithmetic.

2

Certain programming conventions support the intended model of use for the floating- point environment:[3]

• a function call does not alter its caller’s floating-point control modes, clear its caller’s floating-point status flags, nor depend on the state of its caller’s floating-point status flags unless the function is so documented;

• a function call is assumed to require default floating-point control modes, unless its documentation promises otherwise;

• a function call is assumed to have the potential for raising floating-point exceptions, unless its documentation promises otherwise.

3

The type

fenv_t

represents the entire floating-point environment.

4

The type

fexcept_t

represents the floating-point status flags collectively, including any status the implementation associates with the flags.

5

Each of the macros

FE_DIVBYZERO
FE_INEXACT
FE_INVALID
FE_OVERFLOW
FE_UNDERFLOW

is defined if and only if the implementation supports the floating-point exception by means of the functions in 7.6.2.[4] Additional implementation-defined floating-point exceptions, with macro definitions beginning with FE_ and an uppercase letter, may also be specified by the implementation. The defined macros expand to integer constant expressions with values such that bitwise ORs of all combinations of the macros result in distinct values, and furthermore, bitwise ANDs of all combinations of the macros result in zero.[5]

6

The macro

FE_ALL_EXCEPT

is simply the bitwise OR of all floating-point exception macros defined by the implementation. If no such macros are defined, FE_ALL_EXCEPT shall be defined as 0.

7

Each of the macros

FE_DOWNWARD
FE_TONEAREST
FE_TOWARDZERO
FE_UPWARD

is defined if and only if the implementation supports getting and setting the represented rounding direction by means of the fegetround and fesetround functions. Additional implementation-defined rounding directions, with macro definitions beginning with FE_ and an uppercase letter, may also be specified by the implementation. The defined macros expand to integer constant expressions whose values are distinct nonnegative values.[6]

8

The macro

FE_DFL_ENV

represents the default floating-point environment – the one installed at program startup – and has type “pointer to const-qualified fenv_t”. It can be used as an argument to <fenv.h> functions that manage the floating-point environment.

9

Additional implementation-defined environments, with macro definitions beginning with FE_ and an uppercase letter, and having type “pointer to const-qualified fenv_t”, may also be specified by the implementation.

Footnotes

[1]

This header is designed to support the floating-point exception status flags and directed-rounding control modes required by IEC 60559, and other similar floating-point state information. Also it is designed to facilitate code portability among all systems.

[2]

A floating-point status flag is not an object and can be set more than once within an expression.

[3]

With these conventions, a programmer can safely assume default floating-point control modes (or be unaware of them). The responsibilities associated with accessing the floating-point environment fall on the programmer or program that does so explicitly.

[4]

The implementation supports an exception if there are circumstances where a call to at least one of the functions in 7.6.2, using the macro as the appropriate argument, will succeed. It is not necessary for all the functions to succeed all the time.

[5]

The macros should be distinct powers of two.

[6]

Even though the rounding direction macros may expand to constants corresponding to the values of FLT_ROUNDS, they are not required to do so.