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 .\" 3. All advertising materials mentioning features or use of this software
  20 .\"    must display the following acknowledgement:
  21 .\"        This product includes software developed by the NetBSD
  22 .\"        Foundation, Inc. and its contributors.
  23 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  24 .\"    contributors may be used to endorse or promote products derived
  25 .\"    from this software without specific prior written permission.
  26 .\"
  27 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  28 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  29 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  30 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  31 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  32 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  33 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  34 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  35 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  36 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  37 .\" POSSIBILITY OF SUCH DAMAGE.
  38 .\"
  39 .Dd May 16, 2009
  40 .Dt PKILL 1
  41 .Os
  42 .Sh NAME
  43 .Nm pgrep , pkill
  44 .Nd find or signal processes by name
  45 .Sh SYNOPSIS
  46 .Nm pgrep
  47 .Op Fl LSafilnovx
  48 .Op Fl F Ar pidfile
  49 .Op Fl G Ar gid
  50 .Op Fl M Ar core
  51 .Op Fl N Ar system
  52 .Op Fl P Ar ppid
  53 .Op Fl U Ar uid
  54 .Op Fl d Ar delim
  55 .Op Fl g Ar pgrp
  56 .Op Fl j Ar jid
  57 .Op Fl s Ar sid
  58 .Op Fl t Ar tty
  59 .Op Fl u Ar euid
  60 .Ar pattern ...
  61 .Nm pkill
  62 .Op Fl Ar signal
  63 .Op Fl ILafinovx
  64 .Op Fl F Ar pidfile
  65 .Op Fl G Ar gid
  66 .Op Fl M Ar core
  67 .Op Fl N Ar system
  68 .Op Fl P Ar ppid
  69 .Op Fl U Ar uid
  70 .Op Fl g Ar pgrp
  71 .Op Fl j Ar jid
  72 .Op Fl s Ar sid
  73 .Op Fl t Ar tty
  74 .Op Fl u Ar euid
  75 .Ar pattern ...
  76 .Sh DESCRIPTION
  77 The
  78 .Nm pgrep
  79 command searches the process table on the running system and prints the
  80 process IDs of all processes that match the criteria given on the command
  81 line.
  82 .Pp
  83 The
  84 .Nm pkill
  85 command searches the process table on the running system and signals all
  86 processes that match the criteria given on the command line.
  87 .Pp
  88 The following options are available:
  89 .Bl -tag -width ".Fl F Ar pidfile"
  90 .It Fl F Ar pidfile
  91 Restrict matches to a process whose PID is stored in the
  92 .Ar pidfile
  93 file.
  94 .It Fl G Ar gid
  95 Restrict matches to processes with a real group ID in the comma-separated
  96 list
  97 .Ar gid .
  98 .It Fl I
  99 Request confirmation before attempting to signal each process.
 100 .It Fl L
 101 The
 102 .Ar pidfile
 103 file given for the
 104 .Fl F
 105 option must be locked with the
 106 .Xr flock 2
 107 syscall or created with
 108 .Xr pidfile 3 .
 109 .It Fl M Ar core
 110 Extract values associated with the name list from the specified core
 111 instead of the currently running system.
 112 .It Fl N Ar system
 113 Extract the name list from the specified system instead of the default,
 114 which is the kernel image the system has booted from.
 115 .It Fl P Ar ppid
 116 Restrict matches to processes with a parent process ID in the
 117 comma-separated list
 118 .Ar ppid .
 119 .It Fl S
 120 Search also in system processes (kernel threads).
 121 .It Fl U Ar uid
 122 Restrict matches to processes with a real user ID in the comma-separated
 123 list
 124 .Ar uid .
 125 .It Fl d Ar delim
 126 Specify a delimiter to be printed between each process ID.
 127 The default is a newline.
 128 This option can only be used with the
 129 .Nm pgrep
 130 command.
 131 .It Fl a
 132 Include process ancestors in the match list.
 133 By default, the current
 134 .Nm pgrep
 135 or
 136 .Nm pkill
 137 process and all of its ancestors are excluded (unless
 138 .Fl v
 139 is used).
 140 .It Fl f
 141 Match against full argument lists.
 142 The default is to match against process names.
 143 .It Fl g Ar pgrp
 144 Restrict matches to processes with a process group ID in the comma-separated
 145 list
 146 .Ar pgrp .
 147 The value zero is taken to mean the process group ID of the running
 148 .Nm pgrep
 149 or
 150 .Nm pkill
 151 command.
 152 .It Fl i
 153 Ignore case distinctions in both the process table and the supplied pattern.
 154 .It Fl j Ar jid
 155 Restrict matches to processes inside jails with a jail ID in the comma-separated
 156 list
 157 .Ar jid .
 158 The value
 159 .Dq Li any
 160 matches processes in any jail.
 161 The value
 162 .Dq Li none
 163 matches processes not in jail.
 164 .It Fl l
 165 Long output.
 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 This option can only be used with the
 172 .Nm pgrep
 173 command.
 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 s Ar sid
 179 Restrict matches to processes with a session ID in the comma-separated
 180 list
 181 .Ar sid .
 182 The value zero is taken to mean the session ID of the running
 183 .Nm pgrep
 184 or
 185 .Nm pkill
 186 command.
 187 .It Fl t Ar tty
 188 Restrict matches to processes associated with a terminal in the
 189 comma-separated list
 190 .Ar tty .
 191 Terminal names may be of the form
 192 .Pa tty Ns Ar xx
 193 or the shortened form
 194 .Ar xx .
 195 A single dash
 196 .Pq Ql -
 197 matches processes not associated with a terminal.
 198 .It Fl u Ar euid
 199 Restrict matches to processes with an effective user ID in the
 200 comma-separated list
 201 .Ar euid .
 202 .It Fl v
 203 Reverse the sense of the matching; display processes that do not match the
 204 given criteria.
 205 .It Fl x
 206 Require an exact match of the process name, or argument list if
 207 .Fl f
 208 is given.
 209 The default is to match any substring.
 210 .It Fl Ns Ar signal
 211 A non-negative decimal number or symbolic signal name specifying the signal
 212 to be sent instead of the default
 213 .Dv TERM .
 214 This option is valid only when given as the first argument to
 215 .Nm pkill .
 216 .El
 217 .Pp
 218 If any
 219 .Ar pattern
 220 operands are specified, they are used as regular expressions to match
 221 the command name or full argument list of each process.
 222 If the
 223 .Fl f
 224 option is not specified, then the
 225 .Ar pattern
 226 will attempt to match the command name.
 227 However, presently
 228 .Fx
 229 will only keep track of the first 19 characters of the command
 230 name for each process.
 231 Attempts to match any characters after the first 19 of a command name
 232 will quietly fail.
 233 .Pp
 234 Note that a running
 235 .Nm pgrep
 236 or
 237 .Nm pkill
 238 process will never consider itself nor system processes (kernel threads) as
 239 a potential match.
 240 .Sh EXIT STATUS
 241 The
 242 .Nm pgrep
 243 and
 244 .Nm pkill
 245 utilities
 246 return one of the following values upon exit:
 247 .Bl -tag -width indent
 248 .It 0
 249 One or more processes were matched.
 250 .It 1
 251 No processes were matched.
 252 .It 2
 253 Invalid options were specified on the command line.
 254 .It 3
 255 An internal error occurred.
 256 .El
 257 .Sh COMPATIBILITY
 258 Historically the option
 259 .Dq Fl j Li 0
 260 means any jail, although in other utilities such as
 261 .Xr ps 1
 262 jail ID
 263 .Li 0
 264 has the opposite meaning, not in jail.
 265 Therefore
 266 .Dq Fl j Li 0
 267 is deprecated, and its use is discouraged in favor of
 268 .Dq Fl j Li any .
 269 .Sh SEE ALSO
 270 .Xr kill 1 ,
 271 .Xr killall 1 ,
 272 .Xr ps 1 ,
 273 .Xr flock 2 ,
 274 .Xr kill 2 ,
 275 .Xr sigaction 2 ,
 276 .Xr pidfile 3 ,
 277 .Xr re_format 7
 278 .\" Xr signal 7
 279 .Sh HISTORY
 280 The
 281 .Nm pkill
 282 and
 283 .Nm pgrep
 284 utilities
 285 first appeared in
 286 .Nx 1.6 .
 287 They are modelled after utilities of the same name that appeared in Sun
 288 Solaris 7.
 289 They made their first appearance in
 290 .Fx 5.3 .
 291 .Sh AUTHORS
 292 .An Andrew Doran
 293 .Aq ad@NetBSD.org