_UNW_createContextForSelf(3X)_UNW_createContextForSelf(3X)NAME_UNW_createContextForSelf(), _UNW_createContext(), _UNW_destroyCon‐
text() - allocate and deallocate unwind library data structure
SYNOPSISDESCRIPTION
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 pointers. 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 qual‐
ified 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
associated with the unwind header and unwind information for the
kernel's signal handler wrapper function 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 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 target 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 values 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 exam‐
ple, can use ident to identify separate threads within the tar‐
get 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 situations, 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 fol‐
lowing conditions:
· 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 construc‐
tion or if the pointer is NULL (also an indicator of failed con‐
struction). Had the construction been successful, would have
returned
Failed construction in extremely low memory conditions is communi‐
cated by returning NULL in effect setting the pointer to NULL. Sub‐
sequent 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 run‐
ning process:
AUTHOR
and were developed by HP.
SEE ALSOU_STACK_TRACE(3X), _UNW_currentContext(3X), _UNW_getGR(3X), unwind(5).
Integrity Systems Onl_UNW_createContextForSelf(3X)
