excpt - Data structures and prototypes for exception handling
support
#include <excpt.h>
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 [Toc] [Back]
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=>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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
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 [Toc] [Back]
This include file includes function prototypes for all of
the external routines listed in exception_intro(3).
c_excpt(4), exception_intro(3), longjmp(3), signal(2),
signal(4), pdsc(4), delim off
excpt(4)
[ Back ] |
