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