1.\" $NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant Exp $ 2.\" 3.\" $FreeBSD: head/bin/pkill/pkill.1 254134 2013-08-09 08:38:51Z trasz $ 4.\" 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. 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.\" 32.Dd January 7, 2023 33.Dt PKILL 1 34.Os 35.Sh NAME 36.Nm pgrep , 37.Nm pkill 38.Nd find or signal processes by name 39.Sh SYNOPSIS 40.Nm pgrep 41.Op Fl LSTafilnoqvx 42.Op Fl F Ar pidfile 43.Op Fl G Ar gid 44.Op Fl M Ar core 45.Op Fl N Ar system 46.Op Fl P Ar ppid 47.Op Fl U Ar uid 48.Op Fl c Ar class 49.Op Fl d Ar delim 50.Op Fl g Ar pgrp 51.Op Fl j Ar jid 52.Op Fl s Ar sid 53.Op Fl t Ar tty 54.Op Fl u Ar euid 55.Ar pattern ... 56.Nm pkill 57.Op Fl Ar signal 58.Op Fl ILTafilnovx 59.Op Fl F Ar pidfile 60.Op Fl G Ar gid 61.Op Fl M Ar core 62.Op Fl N Ar system 63.Op Fl P Ar ppid 64.Op Fl U Ar uid 65.Op Fl c Ar class 66.Op Fl g Ar pgrp 67.Op Fl j Ar jid 68.Op Fl s Ar sid 69.Op Fl t Ar tty 70.Op Fl u Ar euid 71.Ar pattern ... 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: 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. 90.It Fl G Ar gid 91Restrict matches to processes with a real group ID in the comma-separated 92list 93.Ar gid . 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. 111.It Fl P Ar ppid 112Restrict matches to processes with a parent process ID in the 113comma-separated list 114.Ar ppid . 115.It Fl S 116Search also in system processes (kernel threads). 117.It Fl T 118Restrict matches to processes associated with the current terminal. 119.It Fl U Ar uid 120Restrict matches to processes with a real user ID in the comma-separated 121list 122.Ar uid . 123.It Fl a 124Include process ancestors in the match list. 125By default, the current 126.Nm pgrep 127or 128.Nm pkill 129process and all of its ancestors are excluded (unless 130.Fl v 131is used). 132.It Fl c Ar class 133Restrict matches to processes running with specified login class 134.Ar class . 135.It Fl d Ar delim 136Specify a delimiter to be printed between each process ID. 137The default is a newline. 138This option can only be used with the 139.Nm pgrep 140command. 141.It Fl f 142Match against full argument lists. 143The default is to match against process names. 144.It Fl g Ar pgrp 145Restrict matches to processes with a process group ID in the comma-separated 146list 147.Ar pgrp . 148The value zero is taken to mean the process group ID of the running 149.Nm pgrep 150or 151.Nm pkill 152command. 153.It Fl i 154Ignore case distinctions in both the process table and the supplied pattern. 155.It Fl j Ar jid 156Restrict matches to processes inside jails with a jail ID in the comma-separated 157list 158.Ar jid . 159The value 160.Dq Li any 161matches processes in any jail. 162The value 163.Dq Li none 164matches processes not in jail. 165.It Fl l 166Long output. 167For 168.Nm pgrep , 169print the process name in addition to the process ID for each matching 170process. 171If used in conjunction with 172.Fl f , 173print the process ID and the full argument list for each matching process. 174For 175.Nm pkill , 176display the kill command used for each process killed. 177.It Fl n 178Select only the newest (most recently started) of the matching processes. 179.It Fl o 180Select only the oldest (least recently started) of the matching processes. 181.It Fl q 182Do not write anything to standard output. 183.It Fl s Ar sid 184Restrict matches to processes with a session ID in the comma-separated 185list 186.Ar sid . 187The value zero is taken to mean the session ID of the running 188.Nm pgrep 189or 190.Nm pkill 191command. 192.It Fl t Ar tty 193Restrict matches to processes associated with a terminal in the 194comma-separated list 195.Ar tty . 196Terminal names may be of the form 197.Pa tty Ns Ar xx , 198the full path form 199.Pa /dev/tty Ns Ar xx , 200or the shortened form 201.Ar xx . 202For pseudo terminals, use 203.Pa pts/ Ns Ar xx , 204.Pa /dev/pts/ Ns Ar xx , 205or 206.Ar xx 207as the name. 208A single dash 209.Pq Ql - 210matches processes not associated with a terminal. 211.It Fl u Ar euid 212Restrict matches to processes with an effective user ID in the 213comma-separated list 214.Ar euid . 215.It Fl v 216Reverse the sense of the matching; display processes that do not match the 217given criteria. 218.It Fl x 219Require an exact match of the process name, or argument list if 220.Fl f 221is given. 222The default is to match any substring. 223.It Fl Ns Ar signal 224A non-negative decimal number or symbolic signal name specifying the signal 225to be sent instead of the default 226.Dv TERM . 227This option is valid only when given as the first argument to 228.Nm pkill . 229.El 230.Pp 231If any 232.Ar pattern 233operands are specified, they are used as regular expressions to match 234the command name or full argument list of each process. 235If the 236.Fl f 237option is not specified, then the 238.Ar pattern 239will attempt to match the command name. 240However, presently 241.Fx 242will only keep track of the first 19 characters of the command 243name for each process. 244Attempts to match any characters after the first 19 of a command name 245will quietly fail. 246.Pp 247Note that a running 248.Nm pgrep 249or 250.Nm pkill 251process will never consider itself nor system processes (kernel threads) as 252a potential match. 253.Sh IMPLEMENTATION NOTES 254The Sun Solaris implementation utilised procfs to obtain process information. 255This implementation utilises 256.Xr kvm 3 257instead. 258On a live system, 259.Xr kvm 3 260uses the 261.Va kern.proc 262MIB to obtain the list of processes. 263Kernel memory through 264.Pa /dev/kmem 265is not accessed. 266.Sh EXIT STATUS 267The 268.Nm pgrep 269and 270.Nm pkill 271utilities 272return one of the following values upon exit: 273.Bl -tag -width indent 274.It 0 275One or more processes were matched. 276.It 1 277No processes were matched. 278.It 2 279Invalid options were specified on the command line. 280.It 3 281An internal error occurred. 282.El 283.Sh COMPATIBILITY 284Historically the option 285.Dq Fl j Li 0 286means any jail, although in other utilities such as 287.Xr ps 1 288jail ID 289.Li 0 290has the opposite meaning, not in jail. 291Therefore 292.Dq Fl j Li 0 293is deprecated, and its use is discouraged in favor of 294.Dq Fl j Li any . 295.Sh SEE ALSO 296.Xr kill 1 , 297.Xr killall 1 , 298.Xr ps 1 , 299.Xr flock 2 , 300.Xr kill 2 , 301.Xr sigaction 2 , 302.Xr pidfile 3 , 303.Xr signal 3 , 304.Xr re_format 7 305.Sh HISTORY 306The 307.Nm pkill 308and 309.Nm pgrep 310utilities 311originated in 312.Nx 1.6 . 313They are modelled after utilities of the same name that appeared in Sun 314Solaris 7. 315They first appeared in 316.Dx 1.1 . 317.Sh AUTHORS 318.An Andrew Doran Aq Mt ad@NetBSD.org 319