Annotation of src/usr.bin/pkill/pkill.1, Revision 1.10
1.10 ! millert 1: .\" $OpenBSD: pkill.1,v 1.9 2007/10/31 17:14:34 jmc Exp $
1.1 millert 2: .\" $NetBSD: pkill.1,v 1.8 2003/02/14 15:59:18 grant 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: .\"
1.10 ! millert 38: .Dd $Mdocdate: October 31 2007 $
1.1 millert 39: .Dt PKILL 1
40: .Os
41: .Sh NAME
1.3 jmc 42: .Nm pgrep , pkill
1.1 millert 43: .Nd find or signal processes by name
44: .Sh SYNOPSIS
45: .Nm pgrep
1.10 ! millert 46: .Op Fl flnovx
1.6 jmc 47: .Op Fl d Ar delim
1.1 millert 48: .Op Fl G Ar gid
1.6 jmc 49: .Op Fl g Ar pgrp
1.1 millert 50: .Op Fl P Ar ppid
51: .Op Fl s Ar sid
52: .Op Fl t Ar tty
1.6 jmc 53: .Op Fl U Ar uid
1.1 millert 54: .Op Fl u Ar euid
1.6 jmc 55: .Op Ar pattern ...
1.1 millert 56: .Nm pkill
1.9 jmc 57: .Op Fl Ar signal
1.10 ! millert 58: .Op Fl fnovx
1.1 millert 59: .Op Fl G Ar gid
1.6 jmc 60: .Op Fl g Ar pgrp
1.1 millert 61: .Op Fl P Ar ppid
62: .Op Fl s Ar sid
63: .Op Fl t Ar tty
1.6 jmc 64: .Op Fl U Ar uid
1.1 millert 65: .Op Fl u Ar euid
1.6 jmc 66: .Op Ar pattern ...
1.1 millert 67: .Sh DESCRIPTION
68: The
69: .Nm pgrep
70: command searches the process table on the running system and prints the
71: process IDs of all processes that match the criteria given on the command
72: line.
73: .Pp
74: The
75: .Nm pkill
76: command searches the process table on the running system and signals all
77: processes that match the criteria given on the command line.
78: .Pp
79: The following options are available:
1.7 jmc 80: .Bl -tag -width Ds
1.1 millert 81: .It Fl d Ar delim
82: Specify a delimiter to be printed between each process ID.
83: The default is a newline.
84: This option can only be used with the
85: .Nm pgrep
86: command.
87: .It Fl f
88: Match against full argument lists.
89: The default is to match against process names.
1.6 jmc 90: .It Fl G Ar gid
91: Restrict matches to processes with a real group ID in the comma-separated
92: list
93: .Ar gid .
1.1 millert 94: .It Fl g Ar pgrp
95: Restrict matches to processes with a process group ID in the comma-separated
96: list
97: .Ar pgrp .
98: The value zero is taken to mean the process group ID of the running
99: .Nm pgrep
100: or
101: .Nm pkill
102: command.
103: .It Fl l
104: Long output.
105: Print the process name in addition to the process ID for each matching
106: process.
107: If used in conjunction with
108: .Fl f ,
109: print the process ID and the full argument list for each matching process.
110: This option can only be used with the
111: .Nm pgrep
112: command.
113: .It Fl n
1.10 ! millert 114: Match only the most recently created (newest) process, if any.
! 115: Cannot be used in conjuction with
! 116: .Fl o .
! 117: .It Fl o
! 118: Match only the least recently created (oldest) process, if any.
! 119: Cannot be used in conjuction with
! 120: .Fl n .
1.6 jmc 121: .It Fl P Ar ppid
122: Restrict matches to processes with a parent process ID in the
123: comma-separated list
124: .Ar ppid .
1.1 millert 125: .It Fl s Ar sid
126: Restrict matches to processes with a session ID in the comma-separated
127: list
128: .Ar sid .
129: The value zero is taken to mean the session ID of the running
130: .Nm pgrep
131: or
132: .Nm pkill
133: command.
134: .It Fl t Ar tty
135: Restrict matches to processes associated with a terminal in the
136: comma-separated list
137: .Ar tty .
138: Terminal names may be of the form
139: .Sq ttyxx
140: or the shortened form
141: .Sq xx .
1.7 jmc 142: A single dash
143: .Pq Sq -
144: matches processes not associated with a terminal.
1.6 jmc 145: .It Fl U Ar uid
146: Restrict matches to processes with a real user ID in the comma-separated
147: list
148: .Ar uid .
1.1 millert 149: .It Fl u Ar euid
150: Restrict matches to processes with an effective user ID in the
151: comma-separated list
152: .Ar euid .
153: .It Fl v
154: Reverse the sense of the matching; display processes that do not match the
155: given criteria.
156: .It Fl x
157: Require an exact match of the process name, or argument list if
158: .Fl f
159: is given.
160: The default is to match any substring.
1.9 jmc 161: .It Fl Ar signal
1.1 millert 162: A non-negative decimal number or symbolic signal name specifying the signal
163: to be sent instead of the default TERM.
164: This option is valid only when given as the first argument to
165: .Nm pkill .
166: .El
167: .Pp
168: Note that a running
169: .Nm pgrep
170: or
171: .Nm pkill
1.7 jmc 172: process will never consider itself or system processes (kernel threads) as
1.1 millert 173: a potential match.
1.7 jmc 174: .Pp
1.1 millert 175: .Nm pgrep
176: and
177: .Nm pkill
178: return one of the following values upon exit:
1.7 jmc 179: .Pp
180: .Bl -tag -width Ds -offset indent -compact
1.1 millert 181: .It 0
182: One or more processes were matched.
183: .It 1
184: No processes were matched.
185: .It 2
186: Invalid options were specified on the command line.
187: .It 3
188: An internal error occurred.
189: .El
190: .Sh SEE ALSO
1.7 jmc 191: .Xr grep 1 ,
1.1 millert 192: .Xr kill 1 ,
193: .Xr ps 1 ,
194: .Xr kill 2 ,
195: .Xr sigaction 2 ,
1.2 millert 196: .Xr re_format 7
1.1 millert 197: .Sh HISTORY
198: .Nm pkill
199: and
200: .Nm pgrep
201: first appeared in
202: .Ox 3.5 .
203: They are modelled after utilities of the same name that appeared in Sun
204: Solaris 7.
205: .Sh AUTHORS
206: .An Andrew Doran
207: .Aq ad@NetBSD.org .