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 June 24, 2025 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, excluding itself and all direct ancestors unless the 75.Fl a 76option is specified. 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, excluding itself 82and all direct ancestors unless the 83.Fl a 84option is specified. 85.Pp 86The following options are available: 87.Bl -tag -width ".Fl F Ar pidfile" 88.It Fl F Ar pidfile 89Restrict matches to a process whose PID is stored in the 90.Ar pidfile 91file. 92.It Fl G Ar gid 93Restrict matches to processes with a real group ID in the comma-separated 94list 95.Ar gid . 96.It Fl I 97Request confirmation before attempting to signal each process. 98.It Fl L 99The 100.Ar pidfile 101file given for the 102.Fl F 103option must be locked with the 104.Xr flock 2 105syscall or created with 106.Xr pidfile 3 . 107.It Fl M Ar core 108Extract values associated with the name list from the specified core 109instead of the currently running system. 110.It Fl N Ar system 111Extract the name list from the specified system instead of the default, 112which is the kernel image the system has booted from. 113.It Fl P Ar ppid 114Restrict matches to processes with a parent process ID in the 115comma-separated list 116.Ar ppid . 117.It Fl S 118Search also in system processes (kernel threads). 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 d Ar delim 124Specify a delimiter to be printed between each process ID. 125The default is a newline. 126This option can only be used with the 127.Nm pgrep 128command. 129.It Fl a 130Include process ancestors in the match list. 131By default, the current 132.Nm pgrep 133or 134.Nm pkill 135process and all of its ancestors are excluded (unless 136.Fl v 137is used). 138Note that the 139.Fl a 140option will not 141.Dq unhide 142the 143.Nm pgrep 144or 145.Nm pkill 146process itself, even with 147.Fl v . 148.It Fl c Ar class 149Restrict matches to processes running with specified login class 150.Ar class . 151.It Fl f 152Match against full argument lists. 153The default is to match against process names. 154.It Fl g Ar pgrp 155Restrict matches to processes with a process group ID in the comma-separated 156list 157.Ar pgrp . 158The value zero is taken to mean the process group ID of the running 159.Nm pgrep 160or 161.Nm pkill 162command. 163.It Fl i 164Ignore case distinctions in both the process table and the supplied pattern. 165.It Fl j Ar jail 166Restrict matches to processes inside the specified jails. 167The argument 168.Ar jail 169may be 170.Dq Li any 171to match processes in any jail, 172.Dq Li none 173to match processes not in jail, 174or a comma-separated list of jail IDs or names. 175.It Fl l 176Long output. 177For 178.Nm pgrep , 179print the process name in addition to the process ID for each matching 180process. 181If used in conjunction with 182.Fl f , 183print the process ID and the full argument list for each matching process. 184For 185.Nm pkill , 186display the kill command used for each process killed. 187.It Fl n 188Select only the newest (most recently started) of the matching processes. 189.It Fl o 190Select only the oldest (least recently started) of the matching processes. 191.It Fl q 192For 193.Nm pgrep , 194Do not write anything to standard output. 195.It Fl s Ar sid 196Restrict matches to processes with a session ID in the comma-separated 197list 198.Ar sid . 199The value zero is taken to mean the session ID of the running 200.Nm pgrep 201or 202.Nm pkill 203command. 204.It Fl t Ar tty 205Restrict matches to processes associated with a terminal in the 206comma-separated list 207.Ar tty . 208Terminal names may be of the form 209.Pa tty Ns Ar xx 210or the shortened form 211.Ar xx . 212A single dash 213.Pq Ql - 214matches processes not associated with a terminal. 215.It Fl u Ar euid 216Restrict matches to processes with an effective user ID in the 217comma-separated list 218.Ar euid . 219.It Fl v 220Reverse the sense of the matching; display processes that do not match the 221given criteria. 222.It Fl x 223Require an exact match of the process name, or argument list if 224.Fl f 225is given. 226The default is to match any substring. 227.It Fl Ns Ar signal 228A non-negative decimal number or symbolic signal name specifying the signal 229to be sent instead of the default 230.Dv TERM . 231This option is valid only when given as the first argument to 232.Nm pkill . 233.El 234.Pp 235If any 236.Ar pattern 237operands are specified, they are used as extended regular expressions to match 238the command name or full argument list of each process. 239If the 240.Fl f 241option is not specified, then the 242.Ar pattern 243will attempt to match the command name. 244However, presently 245.Fx 246will only keep track of the first 19 characters of the command 247name for each process. 248Attempts to match any characters after the first 19 of a command name 249will quietly fail. 250.Pp 251Note that a running 252.Nm pgrep 253or 254.Nm pkill 255process will never consider itself nor system processes (kernel threads) as 256a potential match. 257.Sh IMPLEMENTATION NOTES 258The Sun Solaris implementation utilised procfs to obtain process information. 259This implementation utilises 260.Xr kvm 3 261instead. 262On a live system, 263.Xr kvm 3 264uses 265.Va kern.proc 266MIB to obtain the list of processes, kernel memory through 267.Pa /dev/kmem 268is not accessed. 269.Sh EXIT STATUS 270The 271.Nm pgrep 272and 273.Nm pkill 274utilities 275return one of the following values upon exit: 276.Bl -tag -width indent 277.It 0 278One or more processes were matched. 279.It 1 280No processes were matched. 281.It 2 282Invalid options were specified on the command line. 283.It 3 284An internal error occurred. 285.El 286.Sh EXAMPLES 287Show the pid of the process holding the 288.Pa /tmp/.X0-lock 289pid file: 290.Bd -literal -offset indent 291$ pgrep -F /tmp/.X0-lock 2921211 293.Ed 294.Pp 295Show the pid and the name of the process including kernel threads in the 296search: 297.Bd -literal -offset indent 298$ pgrep -lS vnlru 29937 vnlru 300.Ed 301.Pp 302Search for processes including kernel threads that match the extended regular 303expression pattern: 304.Bd -literal -offset indent 305$ pgrep -S 'crypto.*[2-3]' 30620 30719 3086 3095 310.Ed 311.Pp 312Show long output for firefox processes: 313.Bd -literal -offset indent 314$ pgrep -l firefox 3151312 firefox 3161309 firefox 3171288 firefox 3181280 firefox 3191279 firefox 3201278 firefox 3211277 firefox 3221264 firefox 323.Ed 324.Pp 325Same as above but just showing the pid of the most recent process: 326.Bd -literal -offset indent 327$ pgrep -n firefox 3281312 329.Ed 330.Pp 331Look for vim processes. 332Match against the full argument list: 333.Bd -literal -offset indent 334$ pgrep -f vim 33544968 33630790 337.Ed 338.Pp 339Same as above but matching against the 340.Ql list 341word and showing the full argument list: 342.Bd -literal -offset indent 343$ pgrep -f -l list 34430790 vim list.txt 345.Ed 346.Pp 347Send 348.Va SIGSTOP 349signal to processes that are an exact match: 350.Bd -literal -offset indent 351$ pkill -SIGSTOP -f -x "vim list.txt" 352.Ed 353.Pp 354Without 355.Fl f 356names over 19 characters will silently fail: 357.Bd -literal -offset indent 358$ vim this_is_a_very_long_file_name & 359[1] 36689 360$ 361 362[1]+ Stopped vim this_is_a_very_long_file_name 363$ pgrep "vim this" 364$ 365.Ed 366.Pp 367Same as above using the 368.Fl f 369flag: 370.Bd -literal -offset indent 371$ pgrep -f "vim this" 37236689 373.Ed 374.Pp 375Find the 376.Xr top 1 377command running in any jail: 378.Bd -literal -offset indent 379$ pgrep -j any top 38034498 381.Ed 382.Pp 383Show all processes running in jail ID 58: 384.Bd -literal -offset indent 385$ pgrep -l -j58 '.*' 38628397 pkg-static 38728396 pkg-static 38828255 sh 38928254 make 390.Ed 391.Sh COMPATIBILITY 392Historically the option 393.Dq Fl j Li 0 394means any jail, although in other utilities such as 395.Xr ps 1 396jail ID 397.Li 0 398has the opposite meaning, not in jail. 399Therefore 400.Dq Fl j Li 0 401is deprecated, and its use is discouraged in favor of 402.Dq Fl j Li any . 403.Sh SEE ALSO 404.Xr kill 1 , 405.Xr killall 1 , 406.Xr ps 1 , 407.Xr flock 2 , 408.Xr kill 2 , 409.Xr sigaction 2 , 410.Xr kvm 3 , 411.Xr pidfile 3 , 412.Xr re_format 7 413.\" Xr signal 7 414.Sh HISTORY 415The 416.Nm pkill 417and 418.Nm pgrep 419utilities 420first appeared in 421.Nx 1.6 . 422They are modelled after utilities of the same name that appeared in Sun 423Solaris 7. 424They made their first appearance in 425.Fx 5.3 . 426.Sh AUTHORS 427.An Andrew Doran Aq Mt ad@NetBSD.org 428