1fenv(3) Library Functions Manual fenv(3)
2
6 feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetes‐
7 texcept, fegetenv, fegetround, feholdexcept, fesetround, fesetenv, fe‐
8 updateenv, feenableexcept, fedisableexcept, fegetexcept - floating-
9 point rounding and exception handling
10
12 Math library (libm, -lm)
13
15 #include <fenv.h>
16 int feclearexcept(int excepts);
18 int fegetexceptflag(fexcept_t *flagp, int excepts);
19 int feraiseexcept(int excepts);
20 int fesetexceptflag(const fexcept_t *flagp, int excepts);
21 int fetestexcept(int excepts);
22 int fegetround(void);
24 int fesetround(int rounding_mode);
25 int fegetenv(fenv_t *envp);
27 int feholdexcept(fenv_t *envp);
28 int fesetenv(const fenv_t *envp);
29 int feupdateenv(const fenv_t *envp);
30
32 These eleven functions were defined in C99, and describe the handling
33 of floating-point rounding and exceptions (overflow, zero-divide,
34 etc.).
35 Exceptions
37 The divide-by-zero exception occurs when an operation on finite numbers
38 produces infinity as exact answer.
39 The overflow exception occurs when a result has to be represented as a
41 floating-point number, but has (much) larger absolute value than the
42 largest (finite) floating-point number that is representable.
43 The underflow exception occurs when a result has to be represented as a
45 floating-point number, but has smaller absolute value than the smallest
46 positive normalized floating-point number (and would lose much accuracy
47 when represented as a denormalized number).
48 The inexact exception occurs when the rounded result of an operation is
50 not equal to the infinite precision result. It may occur whenever
51 overflow or underflow occurs.
52 The invalid exception occurs when there is no well-defined result for
54 an operation, as for 0/0 or infinity - infinity or sqrt(-1).
55 Exception handling
57 Exceptions are represented in two ways: as a single bit (exception
58 present/absent), and these bits correspond in some implementation-de‐
59 fined way with bit positions in an integer, and also as an opaque
60 structure that may contain more information about the exception (per‐
61 haps the code address where it occurred).
62 Each of the macros FE_DIVBYZERO, FE_INEXACT, FE_INVALID, FE_OVERFLOW,
64 FE_UNDERFLOW is defined when the implementation supports handling of
65 the corresponding exception, and if so then defines the corresponding
66 bit(s), so that one can call exception handling functions, for example,
67 using the integer argument FE_OVERFLOW|FE_UNDERFLOW. Other exceptions
68 may be supported. The macro FE_ALL_EXCEPT is the bitwise OR of all
69 bits corresponding to supported exceptions.
70 The feclearexcept() function clears the supported exceptions repre‐
72 sented by the bits in its argument.
73 The fegetexceptflag() function stores a representation of the state of
75 the exception flags represented by the argument excepts in the opaque
76 object *flagp.
77 The feraiseexcept() function raises the supported exceptions repre‐
79 sented by the bits in excepts.
80 The fesetexceptflag() function sets the complete status for the excep‐
82 tions represented by excepts to the value *flagp. This value must have
83 been obtained by an earlier call of fegetexceptflag() with a last argu‐
84 ment that contained all bits in excepts.
85 The fetestexcept() function returns a word in which the bits are set
87 that were set in the argument excepts and for which the corresponding
88 exception is currently set.
89 Rounding mode
91 The rounding mode determines how the result of floating-point opera‐
92 tions is treated when the result cannot be exactly represented in the
93 significand. Various rounding modes may be provided: round to nearest
94 (the default), round up (toward positive infinity), round down (toward
95 negative infinity), and round toward zero.
96 Each of the macros FE_TONEAREST, FE_UPWARD, FE_DOWNWARD, and FE_TO‐
98 WARDZERO is defined when the implementation supports getting and set‐
99 ting the corresponding rounding direction.
100 The fegetround() function returns the macro corresponding to the cur‐
102 rent rounding mode.
103 The fesetround() function sets the rounding mode as specified by its
105 argument and returns zero when it was successful.
106 C99 and POSIX.1-2008 specify an identifier, FLT_ROUNDS, defined in
108 <float.h>, which indicates the implementation-defined rounding behavior
109 for floating-point addition. This identifier has one of the following
110 values:
111 -1 The rounding mode is not determinable.
113 0 Rounding is toward 0.
115 1 Rounding is toward nearest number.
117 2 Rounding is toward positive infinity.
119 3 Rounding is toward negative infinity.
121 Other values represent machine-dependent, nonstandard rounding modes.
123 The value of FLT_ROUNDS should reflect the current rounding mode as set
125 by fesetround() (but see BUGS).
126 Floating-point environment
128 The entire floating-point environment, including control modes and sta‐
129 tus flags, can be handled as one opaque object, of type fenv_t. The
130 default environment is denoted by FE_DFL_ENV (of type const fenv_t *).
131 This is the environment setup at program start and it is defined by ISO
132 C to have round to nearest, all exceptions cleared and a nonstop (con‐
133 tinue on exceptions) mode.
134 The fegetenv() function saves the current floating-point environment in
136 the object *envp.
137 The feholdexcept() function does the same, then clears all exception
139 flags, and sets a nonstop (continue on exceptions) mode, if available.
140 It returns zero when successful.
141 The fesetenv() function restores the floating-point environment from
143 the object *envp. This object must be known to be valid, for example,
144 the result of a call to fegetenv() or feholdexcept() or equal to
145 FE_DFL_ENV. This call does not raise exceptions.
146 The feupdateenv() function installs the floating-point environment rep‐
148 resented by the object *envp, except that currently raised exceptions
149 are not cleared. After calling this function, the raised exceptions
150 will be a bitwise OR of those previously set with those in *envp. As
151 before, the object *envp must be known to be valid.
152
154 These functions return zero on success and nonzero if an error oc‐
155 curred.
156
158 For an explanation of the terms used in this section, see at‐
159 tributes(7).
160 ┌────────────────────────────────────────────┬───────────────┬─────────┐
162 │Interface │ Attribute │ Value │
163 ├────────────────────────────────────────────┼───────────────┼─────────┤
164 │feclearexcept(), fegetexceptflag(), │ Thread safety │ MT-Safe │
165 │feraiseexcept(), fesetexceptflag(), │ │ │
166 │fetestexcept(), fegetround(), fesetround(), │ │ │
167 │fegetenv(), feholdexcept(), fesetenv(), │ │ │
168 │feupdateenv(), feenableexcept(), │ │ │
169 │fedisableexcept(), fegetexcept() │ │ │
170 └────────────────────────────────────────────┴───────────────┴─────────┘
171
173 C11, POSIX.1-2008, IEC 60559 (IEC 559:1989), ANSI/IEEE 854.
174
176 C99, POSIX.1-2001. glibc 2.1.
177
179 glibc notes
180 If possible, the GNU C Library defines a macro FE_NOMASK_ENV which rep‐
181 resents an environment where every exception raised causes a trap to
182 occur. You can test for this macro using #ifdef. It is defined only
183 if _GNU_SOURCE is defined. The C99 standard does not define a way to
184 set individual bits in the floating-point mask, for example, to trap on
185 specific flags. Since glibc 2.2, glibc supports the functions feen‐
186 ableexcept() and fedisableexcept() to set individual floating-point
187 traps, and fegetexcept() to query the state.
188 #define _GNU_SOURCE /* See feature_test_macros(7) */
190 #include <fenv.h>
191 int feenableexcept(int excepts);
193 int fedisableexcept(int excepts);
194 int fegetexcept(void);
195 The feenableexcept() and fedisableexcept() functions enable (disable)
197 traps for each of the exceptions represented by excepts and return the
198 previous set of enabled exceptions when successful, and -1 otherwise.
199 The fegetexcept() function returns the set of all currently enabled ex‐
200 ceptions.
201
203 C99 specifies that the value of FLT_ROUNDS should reflect changes to
204 the current rounding mode, as set by fesetround(). Currently, this
205 does not occur: FLT_ROUNDS always has the value 1.
206
208 math_error(7)
209Linux man-pages 6.05 2023-07-20 fenv(3)