unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

pgrep(1)                         User Commands                        pgrep(1)



NAME
       pgrep, pkill - find or signal processes by name and other attributes

SYNOPSIS
       pgrep   [-flvx]  [-n  |  -o]   [-d delim]  [-P ppidlist]  [-g pgrplist]
       [-s sidlist] [-u euidlist]  [-U uidlist]  [-G gidlist]  [-J projidlist]
       [-t termlist] [-T taskidlist] [-c ctidlist] [-z zoneidlist] [pattern]

       pkill   [-signal]   [-fvx]   [-n  |  -o]   [-P ppidlist]  [-g pgrplist]
       [-s sidlist] [-u euidlist]  [-U uidlist]  [-G gidlist]  [-J projidlist]
       [-t termlist] [-T taskidlist] [-c ctidlist] [-z zoneidlist] [pattern]

DESCRIPTION
       The  pgrep  utility  examines  the  active  processes on the system and
       reports the process IDs of the processes  whose  attributes  match  the
       criteria specified on the command line. Each process ID is printed as a
       decimal value and is separated from the next ID by a delimiter  string,
       which  defaults  to  a newline. For each attribute option, the user can
       specify a set of possible values separated by  commas  on  the  command
       line. For example,

       pgrep -G other,daemon

       matches  processes  whose real group ID is other OR daemon. If multiple
       criteria  options  are  specified,  pgrep   matches   processes   whose
       attributes match the logical AND of the criteria options. For example,

       pgrep -G other,daemon -U root,daemon

       matches processes whose attributes are:

                 (real group ID is other OR daemon) AND

                 (real user ID is root OR daemon)

       pkill functions identically to pgrep, except that each matching process
       is signaled as if by kill(1) instead of having its process ID  printed.
       A  signal  name  or  number  may be specified as the first command line
       option to pkill.

OPTIONS
       The following options are supported:

       -c ctidlist     Matches only processes whose process contract ID is  in
                       the given list.



       -d delim        Specifies  the  output  delimiter  string to be printed
                       between each matching process ID. If no  -d  option  is
                       specified,  the  default is a newline character. The -d
                       option is only valid when specified  as  an  option  to
                       pgrep.



       -f              The   regular  expression  pattern  should  be  matched
                       against the full process argument string (obtained from
                       the pr_psargs field of the /proc/nnnnn/psinfo file). If
                       no -f option is specified, the  expression  is  matched
                       only  against the name of the executable file (obtained
                       from  the  pr_fname  field  of  the  /proc/nnnnn/psinfo
                       file).



       -g pgrplist     Matches only processes whose process group ID is in the
                       given list. If group 0 is included in the list, this is
                       interpreted  as  the  process  group ID of the pgrep or
                       pkill process.



       -G gidlist      Matches only processes whose real group ID  is  in  the
                       given  list. Each group ID may be specified as either a
                       group name or a numerical group ID.



       -J projidlist   Matches only processes whose project ID is in the given
                       list.  Each  project  ID  may  be specified as either a
                       project name or a numerical project ID.



       -l              Long output format. Prints the process name along  with
                       the  process  ID  of each matching process. The process
                       name is obtained from the pr_psargs or pr_fname  field,
                       depending  on  whether the -f option was specified (see
                       above). The -l option is only valid when  specified  as
                       an option to pgrep.



       -n              Matches only the newest (most recently created) process
                       that meets all other specified matching criteria.  Can-
                       not be used with option -o.



       -o              Matches only the oldest (earliest created) process that
                       meets all other specified matching criteria. Cannot  be
                       used with option -n.



       -P ppidlist     Matches  only  processes  whose parent process ID is in
                       the given list.



       -s sidlist      Matches only processes whose process session ID  is  in
                       in  the  given  list.  If ID 0 is included in the list,
                       this is interpreted as the session ID of the  pgrep  or
                       pkill process.



       -t termlist     Matches only processes which are associated with a ter-
                       minal in the given list. Each terminal is specified  as
                       the  suffix  following "/dev/" of the terminal's device
                       path name in /dev.  For example, term/a or pts/0.



       -T taskidlist   Matches only processes whose task ID is  in  the  given
                       list.  If  ID 0 is included in the list, this is inter-
                       preted as the task ID of the pgrep or pkill process.



       -u euidlist     Matches only processes whose effective user  ID  is  in
                       the given list. Each user ID may be specified as either
                       a login name or a numerical user ID.



       -U uidlist      Matches only processes whose real user  ID  is  in  the
                       given  list.  Each user ID may be specified as either a
                       login name or a numerical user ID.



       -v              Reverses the sense of the matching.  Matches  all  pro-
                       cesses  except  those which meet the specified matching
                       criteria.



       -x              Considers only processes whose argument string or  exe-
                       cutable file name exactly matches the specified pattern
                       to be matching processes. The pattern match is  consid-
                       ered  to  be  exact  when all characters in the process
                       argument string or executable file name match the  pat-
                       tern.



       -z zoneidlist   Matches  only  processes  whose zone ID is in the given
                       list. Each zone ID may be specified as  either  a  zone
                       name or a numerical zone ID. This option is only useful
                       when executed in the global zone. If the pkill  utility
                       is  used  to send signals to processes in  other zones,
                       the process must  have  asserted  the  {PRIV_PROC_ZONE}
                       privilege (see privileges(5)).



       -signal         Specifies  the  signal to send to each matched process.
                       If no signal is specified, SIGTERM is sent by  default.
                       The  value  of  signal can be one of the symbolic names
                       defined in signal.h(3HEAD) without the SIG  prefix,  or
                       the corresponding signal number as a decimal value. The
                       -signal option is only  valid  when  specified  as  the
                       first option to pkill.



OPERANDS
       The following operand is supported:

       pattern         Specifies  an Extended Regular Expression (ERE) pattern
                       to match against either the  executable  file  name  or
                       full  process  argument string. See regex(5) for a com-
                       plete description of the ERE syntax.



EXAMPLES
       Example 1: Obtaining a Process ID

       Obtain the process ID of sendmail:

       example% pgrep -x -u root sendmail
       283

       Example 2: Terminating a Process

       Terminate the most recently created xterm:

       example% pkill -n xterm

EXIT STATUS
       The following exit values are returned:

       0        One or more processes were matched.



       1        No processes were matched.



       2        Invalid command line options were specified.



       3        A fatal error occurred.



FILES
       /proc/nnnnn/psinfo      Process information files



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE AvailabilitySUNWcsu


SEE ALSO
       kill(1),  proc(1),  ps(1), truss(1), kill(2), signal.h(3HEAD), proc(4),
       attributes(5), privileges(5), regex(5), zones(5)

NOTES
       Both utilities match  the  ERE  pattern  argument  against  either  the
       pr_fname  or  pr_psargs  fields  of  the  /proc/nnnnn/psinfo files. The
       lengths of these  strings  are  limited  according  to  definitions  in
       <&lt;sys/procfs.h>&gt;.  Patterns  which can match strings longer than the cur-
       rent limits may fail to match the intended set of processes.

       If the pattern argument contains ERE  meta-characters  which  are  also
       shell  meta-characters, it may be necessary to enclose the pattern with
       appropriate shell quotes.

       Defunct processes are never matched by either pgrep or pkill.

       The current pgrep or pkill process will never consider itself a  poten-
       tial match.



SunOS 5.10                        6 May 2004                          pgrep(1)