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 02, 2020
15.Dt PSTOPSTATUS 3PROC
16.Os
17.Sh NAME
18.Nm Pdstop ,
19.Nm Pstopstatus ,
20.Nm Pstop ,
21.Nm Pwait ,
22.Nm Ldstop ,
23.Nm Lstop ,
24.Nm Lwait
25.Nd process and thread stop operations
26.Sh LIBRARY
27.Lb libproc
28.Sh SYNOPSIS
29.In libproc.h
30.Ft int
31.Fo Pdstop
32.Fa "struct ps_prochandle *P"
33.Fc
34.Ft int
35.Fo Pstopstatus
36.Fa "struct ps_prochandle *P"
37.Fa "long request"
38.Fa "uint_t msec"
39.Fc
40.Ft int
41.Fo Pstop
42.Fa "struct ps_prochandle *P"
43.Fa "uint_t msec"
44.Fc
45.Ft int
46.Fo Pwait
47.Fa "struct ps_prochandle *P"
48.Fa "uint_t msec"
49.Fc
50.Ft int
51.Fo Ldstop
52.Fa "struct ps_lwphandle *L"
53.Fc
54.Ft int
55.Fo Lstop
56.Fa "struct ps_lwphandle *L"
57.Fa "uint_t msec"
58.Fc
59.Ft int
60.Fo Lwait
61.Fa "struct ps_lwphandle *L"
62.Fa "uint_t msec"
63.Fc
64.Sh DESCRIPTION
65The
66.Fn Pstopstatus
67function allows the caller to stop and optionally wait for the process
68handle referred to by
69.Fa P
70to be stopped.
71Stopping a process causes all of its threads to stop execution.
72Where in their execution the threads will halt is not defined.
73Threads may be resumed with
74.Xr Psetrun 3PROC
75and
76.Xr prun 1 .
77.Pp
78The
79.Fa request
80argument should be one of the following symbols:
81.Bl -tag -width Dv -offset indent
82.It Dv PCSTOP
83Stop the process; wait for completion before returning.
84.It Dv PCDSTOP
85Stop the process; do not wait for completion before returning.
86That is, the stopping of the process is performed asynchronously in
87relation to the caller.
88.It Dv PCWSTOP
89Do not direct the process to stop; simply wait for it to stop.
90.It Dv PCNULL
91Do not direct the process to stop; simply refreshes the state of the
92process.
93.El
94.Pp
95Both the
96.Dv PCSTOP
97and
98.Dv PCWSTOP
99requests allow an upper bound on the amount of time to wait for the
100process to stop.
101The
102.Fa msec
103argument indicates the number of milliseconds to wait for the stop to
104complete.
105If the value of
106.Fa msec
107is
108.Sy 0 ,
109then it will wait forever.
110Callers should pass
111.Sy 0
112for
113.Fa msec
114when the request is
115.Dv PCDSTOP
116or
117.Dv PCNULL .
118.Pp
119When a non-zero timeout is specified, the process may or may not be
120stopped upon return.
121The return value does not reflect the current state of the process.
122For example, if the timeout expires during a
123.Fa PCWSTOP
124request, the return value will be
125.Sy 0
126regardless of the actual state of the process.
127.Pp
128Only active processes may be stopped.
129Handles that refer to core files, zombie processes, or files cannot be used;
130unless the value of
131.Fa request
132is set to
133.Dv PCNULL .
134.Pp
135The
136.Fn Pstop
137function is is equivalent to calling the
138.Fn Pstopstatus
139function with the request set to
140.Dv PCSTOP .
141.Pp
142The
143.Fn Pwait
144function is is equivalent to calling the
145.Fn Pstopstatus
146function with the request set to
147.Dv PCWSTOP .
148.Pp
149The
150.Fn Pdstop
151function is is equivalent to calling the
152.Fn Pstopstatus
153function with the request set to
154.Dv PCDSTOP .
155.Pp
156The
157.Fn Ldstop ,
158.Fn Lstop ,
159and
160.Fn Lwait
161functions are equivalent to the
162.Fn Pdstop ,
163.Fn Pstop ,
164and
165.Fn Pwait
166functions, respectively.
167Except, rather than operating on a process, they operate on the thread handle
168.Fa L .
169A call to
170.Fn Lstop
171stops only a single thread; whereas
172.Fn Pstop
173stops every thread in the process.
174.Sh RETURN VALUES
175Upon successful completion, the
176.Fn Pdstop ,
177.Fn Pstopstatus ,
178.Fn Pstop ,
179.Fn Pwait ,
180.Fn Ldstop ,
181.Fn Lstop ,
182and
183.Fn Lwait
184functions return
185.Sy 0 .
186Otherwise,
187.Sy -1
188is returned and
189.Dv errno
190is set to indicate the error that occurred.
191.Sh ERRORS
192For a full list of possible errors see the
193.Sy DIAGNOSTICS
194section in
195.Xr proc 5 .
196.Pp
197The
198.Fn Pdstop ,
199.Fn Pstopstatus ,
200.Fn Pstop ,
201.Fn Pwait ,
202.Fn Ldstop ,
203.Fn Lstop ,
204and
205.Fn Lwait
206functions will fail if:
207.Bl -tag -width Er
208.It Er EAGAIN
209Control over the handle
210.Fa P
211was lost.
212Callers should call
213.Xr Preopen 3PROC .
214For more information on losing control, see
215.Sy PROGRAMMING NOTES
216in
217.Xr proc 5 .
218.It Er ENOENT
219The request was not
220.Dv PCNULL
221and the process handle
222.Fa P
223does not refer to an active process, but refers to a core file, a zombie
224process, or a file.
225.It Er EINVAL
226.Fa request
227is not valid or the process is in an unknown state.
228.It Er EPROTO
229A fatal protocol error occurred and the process could not be stopped.
230.El
231.Sh INTERFACE STABILITY
232.Sy Uncommitted
233.Sh MT-LEVEL
234See
235.Sy LOCKING
236in
237.Xr libproc 3LIB .
238.Sh SEE ALSO
239.Xr libproc 3LIB ,
240.Xr Lgrab 3PROC ,
241.Xr Pcreate 3PROC ,
242.Xr Pgrab 3PROC ,
243.Xr Pgrab_core 3PROC ,
244.Xr Pgrab_file 3PROC ,
245.Xr proc 5
246