original/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  2014-04-01 "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 .sp
  37 .BI "int feclearexcept(int " excepts );
  38 .br
  39 .BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts );
  40 .br
  41 .BI "int feraiseexcept(int " excepts );
  42 .br
  43 .BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts );
  44 .br
  45 .BI "int fetestexcept(int " excepts );
  46 .sp
  47 .B "int fegetround(void);"
  48 .br
  49 .BI "int fesetround(int " rounding_mode );
  50 .sp
  51 .BI "int fegetenv(fenv_t *" envp );
  52 .br
  53 .BI "int feholdexcept(fenv_t *" envp );
  54 .br
  55 .BI "int fesetenv(const fenv_t *" envp );
  56 .br
  57 .BI "int feupdateenv(const fenv_t *" envp );
  58 .fi
  59 .sp
  60 Link with \fI\-lm\fP.
  61 .SH DESCRIPTION
  62 These eleven functions were defined in C99, and describe the handling
  63 of floating-point rounding and exceptions (overflow, zero-divide, etc.).
  64 .SS Exceptions
  65 The
  66 .I divide-by-zero
  67 exception occurs when an operation on finite numbers
  68 produces infinity as exact answer.
  69 .LP
  70 The
  71 .I overflow
  72 exception occurs when a result has to be represented as a
  73 floating-point number, but has (much) larger absolute value than the
  74 largest (finite) floating-point number that is representable.
  75 .LP
  76 The
  77 .I underflow
  78 exception occurs when a result has to be represented as a
  79 floating-point number, but has smaller absolute value than the smallest
  80 positive normalized floating-point number (and would lose much accuracy
  81 when represented as a denormalized number).
  82 .LP
  83 The
  84 .I inexact
  85 exception occurs when the rounded result of an operation
  86 is not equal to the infinite precision result.
  87 It may occur whenever
  88 .I overflow
  89 or
  90 .I underflow
  91 occurs.
  92 .LP
  93 The
  94 .I invalid
  95 exception occurs when there is no well-defined result
  96 for an operation, as for 0/0 or infinity \- infinity or sqrt(\-1).
  97 .SS Exception handling
  98 Exceptions are represented in two ways: as a single bit
  99 (exception present/absent), and these bits correspond in some
 100 implementation-defined way with bit positions in an integer,
 101 and also as an opaque structure that may contain more information
 102 about the exception (perhaps the code address where it occurred).
 103 .LP
 104 Each of the macros
 105 .BR FE_DIVBYZERO ,
 106 .BR FE_INEXACT ,
 107 .BR FE_INVALID ,
 108 .BR FE_OVERFLOW ,
 109 .B FE_UNDERFLOW
 110 is defined when the implementation supports handling
 111 of the corresponding exception, and if so then
 112 defines the corresponding bit(s), so that one can call
 113 exception handling functions, for example, using the integer argument
 114 .BR FE_OVERFLOW | FE_UNDERFLOW .
 115 Other exceptions may be supported.
 116 The macro
 117 .B FE_ALL_EXCEPT
 118 is the bitwise OR of all bits corresponding to supported exceptions.
 119 .PP
 120 The
 121 .BR feclearexcept ()
 122 function clears the supported exceptions represented by the bits
 123 in its argument.
 124 .LP
 125 The
 126 .BR fegetexceptflag ()
 127 function stores a representation of the state of the exception flags
 128 represented by the argument
 129 .I excepts
 130 in the opaque object
 131 .IR *flagp .
 132 .LP
 133 The
 134 .BR feraiseexcept ()
 135 function raises the supported exceptions represented by the bits in
 136 .IR excepts .
 137 .LP
 138 The
 139 .BR fesetexceptflag ()
 140 function sets the complete status for the exceptions represented by
 141 .I excepts
 142 to the value
 143 .IR *flagp .
 144 This value must have been obtained by an earlier call of
 145 .BR fegetexceptflag ()
 146 with a last argument that contained all bits in
 147 .IR excepts .
 148 .LP
 149 The
 150 .BR fetestexcept ()
 151 function returns a word in which the bits are set that were
 152 set in the argument
 153 .I excepts
 154 and for which the corresponding exception is currently set.
 155 .SS Rounding mode
 156 The rounding mode determines how the result of floating-point operations
 157 is treated when the result cannot be exactly represented in the significand.
 158 Various rounding modes may be provided:
 159 round to nearest (the default),
 160 round up (toward positive infinity),
 161 round down (toward negative infinity), and
 162 round toward zero.
 163
 164 Each of the macros
 165 .BR FE_TONEAREST ,
 166 .BR FE_UPWARD ,
 167 .BR FE_DOWNWARD ,
 168 and
 169 .BR FE_TOWARDZERO
 170 is defined when the implementation supports getting and setting
 171 the corresponding rounding direction.
 172 .LP
 173 The
 174 .BR fegetround ()
 175 function returns the macro corresponding to the current
 176 rounding mode.
 177 .LP
 178 The
 179 .BR fesetround ()
 180 function sets the rounding mode as specified by its argument
 181 and returns zero when it was successful.
 182
 183 C99 and POSIX.1-2008 specify an identifier,
 184 .BR FLT_ROUNDS ,
 185 defined in
 186 .IR <float.h> ,
 187 which indicates the implementation-defined rounding
 188 behavior for floating-point addition.
 189 This identifier has one of the following values:
 190 .IP \-1
 191 The rounding mode is not determinable.
 192 .IP 0
 193 Rounding is toward 0.
 194 .IP 1
 195 Rounding is toward nearest number.
 196 .IP 2
 197 Rounding is toward positive infinity.
 198 .IP 3
 199 Rounding is toward negative infinity.
 200 .PP
 201 Other values represent machine-dependent, nonstandard rounding modes.
 202 .PP
 203 The value of
 204 .BR FLT_ROUNDS
 205 should reflect the current rounding mode as set by
 206 .BR fesetround ()
 207 (but see BUGS).
 208 .SS Floating-point environment
 209 The entire floating-point environment, including
 210 control modes and status flags, can be handled
 211 as one opaque object, of type
 212 .IR fenv_t .
 213 The default environment is denoted by
 214 .B FE_DFL_ENV
 215 (of type
 216 .IR "const fenv_t\ *" ).
 217 This is the environment setup at program start and it is defined by
 218 ISO C to have round to nearest, all exceptions cleared and a nonstop
 219 (continue on exceptions) mode.
 220 .LP
 221 The
 222 .BR fegetenv ()
 223 function saves the current floating-point environment in the object
 224 .IR *envp .
 225 .LP
 226 The
 227 .BR feholdexcept ()
 228 function does the same, then clears all exception flags,
 229 and sets a nonstop (continue on exceptions) mode,
 230 if available.
 231 It returns zero when successful.
 232 .LP
 233 The
 234 .BR fesetenv ()
 235 function restores the floating-point environment from
 236 the object
 237 .IR *envp .
 238 This object must be known to be valid, for example, the result of a call to
 239 .BR fegetenv ()
 240 or
 241 .BR feholdexcept ()
 242 or equal to
 243 .BR FE_DFL_ENV .
 244 This call does not raise exceptions.
 245 .LP
 246 The
 247 .BR feupdateenv ()
 248 function installs the floating-point environment represented by
 249 the object
 250 .IR *envp ,
 251 except that currently raised exceptions are not cleared.
 252 After calling this function, the raised exceptions will be a bitwise OR
 253 of those previously set with those in
 254 .IR *envp .
 255 As before, the object
 256 .I *envp
 257 must be known to be valid.
 258 .SH RETURN VALUE
 259 These functions return zero on success and nonzero if an error occurred.
 260 .\" Earlier seven of these functions were listed as returning void.
 261 .\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E))
 262 .\" of the C99 Standard.
 263 .SH VERSIONS
 264 These functions first appeared in glibc in version 2.1.
 265 .SH ATTRIBUTES
 266 .SS Multithreading (see pthreads(7))
 267 The
 268 .BR feclearexcept (),
 269 .BR fegetexceptflag (),
 270 .BR fegetexceptflag (),
 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 and
 282 .BR fegetexcept ()
 283 functions are thread-safe.
 284 .SH CONFORMING TO
 285 IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.
 286 .SH NOTES
 287 .SS Glibc notes
 288 If possible, the GNU C Library defines a macro
 289 .B FE_NOMASK_ENV
 290 which represents an environment where every exception raised causes a
 291 trap to occur.
 292 You can test for this macro using
 293 .BR #ifdef .
 294 It is defined only if
 295 .B _GNU_SOURCE
 296 is defined.
 297 The C99 standard does not define a way to set individual bits in the
 298 floating-point mask, for example, to trap on specific flags.
 299 Since version 2.2, glibc supports the functions
 300 .BR feenableexcept ()
 301 and
 302 .BR fedisableexcept ()
 303 to set individual floating-point traps, and
 304 .BR fegetexcept ()
 305 to query the state.
 306 .sp
 307 .nf
 308 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
 309 .br
 310 .B "#include <fenv.h>"
 311 .sp
 312 .BI "int feenableexcept(int " excepts );
 313 .br
 314 .BI "int fedisableexcept(int " excepts );
 315 .br
 316 .B "int fegetexcept(void);"
 317 .br
 318 .fi
 319 .LP
 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)
 344 .SH COLOPHON
 345 This page is part of release 3.68 of the Linux
 346 .I man-pages
 347 project.
 348 A description of the project,
 349 information about reporting bugs,
 350 and the latest version of this page,
 351 can be found at
 352 \%http://www.kernel.org/doc/man\-pages/.