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.2 2004/07/28 02:51:06 cpressey 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 Jul 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 Ar pattern Op ...
  57 .Nm pkill
  58 .Op Fl signal
  59 .Op Fl fnvx
  60 .Op Fl G Ar gid
  61 .Op Fl P Ar ppid
  62 .Op Fl U Ar uid
  63 .Op Fl g Ar pgrp
  64 .Op Fl s Ar sid
  65 .Op Fl t Ar tty
  66 .Op Fl u Ar euid
  67 .Op Ar pattern Op ...
  68 .Sh DESCRIPTION
  69 The
  70 .Nm pgrep
  71 command searches the process table on the running system and prints the
  72 process IDs of all processes that match the criteria given on the command
  73 line.
  74 .Pp
  75 The
  76 .Nm pkill
  77 command searches the process table on the running system and signals all
  78 processes that match the criteria given on the command line.
  79 .Pp
  80 The following options are available:
  81 .Bl -tag -width xxxxxxxx
  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 P Ar ppid
  87 Restrict matches to processes with a parent process ID in the
  88 comma-separated list
  89 .Ar ppid .
  90 .It Fl U Ar uid
  91 Restrict matches to processes with a real user ID in the comma-separated
  92 list
  93 .Ar uid .
  94 .It Fl d Ar delim
  95 Specify a delimiter to be printed between each process ID.
  96 The default is a newline.
  97 This option can only be used with the
  98 .Nm pgrep
  99 command.
 100 .It Fl f
 101 Match against full argument lists.
 102 The default is to match against process names.
 103 .It Fl g Ar pgrp
 104 Restrict matches to processes with a process group ID in the comma-separated
 105 list
 106 .Ar pgrp .
 107 The value zero is taken to mean the process group ID of the running
 108 .Nm pgrep
 109 or
 110 .Nm pkill
 111 command.
 112 .It Fl l
 113 Long output.
 114 Print the process name in addition to the process ID for each matching
 115 process.
 116 If used in conjunction with
 117 .Fl f ,
 118 print the process ID and the full argument list for each matching process.
 119 This option can only be used with the
 120 .Nm pgrep
 121 command.
 122 .It Fl n
 123 Match only the most recently created process, if any.
 124 .It Fl s Ar sid
 125 Restrict matches to processes with a session ID in the comma-separated
 126 list
 127 .Ar sid .
 128 The value zero is taken to mean the session ID of the running
 129 .Nm pgrep
 130 or
 131 .Nm pkill
 132 command.
 133 .It Fl t Ar tty
 134 Restrict matches to processes associated with a terminal in the
 135 comma-separated list
 136 .Ar tty .
 137 Terminal names may be of the form
 138 .Sq ttyxx
 139 or the shortened form
 140 .Sq xx .
 141 A single dash (`-') matches processes not associated with a terminal.
 142 .It Fl u Ar euid
 143 Restrict matches to processes with an effective user ID in the
 144 comma-separated list
 145 .Ar euid .
 146 .It Fl v
 147 Reverse the sense of the matching; display processes that do not match the
 148 given criteria.
 149 .It Fl x
 150 Require an exact match of the process name, or argument list if
 151 .Fl f
 152 is given.
 153 The default is to match any substring.
 154 .It Fl signal
 155 A non-negative decimal number or symbolic signal name specifying the signal
 156 to be sent instead of the default TERM.
 157 This option is valid only when given as the first argument to
 158 .Nm pkill .
 159 .El
 160 .Pp
 161 Note that a running
 162 .Nm pgrep
 163 or
 164 .Nm pkill
 165 process will never consider itself nor system processes (kernel threads) as
 166 a potential match.
 167 .Sh EXIT STATUS
 168 .Nm pgrep
 169 and
 170 .Nm pkill
 171 return one of the following values upon exit:
 172 .Bl -tag -width foo
 173 .It 0
 174 One or more processes were matched.
 175 .It 1
 176 No processes were matched.
 177 .It 2
 178 Invalid options were specified on the command line.
 179 .It 3
 180 An internal error occurred.
 181 .El
 182 .Sh SEE ALSO
 183 .Xr kill 1 ,
 184 .Xr ps 1 ,
 185 .Xr kill 2 ,
 186 .Xr sigaction 2 ,
 187 .Xr re_format 7 ,
 188 .Xr signal 7
 189 .Sh HISTORY
 190 .Nm pkill
 191 and
 192 .Nm pgrep
 193 originated in
 194 .Nx 1.6 .
 195 They are modelled after utilities of the same name that appeared in Sun
 196 Solaris 7.
 197 They first appeared in
 198 .Dx
 199 in version 1.1.
 200 .Sh AUTHORS
 201 .An Andrew Doran
 202 .Aq ad@NetBSD.org .