1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source. A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PLWP_STACK 3PROC
.Os
.Sh NAME
.Nm Plwp_stack ,
.Nm Plwp_alt_stack ,
.Nm Plwp_main_stack ,
.Nm Lstack ,
.Nm Lalt_stack ,
.Nm Lmain_stack
.Nd get thread stack information
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft int
.Fo Plwp_stack
.Fa "struct ps_prochandle *P"
.Fa "lwpid_t lwpid"
.Fa "stack_t *stkp"
.Fc
.Ft int
.Fo Plwp_alt_stack
.Fa "struct ps_prochandle *P"
.Fa "lwpid_t lwpid"
.Fa "stack_t *stkp"
.Fc
.Ft int
.Fo Plwp_main_stack
.Fa "struct ps_prochandle *P"
.Fa "lwpid_t lwpid"
.Fa "stack_t *stkp"
.Fc
.Ft int
.Fo Lalt_stack
.Fa "struct ps_lwphandle *L"
.Fa "stack_t *stkp"
.Fc
.Ft int
.Fo Lmain_stack
.Fa "struct ps_lwphandle *L"
.Fa "stack_t *stkp"
.Fc
.Ft int
.Fo Lstack
.Fa "struct ps_lwphandle *L"
.Fa "stack_t *stkp"
.Fc
.Sh DESCRIPTION
The
.Fn Plwp_stack ,
.Fn Plwp_alt_stack ,
and
.Fn Plwp_main_stack
functions obtain information about the size and address of the stacks
for the thread identified by
.Fa lwpid
in the process handle
.Fa P .
.Pp
Each thread in a process has its own stack which is used both for
maintaining function call sequences and the storing of local variables.
A thread may also configure a different stack to handle specific
signals.
This stack is often called the
.Em alternate stack .
Whether or not the alternate stack is used may be controlled through the
.Xr sigaction 2
and
.Xr sigaltstack 2
functions .
.Pp
The
.Fn Plwp_stack
function fills in
.Fa stkp
with the information about the thread's currently executing stack,
whether the alternate or main one.
.Pp
The
.Fn Plwp_alt_stack
function fills in
.Fa stkp
with the information about the thread's alternate stack, if it's
configured.
.Pp
The
.Fn Plwp_main_stack
function fills in
.Fa stkp
with the information about the thread's main stack, regardless of if there
is an alternate stack or it is executing one.
.Pp
Process handles that refer to files, obtained through
.Xr Pgrab_file 3PROC ,
do not have any stack information and these functions will always fail
on them.
.Pp
The
.Fn Lalt_stack ,
.Fn Lmain_stack ,
and
.Fn Lstack
functions are identical to the
.Fn Plwp_alt_stack ,
.Fn Plwp_main_stack ,
and
.Fn Plwp_main_stack
functions, except rather than specifying a thread to operate on, they
operate on the thread handle
.Fa L ,
which specifies the thread to operate on.
.Sh RETURN VALUES
Upon successful completion, the
.Fn Plwp_stack ,
.Fn Plwp_alt_stack ,
.Fn Plwp_main_stack ,
.Fn Lalt_stack ,
.Fn Lmain_stack ,
and
.Fn Lstack
functions return
.Sy 0
and fills in
.Fa stkp
with information about the appropriate stack.
Otherwise,
.Sy -1
is returned,
.Sy errno
is updated with the error, and
.Fa stkp
is not modified.
.Sh ERRORS
For a full list of possible errors also see the
.Sy DIAGNOSTICS
section in
.Xr proc 4 .
.Pp
The
.Fn Plwp_stack ,
.Fn Plwp_alt_stack ,
and
.Fn Plwp_main_stack
function will fail if:
.Bl -tag -width Er
.It Er ENODATA
The process handle
.Fa P
refers to a grabbed file, not an active process or core.
.It Er EINVAL
The process handle
.Fa P
refers to a core file and the specified thread does not exist.
.It Er ENOENT
The process handle
.Fa P
refers to an active process and the specified thread does not exist.
.El
.Pp
The
.Fn Plwp_alt_stack
and
.Fn Lalt_stack
functions will fail if:
.Bl -tag -width Er
.It Er ENODATA
The thread identified by
.Fa lwpid
did not have an alternate stack enabled.
.El
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr sigaltstack 2 ,
.Xr libproc 3LIB ,
.Xr proc 4
|
