1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2015 Joyent, Inc.
13.\"
14.Dd May 11, 2016
15.Dt PSTACK_ITER 3PROC
16.Os
17.Sh NAME
18.Nm Pstack_iter
19.Nd iterate process stack frames
20.Sh LIBRARY
21.Lb libproc
22.Sh SYNOPSIS
23.In libproc.h
24.Ft int
25.Fo Pstack_iter
26.Fa "struct ps_prochandle *P"
27.Fa "const prgregset_t regs"
28.Fa "proc_stack_f *func"
29.Fa "void *data"
30.Fc
31.Sh DESCRIPTION
32The
33.Fn Pstack_iter
34function iterates over the stack frames in the process
35.Fa P
36starting at the point defined by
37.Fa regs .
38.Pp
39For each valid stack frame encountered, the callback function
40.Fa func
41is invoked with
42.Fa data
43passed as argument.
44The full signature of
45.Ft proc_stack_f
46is defined in
47.Xr libproc 3LIB .
48With each callback, a register set, argument set, and argument count
49will be provided.
50In that register set, only a subset of the registers will be valid, which
51include the frame pointer, program counter, and on SPARC systems, the next
52program counter.
53These registers can be accessed with the constants
54.Sy R_FP ,
55.Sy R_PC ,
56and
57.Sy R_nPC
58respectively.
59These correspond to the registers
60.Em %ebp
61and
62.Em %eip
63on i386,
64.Em %rbp
65and
66.Em %rip
67on amd64,
68.Em %fp ,
69.Em %pc ,
70and
71.Em %npc
72on both SPARC and SPARCv9.
73.Pp
74Callers will receive a callback for the first stack frame indicated by
75.Fa regs
76and then will receive a subsequent callback for each caller of that
77frame until no such frame can be found.
78Stack frames that logically come after the frame indicated by
79.Fa regs
80will not receive callbacks.
81.Pp
82The compiler can either facilitate or stymie the iteration of the stack.
83Programs that have been compiled in such a way as to omit the frame pointer will
84result in truncated stacks.
85Similarly, if the initial set of registers passed in via
86.Fa regs
87is invalid, then the ability to iterate the stack will be limited.
88The return value of
89.Fa func
90controls whether or not iteration continues.
91If
92.Fa func
93returns
94.Sy 0
95then iteration continues.
96However, if
97.Fa func
98returns non-zero, then iteration will halt and that value will be used
99as the return value of the
100.Fn Pstack_iter
101function.
102Because
103.Fn Pstack_iter
104returns
105.Sy -1
106on internal failure it is recommended the callback function not return
107.Sy -1
108to indicate an error.
109Thus the caller may distinguish between the failure of the callback function and
110the failure of the
111.Fn Pstack_iter
112function.
113.Sh RETURN VALUES
114Upon successful completion, the
115.Fn Pstack_iter
116function returns
117.Sy 0.
118If there was an internal error then
119.Sy -1
120is returned.
121Otherwise, if the callback function
122.Fa func
123returns non-zero, then its return value will be returned instead.
124.Sh INTERFACE STABILITY
125.Sy Uncommitted
126.Sh MT-LEVEL
127See
128.Sy LOCKING
129in
130.Xr libproc 3LIB .
131.Sh SEE ALSO
132.Xr libproc 3LIB ,
133.Xr proc 5
134