1matherr(3M) Mathematical Library Functions matherr(3M)
2
3
4
6 matherr - math library exception-handling function
7
9 #include <math.h>
10
11 int matherr(struct exception *exc);
12
13
15 The System V Interface Definition, Third Edition (SVID3) specifies that
16 certain libm functions call matherr() when exceptions are detected.
17 Users may define their own mechanisms for handling exceptions, by
18 including a function named matherr() in their programs. The matherr()
19 function is of the form described above. When an exception occurs, a
20 pointer to the exception structure exc will be passed to the user-sup‐
21 plied matherr() function. This structure, which is defined in the
22 <math.h> header file, is as follows:
23
24 struct exception {
25 int type;
26 char *name;
27 double arg1, arg2, retval;
28 };
29
30
31
32 The type member is an integer describing the type of exception that has
33 occurred, from the following list of constants (defined in the header
34 file):
35
36 DOMAIN argument domain exception
37
38
39 SING argument singularity
40
41
42 OVERFLOW overflow range exception
43
44
45 UNDERFLOW underflow range exception
46
47
48 TLOSS total loss of significance
49
50
51 PLOSS partial loss of significance
52
53
54
55 Both TLOSS and PLOSS reflect limitations of particular algorithms for
56 trigonometric functions that suffer abrupt declines in accuracy at def‐
57 inite boundaries. Since the implementation does not suffer such abrupt
58 declines, PLOSS is never signaled. TLOSS is signaled for Bessel func‐
59 tions only to satisfy SVID3 requirements.
60
61
62 The name member points to a string containing the name of the function
63 that incurred the exception. The arg1 and arg2 members are the argu‐
64 ments with which the function was invoked. retval is set to the default
65 value that will be returned by the function unless the user's matherr()
66 sets it to a different value.
67
68
69 If the user's matherr() function returns non-zero, no exception message
70 will be printed and errno is not set.
71
73 When an application is built as a SVID3 conforming application (see
74 standards(5)), if matherr() is not supplied by the user, the default
75 matherr exception-handling mechanisms, summarized in the table below,
76 are invoked upon exception:
77
78 DOMAIN 0.0 is usually returned, errno is set to EDOM and a mes‐
79 sage is usually printed on standard error.
80
81
82 SING The largest finite single-precision number, HUGE of appro‐
83 priate sign, is returned, errno is set to EDOM, and a mes‐
84 sage is printed on standard error.
85
86
87 OVERFLOW The largest finite single-precision number, HUGE of appro‐
88 priate sign, is usually returned and errno is set to
89 ERANGE.
90
91
92 UNDERFLOW 0.0 is returned and errno is set to ERANGE.
93
94
95 TLOSS 0.0 is returned, errno is set to ERANGE, and a message is
96 printed on standard error.
97
98
99
100 In general, errno is not a reliable error indicator because it can be
101 unexpectedly set by a function in a handler for an asynchronous signal.
102
103 SVID3 ERROR HANDLING PROCEDURES (compile with cc \-Xt)
104 ┌───────────────────────────────┬───────────────────┬──────────────────┬─────────────┬──────────────┬─────────┐
105 │ <math.h> type │ DOMAIN │ SING │ OVERFLOW │ UNDERFLOW │ TLOSS │
106 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
107 │errno │ EDOM │ EDOM │ ERANGE │ ERANGE │ ERANGE │
108 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
109 │IEEE Exception │ Invalid Operation │ Division by Zero │ Overflow │ Underflow │ − │
110 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
111 │fp_exception_type │ fp_invalid │ fp_division │ fp_overflow │ fp_underflow │ − │
112 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
113 │ACOS, ASIN(|x| > 1): │ Md, 0.0 │ − │ − │ − │ − │
114 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
115 │ACOSH(x < 1), ATANH(|x| > 1): │ NaN │ − │ − │ − │ − │
116 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
117 │ATAN2(0,0): │ Md, 0.0 │ − │ − │ − │ − │
118 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
119 │COSH, SINH: │ − │ − │ ±HUGE │ − │ − │
120 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
121 │EXP: │ − │ − │ +HUGE │ 0.0 │ − │
122 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
123 │FMOD(x,0): │ x │ − │ − │ − │ − │
124 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
125 │HYPOT: │ − │ − │ +HUGE │ − │ − │
126 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
127 │J0, J1, JN(|x| > X_TLOSS): │ − │ − │ − │ − │ Mt, 0.0 │
128 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
129 │LGAMMA: │ │ │ │ │ │
130 │ usual cases │ − │ − │ +HUGE │ − │ − │
131 │ (x = 0 or −integer) │ − │ Ms, +HUGE │ − │ − │ − │
132 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
133 │LOG, LOG10: │ │ │ │ │ │
134 │ (x < 0) │ Md, −HUGE │ − │ − │ − │ − │
135 │ (x = 0) │ − │ Ms, −HUGE │ − │ − │ − │
136 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
137 │POW: │ │ │ │ │ │
138 │ usual cases │ − │ − │ ±HUGE │ ±0.0 │ − │
139 │ (x < 0) ** (y not an integer) │ Md, 0.0 │ − │ − │ − │ − │
140 │ 0 ** 0 │ Md, 0.0 │ − │ − │ − │ − │
141 │ 0 ** (y < 0) │ Md, 0.0 │ − │ − │ − │ │
142 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
143 │REMAINDER(x,0): │ NaN │ − │ − │ − │ − │
144 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
145 │SCALB: │ − │ − │ ±HUGE_VAL │ ±0.0 │ − │
146 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
147 │SQRT(x < 0): │ Md, 0.0 │ − │ − │ − │ − │
148 ├───────────────────────────────┼───────────────────┼──────────────────┼─────────────┼──────────────┼─────────┤
149 │Y0, Y1, YN: │ │ │ │ │ │
150 │ (x < 0) │ Md, −HUGE │ − │ − │ − │ − │
151 │ (x = 0) │ − │ Md, −HUGE │ − │ − │ − │
152 │ (x > X_TLOSS) │ − │ − │ − │ − │ Mt, 0.0 │
153 └───────────────────────────────┴───────────────────┴──────────────────┴─────────────┴──────────────┴─────────┘
154
155 Abbreviations
156 Md Message is printed (DOMAIN error).
157
158
159 Ms Message is printed (SING error).
160
161
162 Mt Message is printed (TLOSS error).
163
164
165 NaN IEEE NaN result and invalid operation exception.
166
167
168 HUGE Maximum finite single-precision floating-point number.
169
170
171 HUGE_VAL IEEE ∞ result and division-by-zero exception.
172
173
174 X_TLOSS The value X_TLOSS is defined in <values.h>.
175
176
177
178 The interaction of IEEE arithmetic and matherr() is not defined when
179 executing under IEEE rounding modes other than the default round to
180 nearest: matherr() is not always called on overflow or underflow and
181 can return results that differ from those in this table.
182
184 The X/Open System Interfaces and Headers (XSH) Issue 3 and later revi‐
185 sions of that specification no longer sanctions the use of the matherr
186 interface. The following table summarizes the values returned in the
187 exceptional cases. In general, XSH dictates that as long as one of the
188 input argument(s) is a NaN, NaN is returned. In particular, pow(NaN,0)
189 = NaN.
190
191 CAE SPECIFICATION ERROR HANDLING PROCEDURES (compile with cc -Xa)
192 ┌───────────────────────────────┬─────────────┬─────────────┬─────────────┬────────────┬─────────┐
193 │ <math.h> type │ DOMAIN │ SING │ OVERFLOW │ UNDERFLOW │ TLOSS │
194 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
195 │errno │ EDOM │ EDOM │ ERANGE │ ERANGE │ ERANGE │
196 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
197 │ACOS, ASIN(|x| > 1): │ 0.0 │ − │ − │ − │ − │
198 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
199 │ATAN2(0,0): │ 0.0 │ − │ − │ − │ − │
200 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
201 │COSH, SINH: │ − │ − │ {±HUGE_VAL} │ − │ − │
202 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
203 │EXP: │ − │ − │ {+HUGE_VAL} │ {0.0} │ − │
204 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
205 │FMOD(x,0): │ {NaN} │ − │ − │ − │ − │
206 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
207 │HYPOT: │ − │ − │ {+HUGE_VAL} │ − │ − │
208 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
209 │J0, J1, JN(|x| > X_TLOSS): │ − │ − │ − │ − │ {0.0} │
210 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
211 │LGAMMA: │ │ │ │ │ │
212 │ usual cases │ − │ − │ {+HUGE_VAL} │ − │ − │
213 │ (x = 0 or −integer) │ − │ +HUGE_VAL │ − │ − │ − │
214 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
215 │LOG, LOG10: │ │ │ │ │ │
216 │ (x < 0) │ -HUGE_VAL │ − │ − │ − │ − │
217 │ (x = 0) │ − │ -HUGE_VAL │ − │ − │ − │
218 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
219 │POW: │ │ │ │ │ │
220 │ usual cases │ − │ − │ ±HUGE_VAL │ ±0.0 │ − │
221 │ (x < 0) ** (y not an integer) │ 0.0 │ − │ − │ − │ − │
222 │ 0 ** 0 │ {1.0} │ − │ − │ − │ − │
223 │ 0 ** (y < 0) │ {-HUGE_VAL} │ − │ − │ − │ − │
224 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
225 │SQRT(x < 0): │ 0.0 │ − │ − │ − │ − │
226 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼────────────┼─────────┤
227 │Y0, Y1, YN: │ │ │ │ │ │
228 │ (x < 0) │ {-HUGE_VAL} │ − │ − │ − │ − │
229 │ (x = 0) │ − │ {-HUGE_VAL} │ − │ − │ − │
230 │ (x > X_TLOSS) │ − │ − │ − │ − │ 0.0 │
231 └───────────────────────────────┴─────────────┴─────────────┴─────────────┴────────────┴─────────┘
232
233 Abbreviations
234 {...} errno is not to be relied upon in all braced cases.
235
236
237 NaN IEEE NaN result and invalid operation exception.
238
239
240 HUGE_VAL IEEE ∞ result and division-by-zero exception.
241
242
243 X_TLOSS The value X_TLOSS is defined in <values.h>.
244
245
247 The ANSI/ISO-C standard covers a small subset of the CAE specification.
248
249
250 The following table summarizes the values returned in the exceptional
251 cases.
252
253 ANSI/ISO-C ERROR HANDLING PROCEDURES (compile with cc -Xc)
254 ┌───────────────────────────────┬─────────────┬─────────────┬─────────────┬─────────────┐
255 │ <math.h> type │ DOMAIN │ SING │ OVERFLOW │ UNDERFLOW │
256 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
257 │errno │ EDOM │ EDOM │ ERANGE │ ERANGE │
258 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
259 │ACOS, ASIN(|x| > 1): │ 0.0 │ − │ − │ − │
260 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
261 │ATAN2(0,0): │ 0.0 │ − │ − │ − │
262 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
263 │EXP: │ − │ − │ +HUGE_VAL │ 0.0 │
264 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
265 │FMOD(x,0): │ NaN │ − │ − │ − │
266 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
267 │LOG, LOG10: │ │ │ │ │
268 │ (x < 0) │ -HUGE_VAL │ − │ − │ − │
269 │ (x = 0) │ − │ -HUGE_VAL │ − │ − │
270 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
271 │POW: │ │ │ │ │
272 │ usual cases │ − │ − │ ±HUGE_VAL │ ±0.0 │
273 │ (x < 0) ** (y not an integer) │ 0.0 │ − │ − │ − │
274 │ 0 ** (y < 0) │ -HUGE_VAL │ − │ − │ − │
275 ├───────────────────────────────┼─────────────┼─────────────┼─────────────┼─────────────┤
276 │SQRT(x < 0): │ 0.0 │ − │ − │ − │
277 └───────────────────────────────┴─────────────┴─────────────┴─────────────┴─────────────┘
278
279 ABBREVIATIONS
280 NaN IEEE NaN result and invalid operation exception.
281
282
283 HUGE_VAL IEEE ∞ result and division-by-zero.
284
285
287 Example 1 Example of matherr() function
288
289 #include <stdio.h>
290 #include <stdlib.h>
291 #include <math.h>
292
293 int
294 matherr(struct exception *x) {
295 switch (x−>type) {
296 case DOMAIN:
297 /* change sqrt to return sqrt(−arg1), not NaN */
298 if (!strcmp(x−>name, "sqrt")) {
299 x−>retval = sqrt(−x−>arg1);
300 return (0); /* print message and set errno */
301 } /* FALLTHRU */
302 case SING:
303 /* all other domain or sing exceptions, print message and */
304 /* abort */
305 fprintf(stderr, "domain exception in %s\n", x−>name);
306 abort( );
307 break;
308 }
309 return (0); /* all other exceptions, execute default procedure */
310 }
311
312
314 See attributes(5) for descriptions of the following attributes:
315
316
317
318
319 ┌─────────────────────────────┬─────────────────────────────┐
320 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
321 ├─────────────────────────────┼─────────────────────────────┤
322 │MT-Level │MT-Safe │
323 └─────────────────────────────┴─────────────────────────────┘
324
326 attributes(5), standards(5)
327
328
329
330SunOS 5.11 23 Sep 1997 matherr(3M)