1 '\" te
2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH PGREP 1 "Dec 30, 2013"
7 .SH NAME
8 pgrep, pkill \- find or signal processes by name and other attributes
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBpgrep\fR [\fB-flvx\fR] [\fB-n\fR | \fB-o\fR] [\fB-d\fR \fIdelim\fR] [\fB-P\fR \fIppidlist\fR]
13 [\fB-g\fR \fIpgrplist\fR] [\fB-s\fR \fIsidlist\fR] [\fB-u\fR \fIeuidlist\fR] [\fB-U\fR \fIuidlist\fR]
14 [\fB-G\fR \fIgidlist\fR] [\fB-J\fR \fIprojidlist\fR] [\fB-t\fR \fItermlist\fR]
15 [\fB-T\fR \fItaskidlist\fR] [\fB-c\fR \fIctidlist\fR] [\fB-z\fR \fIzoneidlist\fR]
16 [\fIpattern\fR]
17 .fi
18
19 .LP
20 .nf
21 \fBpkill\fR [\fB-\fIsignal\fR\fR] [\fB-fvx\fR] [\fB-n\fR | \fB-o\fR] [\fB-P\fR \fIppidlist\fR]
22 [\fB-g\fR \fIpgrplist\fR] [\fB-s\fR \fIsidlist\fR] [\fB-u\fR \fIeuidlist\fR] [\fB-U\fR \fIuidlist\fR]
23 [\fB-G\fR \fIgidlist\fR] [\fB-J\fR \fIprojidlist\fR] [\fB-t\fR \fItermlist\fR]
24 [\fB-T\fR \fItaskidlist\fR] [\fB-c\fR \fIctidlist\fR] [\fB-z\fR \fIzoneidlist\fR]
25 [\fIpattern\fR]
26 .fi
27
28 .SH DESCRIPTION
29 .sp
30 .LP
31 The \fBpgrep\fR utility examines the active processes on the system and reports
32 the process \fBID\fRs of the processes whose attributes match the criteria
33 specified on the command line. Each process \fBID\fR is printed as a decimal
34 value and is separated from the next \fBID\fR by a delimiter string, which
35 defaults to a newline. For each attribute option, the user can specify a set of
36 possible values separated by commas on the command line. For example,
37 .sp
38 .in +2
39 .nf
40 \fBpgrep -G other,daemon\fR
41 .fi
42 .in -2
43 .sp
44
45 .sp
46 .LP
47 matches processes whose real group \fBID\fR is \fBother\fR \fBOR\fR
48 \fBdaemon\fR. If multiple criteria options are specified, \fBpgrep\fR matches
49 processes whose attributes match the logical \fBAND\fR of the criteria options.
50 For example,
51 .sp
52 .in +2
53 .nf
54 \fBpgrep -G other,daemon -U root,daemon\fR
55 .fi
56 .in -2
57 .sp
58
59 .sp
60 .LP
61 matches processes whose attributes are:
62 .br
63 .in +2
64 (real group \fBID\fR is \fBother\fR \fBOR\fR \fBdaemon\fR) \fBAND\fR
65 .in -2
66 .br
67 .in +2
68 (real user \fBID\fR is \fBroot\fR \fBOR\fR \fBdaemon\fR)
69 .in -2
70 .sp
71 .LP
72 \fBpkill\fR functions identically to \fBpgrep\fR, except that each matching
73 process is signaled as if by \fBkill\fR(1) instead of having its process
74 \fBID\fR printed. A signal name or number may be specified as the first command
75 line option to \fBpkill\fR.
76 .SH OPTIONS
77 .sp
78 .LP
79 The following options are supported:
80 .sp
81 .ne 2
82 .na
83 \fB\fB-c\fR \fIctidlist\fR\fR
84 .ad
85 .RS 17n
86 Matches only processes whose process contract ID is in the given list.
87 .RE
88
89 .sp
90 .ne 2
91 .na
92 \fB\fB-d\fR \fIdelim\fR\fR
93 .ad
94 .RS 17n
95 Specifies the output delimiter string to be printed between each matching
96 process \fBID\fR. If no \fB-d\fR option is specified, the default is a newline
97 character. The \fB-d\fR option is only valid when specified as an option to
98 \fBpgrep\fR.
99 .RE
100
101 .sp
102 .ne 2
103 .na
104 \fB\fB-f\fR\fR
105 .ad
106 .RS 17n
107 The regular expression \fIpattern\fR should be matched against the full process
108 argument string (obtained from the \fBpr_psargs\fR field of the
109 \fB/proc/\fInnnnn\fR/psinfo\fR file). If no \fB-f\fR option is specified, the
110 expression is matched only against the name of the executable file (obtained
111 from the \fBpr_fname\fR field of the \fB/proc/\fInnnnn\fR/psinfo\fR file).
112 .RE
113
114 .sp
115 .ne 2
116 .na
117 \fB\fB-g\fR \fIpgrplist\fR\fR
118 .ad
119 .RS 17n
120 Matches only processes whose process group \fBID\fR is in the given list. If
121 group 0 is included in the list, this is interpreted as the process group
122 \fBID\fR of the \fBpgrep\fR or \fBpkill\fR process.
123 .RE
124
125 .sp
126 .ne 2
127 .na
128 \fB\fB-G\fR \fIgidlist\fR\fR
129 .ad
130 .RS 17n
131 Matches only processes whose real group \fBID\fR is in the given list. Each
132 group \fBID\fR may be specified as either a group name or a numerical group
133 \fBID\fR.
134 .RE
135
136 .sp
137 .ne 2
138 .na
139 \fB\fB-J\fR \fIprojidlist\fR\fR
140 .ad
141 .RS 17n
142 Matches only processes whose project \fBID\fR is in the given list. Each
143 project \fBID\fR may be specified as either a project name or a numerical
144 project \fBID\fR.
145 .RE
146
147 .sp
148 .ne 2
149 .na
150 \fB\fB-l\fR\fR
151 .ad
152 .RS 17n
153 Long output format. Prints the process name along with the process \fBID\fR of
154 each matching process. The process name is obtained from the \fBpr_psargs\fR or
155 \fBpr_fname\fR field, depending on whether the \fB-f\fR option was specified
156 (see above). The \fB-l\fR option is only valid when specified as an option to
157 \fBpgrep\fR.
158 .RE
159
160 .sp
161 .ne 2
162 .na
163 \fB\fB-n\fR\fR
164 .ad
165 .RS 17n
166 Matches only the newest (most recently created) process that meets all other
167 specified matching criteria. Cannot be used with option \fB-o\fR.
168 .RE
169
170 .sp
171 .ne 2
172 .na
173 \fB\fB-o\fR\fR
174 .ad
175 .RS 17n
176 Matches only the oldest (earliest created) process that meets all other
177 specified matching criteria. Cannot be used with option \fB-n\fR.
178 .RE
179
180 .sp
181 .ne 2
182 .na
183 \fB\fB-P\fR \fIppidlist\fR\fR
184 .ad
185 .RS 17n
186 Matches only processes whose parent process \fBID\fR is in the given list.
187 .RE
188
189 .sp
190 .ne 2
191 .na
192 \fB\fB-s\fR \fIsidlist\fR\fR
193 .ad
194 .RS 17n
195 Matches only processes whose process session \fBID\fR is in in the given list.
196 If \fBID\fR 0 is included in the list, this is interpreted as the session
197 \fBID\fR of the \fBpgrep\fR or \fBpkill\fR process.
198 .RE
199
200 .sp
201 .ne 2
202 .na
203 \fB\fB-t\fR \fItermlist\fR\fR
204 .ad
205 .RS 17n
206 Matches only processes which are associated with a terminal in the given list.
207 Each terminal is specified as the suffix following "/dev/" of the terminal's
208 device path name in \fB/dev\fR. For example, \fBterm/a\fR or \fBpts/0\fR.
209 .RE
210
211 .sp
212 .ne 2
213 .na
214 \fB\fB-T\fR \fItaskidlist\fR\fR
215 .ad
216 .RS 17n
217 Matches only processes whose task \fBID\fR is in the given list. If \fBID\fR 0
218 is included in the list, this is interpreted as the task \fBID\fR of the
219 \fBpgrep\fR or \fBpkill\fR process.
220 .RE
221
222 .sp
223 .ne 2
224 .na
225 \fB\fB-u\fR \fIeuidlist\fR\fR
226 .ad
227 .RS 17n
228 Matches only processes whose effective user \fBID\fR is in the given list. Each
229 user \fBID\fR may be specified as either a login name or a numerical user
230 \fBID\fR.
231 .RE
232
233 .sp
234 .ne 2
235 .na
236 \fB\fB-U\fR \fIuidlist\fR\fR
237 .ad
238 .RS 17n
239 Matches only processes whose real user \fBID\fR is in the given list. Each user
240 \fBID\fR may be specified as either a login name or a numerical user \fBID\fR.
241 .RE
242
243 .sp
244 .ne 2
245 .na
246 \fB\fB-v\fR\fR
247 .ad
248 .RS 17n
249 Reverses the sense of the matching. Matches all processes \fBexcept\fR those
250 which meet the specified matching criteria.
251 .RE
252
253 .sp
254 .ne 2
255 .na
256 \fB\fB-x\fR\fR
257 .ad
258 .RS 17n
259 Considers only processes whose executable file name \fBexactly\fR matches the
260 specified \fIpattern\fR. The pattern match is considered to be exact when all
261 characters in the executable file name match the pattern.
262 .RE
263
264 .sp
265 .ne 2
266 .na
267 \fB\fB-z\fR \fIzoneidlist\fR\fR
268 .ad
269 .RS 17n
270 Matches only processes whose zone \fBID\fR is in the given list. Each zone
271 \fBID\fR may be specified as either a zone name or a numerical zone \fBID\fR.
272 This option is only useful when executed in the global zone. If the \fBpkill\fR
273 utility is used to send signals to processes in other zones, the process must
274 have asserted the \fB{PRIV_PROC_ZONE}\fR privilege (see \fBprivileges\fR(5)).
275 .RE
276
277 .sp
278 .ne 2
279 .na
280 \fB\fB-\fR\fIsignal\fR\fR
281 .ad
282 .RS 17n
283 Specifies the signal to send to each matched process. If no signal is
284 specified, \fBSIGTERM\fR is sent by default. The value of \fIsignal\fR can be
285 one of the symbolic names defined in \fBsignal.h\fR(3HEAD) without the
286 \fBSIG\fR prefix, or the corresponding signal number as a decimal value. The
287 \fB-\fR\fIsignal\fR option is only valid when specified as the first option to
288 \fBpkill\fR.
289 .RE
290
291 .SH OPERANDS
292 .sp
293 .LP
294 The following operand is supported:
295 .sp
296 .ne 2
297 .na
298 \fB\fIpattern\fR\fR
299 .ad
300 .RS 11n
301 Specifies an Extended Regular Expression (\fBERE\fR) pattern to match against
302 either the executable file name or full process argument string. See
303 \fBregex\fR(5) for a complete description of the \fBERE\fR syntax.
304 .RE
305
306 .SH EXAMPLES
307 .LP
308 \fBExample 1 \fRObtaining a Process ID
309 .sp
310 .LP
311 Obtain the process \fBID\fR of \fBsendmail\fR:
312
313 .sp
314 .in +2
315 .nf
316 example% \fBpgrep -x -u root sendmail\fR
317 283
318 .fi
319 .in -2
320 .sp
321
322 .LP
323 \fBExample 2 \fRTerminating a Process
324 .sp
325 .LP
326 Terminate the most recently created \fBxterm\fR:
327
328 .sp
329 .in +2
330 .nf
331 example% \fBpkill -n xterm\fR
332 .fi
333 .in -2
334 .sp
335
336 .SH EXIT STATUS
337 .sp
338 .LP
339 The following exit values are returned:
340 .sp
341 .ne 2
342 .na
343 \fB\fB0\fR\fR
344 .ad
345 .RS 5n
346 One or more processes were matched.
347 .RE
348
349 .sp
350 .ne 2
351 .na
352 \fB\fB1\fR\fR
353 .ad
354 .RS 5n
355 No processes were matched.
356 .RE
357
358 .sp
359 .ne 2
360 .na
361 \fB\fB2\fR\fR
362 .ad
363 .RS 5n
364 Invalid command line options were specified.
365 .RE
366
367 .sp
368 .ne 2
369 .na
370 \fB\fB3\fR\fR
371 .ad
372 .RS 5n
373 A fatal error occurred.
374 .RE
375
376 .SH FILES
377 .sp
378 .ne 2
379 .na
380 \fB\fB/proc/\fInnnnn\fR/psinfo\fR\fR
381 .ad
382 .RS 22n
383 Process information files
384 .RE
385
386 .SH SEE ALSO
387 .sp
388 .LP
389 \fBkill\fR(1), \fBproc\fR(1), \fBps\fR(1), \fBtruss\fR(1), \fBkill\fR(2),
390 \fBsignal.h\fR(3HEAD), \fBproc\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5),
391 \fBregex\fR(5), \fBzones\fR(5)
392 .SH NOTES
393 .sp
394 .LP
395 Both utilities match the \fBERE\fR \fIpattern\fR argument against either the
396 \fBpr_fname\fR or \fBpr_psargs\fR fields of the
397 \fB/proc/\fR\fInnnnn\fR\fB/psinfo\fR files. The lengths of these strings are
398 limited according to definitions in \fB<sys/procfs.h>\fR\&. Patterns which can
399 match strings longer than the current limits may fail to match the intended set
400 of processes.
401 .sp
402 .LP
403 If the \fIpattern\fR argument contains \fBERE\fR meta-characters which are also
404 shell meta-characters, it may be necessary to enclose the pattern with
405 appropriate shell quotes.
406 .sp
407 .LP
408 Defunct processes are never matched by either \fBpgrep\fR or \fBpkill\fR.
409 .sp
410 .LP
411 The current \fBpgrep\fR or \fBpkill\fR process will never consider itself a
412 potential match.