man3/fenv.3

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