unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

MATHERR(3M)                                                        MATHERR(3M)



NAME
       matherr - math library exception-handling function

SYNOPSIS
       #include <&lt;math.h>&gt;

       int matherr(exc)
       struct exception *exc;

DESCRIPTION
       The  SVID  (System  V Interface Definition) 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.  matherr() 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 <&lt;math.h>&gt; 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  exception  that
       has  occurred,  from  the  following  list of constants (defined in the
       header file):

              DOMAIN              argument domain exception
              SING                argument singularity
              OVERFLOW            overflow range exception
              UNDERFLOW           underflow range exception

       The element name points to a string containing the name of the function
       that  incurred the exception.  The elements arg1 and arg2 are the argu-
       ments 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 will not be set.

       If  matherr()  is  not supplied by the user, the default matherr excep-
       tion-handling mechanisms,  summarized  in  the  table  below,  will  be
       invoked upon exception:

       DOMAIN==fp_invalid
              An  IEEE  NaN  is  usually returned, errno is set to EDOM, and a
              message  is  printed  on  standard  error.    pow(0.0,0.0)   and
              atan2(0.0,0.0)  return  numerical  default results but set errno
              and print the message.

       SING==fp_division
              An IEEE  of appropriate sign is returned, errno is set to  EDOM,
              and a message is printed on standard error.

       OVERFLOW==fp_overflow
              In  the default rounding direction, an IEEE  of appropriate sign
              is returned.  In optional rounding directions, +-MAXDOUBLE,  the
              largest  finite  double-precision  number, is sometimes returned
              instead of +-.  errno is set to ERANGE.

       UNDERFLOW==fp_underflow
              An appropriately-signed zero, subnormal number, or smallest nor-
              malized number is returned, and errno is set to ERANGE.

       The  facilities  provided  by matherr() are not available in situations
       such as compiling on a Sun-3  system  with  /usr/lib/f68881/libm.il  or
       /usr/lib/ffpa/libm.il,  in which case some libm functions are converted
       to atomic hardware operations.  In these cases setting errno and  call-
       ing matherr() are not worth the adverse performance impact, but regular
       ANSI/IEEE Std 754-1985 exception handling remains  available.   In  any
       case  errno  is  not a reliable error indicator in that it may be unex-
       pectedly set by a function in a handler for an asynchronous signal.

       DEFAULT ERROR HANDLING PROCEDURES
                                    Types of Errors
       <math.h> type                DOMAIN     SING        OVERFLOW      UNDERFLOW
       errno                        EDOM       EDOM        ERANGE        ERANGE
       IEEE Exception               Invalid    Division    Overflow      Underflow
                                    Operation  by Zero
       <floatingpoint.h> type       fp_invalid fp_division fp_overflow   fp_underflow
       ACOS, ASIN:                  M, NaN     -           -             -
       ATAN2(0,0):                  M, +-0.0   -           -             -
                                    or +-
       BESSEL:
       y0, y1, yn (x < 0)           M, NaN     -           -             -
       y0, y1, yn (x = 0)           -          M, -        -             -
       COSH, SINH:                  -          -           IEEE Overflow -
       EXP:                         -          -           IEEE Overflow IEEE Underflow
       HYPOT:                       -          -           IEEE Overflow -
       LGAMMA:                      -          M, +        IEEE Overflow -
       LOG, LOG10:
       (x < 0)                      M, NaN     -           -             -
       (x = 0)                      -          M, -        -             -
       POW:
       usual cases                  -          -           IEEE Overflow IEEE Underflow
       (x < 0) ** (y not an integer)           M, NaN      -             --
       0 ** 0                       M, 1.0     -           -             -
       0 ** (y < 0)                 -          M, +-       -             -
       SQRT:                        M, NaN     -           -             -

       center box ; cB s c l .  ABBREVIATIONS

       =

       M                            Message  is  printed   (EDOM   exception).
       NaN                          IEEE  NaN  result  and  invalid  operation
       exception.                               IEEE  result and  division-by-
       zero  exception.  IEEE Overflow                IEEE Overflow result and
       exception.   IEEE  Underflow               IEEE  Underflow  result  and
       exception.                                Closest machine-representable
       approximation to pi.

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

EXAMPLE
       #include <&lt;math.h>&gt;
       int
       matherr(x)
       register struct exception *x;
       {
            switch (x->&gt;type) {
            case
                 DOMAIN:
                 /* change sqrt to return sqrt(-arg1), not NaN */
                 if (!strcmp(x->&gt;name, "sqrt")) {
                      x->&gt;retval = sqrt(-x->&gt;arg1);
                      return (0); /* print message and set errno */
            } /* fall through */
            case
                 SING:
                 /* all other domain or sing exceptions, print message and abort */
                 fprintf(stderr, "domain exception in %s\n", x->&gt;name);
                 abort( );
                 break;
            }
            return (0); /* all other exceptions, execute default procedure */
       }



                                16 August 1989                     MATHERR(3M)