pgrep.1

   1 .\" Manual page for pgrep / pkill.
   2 .\" Licensed under version 2 of the GNU General Public License.
   3 .\" Copyright 2000 Kjetil Torgrim Homme
   4 .\"
   5 .TH PGREP 1 "June 25, 2000" "Linux" "Linux User's Manual"
   6 .SH NAME
   7 pgrep, pkill \- look up or signal processes based on name and other attributes
   8
   9 .SH SYNOPSIS
  10 pgrep [\-flvx] [\-d \fIdelimiter\fP] [\-n|\-o] [\-P \fIppid\fP,...] [\-g \fIpgrp\fP,...]
  11 .br
  12         [\-s \fIsid\fP,...] [\-u \fIeuid\fP,...] [\-U \fIuid\fP,...] [\-G \fIgid\fP,...]
  13 .br
  14         [\-t \fIterm\fP,...] [\fIpattern\fP]
  15
  16 pkill [\-\fIsignal\fP] [\-fvx] [\-n|\-o] [\-P \fIppid\fP,...] [\-g \fIpgrp\fP,...]
  17 .br
  18         [\-s \fIsid\fP,...] [\-u \fIeuid\fP,...] [\-U \fIuid\fP,...] [\-G \fIgid\fP,...]
  19 .br
  20         [\-t \fIterm\fP,...] [\fIpattern\fP]
  21
  22 .SH DESCRIPTION
  23 \fBpgrep\fP looks through the currently running processes and lists the
  24 process IDs which matches the selection criteria to stdout.  All
  25 the criteria have to match.  For example,
  26
  27 pgrep -u root sshd
  28
  29 will only list the processes called \fBsshd\fP AND owned by \fBroot\fP.
  30 On the other hand,
  31
  32 pgrep -u root,daemon
  33
  34 will list the processes owned by \fBroot\fP OR \fBdaemon\fP.
  35
  36 \fBpkill\fP will send the specified signal (by default \fBSIGTERM\fP)
  37 to each process instead of listing them on stdout.
  38
  39 .SH OPTIONS
  40 .TP
  41 \-d \fIdelimiter\fP
  42 Sets the string used to delimit each process ID in the output (by
  43 default a newline).  (\fBpgrep\fP only.)
  44 .TP
  45 \-f
  46 The \fIpattern\fP is normally only matched against the process name.
  47 When \-f is set, the full command line is used.
  48 .TP
  49 \-g \fIpgrp\fP,...
  50 Only match processes in the process group IDs listed.  Process group 0
  51 is translated into \fBpgrep\fP's or \fBpkill\fP's own process group.
  52 .TP
  53 \-G \fIgid\fP,...
  54 Only match processes whose real group ID is listed.  Either the
  55 numerical or symbolical value may be used.
  56 .TP
  57 \-l
  58 List the process name as well as the process ID. (\fBpgrep\fP only.)
  59 .TP
  60 \-n
  61 Select only the newest (most recently started) of the matching
  62 processes.
  63 .TP
  64 \-o
  65 Select only the oldest (least recently started) of the matching
  66 processes.
  67 .TP
  68 \-P \fIppid\fP,...
  69 Only match processes whose parent process ID is listed.
  70 .TP
  71 \-s \fIsid\fP,...
  72 Only match processes whose process session ID is listed.  Session ID 0
  73 is translated into \fBpgrep\fP's or \fBpkill\fP's own session ID.
  74 .TP
  75 \-t \fIterm\fP,...
  76 Only match processes whose controlling terminal is listed.  The
  77 terminal name should be specified without the "/dev/" prefix.
  78 .TP
  79 \-u \fIeuid\fP,...
  80 Only match processes whose effective user ID is listed.  Either the
  81 numerical or symbolical value may be used.
  82 .TP
  83 \-U \fIuid\fP,...
  84 Only match processes whose real user ID is listed.  Either the
  85 numerical or symbolical value may be used.
  86 .TP
  87 \-v
  88 Negates the matching.
  89 .TP
  90 \-x
  91 Only match processes whose name (or command line if \-f is specified)
  92 \fBexactly\fP match the \fIpattern\fP.
  93 .TP
  94 \-\fIsignal\fP
  95 Defines the signal to send to each matched process.  Either the
  96 numeric or the symbolic signal name can be used.  (\fBpkill\fP only.)
  97
  98 .SH OPERANDS
  99 .TP
 100 \fIpattern\fP
 101 Specifies an Extended Regular Expression for matching against the
 102 process names or command lines.
 103
 104 .SH EXAMPLES
 105 Example 1: Find the process ID of the \fBnamed\fP daemon:
 106
 107 unix$ pgrep \-u root named
 108
 109 Example 2: Make \fBsyslog\fP reread its configuration file:
 110
 111 unix$ pkill \-HUP syslogd
 112
 113 Example 3: Give detailed information on all \fBxterm\fP processes:
 114
 115 unix$ ps \-fp $(pgrep \-d, \-x xterm)
 116
 117 Example 4: Make all \fBnetscape\fP processes run nicer:
 118
 119 unix$ renice +4 `pgrep netscape`
 120
 121 .SH "EXIT STATUS"
 122 .TP
 123 .I "0"
 124 One or more processes matched the criteria.
 125 .TP
 126 .I "1"
 127 No processes matched.
 128 .TP
 129 .I "2"
 130 Syntax error in the command line.
 131 .TP
 132 .I "3"
 133 Fatal error: out of memory etc.
 134
 135 .SH NOTES
 136 The process name used for matching is limited to the 15 characters
 137 present in the output of /proc/\fIpid\fP/stat.  Use the \-f option to
 138 match against the complete command line, /proc/\fIpid\fP/cmdline.
 139
 140 The running \fBpgrep\fP or \fBpkill\fP process will never report
 141 itself as a match.
 142
 143 .SH BUGS
 144 The options \-n and \-o and \-v can not be combined.  Let me know if
 145 you need to do this.
 146
 147 Defunct processes are reported.
 148
 149 .SH "SEE ALSO"
 150 ps(1) regex(7) signal(7) killall(1) skill(1) kill(1) kill(2)
 151
 152 .SH STANDARDS
 153 \fBpkill\fP and \fBpgrep\fP were introduced in Sun's Solaris 7.  This
 154 implementation is fully compatible.
 155
 156 .SH AUTHOR
 157 Kjetil Torgrim Homme <kjetilho@ifi.uio.no>
 158
 159 Albert Cahalan <albert@users.sf.net> is the current maintainer of
 160 the procps package.
 161
 162 Please send bug reports to <procps-feedback@lists.sf.net>