'\"! tbl | mmdoc
'\"macro stdmacro
.if n .pH g3m.matherr @(#)matherr	40.9 of 10/27/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} matherr 3M "Math Libraries" "\&"
.if \nX=1 .ds x} matherr 3M "Math Libraries"
.if \nX=2 .ds x} matherr 3M "" "\&"
.if \nX=3 .ds x} matherr "" "" "\&"
.TH \*(x}
.SH NAME
\f4matherr\f1 \- error-handling function
.SH SYNOPSIS
\f4cc\f1
[\f2flag\fP \|.\|.\|.] \f2file\fP \|.\|.\|.
\f4\-lm\f1
[\f2library\fP \|.\|.\|.]
.PP
\f4#include <math.h>\f1
.PP
\f4int matherr (struct exception \(**x);\f1
.SH DESCRIPTION
\f4matherr\fP
is invoked by functions in the math libraries when
errors are detected.  Note that
\f4matherr\fP
is not invoked when the \f4\-Xc\f1 compilation option is used.
Users may define their own procedures for handling errors,
by including a function named
\f4matherr\fP
in their programs.
\f4matherr\fP
must be of the form described above.
When an error occurs,
a pointer to the exception structure
.I x\^
will be passed to the user-supplied
\f4matherr\fP
function.
This structure, which is defined in the
\f4math.h\f1 header file, is as follows:
.RS
.PP
.ft 4
.nf
struct exception {
	int type;
	char \(**name;
	double arg1, arg2, retval;
};
.fi
.ft 1
.RE
.PP
The element
\f4type\fP
is an integer describing the type of error that has occurred, from the
following list of constants (defined in the header file):
.RS
.PP
.nf
.ta 1.25i
\f4DOMAIN\fP	argument domain error
\f4SING\fP	argument singularity
\f4OVERFLOW\fP	overflow range error
\f4UNDERFLOW\fP 	underflow range error
\f4TLOSS\fP	total loss of significance
\f4PLOSS\fP	partial loss of significance
.DT
.fi
.RE
.PP
The element
\f4name\fP
points to a string containing
the name of the function that incurred the error.
The variables
\f4arg1\fP
and
\f4arg2\fP
are the arguments with which the function was invoked.
\f4retval\fP
is set to the default value that will be returned by the function
unless the user's
\f4matherr\fP
sets it to a different value.
.PP
If the user's
\f4matherr\fP
function returns non-zero,
no error message will be printed,
and
\f4errno\fP
will not be set.
.PP
If
\f4matherr\fP
is not supplied by the user,
the default error-handling procedures, described with
the math functions involved, will be invoked upon error.
These procedures are also summarized in the table below.
In every case,
\f4errno\fP
is set to
\f4EDOM\fP
or
\f4ERANGE\fP
and the program continues.
.bp
.in 0
.vs +1
.TS
expand box ;
c s s s s s s
c | c s s s s s
cf4 | cf4 | cf4 | cf4 | cf4 | cf4 | cf4
cf4 | cf4 | cf4 | cf4 | cf4 | cf4 | cf4
l | c | c | c | c | c | c .
Default Error Handling Procedures
_
	Types of Errors
_
type	DOMAIN	SING	OVERFLOW 	UNDERFLOW 	TLOSS 	PLOSS 
_
errno	EDOM	EDOM	ERANGE	ERANGE	ERANGE	ERANGE
_
\s-2\s-1BESSEL\s+1:	\-	\-	\-	\-	M, 0	\-\s+2
\s-2y0, y1, yn (arg \(<= 0)	M, \-H 	\-	\-	\-	\-	\-\s+2
_
\s-2\s-1EXP, EXPF\s+1:	\-	\-	H	0	\-	\-\s+2
_
\s-2\s-1LOG, LOG10\s+1:\s+2
\s-2\s-1LOGF, LOG10F\s+1:\s+2
\s-2 (arg < 0)	M, \-H	\-	\-	\-	\-	\-\s+2
\s-2 (arg = 0)	M, \-H	\- 	\-	\-	\-	\-\s+2
_
\s-2\s-1POW, POWF\s+1:	\-	\-	\(+-H	0	\-	\-\s+2
\s-2neg \(**\(** non-int	M, 0 	\-	\-	\-	\-	\-\s+2
\s-2  0 \(**\(** non-pos	M, 0	\-	\-	\-	\-	\-\s+2
_
\s-2\s-1SQRT, SQRTF\s+1:	M, 0	\-	\-	\-	\-	\-\s+2
_
\s-2\s-1FMOD, FMODF\s+1:\s+2
\s-2 (arg2 = 0)	M, X	\-	\-	\-	\-	\-\s+2
_
\s-2\s-1REMAINDER\s+1:\s+2
\s-2 (arg2 = 0)	M, N	\-	\-	\-	\-	\-\s+2
_
\s-2\s-1GAMMA, LGAMMA\s+1:	\-	M, H	H	\-	\-	\-\s+2
_
\s-2\s-1HYPOT\s+1:	\-	\-	H	\-	\-	\-\s+2
_
\s-2\s-1SINH, SINHF\s+1:	\-	\-	\(+-H	\-	\-	\-\s+2
_
\s-2\s-1COSH, COSHF\s+1:	\-	\-	H	\-	\-	\-\s+2
_
\s-2\s-1ASIN, ACOS, ATAN2\s+1:\s+2	
\s-2\s-1ASINF, ACOSF, ATAN2F\s+1:	M, 0	\-	\-	\-	\-	\-\s+2
_
\s-2\s-1ACOSH\s+1:	M, N	\-	\-	\-	\-	\-\s+2
_
\s-2\s-1ATANH\s+1:\s+2
\s-2 (|\h'.30'arg| > 1)	M, N	\-	\-	\-	\-	\-\s+2
\s-2 (|\h'.30'arg| = 1)	\-	M, N 	\-	\-	\-	\-\s+2
.TE
.in 0
.TS
box expand;
c s
c l .
Abbreviations
M	Message is printed (not with the \f4\-Xa\fP or \f4\-Xc\fP options).
H	\f4HUGE\fP is returned (\f4HUGE_VAL\fP with the \f4\-Xa\fP or \f4\-Xc\fP options).
\-H	\f4\-HUGE\fP is returned (\f4\-HUGE_VAL\fP with the \f4\-Xa\fP or \f4\-Xc\fP options).
\(+-H	\f4HUGE\fP or \f4\-HUGE\fP is returned.
	(\f4HUGE_VAL\fP or \f4\-HUGE_VAL\fP with the \f4\-Xa\fP or \f4\-Xc\fP options).
0	0 is returned.
X	\f2arg1\f1 is returned.
N	\f4NaN\f1 is returned.
.TE
.vs -1
.SH EXAMPLE
.ft4
.nf
.ta .5i 1.0i 1.5i 2.0i
#include <math.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

int
matherr(register struct exception \(**x);
{
	switch (x\->type) {
	case DOMAIN:
		/\(** change sqrt to return sqrt(\-arg1), not 0 \(**/
		if (!strcmp(x\->name, "sqrt")) {
			x\->retval = sqrt(\-x\->arg1);
			return (0); /\(** print message and set errno \(**/
		}
	case SING:
		/\(** all other domain or sing errors, print message \(**/
		/\(** and abort \(**/
		fprintf(stderr, "domain error in %s\en", x\->name);
		abort( );
	case PLOSS:
		/\(** print detailed error message \(**/
		fprintf(stderr, "loss of significance in %s(%g)=%g\en",
			x\->name, x\->arg1, x\->retval);
		return (1); /\(** take no other action \(**/
	}
	return (0); /\(** all other errors, execute default procedure \(**/
}
.SH NOTES
Error handling in \f4\-Xa\f1 and \f4\-Xt\f1 modes [see \f4cc\f1(1)]
is described more completely on individual math library pages.
.\"	@(#)matherr.3m	6.3 of 10/20/83
.Ee
