xref: /netbsd-src/usr.bin/pkill/pkill.1 (revision 9d92ab4fc272b18d6e70508f516aa05f638eddd5)
1.\"	$NetBSD: pkill.1,v 1.33 2024/10/07 06:14:05 roy 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 6, 2024
31.Dt PKILL 1
32.Os
33.Sh NAME
34.Nm pkill ,
35.Nm pgrep ,
36.Nm prenice
37.Nd find or signal processes by name
38.Sh SYNOPSIS
39.Nm pgrep
40.Op Fl fiLlnqvx
41.Op Fl d Ar delim
42.Op Fl F Ar pidfile
43.Op Fl G Ar gid
44.Op Fl g Ar pgrp
45.Op Fl P Ar ppid
46.Op Fl s Ar sid
47.Op Fl t Ar tty
48.Op Fl U Ar uid
49.Op Fl u Ar euid
50.Ar pattern ...
51.Nm pkill
52.Op Fl signal
53.Op Fl fiLlnvx
54.Op Fl F Ar pidfile
55.Op Fl G Ar gid
56.Op Fl g Ar pgrp
57.Op Fl P Ar ppid
58.Op Fl s Ar sid
59.Op Fl t Ar tty
60.Op Fl U Ar uid
61.Op Fl u Ar euid
62.Ar pattern ...
63.Nm prenice
64.Op Fl l
65.Ar priority
66.Ar pattern ...
67.Sh DESCRIPTION
68The
69.Nm pgrep
70command searches the process table on the running system and prints the
71process IDs of all processes that match the criteria given on the command
72line.
73.Pp
74The
75.Nm pkill
76command searches the process table on the running system and signals all
77processes that match the criteria given on the command line.
78.Pp
79The
80.Nm prenice
81command searches the process table on the running system and sets the
82priority of all processes that match the criteria given on the command line.
83.Pp
84By default, matching applies to any substring of the command name
85.Pq Va argv[0] ,
86but options may be used to change this.
87Patterns are specified using extended regular expressions (see
88.Xr re_format 7 ) .
89.Pp
90The following options are available for
91.Nm pkill
92and
93.Nm pgrep :
94.Bl -tag -width ".Fl F Ar pidfile"
95.It Fl d Ar delim
96Specify a delimiter to be printed between each process ID.
97The default is a newline.
98This option can only be used with the
99.Nm pgrep
100command.
101.It Fl f
102Match against full argument lists.
103The default is to match against process names.
104.It Fl F Ar pidfile
105Restrict matches to processes which pid is stored in
106.Ar pidfile
107file.
108.It Fl G Ar gid
109Restrict matches to processes with a real group ID in the comma-separated
110list
111.Ar gid .
112.It Fl g Ar pgrp
113Restrict matches to processes with a process group ID in the comma-separated
114list
115.Ar pgrp .
116The value zero is taken to mean the process group ID of the running
117.Nm pgrep
118or
119.Nm pkill
120command.
121.It Fl i
122Ignore case distinctions in both the process table and the supplied pattern.
123.It Fl L
124The
125.Ar pidfile
126given for the
127.Fl F
128option must be locked with the
129.Xr flock 2
130syscall or created with
131.Xr pidfile_lock 3 .
132.It Fl l
133Long output.
134Print the process name in addition to the process ID for each matching
135process.
136If used in conjunction with
137.Fl f ,
138print the process ID and the full argument list for each matching process.
139.It Fl n
140Match only the most recently created process, if any.
141.It Fl P Ar ppid
142Restrict matches to processes with a parent process ID in the
143comma-separated list
144.Ar ppid .
145.It Fl s Ar sid
146Restrict matches to processes with a session ID in the comma-separated
147list
148.Ar sid .
149The value zero is taken to mean the session ID of the running
150.Nm pgrep
151or
152.Nm pkill
153command.
154.It Fl t Ar tty
155Restrict matches to processes associated with a terminal in the
156comma-separated list
157.Ar tty .
158Terminal names may be specified as a fully qualified path, in the form
159.Sq ttyXX ,
160or
161.Sq pts/N ,
162(where
163.Ar XX
164is any pair of letters, and
165.Ar N
166is a number),
167or the shortened forms
168.Sq XX
169or
170.Sq N .
171A single dash
172.Pq Sq -
173matches processes not associated with a terminal.
174.It Fl U Ar uid
175Restrict matches to processes with a real user ID in the comma-separated
176list
177.Ar uid .
178.It Fl u Ar euid
179Restrict matches to processes with an effective user ID in the
180comma-separated list
181.Ar euid .
182.It Fl v
183Reverse the sense of the matching; display processes that do not match the
184given criteria.
185.It Fl x
186Require an exact match of the process name, or argument list if
187.Fl f
188is given.
189The default is to match any substring.
190.It Fl signal
191A non-negative decimal number or symbolic signal name specifying the signal
192to be sent instead of the default TERM.
193This option is valid only when given as the first argument to
194.Nm pkill .
195.El
196.Pp
197The following option is also available for
198.Nm pgrep :
199.Bl -tag -width ".Fl F Ar pidfile"
200.It Fl q
201Quiet; do not write anything to standard output.
202.El
203.Pp
204The
205.Fl l
206flag is also available for
207.Nm prenice .
208.Pp
209Note that a running
210.Nm pgrep ,
211.Nm pkill ,
212or
213.Nm prenice
214process will never consider itself or system processes (kernel threads) as
215a potential match.
216.Sh IMPLEMENTATION NOTES
217The Sun Solaris implementation utilised procfs to obtain process information.
218This implementation utilises
219.Xr kvm 3
220instead.
221.Sh EXIT STATUS
222.Nm pgrep ,
223.Nm pkill ,
224and
225.Nm prenice
226return one of the following values upon exit:
227.Bl -tag -width foo
228.It 0
229One or more processes were matched.
230.It 1
231No processes were matched.
232.It 2
233Invalid options were specified on the command line.
234.It 3
235An internal error occurred.
236.El
237.Sh SEE ALSO
238.Xr grep 1 ,
239.Xr kill 1 ,
240.Xr ps 1 ,
241.Xr kill 2 ,
242.Xr sigaction 2 ,
243.Xr kvm 3 ,
244.Xr re_format 7 ,
245.Xr signal 7 ,
246.Xr renice 8
247.Sh HISTORY
248.Nm pkill
249and
250.Nm pgrep
251first appeared in
252.Nx 1.6 .
253They are modelled after utilities of the same name that appeared in Sun
254Solaris 7.
255.Pp
256.Nm prenice
257was introduced in
258.Nx 6.0 .
259.Sh AUTHORS
260.An Andrew Doran
261.Aq Mt ad@NetBSD.org .
262