MATHERR(3m,L) AIX Technical Reference MATHERR(3m,L) ------------------------------------------------------------------------------- matherr PURPOSE Performs an action when a math subroutine encounters an error. LIBRARY Math Library (libm.a) SYNTAX #include int matherr (excp) struct exception *excp; DESCRIPTION If matherr error handling is in effect, then the math library subroutines call matherr when an error is detected. See "cbrt, exp, expm1, log, log10, log1p, pow, sqrt" and "sin, cos, tan, asin, acos, atan, atan2" about alternative error handling available for these subroutines. You can override the default error-handling actions by supplying a subroutine of your own in place of the matherr subroutine supplied in the math library. To do this, include in your program a subroutine named matherr that takes one parameter: a pointer to an exception structure. The exception structure is defined in the math.h header file and it contains the following members: int type; char *name; double arg1, arg2, retval; The structure member named type describes the type of error that occurred. Its value is one of the following constants: DOMAIN Domain error SING Singularity OVERFLOW Overflow UNDERFLOW Underflow TLOSS Total loss of significance PLOSS Partial loss of significance The name member points to a string containing the name of the subroutine that encountered the error. The members arg1 and arg2 contain the parameters that were passed to the subroutine. The retval member is the value that the math subroutine returns. All of the math subroutines that call matherr do so in ways similar to this: Processed November 7, 1990 MATHERR(3m,L) 1 MATHERR(3m,L) AIX Technical Reference MATHERR(3m,L) /* ** Set up the exception structure */ exc.type = DOMAIN; /* Type of error */ exc.name = "pow"; /* Name of subroutine */ exc.arg1 = x; /* Arguments to pow(x,y) */ exc.arg2 = y; if (matherr(&exc) == 0) { /* ** matherr returned 0, so perform the ** default error-handling procedures */ fprintf(stderr, "pow: DOMAIN error\n"); exc.retval = 0; errno = EDOM; } return (exc.retval); Studying this sample shows that the return value from the matherr subroutine controls whether or not the math subroutine performs its default error-handling procedures. If matherr returns 0, then the default procedures are performed. Note in particular that if you want to specify the value to be returned by the math subroutine, then your matherr subroutine must set excp"->"retval and return a nonzero value. If you do not supply your own matherr subroutine, then the matherr subroutine supplied in the math library is linked into your program. This subroutine does nothing except return the value 0. Because it returns 0, the calling math subroutine then performs its default error-handling procedures. The default procedures are mentioned in the discussion of each math subroutine. The math library subroutines atan, ceil, erf, erfc, fabs, floor, fmod, and tanh do not generate any of the error types listed on page 1 and therefore do not call matherr. The following table shows the default error-handling procedures for the remaining math library subroutines: +-----------------------------------------------------------------------------+ |Figure 1 (Page 1 of 3). Default Error-Handling Procedures | +------+---------+---------+----------+-----------+---------+-----------------+ | | DOMAIN | SING | OVERFLOW | UNDERFLOW | TLOSS | PLOSS | +------+---------+---------+----------+-----------+---------+-----------------+ |acos | M,0,D(1)| - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |acosh | M,H,D(10| - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |asin | M,0,D(1)| - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ Processed November 7, 1990 MATHERR(3m,L) 2 MATHERR(3m,L) AIX Technical Reference MATHERR(3m,L) +-----------------------------------------------------------------------------+ |Figure 1 (Page 2 of 3). Default Error-Handling Procedures | +------+---------+---------+----------+-----------+---------+-----------------+ | | DOMAIN | SING | OVERFLOW | UNDERFLOW | TLOSS | PLOSS | +------+---------+---------+----------+-----------+---------+-----------------+ |asinh | - | - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |atan2 | M,0,D(2)| - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |atanh | M,H,D(11| - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |cabs | - | - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |cbrt | - | - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |cos | - | - | - | - | M,0,R | *,R | +------+---------+---------+----------+-----------+---------+-----------------+ |cosh | - | - | H,R | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |exp | - | - | H,R | 0,R | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |expml | - | - | H,R | 0,R | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |gamma | - | M,H,D(3)| H,R | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |hypot | - | - | H,R | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |j0 | - | - | - | 0,R | M,0,R | - | +------+---------+---------+----------+-----------+---------+-----------------+ |j1 | - | - | - | 0,R | M,0,R | - | +------+---------+---------+----------+-----------+---------+-----------------+ |jn | - | - | - | 0,R | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |lgamma| M,H,D(3)| - | M,H,R | M,H,R | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |log | M,-H,D(4| M,-H,R(5| - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |log10 | M,-H,D(4| M,-H,R(5| - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |loglp | M,+/-H,D|1-) | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |pow | M,0,D(6)| - | +/-H,R | 0,R | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |sin | - | - | - | - | M,0,R | *,R | +------+---------+---------+----------+-----------+---------+-----------------+ |sinh | - | - | +/-H,R | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |sqrt | M,0,D(7)| - | - | - | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ |tan | - | - | +/-H,R | - | M,0,R | *,R | +------+---------+---------+----------+-----------+---------+-----------------+ Processed November 7, 1990 MATHERR(3m,L) 3 MATHERR(3m,L) AIX Technical Reference MATHERR(3m,L) +-----------------------------------------------------------------------------+ |Figure 1 (Page 3 of 3). Default Error-Handling Procedures | +------+---------+---------+----------+-----------+---------+-----------------+ | | DOMAIN | SING | OVERFLOW | UNDERFLOW | TLOSS | PLOSS | +------+---------+---------+----------+-----------+---------+-----------------+ |y0 | M,-H,D(8| - | -H,R(9) | 0,R | M,0,R | - | +------+---------+---------+----------+-----------+---------+-----------------+ |y1 | M,-H,D(8| - | - | 0,R | M,0,R | - | +------+---------+---------+----------+-----------+---------+-----------------+ |yn | M,-H,D(8| - | -H,R(9) | 0,R | - | - | +------+---------+---------+----------+-----------+---------+-----------------+ The following abbreviations are used in the table: * As much as possible of the value is returned. 0 0 is returned. H HUGE is returned. -H -HUGE is returned. +/-H HUGE or -HUGE is returned. M A message is written to stdout. D errno is set to EDOM. R errno is set to ERANGE. Notes: (1) Caused by passing acos or asin a value larger than 1.0. (2) Caused by trying to calculate atan2(0, 0). (3) Caused by passing gamma or lgamma a nonpositive integer. (4) Caused by passing log or log10 a negative value. (5) Caused by trying to calculate log(0) or log10(0). (6) Caused by trying to raise a negative number to a noninteger power or 0 to a nonpositive power. (7) Caused by passing sqrt a negative value. (8) Caused by passing y0, y1, or yn a nonpositive value. Processed November 7, 1990 MATHERR(3m,L) 4 MATHERR(3m,L) AIX Technical Reference MATHERR(3m,L) (9) Caused by passing y0 a very small positive value. (10) Caused by passing acosh a value smaller than 1.0. (11) Caused by passing atanh a value whose absolute value is greater than or equal to 1.0. (12) Caused by passing loglp a value which is less than or equal to -1.0. EXAMPLES The following subroutine suggests the kinds of actions that a user-supplied matherr subroutine might perform. It is not the matherr subroutine that is provided in the math library. The supplied matherr subroutine merely returns 0. int matherr(x) register struct exception *x; { switch (x->type) { case DOMAIN: case SING: /* Display message and abort */ fprintf(stderr, "domain error in %s\n", x->name); abort(); case OVERFLOW: if (strcmp("exp", x->name) == 0) { /* If exp, display message & return the argument */ fprintf(stderr, "exp of %f\n", x->arg1); x->retval = x->arg1; } else if (strcmp("sinh", x->name) == 0) { /* If sinh, set errno, return 0 */ errno = ERANGE; x->retval = 0; } else /* Otherwise, return HUGE */ x->retval = HUGE; break; case UNDERFLOW: return (0); /* Perform the default procedures */ Processed November 7, 1990 MATHERR(3m,L) 5 MATHERR(3m,L) AIX Technical Reference MATHERR(3m,L) case TLOSS: case PLOSS: /* Display message and return 0 */ fprintf(stderr, "loss of significance in %s\n", x->name); x->retval = 0; break; } /* switch */ return (1); /* Do NOT perform the default procedures */ } /* matherr */ RELATED INFORMATION In this book: "math.h." Processed November 7, 1990 MATHERR(3m,L) 6