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

_
_UNW_createContextForSelf(3X) _UNW_createContextForSelf(3X)
(Itanium(R)-based System Only)
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 Architecture: Chapter 8,
Procedure Linkage. The unwind information for __user_sendsig is communicated in the kernel gate-
way 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 pro-
cess 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 construc-
tion). 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.
68 Hewlett-Packard Company − 2 − HP-UX 11i Version 2: December 2007 Update