 |
Index for
Section 3 |
|
 |
Alphabetical
listing for U |
|
 |
Bottom of
page |
|
unwind(3)
NAME
unwind, exc_virtual_unwind, RtlVirtualUnwind, exc_find_frame_ptr,
exc_remote_virtual_unwind - routines to unwind a context
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 );
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 );
PARAMETERS
pcontext
Pointer to a struct sigcontext (see signal(2)) used to represent a
procedure's context.
pnext_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.
prf 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.
controlpc
Copy of the sc_pc field of the activation context record.
ppointers
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.
handle
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.
fetch_from_process
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:
handle The handle parameter that was passed into
exc_remote_virtual_unwind().
addr The starting address in the remote process from which to copy
memory.
buffer A buffer in the local process into which data from the remote
process is copied.
size 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.
crd_handle
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.
pcrd
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.
pcontext
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.
DESCRIPTION
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.
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
SEE ALSO
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for U |
|
 |
Top of
page |
|