usr.bin/pkill/pkill.1

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