_UNW_createContextForSelf(3X) _UNW_createContextForSelf(3X)
NAME
_UNW_createContextForSelf(), _UNW_createContext(), _UNW_destroyContext() - allocate and deallocate unwind library data structure
SYNOPSIS
DESCRIPTION
and each initialize a data structure called which is managed by the stack unwind library, supplied as is typically used when a process
intends to unwind its own stack. 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 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' kernel
interruption unwind header is read from kernel gateway memory pages.
read_tgt_mem has type definition which is defined in as
The parameters are almost synonymous with those for memcpy(3C). Parameter dst is the destination address to which parameter length
bytes are copied from parameter src. Note that src is of type 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 unwinding are 64-bit point-
ers. When unwinding through a 32-bit application's code, most addresses used during unwinding are 32-bit pointers (although the
unwind library them to fully qualified 64-bit addresses before calling the target memory reader). The memory model and the term
"swizzle" are explained in detail in "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 asso-
ciated with the unwind header and unwind information for the kernel's signal handler wrapper function The client's memory read call-
back 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 for fully bound executables) in a structure defined in See and
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 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 tar-
get process.
2. Parameter load_map_from_ip is a function which the unwind library calls in place of calls to when it needs to obtain a for a given
IP address in target process memory (See dlmodinfo(3C)). When called, load_map_from_ip must fill in a structure with accurate val-
ues for fields and for any valid user process instruction address including instruction addresses associated with (which is the
location of the unwind header), and text_base, (which is the location at which the ELF 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
Chapter 8, The unwind information for __user_sendsig is communicated in the kernel gateway page as described in the discussion of
read_tgt_mem above.
load_map_from_ip has type definition which is defined in as
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 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 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 was designed to fulfill the requirement of unwinding a process other than self, the created can be used by a process to unwind
itself as well. Reasons for doing so include the unwinding of dynamically generated code or run-time instrumented code. In these situa-
tions, the client may need to register and callbacks.
frees memory allocated by or by To avoid memory leaks, an application that allocates an object should call when the is no longer needed.
APPLICATION USAGE
and are thread-safe.
RETURN VALUE
Pointer to struct
ERRORS
and can fail to create the unwind context data structure under the following conditions:
o Low memory conditions. The following Unwind library behavior is guaranteed in low memory conditions:
A failed construction of a creates for the client program enough of an _Unwind_Context object to support a call to the the stack unwind
library entry point which returns in the event of a failed construction or if the pointer is NULL (also an indicator of failed construc-
tion). Had the construction been successful, would have returned
Failed construction in extremely low memory conditions is communicated by returning NULL in effect setting the pointer to NULL. Subse-
quent calls to interface functions of return type return if the pointer is NULL.
EXAMPLES
Example 1
Allocate and initialize an for unwinding the currently running process:
Example 2
Allocate and initialize an for unwinding a process other than the running process:
AUTHOR
and were developed by HP.
SEE ALSO
U_STACK_TRACE(3X), _UNW_currentContext(3X), _UNW_getGR(3X), unwind(5).
Integrity Systems Only _UNW_createContextForSelf(3X)