NAME

matherr() − error-handling function

SYNOPSIS

#include <math.h>

int matherr(struct exception *x)
{
    /* your math error handling here */
}

DESCRIPTION

matherr() is invoked by functions in the Math Library when errors are detected.  Programmers can define their own procedures for handling errors by including a function named matherr() in their programs.  matherr() must be of the form described above.  When an error occurs, a pointer to the exception structure x is 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 error that has occurred, from the following list of constants (defined in the header file):

DOMAIN argument domain error

SING argument singularity

OVERFLOW overflow range error

UNDERFLOW underflow range error

TLOSS total loss of significance

PLOSS partial loss of significance

The element name points to a string containing the name of the function that incurred the error.  The variables 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 there is only one argument, arg1 is set to it, and arg2 is undefined. 

If the user’s matherr() function returns non-zero, no error message is printed, and errno is not set. 

If matherr() is not supplied by the user, the default error-handling procedures (described with the math functions involved) are invoked upon error.  These procedures are also summarized in the table below.  In every case, errno is set to EDOM or ERANGE and the program continues. 

When matherr() is called from a float type math function (for example, expf() or logf()), the argument(s) and default return value (arg1, arg2, and retval) are converted to double.  If an argument is a NaN, it is converted to a double NaN, without trapping, even if it is a signaling NaN.  If a user-supplied matherr() function modifies retval, the value is converted to float when matherr() returns.  If that conversion fails, then a signal is generated.  Therefore, it is the responsibility of the user-supplied matherr() to select values for retval that can be successfully converted to float. 

DEPENDENCIES

/lib/libM.a

In /lib/libM.a, matherr() has been renamed to _matherr() and no error messages are printed to the standard error output.  _matherr() is provided in /lib/libM.a in order to assist in migrating programs from libm.a to libM.a and is not a part of XPG3, ANSI C, or POSIX. 

EXAMPLES

#include <math.h>
int
matherr(x)
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 */
        }
        else if (!strcmp(x->name, "sqrtf")) {
            x->retval = sqrtf(-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\n", x->name);
        abort( );
    case PLOSS:
        /* print detailed error message */
        fprintf(stderr, "loss of significance in %s(%g) = %g\n",
            x->name, x−>arg1, x−>retval);
        return (1); /* take no other action */
    }
    return (0); /* all other errors, execute default procedure */
}

DEFAULTS

STANDARDS CONFORMANCE

matherr() in libm.a: SVID2, XPG2, XPG3
matherr() in libM.a: XPG3

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992