exc_add_pc_range(3)exc_add_pc_range(3)NAME
exc_add_pc_range_table, exc_remove_pc_range_table, exc_lookup_func‐
tion_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 pro‐
gram 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_func‐
tion_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_func‐
tion_entry(
void *handle,
int (*fetch_from_process) (void *handle, void *addr, void *buf‐
fer, long size),
exc_address pc,
exc_address crd_handle,
PRUNTIME_FUNCTION *func_entry,
PRUNTIME_FUNCTION *crd_base );
LIBRARY
Exception Handling Library (libexc.a)
PARAMETERS
Pointer to the base of a code-range descriptor table. Number of code-
range descriptors in the table pointed to by pbase. Address within a
range of code for which the base of a code-range descriptor table is to
be returned. First address for which the gp argument applies. Number
of bytes from begin_address for which the gp argument applies. 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. 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 neces‐
sary state. The state maintained here will most likely include the
identity of the process to be unwound.
Local lookup: This parameter is ignored. 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: The handle parameter that was
passed into exc_remote_lookup_function_entry(). The starting
address in the remote process from which to copy memory. A buf‐
fer 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 lookup: Must be NULL (by definition). 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. 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 appli‐
cation specific. Remote lookup: The address of a PRUNTIME_FUNC‐
TION allocated by the caller, into which the appropriate code-
range descriptor in the remote process is written. The PRUN‐
TIME_FUNCTION must point to struct pdsc_crd, which is also allo‐
cated 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 PRUN‐
TIME_FUNCTION is passed, the contents of the PRUNTIME_FUNCTION
is written with the address of the appropriate pdsc_crd struc‐
ture. May be NULL. Remote lookup: The address of a PRUN‐
TIME_FUNCTION, where the base address of the code-range descrip‐
tor 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 repre‐
sented 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 infor‐
mation 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
section of a relocatable object file that the linker merges into a sin‐
gle code-range descriptor table for each executable and shared object.
The linker also generates code in the and sections so that each exe‐
cutable 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 stan‐
dard 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 nor‐
mal 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_func‐
tion_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 mem‐
ory of the process (local or remote) being acted on: If the user appli‐
cation 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 func‐
tions to obtain enough information to virtually unwind procedure con‐
texts.
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 section of an executable or shared object and
exc_remove_gp_range() in the section. Many executables have only one
such call each in their and 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
exc_add_pc_range(3)