fenv.h(3head)

1fenv.h(3HEAD)                       Headers                      fenv.h(3HEAD)
2
3
4

NAME

6       fenv.h, fenv - floating-point environment
7

SYNOPSIS

9       #include <fenv.h>
10
11

DESCRIPTION

13       The <fenv.h> header defines the following data types through typedef:
14
15       fenv_t       Represents  the  entire  floating-point  environment.  The
16                    floating-point  environment  refers  collectively  to  any
17                    floating-point status flags and control modes supported by
18                    the implementation.
19
20
21       fexcept_t    Represents the floating-point status  flags  collectively,
22                    including  any  status  the implementation associates with
23                    the flags. A floating-point status flag is a system  vari‐
24                    able  whose value is set (but never cleared) when a float‐
25                    ing-point exception is raised,  which  occurs  as  a  side
26                    effect of exceptional floating-point arithmetic to provide
27                    auxiliary information. A floating-point control mode is  a
28                    system  variable  whose  value  can  be set by the user to
29                    affect the subsequent behavior  of  floating-point  arith‐
30                    metic.
31
32
33
34       The  <fenv.h> header defines the following constants if and only if the
35       implementation supports the floating-point exception by  means  of  the
36       floating-point functions feclearexcept(), fegetexceptflag(), feraiseex‐
37       cept(), fesetexceptflag(),  and  fetestexcept().  Each  expands  to  an
38       integer constant expression with values such that bitwise-inclusive ORs
39       of all combinations of the constants result in distinct values.
40
41         FE_DIVBYZERO
42         FE_INEXACT
43         FE_INVALID
44         FE_OVERFLOW
45         FE_UNDERFLOW
46
47
48
49       The <fenv.h> header defines the following constant, which is simply the
50       bitwise-inclusive  OR of all floating-point exception constants defined
51       above:
52
53         FE_ALL_EXCEPT
54
55
56
57       The <fenv.h> header defines the following constants. Each expands to an
58       integer constant expression whose values are distinct non-negative val‐
59       ues.
60
61         FE_DOWNWARD
62         FE_TONEAREST
63         FE_TOWARDZERO
64         FE_UPWARD
65
66
67
68       The <fenv.h> header defines the following  constant,  which  represents
69       the  default  floating-point environment (that is, the one installed at
70       program startup) and has type pointer to const-qualified fenv_t. It can
71       be used as an argument to the functions within the <fenv.h> header that
72       manage the floating-point environment.
73
74         FE_DFL_ENV
75
76
77
78       The FENV_ACCESS pragma provides a means to  inform  the  implementation
79       when an application might access the floating-point environment to test
80       floating-point status flags or  run  under  non-default  floating-point
81       control  modes.  The pragma occurs either outside external declarations
82       or preceding all explicit declarations and statements inside a compound
83       statement.  When outside external declarations, the pragma takes effect
84       from its occurrence until another FENV_ACCESS pragma is encountered, or
85       until  the  end  of the translation unit. When inside a compound state‐
86       ment, the  pragma  takes  effect  from  its  occurrence  until  another
87       FENV_ACCESS  pragma  is encountered (including within a nested compound
88       statement), or until the end of the compound statement; at the end of a
89       compound  statement  the state for the pragma is restored to its condi‐
90       tion just before the compound statement. If this pragma is used in  any
91       other context, the behavior is undefined.
92
93
94       If  part  of  an  application  tests  floating-point status flags, sets
95       floating-point control modes, or runs under non-default mode  settings,
96       but  was translated with the state for the FENV_ ACCESS pragma off, the
97       behavior is undefined. The default state (on or off) for the pragma  is
98       implementation-defined.  (When  execution  passes  from  a  part of the
99       application translated with FENV_ACCESS off to a part  translated  with
100       FENV_ACCESS on, the state of the floating-point status flags is unspec‐
101       ified and the floating-point control  modes  have  their  default  set‐
102       tings.)
103

USAGE

105       This  header is designed to support the floating-point exception status
106       flags and directed-rounding control modes required by  the  IEC  60559:
107       1989  standard,  and  other  similar  floating-point state information.
108       Also, it is designed to facilitate code portability among all  systems.
109       Certain  application programming conventions support the intended model
110       of use for the floating-point environment:
111
112           o      A function call does not alter its  caller's  floating-point
113                  control  modes,  clear  its  caller's  floating-point status
114                  flags, or depend on the state of its caller's floating-point
115                  status flags unless the function is so documented.
116
117           o      A function call is assumed to require default floating-point
118                  control modes, unless its documentation promises otherwise.
119
120           o      A function call is assumed to have the potential for raising
121                  floating-point exceptions, unless its documentation promises
122                  otherwise.
123
124
125       With these conventions, an application can safely assume default float‐
126       ing-point  control  modes (or be unaware of them). The responsibilities
127       associated with accessing the floating-point environment  fall  on  the
128       application that does so explicitly.
129
130
131       Even  though  the  rounding  direction macros might expand to constants
132       corresponding to the values of FLT_ROUNDS, they are not required to  do
133       so. For example:
134
135         #include <fenv.h>
136         void f(double x)
137         {
138             #pragma STDC FENV_ACCESS ON
139             void g(double);
140             void h(double);
141             /* ... */
142             g(x + 1);
143             h(x + 1);
144             /* ... */
145         }
146
147
148
149       If  the  function g() might depend on status flags set as a side effect
150       of the first x+1, or if the second x+1 might depend  on  control  modes
151       set  as a side effect of the call to function g(), then the application
152       must contain an appropriately placed invocation as follows:
153
154         #pragma STDC FENV_ACCESS ON
155
156

ATTRIBUTES

158       See attributes(5) for descriptions of the following attributes:
159
160
161
162
163       ┌─────────────────────────────┬─────────────────────────────┐
164       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
165       ├─────────────────────────────┼─────────────────────────────┤
166       │Interface Stability          │Standard                     │
167       └─────────────────────────────┴─────────────────────────────┘
168

NAME

SYNOPSIS

DESCRIPTION

USAGE

ATTRIBUTES

SEE ALSO