manual/LDP_man-pages/original/man3/fenv.3

   1 .\" Copyright (c) 2000 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   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.
   7 .\"
   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.
  12 .\"
  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.
  17 .\"
  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,
  21 .\" USA.
  22 .\"
  23 .\" 2000-08-14 added GNU additions from Andreas Jaeger
  24 .\" 2000-12-05 some changes inspired by acahalan's remarks
  25 .\"
  26 .TH FENV 3  2008-08-11 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag,
  29 fetestexcept, fegetenv, fegetround, feholdexcept, fesetround,
  30 fesetenv, feupdateenv, feenableexcept, fedisableexcept,
  31 fegetexcept \- floating-point rounding and exception handling
  32 .SH SYNOPSIS
  33 .nf
  34 .B #include <fenv.h>
  35 .sp
  36 .BI "int feclearexcept(int " excepts );
  37 .br
  38 .BI "int fegetexceptflag(fexcept_t *" flagp ", int " excepts );
  39 .br
  40 .BI "int feraiseexcept(int " excepts );
  41 .br
  42 .BI "int fesetexceptflag(const fexcept_t *" flagp ", int " excepts );
  43 .br
  44 .BI "int fetestexcept(int " excepts );
  45 .sp
  46 .B "int fegetround(void);"
  47 .br
  48 .BI "int fesetround(int " rounding_mode );
  49 .sp
  50 .BI "int fegetenv(fenv_t *" envp );
  51 .br
  52 .BI "int feholdexcept(fenv_t *" envp );
  53 .br
  54 .BI "int fesetenv(const fenv_t *" envp );
  55 .br
  56 .BI "int feupdateenv(const fenv_t *" envp );
  57 .fi
  58 .sp
  59 Link with \fI\-lm\fP.
  60 .SH DESCRIPTION
  61 These eleven functions were defined in C99, and describe the handling
  62 of floating-point rounding and exceptions (overflow, zero-divide etc.).
  63 .SS Exceptions
  64 The
  65 .I divide-by-zero
  66 exception occurs when an operation on finite numbers
  67 produces infinity as exact answer.
  68 .LP
  69 The
  70 .I overflow
  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.
  74 .LP
  75 The
  76 .I underflow
  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).
  81 .LP
  82 The
  83 .I inexact
  84 exception occurs when the rounded result of an operation
  85 is not equal to the infinite precision result.
  86 It may occur whenever
  87 .I overflow
  88 or
  89 .I underflow
  90 occurs.
  91 .LP
  92 The
  93 .I invalid
  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).
 102 .LP
 103 Each of the macros
 104 .BR FE_DIVBYZERO ,
 105 .BR FE_INEXACT ,
 106 .BR FE_INVALID ,
 107 .BR FE_OVERFLOW ,
 108 .B FE_UNDERFLOW
 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.
 115 The macro
 116 .B FE_ALL_EXCEPT
 117 is the bitwise OR of all bits corresponding to supported exceptions.
 118 .PP
 119 The
 120 .BR feclearexcept ()
 121 function clears the supported exceptions represented by the bits
 122 in its argument.
 123 .LP
 124 The
 125 .BR fegetexceptflag ()
 126 function stores a representation of the state of the exception flags
 127 represented by the argument
 128 .I excepts
 129 in the opaque object
 130 .IR *flagp .
 131 .LP
 132 The
 133 .BR feraiseexcept ()
 134 function raises the supported exceptions represented by the bits in
 135 .IR excepts .
 136 .LP
 137 The
 138 .BR fesetexceptflag ()
 139 function sets the complete status for the exceptions represented by
 140 .I excepts
 141 to the value
 142 .IR *flagp .
 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
 146 .IR excepts .
 147 .LP
 148 The
 149 .BR fetestexcept ()
 150 function returns a word in which the bits are set that were
 151 set in the argument
 152 .I excepts
 153 and for which the corresponding exception is currently set.
 154 .SS Rounding mode
 155 The rounding mode determines how the result of floating-point operations
 156 is treated when the result cannot be exactly represented in the signifcand.
 157 Various rounding modes may be provided:
 158 round to nearest (the default),
 159 round up (towards positive infinity),
 160 round down (towards negative infinity), and
 161 round towards zero.
 162
 163 Each of the macros
 164 .BR FE_TONEAREST ,
 165 .BR FE_UPWARD ,
 166 .BR FE_DOWNWARD ,
 167 and
 168 .BR FE_TOWARDZERO
 169 is defined when the implementation supports getting and setting
 170 the corresponding rounding direction.
 171 .LP
 172 The
 173 .BR fegetround ()
 174 function returns the macro corresponding to the current
 175 rounding mode.
 176 .LP
 177 The
 178 .BR fesetround ()
 179 function sets the rounding mode as specified by its argument
 180 and returns zero when it was successful.
 181
 182 C99 and POSIX.1-2008 specify an identifier,
 183 .BR FLT_ROUNDS ,
 184 defined in
 185 .IR <float.h> ,
 186 which indicates the implementation-defined rounding
 187 behavior for floating-point addition.
 188 This identifier has one of the following values:
 189 .IP \-1
 190 The rounding mode is not determinable.
 191 .IP 0
 192 Rounding is towards 0.
 193 .IP 1
 194 Rounding is towards nearest number.
 195 .IP 2
 196 Rounding is towards positive infinity.
 197 .IP 3
 198 Rounding is towards negative infinity.
 199 .PP
 200 Other values represent machine-dependent, nonstandard rounding modes.
 201 .PP
 202 The value of
 203 .BR FLT_ROUNDS
 204 should reflect the current rounding mode as set by
 205 .BR fesetround ()
 206 (but see BUGS).
 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
 211 .IR fenv_t .
 212 The default environment is denoted by
 213 .B FE_DFL_ENV
 214 (of type
 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.
 219 .LP
 220 The
 221 .BR fegetenv ()
 222 function saves the current floating-point environment in the object
 223 .IR *envp .
 224 .LP
 225 The
 226 .BR feholdexcept ()
 227 function does the same, then clears all exception flags,
 228 and sets a nonstop (continue on exceptions) mode,
 229 if available.
 230 It returns zero when successful.
 231 .LP
 232 The
 233 .BR fesetenv ()
 234 function restores the floating-point environment from
 235 the object
 236 .IR *envp .
 237 This object must be known to be valid, for example, the result of a call to
 238 .BR fegetenv ()
 239 or
 240 .BR feholdexcept ()
 241 or equal to
 242 .BR FE_DFL_ENV .
 243 This call does not raise exceptions.
 244 .LP
 245 The
 246 .BR feupdateenv ()
 247 function installs the floating-point environment represented by
 248 the object
 249 .IR *envp ,
 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
 253 .IR *envp .
 254 As before, the object
 255 .I *envp
 256 must be known to be valid.
 257 .SH "RETURN VALUE"
 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.
 262 .SH VERSIONS
 263 These functions first appeared in glibc in version 2.1.
 264 .SH "CONFORMING TO"
 265 IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.
 266 .SH NOTES
 267 .SS Glibc Notes
 268 If possible, the GNU C Library defines a macro
 269 .B FE_NOMASK_ENV
 270 which represents an environment where every exception raised causes a
 271 trap to occur.
 272 You can test for this macro using
 273 .BR #ifdef .
 274 It is only defined if
 275 .B _GNU_SOURCE
 276 is defined.
 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 glibc 2.2 supports the functions
 280 .BR feenableexcept ()
 281 and
 282 .BR fedisableexcept ()
 283 to set individual floating-point traps, and
 284 .BR fegetexcept ()
 285 to query the state.
 286 .sp
 287 .nf
 288 .B "#define _GNU_SOURCE"
 289 .br
 290 .B "#include <fenv.h>"
 291 .sp
 292 .BI "int feenableexcept(int " excepts );
 293 .br
 294 .BI "int fedisableexcept(int " excepts );
 295 .br
 296 .B "int fegetexcept(void);"
 297 .br
 298 .fi
 299 .LP
 300 The
 301 .BR feenableexcept ()
 302 and
 303 .BR fedisableexcept ()
 304 functions enable (disable) traps for each of the exceptions represented by
 305 .I excepts
 306 and return the previous set of enabled exceptions when successful,
 307 and \-1 otherwise.
 308 The
 309 .BR fegetexcept ()
 310 function returns the set of all currently enabled exceptions.
 311 .SH BUGS
 312 C99 specifies that the value of
 313 .B FLT_ROUNDS
 314 should reflect changes to the current rounding mode, as set by
 315 .BR fesetround ().
 316 Currently,
 317 .\" Aug 08, glibc 2.8
 318 this does not occur:
 319 .B FLT_ROUNDS
 320 always has the value 1.
 321 .\" See http://gcc.gnu.org/ml/gcc/2002-02/msg01535.html
 322 .SH "SEE ALSO"
 323 .BR feature_test_macros (7),
 324 .BR math_error (7)