Reformatting page.  Please Wait... done


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  sys-
     tem  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 cri-
     teria 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


Illumos             Last change: May 6, 2004                    1


User Commands                                            PGREP(1)


     be specified as the first command line option to pkill.

OPTIONS
     The following options are supported:

     -c ctidlist
                      Matches only processes whose  process  con-
                      tract 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 exe-
                      cutable 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.


Illumos             Last change: May 6, 2004                    2


User Commands                                            PGREP(1)


     -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. Cannot 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  ses-
                      sion  ID  is in in the given list.  If ID 0
                      is included in the  list,  this  is  inter-
                      preted  as  the  session ID of the pgrep or
                      pkill process.


     -t termlist
                      Matches only processes which are associated
                      with  a  terminal  in the given list.  Each
                      terminal is specified as the suffix follow-
                      ing  "/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 interpreted as the task ID of
                      the pgrep or pkill process.


Illumos             Last change: May 6, 2004                    3


User Commands                                            PGREP(1)


     -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  processes  except those which meet the
                      specified matching criteria.


     -x
                      Considers  only  processes  whose  argument
                      string  or  executable  file  name  exactly
                      matches the specified pattern to be  match-
                      ing  processes.  The  pattern match is con-
                      sidered to be exact when all characters  in
                      the  process  argument string or executable
                      file name match the pattern.


     -z zoneidlist
                      Matches only processes whose zone ID is  in
                      the  given list. Each zone ID may be speci-
                      fied 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.


Illumos             Last change: May 6, 2004                    4


User Commands                                            PGREP(1)


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  complete 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.


Illumos             Last change: May 6, 2004                    5


User Commands                                            PGREP(1)


FILES
     /proc/nnnnn/psinfo
                           Process information files


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  <sys/procfs.h>.  Patterns  which  can match
     strings longer than the current 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 potential match.


Illumos             Last change: May 6, 2004                    6