NAME

unwind, exc_virtual_unwind, RtlVirtualUnwind, exc_find_frame_ptr - Routines to unwind a context. 

LIBRARY

Exception Handling Library (libexc.a)

SYNOPSIS

#include <excpt.h>

void unwind(
                PCONTEXT               pcontext,
                PRUNTIME_FUNCTION      prf);
void exc_virtual_unwind(
                PRUNTIME_FUNCTION      prf,
                PCONTEXT               pcontext);
exc_address RtlVirtualUnwind(
                exc_address            controlpc,
                PRUNTIME_FUNCTION      prf,
                PCONTEXT               pcontext,
                PCONTEXT_POINTERS      ppointers);
exc_address  exc_find_frame_ptr(
                PRUNTIME_FUNCTION      prf,
                PCONTEXT               pcontext);
                PCONTEXT               pnext_context);

PARAMETERS

pcontextPointer to a struct sigcontext (see signal(2)) used to represent the current procedure’s context. 

pnext_context
Pointer to a struct sigcontext (see signal(2)) used to represent the context of the current procedure’s caller.  If you specify a non-zero pnext_context argument to exc_find_frame_ptr, the pcontext argument is ignored. 

prfPointer to runtime function (code range descriptor) for the PC stored in the sc_pc field of the activation context record; a call to exc_lookup_function_entry(3) returns this value. Although this argument can be zero, by providing this argument, a caller already having this information would save an extra call (and possible search) for the runtime function. 

controlpcCopy of the sc_pc field of the activation context record. 

ppointersPointer to structure containing addresses corresponding to the locations which were used to restore registers; if zero, this argument is ignored. 

DESCRIPTION

These routines all perform a virtual unwind. Unlike the routines described in exc_resume(3), these routines do not actually unwind a procedure call by modifying the real registers and other machine state.  Instead, these routines modify the structure pointed to by the pcontext argument so that it represents the current procedure’s caller’s context. The routines use procedure information supplied in the structure pointed to by the prf argument to decide how to virtually unwind the context (for instance, how to modify the registers and other machine state). This information is placed in the object by the assembler and linker and conforms to the DEC OSF/1 Calling Standard for AXP Systems. 

If you specify the current procedure’s context in pcontext and the pnext_context argument is non-zero, exc_find_frame_ptr calls exc_virtual_unwind.  exc_virtual_unwind generates a copy of the pcontext argument that it uses in the virtual unwind operation to obtain the stack pointer of the caller: that is, the frame pointer, or static link, of the pcontext supplied as input. The original copy of the context is not modified.  If you supply a pointer to the context of the caller in the pnext_context argument, exc_virtual_unwind returns the stack pointer associated with that context as the frame pointer of the current context. 

The other routines modify the structure pointed to by the pcontext argument to represent the context of the caller. 

unwind originated in the ULTRIX libexc and has an interface compatible with the original one, as long as the ULTRIX caller treated the prf argument as an opaque pointer.  The prf structure has been changed to conform to the DEC OSF/1 Calling Standard for AXP Systems and any caller that explicitly access its fields will encounter incompatibilities. 

exc_virtual_unwind originated in libexcpt. 

RtlVirtualUnwind is a Microsoft Windows NT runtime library interface.  It returns a copy of the updated sc_pc field of the sigcontext when leaving the routine.  The routine also updates the structure pointed to by the ppointers argument. 

These routines typically use masks and stack offsets found in procedure related data structures (described in the DEC OSF/1 Calling Standard for AXP Systems) to restore registers. Those data structures also can contain enough information for these routines to adequately deal with prologues, epilogues, and signal frames. 

Users writing assembly language routines should consult the Assembly Language Programmer’s Guide to determine which directives are required to provide enough information for these routines to correctly unwind through them. 

FILES

/usr/ccs/lib/cmplrs/cc/libexc.a - exception handling library
/usr/include/excpt.h - include file
/usr/include/pdsc.h - include file
/usr/include/signal.h - include file
/usr/include/machine/fpu.h - include file

RELATED INFORMATION

Functions:exception_intro(3), exception_dispatcher(3), exc_lookup_function_entry(3), signal(2), sigaction(2), setjmp(3), exc_unwind(3), __exc_last_chance(3), ieee(3). 

Files: excpt(4), c_excpt(4), signal(4), pdsc(4). 

Assembly Language Programmer’s Guide. 

DEC OSF/1 Calling Standard for AXP Systems.