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  2000-08-12 "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 DivideByZero exception occurs when an operation on finite numbers
  65 produces infinity as exact answer.
  66 .LP
  67 The Overflow exception occurs when a result has to be represented as a
  68 floating point number, but has (much) larger absolute value than the
  69 largest (finite) floating point number that is representable.
  70 .LP
  71 The Underflow exception occurs when a result has to be represented as a
  72 floating point number, but has smaller absolute value than the smallest
  73 positive normalized floating point number (and would lose much accuracy
  74 when represented as a denormalized number).
  75 .LP
  76 The Inexact exception occurs when the rounded result of an operation
  77 is not equal to the infinite precision result.
  78 It may occur whenever Overflow or Underflow occurs.
  79 .LP
  80 The Invalid exception occurs when there is no well-defined result
  81 for an operation, as for 0/0 or infinity \- infinity or sqrt(\-1).
  82 .SS "Exception handling"
  83 Exceptions are represented in two ways: as a single bit
  84 (exception present/absent), and these bits correspond in some
  85 implementation-defined way with bit positions in an integer,
  86 and also as an opaque structure that may contain more information
  87 about the exception (perhaps the code address where it occurred).
  88 .LP
  89 Each of the macros
  90 .BR FE_DIVBYZERO ,
  91 .BR FE_INEXACT ,
  92 .BR FE_INVALID ,
  93 .BR FE_OVERFLOW ,
  94 .B FE_UNDERFLOW
  95 is defined when the implementation supports handling
  96 of the corresponding exception, and if so then
  97 defines the corresponding bit(s), so that one can call
  98 exception handling functions, for example, using the integer argument
  99 .BR FE_OVERFLOW | FE_UNDERFLOW .
 100 Other exceptions may be supported.
 101 The macro
 102 .B FE_ALL_EXCEPT
 103 is the bitwise OR of all bits corresponding to supported exceptions.
 104 .PP
 105 The
 106 .BR feclearexcept ()
 107 function clears the supported exceptions represented by the bits
 108 in its argument.
 109 .LP
 110 The
 111 .BR fegetexceptflag ()
 112 function stores a representation of the state of the exception flags
 113 represented by the argument
 114 .I excepts
 115 in the opaque object
 116 .RI * flagp .
 117 .LP
 118 The
 119 .BR feraiseexcept ()
 120 function raises the supported exceptions represented by the bits in
 121 .IR excepts .
 122 .LP
 123 The
 124 .BR fesetexceptflag ()
 125 function sets the complete status for the exceptions represented by
 126 .I excepts
 127 to the value
 128 .RI * flagp .
 129 This value must have been obtained by an earlier call of
 130 .BR fegetexceptflag ()
 131 with a last argument that contained all bits in
 132 .IR excepts .
 133 .LP
 134 The
 135 .BR fetestexcept ()
 136 function returns a word in which the bits are set that were
 137 set in the argument
 138 .I excepts
 139 and for which the corresponding exception is currently set.
 140 .SS Rounding
 141 Each of the macros
 142 .BR FE_DOWNWARD ,
 143 .BR FE_TONEAREST ,
 144 .BR FE_TOWARDZERO ,
 145 .B FE_UPWARD
 146 is defined when the implementation supports getting and setting
 147 the corresponding rounding direction.
 148 .LP
 149 The
 150 .BR fegetround ()
 151 function returns the macro corresponding to the current
 152 rounding mode.
 153 .LP
 154 The
 155 .BR fesetround ()
 156 function sets the rounding mode as specified by its argument
 157 and returns zero when it was successful.
 158 .SS "Floating point environment"
 159 The entire floating point environment, including
 160 control modes and status flags, can be handled
 161 as one opaque object, of type
 162 .IR fenv_t .
 163 The default environment is denoted by
 164 .B FE_DFL_ENV
 165 (of type
 166 .IR "const fenv_t *" ).
 167 This is the environment setup at program start and it is defined by
 168 ISO C to have round to nearest, all exceptions cleared and a non-stop
 169 (continue on exceptions) mode.
 170 .LP
 171 The
 172 .BR fegetenv ()
 173 function saves the current floating point environment in the object
 174 .RI * envp .
 175 .LP
 176 The
 177 .BR feholdexcept ()
 178 function does the same, then clears all exception flags,
 179 and sets a non-stop (continue on exceptions) mode,
 180 if available.
 181 It returns zero when successful.
 182 .LP
 183 The
 184 .BR fesetenv ()
 185 function restores the floating point environment from
 186 the object
 187 .RI * envp .
 188 This object must be known to be valid, for example, the result of a call to
 189 .BR fegetenv ()
 190 or
 191 .BR feholdexcept ()
 192 or equal to
 193 .BR FE_DFL_ENV .
 194 This call does not raise exceptions.
 195 .LP
 196 The
 197 .BR feupdateenv ()
 198 function installs the floating-point environment represented by
 199 the object
 200 .RI * envp ,
 201 except that currently raised exceptions are not cleared.
 202 After calling this function, the raised exceptions will be a bitwise OR
 203 of those previously set with those in
 204 .RI * envp .
 205 As before, the object
 206 .RI * envp
 207 must be known to be valid.
 208 .SH "RETURN VALUE"
 209 These functions return zero on success and non-zero if an error occurred.
 210 .\" Earlier seven of these functions were listed as returning void.
 211 .\" This was corrected in Corrigendum 1 (ISO/IEC 9899:1999/Cor.1:2001(E))
 212 .\" of the C99 Standard.
 213 .SH "CONFORMING TO"
 214 IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99.
 215 .SH NOTES
 216 .SS Glibc Notes
 217 If possible, the GNU C Library defines a macro
 218 .B FE_NOMASK_ENV
 219 which represents an environment where every exception raised causes a
 220 trap to occur.
 221 You can test for this macro using
 222 .BR #ifdef .
 223 It is only defined if
 224 .B _GNU_SOURCE
 225 is defined.
 226 The C99 standard does not define a way to set individual bits in the
 227 floating point mask, for example, to trap on specific flags.
 228 glibc 2.2 supports the functions
 229 .BR feenableexcept ()
 230 and
 231 .BR fedisableexcept ()
 232 to set individual floating point traps, and
 233 .BR fegetexcept ()
 234 to query the state.
 235 .sp
 236 .nf
 237 .B "#define _GNU_SOURCE"
 238 .br
 239 .B "#include <fenv.h>"
 240 .sp
 241 .BI "int feenableexcept(int " excepts );
 242 .br
 243 .BI "int fedisableexcept(int " excepts );
 244 .br
 245 .B "int fegetexcept(void);"
 246 .br
 247 .fi
 248 .LP
 249 The
 250 .BR feenableexcept ()
 251 and
 252 .BR fedisableexcept ()
 253 functions enable (disable) traps for each of the exceptions represented by
 254 .I excepts
 255 and return the previous set of enabled exceptions when successful,
 256 and \-1 otherwise.
 257 The
 258 .BR fegetexcept ()
 259 function returns the set of all currently enabled exceptions.
 260 .SH "SEE ALSO"
 261 .BR feature_test_macros (7)