Debian Codegraph @

upstream/debian-trixie/man3/fenv.3

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