1fex_set_handling(3M) Mathematical Library Functions fex_set_handling(3M)
2
6 fex_set_handling, fex_get_handling, fex_getexcepthandler, fex_setex‐
7 cepthandler - control floating point exception handling modes
8
10 c99 [ flag... ] file... -lm [ library... ]
11 #include <fenv.h>
12 int fex_set_handling(int ex, int mode, void(*handler);
14 int fex_get_handling(int ex);
17 void fex_getexcepthandler(fex_handler_t *buf, int ex);
20 void fex_setexcepthandler(const fex_handler_t *buf, int ex);
23
26 These functions provide control of floating point exception handling
27 modes. For each function, the ex argument specifies one or more excep‐
28 tions indicated by a bitwise-OR of any of the following values defined
29 in <fenv.h>:
30 FEX_INEXACT
32 FEX_UNDERFLOW
35 FEX_OVERFLOW
38 FEX_DIVBYZERO division by zero
41 FEX_INV_ZDZ 0/0 invalid operation
44 FEX_INV_IDI infinity/infinity invalid operation
47 FEX_INV_ISI infinity-infinity invalid operation
50 FEX_INV_ZMI 0*infinity invalid operation
53 FEX_INV_SQRT square root of negative operand
56 FEX_INV_SNAN signaling NaN
59 FEX_INV_INT invalid integer conversion
62 FEX_INV_CMP invalid comparison
65 For convenience, the following combinations of values are also defined:
69 FEX_NONE no exceptions
71 FEX_INVALID all invalid operation exceptions
74 FEX_COMMON overflow, division by zero, and invalid operation
77 FEX_ALL all exceptions
80 The fex_set_handling() function establishes the specified mode for han‐
84 dling the floating point exceptions identified by ex. The selected
85 mode determines the action to be taken when one of the indicated excep‐
86 tions occurs. It must be one of the following values:
87 FEX_NOHANDLER Trap but do not otherwise handle the exception, evok‐
89 ing instead whatever ambient behavior would normally
90 be in effect. This is the default behavior when the
91 exception's trap is enabled. The handler parameter is
92 ignored.
93 FEX_NONSTOP Provide the IEEE 754 default result for the operation
96 that caused the exception, set the exception's flag,
97 and continue execution. This is the default behavior
98 when the exception's trap is disabled. The handler
99 parameter is ignored.
100 FEX_ABORT Call abort(3C). The handler parameter is ignored.
103 FEX_SIGNAL Invoke the function *handler with the parameters nor‐
106 mally supplied to a signal handler installed with
107 sigfpe(3C).
108 FEX_CUSTOM Invoke the function *handler as described in the next
111 paragraph.
112 In FEX_CUSTOM mode, when a floating point exception occurs, the handler
116 function is invoked as though its prototype were:
117 #include <fenv.h>
119 void handler(int ex, fex_info_t *info);
120 On entry, ex is the value (of the first twelve listed above) corre‐
124 sponding to the exception that occurred, info->op indicates the opera‐
125 tion that caused the exception, info->op1 and info->op2 contain the
126 values of the operands, info->res contains the default untrapped result
127 value, and info->flags reflects the exception flags that the operation
128 would have set had it not been trapped. If the handler returns, the
129 value contained in info->res on exit is substituted for the result of
130 the operation, the flags indicated by info->flags are set, and execu‐
131 tion resumes at the point where the exception occurred. The handler
132 might modify info->res and info->flags to supply any desired result
133 value and flags. Alternatively, if the exception is underflow or over‐
134 flow, the hander might set
135 info->res.type = fex_nodata;
138 which causes the exponent-adjusted result specified by IEEE 754 to be
141 substituted. If the handler does not modify info->res or info->flags,
142 the effect is the same as if the exception had not been trapped.
143 Although the default untrapped result of an exceptional operation is
146 always available to a FEX_CUSTOM handler, in some cases, one or both
147 operands may not be. In these cases, the handler may be invoked with
148 info->op1.type == fex_nodata or info->op2.type == fex_nodata to indi‐
149 cate that the respective data structures do not contain valid data.
150 (For example, info->op2.type == fex_nodata if the exceptional operation
151 is a unary operation.) Before accessing the operand values, a custom
152 handler should always examine the type field of the operand data struc‐
153 tures to ensure that they contain valid data in the appropriate format.
154 The fex_get_handling() function returns the current handling mode for
157 the exception specified by ex, which must be one of the first twelve
158 exceptions listed above.
159 The fex_getexcepthandler() function saves the current handling modes
162 and associated data for the exceptions specified by ex in the data
163 structure pointed to by buf. The type fex_handler_t is defined in
164 <fenv.h>.
165 The fex_setexcepthandler() function restores the handling modes and
168 associated data for the exceptions specified by ex from the data struc‐
169 ture pointed to by buf. This data structure must have been set by a
170 previous call to fex_getexcepthandler(). Otherwise the effect on the
171 indicated modes is undefined.
172
174 The fex_set_handling() function returns a non-zero value if the
175 requested exception handling mode is established. Otherwise, it returns
176 0.
177
179 The following example demonstrates how to substitute a predetermined
180 value for the result of a 0/0 invalid operation.
181 #include <math.h>
183 #include <fenv.h>
184 double k;
186 void presub(int ex, fex_info_t *info) {
188 info->res.type = fex_double;
189 info->res.val.d = k;
190 }
191 int main() {
193 double x, w;
194 int i;
195 fex_handler_t buf;
196 /*
197 * save current 0/0 handler
198 */
199 (void) fex_getexcepthandler(&buf, FEX_INV_ZDZ);
200 /*
201 * set up presubstitution handler for 0/0
202 */
203 (void) fex_set_handling(FEX_INV_ZDZ, FEX_CUSTOM, presub);
204 /*
205 * compute (k*x)/sin(x) for k=2.0, x=0.5, 0.4, ..., 0.1, 0.0
206 */
207 k = 2.0;
208 (void) printf("Evaluating f(x) = (k*x)/sin(x)\n\n");
209 for (i = 5; i >= 0; i--) {
210 x = (double) i * 0.1;
211 w = (k * x) / sin(x);
212 (void) printf("\tx=%3.3f\t f(x) = % 1.20e\n", x, w);
213 }
214 /*
215 * restore old 0/0 handler
216 */
217 (void) fex_setexcepthandler(&buf, FEX_INV_ZDZ);
218 return 0;
219 }
220 The output from the preceding program reads:
224 Evaluating f(x) = (k*x)/sin(x)
226 x=0.500 f(x) = 2.08582964293348816000e+00
228 x=0.400 f(x) = 2.05434596443822626000e+00
229 x=0.300 f(x) = 2.03031801709447368000e+00
230 x=0.200 f(x) = 2.01339581906893761000e+00
231 x=0.100 f(x) = 2.00333722632695554000e+00
232 x=0.000 f(x) = 2.00000000000000000000e+00
233 When x = 0, f(x) is computed as 0/0 and an invalid operation exception
237 occurs. In this example, the value 2.0 is substituted for the result.
238
240 See attributes(5) for descriptions of the following attributes:
241 ┌───────────────────────────────────────────────────────────┐
246 │ATTRIBUTE TYPE ATTRIBUTE VALUE │
247 │Availability SUNWlibms, SUNWlmxs │
248 │Interface Stability Stable │
249 │MT-Level MT-Safe (see Notes) │
250 └───────────────────────────────────────────────────────────┘
251
253 sigfpe(3C), feclearexcept(3M), fegetenv(3M), fex_set_log(3M),
254 attributes(5)
255 Numerical Computation Guide
258
260 In a multithreaded application, the preceding functions affect excep‐
261 tion handling modes only for the calling thread.
262 The functions described on this page automatically install and dein‐
265 stall SIGFPE handlers and set and clear the trap enable mode bits in
266 the floating point status register as needed. If a program uses these
267 functions and attempts to install a SIGFPE handler or control the trap
268 enable mode bits independently, the resulting behavior is not defined.
269 All traps are disabled before a handler installed in FEX_CUSTOM mode is
272 invoked. When the SIGFPE signal is blocked, as it is when such a han‐
273 dler is invoked, the floating point environment, exception flags, and
274 retrospective diagnostic functions described in feclearexcept(3M),
275 fegetenv(3M), and fex_set_log(3M) do not re-enable traps. Thus, the
276 handler itself always runs in FEX_NONSTOP mode with logging of retro‐
277 spective diagnostics disabled. Attempting to change these modes within
278 the handler may not produce the expected results.
279SunOS 5.11 12 Jul 2006 fex_set_handling(3M)