xref: /freebsd/bin/pkill/pkill.1 (revision cbb3ec25236ba72f91cbdf23f8b78b9d1af0cedf)
1.\"	$NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant Exp $
2.\"
3.\" Copyright (c) 2002 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Doran.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE.
29.\"
30.Dd October 5, 2020
31.Dt PKILL 1
32.Os
33.Sh NAME
34.Nm pgrep , pkill
35.Nd find or signal processes by name
36.Sh SYNOPSIS
37.Nm pgrep
38.Op Fl LSafilnoqvx
39.Op Fl F Ar pidfile
40.Op Fl G Ar gid
41.Op Fl M Ar core
42.Op Fl N Ar system
43.Op Fl P Ar ppid
44.Op Fl U Ar uid
45.Op Fl c Ar class
46.Op Fl d Ar delim
47.Op Fl g Ar pgrp
48.Op Fl j Ar jail
49.Op Fl s Ar sid
50.Op Fl t Ar tty
51.Op Fl u Ar euid
52.Ar pattern ...
53.Nm pkill
54.Op Fl Ar signal
55.Op Fl ILafilnovx
56.Op Fl F Ar pidfile
57.Op Fl G Ar gid
58.Op Fl M Ar core
59.Op Fl N Ar system
60.Op Fl P Ar ppid
61.Op Fl U Ar uid
62.Op Fl c Ar class
63.Op Fl g Ar pgrp
64.Op Fl j Ar jail
65.Op Fl s Ar sid
66.Op Fl t Ar tty
67.Op Fl u Ar euid
68.Ar pattern ...
69.Sh DESCRIPTION
70The
71.Nm pgrep
72command searches the process table on the running system and prints the
73process IDs of all processes that match the criteria given on the command
74line.
75.Pp
76The
77.Nm pkill
78command searches the process table on the running system and signals all
79processes that match the criteria given on the command line.
80.Pp
81The following options are available:
82.Bl -tag -width ".Fl F Ar pidfile"
83.It Fl F Ar pidfile
84Restrict matches to a process whose PID is stored in the
85.Ar pidfile
86file.
87.It Fl G Ar gid
88Restrict matches to processes with a real group ID in the comma-separated
89list
90.Ar gid .
91.It Fl I
92Request confirmation before attempting to signal each process.
93.It Fl L
94The
95.Ar pidfile
96file given for the
97.Fl F
98option must be locked with the
99.Xr flock 2
100syscall or created with
101.Xr pidfile 3 .
102.It Fl M Ar core
103Extract values associated with the name list from the specified core
104instead of the currently running system.
105.It Fl N Ar system
106Extract the name list from the specified system instead of the default,
107which is the kernel image the system has booted from.
108.It Fl P Ar ppid
109Restrict matches to processes with a parent process ID in the
110comma-separated list
111.Ar ppid .
112.It Fl S
113Search also in system processes (kernel threads).
114.It Fl U Ar uid
115Restrict matches to processes with a real user ID in the comma-separated
116list
117.Ar uid .
118.It Fl d Ar delim
119Specify a delimiter to be printed between each process ID.
120The default is a newline.
121This option can only be used with the
122.Nm pgrep
123command.
124.It Fl a
125Include process ancestors in the match list.
126By default, the current
127.Nm pgrep
128or
129.Nm pkill
130process and all of its ancestors are excluded (unless
131.Fl v
132is used).
133.It Fl c Ar class
134Restrict matches to processes running with specified login class
135.Ar class .
136.It Fl f
137Match against full argument lists.
138The default is to match against process names.
139.It Fl g Ar pgrp
140Restrict matches to processes with a process group ID in the comma-separated
141list
142.Ar pgrp .
143The value zero is taken to mean the process group ID of the running
144.Nm pgrep
145or
146.Nm pkill
147command.
148.It Fl i
149Ignore case distinctions in both the process table and the supplied pattern.
150.It Fl j Ar jail
151Restrict matches to processes inside the specified jails.
152The argument
153.Ar jail
154may be
155.Dq Li any
156to match processes in any jail,
157.Dq Li none
158to match processes not in jail,
159or a comma-separated list of jail IDs or names.
160.It Fl l
161Long output.
162For
163.Nm pgrep ,
164print the process name in addition to the process ID for each matching
165process.
166If used in conjunction with
167.Fl f ,
168print the process ID and the full argument list for each matching process.
169For
170.Nm pkill ,
171display the kill command used for each process killed.
172.It Fl n
173Select only the newest (most recently started) of the matching processes.
174.It Fl o
175Select only the oldest (least recently started) of the matching processes.
176.It Fl q
177For
178.Nm pgrep ,
179Do not write anything to standard output.
180.It Fl s Ar sid
181Restrict matches to processes with a session ID in the comma-separated
182list
183.Ar sid .
184The value zero is taken to mean the session ID of the running
185.Nm pgrep
186or
187.Nm pkill
188command.
189.It Fl t Ar tty
190Restrict matches to processes associated with a terminal in the
191comma-separated list
192.Ar tty .
193Terminal names may be of the form
194.Pa tty Ns Ar xx
195or the shortened form
196.Ar xx .
197A single dash
198.Pq Ql -
199matches processes not associated with a terminal.
200.It Fl u Ar euid
201Restrict matches to processes with an effective user ID in the
202comma-separated list
203.Ar euid .
204.It Fl v
205Reverse the sense of the matching; display processes that do not match the
206given criteria.
207.It Fl x
208Require an exact match of the process name, or argument list if
209.Fl f
210is given.
211The default is to match any substring.
212.It Fl Ns Ar signal
213A non-negative decimal number or symbolic signal name specifying the signal
214to be sent instead of the default
215.Dv TERM .
216This option is valid only when given as the first argument to
217.Nm pkill .
218.El
219.Pp
220If any
221.Ar pattern
222operands are specified, they are used as extended regular expressions to match
223the command name or full argument list of each process.
224If the
225.Fl f
226option is not specified, then the
227.Ar pattern
228will attempt to match the command name.
229However, presently
230.Fx
231will only keep track of the first 19 characters of the command
232name for each process.
233Attempts to match any characters after the first 19 of a command name
234will quietly fail.
235.Pp
236Note that a running
237.Nm pgrep
238or
239.Nm pkill
240process will never consider itself nor system processes (kernel threads) as
241a potential match.
242.Sh IMPLEMENTATION NOTES
243The Sun Solaris implementation utilised procfs to obtain process information.
244This implementation utilises
245.Xr kvm 3
246instead.
247On a live system,
248.Xr kvm 3
249uses
250.Va kern.proc
251MIB to obtain the list of processes, kernel memory through
252.Pa /dev/kmem
253is not accessed.
254.Sh EXIT STATUS
255The
256.Nm pgrep
257and
258.Nm pkill
259utilities
260return one of the following values upon exit:
261.Bl -tag -width indent
262.It 0
263One or more processes were matched.
264.It 1
265No processes were matched.
266.It 2
267Invalid options were specified on the command line.
268.It 3
269An internal error occurred.
270.El
271.Sh EXAMPLES
272Show the pid of the process holding the
273.Pa /tmp/.X0-lock
274pid file:
275.Bd -literal -offset indent
276$ pgrep -F /tmp/.X0-lock
2771211
278.Ed
279.Pp
280Show the pid and the name of the process including kernel threads in the
281search:
282.Bd -literal -offset indent
283$ pgrep -lS vnlru
28437 vnlru
285.Ed
286.Pp
287Search for processes including kernel threads that match the extended regular
288expression pattern:
289.Bd -literal -offset indent
290$ pgrep -S 'crypto.*[2-3]'
29120
29219
2936
2945
295.Ed
296.Pp
297Show long output for firefox processes:
298.Bd -literal -offset indent
299$ pgrep -l firefox
3001312 firefox
3011309 firefox
3021288 firefox
3031280 firefox
3041279 firefox
3051278 firefox
3061277 firefox
3071264 firefox
308.Ed
309.Pp
310Same as above but just showing the pid of the most recent process:
311.Bd -literal -offset indent
312$ pgrep -n firefox
3131312
314.Ed
315.Pp
316Look for vim processes.
317Match against the full argument list:
318.Bd -literal -offset indent
319$ pgrep -f vim
32044968
32130790
322.Ed
323.Pp
324Same as above but matching against the
325.Ql list
326word and showing the full argument list:
327.Bd -literal -offset indent
328$ pgrep -f -l list
32930790 vim list.txt
330.Ed
331.Pp
332Send
333.Va SIGSTOP
334signal to processes that are an exact match:
335.Bd -literal -offset indent
336$ pkill -SIGSTOP -f -x "vim list.txt"
337.Ed
338.Pp
339Without
340.Fl f
341names over 19 characters will silently fail:
342.Bd -literal -offset indent
343$ vim this_is_a_very_long_file_name &
344[1] 36689
345$
346
347[1]+  Stopped                 vim this_is_a_very_long_file_name
348$ pgrep "vim this"
349$
350.Ed
351.Pp
352Same as above using the
353.Fl f
354flag:
355.Bd -literal -offset indent
356$ pgrep -f "vim this"
35736689
358.Ed
359.Pp
360Find the
361.Xr top 1
362command running in any jail:
363.Bd -literal -offset indent
364$ pgrep -j any top
36534498
366.Ed
367.Pp
368Show all processes running in jail ID 58:
369.Bd -literal -offset indent
370$ pgrep -l -j58 '.*'
37128397 pkg-static
37228396 pkg-static
37328255 sh
37428254 make
375.Ed
376.Sh COMPATIBILITY
377Historically the option
378.Dq Fl j Li 0
379means any jail, although in other utilities such as
380.Xr ps 1
381jail ID
382.Li 0
383has the opposite meaning, not in jail.
384Therefore
385.Dq Fl j Li 0
386is deprecated, and its use is discouraged in favor of
387.Dq Fl j Li any .
388.Sh SEE ALSO
389.Xr kill 1 ,
390.Xr killall 1 ,
391.Xr ps 1 ,
392.Xr flock 2 ,
393.Xr kill 2 ,
394.Xr sigaction 2 ,
395.Xr kvm 3 ,
396.Xr pidfile 3 ,
397.Xr re_format 7
398.\" Xr signal 7
399.Sh HISTORY
400The
401.Nm pkill
402and
403.Nm pgrep
404utilities
405first appeared in
406.Nx 1.6 .
407They are modelled after utilities of the same name that appeared in Sun
408Solaris 7.
409They made their first appearance in
410.Fx 5.3 .
411.Sh AUTHORS
412.An Andrew Doran Aq Mt ad@NetBSD.org
413