 |
Index for
Section 3 |
|
 |
Alphabetical
listing for E |
|
 |
Bottom of
page |
|
exc_add_pc_range(3)
NAME
exc_add_pc_range_table, exc_remove_pc_range_table,
exc_lookup_function_table, find_rpd, exc_lookup_function_entry,
exc_remote_lookup_function_entry, exc_add_gp_range, exc_remove_gp_range,
exc_lookup_gp - routines to support mapping program counters to the data
structures defined at run time
SYNOPSIS
#include <excpt.h>
void exc_add_pc_range_table(
PRUNTIME_FUNCTION pbase,
pdsc_count count );
void exc_remove_pc_range_table(
PRUNTIME_FUNCTION pbase );
PRUNTIME_FUNCTION exc_lookup_function_table(
exc_address pc );
PRUNTIME_FUNCTION find_rpd(
exc_address pc );
PRUNTIME_FUNCTION exc_lookup_function_entry(
exc_address pc );
void exc_add_gp_range(
exc_address begin_address,
unsigned long length,
exc_address gp );
void exc_remove_gp_range(
exc_address begin_address );
exc_address exc_lookup_gp(
exc_address pc );
PRUNTIME_FUNCTION exc_remote_lookup_function_entry(
void *handle,
int (*fetch_from_process) (void *handle, void *addr, void *buffer,
long size),
exc_address pc,
exc_address crd_handle,
PRUNTIME_FUNCTION *func_entry,
PRUNTIME_FUNCTION *crd_base );
LIBRARY
Exception Handling Library (libexc.a)
PARAMETERS
pbase
Pointer to the base of a code-range descriptor table.
count
Number of code-range descriptors in the table pointed to by pbase.
pc Address within a range of code for which the base of a code-range
descriptor table is to be returned.
begin_address
First address for which the gp argument applies.
length
Number of bytes from begin_address for which the gp argument applies.
gp Address of the global pointer used to refer to the Global Offset Table
and small data sections (see the Calling Standard for Alpha Systems and
the Object File/Symbol Table Format Specification).
The following parameter descriptions apply to the
exc_remote_lookup_function_entry() routine. How these parameters are
interpreted depends on whether the process involved in the operation is
local or remote.
handle
Remote lookup: A pointer to an arbitrary block of memory, 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 lookup: This parameter is ignored.
fetch_from_process
Remote lookup: The address of an application-specific function
contained in the user application that calls
exc_remote_lookup_function_entry(). If fetch_from_process is NULL, the
lookup of the code-range descriptor 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_lookup_function_entry().
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 lookup: Must be NULL (by definition).
pc Remote lookup: The program counter (PC) value in the remote process for
which code-range descriptor information is to be returned.
Local lookup: The program counter (PC) value in the local process for
which code-range descriptor information is to be returned.
crd_handle
Remote lookup: The address of the cell exc_crd_list_head in the process
whose function entry is being looked up. The means by which this
address is communicated to the process calling
exc_remote_lookup_function_entry() is application specific.
func_entry
Remote lookup: The address of a PRUNTIME_FUNCTION allocated by the
caller, into which the appropriate code-range descriptor in the remote
process is written. The PRUNTIME_FUNCTION must point to struct
pdsc_crd, which is also allocated by the caller. The code-range
descriptor does not need to be initialized in any way.
In the event of a lookup failure (that is, the function return value is
zero), the contents of the structure pdsc_crd pointed to by this
PRUNTIME_FUNCTION are unpredictable.
Local lookup: The address of a PRUNTIME_FUNCTION. If a
PRUNTIME_FUNCTION is passed, the contents of the PRUNTIME_FUNCTION is
written with the address of the appropriate pdsc_crd structure. May be
NULL.
crd_base
Remote lookup: The address of a PRUNTIME_FUNCTION, where the base
address of the code-range descriptor table is written. (Note: this
pointer is written with an address in the remote address space. Do not
try to dereference this pointer.)
Local lookup: Same meaning as remote lookup case, except may be NULL.
DESCRIPTION
The exception system needs to access procedure-specific information at run
time in order to perform unwinds and call handlers. You find this
information by mapping a PC to a procedure and its structures.
The PRUNTIME_FUNCTION typedef points to a code-range descriptor (pdsc(4)).
A code-range descriptor represents a range of addresses. To support very
high levels of optimization, one procedure can be represented by many
code-range descriptors (but a code-range descriptor belongs to only one
procedure).
The code-range descriptor provides the key to access all of the information
that the exception system requires about a procedure (although some of it
may be available only indirectly through the code-range descriptor).
The assembler automatically generates code-range descriptors in the .pdata
section of a relocatable object file that the linker merges into a single
code-range descriptor table for each executable and shared object. The
linker also generates code in the .init and .fini sections so that each
executable and shared object will register (by calling
exc_add_pc_range_table()) and deregister (by calling
exc_remove_pc_range_table()) their code-range descriptor tables at run time
with the exception system (if present).
You may need to call these routines manually if you are using the exception
system and generate or load code yourself without using standard Tru64 UNIX
system libraries and services.
The exception system maintains the list of registered code-range descriptor
tables. The exc_lookup_function_table() routine returns a pointer to the
base of a code-range descriptor table containing a range of code that
includes the address supplied in the pc argument. This routine returns a
NULL (zero-value) pointer if an entry for the pc argument is not found.
The exc_lookup_function_entry() and find_rpd() routines each return a
PRUNTIME_FUNCTION for the address supplied by the pc argument.
Note
The find_rpd() routine is an old ULTRIX libexc interface. It continues to
work on Tru64 UNIX systems if its callers treat its return argument as an
opaque pointer. If they explicitly access fields in the returned structure,
they will encounter incompatibilities.
The exc_remote_lookup_function_entry() routine can look up a code-range
descriptor in either the local process or a remote process. When the
correct code-range descriptor is located, it is copied into the local
address space in storage indicated by the func_entry parameter. In normal
remote unwinding use, exc_remote_lookup_function_entry() is not called from
the application, but is used as a utility routine by
exc_remote_virtual_unwind(). In both cases (local and remote),
exc_remote_lookup_function_entry() returns the address of the code-range
descriptor if successful and zero otherwise. (Note: the return value from
exc_remote_lookup_function_entry() is an address in the remote address
space. Do not try to dereference this pointer.)
Remote lookup of a code-range descriptor by the
exc_remote_lookup_function_entry() function can involve either a local
process or a remote process -- unlike the other lookup and find functions
that operate only on local processes. Remote lookup 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 lookup operation is being performed on the local
process.
This allows the lookup 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 lookup 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 acted on.
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 lookup is the capability to look up code-range
descriptors in a process that is not necessarily the process doing the
lookup.
The unwind functions typically call some of these lookup and find functions
to obtain enough information to virtually unwind procedure contexts.
The gp is not in the code-range or procedure descriptors ( pdsc(4)) because
the same gp can be used for many routines and including the gp would waste
space. Instead, the linker generates calls to exc_add_gp_range() in the
.init section of an executable or shared object and exc_remove_gp_range()
in the .fini section. Many executables have only one such call each in
their .init and .fini sections.
The exc_lookup_gp() routine returns a NULL (zero value) pointer if an entry
for the pc parameter is not found.
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), 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).
Calling Standard for Alpha Systems
Object File/Symbol Table Format Specification
Assembly Language Programmer's Guide
|
Index for
Section 3 |
|
|
Alphabetical
listing for E |
|
 |
Top of
page |
|