unwind, exc_virtual_unwind, RtlVirtualUnwind,
exc_find_frame_ptr, exc_remote_virtual_unwind - routines
to unwind a context
#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 ); unsigned long
exc_remote_virtual_unwind(
void *handle,
int (*fetch_from_process) (void *handle, void
*addr, void *buffer, long size),
exc_address crd_handle,
PRUNTIME_FUNCTION pcrd,
PCONTEXT pcontext );
Pointer to a struct sigcontext (see signal(2)) used to
represent a procedure's context. Pointer to a struct sigcontext
(see signal(2)) used to represent the context of a
procedure's caller. If you specify a nonzero pnext_context
argument, the pcontext argument is ignored. Pointer to
run-time 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() returns this
value. Although this argument can be zero, by providing
this argument, a caller already having this information
would save an extra search for the run-time function.
Copy of the sc_pc field of the activation context record.
Pointer to structure containing addresses corresponding to
the locations that were used to restore registers; if
zero, this argument is ignored.
The following descriptions apply to parameters for the
exc_remote_virtual_unwind() routine. How these parameters
are interpreted depends on whether the process involved in
the operation is local or remote. Remote unwind: A
pointer to an arbitrary block of memory that is set up and
managed by the user application and passed through the
exception handling routines. This allows the author of
the function identified by the fetch_from_process parameter
to maintain any necessary state. The state maintained
here will most likely include the identity of the process
to be unwound.
Local unwind: This parameter is ignored. Remote
unwind: The address of an application-specific
function, written by the author of the application
that calls exc_remote_virtual_unwind(). If the
value of the fetch_from_process parameter is NULL,
the unwind takes place in the local process, not a
remote process.
The function identified by the fetch_from_process
parameter takes the following arguments: The handle
parameter that was passed into exc_remote_virtual_unwind().
The starting address in the remote
process from which to copy memory. A buffer in the
local process into which data from the remote process
is copied. The number of bytes to copy from
addr to buffer. The region of memory pointed to by
buffer must be at least size bytes in length.
The function identified by the fetch_from_process
parameter returns 0 (zero) to indicate success and
nonzero to indicate a failure in accessing the
remote address space. A failure will also cause an
exception status to be raised.
Local unwind: The fetch_from_process parameter is
ignored. Remote unwind: The address of the cell
exc_crd_list_head in the remote process. The means
by which this address is communicated to the local
(tracing) process is application specific.
Local unwind: This parameter is ignored. Remote
unwind: This parameter is ignored.
Local unwind: The address of a code-range descriptor
describing the context from which to begin the
unwind. If NULL, the code-range descriptor is
looked up based on the PC contained in the pcontext
parameter. This is often passed as NULL for the
initial invocation of exc_remote_virtual_unwind()
and is always passed as NULL for iterated invocations
during the stack walk. A pointer to a struct
sigcontext representing the context of the procedure
(local or remote) to be unwound.
At a minimum, this context structure must contain
the following context for the routine to be
unwound: FP register ($15), SP register ($30), RA
register ($26 in a standard call), and the PC.
Additionally, the context may contain the preserved
registers.
This argument needs to be set up only once; consecutive
calls to exc_remote_virtual_unwind() manipulate
this structure to represent the state of successively
earlier procedures in the call chain.
All of the unwind routines 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 previous procedure in
the call stack. 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 calling standard
for Alpha systems.
If the specify a procedure's context in pcontext and the
pnext_context argument is nonzero, exc_find_frame_ptr generates
a copy of the pcontext argument. 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_find_frame_ptr() returns the stack pointer associated
with that context as the frame pointer of the current
context.
The other unwind routines modify the structure pointed to
by the pcontext argument in order to represent the context
of the caller.
Remote unwinding by the exc_remote_virtual_unwind() function
can involve a local or remote process -- unlike the
unwind(), exc_virtual_unwind(), and RtlVirtualUnwind()
functions that operate only on local processes. Remote
unwinding is controlled by the fetch_from_process parameter.
This parameter is a pointer to (or handle for) an
application-supplied function that knows how to access the
memory of the process (local or remote) being acted on: If
the user application passes a NULL value in the
fetch_from_process parameter, the local process is performing
an unwind on its own stack. This allows the unwind
routine to make certain optimizations in its processing.
If the user application passes the address of a routine in
the fetch_from_process parameter, the unwind routine is
not allowed to assume anything about the process it is
accessing, and only the fetch routine is allowed to know
the identity of the process being unwound. It might be
the local process, it might be another process in the system,
it might be a process on another system on the network,
or it might be a corefile from a long-deceased process.
To summarize, remote unwinding is the capability to unwind
the stack of a process that is not necessarily the process
doing the unwind.
The exc_remote_virtual_unwind() function returns 1 to
indicate that the program being unwound was in the prologue
or epilogue of the frame for the current context;
otherwise, it returns 0.
All of the unwind routines typically use masks and stack
offsets found in procedure related data structures
(described in the Calling Standard for Alpha 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.
The origins of the various unwind routines are as follows:
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 calling standard for Alpha systems, and any callers
that explicitly access its fields will encounter incompatibilities.
exc_virtual_unwind() originated in libexc.
RtlVirtualUnwind() is a Microsoft Windows NT run-time
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.
/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
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
Calling Standard for Alpha Systems
unwind(3)
[ Back ] |
