Content-type: text/html Man page of excpt

excpt

Section: Devices and Network Interfaces (4)
Index Return to Main Contents
 

NAME

excpt - Data structures and prototypes for exception handling support  

SYNOPSIS

#include <excpt.h>  

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:


LIBEXCNTVMS

Code/NUMBER32 bits0:163:13
Facility--16:1316:11
Customer--29:127:1
Severity--30:20: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=>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 little 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 corruption 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 exceptions 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 parameters 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 <signal.h>
    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) & EXCEPTION_UNWIND) != 0) #define IS_DISPATCHING(flag) (((flag) & EXCEPTION_UNWIND) == 0) #define IS_TARGET_UNWIND(flag) ((flag) \
  & 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.


MacroComment

EXCEPT_PDreturn pointer to pdsc_rpd
EXCPT_BEGIN_ADDRESSfirst address in code range
EXCPT_END_ADDRESSlast address in code range +4
EXCPT_LANG_HANDLERhandler address
EXCPT_LANG_HANDLER_DATAhandler data address
EXCPT_PROLOG_END_ADDRESSend 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 routines listed in exception_intro(3).  

RELATED INFORMATION

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


 

Index

NAME
SYNOPSIS
DESCRIPTION
Exception Encoding
System Exception Record
Activation Context Record
Exception Disposition
Exception Record Flags
Run-time Function Type
Function prototypes
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:07 GMT, October 02, 2010