NAME

matherr - error-handling function

SYNOPSIS

cc [flag ...] file ...  -lm [library ...]

#include <math.h>

int matherr (struct exception *x);

DESCRIPTION

matherr is invoked by functions in the math  libraries  when
errors  are detected.  Note that matherr is not invoked when
the -Xc compilation option is used.  Users may 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  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  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 the user's matherr function returns  non-zero,  no  error
message will be printed, and errno will not be set.

If matherr is not supplied by the user, the  default  error-
handling  procedures,  described  with  the  math  functions
involved, will be 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.

___________________________________________________________________________________
|________________________Default_Error_Handling_Procedures________________________|
|                     |                       Types of Errors                     |
|_____________________|___________________________________________________________|
|_____________________|________|_______|___________|____________|________|________|
|        errno        |   EDOM |  EDOM |   ERANGE  |    ERANGE  |  ERANGE|  ERANGE|
|_____________________|________|_______|___________|____________|________|________|
|BESSEL:              |    -   |    -  |      -    |      -     |   M, 0 |    -   |
|y0,_y1,_yn_(arg___0)_|__M,_-H_|____-__|______-____|______-_____|____-___|____-___|
|EXP, EXPF:           |    -   |    -  |      H    |      0     |    -   |    -   |
|_____________________|________|_______|___________|____________|________|________|
|LOG, LOG10:          |        |       |           |            |        |        |
|LOGF, LOG10F:        |        |       |           |            |        |        |
| (arg < 0)           |  M, -H |    -  |      -    |      -     |    -   |    -   |
|_(arg_=_0)___________|__M,_-H_|___-___|______-____|______-_____|____-___|____-___|
|POW, POWF:           |    -   |    -  |     +H    |      0     |    -   |    -   |
|neg ** non-int       |  M, 0  |    -  |      -    |      -     |    -   |    -   |
|  0 ** non-pos       |   M, 0 |    -  |      -    |      -     |    -   |    -   |
|_____________________|________|_______|___________|____________|________|________|
|SQRT,_SQRTF:_________|___M,_0_|____-__|______-____|______-_____|____-___|____-___|
|FMOD, FMODF:         |        |       |           |            |        |        |
| (arg2 = 0)          |   M, X |    -  |      -    |      -     |    -   |    -   |
|_____________________|________|_______|___________|____________|________|________|
|REMAINDER:           |        |       |           |            |        |        |
|_(arg2_=_0)__________|___M,_N_|____-__|______-____|______-_____|____-___|____-___|
|GAMMA, LGAMMA:       |    -   |  M, H |      H    |      -     |    -   |    -   |
|_____________________|________|_______|___________|____________|________|________|
|HYPOT:_______________|____-___|____-__|______H____|______-_____|____-___|____-___|
|SINH, SINHF:         |    -   |    -  |     +H    |      -     |    -   |    -   |
|_____________________|________|_______|___________|____________|________|________|
|COSH,_COSHF:_________|____-___|____-__|______H____|______-_____|____-___|____-___|
|ASIN, ACOS, ATAN2:   |        |       |           |            |        |        |
|ASINF, ACOSF, ATAN2F:|   M, 0 |    -  |      -    |      -     |    -   |    -   |
|_____________________|________|_______|___________|____________|________|________|
|ACOSH:_______________|___M,_N_|____-__|______-____|______-_____|____-___|____-___|
|ATANH:               |        |       |           |            |        |        |
| (|arg| > 1)         |   M, N |    -  |      -    |      -     |    -   |    -   |
| (|arg| = 1)         |    -   |  M, N |      -    |      -     |    -   |    -   |
_________________________________________________________________________|________|
|                         Abbreviations                         |
|M    Message is printed (not with the -Xa or -Xc options).     |
|H    HUGE is returned (HUGE_VAL with the -Xa or -Xc options).  |
|-H   -HUGE is returned (-HUGE_VAL with the -Xa or -Xc options).|
|+H   HUGE or -HUGE is returned.                                |
|     (HUGE_VAL or -HUGE_VAL with the -Xa or -Xc options).      |
|0    0 is returned.                                            |
|X    arg1 is returned.                                         |
|N    NaN is returned.                                          |
|_______________________________________________________________|

EXAMPLE

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

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

int
matherr(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 */
          }
     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 */
}

NOTES

Error handling in -Xa and -Xt modes [see cc(1)] is described
more completely on individual math library pages.