Debian Codegraph @

upstream/debian-unstable/man3/fenv.3

raw
1 '\" t
2 .\" Copyright 2000, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH fenv 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
10 fetestexcept, fegetenv, fegetround, feholdexcept, fesetround,
11 fesetenv, feupdateenv, feenableexcept, fedisableexcept,
12 fegetexcept \- floating-point rounding and exception handling
13 .SH LIBRARY
14 Math library
15 .RI ( libm ,\~ \-lm )
16 .SH SYNOPSIS
17 .nf
18 .B #include <fenv.h>
19 .P
20 .BI "int feclearexcept(int " excepts );
21 .BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts );
22 .BI "int feraiseexcept(int " excepts );
23 .BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts );
24 .BI "int fetestexcept(int " excepts );
25 .P
26 .B "int fegetround(void);"
27 .BI "int fesetround(int " rounding_mode );
28 .P
29 .BI "int fegetenv(fenv_t *" envp );
30 .BI "int feholdexcept(fenv_t *" envp );
31 .BI "int fesetenv(const fenv_t *" envp );
32 .BI "int feupdateenv(const fenv_t *" envp );
33 .fi
34 .SH DESCRIPTION
35 These eleven functions were defined in C99, and describe the handling
36 of floating-point rounding and exceptions (overflow, zero-divide, etc.).
37 .SS Exceptions
38 The
39 .I divide-by-zero
40 exception occurs when an operation on finite numbers
41 produces infinity as exact answer.
42 .P
43 The
44 .I overflow
45 exception occurs when a result has to be represented as a
46 floating-point number, but has (much) larger absolute value than the
47 largest (finite) floating-point number that is representable.
48 .P
49 The
50 .I underflow
51 exception occurs when a result has to be represented as a
52 floating-point number, but has smaller absolute value than the smallest
53 positive normalized floating-point number (and would lose much accuracy
54 when represented as a denormalized number).
55 .P
56 The
57 .I inexact
58 exception occurs when the rounded result of an operation
59 is not equal to the infinite precision result.
60 It may occur whenever
61 .I overflow
62 or
63 .I underflow
64 occurs.
65 .P
66 The
67 .I invalid
68 exception occurs when there is no well-defined result
69 for an operation, as for 0/0 or infinity \- infinity or sqrt(\-1).
70 .SS Exception handling
71 Exceptions are represented in two ways: as a single bit
72 (exception present/absent), and these bits correspond in some
73 implementation-defined way with bit positions in an integer,
74 and also as an opaque structure that may contain more information
75 about the exception (perhaps the code address where it occurred).
76 .P
77 Each of the macros
78 .BR FE_DIVBYZERO ,
79 .BR FE_INEXACT ,
80 .BR FE_INVALID ,
81 .BR FE_OVERFLOW ,
82 .B FE_UNDERFLOW
83 is defined when the implementation supports handling
84 of the corresponding exception, and if so then
85 defines the corresponding bit(s), so that one can call
86 exception handling functions, for example, using the integer argument
87 .BR FE_OVERFLOW | FE_UNDERFLOW .
88 Other exceptions may be supported.
89 The macro
90 .B FE_ALL_EXCEPT
91 is the bitwise OR of all bits corresponding to supported exceptions.
92 .P
93 The
94 .BR feclearexcept ()
95 function clears the supported exceptions represented by the bits
96 in its argument.
97 .P
98 The
99 .BR fegetexceptflag ()
100 function stores a representation of the state of the exception flags
101 represented by the argument
102 .I excepts
103 in the opaque object
104 .IR *flagp .
105 .P
106 The
107 .BR feraiseexcept ()
108 function raises the supported exceptions represented by the bits in
109 .IR excepts .
110 .P
111 The
112 .BR fesetexceptflag ()
113 function sets the complete status for the exceptions represented by
114 .I excepts
115 to the value
116 .IR *flagp .
117 This value must have been obtained by an earlier call of
118 .BR fegetexceptflag ()
119 with a last argument that contained all bits in
120 .IR excepts .
121 .P
122 The
123 .BR fetestexcept ()
124 function returns a word in which the bits are set that were
125 set in the argument
126 .I excepts
127 and for which the corresponding exception is currently set.
128 .SS Rounding mode
129 The rounding mode determines how the result of floating-point operations
130 is treated when the result cannot be exactly represented in the significand.
131 Various rounding modes may be provided:
132 round to nearest (the default),
133 round up (toward positive infinity),
134 round down (toward negative infinity), and
135 round toward zero.
136 .P
137 Each of the macros
138 .BR FE_TONEAREST ,
139 .BR FE_UPWARD ,
140 .BR FE_DOWNWARD ,
141 and
142 .B FE_TOWARDZERO
143 is defined when the implementation supports getting and setting
144 the corresponding rounding direction.
145 .P
146 The
147 .BR fegetround ()
148 function returns the macro corresponding to the current
149 rounding mode.
150 .P
151 The
152 .BR fesetround ()
153 function sets the rounding mode as specified by its argument
154 and returns zero when it was successful.
155 .P
156 C99 and POSIX.1-2008 specify an identifier,
157 .BR FLT_ROUNDS ,
158 defined in
159 .IR <float.h> ,
160 which indicates the implementation-defined rounding
161 behavior for floating-point addition.
162 This identifier has one of the following values:
163 .TP
164 .B \-1
165 The rounding mode is not determinable.
166 .TP
167 .B 0
168 Rounding is toward 0.
169 .TP
170 .B 1
171 Rounding is toward nearest number.
172 .TP
173 .B 2
174 Rounding is toward positive infinity.
175 .TP
176 .B 3
177 Rounding is toward negative infinity.
178 .P
179 Other values represent machine-dependent, nonstandard rounding modes.
180 .P
181 The value of
182 .B FLT_ROUNDS
183 should reflect the current rounding mode as set by
184 .BR fesetround ()
185 (but see BUGS).
186 .SS Floating-point environment
187 The entire floating-point environment, including
188 control modes and status flags, can be handled
189 as one opaque object, of type
190 .IR fenv_t .
191 The default environment is denoted by
192 .B FE_DFL_ENV
193 (of type
194 .IR "const fenv_t\ *" ).
195 This is the environment setup at program start and it is defined by
196 ISO C to have round to nearest, all exceptions cleared and a nonstop
197 (continue on exceptions) mode.
198 .P
199 The
200 .BR fegetenv ()
201 function saves the current floating-point environment in the object
202 .IR *envp .
203 .P
204 The
205 .BR feholdexcept ()
206 function does the same, then clears all exception flags,
207 and sets a nonstop (continue on exceptions) mode,
208 if available.
209 It returns zero when successful.
210 .P
211 The
212 .BR fesetenv ()
213 function restores the floating-point environment from
214 the object
215 .IR *envp .
216 This object must be known to be valid, for example, the result of a call to
217 .BR fegetenv ()
218 or
219 .BR feholdexcept ()
220 or equal to
221 .BR FE_DFL_ENV .
222 This call does not raise exceptions.
223 .P
224 The
225 .BR feupdateenv ()
226 function installs the floating-point environment represented by
227 the object
228 .IR *envp ,
229 except that currently raised exceptions are not cleared.
230 After calling this function, the raised exceptions will be a bitwise OR
231 of those previously set with those in
232 .IR *envp .
233 As before, the object
234 .I *envp
235 must be known to be valid.
236 .SH RETURN VALUE
237 These functions return zero on success and nonzero if an error occurred.
238 .\" Earlier seven of these functions were listed as returning void.
239 .\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E))
240 .\" of the C99 Standard.
241 .SH ATTRIBUTES
242 For an explanation of the terms used in this section, see
243 .BR attributes (7).
244 .nh
245 .TS
246 allbox;
247 lbx lb lb
248 l l l.
249 Interface Attribute Value
250 T{
251 .na
252 .nh
253 .BR feclearexcept (),
254 .BR fegetexceptflag (),
255 .BR feraiseexcept (),
256 .BR fesetexceptflag (),
257 .BR fetestexcept (),
258 .BR fegetround (),
259 .BR fesetround (),
260 .BR fegetenv (),
261 .BR feholdexcept (),
262 .BR fesetenv (),
263 .BR feupdateenv (),
264 .BR feenableexcept (),
265 .BR fedisableexcept (),
266 .BR fegetexcept ()
267 T} Thread safety T{
268 .na
269 .nh
270 MT-Safe
271 T}
272 .TE
273 .hy
274 .SH STANDARDS
275 C11, POSIX.1-2008, IEC 60559 (IEC 559:1989), ANSI/IEEE 854.
276 .SH HISTORY
277 C99, POSIX.1-2001.
278 glibc 2.1.
279 .SH NOTES
280 .SS glibc notes
281 If possible, the GNU C Library defines a macro
282 .B FE_NOMASK_ENV
283 which represents an environment where every exception raised causes a
284 trap to occur.
285 You can test for this macro using
286 .BR #ifdef .
287 It is defined only if
288 .B _GNU_SOURCE
289 is defined.
290 The C99 standard does not define a way to set individual bits in the
291 floating-point mask, for example, to trap on specific flags.
292 Since glibc 2.2, glibc supports the functions
293 .BR feenableexcept ()
294 and
295 .BR fedisableexcept ()
296 to set individual floating-point traps, and
297 .BR fegetexcept ()
298 to query the state.
299 .P
300 .nf
301 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
302 .B "#include <fenv.h>"
303 .P
304 .BI "int feenableexcept(int " excepts );
305 .BI "int fedisableexcept(int " excepts );
306 .B "int fegetexcept(void);"
307 .fi
308 .P
309 The
310 .BR feenableexcept ()
311 and
312 .BR fedisableexcept ()
313 functions enable (disable) traps for each of the exceptions represented by
314 .I excepts
315 and return the previous set of enabled exceptions when successful,
316 and \-1 otherwise.
317 The
318 .BR fegetexcept ()
319 function returns the set of all currently enabled exceptions.
320 .SH BUGS
321 C99 specifies that the value of
322 .B FLT_ROUNDS
323 should reflect changes to the current rounding mode, as set by
324 .BR fesetround ().
325 Currently,
326 .\" Aug 08, glibc 2.8
327 this does not occur:
328 .B FLT_ROUNDS
329 always has the value 1.
330 .\" See http://gcc.gnu.org/ml/gcc/2002-02/msg01535.html
331 .SH SEE ALSO
332 .BR math_error (7)