pkill(1): add '-j jid' flag to restrict matches to jailed processes.
[dragonfly.git] / usr.bin / pkill / pkill.1
1 .\"     $NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant Exp $
2 .\"     $DragonFly: src/usr.bin/pkill/pkill.1,v 1.6 2007/05/17 08:19:02 swildner Exp $
3 .\"
4 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
5 .\" All rights reserved.
6 .\"
7 .\" This code is derived from software contributed to The NetBSD Foundation
8 .\" by Andrew Doran.
9 .\"
10 .\" Redistribution and use in source and binary forms, with or without
11 .\" modification, are permitted provided that the following conditions
12 .\" are met:
13 .\" 1. Redistributions of source code must retain the above copyright
14 .\"    notice, this list of conditions and the following disclaimer.
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\"    notice, this list of conditions and the following disclaimer in the
17 .\"    documentation and/or other materials provided with the distribution.
18 .\" 3. All advertising materials mentioning features or use of this software
19 .\"    must display the following acknowledgement:
20 .\"        This product includes software developed by the NetBSD
21 .\"        Foundation, Inc. and its contributors.
22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
23 .\"    contributors may be used to endorse or promote products derived
24 .\"    from this software without specific prior written permission.
25 .\"
26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36 .\" POSSIBILITY OF SUCH DAMAGE.
37 .\"
38 .Dd July 27, 2004
39 .Dt PKILL 1
40 .Os
41 .Sh NAME
42 .Nm pgrep ,
43 .Nm pkill
44 .Nd find or signal processes by name
45 .Sh SYNOPSIS
46 .Nm pgrep
47 .Op Fl flnvx
48 .Op Fl G Ar gid
49 .Op Fl P Ar ppid
50 .Op Fl U Ar uid
51 .Op Fl d Ar delim
52 .Op Fl g Ar pgrp
53 .Op Fl s Ar sid
54 .Op Fl t Ar tty
55 .Op Fl u Ar euid
56 .Op Fl j Ar jid
57 .Op Ar pattern Op ...
58 .Nm pkill
59 .Op Fl signal
60 .Op Fl fnvx
61 .Op Fl G Ar gid
62 .Op Fl P Ar ppid
63 .Op Fl U Ar uid
64 .Op Fl g Ar pgrp
65 .Op Fl s Ar sid
66 .Op Fl t Ar tty
67 .Op Fl u Ar euid
68 .Op Fl j Ar jid
69 .Op Ar pattern Op ...
70 .Sh DESCRIPTION
71 The
72 .Nm pgrep
73 command searches the process table on the running system and prints the
74 process IDs of all processes that match the criteria given on the command
75 line.
76 .Pp
77 The
78 .Nm pkill
79 command searches the process table on the running system and signals all
80 processes that match the criteria given on the command line.
81 .Pp
82 The following options are available:
83 .Bl -tag -width xxxxxxxx
84 .It Fl G Ar gid
85 Restrict matches to processes with a real group ID in the comma-separated
86 list
87 .Ar gid .
88 .It Fl P Ar ppid
89 Restrict matches to processes with a parent process ID in the
90 comma-separated list
91 .Ar ppid .
92 .It Fl U Ar uid
93 Restrict matches to processes with a real user ID in the comma-separated
94 list
95 .Ar uid .
96 .It Fl d Ar delim
97 Specify a delimiter to be printed between each process ID.
98 The default is a newline.
99 This option can only be used with the
100 .Nm pgrep
101 command.
102 .It Fl f
103 Match against full argument lists.
104 The default is to match against process names.
105 .It Fl g Ar pgrp
106 Restrict matches to processes with a process group ID in the comma-separated
107 list
108 .Ar pgrp .
109 The value zero is taken to mean the process group ID of the running
110 .Nm pgrep
111 or
112 .Nm pkill
113 command.
114 .It Fl j Ar jid
115 Restrict matches to processes inside jails with a jail ID in the comma-separated
116 list
117 .Ar jid .
118 The value
119 .Dq Li -1
120 matches processes in any jail.
121 The value
122 .Dq Li 0
123 matches processes not in a jail.
124 .It Fl l
125 Long output.
126 Print the process name in addition to the process ID for each matching
127 process.
128 If used in conjunction with
129 .Fl f ,
130 print the process ID and the full argument list for each matching process.
131 This option can only be used with the
132 .Nm pgrep
133 command.
134 .It Fl n
135 Match only the most recently created process, if any.
136 .It Fl s Ar sid
137 Restrict matches to processes with a session ID in the comma-separated
138 list
139 .Ar sid .
140 The value zero is taken to mean the session ID of the running
141 .Nm pgrep
142 or
143 .Nm pkill
144 command.
145 .It Fl t Ar tty
146 Restrict matches to processes associated with a terminal in the
147 comma-separated list
148 .Ar tty .
149 Terminal names may be of the form
150 .Sq ttyxx
151 or the shortened form
152 .Sq xx .
153 A single dash (`-') matches processes not associated with a terminal.
154 .It Fl u Ar euid
155 Restrict matches to processes with an effective user ID in the
156 comma-separated list
157 .Ar euid .
158 .It Fl v
159 Reverse the sense of the matching; display processes that do not match the
160 given criteria.
161 .It Fl x
162 Require an exact match of the process name, or argument list if
163 .Fl f
164 is given.
165 The default is to match any substring.
166 .It Fl signal
167 A non-negative decimal number or symbolic signal name specifying the signal
168 to be sent instead of the default TERM.
169 This option is valid only when given as the first argument to
170 .Nm pkill .
171 .El
172 .Pp
173 Note that a running
174 .Nm pgrep
175 or
176 .Nm pkill
177 process will never consider itself nor system processes (kernel threads) as
178 a potential match.
179 .Sh DIAGNOSTICS
180 .Nm pgrep
181 and
182 .Nm pkill
183 return one of the following values upon exit:
184 .Bl -tag -width foo
185 .It 0
186 One or more processes were matched.
187 .It 1
188 No processes were matched.
189 .It 2
190 Invalid options were specified on the command line.
191 .It 3
192 An internal error occurred.
193 .El
194 .Sh SEE ALSO
195 .Xr kill 1 ,
196 .Xr ps 1 ,
197 .Xr kill 2 ,
198 .Xr sigaction 2 ,
199 .Xr signal 3 ,
200 .Xr re_format 7
201 .Sh HISTORY
202 .Nm pkill
203 and
204 .Nm pgrep
205 originated in
206 .Nx 1.6 .
207 They are modeled after utilities of the same name that appeared in Sun
208 Solaris 7.
209 They first appeared in
210 .Dx
211 in version 1.1.
212 .Sh AUTHORS
213 .An Andrew Doran
214 .Aq ad@NetBSD.org .