matherr(3M)
NAME
matherr - math library exception-handling function
SYNOPSIS
#include <math.h>
int matherr(struct exception *exc);
DESCRIPTION
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 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 <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 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
TLOSS total loss of significance
PLOSS partial loss of significance
Both TLOSS and PLOSS 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, 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 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 standard 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.
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 because
it can 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), NaN - - - -
ATANH(|x| > 1):
_____________________________________________________________________________________________________
ATAN2(0,0): Md, 0.0 - - - -
_____________________________________________________________________________________________________
COSH, SINH: - - _HUGE - -
_____________________________________________________________________________________________________
EXP: - - +HUGE 0.0 -
_____________________________________________________________________________________________________
FMOD(x,0): x - - - -
_____________________________________________________________________________________________________
HYPOT: - - +HUGE - -
_____________________________________________________________________________________________________
J0, J1, JN(|x| > - - - - Mt, 0.0
X_TLOSS):
_____________________________________________________________________________________________________
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 Md, 0.0 - - - -
integer)
_____________________________________________________________________________________________________
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 oo 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 can return results that differ
from those in this table.
X/OPEN COMMON APPLICATION ENVIRONMENT (CAE) SPECIFICATIONS CON-
FORMANCE
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 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| > - - - - {0.0}
X_TLOSS):
________________________________________________________________________________________
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 0.0 - - - -
integer)
________________________________________________________________________________________
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 oo result and division-by-zero exception.
X_TLOSS
The value X_TLOSS is defined in <values.h>.
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 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 0.0 - - -
an integer)
______________________________________________________________________________
0 ** (y < 0) -HUGE_VAL - - -
______________________________________________________________________________
SQRT(x < 0): 0.0 - - -
______________________________________________________________________________
| | | | | |
| | | | | |
ABBREVIATIONS | | | | |
|NaN IEEE NaN result|and invalid operation exception. | |
| | | | | |
|HUGE_VAL | | | | |
| IEEE oo result and division-by-zero. | | |
| | | | | |
EXAMPLES | | | | |
|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 */
}
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
attributes(5), standards(5)
Man(1) output converted with
man2html