1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292
|
.\"
.\" Copyright 2000 Kjetil Torgrim Homme
.\" 2017-2020 Craig Small
.\"
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\"
.TH PGREP "1" "2020-06-04" "procps-ng" "User Commands"
.SH NAME
pgrep, pkill, pidwait \- look up, signal, or wait for processes based on name and other attributes
.SH SYNOPSIS
.B pgrep
[options] pattern
.br
.B pkill
[options] pattern
.br
.B pidwait
[options] pattern
.SH DESCRIPTION
.B pgrep
looks through the currently running processes and lists the process IDs which
match the selection criteria to stdout. All the criteria have to match.
For example,
.IP
$ pgrep \-u root sshd
.PP
will only list the processes called
.B sshd
AND owned by
.BR root .
On the other hand,
.IP
$ pgrep \-u root,daemon
.PP
will list the processes owned by
.B root
OR
.BR daemon .
.PP
.B pkill
will send the specified signal (by default
.BR SIGTERM )
to each process instead of listing them on stdout.
.PP
.B pidwait
will wait for each process instead of listing them on stdout.
.SH OPTIONS
.TP
\fB\-\fR\fIsignal\fP
.TQ
\fB\-\-signal\fR \fIsignal\fR
Defines the signal to send to each matched process. Either the numeric or
the symbolic signal name can be used.
.RB ( pkill
only.)
.TP
\fB\-c\fR, \fB\-\-count\fR
Suppress normal output; instead print a count of matching processes. When
count does not match anything, e.g. returns zero, the command will return
non-zero value. Note that for pkill and pidwait, the count is the number of
matching processes, not the processes that were successfully signaled or waited
for.
.TP
\fB\-d\fR, \fB\-\-delimiter\fR \fIdelimiter\fP
Sets the string used to delimit each process ID in the output (by default a
newline).
.RB ( pgrep
only.)
.TP
\fB\-e\fR, \fB\-\-echo\fR
Display name and PID of the process being killed.
.RB ( pkill
only.)
.TP
\fB\-f\fR, \fB\-\-full\fR
The
.I pattern
is normally only matched against the process name. When
.B \-f
is set, the full command line is used.
.TP
\fB\-g\fR, \fB\-\-pgroup\fR \fIpgrp\fP,...
Only match processes in the process group IDs listed. Process group 0 is
translated into
.BR pgrep 's,
.BR pkill 's,
or
.BR pidwait 's
own process group.
.TP
\fB\-G\fR, \fB\-\-group\fR \fIgid\fP,...
Only match processes whose real group ID is listed. Either the numerical or
symbolical value may be used.
.TP
\fB\-i\fR, \fB\-\-ignore\-case\fR
Match processes case-insensitively.
.TP
\fB\-l\fR, \fB\-\-list\-name\fR
List the process name as well as the process ID.
.RB ( pgrep
only.)
.TP
\fB\-a\fR, \fB\-\-list\-full\fR
List the full command line as well as the process ID.
.RB ( pgrep
only.)
.TP
\fB\-n\fR, \fB\-\-newest\fR
Select only the newest (most recently started) of the matching processes.
.TP
\fB\-o\fR, \fB\-\-oldest\fR
Select only the oldest (least recently started) of the matching processes.
.TP
\fB\-O\fR, \fB\-\-older\fR \fIsecs\fP
Select processes older than secs.
.TP
\fB\-P\fR, \fB\-\-parent\fR \fIppid\fP,...
Only match processes whose parent process ID is listed.
.TP
\fB\-s\fR, \fB\-\-session\fR \fIsid\fP,...
Only match processes whose process session ID is listed. Session ID 0
is translated into
.BR pgrep 's,
.BR pkill 's,
or
.BR pidwait 's
own session ID.
.TP
\fB\-t\fR, \fB\-\-terminal\fR \fIterm\fP,...
Only match processes whose controlling terminal is listed. The terminal name
should be specified without the "/dev/" prefix.
.TP
\fB\-u\fR, \fB\-\-euid\fR \fIeuid\fP,...
Only match processes whose effective user ID is listed. Either the numerical
or symbolical value may be used.
.TP
\fB\-U\fR, \fB\-\-uid\fR \fIuid\fP,...
Only match processes whose real user ID is listed. Either the numerical or
symbolical value may be used.
.TP
\fB\-v\fR, \fB\-\-inverse\fR\fR
Negates the matching. This option is usually used in
.BR pgrep 's
or
.BR pidwait 's
context. In
.BR pkill 's
context the short option is disabled to avoid accidental usage of the option.
.TP
\fB\-w\fR, \fB\-\-lightweight\fR\fR
Shows all thread ids instead of pids in
.BR pgrep 's
or
.BR pidwait 's
context. In
.BR pkill 's
context this option is disabled.
.TP
\fB\-x\fR, \fB\-\-exact\fR\fR
Only match processes whose names (or command lines if \fB\-f\fR is specified)
.B exactly
match the
.IR pattern .
.TP
\fB\-F\fR, \fB\-\-pidfile\fR \fIfile\fR
Read \fIPID\fRs from \fIfile\fR. This option is more useful for
.BR pkill or pidwait
than
.BR pgrep .
.TP
\fB\-L\fR, \fB\-\-logpidfile\fR
Fail if pidfile (see \fB\-F\fR) not locked.
.TP
\fB\-r\fR, \fB\-\-runstates\fR \fID,R,S,Z,\fP...
Match only processes which match the process state.
.TP
\fB\-\-ns \fIpid\fP
Match processes that belong to the same namespaces. Required to run as
root to match processes from other users. See \fB\-\-nslist\fR for how to
limit which namespaces to match.
.TP
\fB\-\-nslist \fIname\fP,...
Match only the provided namespaces. Available namespaces:
ipc, mnt, net, pid, user,uts.
.TP
\fB\-q\fR, \fB\-\-queue \fIvalue\fP
Use
.BR sigqueue(3)
rather than
.BR kill(2)
and the value argument is used to specify
an integer to be sent with the signal. If the receiving process has
installed a handler for this signal using the SA_SIGINFO flag to
.BR sigaction(2)
, then it can obtain this data via the si_value field of the
siginfo_t structure.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version information and exit.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display help and exit.
.PD
.SH OPERANDS
.TP
.I pattern
Specifies an Extended Regular Expression for matching against the process
names or command lines.
.SH EXAMPLES
Example 1: Find the process ID of the
.B named
daemon:
.IP
$ pgrep \-u root named
.PP
Example 2: Make
.B syslog
reread its configuration file:
.IP
$ pkill \-HUP syslogd
.PP
Example 3: Give detailed information on all
.B xterm
processes:
.IP
$ ps \-fp $(pgrep \-d, \-x xterm)
.PP
Example 4: Make all
.B chrome
processes run nicer:
.IP
$ renice +4 $(pgrep chrome)
.SH "EXIT STATUS"
.PD 0
.TP
0
One or more processes matched the criteria. For pkill and pidwait, one or more
processes must also have been successfully signalled or waited for.
.TP
1
No processes matched or none of them could be signalled.
.TP
2
Syntax error in the command line.
.TP
3
Fatal error: out of memory etc.
.PD
.SH NOTES
The process name used for matching is limited to the 15 characters present in
the output of /proc/\fIpid\fP/stat. Use the \fB\-f\fR option to match against the
complete command line, /proc/\fIpid\fP/cmdline.
.PP
The running
.BR pgrep ,
.BR pkill ,
or
.B pidwait
process will never report itself as a
match.
.SH BUGS
The options
.B \-n
and
.B \-o
and
.B \-v
can not be combined. Let
me know if you need to do this.
.PP
Defunct processes are reported.
.SH "SEE ALSO"
.BR ps (1),
.BR regex (7),
.BR signal (7),
.BR sigqueue (3),
.BR killall (1),
.BR skill (1),
.BR kill (1),
.BR kill (2)
.SH AUTHOR
.UR kjetilho@ifi.uio.no
Kjetil Torgrim Homme
.UE
.SH "REPORTING BUGS"
Please send bug reports to
.UR procps@freelists.org
.UE
|