Mathematical Library Functions matherr(3M)
NAME
matherr - math library exception-handling function
SYNOPSIS
#include
int matherr(struct exception *exc);
DESCRIPTION
The System V Interface Definition, Third Edition (SVID3)
specifies that certain libm functions call matherr() when
exceptions are detected. Users may define their own mechan-
isms 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 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 excep-
tion 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
TLOS total loss of significance
PLOS partial loss of significance
SunOS 5.11 Last change: 23 Sep 1997 1
Mathematical Library Functions matherr(3M)
Both TLOS and PLOS reflect limitations of particular algo-
rithms for trigonometric functions that suffer abrupt
declines in accuracy at definite boundaries. Since the
implementation does not suffer such abrupt declines, PLOS
is never signaled. TLOS 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 excep-
tion message will be printed and errno is not set.
SVID3 STANDARD CONFORMANCE
When an application is built as a SVID3 conforming applica-
tion (see standards(5)), if matherr() is not supplied by the
user, the default matherr exception-handling mechanisms,
summarized in the table below, are 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 stan-
dard error.
OVERFLOW The largest finite single-precision number,
HUGE of appropriate sign, is usually returned
and errno is set to ERANGE.
UNDERFLOW 0.0 is returned and errno is set to ERANGE.
TLOS 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 because
it can be unexpectedly set by a function in a handler for an
asynchronous signal.
SunOS 5.11 Last change: 23 Sep 1997 2
Mathematical Library Functions matherr(3M)
SVID3 EROR HANDLING PROCEDURES (compile with cc \-Xt)
SunOS 5.11 Last change: 23 Sep 1997 3
Mathematical Library Functions matherr(3M)
type DOMAIN SING OVERFLOW UNDERFLOW TLOS
errno EDOM EDOM ERANGE ERANGE ERANGE
IE Exception Invalid Operation Division by Zero Overflow Underflow -
fpexceptiontype fpinvalid fpdivision fpoverflow fpunderflow -
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 > XTLOS): - - - - Mt, 0.0
LGAMA:
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: - - ]HUGEVAL ]0.0 -
SQRT(x < 0): Md, 0.0 - - - -
Y0, Y1, YN:
(x < 0) Md, -HUGE - - - -
(x = 0) - Md, -HUGE - - -
(x > XTLOS) - - - - Mt, 0.0
SunOS 5.11 Last change: 23 Sep 1997 4
Mathematical Library Functions matherr(3M)
Abbreviations
Md Message is printed (DOMAIN error).
Ms Message is printed (SING error).
Mt Message is printed (TLOS error).
NaN IE NaN result and invalid operation exception.
HUGE Maximum finite single-precision floating-point
number.
HUGEVAL IE oo result and division-by-zero exception.
XTLOS The value XTLOS is defined in .
The interaction of IE arithmetic and matherr() is not
defined when executing under IE rounding modes other than
the default round to nearest: matherr() is not always called
on overflow or underflow and can return results that differ
from those in this table.
X/OPEN COMON APLICATION ENVIRONMENT (CAE) SPECIFICATIONS
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 sum-
marizes 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 is returned. In particular,
pow(NaN,0) = NaN.
CAE SPECIFICATION EROR HANDLING PROCEDURES (compile with cc
-Xa)
SunOS 5.11 Last change: 23 Sep 1997 5
Mathematical Library Functions matherr(3M)
SunOS 5.11 Last change: 23 Sep 1997 6
Mathematical Library Functions matherr(3M)
type DOMAIN SING OVERFLOW UNDERFLOW TLOS
errno EDOM EDOM ERANGE ERANGE ERANGE
ACOS, ASIN(x > 1): 0.0 - - - -
ATAN2(0,0): 0.0 - - - -
COSH, SINH: - - {]HUGEVAL} - -
EXP: - - {]HUGEVAL} {0.0} -
FMOD(x,0): {NaN} - - - -
HYPOT: - - {]HUGEVAL} - -
J0, J1, JN(x > XTLOS): - - - - {0.0}
LGAMA:
usual cases - - {]HUGEVAL} - -
(x = 0 or -integer) - ]HUGEVAL - - -
LOG, LOG10:
(x < 0) -HUGEVAL - - - -
(x = 0) - -HUGEVAL - - -
POW:
usual cases - - ]HUGEVAL ]0.0 -
(x < 0) ** (y not an integer) 0.0 - - - -
0 ** 0 {1.0} - - - -
0 ** (y < 0) {-HUGEVAL} - - - -
SQRT(x < 0): 0.0 - - - -
Y0, Y1, YN:
(x < 0) {-HUGEVAL} - - - -
(x = 0) - {-HUGEVAL} - - -
(x > XTLOS) - - - - 0.0
Abbreviations
{...} errno is not to be relied upon in all braced
cases.
NaN IE NaN result and invalid operation exception.
HUGEVAL IE oo result and division-by-zero exception.
SunOS 5.11 Last change: 23 Sep 1997 7
Mathematical Library Functions matherr(3M)
XTLOS The value XTLOS is defined in .
ANSI/ISO-C STANDARD CONFORMANCE
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 EROR HANDLING PROCEDURES (compile with cc -Xc)
SunOS 5.11 Last change: 23 Sep 1997 8
Mathematical Library Functions matherr(3M)
type DOMAIN SING OVERFLOW UNDERFLOW
errno EDOM EDOM ERANGE ERANGE
ACOS, ASIN(x > 1): 0.0 - - -
ATAN2(0,0): 0.0 - - -
EXP: - - ]HUGEVAL 0.0
FMOD(x,0): NaN - - -
LOG, LOG10:
(x < 0) -HUGEVAL - - -
(x = 0) - -HUGEVAL - -
POW:
usual cases - - ]HUGEVAL ]0.0
(x < 0) ** (y not an integer) 0.0 - - -
0 ** (y < 0) -HUGEVAL - - -
SQRT(x < 0): 0.0 - - -
ABREVIATIONS
NaN IE NaN result and invalid operation exception.
HUGEVAL IE oo result and division-by-zero.
EXAMPLES
Example 1 Example of matherr() function
#include
#include
#include
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 */
} /* FALTHRU */
case SING:
/* all other domain or sing exceptions, print message and */
/* abort */
SunOS 5.11 Last change: 23 Sep 1997 9
Mathematical Library Functions matherr(3M)
fprintf(stderr, "domain exception in %s\n", x->name);
abort( );
break;
}
return (0); /* all other exceptions, execute default procedure */
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level MT-Safe
SEE ALSO
attributes(5), standards(5)
SunOS 5.11 Last change: 23 Sep 1997 10
|
