HP-UX Reference (11i v2 04/09) - 3 Library Functions A-M (vol 6)

_
_UNW_createContextForSelf(3X) _UNW_createContextForSelf(3X)
(Itanium(R)-based Systems Only)
load_module_desc
structure with accurate values for fields linkage_ptr,
unwind_base,
and
text_base for any valid user process instruction address including instruction addresses
associated with __user_sendsig
. Unwind_base (which is the location of the unwind header),
and text_base , (which is the location at which the ELF
.text segment is loaded), must each be full
64-bit addresses (as opposed to 32-bit un-swizzled pointers). Linkage_ptr is the (full 64-bit) value of
a procedure’s GP register. See Itanium Processor Family Software Conventions and Runtime Archi-
tecture : Chapter 8, Procedure Linkage. The unwind information for __user_sendsig is communi-
cated in the kernel gateway page as described in the discussion of read_tgt_mem above.
load_map_from_ip has type definition
_UNW_LoadMapFromIP
which is defined in
unwind.h as
typedef void (* _UNW_LoadMapFromIP) (
struct load_module_desc * new_load_map,
uint64_t ip,
uint32_t ident);
Parameter new_load_map is a pointer to a pre-allocated struct load_module_desc to be filled in by
load_map_from_ip.
Parameter ip is any instruction pointer associated with the load module for which information is
requested.
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
load_map_from_ip callback. A debugger, for example, can use ident to identify separate threads
within the target process.
3. The semantics of
_UNW_createContext
’s third parameter ident , which is provided for the use of
the unwinder client program, is discussed in the read_tgt_mem and load_map_from_ip paragraphs
above.
Although
_UNW_createContext
was designed to fulfill the requirement of unwinding a process other
than self, the
_Unwind_Context
created _UNW_createContext can be used by a process to
unwind itself as well. Reason’s for doing so include the unwinding of dynamically generated code or run-
time instrumented code. In these situations, the client may need to register
_UNW_LoadMapFromIP
and _UNW_ReadTargetMem
callbacks.
_UNW_destroyContext
frees memory allocated by _UNW_createContextForSelf or by
_UNW_createContext
. To avoid memory leaks, an application that allocates an _Unwind_Context
object should call _UNW_destroyContext
when the _Unwind_Context is no longer needed.
Application UsagE
_UNW_createContextForSelf
, _UNW_createContext, and _UNW_destroyContext
are
thread-safe.
RETURN VALUE
Pointer to struct
_Unwind_Context.
ERRORS
_UNW_createContextForSelf and _UNW_createContext
can fail to create the unwind context
data structure under the following conditions:
• Low memory conditions. The following Unwind library behavior is guaranteed in low memory condi-
tions:
A failed construction of a
_Unwind_Context creates for the client program enough of an
_Unwind_Context object to support a call to the the stack unwind library entry point
_UNW_getAlertCode() , which returns _UNW_MEMORY_ALLOCATION_ERROR in the event of a
failed construction or if the _Unwind_Context pointer is NULL (also an indicator of failed con-
struction). Had the construction been successful, _UNW_getAlertCode() would have returned
_UNW_OK.
Failed construction in extremely low memory conditions is communicated by returning
NULL in effect
setting the _Unwind_Context pointer to NULL. Subsequent calls to interface functions of return
type _UNW_ReturnCode return _UNW_MEMORY_ALLOCATION_ERROR if the
_Unwind_Context pointer is NULL.
Section 3−−4 Hewlett-Packard Company − 2 − HP-UX 11i Version 2: September 2004