matherr()

display error messages for math library functions

Synopsis:

#include <math.h>
int matherr( struct exception *err_info );

Description:

The matherr() function is invoked each time an error is detected by functions in the math library. The default matherr() function supplied in the library returns zero, which causes:

• an error message to be displayed on stderr
• errno to be set with an appropriate error value.

An alternative version of this function can be provided, instead of the library version, in order that the error handling for mathematical errors can be handled by an application.

A program may contain a user-written version of matherr() to take any appropriate action when an error is detected. For example, the replacement function could do the following:

• When zero is returned, an error message is printed on stderr, and errno is set, as is the case with the default function.
• When a nonzero value is returned, the function doesn't print a message, or change errno. The value err_info->retval is used as the return value for the function in which the error was detected.

The matherr() function is passed a pointer to a structure of type struct exception, which contains information about the error that has been detected:

struct exception
{ int type;        /* type of error                */
  char *name;      /* name of function             */
  double arg1;     /* first argument to function   */
  double arg2;     /* second argument to function  */
  double retval;   /* default return value         */
};

The type field contains one of the following values:

DOMAIN

A domain error has occurred, such as sqrt(-1e0).

SING

A singularity will result, such as pow(0e0,-2).

OVERFLOW

An overflow will result, such as pow(10e0,100).

UNDERFLOW

An underflow will result, such as pow(10e0,-100).

TLOSS

Total loss of significance will result, such as exp(1000).

PLOSS

Partial loss of significance will result, such as sin(10e70).

The name field points to a string containing the name of the function that detected the error. The fields arg1 and arg2 (if required) give the values that caused the error. The field retval contains the value that will be returned by the function. This value may be changed by a user-supplied version of the matherr() function.

Returns:

Zero when an error message is to be printed, and a nonzero value otherwise.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <math.h>

/* Demonstrate an error routine in which negative */
/* arguments to "sqrt" are treated as positive    */

int main( void )
  {
    printf( "%e\n", sqrt( -5e0 ) );
    return( EXIT_SUCCESS );
  }

int matherr( struct exception *err )
  {
    if( strcmp( err->name, "sqrt" ) == 0 ) {
      if( err->type == DOMAIN ) {
        err->retval = sqrt( -(err->arg1) );
        return( 1 );
      } else
        return( 0 );
    } else
        return( 0 );
  }

Classification:

WATCOM

See also:

errno