| 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) |