1 '\" te
   2 .\"  Copyright (c) 2004, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH PGREP 1 "May 6, 2004"
   7 .SH NAME
   8 pgrep, pkill \- find or signal processes by name and other attributes
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBpgrep\fR [\fB-flvx\fR] [\fB-n\fR | \fB-o\fR] [\fB-d\fR \fIdelim\fR] [\fB-P\fR \fIppidlist\fR]
  13      [\fB-g\fR \fIpgrplist\fR] [\fB-s\fR \fIsidlist\fR] [\fB-u\fR \fIeuidlist\fR] [\fB-U\fR \fIuidlist\fR]
  14      [\fB-G\fR \fIgidlist\fR] [\fB-J\fR \fIprojidlist\fR] [\fB-t\fR \fItermlist\fR]
  15      [\fB-T\fR \fItaskidlist\fR] [\fB-c\fR \fIctidlist\fR] [\fB-z\fR \fIzoneidlist\fR]
  16      [\fIpattern\fR]
  17 .fi
  18 
  19 .LP
  20 .nf
  21 \fBpkill\fR [\fB-\fIsignal\fR\fR] [\fB-fvx\fR] [\fB-n\fR | \fB-o\fR] [\fB-P\fR \fIppidlist\fR]
  22      [\fB-g\fR \fIpgrplist\fR] [\fB-s\fR \fIsidlist\fR] [\fB-u\fR \fIeuidlist\fR] [\fB-U\fR \fIuidlist\fR]
  23      [\fB-G\fR \fIgidlist\fR] [\fB-J\fR \fIprojidlist\fR] [\fB-t\fR \fItermlist\fR]
  24      [\fB-T\fR \fItaskidlist\fR] [\fB-c\fR \fIctidlist\fR] [\fB-z\fR \fIzoneidlist\fR]
  25      [\fIpattern\fR]
  26 .fi
  27 
  28 .SH DESCRIPTION
  29 .sp
  30 .LP
  31 The \fBpgrep\fR utility examines the active processes on the system and reports
  32 the process \fBID\fRs of the processes whose attributes match the criteria
  33 specified on the command line. Each process \fBID\fR is printed as a decimal
  34 value and is separated from the next \fBID\fR by a delimiter string, which
  35 defaults to a newline. For each attribute option, the user can specify a set of
  36 possible values separated by commas on the command line. For example,
  37 .sp
  38 .in +2
  39 .nf
  40 \fBpgrep -G other,daemon\fR
  41 .fi
  42 .in -2
  43 .sp
  44 
  45 .sp
  46 .LP
  47 matches processes whose real group \fBID\fR is \fBother\fR \fBOR\fR
  48 \fBdaemon\fR. If multiple criteria options are specified, \fBpgrep\fR matches
  49 processes whose attributes match the logical \fBAND\fR of the criteria options.
  50 For example,
  51 .sp
  52 .in +2
  53 .nf
  54 \fBpgrep -G other,daemon -U root,daemon\fR
  55 .fi
  56 .in -2
  57 .sp
  58 
  59 .sp
  60 .LP
  61 matches processes whose attributes are:
  62 .br
  63 .in +2
  64 (real group \fBID\fR is \fBother\fR \fBOR\fR \fBdaemon\fR) \fBAND\fR
  65 .in -2
  66 .br
  67 .in +2
  68 (real user \fBID\fR is \fBroot\fR \fBOR\fR \fBdaemon\fR)
  69 .in -2
  70 .sp
  71 .LP
  72 \fBpkill\fR functions identically to \fBpgrep\fR, except that each matching
  73 process is signaled as if by \fBkill\fR(1) instead of having its process
  74 \fBID\fR printed. A signal name or number may be specified as the first command
  75 line option to \fBpkill\fR.
  76 .SH OPTIONS
  77 .sp
  78 .LP
  79 The following options are supported:
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fB-c\fR \fIctidlist\fR\fR
  84 .ad
  85 .RS 17n
  86 Matches only processes whose process contract ID is in the given list.
  87 .RE
  88 
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fB-d\fR \fIdelim\fR\fR
  93 .ad
  94 .RS 17n
  95 Specifies the output delimiter string to be printed between each matching
  96 process \fBID\fR. If no \fB-d\fR option is specified, the default is a newline
  97 character. The \fB-d\fR option is only valid when specified as an option to
  98 \fBpgrep\fR.
  99 .RE
 100 
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fB-f\fR\fR
 105 .ad
 106 .RS 17n
 107 The regular expression \fIpattern\fR should be matched against the full process
 108 argument string (obtained from the \fBpr_psargs\fR field of the
 109 \fB/proc/\fInnnnn\fR/psinfo\fR file). If no \fB-f\fR option is specified, the
 110 expression is matched only against the name of the executable file (obtained
 111 from the \fBpr_fname\fR field of the \fB/proc/\fInnnnn\fR/psinfo\fR file).
 112 .RE
 113 
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fB-g\fR \fIpgrplist\fR\fR
 118 .ad
 119 .RS 17n
 120 Matches only processes whose process group \fBID\fR is in the given list. If
 121 group 0 is included in the list, this is interpreted as the process group
 122 \fBID\fR of the \fBpgrep\fR or \fBpkill\fR process.
 123 .RE
 124 
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fB-G\fR \fIgidlist\fR\fR
 129 .ad
 130 .RS 17n
 131 Matches only processes whose real group \fBID\fR is in the given list. Each
 132 group \fBID\fR may be specified as either a group name or a numerical group
 133 \fBID\fR.
 134 .RE
 135 
 136 .sp
 137 .ne 2
 138 .na
 139 \fB\fB-J\fR \fIprojidlist\fR\fR
 140 .ad
 141 .RS 17n
 142 Matches only processes whose project \fBID\fR is in the given list. Each
 143 project \fBID\fR may be specified as either a project name or a numerical
 144 project \fBID\fR.
 145 .RE
 146 
 147 .sp
 148 .ne 2
 149 .na
 150 \fB\fB-l\fR\fR
 151 .ad
 152 .RS 17n
 153 Long output format. Prints the process name along with the process \fBID\fR of
 154 each matching process. The process name is obtained from the \fBpr_psargs\fR or
 155 \fBpr_fname\fR field, depending on whether the \fB-f\fR option was specified
 156 (see above). The \fB-l\fR option is only valid when specified as an option to
 157 \fBpgrep\fR.
 158 .RE
 159 
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fB-n\fR\fR
 164 .ad
 165 .RS 17n
 166 Matches only the newest (most recently created) process that meets all other
 167 specified matching criteria. Cannot be used with option \fB-o\fR.
 168 .RE
 169 
 170 .sp
 171 .ne 2
 172 .na
 173 \fB\fB-o\fR\fR
 174 .ad
 175 .RS 17n
 176 Matches only the oldest (earliest created) process that meets all other
 177 specified matching criteria. Cannot be used with option \fB-n\fR.
 178 .RE
 179 
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fB-P\fR \fIppidlist\fR\fR
 184 .ad
 185 .RS 17n
 186 Matches only processes whose parent process \fBID\fR is in the given list.
 187 .RE
 188 
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fB-s\fR \fIsidlist\fR\fR
 193 .ad
 194 .RS 17n
 195 Matches only processes whose process session \fBID\fR is in in the given list.
 196 If \fBID\fR 0 is included in the list, this is interpreted as the session
 197 \fBID\fR of the \fBpgrep\fR or \fBpkill\fR process.
 198 .RE
 199 
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fB-t\fR \fItermlist\fR\fR
 204 .ad
 205 .RS 17n
 206 Matches only processes which are associated with a terminal in the given list.
 207 Each terminal is specified as the suffix following "/dev/" of the terminal's
 208 device path name in \fB/dev\fR. For example, \fBterm/a\fR or \fBpts/0\fR.
 209 .RE
 210 
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fB-T\fR \fItaskidlist\fR\fR
 215 .ad
 216 .RS 17n
 217 Matches only processes whose task \fBID\fR is in the given list. If \fBID\fR 0
 218 is included in the list, this is interpreted as the task \fBID\fR of the
 219 \fBpgrep\fR or \fBpkill\fR process.
 220 .RE
 221 
 222 .sp
 223 .ne 2
 224 .na
 225 \fB\fB-u\fR \fIeuidlist\fR\fR
 226 .ad
 227 .RS 17n
 228 Matches only processes whose effective user \fBID\fR is in the given list. Each
 229 user \fBID\fR may be specified as either a login name or a numerical user
 230 \fBID\fR.
 231 .RE
 232 
 233 .sp
 234 .ne 2
 235 .na
 236 \fB\fB-U\fR \fIuidlist\fR\fR
 237 .ad
 238 .RS 17n
 239 Matches only processes whose real user \fBID\fR is in the given list. Each user
 240 \fBID\fR may be specified as either a login name or a numerical user \fBID\fR.
 241 .RE
 242 
 243 .sp
 244 .ne 2
 245 .na
 246 \fB\fB-v\fR\fR
 247 .ad
 248 .RS 17n
 249 Reverses the sense of the matching. Matches all processes \fBexcept\fR those
 250 which meet the specified matching criteria.
 251 .RE
 252 
 253 .sp
 254 .ne 2
 255 .na
 256 \fB\fB-x\fR\fR
 257 .ad
 258 .RS 17n
 259 Considers only processes whose argument string or executable file name
 260 \fBexactly\fR matches the specified \fIpattern\fR to be matching processes. The
 261 pattern match is considered to be exact when all characters in the process
 262 argument string or executable file name match the pattern.
 263 .RE
 264 
 265 .sp
 266 .ne 2
 267 .na
 268 \fB\fB-z\fR \fIzoneidlist\fR\fR
 269 .ad
 270 .RS 17n
 271 Matches only processes whose zone \fBID\fR is in the given list. Each zone
 272 \fBID\fR may be specified as either a zone name or a numerical zone \fBID\fR.
 273 This option is only useful when executed in the global zone. If the \fBpkill\fR
 274 utility is used to send signals to processes in  other zones, the process must
 275 have asserted the \fB{PRIV_PROC_ZONE}\fR privilege (see \fBprivileges\fR(5)).
 276 .RE
 277 
 278 .sp
 279 .ne 2
 280 .na
 281 \fB\fB-\fR\fIsignal\fR\fR
 282 .ad
 283 .RS 17n
 284 Specifies the signal to send to each matched process. If no signal is
 285 specified, \fBSIGTERM\fR is sent by default. The value of \fIsignal\fR can be
 286 one of the symbolic names defined in \fBsignal.h\fR(3HEAD) without the
 287 \fBSIG\fR prefix, or the corresponding signal number as a decimal value. The
 288 \fB-\fR\fIsignal\fR option is only valid when specified as the first option to
 289 \fBpkill\fR.
 290 .RE
 291 
 292 .SH OPERANDS
 293 .sp
 294 .LP
 295 The following operand is supported:
 296 .sp
 297 .ne 2
 298 .na
 299 \fB\fIpattern\fR\fR
 300 .ad
 301 .RS 11n
 302 Specifies an Extended Regular Expression (\fBERE\fR) pattern to match against
 303 either the executable file name or full process argument string. See
 304 \fBregex\fR(5) for a complete description of the \fBERE\fR syntax.
 305 .RE
 306 
 307 .SH EXAMPLES
 308 .LP
 309 \fBExample 1 \fRObtaining a Process ID
 310 .sp
 311 .LP
 312 Obtain the process \fBID\fR of \fBsendmail\fR:
 313 
 314 .sp
 315 .in +2
 316 .nf
 317 example% \fBpgrep -x -u root sendmail\fR
 318 283
 319 .fi
 320 .in -2
 321 .sp
 322 
 323 .LP
 324 \fBExample 2 \fRTerminating a Process
 325 .sp
 326 .LP
 327 Terminate the most recently created \fBxterm\fR:
 328 
 329 .sp
 330 .in +2
 331 .nf
 332 example% \fBpkill -n xterm\fR
 333 .fi
 334 .in -2
 335 .sp
 336 
 337 .SH EXIT STATUS
 338 .sp
 339 .LP
 340 The following exit values are returned:
 341 .sp
 342 .ne 2
 343 .na
 344 \fB\fB0\fR\fR
 345 .ad
 346 .RS 5n
 347 One or more processes were matched.
 348 .RE
 349 
 350 .sp
 351 .ne 2
 352 .na
 353 \fB\fB1\fR\fR
 354 .ad
 355 .RS 5n
 356 No processes were matched.
 357 .RE
 358 
 359 .sp
 360 .ne 2
 361 .na
 362 \fB\fB2\fR\fR
 363 .ad
 364 .RS 5n
 365 Invalid command line options were specified.
 366 .RE
 367 
 368 .sp
 369 .ne 2
 370 .na
 371 \fB\fB3\fR\fR
 372 .ad
 373 .RS 5n
 374 A fatal error occurred.
 375 .RE
 376 
 377 .SH FILES
 378 .sp
 379 .ne 2
 380 .na
 381 \fB\fB/proc/\fInnnnn\fR/psinfo\fR\fR
 382 .ad
 383 .RS 22n
 384 Process information files
 385 .RE
 386 
 387 .SH SEE ALSO
 388 .sp
 389 .LP
 390 \fBkill\fR(1), \fBproc\fR(1), \fBps\fR(1), \fBtruss\fR(1), \fBkill\fR(2),
 391 \fBsignal.h\fR(3HEAD), \fBproc\fR(4), \fBattributes\fR(5), \fBprivileges\fR(5),
 392 \fBregex\fR(5), \fBzones\fR(5)
 393 .SH NOTES
 394 .sp
 395 .LP
 396 Both utilities match the \fBERE\fR \fIpattern\fR argument against either the
 397 \fBpr_fname\fR or \fBpr_psargs\fR fields of the
 398 \fB/proc/\fR\fInnnnn\fR\fB/psinfo\fR files. The lengths of these strings are
 399 limited according to definitions in \fB<sys/procfs.h>\fR\&. Patterns which can
 400 match strings longer than the current limits may fail to match the intended set
 401 of processes.
 402 .sp
 403 .LP
 404 If the \fIpattern\fR argument contains \fBERE\fR meta-characters which are also
 405 shell meta-characters, it may be necessary to enclose the pattern with
 406 appropriate shell quotes.
 407 .sp
 408 .LP
 409 Defunct processes are never matched by either \fBpgrep\fR or \fBpkill\fR.
 410 .sp
 411 .LP
 412 The current \fBpgrep\fR or \fBpkill\fR process will never consider itself a
 413 potential match.