|
Mathematical Library Functions | matherr(3M) |
| matherr - math library exception-handling
function |
SYNOPSIS
|
#include <math.h> int matherr(struct exception *exc); |
|
The The System V Interface Definition, Third Edition (SVID3) specifies
that certain libm functions call matherr()
when exceptions are detected. Users may define their own mechanisms for
handling exceptions, by including a function named matherr()
in their programs. The matherr() function is of the
form described above. When an exception occurs, a pointer to the exception
structure exc will be passed to the user-supplied matherr() function. This structure, which is defined in the <math.h> header file, is as follows:
|
struct exception {
int type;
char *name;
double arg1, arg2, retval;
};
|
The type member is an integer describing the type
of exception that has occurred, from the following list of constants (defined
in the header file):
-
DOMAIN
- argument domain
exception
-
SING
- argument singularity
-
OVERFLOW
- overflow range exception
-
UNDERFLOW
- underflow range exception
-
TLOSS
- total loss of significance
-
PLOSS
- partial loss of significance
Note that both TLOSS and PLOSS reflect limitations of particular
algorithms for trigonometric functions that suffer abrupt declines in accuracy
at definite boundaries. Since the implementation does not suffer such abrupt
declines, PLOSS is never signaled. TLOSS is signaled for Bessel functions only to satisfy SVID3 requirements.
The name member points to a string containing
the name of the function that incurred the exception. The arg1 and arg2 members are the arguments with which
the function was invoked. retval is set to the default
value that will be returned by the function unless the user's matherr() sets it to a different value.
If the user's matherr() function returns non-zero,
no exception message will be printed, and errno will
not be set.
|
|
When an application is built as a SVID3 conforming application (see standards(5)),
if matherr() is not supplied by the user, the default
matherr exception-handling mechanisms, summarized in the table below, will
be invoked upon exception:
-
DOMAIN
- 0.0 is usually
returned, errno is set to EDOM,
and a message is usually printed on standard error.
-
SING
- The largest finite single-precision number, HUGE of appropriate sign is returned, errno
is set to EDOM, and a message is printed on standard
error.
-
OVERFLOW
- The largest finite single-precision number, HUGE of appropriate sign is usually returned, errno
is set to ERANGE.
-
UNDERFLOW
- 0.0 is returned, and errno is set to ERANGE.
-
TLOSS
- 0.0 is returned, errno is set to ERANGE, and a message is printed on standard error.
In general, errno is not a reliable error indicator
in that it may be unexpectedly set by a function in a handler for an asynchronous
signal.
SVID3 ERROR HANDLING PROCEDURES (compile with cc \-Xt)
|
<math.h> type | DOMAIN | SING | OVERFLOW | UNDERFLOW | TLOSS |
errno | EDOM | EDOM | ERANGE | ERANGE | ERANGE |
IEEE Exception | Invalid Operation | Division by Zero | Overflow | Underflow | - |
fp_exception_type | fp_invalid | fp_division | fp_overflow | fp_underflow | - |
ACOS, ASIN(|x| > 1): | Md, 0.0 | - | - | - | - |
ACOSH(x < 1), ATANH(|x| > 1): | NaN | - | - | - | - |
ATAN2(0,0): | Md, 0.0 | - | - | - | - |
COSH, SINH: | - | - | +-HUGE | - | - |
EXP: | - | - | +HUGE | 0.0 | - |
FMOD(x,0): | x | - | - | - | - |
HYPOT: | - | - | +HUGE | - | - |
J0, J1, JN(|x| > X_TLOSS): | - | - | - | - | Mt, 0.0 |
LGAMMA: | | | | | |
usual cases | - | - | +HUGE | - | - |
(x = 0 or -integer) | - | Ms, +HUGE | - | - | - |
LOG, LOG10: | | | | | |
(x < 0) | Md, -HUGE | - | - | - | - |
(x = 0) | - | Ms, -HUGE | - | - | - |
POW: | | | | | |
usual cases | - | - | +-HUGE | +-0.0 | - |
(x < 0) ** (y not an integer) | Md, 0.0 | - | - | - | - |
0 ** 0 | Md, 0.0 | - | - | - | - |
0 ** (y < 0) | Md, 0.0 | - | - | - |
REMAINDER(x,0): | NaN | - | - | - | - |
SCALB: | - | - | +-HUGE_VAL | +-0.0 | - |
SQRT(x < 0): | Md, 0.0 | - | - | - | - |
Y0, Y1, YN: | | | | | |
(x < 0) | Md, -HUGE | - | - | - | - |
(x = 0) | - | Md, -HUGE | - | - | - |
(x > X_TLOSS) | - | - | - | - | Mt, 0.0 |
|
Abbreviations
|
- Md
- Message is printed
(DOMAIN error).
- Ms
- Message is printed (SING error).
- Mt
- Message is printed (TLOSS error).
- NaN
- IEEE NaN result and invalid
operation exception.
- HUGE
- Maximum finite single-precision
floating-point number.
- HUGE_VAL
- IEEE [infin ] result and
division-by-zero exception.
- X_TLOSS
- The value X_TLOSS is defined
in <values.h>.
The interaction of IEEE arithmetic and matherr()
is not defined when executing under IEEE rounding modes other than the default
round to nearest: matherr() is not always called on overflow
or underflow, and the matherr() may return results that
differ from those in this table.
|
|
|
The X/Open System Interfaces and Headers (XSH) Issue 3 and later revisions
of that specification no longer sanctions the use of the matherr() interface. The following table summarizes the values returned
in the exceptional cases. In general, XSH dictates that as long as one
of the input argument(s) is a NaN, NaN shall be returned. In particular,
pow(NaN,0) = NaN.
CAE SPECIFICATION ERROR HANDLING PROCEDURES (compile with
cc Xa)
|
<math.h> type | DOMAIN | SING | OVERFLOW | UNDERFLOW | TLOSS |
errno | EDOM | EDOM | ERANGE | ERANGE | ERANGE |
ACOS, ASIN(|x| > 1): | 0.0 | - | - | - | - |
ATAN2(0,0): | 0.0 | - | - | - | - |
COSH, SINH: | - | - | {+-HUGE_VAL} | - | - |
EXP: | - | - | {+HUGE_VAL} | {0.0} | - |
FMOD(x,0): | {NaN} | - | - | - | - |
HYPOT: | - | - | {+HUGE_VAL} | - | - |
J0, J1, JN(|x| > X_TLOSS): | - | - | - | - | {0.0} |
LGAMMA: | | | | | |
usual cases | - | - | {+HUGE_VAL} | - | - |
(x = 0 or -integer) | - | +HUGE_VAL | - | - | - |
LOG, LOG10: | | | | | |
(x < 0) | HUGE_VAL | - | - | - | - |
(x = 0) | - | HUGE_VAL | - | - | - |
POW: | | | | | |
usual cases | - | - | +-HUGE_VAL | +-0.0 | - |
(x < 0) ** (y not an integer) | 0.0 | - | - | - | - |
0 ** 0 | {1.0} | - | - | - | - |
0 ** (y < 0) | {HUGE_VAL} | - | - | - | - |
SQRT(x < 0): | 0.0 | - | - | - | - |
Y0, Y1, YN: | | | | | |
(x < 0) | {HUGE_VAL} | - | - | - | - |
(x = 0) | - | {HUGE_VAL} | - | - | - |
(x > X_TLOSS) | - | - | - | - | 0.0 |
|
Abbreviations
|
- {...}
-
errno is not to be relied upon in all braced cases.
- NaN
- IEEE NaN result and invalid
operation exception.
- HUGE_VAL
- IEEE [infin ] result and
division-by-zero exception.
- X_TLOSS
- The value X_TLOSS is defined
in <values.h>.
|
|
|
The ANSI/ISO-C standard covers a small subset of the CAE specification.
The following table summarizes the values returned in the exceptional
cases.
ANSI/ISO-C ERROR HANDLING PROCEDURES (compile with cc Xc)
|
<math.h> type | DOMAIN | SING | OVERFLOW | UNDERFLOW |
errno | EDOM | EDOM | ERANGE | ERANGE |
ACOS, ASIN(|x| > 1): | 0.0 | - | - | - |
ATAN2(0,0): | 0.0 | - | - | - |
EXP: | - | - | +HUGE_VAL | 0.0 |
FMOD(x,0): | NaN | - | - | - |
LOG, LOG10: | | | | |
(x < 0) | HUGE_VAL | - | - | - |
(x = 0) | - | HUGE_VAL | - | - |
POW: | | | | |
usual cases | - | - | +-HUGE_VAL | +-0.0 |
(x < 0) ** (y not an integer) | 0.0 | - | - | - |
0 ** (y < 0) | HUGE_VAL | - | - | - |
SQRT(x < 0): | 0.0 | - | - | - |
|
ABBREVIATIONS
|
- NaN
- IEEE NaN result
and invalid operation exception.
- HUGE_VAL
- IEEE [infin ] result and
division-by-zero
|
|
| Example 1. Example of matherr function
|
|
#include <stdio.h>
#include <stdlib.h>
#include <math.h>
int
matherr(struct exception *x) {
switch (x->type) {
case DOMAIN:
/* change sqrt to return sqrt(-arg1), not NaN */
if (!strcmp(x->name, "sqrt")) {
x->retval = sqrt(-x->arg1);
return (0); /* print message and set errno */
} /* FALLTHRU */
case SING:
/* all other domain or sing exceptions, print message and */
/* abort */
fprintf(stderr, "domain exception in %s\n", x->name);
abort( );
break;
}
return (0); /* all other exceptions, execute default procedure */
}
|
|
|
|
See attributes(5)
for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
MT-Level | MT-Safe |
|
| |