pkill/pwait: tweak manuals
[dragonfly.git] / usr.bin / pkill / pkill.1
1 .\"     $NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant Exp $
2 .\"
3 .\" $FreeBSD: head/bin/pkill/pkill.1 254134 2013-08-09 08:38:51Z trasz $
4 .\"
5 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
6 .\" All rights reserved.
7 .\"
8 .\" This code is derived from software contributed to The NetBSD Foundation
9 .\" by Andrew Doran.
10 .\"
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
13 .\" are met:
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\"    notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\"    notice, this list of conditions and the following disclaimer in the
18 .\"    documentation and/or other materials provided with the distribution.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
21 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
24 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
25 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
26 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
29 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 .\" POSSIBILITY OF SUCH DAMAGE.
31 .\"
32 .Dd August 9, 2013
33 .Dt PKILL 1
34 .Os
35 .Sh NAME
36 .Nm pgrep ,
37 .Nm pkill
38 .Nd find or signal processes by name
39 .Sh SYNOPSIS
40 .Nm pgrep
41 .Op Fl LSafilnoqvx
42 .Op Fl F Ar pidfile
43 .Op Fl G Ar gid
44 .Op Fl M Ar core
45 .Op Fl N Ar system
46 .Op Fl P Ar ppid
47 .Op Fl U Ar uid
48 .Op Fl c Ar class
49 .Op Fl d Ar delim
50 .Op Fl g Ar pgrp
51 .Op Fl j Ar jid
52 .Op Fl s Ar sid
53 .Op Fl t Ar tty
54 .Op Fl u Ar euid
55 .Ar pattern ...
56 .Nm pkill
57 .Op Fl Ar signal
58 .Op Fl ILafilnovx
59 .Op Fl F Ar pidfile
60 .Op Fl G Ar gid
61 .Op Fl M Ar core
62 .Op Fl N Ar system
63 .Op Fl P Ar ppid
64 .Op Fl U Ar uid
65 .Op Fl c Ar class
66 .Op Fl g Ar pgrp
67 .Op Fl j Ar jid
68 .Op Fl s Ar sid
69 .Op Fl t Ar tty
70 .Op Fl u Ar euid
71 .Ar pattern ...
72 .Sh DESCRIPTION
73 The
74 .Nm pgrep
75 command searches the process table on the running system and prints the
76 process IDs of all processes that match the criteria given on the command
77 line.
78 .Pp
79 The
80 .Nm pkill
81 command searches the process table on the running system and signals all
82 processes that match the criteria given on the command line.
83 .Pp
84 The following options are available:
85 .Bl -tag -width ".Fl F Ar pidfile"
86 .It Fl F Ar pidfile
87 Restrict matches to a process whose PID is stored in the
88 .Ar pidfile
89 file.
90 .It Fl G Ar gid
91 Restrict matches to processes with a real group ID in the comma-separated
92 list
93 .Ar gid .
94 .It Fl I
95 Request confirmation before attempting to signal each process.
96 .It Fl L
97 The
98 .Ar pidfile
99 file given for the
100 .Fl F
101 option must be locked with the
102 .Xr flock 2
103 syscall or created with
104 .Xr pidfile 3 .
105 .It Fl M Ar core
106 Extract values associated with the name list from the specified core
107 instead of the currently running system.
108 .It Fl N Ar system
109 Extract the name list from the specified system instead of the default,
110 which is the kernel image the system has booted from.
111 .It Fl P Ar ppid
112 Restrict matches to processes with a parent process ID in the
113 comma-separated list
114 .Ar ppid .
115 .It Fl S
116 Search also in system processes (kernel threads).
117 .It Fl U Ar uid
118 Restrict matches to processes with a real user ID in the comma-separated
119 list
120 .Ar uid .
121 .It Fl d Ar delim
122 Specify a delimiter to be printed between each process ID.
123 The default is a newline.
124 This option can only be used with the
125 .Nm pgrep
126 command.
127 .It Fl a
128 Include process ancestors in the match list.
129 By default, the current
130 .Nm pgrep
131 or
132 .Nm pkill
133 process and all of its ancestors are excluded (unless
134 .Fl v
135 is used).
136 .It Fl c Ar class
137 Restrict matches to processes running with specified login class
138 .Ar class .
139 .It Fl f
140 Match against full argument lists.
141 The default is to match against process names.
142 .It Fl g Ar pgrp
143 Restrict matches to processes with a process group ID in the comma-separated
144 list
145 .Ar pgrp .
146 The value zero is taken to mean the process group ID of the running
147 .Nm pgrep
148 or
149 .Nm pkill
150 command.
151 .It Fl i
152 Ignore case distinctions in both the process table and the supplied pattern.
153 .It Fl j Ar jid
154 Restrict matches to processes inside jails with a jail ID in the comma-separated
155 list
156 .Ar jid .
157 The value
158 .Dq Li any
159 matches processes in any jail.
160 The value
161 .Dq Li none
162 matches processes not in jail.
163 .It Fl l
164 Long output.
165 For
166 .Nm pgrep ,
167 print the process name in addition to the process ID for each matching
168 process.
169 If used in conjunction with
170 .Fl f ,
171 print the process ID and the full argument list for each matching process.
172 For
173 .Nm pkill ,
174 display the kill command used for each process killed.
175 .It Fl n
176 Select only the newest (most recently started) of the matching processes.
177 .It Fl o
178 Select only the oldest (least recently started) of the matching processes.
179 .It Fl q
180 Do not write anything to standard output.
181 .It Fl s Ar sid
182 Restrict matches to processes with a session ID in the comma-separated
183 list
184 .Ar sid .
185 The value zero is taken to mean the session ID of the running
186 .Nm pgrep
187 or
188 .Nm pkill
189 command.
190 .It Fl t Ar tty
191 Restrict matches to processes associated with a terminal in the
192 comma-separated list
193 .Ar tty .
194 Terminal names may be of the form
195 .Pa tty Ns Ar xx
196 or the shortened form
197 .Ar xx .
198 A single dash
199 .Pq Ql -
200 matches processes not associated with a terminal.
201 .It Fl u Ar euid
202 Restrict matches to processes with an effective user ID in the
203 comma-separated list
204 .Ar euid .
205 .It Fl v
206 Reverse the sense of the matching; display processes that do not match the
207 given criteria.
208 .It Fl x
209 Require an exact match of the process name, or argument list if
210 .Fl f
211 is given.
212 The default is to match any substring.
213 .It Fl Ns Ar signal
214 A non-negative decimal number or symbolic signal name specifying the signal
215 to be sent instead of the default
216 .Dv TERM .
217 This option is valid only when given as the first argument to
218 .Nm pkill .
219 .El
220 .Pp
221 If any
222 .Ar pattern
223 operands are specified, they are used as regular expressions to match
224 the command name or full argument list of each process.
225 If the
226 .Fl f
227 option is not specified, then the
228 .Ar pattern
229 will attempt to match the command name.
230 However, presently
231 .Fx
232 will only keep track of the first 19 characters of the command
233 name for each process.
234 Attempts to match any characters after the first 19 of a command name
235 will quietly fail.
236 .Pp
237 Note that a running
238 .Nm pgrep
239 or
240 .Nm pkill
241 process will never consider itself nor system processes (kernel threads) as
242 a potential match.
243 .Sh EXIT STATUS
244 The
245 .Nm pgrep
246 and
247 .Nm pkill
248 utilities
249 return one of the following values upon exit:
250 .Bl -tag -width indent
251 .It 0
252 One or more processes were matched.
253 .It 1
254 No processes were matched.
255 .It 2
256 Invalid options were specified on the command line.
257 .It 3
258 An internal error occurred.
259 .El
260 .Sh COMPATIBILITY
261 Historically the option
262 .Dq Fl j Li 0
263 means any jail, although in other utilities such as
264 .Xr ps 1
265 jail ID
266 .Li 0
267 has the opposite meaning, not in jail.
268 Therefore
269 .Dq Fl j Li 0
270 is deprecated, and its use is discouraged in favor of
271 .Dq Fl j Li any .
272 .Sh SEE ALSO
273 .Xr kill 1 ,
274 .Xr killall 1 ,
275 .Xr ps 1 ,
276 .Xr flock 2 ,
277 .Xr kill 2 ,
278 .Xr sigaction 2 ,
279 .Xr pidfile 3 ,
280 .Xr re_format 7
281 .\" Xr signal 7
282 .Sh HISTORY
283 The
284 .Nm pkill
285 and
286 .Nm pgrep
287 utilities
288 first appeared in
289 .Nx 1.6 .
290 They are modelled after utilities of the same name that appeared in Sun
291 Solaris 7.
292 They first appeared in
293 .Dx 1.1 .
294 .Sh AUTHORS
295 .An Andrew Doran Aq Mt ad@NetBSD.org