unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



excpt(4)							     excpt(4)



NAME
  excpt	- Data structures and prototypes for exception handling	support

SYNOPSIS

  #include <&lt;excpt.h>&gt;

DESCRIPTION

  The excpt.h include file brings together all of the data structures and
  prototypes required to support the exception handling	system.	 Calling
  Standard for Alpha Systems for an overview of	the system.

  The excpt.h file also	includes the following include files: signal.h,
  pdsc.h, and c_excpt.h	(which contains	some C structured exception specific
  definitions described	in c_excpt(4)).	 The excpt.h include file defines the
  following:

    +  Exception code encoding

    +  System exception	record

    +  System context record

    +  System context pointers record

    +  Exception flags

    +  Exception dispositions

    +  Language	handler	definitions

    +  Run-time	procedure type definition

    +  Macros to access	runtime	procedure descriptor fields

    +  Exception system	prototypes

  Exception Encoding

  Existing exception code formats have been merged to represent	them in	a new
  format. The existing codes are:

  _____________________________________
		LIBEXC	  NT	  VMS
  _____________________________________
  Code/NUMBER	32 bits	  0:16	  3:13

  Facility	--	  16:13	  16:11

  Customer	--	  29:1	  27:1

  Severity	--	  30:2	  0:3

  Control	--	  --	  28:4
  _____________________________________

  Libexc segments the address space into signals and other constants.  There
  is no	compatibility with old LIBEXC constants. Instead, everything is	a
  case from the	facility field.

  The following	example	shows the typedef for a	union for exception codes:

       typedef union exception_code {
	   struct {
	       pdsc_uint_16	   facility_dependent_1:16;
	       pdsc_uint_16	   facility:12;
	       pdsc_uint_16	   facility_dependent_2:4;
	       pdsc_uint_32	   facility_dependent_3;
	   } exception_code_base;
	   struct {
	       pdsc_uint_32	   osf_facility;
				      /* osf marker+signal,lang,etc */
	       pdsc_uint_32	   code;       /* subcode */
	   } exception_code_osf;
	   struct {
	       pdsc_uint_16	   code:16;    /* subcode */
	       pdsc_uint_16	   facility:13;	  /* base distinguisher	*/
	       pdsc_uint_16	   customer:1; /* nt versus customer */
	       pdsc_uint_16	   severity:2; /* as it	says */
	       pdsc_uint_32	   reserved;  /* sign extension	of bit 31 */
	   } exception_code_nt;
	   struct {
	       pdsc_uint_16	   severity:3;	     /*	as it says */
	       pdsc_uint_16	   message_number:13;	    /* subcode */
	       pdsc_uint_16	   facility:11;	 /* base distinguisher */
	       pdsc_uint_16	   customer:1;	 /* vms	versus customer	*/
	       pdsc_uint_16	   control:4;	 /* 1=>&gt;prnt,rest resrv */
	       pdsc_uint_32	   reserved;  /* sign extension	of bit 31 */
	   } exception_code_vms;
       } exception_code; /* exception_code */

  A facility code for Tru64 UNIX is used as a base for all other Tru64 UNIX
  codes.  Constants chosen for the osf_facility	let the	program	set the	code
  based	on information it has (for example, the	signal code for	EXC_SIGNAL).

  The possible values for the osf_facility field are in	the excpt.h include
  file.

  An example of	using EXC_VALUE	is defining the	codes for the EXC_INTERNAL
  osf_facility (Note that some of the following	definitions are	shown on two
  lines	with the continuation character	due to the space limitations of	a
  reference page):

  #define EXC_STATUS_UNWIND		EXC_VALUE(EXC_INTERNAL,	0)
  #define EXC_STATUS_NONCONTINUABLE_EXCEPTION  \
     EXC_VALUE(EXC_INTERNAL, 1)
  #define EXC_STATUS_INVALID_DISPOSITION \
     EXC_VALUE(EXC_INTERNAL,2)
  #define EXC_SIGNAL_EXPECTED		  EXC_VALUE(EXC_INTERNAL,3)
  #define EXC_RUNTIME_FUNCTION_NOT_FOUND  \
    EXC_VALUE(EXC_INTERNAL,4)
  #define EXC_INFINITE_LOOP_UNWIND   \
    EXC_VALUE(EXC_INTERNAL,5)

  Typically, users either will print out the ascii values for the preceding
  fields, or do	final cleanup and call for operator assistance.	There is lit-
  tle in the way of recovery that can usually occur when these errors are
  encountered. Usually,	these errors indicate a	programming error (for
  example, attempted to	continue a non-continuable exception) or some corrup-
  tion in the exception	system data structures causes the exception system to
  not be able to perform any useful task.



  System Exception Record

  The system exception record provides a handle	to identify an exception.
  This data structure communicates to routines that raise and dispatch excep-
  tions	as well	as the routine that unwinds and	executes finally handlers.
  The definition of the	exception record follows:

       typedef struct system_exrec *exrec_ptr;

       /* UNIX Exception Record	*/
       typedef struct system_exrec {
	 long		   ExceptionCode;	/* reason for exception	*/
	 unsigned long	   ExceptionFlags;  /* in progress, e.g. unwind	*/
	 exrec_ptr	   ExceptionRecord; /* rec chain, e.g.nested info */
	 void		  *ExceptionAddress;	/* where error occurred	*/
	 unsigned long	   NumberParameters; /*	# of ExceptionInformation's*/
	 unsigned long	   ExceptionInformation[1];   /* additional info */
       } system_exrec_type;

  The exception	record pointer allows for nested exceptions to be chained.
  The ExceptionAddress is the address at which the error occurred. The param-
  eters	may be arguments which qualify an exception. The NumberParameters is
  dictated by the ExceptionCode. Currently, NumberParameters is	always zero.

  Activation Context Record

  This record defines the state	of the machine registers and system software
  flags	(for signals and traps)	for a procedure's activation on	the stack.
  The struct sigcontext	found in signal.h (which is also used by
  setjmp/longjmp) represents a procedure's context.

	   #include <&lt;signal.h>&gt;
	   typedef struct sigcontext CONTEXT, *PCONTEXT;

  The following	code example defines context pointers to support
  exc_virtual_unwind(3). These pointers	can also provide a set of addresses
  from which the registers in the CONTEXT are filled:

	   typedef exc_address		CONTEXT_POINTERS[64];
	   typedef CONTEXT_POINTERS	*PCONTEXT_POINTERS;

  Exception Disposition

  An exception disposition is returned by a language exception handler.	The
  handler may also choose not to return	and call a routine such	as
  exc_unwind(3)	directly.

	   typedef enum	_EXCEPTION_DISPOSITION {
	       ExceptionContinueExecution,
	       ExceptionContinueSearch,
	       ExceptionNestedException,
	       ExceptionCollidedUnwind
	   } EXCEPTION_DISPOSITION;

  Exception Record Flags

  The exception	record flags are used to communicate what is going on with a
  particular exception.	Both the exception system and user code	may set	these
  flags. Macros	are provided to	easily test the	ExceptionFlags field of	the
  exception record (system_exrec_type):

  #define EXCEPTION_NONCONTINUABLE 0x1 /* Noncontinuable exception */
  #define EXCEPTION_UNWINDING	   0x2	  /* Unwind is in progress */
  #define EXCEPTION_EXIT_UNWIND	   0x4	  /* Exit unwind is in progress	*/
  #define EXCEPTION_STACK_INVALID  0x08	  /* Stack out of limits
    or unaligned */
  #define EXCEPTION_NESTED_CALL	 0x10	/* Nested exception handler call */
  #define EXCEPTION_TARGET_UNWIND  0x20	/*Execute termination handler
    for	it*/
  #define EXCEPTION_COLLIDED_UNWIND  0x40 /*unwind through unwind
    dispatcher*/

  #define EXCEPTION_UNWIND     (EXCEPTION_UNWINDING | \
				EXCEPTION_EXIT_UNWIND |	\
				EXCEPTION_TARGET_UNWIND	| \
				EXCEPTION_COLLIDED_UNWIND)

  #define IS_UNWINDING(flag)	 (((flag) &&amp; EXCEPTION_UNWIND) != 0)
  #define IS_DISPATCHING(flag)	 (((flag) &&amp; EXCEPTION_UNWIND) == 0)
  #define IS_TARGET_UNWIND(flag) ((flag) \
    &&amp; EXCEPTION_TARGET_UNWIND)

  Run-time Function Type

  The run-time function	is used	to access information regarding	how to unwind
  a procedure's	activation and where it	has a handler.	On Tru64 UNIX this
  structure is defined to be a code range descriptor (see pdsc(4)). Although
  it does not provide direct access to most of the information required, the
  run-time function indirectly does the	following:

  typedef union	pdsc_crd RUNTIME_FUNCTION, *PRUNTIME_FUNCTION, \
    *PRUNTIME_FUNCTION;

  The macros in	the following table facilitate accessing the information
  related to the procedures the	preceding structures represent.	 The argument
  for each macro is PRUNTIME_FUNCTION.

  ________________________________________________________
  Macro			     Comment
  ________________________________________________________
  EXCEPT_PD		     return pointer to pdsc_rpd

  EXCPT_BEGIN_ADDRESS	     first address in code range

  EXCPT_END_ADDRESS	     last address in code range	+4

  EXCPT_LANG_HANDLER	     handler address

  EXCPT_LANG_HANDLER_DATA    handler data address

  EXCPT_PROLOG_END_ADDRESS   end address of prolog +4
  ________________________________________________________

  The excpt.h include file also	provides direct	access to the code range
  descriptor table and its number of elements with function_table and
  function_table_size variables	(actually macros) respectively.

  The dispatcher context contains enough information for the dispatcher	to
  deliver pertinent information	to language handlers about what	it was asked
  to do	and by whom and	enough information for them to detect collided
  unwinds.

       typedef struct {
	   unsigned long      pc;		   /* current pc in backup */
	   pRUNTIME_FUNCTION  functionTable;	   /* entry matching pc	*/
	   PCONTEXT	      originating_context; /* disp called with this */
       } DISPATCHER_CONTEXT;

  Function prototypes

  This include file includes function prototypes for all of the	external rou-
  tines	listed in exception_intro(3).

RELATED	INFORMATION

  c_excpt(4), exception_intro(3), longjmp(3), signal(2), signal(4), pdsc(4),