uwx_register_callbacks(3X)uwx_register_callbacks(3X)NAMEuwx_register_callbacks() - register callback routines for stack unwind
SYNOPSISDESCRIPTION
is part of the Unwind Express Library for Integrity system; see
uwx(3X). registers two callback routines, a copy-in callback and a
lookup-ip callback, with the unwind environment. For self-unwinding,
two routines — and — are provided in the Unwind Express library for
this purpose. For other unwinding applications, the client must supply
these routines.
The callback routines provide the interface between the unwind engine
and the specific environment in which unwinding is taking place. This
interface uses a "token" by which the callback routines can maintain
and share state information. The token is an arbitrary pointer-sized
value that is provided by the client, and passed to the callback rou‐
tines when they are called by the unwind engine. The lookup-ip call‐
back routine is called by the unwind engine to lookup an Instruction
Pointer (IP) and find the load module associated with that IP. The
copy-in callback routine is called to read data from the memory space
of the process being unwound.
Parameters
env A pointer to an unwind environment object.
tok The "token"—an arbitrary value provided by the client to
be passed to the callback routines. When using the pro‐
vided callbacks for self-unwinding, this parameter must
be the pointer to the self-info object returned by
copyin Pointer to the copy-in callback routine. For self-
unwinding, this parameter should be the address of the
routine.
lookupip Pointer to the lookup-ip callback routine. For self-
unwinding, this parameter should be the address of the
routine.
The Callback Token
The token, declared as type is typically a pointer to a callback infor‐
mation structure defined by and provided by the client. This structure
contains information that the client needs to share with the callback
routines it provides. The structure may also provide a storage area
where the callback routines can maintain cached information.
For a cross-unwind, the callback information structure needs to contain
information about the target process (e.g., thread or process id),
along with some address space mapping information.
The callback information structure also needs to contain a copy of or a
reference to the initial context from which the unwind was initiated.
The unwind environment itself tracks only the state of preserved regis‐
ters and the key stack marker values (ip, sp, bsp, cfm); if execution
stops in a leaf function or early in a function prologue, some impor‐
tant values may exist in scratch registers (e.g., the return pointer,
rp, may still be in BR0). When the unwind engine determines that it
needs the value from a register that it doesn't already have, it uses
the copy-in callback to obtain that value.
The Lookup IP callback
The lookup-ip callback is used for obtaining information for a given
IP. Its prototype is given in as follows:
The unwind engine passes the following parameters to the callback rou‐
tine:
request Identifies the type of request that the unwind engine
is making.
ip The IP for which information is needed.
tok The callback token.
resultp Address of a result vector pointer.
The unwind engine uses this callback for four types of requests:
Requests the callback to lookup information for the given IP.
The callback must allocate a result vector, place the load
information in the vector, and return a pointer to the
result vector in
Informs the callback when it is safe to free the result vector.
A pointer to the vector returned by the lookup request is
passed in (*resultp). The ip parameter is not used for
this request. (If the result vector was not dynamically
allocated, this request can be ignored.)
Requests the callback to return symbolic information for the IP.
If symbolic information is available, the callback must
allocate a result vector, place the symbolic information in
the vector, and return a pointer to the result vector in
Requests the callback to return the name of the module contain‐
ing the IP.
If the module name is available, the callback must allocate
a result vector, place the module name in the vector, and
return a pointer to the result vector in
In order to step from one frame to a previous frame on the stack,
starts with the current IP and makes a request to obtain information
about this IP. The and requests are used only if the client makes a
specific request for symbolic information that is not already available
for the current frame.
The parameter is both an input and an output parameter to the lookup-ip
callback routine. As an input parameter, it points to an array of
key/value pairs of unsigned 64-bit integers. The first value in each
pair is a key, and the second value in each pair is a corresponding
value. The vector is terminated by a key/value pair whose key is 0.
The vector may contain the following keys:
Version number of the current callback interface.
The value corresponding to this key is currently 3. This
version number changes only when the callback interface
adds new features that a client may wish to check for.
Current value of the predicate registers.
This is provided only for requests, and only if the predi‐
cates are currently known.
Starting address of the current function.
This is provided only for and requests, and only if the
starting address of the function is currently available.
(This value can assist the callback routine in locating the
proper symbol name.)
An inline context identifier. This is provided only for
requests in response to a call to the entry point. See
uwx_step_inline(3X) and uwx_find_source_info(3X) for more
information about stepping over inlined calls.
In response to the request, the callback must return one of the follow‐
ing status codes:
A load module was found.
The result vector contains load module and unwind table
information.
No information found for this IP.
An error occurred.
In the normal case, the callback obtains the following information
about the given IP: base address of its text segment, starting and end‐
ing addresses of the unwind table, and (optional) unwind flags. It
places this information in the result vector, and returns the status
code.
The result vector is an array of key/value pairs. The first value in
each pair is a key, and the second value in each pair is a correspond‐
ing value. The vector is terminated by a key/value pair whose key is
0.
The following keys can be returned in the result vector:
Base address of text segment.
Starting address of unwind table.
Ending address of unwind table.
Unwind flags (HP-UX only).
Value of the
gp register for this load module.
On HP-UX, the load information can be obtained with the and routines.
The routine returns a descriptor containing the base address of the
text segment and the address of the unwind header, and the routine
returns the name of that load module. The unwind header contains the
unwind flags, and the segment-relative offsets of the beginning and end
of the unwind table. The callback must convert the segment-relative
offsets to virtual addresses by adding the base address of the text
segment. The unwind flags contain a version number of the unwind table
format, and a flag that indicates whether the unwind table contains
32-bit or 64-bit entries. (On other operating systems, unwind tables
always contain 64-bit entries, so the unwind flags do not need to be
provided.)
If the callback does not find any information it returns the status
code. It should leave the resultp parameter unmodified.
When the callback returns the unwind engine will assume that the IP
belongs to a leaf procedure with default unwind properties, and will
attempt to unwind accordingly.
If any error condition occurs that would prevent the unwind engine from
unwinding correctly, the callback should return and leave the resultp
parameter unmodified.
In response to the or request, the callback must return one of the fol‐
lowing status codes:
Symbolic information was found for this IP.
No symbolic information found for this IP.
An error occurred.
When returning with status, the result vector can contain the following
keys:
Pointer to name of the load module containing the IP.
Pointer to name of the function containing the IP.
Address of the start of function containing the IP.
Pointer to name of an inlined function name
(if the current context is in an inlined call).
Pointer to name of the source file containing the current func‐
tion.
Source line number within the source file corresponding to the
IP.
An inline context identifier for use in stepping through
inlined calls (if the current context is in an inlined
call).
In all cases when the callback returns a pointer to a string, the
unwind engine copies the string into a string pool within the unwind
environment. The client may deallocate or reuse its string storage
after the request.
The Copy-In Callback
The copy-in callback is used for obtaining values from the address
space of the process being unwound. Its prototype is given in as fol‐
lows:
The unwind engine passes the following parameters to the callback rou‐
tine:
request Identifies the type of request that the unwind engine
is making.
loc Address in local memory where the requested data
should be placed. This address will always be prop‐
erly aligned for an object of the requested length.
rem Address in remote memory from which remote data should
be read, or the identifier of a register to be read
from the context of the target process.
len Number of bytes to read from the target address space.
For requests, it will always be either 4 or 8; for all
other requests, it will always be 8.
tok The callback token.
The unwind engine uses this callback for four types of requests:
Read data from the unwind information area of the target
process.
Since this area is in the text segment, a debugger may
choose to read this information directly from the file or
from a copy in local memory instead of from the target
process.
Read data from the memory stack of the target process.
Read data from the register stack backing store of the target
process.
Special considerations may be necessary for portions of the
backing store. (For example, on HP-UX, reading from an
area between BSP and BSPSTORE using either or the library
requires a special request type.)
Read data from a register in the current process context.
If unwinding was initiated or resumed from a signal context
record, this request should read data from the signal con‐
text record.
For all but requests, the rem parameter contains the address in remote
memory from which data should be read. This address will always be
properly aligned for an object of the requested length.
For requests, the rem parameter contains the register identifier of the
register whose value is needed. The register identifier will be one of
the following:
predicates (PR0-PR63)
(1
-
31)
(2
-
127)
(0
-
7)
On
a
suc‐
cess‐
ful
copy
in
oper‐
a‐
tion,
the
call‐
back
must
return
the
num‐
ber
of
bytes
read
(which
must
match
the
len
param‐
e‐
ter).
If
an
error
occurs,
the
call‐
back
should
return
0.
RETURN
VALUE
returns
on
suc‐
cess‐
ful
reg‐
is‐
tra‐
tion
of
the
call‐
back
rou‐
tines.
See
uwx(3X)
for
error
codes.
AUTHOR
The
Unwind
Express
Library
was
devel‐
oped
by
Hewlett-
Packard.
SEE ALSO
dlget‐
name(3C),
dlmod‐
info(3C),
uc_access(3),
uwx(3X),
uwx_add_to_bsp(3X),
uwx_find_source_info(3X),
uwx_find_sym‐
bol(3X),
uwx_free(3X),
uwx_get_abi_con‐
text_code(3X),
uwx_get_func‐
start(3X),
uwx_get_mod‐
ule_info(3X),
uwx_get_nat(3X),
uwx_get_reg(3X),
uwx_get_source_info(3X),
uwx_get_sym_info(3X),
uwx_init(3X),
uwx_init_con‐
text(3X),
uwx_reg‐
is‐
ter_alloc_cb(3X),
uwx_release_sym‐
bol_cache(3X),
uwx_self_do_con‐
text_frame(3X),
uwx_self_free_info(3X),
uwx_self_init_con‐
text(3X),
uwx_self_init_info(3X),
uwx_set_nofr(3X),
uwx_set_remote(3X),
uwx_step(3X),
uwx_step_inline(3X).
Integrity Systems Only uwx_register_callbacks(3X)
