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 "Jan 17, 2014"
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 Matches only processes whose executable file name (ignoring any path)
260 \fBexactly\fR matches the specified \fIpattern\fR. However, when used with -f,
261 the \fIpattern\fR should be matched against the full process argument
262 string. For example if there exists a process `/bin/ls /home' then:
263 .sp
264 .in +2
265 .nf
266 $ pgrep -x ls
267 1780
268 $ pgrep -x -f '/bin/ls /home'
269 1780
270 $ pgrep -x -f '/bin/ls.*'
271 1780
272 $ pgrep -x /bin/ls
273 $ pgrep -x -f 'ls /home'
274 $ pgrep -x -f /bin/ls
275 $
276
277 .fi
278 .in -2
279 .sp
280
281 .RE
282
283 .sp
284 .ne 2
285 .na
286 \fB\fB-z\fR \fIzoneidlist\fR\fR
287 .ad
288 .RS 17n
289 Matches only processes whose zone \fBID\fR is in the given list. Each zone
290 \fBID\fR may be specified as either a zone name or a numerical zone \fBID\fR.
291 This option is only useful when executed in the global zone. If the \fBpkill\fR
292 utility is used to send signals to processes in other zones, the process must
293 have asserted the \fB{PRIV_PROC_ZONE}\fR privilege (see \fBprivileges\fR(5)).
294 .RE
295
296 .sp
297 .ne 2
298 .na
299 \fB\fB-\fR\fIsignal\fR\fR
300 .ad
301 .RS 17n
302 Specifies the signal to send to each matched process. If no signal is
303 specified, \fBSIGTERM\fR is sent by default. The value of \fIsignal\fR can be
304 one of the symbolic names defined in \fBsignal.h\fR(3HEAD) without the
305 \fBSIG\fR prefix, or the corresponding signal number as a decimal value. The
306 \fB-\fR\fIsignal\fR option is only valid when specified as the first option to
307 \fBpkill\fR.
308 .RE
309
310 .SH OPERANDS
311 .sp
312 .LP
313 The following operand is supported:
314 .sp
315 .ne 2
316 .na
317 \fB\fIpattern\fR\fR
318 .ad
319 .RS 11n
320 Specifies an Extended Regular Expression (\fBERE\fR) pattern to match against
321 either the executable file name or full process argument string. See
322 \fBregex\fR(5) for a complete description of the \fBERE\fR syntax.
323 .RE
324
325 .SH EXAMPLES
326 .LP
327 \fBExample 1 \fRObtaining a Process ID
328 .sp
329 .LP
330 Obtain the process \fBID\fR of \fBsendmail\fR:
331
332 .sp
333 .in +2
334 .nf
335 example% \fBpgrep -x -u root sendmail\fR
336 283
337 .fi
338 .in -2
339 .sp
340
341 .LP
342 \fBExample 2 \fRTerminating a Process
343 .sp
344 .LP
345 Terminate the most recently created \fBxterm\fR:
346
347 .sp
348 .in +2
349 .nf
350 example% \fBpkill -n xterm\fR
351 .fi
352 .in -2
353 .sp
354
355 .SH EXIT STATUS
356 .sp
357 .LP
358 The following exit values are returned:
359 .sp
360 .ne 2
361 .na
362 \fB\fB0\fR\fR
363 .ad
364 .RS 5n
365 One or more processes were matched.
366 .RE
367
368 .sp
369 .ne 2
370 .na
371 \fB\fB1\fR\fR
372 .ad
373 .RS 5n
374 No processes were matched.
375 .RE
376
377 .sp
378 .ne 2
379 .na
380 \fB\fB2\fR\fR
381 .ad
382 .RS 5n
383 Invalid command line options were specified.
384 .RE
385
386 .sp
387 .ne 2
388 .na
389 \fB\fB3\fR\fR
390 .ad
391 .RS 5n
392 A fatal error occurred.
393 .RE
394
395 .SH FILES
396 .sp
397 .ne 2
398 .na
399 \fB\fB/proc/\fInnnnn\fR/psinfo\fR\fR
400 .ad
401 .RS 22n
402 Process information files
403 .RE
404
405 .SH SEE ALSO
406 .sp
407 .LP
408 \fBkill\fR(1), \fBproc\fR(1), \fBps\fR(1), \fBtruss\fR(1), \fBkill\fR(2),
409 \fBsignal.h\fR(3HEAD), \fBproc\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5),
410 \fBregex\fR(5), \fBzones\fR(5)
411 .SH NOTES
412 .sp
413 .LP
414 Both utilities match the \fBERE\fR \fIpattern\fR argument against either the
415 \fBpr_fname\fR or \fBpr_psargs\fR fields of the
416 \fB/proc/\fR\fInnnnn\fR\fB/psinfo\fR files. The lengths of these strings are
417 limited according to definitions in \fB<sys/procfs.h>\fR\&. Patterns which can
418 match strings longer than the current limits may fail to match the intended set
419 of processes.
420 .sp
421 .LP
422 If the \fIpattern\fR argument contains \fBERE\fR meta-characters which are also
423 shell meta-characters, it may be necessary to enclose the pattern with
424 appropriate shell quotes.
425 .sp
426 .LP
427 Defunct processes are never matched by either \fBpgrep\fR or \fBpkill\fR.
428 .sp
429 .LP
430 The current \fBpgrep\fR or \fBpkill\fR process will never consider itself a
431 potential match.