1<fenv.h>(P) POSIX Programmer's Manual <fenv.h>(P)
2
6 fenv.h - floating-point environment
7
9 #include <fenv.h>
10
12 The <fenv.h> header shall define the following data types through type‐
13 def:
14 fenv_t Represents the entire floating-point environment. The floating-
16 point environment refers collectively to any floating-point sta‐
17 tus flags and control modes supported by the implementation.
18 fexcept_t
20 Represents the floating-point status flags collectively, includ‐
21 ing any status the implementation associates with the flags. A
22 floating-point status flag is a system variable whose value is
23 set (but never cleared) when a floating-point exception is
24 raised, which occurs as a side effect of exceptional floating-
25 point arithmetic to provide auxiliary information. A floating-
26 point control mode is a system variable whose value may be set
27 by the user to affect the subsequent behavior of floating-point
28 arithmetic.
29 The <fenv.h> header shall define the following constants if and only if
32 the implementation supports the floating-point exception by means of
33 the floating-point functions feclearexcept(), fegetexceptflag(),
34 feraiseexcept(), fesetexceptflag(), and fetestexcept(). Each expands to
35 an integer constant expression with values such that bitwise-inclusive
36 ORs of all combinations of the constants result in distinct values.
37 FE_DIVBYZERO
40 FE_INEXACT
41 FE_INVALID
42 FE_OVERFLOW
43 FE_UNDERFLOW
44 The <fenv.h> header shall define the following constant, which is sim‐
46 ply the bitwise-inclusive OR of all floating-point exception constants
47 defined above:
48 FE_ALL_EXCEPT
51 The <fenv.h> header shall define the following constants if and only if
53 the implementation supports getting and setting the represented round‐
54 ing direction by means of the fegetround() and fesetround() functions.
55 Each expands to an integer constant expression whose values are dis‐
56 tinct non-negative vales.
57 FE_DOWNWARD
60 FE_TONEAREST
61 FE_TOWARDZERO
62 FE_UPWARD
63 The <fenv.h> header shall define the following constant, which repre‐
65 sents the default floating-point environment (that is, the one
66 installed at program startup) and has type pointer to const-qualified
67 fenv_t. It can be used as an argument to the functions within the
68 <fenv.h> header that manage the floating-point environment.
69 FE_DFL_ENV
72 The following shall be declared as functions and may also be defined as
74 macros. Function prototypes shall be provided.
75 int feclearexcept(int);
78 int fegetexceptflag(fexcept_t *, int);
79 int feraiseexcept(int);
80 int fesetexceptflag(const fexcept_t *, int);
81 int fetestexcept(int);
82 int fegetround(void);
83 int fesetround(int);
84 int fegetenv(fenv_t *);
85 int feholdexcept(fenv_t *);
86 int fesetenv(const fenv_t *);
87 int feupdateenv(const fenv_t *);
88 The FENV_ACCESS pragma provides a means to inform the implementation
90 when an application might access the floating-point environment to test
91 floating-point status flags or run under non-default floating-point
92 control modes. The pragma shall occur either outside external declara‐
93 tions or preceding all explicit declarations and statements inside a
94 compound statement. When outside external declarations, the pragma
95 takes effect from its occurrence until another FENV_ACCESS pragma is
96 encountered, or until the end of the translation unit. When inside a
97 compound statement, the pragma takes effect from its occurrence until
98 another FENV_ACCESS pragma is encountered (including within a nested
99 compound statement), or until the end of the compound statement; at the
100 end of a compound statement the state for the pragma is restored to its
101 condition just before the compound statement. If this pragma is used in
102 any other context, the behavior is undefined. If part of an application
103 tests floating-point status flags, sets floating-point control modes,
104 or runs under non-default mode settings, but was translated with the
105 state for the FENV_ACCESS pragma off, the behavior is undefined. The
106 default state (on or off) for the pragma is implementation-defined.
107 (When execution passes from a part of the application translated with
108 FENV_ACCESS off to a part translated with FENV_ACCESS on, the state of
109 the floating-point status flags is unspecified and the floating-point
110 control modes have their default settings.)
111 The following sections are informative.
113
115 This header is designed to support the floating-point exception status
116 flags and directed-rounding control modes required by the
117 IEC 60559:1989 standard, and other similar floating-point state infor‐
118 mation. Also it is designed to facilitate code portability among all
119 systems.
120 Certain application programming conventions support the intended model
122 of use for the floating-point environment:
123 * A function call does not alter its caller's floating-point control
125 modes, clear its caller's floating-point status flags, nor depend on
126 the state of its caller's floating-point status flags unless the
127 function is so documented.
128 * A function call is assumed to require default floating-point control
130 modes, unless its documentation promises otherwise.
131 * A function call is assumed to have the potential for raising float‐
133 ing-point exceptions, unless its documentation promises otherwise.
134 With these conventions, an application can safely assume default float‐
136 ing-point control modes (or be unaware of them). The responsibilities
137 associated with accessing the floating-point environment fall on the
138 application that does so explicitly.
139 Even though the rounding direction macros may expand to constants cor‐
141 responding to the values of FLT_ROUNDS, they are not required to do so.
142 For example:
144 #include <fenv.h>
147 void f(double x)
148 {
149 #pragma STDC FENV_ACCESS ON
150 void g(double);
151 void h(double);
152 /* ... */
153 g(x + 1);
154 h(x + 1);
155 /* ... */
156 }
157 If the function g() might depend on status flags set as a side effect
159 of the first x+1, or if the second x+1 might depend on control modes
160 set as a side effect of the call to function g(), then the application
161 shall contain an appropriately placed invocation as follows:
162 #pragma STDC FENV_ACCESS ON
165
167 The fexcept_t Type
168 fexcept_t does not have to be an integer type. Its values must be
169 obtained by a call to fegetexceptflag(), and cannot be created by logi‐
170 cal operations from the exception macros. An implementation might sim‐
171 ply implement fexcept_t as an int and use the representations reflected
172 by the exception macros, but is not required to; other representations
173 might contain extra information about the exceptions. fexcept_t might
174 be a struct with a member for each exception (that might hold the
175 address of the first or last floating-point instruction that caused
176 that exception). The ISO/IEC 9899:1999 standard makes no claims about
177 the internals of an fexcept_t, and so the user cannot inspect it.
178 Exception and Rounding Macros
180 Macros corresponding to unsupported modes and rounding directions are
181 not defined by the implementation and must not be defined by the appli‐
182 cation. An application might use #ifdef to test for this.
183
185 None.
186
188 The System Interfaces volume of IEEE Std 1003.1-2001, feclearexcept(),
189 fegetenv(), fegetexceptflag(), fegetround(), feholdexcept(), feraiseex‐
190 cept(), fesetenv(), fesetexceptflag(), fesetround(), fetestexcept(),
191 feupdateenv()
192
194 Portions of this text are reprinted and reproduced in electronic form
195 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
196 -- Portable Operating System Interface (POSIX), The Open Group Base
197 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
198 Electrical and Electronics Engineers, Inc and The Open Group. In the
199 event of any discrepancy between this version and the original IEEE and
200 The Open Group Standard, the original IEEE and The Open Group Standard
201 is the referee document. The original Standard can be obtained online
202 at http://www.opengroup.org/unix/online.html .
203IEEE/The Open Group 2003 <fenv.h>(P)