HP-UX Reference (11i v2 03/08) - 3 Library Functions N-Z (vol 7)

u
uwx(3X) uwx(3X)
(Itanium(R)-based System Only)
NAME
uwx - Unwind Express library
SYNOPSIS
#include <uwx.h>
#include <uwx_self.h>
struct uwx_env *uwx_init();
struct uwx_self_info *uwx_self_init_info(struct uwx_env *env);
int uwx_register_callbacks(
struct uwx_env *env,
intptr_t tok,
copy_cb copyin,
lookupip_cb lookupip
);
int uwx_self_init_context(struct uwx_env *env);
int uwx_init_context(
struct uwx_env *env,
uint64_t ip,
uint64_t sp,
uint64_t bsp,
uint64_t cfm
);
int uwx_step(struct uwx_env *env);
int uwx_get_reg(struct uwx_env *env, int regid, uint64_t *valp);
int uwx_get_abi_context_code(struct uwx_env *env);
int uwx_self_do_context_frame(
struct uwx_env *env,
struct uwx_self_info *info
);
int uwx_free(struct uwx_env *env);
int uwx_self_free_info(struct uwx_self_info *info);
int uwx_register_alloc_cb(alloc_cb alt_alloc, free_cb alt_free);
DESCRIPTION
The Unwind Express library is a lightweight library for unwinding a process stack on Itanium-based sys-
tem. 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:
HP-UX 11i Version 2: August 2003 1 Hewlett-Packard Company Section 31111