Pstack_iter —
iterate process stack frames
Process Control Library (libproc, -lproc)
#include
<libproc.h>
int
Pstack_iter(
struct
ps_prochandle *P,
const prgregset_t
regs,
proc_stack_f *func,
void *data);
The
Pstack_iter() function iterates over the
stack frames in the process
P starting at the
point defined by
regs.
For each valid stack frame encountered, the callback function
func is invoked with
data passed as argument. The full signature
of
proc_stack_f is defined in
libproc(3LIB). With each callback, a register
set, argument set, and argument count will be provided. In that register set,
only a subset of the registers will be valid, which include the frame pointer,
program counter, and on SPARC systems, the next program counter. These
registers can be accessed with the constants
R_FP,
R_PC, and
R_nPC respectively. These correspond to the
registers
%ebp and
%eip on i386,
%rbp
and
%rip on amd64,
%fp,
%pc, and
%npc on both SPARC and SPARCv9.
Callers will receive a callback for the first stack frame indicated by
regs and then will receive a subsequent
callback for each caller of that frame until no such frame can be found. Stack
frames that logically come after the frame indicated by
regs will not receive callbacks.
The compiler can either facilitate or stymie the iteration of the stack.
Programs that have been compiled in such a way as to omit the frame pointer
will result in truncated stacks. Similarly, if the initial set of registers
passed in via
regs is invalid, then the
ability to iterate the stack will be limited. The return value of
func controls whether or not iteration
continues. If
func returns
0 then iteration continues. However, if
func returns non-zero, then iteration will
halt and that value will be used as the return value of the
Pstack_iter() function. Because
Pstack_iter() returns
-1 on internal failure it is recommended the
callback function not return
-1 to indicate an
error. Thus the caller may distinguish between the failure of the callback
function and the failure of the
Pstack_iter() function.
Upon successful completion, the
Pstack_iter()
function returns
0. If there was an internal
error then
-1 is returned. Otherwise, if the
callback function
func returns non-zero, then
its return value will be returned instead.
Uncommitted
See
LOCKING in
libproc(3LIB).
libproc(3LIB),
proc(4)