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