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