uwx.3x (2010 09)

u
uwx(3X) uwx(3X)
(Integrity Systems Only)
NAME
uwx() - Unwind Express Library
SYNOPSIS
cc [flag... ] file...
-lunwind [library ] ...
#include <uwx.h>
#include <uwx_self.h>
DESCRIPTION
The Unwind Express Library is a lightweight library for unwinding a process stack on Integrity systems.
It may be used for "self-unwinding," where a thread traces back through its own stack, or for "cross-
unwinding," where a debugger or other tool can examine the stack of another target thread or process.
To use the Unwind Express Library, link your application with the
-lunwind option on the compiler or
linker command line. All source code should include the header file
<uwx.h>. Source code that uses the
library for self-unwinding should also include the header file
<uwx_self.h>
.
The Unwind Express Library maintains its entire state within a single unwind environment structure.
To unwind a stack, the client application provides an initial context to the unwind environment, then
unwinds the stack one frame at a time. After reaching the bottom of the stack, the unwind environment
may be reused for a subsequent unwind operation simply by providing a new initial context, or it may be
discarded, freeing the memory it was using.
A client application may create any number of separate unwind environments, and each one will operate
independently of and completely unaffected by the others.
The Unwind Express Library consists of a core unwind engine that can be adapted to specific environ-
ments through the use of callback routines. For self-unwinding, a set of standard callback routines are
provided as part of the library. For cross-unwinding, the client must supply callback routines to interface
the unwind engine to the target thread or process.
Self-Unwinding
To prepare for self-unwinding, a client application must perform the following steps to create and initial-
ize a new unwind environment:
1. Call
uwx_init() to create a new unwind environment. The return value is a pointer to the
unwind environment.
2. Call
uwx_self_init_info()
to initialize the standard callback environment. The return value
is a pointer to the callback info structure.
3. Call
uwx_register_callbacks()
to register the standard callbacks: uwx_self_copyin()
and uwx_self_lookupip()
.
The steps above may be performed at any time in advance of performing a stack unwind. The resulting
unwind environment can then be used repeatedly.
To perform a stack unwind from some point in the application, the client must perform the following
steps:
1. Call
uwx_self_init_context() to provide the current thread’s context as a starting point for
unwinding. The stack frame for the caller of this function becomes the current frame.
2. Call
uwx_step() to step back one frame in the call stack. After each step, the new frame becomes
the current frame, and the client may call uwx_get_reg() to obtain values from the recon-
structed context for the new frame. This step can be repeated until the process reaches the bottom
of the stack or a signal context frame.
3. When a signal context frame is reached, the client may call
uwx_self_do_context_frame()
to provide a new starting point for unwinding based on the context at the point of interruption. The
stack frame for the function interrupted by the signal becomes the current frame. Subsequent calls
to uwx_step() will proceed from there.
Cross-Unwinding
To prepare for cross-unwinding, a client application must perform the following steps to create and ini-
tialize a new unwind environment:
1. Call uwx_init() to create a new unwind environment. The return value is a pointer to the
unwind environment.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1