_matherr(3M)

NAME

_matherr() − error-handling function (TO BE WITHDRAWN)

SYNOPSIS

#include <math.h>

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

DESCRIPTION

_matherr() is invoked by some 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 declared in the <math.h> header file and allocated on the stack by one of the math library internal routines, 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

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 in the man pages for the math functions) are invoked upon error, 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.

To use this function, link in the math library by specifying −lm on the compiler or linker command line.

The matherr() and _matherr() functions are obsolete and will not be supported at the next release of HP-UX. The matherr() function is not required by any version of XPG nor by ANSI C, and has not been part of any standard since SVID2. In the HP-UX math library, the SVID2 matherr() function has been renamed to _matherr(), and no error messages are printed to the standard error output. _matherr() is provided in libm.a in order to assist in supporting old programs. Executables that use the old matherr() or _matherr() will continue to run indefinitely, even on future releases of HP-UX.

However, if you intend to recompile or relink any of your current programs that use matherr() or _matherr() on a future release of HP−UX, you should be aware that any function called matherr() or _matherr() will no longer be called in case of library errors.

If you want to intercept math library calls that experience argument errors, you should consider writing wrapper routines that intervene between the original caller and the math library. Such a wrapper could check the value of errno after the math library function returns, and if appropriate, invoke your special error handler.

EXAMPLE

#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); /* set errno */
        }
        else if (!strcmp(x->name, "sqrtf")) {
            x->retval = sqrtf(-x->arg1);
            return (0); /* set errno */
        }
    case SING:
        /* all other domain or sing errors, print message and abort */
        fprintf(stderr, "domain error in %s\n", x->name);
        abort( );
    }
    return (0); /* all other errors, execute default procedure */
}

STANDARDS CONFORMANCE

matherr(): SVID2