1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH fex_set_handling 3M "12 Jul 2006" "SunOS 5.11" "Mathematical Library Functions"
7 .SH NAME
8 fex_set_handling, fex_get_handling, fex_getexcepthandler, fex_setexcepthandler
9 \- control floating point exception handling modes
10 .SH SYNOPSIS
11 .LP
12 .nf
13 c99 [ \fIflag\fR... ] \fIfile\fR... -lm [ \fIlibrary\fR... ]
14 #include <fenv.h>
15
16 \fBint\fR \fBfex_set_handling\fR(\fBint\fR \fIex\fR, \fBint\fR \fImode\fR, \fBvoid(*\fR\fIhandler\fR);
17 .fi
18
19 .LP
20 .nf
21 \fBint\fR \fBfex_get_handling\fR(\fBint\fR \fIex\fR);
22 .fi
23
24 .LP
25 .nf
26 \fBvoid\fR \fBfex_getexcepthandler\fR(\fBfex_handler_t *\fR\fIbuf\fR, \fBint\fR \fIex\fR);
27 .fi
28
29 .LP
30 .nf
31 \fBvoid\fR \fBfex_setexcepthandler\fR(\fBconst fex_handler_t *\fR\fIbuf\fR, \fBint\fR \fIex\fR);
32 .fi
33
34 .SH DESCRIPTION
35 .sp
36 .LP
37 These functions provide control of floating point exception handling modes. For
38 each function, the \fIex\fR argument specifies one or more exceptions indicated
39 by a bitwise-OR of any of the following values defined in <\fBfenv.h\fR>:
40 .sp
41 .ne 2
42 .mk
43 .na
44 \fB\fBFEX_INEXACT\fR\fR
45 .ad
46 .RS 17n
47 .rt
48
49 .RE
50
51 .sp
52 .ne 2
53 .mk
54 .na
55 \fB\fBFEX_UNDERFLOW\fR\fR
56 .ad
57 .RS 17n
58 .rt
59
60 .RE
61
62 .sp
63 .ne 2
64 .mk
65 .na
66 \fB\fBFEX_OVERFLOW\fR\fR
67 .ad
68 .RS 17n
69 .rt
70
71 .RE
72
73 .sp
74 .ne 2
75 .mk
76 .na
77 \fB\fBFEX_DIVBYZERO\fR\fR
78 .ad
79 .RS 17n
80 .rt
81 division by zero
82 .RE
83
84 .sp
85 .ne 2
86 .mk
87 .na
88 \fB\fBFEX_INV_ZDZ\fR\fR
89 .ad
90 .RS 17n
91 .rt
92 0/0 invalid operation
93 .RE
94
95 .sp
96 .ne 2
97 .mk
98 .na
99 \fB\fBFEX_INV_IDI\fR\fR
100 .ad
101 .RS 17n
102 .rt
103 infinity/infinity invalid operation
104 .RE
105
106 .sp
107 .ne 2
108 .mk
109 .na
110 \fB\fBFEX_INV_ISI\fR\fR
111 .ad
112 .RS 17n
113 .rt
114 infinity-infinity invalid operation
115 .RE
116
117 .sp
118 .ne 2
119 .mk
120 .na
121 \fB\fBFEX_INV_ZMI\fR\fR
122 .ad
123 .RS 17n
124 .rt
125 0*infinity invalid operation
126 .RE
127
128 .sp
129 .ne 2
130 .mk
131 .na
132 \fB\fBFEX_INV_SQRT\fR\fR
133 .ad
134 .RS 17n
135 .rt
136 square root of negative operand
137 .RE
138
139 .sp
140 .ne 2
141 .mk
142 .na
143 \fB\fBFEX_INV_SNAN\fR\fR
144 .ad
145 .RS 17n
146 .rt
147 signaling NaN
148 .RE
149
150 .sp
151 .ne 2
152 .mk
153 .na
154 \fB\fBFEX_INV_INT\fR\fR
155 .ad
156 .RS 17n
157 .rt
158 invalid integer conversion
159 .RE
160
161 .sp
162 .ne 2
163 .mk
164 .na
165 \fB\fBFEX_INV_CMP\fR\fR
166 .ad
167 .RS 17n
168 .rt
169 invalid comparison
170 .RE
171
172 .sp
173 .LP
174 For convenience, the following combinations of values are also defined:
175 .sp
176 .ne 2
177 .mk
178 .na
179 \fB\fBFEX_NONE\fR\fR
180 .ad
181 .RS 15n
182 .rt
183 no exceptions
184 .RE
185
186 .sp
187 .ne 2
188 .mk
189 .na
190 \fB\fBFEX_INVALID\fR\fR
191 .ad
192 .RS 15n
193 .rt
194 all invalid operation exceptions
195 .RE
196
197 .sp
198 .ne 2
199 .mk
200 .na
201 \fB\fBFEX_COMMON\fR\fR
202 .ad
203 .RS 15n
204 .rt
205 overflow, division by zero, and invalid operation
206 .RE
207
208 .sp
209 .ne 2
210 .mk
211 .na
212 \fB\fBFEX_ALL\fR\fR
213 .ad
214 .RS 15n
215 .rt
216 all exceptions
217 .RE
218
219 .sp
220 .LP
221 The \fBfex_set_handling()\fR function establishes the specified \fImode\fR for
222 handling the floating point exceptions identified by \fIex\fR. The selected
223 \fImode\fR determines the action to be taken when one of the indicated
224 exceptions occurs. It must be one of the following values:
225 .sp
226 .ne 2
227 .mk
228 .na
229 \fB\fBFEX_NOHANDLER\fR\fR
230 .ad
231 .RS 17n
232 .rt
233 Trap but do not otherwise handle the exception, evoking instead whatever
234 ambient behavior would normally be in effect. This is the default behavior
235 when the exception's trap is enabled. The \fIhandler\fR parameter is ignored.
236 .RE
237
238 .sp
239 .ne 2
240 .mk
241 .na
242 \fB\fBFEX_NONSTOP\fR\fR
243 .ad
244 .RS 17n
245 .rt
246 Provide the IEEE 754 default result for the operation that caused the
247 exception, set the exception's flag, and continue execution. This is the
248 default behavior when the exception's trap is disabled. The \fIhandler\fR
249 parameter is ignored.
250 .RE
251
252 .sp
253 .ne 2
254 .mk
255 .na
256 \fB\fBFEX_ABORT\fR\fR
257 .ad
258 .RS 17n
259 .rt
260 Call \fBabort\fR(3C). The \fIhandler\fR parameter is ignored.
261 .RE
262
263 .sp
264 .ne 2
265 .mk
266 .na
267 \fB\fBFEX_SIGNAL\fR\fR
268 .ad
269 .RS 17n
270 .rt
271 Invoke the function *\fIhandler\fR with the parameters normally supplied to a
272 signal handler installed with \fBsigfpe\fR(3C).
273 .RE
274
275 .sp
276 .ne 2
277 .mk
278 .na
279 \fB\fBFEX_CUSTOM\fR\fR
280 .ad
281 .RS 17n
282 .rt
283 Invoke the function *\fIhandler\fR as described in the next paragraph.
284 .RE
285
286 .sp
287 .LP
288 In \fBFEX_CUSTOM\fR mode, when a floating point exception occurs, the handler
289 function is invoked as though its prototype were:
290 .sp
291 .in +2
292 .nf
293 #include <fenv.h>
294 void handler(int ex, fex_info_t *info);
295 .fi
296 .in -2
297
298 .sp
299 .LP
300 On entry, \fIex\fR is the value (of the first twelve listed above)
301 corresponding to the exception that occurred, \fBinfo->op\fR indicates the
302 operation that caused the exception, \fBinfo->op1\fR and \fBinfo->op2\fR
303 contain the values of the operands, \fBinfo->res\fR contains the default
304 untrapped result value, and \fBinfo->flags\fR reflects the exception flags that
305 the operation would have set had it not been trapped. If the handler returns,
306 the value contained in \fBinfo->res\fR on exit is substituted for the result of
307 the operation, the flags indicated by \fBinfo->flags\fR are set, and execution
308 resumes at the point where the exception occurred. The handler might modify
309 \fBinfo->res\fR and \fBinfo->flags\fR to supply any desired result value and
310 flags. Alternatively, if the exception is underflow or overflow, the hander
311 might set
312 .sp
313 .LP
314 info->res.type = fex_nodata;
315 .sp
316 .LP
317 which causes the exponent-adjusted result specified by IEEE 754 to be
318 substituted. If the handler does not modify \fBinfo->res\fR or
319 \fBinfo->flags\fR, the effect is the same as if the exception had not been
320 trapped.
321 .sp
322 .LP
323 Although the default untrapped result of an exceptional operation is always
324 available to a \fBFEX_CUSTOM\fR handler, in some cases, one or both operands
325 may not be. In these cases, the handler may be invoked with \fBinfo->op1.type
326 == fex_nodata\fR or \fBinfo->op2.type == fex_nodata\fR to indicate that the
327 respective data structures do not contain valid data. (For example,
328 \fBinfo->op2.type == fex_nodata\fR if the exceptional operation is a unary
329 operation.) Before accessing the operand values, a custom handler should
330 always examine the \fBtype\fR field of the operand data structures to ensure
331 that they contain valid data in the appropriate format.
332 .sp
333 .LP
334 The \fBfex_get_handling()\fR function returns the current handling mode for the
335 exception specified by \fIex\fR, which must be one of the first twelve
336 exceptions listed above.
337 .sp
338 .LP
339 The \fBfex_getexcepthandler()\fR function saves the current handling modes and
340 associated data for the exceptions specified by \fIex\fR in the data structure
341 pointed to by \fIbuf\fR. The type \fBfex_handler_t\fR is defined in
342 <\fBfenv.h\fR>.
343 .sp
344 .LP
345 The \fBfex_setexcepthandler()\fR function restores the handling modes and
346 associated data for the exceptions specified by \fIex\fR from the data
347 structure pointed to by \fIbuf\fR. This data structure must have been set by a
348 previous call to \fBfex_getexcepthandler()\fR. Otherwise the effect on the
349 indicated modes is undefined.
350 .SH RETURN VALUES
351 .sp
352 .LP
353 The \fBfex_set_handling()\fR function returns a non-zero value if the requested
354 exception handling mode is established. Otherwise, it returns 0.
355 .SH EXAMPLES
356 .sp
357 .LP
358 The following example demonstrates how to substitute a predetermined value for
359 the result of a 0/0 invalid operation.
360 .sp
361 .in +2
362 .nf
363 #include <math.h>
364 #include <fenv.h>
365
366 double k;
367
368 void presub(int ex, fex_info_t *info) {
369 info->res.type = fex_double;
370 info->res.val.d = k;
371 }
372
373 int main() {
374 double x, w;
375 int i;
376 fex_handler_t buf;
377 /*
378 * save current 0/0 handler
379 */
380 (void) fex_getexcepthandler(&buf, FEX_INV_ZDZ);
381 /*
382 * set up presubstitution handler for 0/0
383 */
384 (void) fex_set_handling(FEX_INV_ZDZ, FEX_CUSTOM, presub);
385 /*
386 * compute (k*x)/sin(x) for k=2.0, x=0.5, 0.4, ..., 0.1, 0.0
387 */
388 k = 2.0;
389 (void) printf("Evaluating f(x) = (k*x)/sin(x)\en\en");
390 for (i = 5; i >= 0; i--) {
391 x = (double) i * 0.1;
392 w = (k * x) / sin(x);
393 (void) printf("\etx=%3.3f\et f(x) = % 1.20e\en", x, w);
394 }
395 /*
396 * restore old 0/0 handler
397 */
398 (void) fex_setexcepthandler(&buf, FEX_INV_ZDZ);
399 return 0;
400 }
401 .fi
402 .in -2
403
404 .sp
405 .LP
406 The output from the preceding program reads:
407 .sp
408 .in +2
409 .nf
410 Evaluating f(x) = (k*x)/sin(x)
411
412 x=0.500 f(x) = 2.08582964293348816000e+00
413 x=0.400 f(x) = 2.05434596443822626000e+00
414 x=0.300 f(x) = 2.03031801709447368000e+00
415 x=0.200 f(x) = 2.01339581906893761000e+00
416 x=0.100 f(x) = 2.00333722632695554000e+00
417 x=0.000 f(x) = 2.00000000000000000000e+00
418 .fi
419 .in -2
420
421 .sp
422 .LP
423 When \fIx\fR = 0, \fIf(x)\fR is computed as 0/0 and an invalid operation
424 exception occurs. In this example, the value 2.0 is substituted for the
425 result.
426 .SH ATTRIBUTES
427 .sp
428 .LP
429 See \fBattributes\fR(5) for descriptions of the following attributes:
430 .sp
431
432 .sp
433 .TS
434 tab() box;
435 lw(2.75i) lw(2.75i)
436 lw(2.75i) lw(2.75i)
437 .
438 ATTRIBUTE TYPEATTRIBUTE VALUE
439 AvailabilitySUNWlibms, SUNWlmxs
440 Interface StabilityStable
441 MT-LevelMT-Safe (see Notes)
442 .TE
443
444 .SH SEE ALSO
445 .sp
446 .LP
447 \fBsigfpe\fR(3C), \fBfeclearexcept\fR(3M), \fBfegetenv\fR(3M),
448 \fBfex_set_log\fR(3M), \fBattributes\fR(5)
449 .sp
450 .LP
451 \fINumerical Computation Guide\fR
452 .SH NOTES
453 .sp
454 .LP
455 In a multithreaded application, the preceding functions affect exception
456 handling modes only for the calling thread.
457 .sp
458 .LP
459 The functions described on this page automatically install and deinstall
460 \fBSIGFPE\fR handlers and set and clear the trap enable mode bits in the
461 floating point status register as needed. If a program uses these functions
462 and attempts to install a \fBSIGFPE\fR handler or control the trap enable mode
463 bits independently, the resulting behavior is not defined.
464 .sp
465 .LP
466 All traps are disabled before a handler installed in \fBFEX_CUSTOM\fR mode is
467 invoked. When the \fBSIGFPE\fR signal is blocked, as it is when such a handler
468 is invoked, the floating point environment, exception flags, and retrospective
469 diagnostic functions described in \fBfeclearexcept\fR(3M), \fBfegetenv\fR(3M),
470 and \fBfex_set_log\fR(3M) do not re-enable traps. Thus, the handler itself
471 always runs in \fBFEX_NONSTOP\fR mode with logging of retrospective diagnostics
472 disabled. Attempting to change these modes within the handler may not produce
473 the expected results.