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