Tribblix: manual page: Pstack

PSTACK_ITER(3PROC) Process Control Library Functions PSTACK_ITER(3PROC)

NAME

Pstack_iter - iterate process stack frames

LIBRARY

Process Control Library (libproc, -lproc)

SYNOPSIS

#include <libproc.h>

int
Pstack_iter(struct ps_prochandle *P, const prgregset_t regs,
proc_stack_f *func, void *data);

DESCRIPTION

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.

RETURN VALUES

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.

INTERFACE STABILITY