1fex_set_handling(3M)    Mathematical Library Functions    fex_set_handling(3M)
2
3
4

NAME

6       fex_set_handling,  fex_get_handling,  fex_getexcepthandler,  fex_setex‐
7       cepthandler - control floating point exception handling modes
8

SYNOPSIS

10       c99 [ flag... ] file... -lm [ library... ]
11       #include <fenv.h>
12
13       int fex_set_handling(int ex, int mode, void(*handler);
14
15
16       int fex_get_handling(int ex);
17
18
19       void fex_getexcepthandler(fex_handler_t *buf, int ex);
20
21
22       void fex_setexcepthandler(const fex_handler_t *buf, int ex);
23
24

DESCRIPTION

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
31       FEX_INEXACT
32
33
34       FEX_UNDERFLOW
35
36
37       FEX_OVERFLOW
38
39
40       FEX_DIVBYZERO    division by zero
41
42
43       FEX_INV_ZDZ      0/0 invalid operation
44
45
46       FEX_INV_IDI      infinity/infinity invalid operation
47
48
49       FEX_INV_ISI      infinity-infinity invalid operation
50
51
52       FEX_INV_ZMI      0*infinity invalid operation
53
54
55       FEX_INV_SQRT     square root of negative operand
56
57
58       FEX_INV_SNAN     signaling NaN
59
60
61       FEX_INV_INT      invalid integer conversion
62
63
64       FEX_INV_CMP      invalid comparison
65
66
67
68       For convenience, the following combinations of values are also defined:
69
70       FEX_NONE       no exceptions
71
72
73       FEX_INVALID    all invalid operation exceptions
74
75
76       FEX_COMMON     overflow, division by zero, and invalid operation
77
78
79       FEX_ALL        all exceptions
80
81
82
83       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
88       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
94
95       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
101
102       FEX_ABORT        Call abort(3C). The handler parameter is ignored.
103
104
105       FEX_SIGNAL       Invoke the function *handler with the parameters  nor‐
106                        mally  supplied  to  a  signal  handler installed with
107                        sigfpe(3C).
108
109
110       FEX_CUSTOM       Invoke the function *handler as described in the  next
111                        paragraph.
112
113
114
115       In FEX_CUSTOM mode, when a floating point exception occurs, the handler
116       function is invoked as though its prototype were:
117
118         #include <fenv.h>
119         void handler(int ex, fex_info_t *info);
120
121
122
123       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
136
137       info->res.type = fex_nodata;
138
139
140       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
144
145       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
155
156       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
160
161       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
166
167       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

RETURN VALUES

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

EXAMPLES

179       The following example demonstrates how to  substitute  a  predetermined
180       value for the result of a 0/0 invalid operation.
181
182         #include <math.h>
183         #include <fenv.h>
184
185         double k;
186
187         void presub(int ex, fex_info_t *info) {
188              info->res.type = fex_double;
189              info->res.val.d = k;
190         }
191
192         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
221
222
223       The output from the preceding program reads:
224
225         Evaluating f(x) = (k*x)/sin(x)
226
227              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
234
235
236       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

ATTRIBUTES

240       See attributes(5) for descriptions of the following attributes:
241
242
243
244
245       ┌───────────────────────────────────────────────────────────┐
246       │ATTRIBUTE TYPE                ATTRIBUTE VALUE              │
247       │Availability                  SUNWlibms, SUNWlmxs          │
248       │Interface Stability           Stable                       │
249       │MT-Level                      MT-Safe (see Notes)          │
250       └───────────────────────────────────────────────────────────┘
251

SEE ALSO

253       sigfpe(3C),    feclearexcept(3M),    fegetenv(3M),     fex_set_log(3M),
254       attributes(5)
255
256
257       Numerical Computation Guide
258

NOTES

260       In  a  multithreaded application, the preceding functions affect excep‐
261       tion handling modes only for the calling thread.
262
263
264       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
270
271       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.
279
280
281
282SunOS 5.11                        12 Jul 2006             fex_set_handling(3M)
Impressum