1 '\" te
2 .\" Copyright (c) 2008, 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 matherr 3M "23 Sep 1997" "SunOS 5.11" "Mathematical Library Functions"
7 .SH NAME
8 matherr \- math library exception-handling function
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <math.h>
13
14 \fBint\fR \fBmatherr\fR(\fBstruct exception *\fR\fIexc\fR);
15 .fi
16
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The System V Interface Definition, Third Edition (SVID3) specifies that certain
21 \fBlibm\fR functions call \fBmatherr()\fR when exceptions are detected. Users
22 may define their own mechanisms for handling exceptions, by including a
23 function named \fBmatherr()\fR in their programs. The \fBmatherr()\fR function
24 is of the form described above. When an exception occurs, a pointer to the
25 exception structure \fIexc\fR will be passed to the user-supplied
26 \fBmatherr()\fR function. This structure, which is defined in the
27 \fB<math.h>\fR header file, is as follows:
28 .sp
29 .in +2
30 .nf
31 struct exception {
32 int type;
33 char *name;
34 double arg1, arg2, retval;
35 };
36 .fi
37 .in -2
38
39 .sp
40 .LP
41 The \fBtype\fR member is an integer describing the type of exception that has
42 occurred, from the following list of constants (defined in the header file):
43 .sp
44 .ne 2
45 .mk
46 .na
47 \fB\fBDOMAIN\fR\fR
48 .ad
49 .RS 13n
50 .rt
51 argument domain exception
52 .RE
53
54 .sp
55 .ne 2
56 .mk
57 .na
58 \fB\fBSING\fR\fR
59 .ad
60 .RS 13n
61 .rt
62 argument singularity
63 .RE
64
65 .sp
66 .ne 2
67 .mk
68 .na
69 \fB\fBOVERFLOW\fR\fR
70 .ad
71 .RS 13n
72 .rt
73 overflow range exception
74 .RE
75
76 .sp
77 .ne 2
78 .mk
79 .na
80 \fB\fBUNDERFLOW\fR\fR
81 .ad
82 .RS 13n
83 .rt
84 underflow range exception
85 .RE
86
87 .sp
88 .ne 2
89 .mk
90 .na
91 \fB\fBTLOSS\fR\fR
92 .ad
93 .RS 13n
94 .rt
95 total loss of significance
96 .RE
97
98 .sp
99 .ne 2
100 .mk
101 .na
102 \fB\fBPLOSS\fR\fR
103 .ad
104 .RS 13n
105 .rt
106 partial loss of significance
107 .RE
108
109 .sp
110 .LP
111 Both \fBTLOSS\fR and \fBPLOSS\fR reflect limitations of particular algorithms
112 for trigonometric functions that suffer abrupt declines in accuracy at definite
113 boundaries. Since the implementation does not suffer such abrupt declines,
114 \fBPLOSS\fR is never signaled. \fBTLOSS\fR is signaled for Bessel functions
115 \fIonly\fR to satisfy SVID3 requirements.
116 .sp
117 .LP
118 The \fBname\fR member points to a string containing the name of the function
119 that incurred the exception. The \fBarg1\fR and \fBarg2\fR members are the
120 arguments with which the function was invoked. \fBretval\fR is set to the
121 default value that will be returned by the function unless the user's
122 \fBmatherr()\fR sets it to a different value.
123 .sp
124 .LP
125 If the user's \fBmatherr()\fR function returns non-zero, no exception message
126 will be printed and \fBerrno\fR is not set.
127 .SH SVID3 STANDARD CONFORMANCE
128 .sp
129 .LP
130 When an application is built as a SVID3 conforming application (see
131 \fBstandards\fR(5)), if \fBmatherr()\fR is not supplied by the user, the
132 default matherr exception-handling mechanisms, summarized in the table below,
133 are invoked upon exception:
134 .sp
135 .ne 2
136 .mk
137 .na
138 \fB\fBDOMAIN\fR\fR
139 .ad
140 .RS 13n
141 .rt
142 0.0 is usually returned, \fBerrno\fR is set to \fBEDOM\fR and a message is
143 usually printed on standard error.
144 .RE
145
146 .sp
147 .ne 2
148 .mk
149 .na
150 \fB\fBSING\fR\fR
151 .ad
152 .RS 13n
153 .rt
154 The largest finite single-precision number, \fBHUGE\fR of appropriate sign, is
155 returned, \fBerrno\fR is set to \fBEDOM\fR, and a message is printed on
156 standard error.
157 .RE
158
159 .sp
160 .ne 2
161 .mk
162 .na
163 \fB\fBOVERFLOW\fR\fR
164 .ad
165 .RS 13n
166 .rt
167 The largest finite single-precision number, \fBHUGE\fR of appropriate sign, is
168 usually returned and \fBerrno\fR is set to \fBERANGE\fR.
169 .RE
170
171 .sp
172 .ne 2
173 .mk
174 .na
175 \fB\fBUNDERFLOW\fR\fR
176 .ad
177 .RS 13n
178 .rt
179 0.0 is returned and \fBerrno\fR is set to \fBERANGE\fR.
180 .RE
181
182 .sp
183 .ne 2
184 .mk
185 .na
186 \fB\fBTLOSS\fR\fR
187 .ad
188 .RS 13n
189 .rt
190 0.0 is returned, \fBerrno\fR is set to \fBERANGE\fR, and a message is printed
191 on standard error.
192 .RE
193
194 .sp
195 .LP
196 In general, \fBerrno\fR is not a reliable error indicator because it can be
197 unexpectedly set by a function in a handler for an asynchronous signal.
198 .SS "SVID3 ERROR HANDLING PROCEDURES (compile with cc \e-Xt)"
199 .sp
200
201 .sp
202 .TS
203 tab() box;
204 cw(1.29i) |cw(.81i) |cw(.79i) |cw(.87i) |cw(1.03i) |cw(.71i)
205 lw(1.29i) |lw(.81i) |lw(.79i) |lw(.87i) |lw(1.03i) |lw(.71i)
206 .
207 <math.h> typeDOMAINSINGOVERFLOWUNDERFLOWTLOSS
208 _
209 \fBerrno\fREDOMEDOMERANGEERANGEERANGE
210 _
211 IEEE ExceptionInvalid OperationDivision by ZeroOverflowUnderflow\(mi
212 _
213 fp_exception_typefp_invalidfp_divisionfp_overflowfp_underflow\(mi
214 _
215 ACOS, ASIN\|(|x| > 1):Md, 0.0\(mi\(mi\(mi\(mi
216 _
217 ACOSH\|(x < 1), ATANH\|(|x| > 1):NaN\(mi\(mi\(mi\(mi
218 _
219 ATAN2\|(0,0):Md, 0.0\(mi\(mi\(mi\(mi
220 _
221 COSH, SINH:\(mi\(mi\(+-HUGE\(mi\(mi
222 _
223 EXP:\(mi\(mi+HUGE0.0\(mi
224 _
225 FMOD\|(x,0):x\(mi\(mi\(mi\(mi
226 _
227 HYPOT:\(mi\(mi+HUGE\(mi\(mi
228 _
229 J0, J1, JN\|(|x| > X_TLOSS):\(mi\(mi\(mi\(miMt, 0.0
230 _
231 LGAMMA:
232 usual cases\(mi\(mi+HUGE\(mi\(mi
233 (x = 0 or \(miinteger) \(miMs, +HUGE\(mi\(mi\(mi
234 _
235 LOG, LOG10:
236 (x < 0)Md, \(miHUGE\(mi \(mi\(mi\(mi
237 (x = 0)\(miMs, \(miHUGE\(mi\(mi\(mi
238 _
239 POW:
240 usual cases\(mi\(mi\(+-HUGE\(+-0.0\(mi
241 (x < 0) ** (y not an integer)Md, 0.0\(mi\(mi\(mi\(mi
242 0 ** 0Md, 0.0\(mi\(mi\(mi\(mi
243 0 ** (y < 0)Md, 0.0\(mi\(mi\(mi
244 _
245 REMAINDER\|(x,0):NaN\(mi\(mi\(mi\(mi
246 _
247 SCALB:\(mi\(mi\(+-HUGE_VAL\(+-0.0\(mi
248 _
249 SQRT\|(x < 0):Md, 0.0\(mi\(mi\(mi\(mi
250 _
251 Y0, Y1, YN:
252 (x < 0)Md, \(miHUGE\(mi\(mi\(mi\(mi
253 (x = 0)\(miMd, \(miHUGE\(mi\(mi\(mi
254 (x > X_TLOSS)\(mi\(mi\(mi\(miMt, 0.0
255 .TE
256
257 .SS "Abbreviations"
258 .sp
259 .ne 2
260 .mk
261 .na
262 \fBMd\fR
263 .ad
264 .RS 12n
265 .rt
266 Message is printed (DOMAIN error).
267 .RE
268
269 .sp
270 .ne 2
271 .mk
272 .na
273 \fBMs\fR
274 .ad
275 .RS 12n
276 .rt
277 Message is printed (SING error).
278 .RE
279
280 .sp
281 .ne 2
282 .mk
283 .na
284 \fBMt\fR
285 .ad
286 .RS 12n
287 .rt
288 Message is printed (TLOSS error).
289 .RE
290
291 .sp
292 .ne 2
293 .mk
294 .na
295 \fBNaN\fR
296 .ad
297 .RS 12n
298 .rt
299 IEEE NaN result and invalid operation exception.
300 .RE
301
302 .sp
303 .ne 2
304 .mk
305 .na
306 \fBHUGE\fR
307 .ad
308 .RS 12n
309 .rt
310 Maximum finite single-precision floating-point number.
311 .RE
312
313 .sp
314 .ne 2
315 .mk
316 .na
317 \fBHUGE_VAL\fR
318 .ad
319 .RS 12n
320 .rt
321 IEEE \(if result and division-by-zero exception.
322 .RE
323
324 .sp
325 .ne 2
326 .mk
327 .na
328 \fBX_TLOSS\fR
329 .ad
330 .RS 12n
331 .rt
332 The value X_TLOSS is defined in <values.h>.
333 .RE
334
335 .sp
336 .LP
337 The interaction of IEEE arithmetic and \fBmatherr()\fR is not defined when
338 executing under IEEE rounding modes other than the default round to nearest:
339 \fBmatherr()\fR is not always called on overflow or underflow and can return
340 results that differ from those in this table.
341 .SH X/OPEN COMMON APPLICATION ENVIRONMENT (CAE) SPECIFICATIONS CONFORMANCE
342 .sp
343 .LP
344 The X/Open System Interfaces and Headers (XSH) Issue 3 and later revisions of
345 that specification no longer sanctions the use of the \fBmatherr\fR interface.
346 The following table summarizes the values returned in the exceptional cases.
347 In general, XSH dictates that as long as one of the input argument(s) is a NaN,
348 NaN is returned. In particular, \fBpow(NaN,0)\fR = NaN.
349 .SS "CAE SPECIFICATION ERROR HANDLING PROCEDURES (compile with cc \fB-Xa\fR)"
350 .sp
351
352 .sp
353 .TS
354 tab() box;
355 cw(.82i) |cw(1.03i) |cw(1i) |cw(.97i) |cw(.96i) |cw(.72i)
356 lw(.82i) |lw(1.03i) |lw(1i) |lw(.97i) |lw(.96i) |lw(.72i)
357 .
358 <math.h> typeDOMAINSINGOVERFLOWUNDERFLOWTLOSS
359 _
360 \fBerrno\fREDOMEDOMERANGEERANGEERANGE
361 _
362 ACOS, ASIN\|(|x| > 1):0.0\(mi\(mi\(mi\(mi
363 _
364 ATAN2\|(0,0):0.0\(mi\(mi\(mi\(mi
365 _
366 COSH, SINH:\(mi\(mi{\(+-HUGE_VAL}\(mi\(mi
367 _
368 EXP:\(mi\(mi{+HUGE_VAL}{0.0}\(mi
369 _
370 FMOD\|(x,0):{NaN}\(mi\(mi\(mi\(mi
371 _
372 HYPOT:\(mi\(mi{+HUGE_VAL}\(mi\(mi
373 _
374 J0, J1, JN\|(|x| > X_TLOSS):\(mi\(mi\(mi\(mi{0.0}
375 _
376 LGAMMA:
377 usual cases\(mi\(mi{+HUGE_VAL}\(mi\(mi
378 (x = 0 or \(miinteger) \(mi+HUGE_VAL\(mi\(mi\(mi
379 _
380 LOG, LOG10:
381 (x < 0)\fB-HUGE_VAL\fR\(mi\(mi\(mi\(mi
382 (x = 0)\(mi\fB-HUGE_VAL\fR\(mi\(mi\(mi
383 _
384 POW:
385 usual cases\(mi\(mi\(+-HUGE_VAL\(+-0.0\(mi
386 (x < 0) ** (y not an integer)0.0\(mi\(mi\(mi\(mi
387 0 ** 0{1.0}\(mi\(mi\(mi\(mi
388 0 ** (y < 0){\fB-HUGE_VAL\fR}\(mi\(mi\(mi\(mi
389 _
390 SQRT\|(x < 0):0.0\(mi\(mi\(mi\(mi
391 _
392 Y0, Y1, YN:
393 (x < 0){\fB-HUGE_VAL\fR}\(mi\(mi\(mi\(mi
394 (x = 0)\(mi{\fB-HUGE_VAL\fR}\(mi\(mi\(mi
395 (x > X_TLOSS)\(mi\(mi\(mi\(mi0.0
396 .TE
397
398 .SS "Abbreviations"
399 .sp
400 .ne 2
401 .mk
402 .na
403 \fB{...}\fR
404 .ad
405 .RS 12n
406 .rt
407 \fBerrno\fR is not to be relied upon in all braced cases.
408 .RE
409
410 .sp
411 .ne 2
412 .mk
413 .na
414 \fBNaN\fR
415 .ad
416 .RS 12n
417 .rt
418 IEEE NaN result and invalid operation exception.
419 .RE
420
421 .sp
422 .ne 2
423 .mk
424 .na
425 \fBHUGE_VAL\fR
426 .ad
427 .RS 12n
428 .rt
429 IEEE \(if result and division-by-zero exception.
430 .RE
431
432 .sp
433 .ne 2
434 .mk
435 .na
436 \fBX_TLOSS\fR
437 .ad
438 .RS 12n
439 .rt
440 The value X_TLOSS is defined in <\fBvalues.h\fR>.
441 .RE
442
443 .SH ANSI/ISO-C STANDARD CONFORMANCE
444 .sp
445 .LP
446 The ANSI/ISO-C standard covers a small subset of the CAE specification.
447 .sp
448 .LP
449 The following table summarizes the values returned in the exceptional cases.
450 .SS "ANSI/ISO-C ERROR HANDLING PROCEDURES (compile with cc \fB-Xc\fR)"
451 .sp
452
453 .sp
454 .TS
455 tab() box;
456 cw(1.1i) |cw(1.1i) |cw(1.1i) |cw(1.1i) |cw(1.11i)
457 lw(1.1i) |lw(1.1i) |lw(1.1i) |lw(1.1i) |lw(1.11i)
458 .
459 <math.h> typeDOMAINSINGOVERFLOWUNDERFLOW
460 _
461 \fBerrno\fREDOMEDOMERANGEERANGE
462 _
463 ACOS, ASIN\|(|x| > 1):0.0\(mi\(mi\(mi
464 _
465 ATAN2\|(0,0):0.0\(mi\(mi\(mi
466 _
467 EXP:\(mi\(mi+HUGE_VAL0.0
468 _
469 FMOD\|(x,0):NaN\(mi\(mi\(mi
470 _
471 LOG, LOG10:
472 (x < 0)\fB-HUGE_VAL\fR\(mi\(mi\(mi
473 (x = 0)\(mi\fB-HUGE_VAL\fR\(mi\(mi
474 _
475 POW:
476 usual cases\(mi\(mi\(+-HUGE_VAL\(+-0.0
477 (x < 0) ** (y not an integer)0.0\(mi\(mi\(mi
478 0 ** (y < 0)\fB-HUGE_VAL\fR\(mi\(mi\(mi
479 _
480 SQRT\|(x < 0):0.0\(mi\(mi\(mi
481 .TE
482
483 .SS "ABBREVIATIONS"
484 .sp
485 .ne 2
486 .mk
487 .na
488 \fBNaN\fR
489 .ad
490 .RS 12n
491 .rt
492 IEEE NaN result and invalid operation exception.
493 .RE
494
495 .sp
496 .ne 2
497 .mk
498 .na
499 \fBHUGE_VAL\fR
500 .ad
501 .RS 12n
502 .rt
503 IEEE \(if result and division-by-zero.
504 .RE
505
506 .SH EXAMPLES
507 .LP
508 \fBExample 1 \fRExample of \fBmatherr()\fR function
509 .sp
510 .in +2
511 .nf
512 #include <stdio.h>
513 #include <stdlib.h>
514 #include <math.h>
515
516 int
517 matherr(struct exception *x) {
518 switch (x\(mi>type) {
519 case DOMAIN:
520 /* change sqrt to return sqrt(\(miarg1), not NaN */
521 if (!strcmp(x\(mi>name, "sqrt")) {
522 x\(mi>retval = sqrt(\(mix\(mi>arg1);
523 return (0); /* print message and set errno */
524 } /* FALLTHRU */
525 case SING:
526 /* all other domain or sing exceptions, print message and */
527 /* abort */
528 fprintf(stderr, "domain exception in %s\en", x\(mi>name);
529 abort( );
530 break;
531 }
532 return (0); /* all other exceptions, execute default procedure */
533 }
534 .fi
535 .in -2
536
537 .SH ATTRIBUTES
538 .sp
539 .LP
540 See \fBattributes\fR(5) for descriptions of the following attributes:
541 .sp
542
543 .sp
544 .TS
545 tab() box;
546 cw(2.75i) |cw(2.75i)
547 lw(2.75i) |lw(2.75i)
548 .
549 ATTRIBUTE TYPEATTRIBUTE VALUE
550 _
551 MT-LevelMT-Safe
552 .TE
553
554 .SH SEE ALSO
555 .sp
556 .LP
557 \fBattributes\fR(5), \fBstandards\fR(5)