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