1 .\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
3 .\" This is free documentation; you can redistribute it and/or
4 .\" modify it under the terms of the GNU General Public License as
5 .\" published by the Free Software Foundation; either version 2 of
6 .\" the License, or (at your option) any later version.
8 .\" The GNU General Public License's references to "object code"
9 .\" and "executables" are to be interpreted as the output of any
10 .\" document formatting or typesetting system, including
11 .\" intermediate and printed output.
13 .\" This manual is distributed in the hope that it will be useful,
14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 .\" GNU General Public License for more details.
18 .\" You should have received a copy of the GNU General Public
19 .\" License along with this manual; if not, write to the Free
20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
23 .\" 2000-08-14 added GNU additions from Andreas Jaeger
24 .\" 2000-12-05 some changes inspired by acahalan's remarks
26 .TH FENV 3 2010-10-31 "Linux" "Linux Programmer's Manual"
28 feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
29 fetestexcept, fegetenv, fegetround, feholdexcept, fesetround,
30 fesetenv, feupdateenv, feenableexcept, fedisableexcept,
31 fegetexcept \- floating-point rounding and exception handling
36 .BI "int feclearexcept(int " excepts );
38 .BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts );
40 .BI "int feraiseexcept(int " excepts );
42 .BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts );
44 .BI "int fetestexcept(int " excepts );
46 .B "int fegetround(void);"
48 .BI "int fesetround(int " rounding_mode );
50 .BI "int fegetenv(fenv_t *" envp );
52 .BI "int feholdexcept(fenv_t *" envp );
54 .BI "int fesetenv(const fenv_t *" envp );
56 .BI "int feupdateenv(const fenv_t *" envp );
61 These eleven functions were defined in C99, and describe the handling
62 of floating-point rounding and exceptions (overflow, zero-divide etc.).
66 exception occurs when an operation on finite numbers
67 produces infinity as exact answer.
71 exception occurs when a result has to be represented as a
72 floating-point number, but has (much) larger absolute value than the
73 largest (finite) floating-point number that is representable.
77 exception occurs when a result has to be represented as a
78 floating-point number, but has smaller absolute value than the smallest
79 positive normalized floating-point number (and would lose much accuracy
80 when represented as a denormalized number).
84 exception occurs when the rounded result of an operation
85 is not equal to the infinite precision result.
94 exception occurs when there is no well-defined result
95 for an operation, as for 0/0 or infinity \- infinity or sqrt(\-1).
96 .SS "Exception handling"
97 Exceptions are represented in two ways: as a single bit
98 (exception present/absent), and these bits correspond in some
99 implementation-defined way with bit positions in an integer,
100 and also as an opaque structure that may contain more information
101 about the exception (perhaps the code address where it occurred).
109 is defined when the implementation supports handling
110 of the corresponding exception, and if so then
111 defines the corresponding bit(s), so that one can call
112 exception handling functions, for example, using the integer argument
113 .BR FE_OVERFLOW | FE_UNDERFLOW .
114 Other exceptions may be supported.
117 is the bitwise OR of all bits corresponding to supported exceptions.
121 function clears the supported exceptions represented by the bits
125 .BR fegetexceptflag ()
126 function stores a representation of the state of the exception flags
127 represented by the argument
134 function raises the supported exceptions represented by the bits in
138 .BR fesetexceptflag ()
139 function sets the complete status for the exceptions represented by
143 This value must have been obtained by an earlier call of
144 .BR fegetexceptflag ()
145 with a last argument that contained all bits in
150 function returns a word in which the bits are set that were
153 and for which the corresponding exception is currently set.
155 The rounding mode determines how the result of floating-point operations
156 is treated when the result cannot be exactly represented in the significand.
157 Various rounding modes may be provided:
158 round to nearest (the default),
159 round up (toward positive infinity),
160 round down (toward negative infinity), and
169 is defined when the implementation supports getting and setting
170 the corresponding rounding direction.
174 function returns the macro corresponding to the current
179 function sets the rounding mode as specified by its argument
180 and returns zero when it was successful.
182 C99 and POSIX.1-2008 specify an identifier,
186 which indicates the implementation-defined rounding
187 behavior for floating-point addition.
188 This identifier has one of the following values:
190 The rounding mode is not determinable.
192 Rounding is toward 0.
194 Rounding is toward nearest number.
196 Rounding is toward positive infinity.
198 Rounding is toward negative infinity.
200 Other values represent machine-dependent, nonstandard rounding modes.
204 should reflect the current rounding mode as set by
207 .SS "Floating-point environment"
208 The entire floating-point environment, including
209 control modes and status flags, can be handled
210 as one opaque object, of type
212 The default environment is denoted by
215 .IR "const fenv_t *" ).
216 This is the environment setup at program start and it is defined by
217 ISO C to have round to nearest, all exceptions cleared and a nonstop
218 (continue on exceptions) mode.
222 function saves the current floating-point environment in the object
227 function does the same, then clears all exception flags,
228 and sets a nonstop (continue on exceptions) mode,
230 It returns zero when successful.
234 function restores the floating-point environment from
237 This object must be known to be valid, for example, the result of a call to
243 This call does not raise exceptions.
247 function installs the floating-point environment represented by
250 except that currently raised exceptions are not cleared.
251 After calling this function, the raised exceptions will be a bitwise OR
252 of those previously set with those in
254 As before, the object
256 must be known to be valid.
258 These functions return zero on success and nonzero if an error occurred.
259 .\" Earlier seven of these functions were listed as returning void.
260 .\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E))
261 .\" of the C99 Standard.
263 These functions first appeared in glibc in version 2.1.
265 IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.
268 If possible, the GNU C Library defines a macro
270 which represents an environment where every exception raised causes a
272 You can test for this macro using
274 It is only defined if
277 The C99 standard does not define a way to set individual bits in the
278 floating-point mask, for example, to trap on specific flags.
279 Since version 2.2, glibc supports the functions
280 .BR feenableexcept ()
282 .BR fedisableexcept ()
283 to set individual floating-point traps, and
288 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
290 .B "#include <fenv.h>"
292 .BI "int feenableexcept(int " excepts );
294 .BI "int fedisableexcept(int " excepts );
296 .B "int fegetexcept(void);"
301 .BR feenableexcept ()
303 .BR fedisableexcept ()
304 functions enable (disable) traps for each of the exceptions represented by
306 and return the previous set of enabled exceptions when successful,
310 function returns the set of all currently enabled exceptions.
312 C99 specifies that the value of
314 should reflect changes to the current rounding mode, as set by
317 .\" Aug 08, glibc 2.8
320 always has the value 1.
321 .\" See http://gcc.gnu.org/ml/gcc/2002-02/msg01535.html
323 .BR feature_test_macros (7),