adv_cmds/pkill/pkill.1

   1 .\"     $NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant Exp $
   2 .\"
   3 .\" $FreeBSD: src/bin/pkill/pkill.1,v 1.8 2010/07/12 01:58:46 brian Exp $
   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 Lafilnoqvx
  41 .Op Fl F Ar pidfile
  42 .Op Fl G Ar gid
  43 .Op Fl P Ar ppid
  44 .Op Fl U Ar uid
  45 .Op Fl d Ar delim
  46 .Op Fl g Ar pgrp
  47 .Op Fl t Ar tty
  48 .Op Fl u Ar euid
  49 .Ar pattern ...
  50 .Nm pkill
  51 .Op Fl Ar signal
  52 .Op Fl ILafilnovx
  53 .Op Fl F Ar pidfile
  54 .Op Fl G Ar gid
  55 .Op Fl P Ar ppid
  56 .Op Fl U Ar uid
  57 .Op Fl g Ar pgrp
  58 .Op Fl t Ar tty
  59 .Op Fl u Ar euid
  60 .Ar pattern ...
  61 .Sh DESCRIPTION
  62 The
  63 .Nm pgrep
  64 command searches the process table on the running system and prints the
  65 process IDs of all processes that match the criteria given on the command
  66 line.
  67 .Pp
  68 The
  69 .Nm pkill
  70 command searches the process table on the running system and signals all
  71 processes that match the criteria given on the command line.
  72 .Pp
  73 The following options are available:
  74 .Bl -tag -width ".Fl F Ar pidfile"
  75 .It Fl F Ar pidfile
  76 Restrict matches to a process whose PID is stored in the
  77 .Ar pidfile
  78 file.
  79 .It Fl G Ar gid
  80 Restrict matches to processes with a real group ID in the comma-separated
  81 list
  82 .Ar gid .
  83 .It Fl I
  84 Request confirmation before attempting to signal each process.
  85 .It Fl L
  86 The
  87 .Ar pidfile
  88 file given for the
  89 .Fl F
  90 option must be locked with the
  91 .Xr flock 2
  92 syscall or created with
  93 .Xr pidfile 3 .
  94 .It Fl P Ar ppid
  95 Restrict matches to processes with a parent process ID in the
  96 comma-separated list
  97 .Ar ppid .
  98 .It Fl U Ar uid
  99 Restrict matches to processes with a real user ID in the comma-separated
 100 list
 101 .Ar uid .
 102 .It Fl d Ar delim
 103 Specify a delimiter to be printed between each process ID.
 104 The default is a newline.
 105 This option can only be used with the
 106 .Nm pgrep
 107 command.
 108 .It Fl a
 109 Include process ancestors in the match list.
 110 By default, the current
 111 .Nm pgrep
 112 or
 113 .Nm pkill
 114 process and all of its ancestors are excluded (unless
 115 .Fl v
 116 is used).
 117 .It Fl f
 118 Match against full argument lists.
 119 The default is to match against process names.
 120 .It Fl g Ar pgrp
 121 Restrict matches to processes with a process group ID in the comma-separated
 122 list
 123 .Ar pgrp .
 124 The value zero is taken to mean the process group ID of the running
 125 .Nm pgrep
 126 or
 127 .Nm pkill
 128 command.
 129 .It Fl i
 130 Ignore case distinctions in both the process table and the supplied pattern.
 131 .It Fl l
 132 Long output.
 133 For
 134 .Nm pgrep ,
 135 print the process name in addition to the process ID for each matching
 136 process.
 137 If used in conjunction with
 138 .Fl f ,
 139 print the process ID and the full argument list for each matching process.
 140 For
 141 .Nm pkill ,
 142 display the kill command used for each process killed.
 143 .It Fl n
 144 Select only the newest (most recently started) of the matching processes.
 145 .It Fl o
 146 Select only the oldest (least recently started) of the matching processes.
 147 .It Fl q
 148 Do not write anything to standard output.
 149 .It Fl t Ar tty
 150 Restrict matches to processes associated with a terminal in the
 151 comma-separated list
 152 .Ar tty .
 153 Terminal names may be of the form
 154 .Pa tty Ns Ar xx
 155 or the shortened form
 156 .Ar xx .
 157 A single dash
 158 .Pq Ql -
 159 matches processes not associated with a terminal.
 160 .It Fl u Ar euid
 161 Restrict matches to processes with an effective user ID in the
 162 comma-separated list
 163 .Ar euid .
 164 .It Fl v
 165 Reverse the sense of the matching; display processes that do not match the
 166 given criteria.
 167 .It Fl x
 168 Require an exact match of the process name, or argument list if
 169 .Fl f
 170 is given.
 171 The default is to match any substring.
 172 .It Fl Ns Ar signal
 173 A non-negative decimal number or symbolic signal name specifying the signal
 174 to be sent instead of the default
 175 .Dv TERM .
 176 This option is valid only when given as the first argument to
 177 .Nm pkill .
 178 .El
 179 .Pp
 180 If any
 181 .Ar pattern
 182 operands are specified, they are used as regular expressions to match
 183 the command name or full argument list of each process.
 184 .Pp
 185 Note that a running
 186 .Nm pgrep
 187 or
 188 .Nm pkill
 189 process will never consider itself as
 190 a potential match.
 191 .Sh EXIT STATUS
 192 The
 193 .Nm pgrep
 194 and
 195 .Nm pkill
 196 utilities
 197 return one of the following values upon exit:
 198 .Bl -tag -width indent
 199 .It 0
 200 One or more processes were matched.
 201 .It 1
 202 No processes were matched.
 203 .It 2
 204 Invalid options were specified on the command line.
 205 .It 3
 206 An internal error occurred.
 207 .El
 208 .Sh SEE ALSO
 209 .Xr kill 1 ,
 210 .Xr killall 1 ,
 211 .Xr ps 1 ,
 212 .Xr flock 2 ,
 213 .Xr kill 2 ,
 214 .Xr sigaction 2 ,
 215 .Xr pidfile 3 ,
 216 .Xr re_format 7
 217 .\" Xr signal 7
 218 .Sh HISTORY
 219 The
 220 .Nm pkill
 221 and
 222 .Nm pgrep
 223 utilities
 224 first appeared in
 225 .Nx 1.6 .
 226 They are modelled after utilities of the same name that appeared in Sun
 227 Solaris 7.
 228 They made their first appearance in
 229 .Fx 5.3 .
 230 .Sh AUTHORS
 231 .An Andrew Doran
 232 .Aq ad@NetBSD.org