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