./_Man_SunOS_4.1.3_html/html3/matherr.3m.html

Manual page for MATHERR(3M)

matherr - math library exception-handling function

SYNOPSIS

#include <math.h>

int matherr(exc) struct exception *exc;

DESCRIPTION

The SVID (System V Interface Definition) 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. matherr() 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 element type 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

The element name points to a string containing the name of the function that incurred the exception. The elements arg1 and arg2 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.

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==fp_invalid: An IEEE NaN is usually returned, errno is set to EDOM, and a message is printed on standard error. pow(0.0,0.0) and atan2(0.0,0.0) return numerical default results but set errno and print the message.
SING==fp_division: An IEEE \(if of appropriate sign is returned, errno is set to EDOM, and a message is printed on standard error.
OVERFLOW==fp_overflow: In the default rounding direction, an IEEE \(if of appropriate sign is returned. In optional rounding directions, ±MAXDOUBLE, the largest finite double-precision number, is sometimes returned instead of ±\(if. errno is set to ERANGE.
UNDERFLOW==fp_underflow: An appropriately-signed zero, subnormal number, or smallest normalized number is returned, and errno is set to ERANGE.

The facilities provided by matherr() are not available in situations such as compiling on a Sun-3 system with /usr/lib/f68881/libm.il or /usr/lib/ffpa/libm.il, in which case some libm functions are converted to atomic hardware operations. In these cases setting errno and calling matherr() are not worth the adverse performance impact, but regular ANSI/IEEE Std 754-1985 exception handling remains available. In any case errno is not a reliable error indicator in that it may be unexpectedly set by a function in a handler for an asynchronous signal.

+------------------------------------------------------------------------------------------------------+
|                                  DEFAULT ERROR HANDLING PROCEDURES                                   |
|                                                                                                      |
+------------------------------------------------------------------------------------------------------+
|                                                           Types of Errors                            |
+------------------------------+-------------------+------------------+---------------+----------------+
|        <math.h> type         |      DOMAIN       |       SING       |   OVERFLOW    |   UNDERFLOW    |
+------------------------------+-------------------+------------------+---------------+----------------+
|errno                         |       EDOM        |       EDOM       |    ERANGE     |     ERANGE     |
+------------------------------+-------------------+------------------+---------------+----------------+
|IEEE Exception                | Invalid Operation | Division by Zero |   Overflow    |   Underflow    |
+------------------------------+-------------------+------------------+---------------+----------------+
|<floatingpoint.h> type        |    fp_invalid     |   fp_division    |  fp_overflow  |  fp_underflow  |
|                              |                   |                  |               |                |
+------------------------------+-------------------+------------------+---------------+----------------+
|ACOS, ASIN:                   |      M, NaN       |        -         |       -       |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+
|ATAN2(0,0):                   |   M, ą0.0 or ą    |        -         |       -       |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+
|BESSEL:                       |                   |                  |               |                |
|y0, y1, yn (x < 0)            |      M, NaN       |        -         |       -       |       -        |
|y0, y1, yn (x = 0)            |         -         |       M, -       |       -       |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+
|COSH, SINH:                   |         -         |        -         | IEEE Overflow |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+
|EXP:                          |         -         |        -         | IEEE Overflow | IEEE Underflow |
+------------------------------+-------------------+------------------+---------------+----------------+
|HYPOT:                        |         -         |        -         | IEEE Overflow |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+
|LGAMMA:                       |         -         |       M, +       | IEEE Overflow |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+
|LOG, LOG10:                   |                   |                  |               |                |
| (x < 0)                      |      M, NaN       |        -         |       -       |       -        |
| (x = 0)                      |         -         |       M, -       |       -       |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+
|POW:                          |                   |                  |               |                |
|usual cases                   |         -         |        -         | IEEE Overflow | IEEE Underflow |
|(x < 0) ** (y not an integer) |      M, NaN       |        -         |       -       |       -        |
|  0 ** 0                      |      M, 1.0       |        -         |       -       |       -        |
|  0 ** (y < 0)                |         -         |       M, ą       |       -       |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+
|SQRT:                         |      M, NaN       |        -         |       -       |       -        |
+------------------------------+-------------------+------------------+---------------+----------------+

+--------------------------------------------------------------------+
|                           ABBREVIATIONS                            |
|                                                                    |
+--------------------------------------------------------------------+
|                                                                    |
|      M          Message is printed (EDOM exception).               |
|     NaN         IEEE NaN result and invalid operation exception.   |
|                 IEEE  result and division-by-zero exception.       |
|IEEE Overflow    IEEE Overflow result and exception.                |
|IEEE Underflow   IEEE Underflow result and exception.               |
|                 Closest machine-representable approximation to pi. |
+--------------------------------------------------------------------+

The interaction of IEEE arithmetic and matherr() is not defined when executing under IEEE rounding modes other than the default round to nearest: matherr() may not be called on overflow or underflow, and the Sun-provided matherr() may return results that differ from those in this table.

EXAMPLE

#include <math.h>
int
matherr(x)
register 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 */
	} /* fall through */
	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 */
}