matherr man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

matherr(3M)		Mathematical Library Functions		   matherr(3M)

NAME
       matherr - math library exception-handling function

SYNOPSIS
       #include <math.h>

       int matherr(struct exception *exc);

DESCRIPTION
       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-sup‐
       plied  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	    argument domain exception

       SING	    argument singularity

       OVERFLOW	    overflow range exception

       UNDERFLOW    underflow range exception

       TLOSS	    total loss of significance

       PLOSS	    partial loss of significance

       Both TLOSS and PLOSS reflect limitations of particular  algorithms  for
       trigonometric functions that suffer abrupt declines in accuracy at def‐
       inite boundaries. Since the implementation does not suffer such	abrupt
       declines,  PLOSS	 is never signaled. TLOSS is signaled for Bessel func‐
       tions 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 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 is not set.

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

       DOMAIN	    0.0 is usually returned, errno is set to EDOM and  a  mes‐
		    sage is usually printed on standard error.

       SING	    The largest finite single-precision number, HUGE of appro‐
		    priate sign, is returned, errno is set to EDOM, and a mes‐
		    sage is printed on standard error.

       OVERFLOW	    The largest finite single-precision number, HUGE of appro‐
		    priate sign, is usually  returned  and  errno  is  set  to
		    ERANGE.

       UNDERFLOW    0.0 is returned and errno is set to ERANGE.

       TLOSS	    0.0	 is returned, errno is set to ERANGE, and a message is
		    printed on standard error.

       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.

   SVID3 ERROR HANDLING PROCEDURES (compile with cc \-Xt)
       ┌───────────────────────────────┬───────────────────┬──────────────────┬─────────────┬──────────────┬─────────┐
       │	<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 │
       └───────────────────────────────┴───────────────────┴──────────────────┴─────────────┴──────────────┴─────────┘

   Abbreviations
       Md	   Message is printed (DOMAIN error).

       Ms	   Message is printed (SING error).

       Mt	   Message is printed (TLOSS error).

       NaN	   IEEE NaN result and invalid operation exception.

       HUGE	   Maximum finite single-precision floating-point number.

       HUGE_VAL	   IEEE ∞ result and division-by-zero exception.

       X_TLOSS	   The value X_TLOSS is defined in <values.h>.

       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.

X/OPEN COMMON APPLICATION ENVIRONMENT (CAE) SPECIFICATIONS CONFORMANCE
       The X/Open System Interfaces and Headers (XSH) Issue 3 and later	 revi‐
       sions  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.

   CAE SPECIFICATION ERROR HANDLING PROCEDURES (compile with cc -Xa)
       ┌───────────────────────────────┬─────────────┬─────────────┬─────────────┬────────────┬─────────┐
       │	<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	│
       └───────────────────────────────┴─────────────┴─────────────┴─────────────┴────────────┴─────────┘

   Abbreviations
       {...}	   errno is not to be relied upon in all braced cases.

       NaN	   IEEE NaN result and invalid operation exception.

       HUGE_VAL	   IEEE ∞ result and division-by-zero exception.

       X_TLOSS	   The value X_TLOSS is defined in <values.h>.

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

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

   ANSI/ISO-C ERROR HANDLING PROCEDURES (compile with cc -Xc)
       ┌───────────────────────────────┬─────────────┬─────────────┬─────────────┬─────────────┐
       │	<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	     │ −	   │ −		 │ −	       │
       └───────────────────────────────┴─────────────┴─────────────┴─────────────┴─────────────┘

   ABBREVIATIONS
       NaN	   IEEE NaN result and invalid operation exception.

       HUGE_VAL	   IEEE ∞ result and division-by-zero.

EXAMPLES
       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\n", x−>name);
	    abort( );
	    break;
	   }
	   return (0); /* all other exceptions, execute default procedure */
	  }

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │MT-Safe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       attributes(5), standards(5)

SunOS 5.11			  23 Sep 1997			   matherr(3M)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net