pkill(1): add '-j jid' flag to restrict matches to jailed processes.
[dragonfly.git] / usr.bin / pkill / pkill.1
CommitLineData
df558cd9 1.\" $NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant Exp $
3f5e28f4 2.\" $DragonFly: src/usr.bin/pkill/pkill.1,v 1.6 2007/05/17 08:19:02 swildner Exp $
df558cd9
CP
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.\"
142250fb 38.Dd July 27, 2004
df558cd9
CP
39.Dt PKILL 1
40.Os
41.Sh NAME
4e3518d8 42.Nm pgrep ,
df558cd9
CP
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
54499c33 56.Op Fl j Ar jid
df558cd9
CP
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
54499c33 68.Op Fl j Ar jid
df558cd9
CP
69.Op Ar pattern Op ...
70.Sh DESCRIPTION
71The
72.Nm pgrep
73command searches the process table on the running system and prints the
74process IDs of all processes that match the criteria given on the command
75line.
76.Pp
77The
78.Nm pkill
79command searches the process table on the running system and signals all
80processes that match the criteria given on the command line.
81.Pp
82The following options are available:
83.Bl -tag -width xxxxxxxx
84.It Fl G Ar gid
85Restrict matches to processes with a real group ID in the comma-separated
86list
87.Ar gid .
88.It Fl P Ar ppid
89Restrict matches to processes with a parent process ID in the
90comma-separated list
91.Ar ppid .
92.It Fl U Ar uid
93Restrict matches to processes with a real user ID in the comma-separated
94list
95.Ar uid .
96.It Fl d Ar delim
97Specify a delimiter to be printed between each process ID.
98The default is a newline.
99This option can only be used with the
100.Nm pgrep
101command.
102.It Fl f
103Match against full argument lists.
104The default is to match against process names.
105.It Fl g Ar pgrp
106Restrict matches to processes with a process group ID in the comma-separated
107list
108.Ar pgrp .
109The value zero is taken to mean the process group ID of the running
110.Nm pgrep
111or
112.Nm pkill
113command.
54499c33
CT
114.It Fl j Ar jid
115Restrict matches to processes inside jails with a jail ID in the comma-separated
116list
117.Ar jid .
118The value
119.Dq Li -1
120matches processes in any jail.
121The value
122.Dq Li 0
123matches processes not in a jail.
df558cd9
CP
124.It Fl l
125Long output.
126Print the process name in addition to the process ID for each matching
127process.
128If used in conjunction with
129.Fl f ,
130print the process ID and the full argument list for each matching process.
131This option can only be used with the
132.Nm pgrep
133command.
134.It Fl n
135Match only the most recently created process, if any.
136.It Fl s Ar sid
137Restrict matches to processes with a session ID in the comma-separated
138list
139.Ar sid .
140The value zero is taken to mean the session ID of the running
141.Nm pgrep
142or
143.Nm pkill
144command.
145.It Fl t Ar tty
146Restrict matches to processes associated with a terminal in the
147comma-separated list
148.Ar tty .
149Terminal names may be of the form
150.Sq ttyxx
151or the shortened form
152.Sq xx .
153A single dash (`-') matches processes not associated with a terminal.
154.It Fl u Ar euid
155Restrict matches to processes with an effective user ID in the
156comma-separated list
157.Ar euid .
158.It Fl v
159Reverse the sense of the matching; display processes that do not match the
160given criteria.
161.It Fl x
162Require an exact match of the process name, or argument list if
163.Fl f
164is given.
165The default is to match any substring.
166.It Fl signal
167A non-negative decimal number or symbolic signal name specifying the signal
168to be sent instead of the default TERM.
169This option is valid only when given as the first argument to
170.Nm pkill .
171.El
172.Pp
173Note that a running
174.Nm pgrep
175or
176.Nm pkill
177process will never consider itself nor system processes (kernel threads) as
178a potential match.
81548a7c 179.Sh DIAGNOSTICS
df558cd9
CP
180.Nm pgrep
181and
182.Nm pkill
183return one of the following values upon exit:
184.Bl -tag -width foo
185.It 0
186One or more processes were matched.
187.It 1
188No processes were matched.
189.It 2
190Invalid options were specified on the command line.
191.It 3
192An 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 ,
302e0891
SW
199.Xr signal 3 ,
200.Xr re_format 7
df558cd9
CP
201.Sh HISTORY
202.Nm pkill
203and
204.Nm pgrep
4e3518d8 205originated in
df558cd9 206.Nx 1.6 .
3f5e28f4 207They are modeled after utilities of the same name that appeared in Sun
df558cd9 208Solaris 7.
4e3518d8
CP
209They first appeared in
210.Dx
211in version 1.1.
df558cd9
CP
212.Sh AUTHORS
213.An Andrew Doran
214.Aq ad@NetBSD.org .