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