_matherr, _matherrl

Go Up to math.h Index

Header File

math.h

Category

Diagnostic Routines, Math Routines

Prototype

int _matherr(struct _exception *e);

int _matherrl(struct _exceptionl *e);

Description

User-modifiable math error handler.

_matherr is called when an error is generated by the math library.

_matherrl is the long double version; it is called when an error is generated by the long double math functions.

_matherr and _matherrl each serve as a user hook (a function that can be customized by the user) that you can replace by writing your own math error-handling routine.

_matherr and _matherrl are useful for information on trapping domain and range errors caused by the math functions. They do not trap floating-point exceptions, such as division by zero. See signal for information on trapping such errors.

You can define your own _matherr or _matherrl routine to be a custom error handler (such as one that catches and resolves certain types of errors); this customized function overrides the default version in the C library. The customized _matherr or _matherrl should return 0 if it fails to resolve the error, or nonzero if the error is resolved. When _matherr or _matherrl return nonzero, no error message is printed and the global variable errno is not changed.

Here are the _exception and _exceptionl structures (defined in math.h):

struct _exception {

int type;

char *name;

double arg1, arg2, retval;

};

struct _exceptionl {

int type;

char *name;

long double arg1, arg2, retval;

};

The members of the _exception and _exceptionl structures are shown in the following table:

type	The type of mathematical error that occurred; an enum type defined in the typedef _mexcep (see definition after this list).
name	A pointer to a null-terminated string holding the name of the math library function that resulted in an error.
arg1, arg2	The arguments (passed to the function that name points to) caused the error; if only one argument was passed to the function, it is stored in arg1.
retval	The default return value for _matherr (or _matherrl); you can modify this value.

The typedef _mexcep, also defined in math.h, enumerates the following symbolic constants representing possible mathematical errors:

DOMAIN	Argument was not in domain of function, such as log(-1).
SING	Argument would result in a singularity, such as pow(0, -2).
OVERFLOW	Argument would produce a function result greater than DBL_MAX (or LDBL_MAX), such as exp(1000).
UNDERFLOW	Argument would produce a function result less than DBL_MIN (or LDBL_MIN), such as exp(-1000).
TLOSS	Argument would produce function result with total loss of significant digits, such as sin(10e70).

The macros DBL_MAX, DBL_MIN, LDBL_MAX, and LDBL_MIN are defined in float.h

The source code to the default _matherr and _matherrl is on the C++Builder distribution disks.

The UNIX-style _matherr and _matherrl default behavior (printing a message and terminating) is not ANSI compatible. If you want a UNIX-style version of these routines, use MATHERR.C and MATHERRL.C provided on the C++Builder distribution disks.

Example

#include <math.h>
#include <string.h>
#include <stdio.h>
int _matherr (struct _exception *a)
{
  if (a->type == DOMAIN)
    if (!strcmp(a->name,"sqrt")) {
      a->retval = sqrt (-(a->arg1));
    return 1;
    }
  return 0;
}
int main(void)
{
  double x = -2.0, y;
  y = sqrt(x);
  printf("_Matherr corrected value: %lf\n",y);
  return 0;
}