HP-UX Reference (11i v2 07/12) - 3 Library Functions N-Z (vol 7)

u
uwx_register_callbacks(3X) uwx_register_callbacks(3X)
(Integrity Systems Only)
NAME
uwx_register_callbacks() - register callback routines for stack unwind
SYNOPSIS
#include <uwx.h>
int uwx_register_callbacks(
struct uwx_env
*env,
intptr_t
tok
copyin_cb copyin,
lookupip_cb
lookupip
);
DESCRIPTION
uwx_register_callbacks()
is part of the Unwind Express Library for Integrity system; see
uwx(3X).
uwx_register_callbacks()
registers two callback routines, a copy-in callback and a
lookup-ip callback, with the unwind environment. For self-unwinding, two routines —
uwx_self_copyin()
and uwx_self_lookupip()
— 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 routines when they are called by the unwind engine. The lookup-ip callback rou-
tine is called by the unwind engine to lookup an Instruction Pointer (IP) and find the load module associ-
ated 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 provided callbacks for self-unwinding, this parameter must be the pointer
to the self-info object returned by
uwx_self_init_info()
.
copyin Pointer to the copy-in callback routine. For self-unwinding, this parameter should be the
address of the
uwx_self_copyin()
routine.
lookupip Pointer to the lookup-ip callback routine. For self-unwinding, this parameter should be the
address of the
uwx_self_lookupip()
routine.
The Callback Token
The token, declared as type
intptr_t, is typically a pointer to a callback information 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 pro-
cess (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 registers
and the key stack marker values (ip, sp, bsp, cfm); if execution stops in a leaf function or early in a func-
tion prologue, some important 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 <uwx.h>
as follows:
600 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: December 2007 Update