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 SYNOPSIS
21.Lb libproc
22.In libproc.h
23.Ft int
24.Fo Pstack_iter
25.Fa "struct ps_prochandle *P"
26.Fa "const prgregset_t regs"
27.Fa "proc_stack_f *func"
28.Fa "void *data"
29.Fc
30.Sh DESCRIPTION
31The
32.Fn Pstack_iter
33function iterates over the stack frames in the process
34.Fa P
35starting at the point defined by
36.Fa regs .
37.Pp
38For each valid stack frame encountered, the callback function
39.Fa func
40is invoked with
41.Fa data
42passed as argument. The full signature of
43.Ft proc_stack_f
44is defined in
45.Xr libproc 3LIB .
46With each callback, a register set, argument set, and argument count
47will be provided. In that register set, only a subset of the registers
48will be valid, which include the frame pointer, program counter, and on
49SPARC systems, the next program counter. These registers can be accessed
50with the constants
51.Sy R_FP ,
52.Sy R_PC ,
53and
54.Sy R_nPC
55respectively. These correspond to the registers
56.Em %ebp
57and
58.Em %eip
59on i386,
60.Em %rbp
61and
62.Em %rip
63on amd64,
64.Em %fp ,
65.Em %pc ,
66and
67.Em %npc
68on both SPARC and SPARCv9.
69.Pp
70Callers will receive a callback for the first stack frame indicated by
71.Fa regs
72and then will receive a subsequent callback for each caller of that
73frame until no such frame can be found. Stack frames that logically come
74after the frame indicated by
75.Fa regs
76will not receive callbacks.
77.Pp
78The compiler can either facilitate or stymie the iteration of the
79stack. Programs that have been compiled in such a way as to omit the
80frame pointer will result in truncated stacks. Similarly, if the initial
81set of registers passed in via
82.Fa regs
83is invalid, then the ability to iterate the stack will be limited.
84The return value of
85.Fa func
86controls whether or not iteration continues. If
87.Fa func
88returns
89.Sy 0
90then iteration continues. However, if
91.Fa func
92returns non-zero, then iteration will halt and that value will be used
93as the return value of the
94.Fn Pstack_iter
95function. Because
96.Fn Pstack_iter
97returns
98.Sy -1
99on internal failure it is recommended the callback function not return
100.Sy -1
101to indicate an error. Thus the caller may distinguish between the
102failure of the callback function and the failure of the
103.Fn Pstack_iter
104function.
105.Sh RETURN VALUES
106Upon successful completion, the
107.Fn Pstack_iter
108function returns
109.Sy 0.
110If there was an internal error then
111.Sy -1
112is returned. Otherwise, if the callback function
113.Fa func
114returns non-zero, then its return value will be returned instead.
115.Sh INTERFACE STABILITY
116.Sy Uncommitted
117.Sh MT-LEVEL
118See
119.Sy LOCKING
120in
121.Xr libproc 3LIB .
122.Sh SEE ALSO
123.Xr libproc 3LIB ,
124.Xr proc 4
125