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/Pgrab.3proc
+++ new/usr/src/man/man3proc/Pgrab.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.
↓ open down ↓ |
9 lines elided |
↑ open up ↑ |
10 10 .\"
11 11 .\"
12 12 .\" Copyright 2015 Joyent, Inc.
13 13 .\"
14 14 .Dd May 11, 2016
15 15 .Dt PGRAB 3PROC
16 16 .Os
17 17 .Sh NAME
18 18 .Nm Pgrab
19 19 .Nd grab and control a process
20 -.Sh SYNOPSIS
20 +.Sh LIBRARY
21 21 .Lb libproc
22 +.Sh SYNOPSIS
22 23 .In libproc.h
23 24 .Ft "struct ps_prochandle *"
24 25 .Fo Pgrab
25 26 .Fa "pid_t pid"
26 27 .Fa "int flags"
27 28 .Fa "int *perr"
28 29 .Fc
29 30 .Sh DESCRIPTION
30 31 The
31 32 .Fn Pgrab
32 33 function attempts to grab the process identified by
33 34 .Fa pid
34 35 and returns a handle to it that allows the process to be controlled,
35 36 interrogated, and manipulated.
36 37 This interface only works with processes that already exist.
37 38 Use
38 39 .Xr Pgrab_core 3PROC
39 40 for core files and
40 41 .Xr Pcreate 3PROC
41 42 to create processes.
42 43 .Pp
43 44 A grabbed process undergoes the following changes unless
44 45 .Fa flags
45 46 is set to the contrary:
46 47 .Bl -bullet -offset indent
47 48 .It
48 49 The process is stopped
49 50 .It
50 51 All other tracing flags are cleared
51 52 .It
52 53 The grab is exclusive.
53 54 If any existing handles to this process exist or anyone else is using the
54 55 underlying facilities of the /proc file system to control this process,
55 56 it will fail.
56 57 .It
57 58 Unless the process is already stopped, the
58 59 .Dv PR_RLC
59 60 flag is set indicating the process should run-on-last-close.
60 61 Allowing the process to resume running if its controlling process dies.
61 62 .El
62 63 .Pp
63 64 Grabbing a process is a
64 65 .Em destructive
65 66 action.
66 67 Stopping a process stops execution of all its threads.
67 68 The impact of stopping a process depends on the purpose of that process.
68 69 For example, if one stops a process that's primarily doing
69 70 computation, then its computation is delayed the entire time that it
70 71 is stopped.
71 72 However, if instead this is an active TCP server, then the accept backlog may
72 73 fill causing connection errors and potentially connection time out errors.
73 74 .Pp
74 75 Special care must be taken to ensure that a stopped process continues,
75 76 even if the controlling process terminates.
76 77 If the controlling process disables the
77 78 .Dv PR_RLC
78 79 flag or the process was already stopped, then the process remains
79 80 stopped after the controlling process terminates.
80 81 Exercise caution when changing this behavior.
81 82 .Pp
82 83 Many of these default behaviors can be controlled by passing values to
83 84 the
84 85 .Fa flags
85 86 argument.
86 87 Values for
87 88 .Fa flags
88 89 are constructed by a bitwise-inclusive-OR of flags from the following
89 90 list:
90 91 .Bl -tag -width Dv -offset indent
91 92 .It Dv PGRAB_RETAIN
92 93 Indicates that any existing tracing flags on
93 94 .Fa pid
94 95 should be retained.
95 96 If this flag is not specified, they will be cleared as part of creating the
96 97 .Sy libproc
97 98 handle for this process.
98 99 .Pp
99 100 Normally extant tracing flags are cleared when a process is grabbed.
100 101 .It Dv PGRAB_FORCE
101 102 Indicates that the process should not be grabbed exclusively.
102 103 Care should be taken with this option.
103 104 If other consumers are manipulating the process, then this may result in
104 105 surprising behavior as the process is being manipulated from multiple points of
105 106 control at the same time.
106 107 .Pp
107 108 Normally an attempt will be made to grab the process exclusively and
108 109 fail if it is already in use.
109 110 .It Dv PGRAB_RDONLY
110 111 Indicates that the process should be grabbed in a read-only fashion.
111 112 This implies that both the
112 113 .Dv PGRAB_RETAIN
113 114 and
114 115 .Dv PGRAB_NOSTOP
115 116 flags should be set.
116 117 If a process is opened read-only, then a caller can only read information about
117 118 a process and cannot manipulate it, change its current state, or inject systems
118 119 calls into it.
119 120 .Pp
120 121 Normally when a process is grabbed, it does so for both reading and writing.
121 122 .It Dv PGRAB_NOSTOP
122 123 Do not stop a process as it is grabbed.
123 124 Note, any extant tracing flags on the process will still be cleared unless the
124 125 .Dv PGRAB_RETAIN
125 126 flag has been set.
126 127 .Pp
127 128 Normally a process is stopped as a result of grabbing the process.
128 129 .El
129 130 .Pp
130 131 The
131 132 .Fa perr
132 133 argument must be a
133 134 .Pf non- Dv NULL
134 135 pointer which will store a more detailed error in the event that the
135 136 .Fn Pgrab
136 137 function fails.
137 138 A human-readable form of the error can be obtained with
138 139 .Xr Pgrab_error 3PROC .
139 140 .Pp
140 141 Once a caller is done with the library handle it should call
141 142 .Xr Prelease 3PROC
142 143 to release the grabbed process.
143 144 Failure to properly release the handle may leave a process stopped and interfere
144 145 with the ability of other software to obtain a handle.
145 146 .Ss Permissions
146 147 Unprivileged users may grab and control their own processes only if both
147 148 the user and group IDs of the target process match those of the calling
148 149 process.
149 150 In addition, the caller must have a super set of the target's privileges.
150 151 Processes with the
151 152 .Sy PRIV_PROC_OWNER
152 153 privilege may manipulate any process on the system, as long as it has an
153 154 equal privilege set.
154 155 For more details on the security and programming considerations, please see the
155 156 section
156 157 .Sy PROGRAMMING NOTES
157 158 in
158 159 .Xr proc 4 .
159 160 .Sh RETURN VALUES
160 161 Upon successful completion, the
161 162 .Fn Pgrab
162 163 function returns a control handle to the process.
163 164 Otherwise,
164 165 .Dv NULL
165 166 is returned with
166 167 .Fa perr
167 168 containing the error code.
168 169 .Sh ERRORS
169 170 The
170 171 .Fn Pgrab
171 172 function will fail if:
172 173 .Bl -tag -width Er
173 174 .It Er G_BUSY
174 175 The process
175 176 .Fa pid
176 177 is already being traced and the
177 178 .Dv PGRAB_FORCE
178 179 flag was not passed in
179 180 .Fa flags .
180 181 .It Er G_LP64
181 182 The calling process is a 32-bit process and process
182 183 .Fa pid
183 184 is 64-bit.
184 185 .It Er G_NOFD
185 186 Too many files are open.
186 187 This is logically equivalent to receiving
187 188 .Er EMFILE .
188 189 .It Er G_NOPROC
189 190 The process referred to by
190 191 .Fa pid
191 192 does not exist.
192 193 .It Er G_PERM
193 194 The calling process has insufficient permissions or privileges to open
194 195 the specified process.
195 196 See
196 197 .Sx Permissions
197 198 for more information.
198 199 .It Er G_SYS
199 200 The process referred to by
200 201 .Fa pid
201 202 is a system process and cannot be grabbed.
202 203 .It Er G_SELF
203 204 The process referred to by
204 205 .Fa pid
205 206 is the process ID of the caller and the
206 207 .Dv PGRAB_RDONLY
207 208 was not passed.
208 209 A process may only grab itself if it's read-only.
209 210 .It Er G_STRANGE
210 211 An unanticipated system error occurred while trying to grab the process
211 212 file and create the handle.
212 213 The value of
213 214 .Sy errno
214 215 indicates the system failure.
215 216 .It Er G_ZOMB
216 217 The process referred to by
217 218 .Fa pid
218 219 is a zombie and cannot be grabbed.
219 220 .El
220 221 .Sh INTERFACE STABILITY
221 222 .Sy Uncommitted
222 223 .Sh MT-LEVEL
223 224 .Sy MT-Safe
224 225 .Sh SEE ALSO
225 226 .Xr errno 3C ,
226 227 .Xr libproc 3LIB ,
227 228 .Xr Pfree 3PROC ,
228 229 .Xr Pgrab_core 3PROC ,
229 230 .Xr Pgrab_error 3PROC ,
230 231 .Xr Pgrab_file 3PROC ,
231 232 .Xr Prelease 3PROC
↓ open down ↓ |
200 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX