1.\" $NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant Exp $ 2.\" 3.\" $FreeBSD$ 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 October 5, 2020 33.Dt PKILL 1 34.Os 35.Sh NAME 36.Nm pgrep , pkill 37.Nd find or signal processes by name 38.Sh SYNOPSIS 39.Nm pgrep 40.Op Fl LSafilnoqvx 41.Op Fl F Ar pidfile 42.Op Fl G Ar gid 43.Op Fl M Ar core 44.Op Fl N Ar system 45.Op Fl P Ar ppid 46.Op Fl U Ar uid 47.Op Fl c Ar class 48.Op Fl d Ar delim 49.Op Fl g Ar pgrp 50.Op Fl j Ar jail 51.Op Fl s Ar sid 52.Op Fl t Ar tty 53.Op Fl u Ar euid 54.Ar pattern ... 55.Nm pkill 56.Op Fl Ar signal 57.Op Fl ILafilnovx 58.Op Fl F Ar pidfile 59.Op Fl G Ar gid 60.Op Fl M Ar core 61.Op Fl N Ar system 62.Op Fl P Ar ppid 63.Op Fl U Ar uid 64.Op Fl c Ar class 65.Op Fl g Ar pgrp 66.Op Fl j Ar jail 67.Op Fl s Ar sid 68.Op Fl t Ar tty 69.Op Fl u Ar euid 70.Ar pattern ... 71.Sh DESCRIPTION 72The 73.Nm pgrep 74command searches the process table on the running system and prints the 75process IDs of all processes that match the criteria given on the command 76line. 77.Pp 78The 79.Nm pkill 80command searches the process table on the running system and signals all 81processes that match the criteria given on the command line. 82.Pp 83The following options are available: 84.Bl -tag -width ".Fl F Ar pidfile" 85.It Fl F Ar pidfile 86Restrict matches to a process whose PID is stored in the 87.Ar pidfile 88file. 89.It Fl G Ar gid 90Restrict matches to processes with a real group ID in the comma-separated 91list 92.Ar gid . 93.It Fl I 94Request confirmation before attempting to signal each process. 95.It Fl L 96The 97.Ar pidfile 98file given for the 99.Fl F 100option must be locked with the 101.Xr flock 2 102syscall or created with 103.Xr pidfile 3 . 104.It Fl M Ar core 105Extract values associated with the name list from the specified core 106instead of the currently running system. 107.It Fl N Ar system 108Extract the name list from the specified system instead of the default, 109which is the kernel image the system has booted from. 110.It Fl P Ar ppid 111Restrict matches to processes with a parent process ID in the 112comma-separated list 113.Ar ppid . 114.It Fl S 115Search also in system processes (kernel threads). 116.It Fl U Ar uid 117Restrict matches to processes with a real user ID in the comma-separated 118list 119.Ar uid . 120.It Fl d Ar delim 121Specify a delimiter to be printed between each process ID. 122The default is a newline. 123This option can only be used with the 124.Nm pgrep 125command. 126.It Fl a 127Include process ancestors in the match list. 128By default, the current 129.Nm pgrep 130or 131.Nm pkill 132process and all of its ancestors are excluded (unless 133.Fl v 134is used). 135.It Fl c Ar class 136Restrict matches to processes running with specified login class 137.Ar class . 138.It Fl f 139Match against full argument lists. 140The default is to match against process names. 141.It Fl g Ar pgrp 142Restrict matches to processes with a process group ID in the comma-separated 143list 144.Ar pgrp . 145The value zero is taken to mean the process group ID of the running 146.Nm pgrep 147or 148.Nm pkill 149command. 150.It Fl i 151Ignore case distinctions in both the process table and the supplied pattern. 152.It Fl j Ar jail 153Restrict matches to processes inside the specified jails. 154The argument 155.Ar jail 156may be 157.Dq Li any 158to match processes in any jail, 159.Dq Li none 160to match processes not in jail, 161or a comma-separated list of jail IDs or names. 162.It Fl l 163Long output. 164For 165.Nm pgrep , 166print the process name in addition to the process ID for each matching 167process. 168If used in conjunction with 169.Fl f , 170print the process ID and the full argument list for each matching process. 171For 172.Nm pkill , 173display the kill command used for each process killed. 174.It Fl n 175Select only the newest (most recently started) of the matching processes. 176.It Fl o 177Select only the oldest (least recently started) of the matching processes. 178.It Fl q 179For 180.Nm pgrep , 181Do not write anything to standard output. 182.It Fl s Ar sid 183Restrict matches to processes with a session ID in the comma-separated 184list 185.Ar sid . 186The value zero is taken to mean the session ID of the running 187.Nm pgrep 188or 189.Nm pkill 190command. 191.It Fl t Ar tty 192Restrict matches to processes associated with a terminal in the 193comma-separated list 194.Ar tty . 195Terminal names may be of the form 196.Pa tty Ns Ar xx 197or the shortened form 198.Ar xx . 199A single dash 200.Pq Ql - 201matches processes not associated with a terminal. 202.It Fl u Ar euid 203Restrict matches to processes with an effective user ID in the 204comma-separated list 205.Ar euid . 206.It Fl v 207Reverse the sense of the matching; display processes that do not match the 208given criteria. 209.It Fl x 210Require an exact match of the process name, or argument list if 211.Fl f 212is given. 213The default is to match any substring. 214.It Fl Ns Ar signal 215A non-negative decimal number or symbolic signal name specifying the signal 216to be sent instead of the default 217.Dv TERM . 218This option is valid only when given as the first argument to 219.Nm pkill . 220.El 221.Pp 222If any 223.Ar pattern 224operands are specified, they are used as extended regular expressions to match 225the command name or full argument list of each process. 226If the 227.Fl f 228option is not specified, then the 229.Ar pattern 230will attempt to match the command name. 231However, presently 232.Fx 233will only keep track of the first 19 characters of the command 234name for each process. 235Attempts to match any characters after the first 19 of a command name 236will quietly fail. 237.Pp 238Note that a running 239.Nm pgrep 240or 241.Nm pkill 242process will never consider itself nor system processes (kernel threads) as 243a potential match. 244.Sh IMPLEMENTATION NOTES 245The Sun Solaris implementation utilised procfs to obtain process information. 246This implementation utilises 247.Xr kvm 3 248instead. 249On a live system, 250.Xr kvm 3 251uses 252.Va kern.proc 253MIB to obtain the list of processes, kernel memory through 254.Pa /dev/kmem 255is not accessed. 256.Sh EXIT STATUS 257The 258.Nm pgrep 259and 260.Nm pkill 261utilities 262return one of the following values upon exit: 263.Bl -tag -width indent 264.It 0 265One or more processes were matched. 266.It 1 267No processes were matched. 268.It 2 269Invalid options were specified on the command line. 270.It 3 271An internal error occurred. 272.El 273.Sh EXAMPLES 274Show the pid of the process holding the 275.Pa /tmp/.X0-lock 276pid file: 277.Bd -literal -offset indent 278$ pgrep -F /tmp/.X0-lock 2791211 280.Ed 281.Pp 282Show the pid and the name of the process including kernel threads in the 283search: 284.Bd -literal -offset indent 285$ pgrep -lS vnlru 28637 vnlru 287.Ed 288.Pp 289Search for processes including kernel threads that match the extended regular 290expression pattern: 291.Bd -literal -offset indent 292$ pgrep -S 'crypto.*[2-3]' 29320 29419 2956 2965 297.Ed 298.Pp 299Show long output for firefox processes: 300.Bd -literal -offset indent 301$ pgrep -l firefox 3021312 firefox 3031309 firefox 3041288 firefox 3051280 firefox 3061279 firefox 3071278 firefox 3081277 firefox 3091264 firefox 310.Ed 311.Pp 312Same as above but just showing the pid of the most recent process: 313.Bd -literal -offset indent 314$ pgrep -n firefox 3151312 316.Ed 317.Pp 318Look for vim processes. 319Match against the full argument list: 320.Bd -literal -offset indent 321$ pgrep -f vim 32244968 32330790 324.Ed 325.Pp 326Same as above but matching against the 327.Ql list 328word and showing the full argument list: 329.Bd -literal -offset indent 330$ pgrep -f -l list 33130790 vim list.txt 332.Ed 333.Pp 334Send 335.Va SIGSTOP 336signal to processes that are an exact match: 337.Bd -literal -offset indent 338$ pkill -SIGSTOP -f -x "vim list.txt" 339.Ed 340.Pp 341Without 342.Fl f 343names over 19 characters will silently fail: 344.Bd -literal -offset indent 345$ vim this_is_a_very_long_file_name & 346[1] 36689 347$ 348 349[1]+ Stopped vim this_is_a_very_long_file_name 350$ pgrep "vim this" 351$ 352.Ed 353.Pp 354Same as above using the 355.Fl f 356flag: 357.Bd -literal -offset indent 358$ pgrep -f "vim this" 35936689 360.Ed 361.Pp 362Find the 363.Xr top 1 364command running in any jail: 365.Bd -literal -offset indent 366$ pgrep -j any top 36734498 368.Ed 369.Pp 370Show all processes running in jail ID 58: 371.Bd -literal -offset indent 372$ pgrep -l -j58 '.*' 37328397 pkg-static 37428396 pkg-static 37528255 sh 37628254 make 377.Ed 378.Sh COMPATIBILITY 379Historically the option 380.Dq Fl j Li 0 381means any jail, although in other utilities such as 382.Xr ps 1 383jail ID 384.Li 0 385has the opposite meaning, not in jail. 386Therefore 387.Dq Fl j Li 0 388is deprecated, and its use is discouraged in favor of 389.Dq Fl j Li any . 390.Sh SEE ALSO 391.Xr kill 1 , 392.Xr killall 1 , 393.Xr ps 1 , 394.Xr flock 2 , 395.Xr kill 2 , 396.Xr sigaction 2 , 397.Xr kvm 3 , 398.Xr pidfile 3 , 399.Xr re_format 7 400.\" Xr signal 7 401.Sh HISTORY 402The 403.Nm pkill 404and 405.Nm pgrep 406utilities 407first appeared in 408.Nx 1.6 . 409They are modelled after utilities of the same name that appeared in Sun 410Solaris 7. 411They made their first appearance in 412.Fx 5.3 . 413.Sh AUTHORS 414.An Andrew Doran Aq Mt ad@NetBSD.org 415