te
Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
matherr - math library exception-handling function

#include <math.h>

int matherr(struct exception *exc);

The System V Interface Definition, Third Edition (SVID3) specifies that certain libm functions call matherr() when exceptions are detected. Users may define their own mechanisms for handling exceptions, by including a function named matherr() in their programs. The matherr() function is of the form described above. When an exception occurs, a pointer to the exception structure exc 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 type member is an integer describing the type of exception that has occurred, from the following list of constants (defined in the header file):

DOMAIN

SING

OVERFLOW

UNDERFLOW

TLOSS

PLOSS

Both TLOSS and PLOSS reflect limitations of particular algorithms for trigonometric functions that suffer abrupt declines in accuracy at definite boundaries. Since the implementation does not suffer such abrupt declines, PLOSS is never signaled. TLOSS is signaled for Bessel functions only to satisfy SVID3 requirements.

The name member points to a string containing the name of the function that incurred the exception. The arg1 and arg2 members 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 exception message will be printed and errno is not set.

When an application is built as a SVID3 conforming application (see standards(7)), if matherr() is not supplied by the user, the default matherr exception-handling mechanisms, summarized in the table below, are invoked upon exception:

DOMAIN

SING

OVERFLOW

UNDERFLOW

TLOSS

In general, errno is not a reliable error indicator because it can be unexpectedly set by a function in a handler for an asynchronous signal.

<math.h> type DOMAIN SING OVERFLOW UNDERFLOW TLOSS

errno EDOM EDOM ERANGE ERANGE ERANGE

IEEE Exception Invalid Operation Division by Zero Overflow Underflow -

fp_exception_type fp_invalid fp_division fp_overflow fp_underflow -

ACOS, ASIN\|(|x| > 1): Md, 0.0 - - - -

ACOSH\|(x < 1), ATANH\|(|x| > 1): NaN - - - -

ATAN2\|(0,0): Md, 0.0 - - - -

COSH, SINH: - - \(+-HUGE - -

EXP: - - +HUGE 0.0 -

FMOD\|(x,0): x - - - -

HYPOT: - - +HUGE - -

J0, J1, JN\|(|x| > X_TLOSS): - - - - Mt, 0.0

LGAMMA:

usual cases - - +HUGE - -

(x = 0 or -integer) - Ms, +HUGE - - -

LOG, LOG10:

(x < 0) Md, -HUGE - - - -

(x = 0) - Ms, -HUGE - - -

POW:

usual cases - - \(+-HUGE \(+-0.0 -

(x < 0) ** (y not an integer) Md, 0.0 - - - -

0 ** 0 Md, 0.0 - - - -

0 ** (y < 0) Md, 0.0 - - -

REMAINDER\|(x,0): NaN - - - -

SCALB: - - \(+-HUGE_VAL \(+-0.0 -

SQRT\|(x < 0): Md, 0.0 - - - -

Y0, Y1, YN:

(x < 0) Md, -HUGE - - - -

(x = 0) - Md, -HUGE - - -

(x > X_TLOSS) - - - - Mt, 0.0

Md

Ms

Mt

NaN

HUGE

HUGE_VAL

X_TLOSS

The interaction of IEEE arithmetic and matherr() is not defined when executing under IEEE rounding modes other than the default round to nearest: matherr() is not always called on overflow or underflow and can return results that differ from those in this table.

The X/Open System Interfaces and Headers (XSH) Issue 3 and later revisions of that specification no longer sanctions the use of the matherr interface. The following table summarizes the values returned in the exceptional cases. In general, XSH dictates that as long as one of the input argument(s) is a NaN, NaN is returned. In particular, pow(NaN,0) = NaN.

<math.h> type DOMAIN SING OVERFLOW UNDERFLOW TLOSS

errno EDOM EDOM ERANGE ERANGE ERANGE

ACOS, ASIN\|(|x| > 1): 0.0 - - - -

ATAN2\|(0,0): 0.0 - - - -

COSH, SINH: - - {\(+-HUGE_VAL} - -

EXP: - - {+HUGE_VAL} {0.0} -

FMOD\|(x,0): {NaN} - - - -

HYPOT: - - {+HUGE_VAL} - -

J0, J1, JN\|(|x| > X_TLOSS): - - - - {0.0}

LGAMMA:

usual cases - - {+HUGE_VAL} - -

(x = 0 or -integer) - +HUGE_VAL - - -

LOG, LOG10:

(x < 0) -HUGE_VAL - - - -

(x = 0) - -HUGE_VAL - - -

POW:

usual cases - - \(+-HUGE_VAL \(+-0.0 -

(x < 0) ** (y not an integer) 0.0 - - - -

0 ** 0 {1.0} - - - -

0 ** (y < 0) {-HUGE_VAL} - - - -

SQRT\|(x < 0): 0.0 - - - -

Y0, Y1, YN:

(x < 0) {-HUGE_VAL} - - - -

(x = 0) - {-HUGE_VAL} - - -

(x > X_TLOSS) - - - - 0.0

{...}

NaN

HUGE_VAL

X_TLOSS

The ANSI/ISO-C standard covers a small subset of the CAE specification.

The following table summarizes the values returned in the exceptional cases.

<math.h> type DOMAIN SING OVERFLOW UNDERFLOW

errno EDOM EDOM ERANGE ERANGE

ACOS, ASIN\|(|x| > 1): 0.0 - - -

ATAN2\|(0,0): 0.0 - - -

EXP: - - +HUGE_VAL 0.0

FMOD\|(x,0): NaN - - -

LOG, LOG10:

(x < 0) -HUGE_VAL - - -

(x = 0) - -HUGE_VAL - -

POW:

usual cases - - \(+-HUGE_VAL \(+-0.0

(x < 0) ** (y not an integer) 0.0 - - -

0 ** (y < 0) -HUGE_VAL - - -

SQRT\|(x < 0): 0.0 - - -

NaN

HUGE_VAL

Example 1 Example of matherr() function

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

int
matherr(struct exception *x) {
 switch (x->type) {
 case DOMAIN:
 /* change sqrt to return sqrt(-arg1), not NaN */
 if (!strcmp(x->name, "sqrt")) {
 x->retval = sqrt(-x->arg1);
 return (0); /* print message and set errno */
 } /* FALLTHRU */
 case SING:
 /* all other domain or sing exceptions, print message and */
 /* abort */
 fprintf(stderr, "domain exception in %s\en", x->name);
 abort( );
 break;
 }
 return (0); /* all other exceptions, execute default procedure */
 }

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

MT-Level MT-Safe

attributes (7), standards (7)