usr.bin/pkill/pkill.1

   1 .\"     $NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant Exp $
   2 .\"     $DragonFly: src/usr.bin/pkill/pkill.1,v 1.6 2007/05/17 08:19:02 swildner Exp $
   3 .\"
   4 .\" Copyright (c) 2002 The NetBSD Foundation, Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" This code is derived from software contributed to The NetBSD Foundation
   8 .\" by Andrew Doran.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"        This product includes software developed by the NetBSD
  21 .\"        Foundation, Inc. and its contributors.
  22 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  23 .\"    contributors may be used to endorse or promote products derived
  24 .\"    from this software without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  36 .\" POSSIBILITY OF SUCH DAMAGE.
  37 .\"
  38 .Dd July 27, 2004
  39 .Dt PKILL 1
  40 .Os
  41 .Sh NAME
  42 .Nm pgrep ,
  43 .Nm pkill
  44 .Nd find or signal processes by name
  45 .Sh SYNOPSIS
  46 .Nm pgrep
  47 .Op Fl flnvx
  48 .Op Fl G Ar gid
  49 .Op Fl P Ar ppid
  50 .Op Fl U Ar uid
  51 .Op Fl d Ar delim
  52 .Op Fl g Ar pgrp
  53 .Op Fl s Ar sid
  54 .Op Fl t Ar tty
  55 .Op Fl u Ar euid
  56 .Op Fl j Ar jid
  57 .Op Ar pattern Op ...
  58 .Nm pkill
  59 .Op Fl signal
  60 .Op Fl fnvx
  61 .Op Fl G Ar gid
  62 .Op Fl P Ar ppid
  63 .Op Fl U Ar uid
  64 .Op Fl g Ar pgrp
  65 .Op Fl s Ar sid
  66 .Op Fl t Ar tty
  67 .Op Fl u Ar euid
  68 .Op Fl j Ar jid
  69 .Op Ar pattern Op ...
  70 .Sh DESCRIPTION
  71 The
  72 .Nm pgrep
  73 command searches the process table on the running system and prints the
  74 process IDs of all processes that match the criteria given on the command
  75 line.
  76 .Pp
  77 The
  78 .Nm pkill
  79 command searches the process table on the running system and signals all
  80 processes that match the criteria given on the command line.
  81 .Pp
  82 The following options are available:
  83 .Bl -tag -width xxxxxxxx
  84 .It Fl G Ar gid
  85 Restrict matches to processes with a real group ID in the comma-separated
  86 list
  87 .Ar gid .
  88 .It Fl P Ar ppid
  89 Restrict matches to processes with a parent process ID in the
  90 comma-separated list
  91 .Ar ppid .
  92 .It Fl U Ar uid
  93 Restrict matches to processes with a real user ID in the comma-separated
  94 list
  95 .Ar uid .
  96 .It Fl d Ar delim
  97 Specify a delimiter to be printed between each process ID.
  98 The default is a newline.
  99 This option can only be used with the
 100 .Nm pgrep
 101 command.
 102 .It Fl f
 103 Match against full argument lists.
 104 The default is to match against process names.
 105 .It Fl g Ar pgrp
 106 Restrict matches to processes with a process group ID in the comma-separated
 107 list
 108 .Ar pgrp .
 109 The value zero is taken to mean the process group ID of the running
 110 .Nm pgrep
 111 or
 112 .Nm pkill
 113 command.
 114 .It Fl j Ar jid
 115 Restrict matches to processes inside jails with a jail ID in the comma-separated
 116 list
 117 .Ar jid .
 118 The value
 119 .Dq Li -1
 120 matches processes in any jail.
 121 The value
 122 .Dq Li 0
 123 matches processes not in a jail.
 124 .It Fl l
 125 Long output.
 126 Print the process name in addition to the process ID for each matching
 127 process.
 128 If used in conjunction with
 129 .Fl f ,
 130 print the process ID and the full argument list for each matching process.
 131 This option can only be used with the
 132 .Nm pgrep
 133 command.
 134 .It Fl n
 135 Match only the most recently created process, if any.
 136 .It Fl s Ar sid
 137 Restrict matches to processes with a session ID in the comma-separated
 138 list
 139 .Ar sid .
 140 The value zero is taken to mean the session ID of the running
 141 .Nm pgrep
 142 or
 143 .Nm pkill
 144 command.
 145 .It Fl t Ar tty
 146 Restrict matches to processes associated with a terminal in the
 147 comma-separated list
 148 .Ar tty .
 149 Terminal names may be of the form
 150 .Sq ttyxx
 151 or the shortened form
 152 .Sq xx .
 153 A single dash (`-') matches processes not associated with a terminal.
 154 .It Fl u Ar euid
 155 Restrict matches to processes with an effective user ID in the
 156 comma-separated list
 157 .Ar euid .
 158 .It Fl v
 159 Reverse the sense of the matching; display processes that do not match the
 160 given criteria.
 161 .It Fl x
 162 Require an exact match of the process name, or argument list if
 163 .Fl f
 164 is given.
 165 The default is to match any substring.
 166 .It Fl signal
 167 A non-negative decimal number or symbolic signal name specifying the signal
 168 to be sent instead of the default TERM.
 169 This option is valid only when given as the first argument to
 170 .Nm pkill .
 171 .El
 172 .Pp
 173 Note that a running
 174 .Nm pgrep
 175 or
 176 .Nm pkill
 177 process will never consider itself nor system processes (kernel threads) as
 178 a potential match.
 179 .Sh DIAGNOSTICS
 180 .Nm pgrep
 181 and
 182 .Nm pkill
 183 return one of the following values upon exit:
 184 .Bl -tag -width foo
 185 .It 0
 186 One or more processes were matched.
 187 .It 1
 188 No processes were matched.
 189 .It 2
 190 Invalid options were specified on the command line.
 191 .It 3
 192 An internal error occurred.
 193 .El
 194 .Sh SEE ALSO
 195 .Xr kill 1 ,
 196 .Xr ps 1 ,
 197 .Xr kill 2 ,
 198 .Xr sigaction 2 ,
 199 .Xr signal 3 ,
 200 .Xr re_format 7
 201 .Sh HISTORY
 202 .Nm pkill
 203 and
 204 .Nm pgrep
 205 originated in
 206 .Nx 1.6 .
 207 They are modeled after utilities of the same name that appeared in Sun
 208 Solaris 7.
 209 They first appeared in
 210 .Dx
 211 in version 1.1.
 212 .Sh AUTHORS
 213 .An Andrew Doran
 214 .Aq ad@NetBSD.org .