1FENV(3) Linux Programmer's Manual FENV(3)
2
6 feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetes‐
7 texcept, fegetenv, fegetround, feholdexcept, fesetround, fesetenv,
8 feupdateenv, feenableexcept, fedisableexcept, fegetexcept - floating-
9 point rounding and exception handling
10
12 #include <fenv.h>
13 int feclearexcept(int excepts);
15 int fegetexceptflag(fexcept_t *flagp, int excepts);
16 int feraiseexcept(int excepts);
17 int fesetexceptflag(const fexcept_t *flagp, int excepts);
18 int fetestexcept(int excepts);
19 int fegetround(void);
21 int fesetround(int rounding_mode);
22 int fegetenv(fenv_t *envp);
24 int feholdexcept(fenv_t *envp);
25 int fesetenv(const fenv_t *envp);
26 int feupdateenv(const fenv_t *envp);
27 Link with -lm.
29
31 These eleven functions were defined in C99, and describe the handling
32 of floating-point rounding and exceptions (overflow, zero-divide,
33 etc.).
34 Exceptions
36 The divide-by-zero exception occurs when an operation on finite numbers
37 produces infinity as exact answer.
38 The overflow exception occurs when a result has to be represented as a
40 floating-point number, but has (much) larger absolute value than the
41 largest (finite) floating-point number that is representable.
42 The underflow exception occurs when a result has to be represented as a
44 floating-point number, but has smaller absolute value than the smallest
45 positive normalized floating-point number (and would lose much accuracy
46 when represented as a denormalized number).
47 The inexact exception occurs when the rounded result of an operation is
49 not equal to the infinite precision result. It may occur whenever
50 overflow or underflow occurs.
51 The invalid exception occurs when there is no well-defined result for
53 an operation, as for 0/0 or infinity - infinity or sqrt(-1).
54 Exception handling
56 Exceptions are represented in two ways: as a single bit (exception
57 present/absent), and these bits correspond in some implementation-
58 defined way with bit positions in an integer, and also as an opaque
59 structure that may contain more information about the exception (per‐
60 haps the code address where it occurred).
61 Each of the macros FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW,
63 FE_UNDERFLOW is defined when the implementation supports handling of
64 the corresponding exception, and if so then defines the corresponding
65 bit(s), so that one can call exception handling functions, for example,
66 using the integer argument FE_OVERFLOW|FE_UNDERFLOW. Other exceptions
67 may be supported. The macro FE_ALL_EXCEPT is the bitwise OR of all
68 bits corresponding to supported exceptions.
69 The feclearexcept() function clears the supported exceptions repre‐
71 sented by the bits in its argument.
72 The fegetexceptflag() function stores a representation of the state of
74 the exception flags represented by the argument excepts in the opaque
75 object *flagp.
76 The feraiseexcept() function raises the supported exceptions repre‐
78 sented by the bits in excepts.
79 The fesetexceptflag() function sets the complete status for the excep‐
81 tions represented by excepts to the value *flagp. This value must have
82 been obtained by an earlier call of fegetexceptflag() with a last argu‐
83 ment that contained all bits in excepts.
84 The fetestexcept() function returns a word in which the bits are set
86 that were set in the argument excepts and for which the corresponding
87 exception is currently set.
88 Rounding mode
90 The rounding mode determines how the result of floating-point opera‐
91 tions is treated when the result cannot be exactly represented in the
92 significand. Various rounding modes may be provided: round to nearest
93 (the default), round up (toward positive infinity), round down (toward
94 negative infinity), and round toward zero.
95 Each of the macros FE_TONEAREST, FE_UPWARD, FE_DOWNWARD, and
97 FE_TOWARDZERO is defined when the implementation supports getting and
98 setting the corresponding rounding direction.
99 The fegetround() function returns the macro corresponding to the cur‐
101 rent rounding mode.
102 The fesetround() function sets the rounding mode as specified by its
104 argument and returns zero when it was successful.
105 C99 and POSIX.1-2008 specify an identifier, FLT_ROUNDS, defined in
107 <float.h>, which indicates the implementation-defined rounding behavior
108 for floating-point addition. This identifier has one of the following
109 values:
110 -1 The rounding mode is not determinable.
112 0 Rounding is toward 0.
114 1 Rounding is toward nearest number.
116 2 Rounding is toward positive infinity.
118 3 Rounding is toward negative infinity.
120 Other values represent machine-dependent, nonstandard rounding modes.
122 The value of FLT_ROUNDS should reflect the current rounding mode as set
124 by fesetround() (but see BUGS).
125 Floating-point environment
127 The entire floating-point environment, including control modes and sta‐
128 tus flags, can be handled as one opaque object, of type fenv_t. The
129 default environment is denoted by FE_DFL_ENV (of type const fenv_t *).
130 This is the environment setup at program start and it is defined by ISO
131 C to have round to nearest, all exceptions cleared and a nonstop (con‐
132 tinue on exceptions) mode.
133 The fegetenv() function saves the current floating-point environment in
135 the object *envp.
136 The feholdexcept() function does the same, then clears all exception
138 flags, and sets a nonstop (continue on exceptions) mode, if available.
139 It returns zero when successful.
140 The fesetenv() function restores the floating-point environment from
142 the object *envp. This object must be known to be valid, for example,
143 the result of a call to fegetenv() or feholdexcept() or equal to
144 FE_DFL_ENV. This call does not raise exceptions.
145 The feupdateenv() function installs the floating-point environment rep‐
147 resented by the object *envp, except that currently raised exceptions
148 are not cleared. After calling this function, the raised exceptions
149 will be a bitwise OR of those previously set with those in *envp. As
150 before, the object *envp must be known to be valid.
151
153 These functions return zero on success and nonzero if an error
154 occurred.
155
157 These functions first appeared in glibc in version 2.1.
158
160 For an explanation of the terms used in this section, see
161 attributes(7).
162 ┌────────────────────────────────────┬───────────────┬─────────┐
164 │Interface │ Attribute │ Value │
165 ├────────────────────────────────────┼───────────────┼─────────┤
166 │feclearexcept(), fegetexceptflag(), │ Thread safety │ MT-Safe │
167 │feraiseexcept(), fesetexceptflag(), │ │ │
168 │fetestexcept(), fegetround(), │ │ │
169 │fesetround(), fegetenv(), │ │ │
170 │feholdexcept(), fesetenv(), │ │ │
171 │feupdateenv(), feenableexcept(), │ │ │
172 │fedisableexcept(), fegetexcept() │ │ │
173 └────────────────────────────────────┴───────────────┴─────────┘
175 IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.
176
178 Glibc notes
179 If possible, the GNU C Library defines a macro FE_NOMASK_ENV which rep‐
180 resents an environment where every exception raised causes a trap to
181 occur. You can test for this macro using #ifdef. It is defined only
182 if _GNU_SOURCE is defined. The C99 standard does not define a way to
183 set individual bits in the floating-point mask, for example, to trap on
184 specific flags. Since version 2.2, glibc supports the functions feen‐
185 ableexcept() and fedisableexcept() to set individual floating-point
186 traps, and fegetexcept() to query the state.
187 #define _GNU_SOURCE /* See feature_test_macros(7) */
189 #include <fenv.h>
190 int feenableexcept(int excepts);
192 int fedisableexcept(int excepts);
193 int fegetexcept(void);
194 The feenableexcept() and fedisableexcept() functions enable (disable)
196 traps for each of the exceptions represented by excepts and return the
197 previous set of enabled exceptions when successful, and -1 otherwise.
198 The fegetexcept() function returns the set of all currently enabled ex‐
199 ceptions.
200
202 C99 specifies that the value of FLT_ROUNDS should reflect changes to
203 the current rounding mode, as set by fesetround(). Currently, this
204 does not occur: FLT_ROUNDS always has the value 1.
205
207 math_error(7)
208
210 This page is part of release 5.02 of the Linux man-pages project. A
211 description of the project, information about reporting bugs, and the
212 latest version of this page, can be found at
213 https://www.kernel.org/doc/man-pages/.
214Linux 2017-09-15 FENV(3)