bin/pkill/pkill.1

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