usr.bin/pkill/pkill.1

   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 August 9, 2013
  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 jid
  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 jid
  67 .Op Fl s Ar sid
  68 .Op Fl t Ar tty
  69 .Op Fl u Ar euid
  70 .Ar pattern ...
  71 .Sh DESCRIPTION
  72 The
  73 .Nm pgrep
  74 command searches the process table on the running system and prints the
  75 process IDs of all processes that match the criteria given on the command
  76 line.
  77 .Pp
  78 The
  79 .Nm pkill
  80 command searches the process table on the running system and signals all
  81 processes that match the criteria given on the command line.
  82 .Pp
  83 The following options are available:
  84 .Bl -tag -width ".Fl F Ar pidfile"
  85 .It Fl F Ar pidfile
  86 Restrict matches to a process whose PID is stored in the
  87 .Ar pidfile
  88 file.
  89 .It Fl G Ar gid
  90 Restrict matches to processes with a real group ID in the comma-separated
  91 list
  92 .Ar gid .
  93 .It Fl I
  94 Request confirmation before attempting to signal each process.
  95 .It Fl L
  96 The
  97 .Ar pidfile
  98 file given for the
  99 .Fl F
 100 option must be locked with the
 101 .Xr flock 2
 102 syscall or created with
 103 .Xr pidfile 3 .
 104 .It Fl M Ar core
 105 Extract values associated with the name list from the specified core
 106 instead of the currently running system.
 107 .It Fl N Ar system
 108 Extract the name list from the specified system instead of the default,
 109 which is the kernel image the system has booted from.
 110 .It Fl P Ar ppid
 111 Restrict matches to processes with a parent process ID in the
 112 comma-separated list
 113 .Ar ppid .
 114 .It Fl S
 115 Search also in system processes (kernel threads).
 116 .It Fl U Ar uid
 117 Restrict matches to processes with a real user ID in the comma-separated
 118 list
 119 .Ar uid .
 120 .It Fl d Ar delim
 121 Specify a delimiter to be printed between each process ID.
 122 The default is a newline.
 123 This option can only be used with the
 124 .Nm pgrep
 125 command.
 126 .It Fl a
 127 Include process ancestors in the match list.
 128 By default, the current
 129 .Nm pgrep
 130 or
 131 .Nm pkill
 132 process and all of its ancestors are excluded (unless
 133 .Fl v
 134 is used).
 135 .It Fl c Ar class
 136 Restrict matches to processes running with specified login class
 137 .Ar class .
 138 .It Fl f
 139 Match against full argument lists.
 140 The default is to match against process names.
 141 .It Fl g Ar pgrp
 142 Restrict matches to processes with a process group ID in the comma-separated
 143 list
 144 .Ar pgrp .
 145 The value zero is taken to mean the process group ID of the running
 146 .Nm pgrep
 147 or
 148 .Nm pkill
 149 command.
 150 .It Fl i
 151 Ignore case distinctions in both the process table and the supplied pattern.
 152 .It Fl j Ar jid
 153 Restrict matches to processes inside jails with a jail ID in the comma-separated
 154 list
 155 .Ar jid .
 156 The value
 157 .Dq Li any
 158 matches processes in any jail.
 159 The value
 160 .Dq Li none
 161 matches processes not in jail.
 162 .It Fl l
 163 Long output.
 164 For
 165 .Nm pgrep ,
 166 print the process name in addition to the process ID for each matching
 167 process.
 168 If used in conjunction with
 169 .Fl f ,
 170 print the process ID and the full argument list for each matching process.
 171 For
 172 .Nm pkill ,
 173 display the kill command used for each process killed.
 174 .It Fl n
 175 Select only the newest (most recently started) of the matching processes.
 176 .It Fl o
 177 Select only the oldest (least recently started) of the matching processes.
 178 .It Fl q
 179 Do not write anything to standard output.
 180 .It Fl s Ar sid
 181 Restrict matches to processes with a session ID in the comma-separated
 182 list
 183 .Ar sid .
 184 The value zero is taken to mean the session ID of the running
 185 .Nm pgrep
 186 or
 187 .Nm pkill
 188 command.
 189 .It Fl t Ar tty
 190 Restrict matches to processes associated with a terminal in the
 191 comma-separated list
 192 .Ar tty .
 193 Terminal names may be of the form
 194 .Pa tty Ns Ar xx
 195 or the shortened form
 196 .Ar xx .
 197 A single dash
 198 .Pq Ql -
 199 matches processes not associated with a terminal.
 200 .It Fl u Ar euid
 201 Restrict matches to processes with an effective user ID in the
 202 comma-separated list
 203 .Ar euid .
 204 .It Fl v
 205 Reverse the sense of the matching; display processes that do not match the
 206 given criteria.
 207 .It Fl x
 208 Require an exact match of the process name, or argument list if
 209 .Fl f
 210 is given.
 211 The default is to match any substring.
 212 .It Fl Ns Ar signal
 213 A non-negative decimal number or symbolic signal name specifying the signal
 214 to be sent instead of the default
 215 .Dv TERM .
 216 This option is valid only when given as the first argument to
 217 .Nm pkill .
 218 .El
 219 .Pp
 220 If any
 221 .Ar pattern
 222 operands are specified, they are used as regular expressions to match
 223 the command name or full argument list of each process.
 224 If the
 225 .Fl f
 226 option is not specified, then the
 227 .Ar pattern
 228 will attempt to match the command name.
 229 However, presently
 230 .Fx
 231 will only keep track of the first 19 characters of the command
 232 name for each process.
 233 Attempts to match any characters after the first 19 of a command name
 234 will quietly fail.
 235 .Pp
 236 Note that a running
 237 .Nm pgrep
 238 or
 239 .Nm pkill
 240 process will never consider itself nor system processes (kernel threads) as
 241 a potential match.
 242 .Sh EXIT STATUS
 243 The
 244 .Nm pgrep
 245 and
 246 .Nm pkill
 247 utilities
 248 return one of the following values upon exit:
 249 .Bl -tag -width indent
 250 .It 0
 251 One or more processes were matched.
 252 .It 1
 253 No processes were matched.
 254 .It 2
 255 Invalid options were specified on the command line.
 256 .It 3
 257 An internal error occurred.
 258 .El
 259 .Sh COMPATIBILITY
 260 Historically the option
 261 .Dq Fl j Li 0
 262 means any jail, although in other utilities such as
 263 .Xr ps 1
 264 jail ID
 265 .Li 0
 266 has the opposite meaning, not in jail.
 267 Therefore
 268 .Dq Fl j Li 0
 269 is deprecated, and its use is discouraged in favor of
 270 .Dq Fl j Li any .
 271 .Sh SEE ALSO
 272 .Xr kill 1 ,
 273 .Xr killall 1 ,
 274 .Xr ps 1 ,
 275 .Xr flock 2 ,
 276 .Xr kill 2 ,
 277 .Xr sigaction 2 ,
 278 .Xr pidfile 3 ,
 279 .Xr re_format 7
 280 .\" Xr signal 7
 281 .Sh HISTORY
 282 The
 283 .Nm pkill
 284 and
 285 .Nm pgrep
 286 utilities
 287 first appeared in
 288 .Nx 1.6 .
 289 They are modelled after utilities of the same name that appeared in Sun
 290 Solaris 7.
 291 They first appeared in
 292 .Dx 1.1.
 293 .Sh AUTHORS
 294 .An Andrew Doran Aq Mt ad@NetBSD.org