_UNW_createContextForSelf.3x (2010 09)

_
_UNW_createContextForSelf(3X) _UNW_createContextForSelf(3X)
(Integrity Systems Only)
NAME
_UNW_createContextForSelf(), _UNW_createContext(), _UNW_destroyContext() - allocate and deallocate
unwind library data structure
SYNOPSIS
#include <unwind.h>
_Unwind_Context * _UNW_createContextForSelf(void);
_Unwind_Context * _UNW_createContext(
_UNW_ReadTargetMem read_tgt_mem,
_UNW_LoadMapFromIP load_map_from_ip,
uint32_t ident);
void _UNW_destroyContext(_Unwind_Context* p);
DESCRIPTION
_UNW_createContextForSelf
and _UNW_createContext
each initialize a data structure called
_Unwind_Context
, which is managed by the stack unwind library, supplied as
libunwind.so.
_UNW_createContextForSelf
is typically used when a process intends to unwind its own stack.
_UNW_createContext
is typically used when a process intends to unwind a different process’ stack or
the stack of a "dead" process preserved in a core file.
When using
_UNW_createContext
for unwinding a process (referred to as the target process), the
client process is required to provide three parameters:
1. Parameter read_tgt_mem is a function which the unwind library calls to read values from the target
process memory including the unwind header, unwind table and unwind information blocks, the
procedure call stack, and the Register Stack Engine backing store. It must be able to read from
anywhere in the 64-bit address space (even for 32-bit applications) since the Integrity systems’ ker-
nel interruption unwind header is read from kernel gateway memory pages.
read_tgt_mem has type definition
_UNW_ReadTargetMem
, which is defined in unwind.h as
typedef void * (* _UNW_ReadTargetMem) (void *dst,
uint64_t src,
size_t length,
uint32_t ident);
The parameters are almost synonymous with those for memcpy (3C). Parameter dst is the destina-
tion address to which parameter length bytes are copied from parameter src. Note that src is of
type
uint64_t in order to represent the 64-bit addresses required for reading the kernel gateway
page. When unwinding through a 64-bit application, all src and dst addresses used during unwind-
ing are 64-bit pointers. When unwinding through a 32-bit application’s code, most addresses used
during unwinding are 32-bit pointers (although the unwind library swizzles them to fully qualified
64-bit addresses before calling the target memory reader). The memory model and the term "swiz-
zle" are explained in detail in Itanium Processor Family Runtime Architecture Supplement : 32-Bit
Runtime Architecture for HP-UX , "Section 1: Memory Model".
The only range of addresses which require 64-bit pointers (and therefore unreachable from the 32-
bit address space) are those associated with the unwind header and unwind information for the
kernel’s signal handler wrapper function
__user_sendsig. The client’s memory read callback
function must be able to detect this range and to read this range of addresses. The range is defined
at program startup time by the microloader and dynamic loader (or in crt0.o for fully bound exe-
cutables) in a structure load_info_t, defined in /usr/include/crt0.h. See Itanium Proces-
sor Family Runtime Architecture Supplement: Signal Handling on HP-UX and Itanium Processor
Family Runtime Architecture Supplement: Program Startup on HP-UX .
read_tgt_mem ’s third parameter, ident , is transparent to the unwind library itself, and is provided
for the use of the unwinder client program. The client program supplies the unwind library with a
value for ident (via the call to
_UNW_createContext) which the unwind library in turn passes
along to the read_tgt_mem callback. A debugger, for example, can use ident to identify separate
threads within the target process.
2. Parameter load_map_from_ip is a function which the unwind library calls in place of calls to
dlmodinfo when it needs to obtain a load_module_desc for a given IP address in target pro-
cess memory (See dlmodinfo (3C)). When called, load_map_from_ip must fill in a
load_module_desc structure with accurate values for fields linkage_ptr, unwind_base,
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1