1FENV(3)                    Linux Programmer's Manual                   FENV(3)
2
3
4

NAME

6       feclearexcept,  fegetexceptflag, feraiseexcept, fesetexceptflag, fetes‐
7       texcept,  fegetenv,  fegetround,  feholdexcept,  fesetround,  fesetenv,
8       feupdateenv,  feenableexcept,  fedisableexcept, fegetexcept - floating-
9       point rounding and exception handling
10

SYNOPSIS

12       #include <fenv.h>
13
14       int feclearexcept(int excepts);
15       int fegetexceptflag(fexcept_t *flagp, int excepts);
16       int feraiseexcept(int excepts);
17       int fesetexceptflag(const fexcept_t *flagp, int excepts);
18       int fetestexcept(int excepts);
19
20       int fegetround(void);
21       int fesetround(int rounding_mode);
22
23       int fegetenv(fenv_t *envp);
24       int feholdexcept(fenv_t *envp);
25       int fesetenv(const fenv_t *envp);
26       int feupdateenv(const fenv_t *envp);
27
28       Link with -lm.
29

DESCRIPTION

31       These eleven functions were defined in C99, and describe  the  handling
32       of floating-point rounding and exceptions (overflow, zero-divide etc.).
33
34   Exceptions
35       The divide-by-zero exception occurs when an operation on finite numbers
36       produces infinity as exact answer.
37
38       The overflow exception occurs when a result has to be represented as  a
39       floating-point  number,  but  has (much) larger absolute value than the
40       largest (finite) floating-point number that is representable.
41
42       The underflow exception occurs when a result has to be represented as a
43       floating-point number, but has smaller absolute value than the smallest
44       positive normalized floating-point number (and would lose much accuracy
45       when represented as a denormalized number).
46
47       The inexact exception occurs when the rounded result of an operation is
48       not equal to the infinite precision  result.   It  may  occur  whenever
49       overflow or underflow occurs.
50
51       The  invalid  exception occurs when there is no well-defined result for
52       an operation, as for 0/0 or infinity - infinity or sqrt(-1).
53
54   Exception handling
55       Exceptions are represented in two ways:  as  a  single  bit  (exception
56       present/absent),  and  these  bits  correspond  in some implementation-
57       defined way with bit positions in an integer, and  also  as  an  opaque
58       structure  that  may contain more information about the exception (per‐
59       haps the code address where it occurred).
60
61       Each of the macros FE_DIVBYZERO, FE_INEXACT,  FE_INVALID,  FE_OVERFLOW,
62       FE_UNDERFLOW  is  defined  when the implementation supports handling of
63       the corresponding exception, and if so then defines  the  corresponding
64       bit(s), so that one can call exception handling functions, for example,
65       using the integer argument FE_OVERFLOW|FE_UNDERFLOW.  Other  exceptions
66       may  be  supported.   The  macro FE_ALL_EXCEPT is the bitwise OR of all
67       bits corresponding to supported exceptions.
68
69       The feclearexcept() function clears  the  supported  exceptions  repre‐
70       sented by the bits in its argument.
71
72       The  fegetexceptflag() function stores a representation of the state of
73       the exception flags represented by the argument excepts in  the  opaque
74       object *flagp.
75
76       The  feraiseexcept()  function  raises  the supported exceptions repre‐
77       sented by the bits in excepts.
78
79       The fesetexceptflag() function sets the complete status for the  excep‐
80       tions represented by excepts to the value *flagp.  This value must have
81       been obtained by an earlier call of fegetexceptflag() with a last argu‐
82       ment that contained all bits in excepts.
83
84       The  fetestexcept()  function  returns a word in which the bits are set
85       that were set in the argument excepts and for which  the  corresponding
86       exception is currently set.
87
88   Rounding mode
89       The  rounding  mode  determines how the result of floating-point opera‐
90       tions is treated when the result cannot be exactly represented  in  the
91       signifcand.   Various  rounding modes may be provided: round to nearest
92       (the  default),  round  up  (towards  positive  infinity),  round  down
93       (towards negative infinity), and round towards zero.
94
95       Each   of   the   macros   FE_TONEAREST,  FE_UPWARD,  FE_DOWNWARD,  and
96       FE_TOWARDZERO is defined when the implementation supports  getting  and
97       setting the corresponding rounding direction.
98
99       The  fegetround()  function returns the macro corresponding to the cur‐
100       rent rounding mode.
101
102       The fesetround() function sets the rounding mode as  specified  by  its
103       argument and returns zero when it was successful.
104
105       C99  and  POSIX.1-2008  specify  an  identifier, FLT_ROUNDS, defined in
106       <float.h>, which indicates the implementation-defined rounding behavior
107       for  floating-point addition.  This identifier has one of the following
108       values:
109
110       -1     The rounding mode is not determinable.
111
112       0      Rounding is towards 0.
113
114       1      Rounding is towards nearest number.
115
116       2      Rounding is towards positive infinity.
117
118       3      Rounding is towards negative infinity.
119
120       Other values represent machine-dependent, non-standard rounding modes.
121
122       The value of FLT_ROUNDS should reflect the current rounding mode as set
123       by fesetround() (but see BUGS).
124
125   Floating-point environment
126       The entire floating-point environment, including control modes and sta‐
127       tus flags, can be handled as one opaque object, of  type  fenv_t.   The
128       default  environment is denoted by FE_DFL_ENV (of type const fenv_t *).
129       This is the environment setup at program start and it is defined by ISO
130       C to have round to nearest, all exceptions cleared and a non-stop (con‐
131       tinue on exceptions) mode.
132
133       The fegetenv() function saves the current floating-point environment in
134       the object *envp.
135
136       The  feholdexcept()  function  does the same, then clears all exception
137       flags, and sets a non-stop (continue on exceptions) mode, if available.
138       It returns zero when successful.
139
140       The  fesetenv()  function  restores the floating-point environment from
141       the object *envp.  This object must be known to be valid, for  example,
142       the  result  of  a  call  to  fegetenv()  or feholdexcept() or equal to
143       FE_DFL_ENV.  This call does not raise exceptions.
144
145       The feupdateenv() function installs the floating-point environment rep‐
146       resented  by  the object *envp, except that currently raised exceptions
147       are not cleared.  After calling this function,  the  raised  exceptions
148       will  be  a bitwise OR of those previously set with those in *envp.  As
149       before, the object *envp must be known to be valid.
150

RETURN VALUE

152       These functions return  zero  on  success  and  non-zero  if  an  error
153       occurred.
154

VERSIONS

156       These functions first appeared in glibc in version 2.1.
157

CONFORMING TO

159       IEC 60559 (IEC 559:1989), ANSI/IEEE 854, C99, POSIX.1-2001.
160

NOTES

162   Glibc Notes
163       If possible, the GNU C Library defines a macro FE_NOMASK_ENV which rep‐
164       resents an environment where every exception raised causes  a  trap  to
165       occur.   You  can test for this macro using #ifdef.  It is only defined
166       if _GNU_SOURCE is defined.  The C99 standard does not define a  way  to
167       set individual bits in the floating-point mask, for example, to trap on
168       specific flags.  glibc 2.2 supports the functions feenableexcept()  and
169       fedisableexcept()  to set individual floating-point traps, and fegetex‐
170       cept() to query the state.
171
172       #define _GNU_SOURCE
173       #include <fenv.h>
174
175       int feenableexcept(int excepts);
176       int fedisableexcept(int excepts);
177       int fegetexcept(void);
178
179       The feenableexcept() and fedisableexcept() functions  enable  (disable)
180       traps  for each of the exceptions represented by excepts and return the
181       previous set of enabled exceptions when successful, and  -1  otherwise.
182       The  fegetexcept()  function  returns  the set of all currently enabled
183       exceptions.
184

BUGS

186       C99 specifies that the value of FLT_ROUNDS should  reflect  changes  to
187       the  current  rounding  mode,  as set by fesetround().  Currently, this
188       does not occur: FLT_ROUNDS always has the value 1.
189

SEE ALSO

191       feature_test_macros(7), math_error(7)
192

COLOPHON

194       This page is part of release 3.22 of the Linux  man-pages  project.   A
195       description  of  the project, and information about reporting bugs, can
196       be found at http://www.kernel.org/doc/man-pages/.
197
198
199
200Linux                             2008-08-11                           FENV(3)
Impressum