prstat manpage

http://compute.cnr.berkeley.edu/cgi-bin/man-cgi?prstat+1

System Administration Commands                         prstat(1M)

NAME

     prstat - report active process statistics

SYNOPSIS

     prstat [-acHJLmRtTv] [-C psrsetlist] [-h lgrplist]
          [-j projlist] [-k tasklist] [-n ntop[,nbottom]]
          [-p pidlist] [-P cpulist] [-s key | -S key ]
          [-u euidlist] [-U uidlist] [-z zoneidlist] [-Z]
          [interval [count]]

DESCRIPTION

     The prstat utility iteratively examines all active processes
     on  the  system and reports statistics based on the selected
     output mode and sort order. prstat provides options to exam-
     ine  only processes matching specified PIDs, UIDs, zone IDs,
     CPU IDs, and processor set IDs.

     The -j, -k, -C, -p, -P, -u, -U, and -z options accept  lists
     as  arguments.  Items  in  a list can be either separated by
     commas or enclosed in quotes  and  separated  by  commas  or
     spaces.

     If you  do  not  specify  an  option,  prstat  examines  all
     processes and reports statistics sorted by CPU usage.

OPTIONS

     The following options are supported:

     -a

         Report information about processes and  users.  In  this
         mode  prstat  displays  separate reports about processes
         and users at the same time.

     -c

         Print new reports  below  previous  reports  instead  of
         overprinting them.

     -C psrsetlist

         Report only processes or lwps that are bound to  proces-
         sor  sets in the given list. Each processor set is iden-
         tified by an integer as reported by psrset(1M). The load
         averages  displayed  are the sum of the load averages of
         the specified processor sets (see  pset_getloadavg(3C)).
         Processes  with one or more LWPs bound to processor sets

SunOS 5.10          Last change: 27 Feb 2011                    1

System Administration Commands                         prstat(1M)

         in the given list are reported even when the  -L  option
         is not used.

     -h lgrplist

         Report only processes or lwps whose home  lgroup  is  in
         the  given list of lgroups. No processes or lwps will be
         listed for invalid lgroups.

     -H

         Report information about  home  lgroup.  In  this  mode,
         prstat adds an extra column showing process or lwps home
         lgroup with the header LGRP.

     -j projlist

         Report only processes or lwps whose project ID is in the
         given list. Each project ID can be specified as either a
         project name or a numerical project ID. See project(4).

     -J

         Report information about processes and projects. In this
         mode  prstat  displays  separate reports about processes
         and projects at the same time.

     -k tasklist

         Report only processes or lwps whose task ID is in  task-
         list.

     -L

         Report statistics for each light-weight  process  (LWP).
         By  default,  prstat reports only the number of LWPs for
         each process.

     -m

         Report microstate  process  accounting  information.  In
         addition to all fields listed in -v mode, this mode also
         includes the percentage of time the  process  has  spent
         processing  system  traps,  text  page faults, data page
         faults, waiting for  user  locks  and  waiting  for  CPU

SunOS 5.10          Last change: 27 Feb 2011                    2

System Administration Commands                         prstat(1M)

         (latency time).

     -n ntop[,nbottom]

         Restrict number  of  output  lines.  The  ntop  argument
         determines  how  many lines of process or lwp statistics
         are reported, and the nbottom  argument  determines  how
         many  lines  of  user,  task, or projects statistics are
         reported if the -a, -t, -T, -J, or -Z options are speci-
         fied.  By default, prstat displays as many lines of out-
         put that fit in a window or terminal. When  you  specify
         the  -c  option  or  direct  the  output  to a file, the
         default values for ntop and nbottom are 15 and 5.

     -p pidlist

         Report only processes whose process ID is in  the  given
         list.

     -P cpulist

         Report only processes or lwps which have  most  recently
         executed on a CPU in the given list. Each CPU is identi-
         fied by an integer as reported by psrinfo(1M).

     -R

         Put prstat in the real time scheduling class. When  this
         option  is  used,  prstat  is  given priority over time-
         sharing and interactive processes. This option is avail-
         able only for superuser.

     -s key

         Sort output lines (that is, processes, lwps,  or  users)
         by  key in descending order. Only one key can be used as
         an argument.

         There are five possible key values:

         cpu

             Sort by process CPU usage. This is the default.

         pri

SunOS 5.10          Last change: 27 Feb 2011                    3

System Administration Commands                         prstat(1M)

             Sort by process priority.

         rss

             Sort by resident set size.

         size

             Sort by size of process image.

         time

             Sort by process execution time.

     -S key

         Sort output lines by key in  ascending  order.  Possible
         key values are the same as for the -s option. See -s.

     -t

         Report total usage summary for each  user.  The  summary
         includes  the total number of processes or LWPs owned by
         the user, total size of process images,  total  resident
         set  size, total cpu time, and percentages of recent cpu
         time and system memory.

     -T

         Report information about processes and  tasks.  In  this
         mode  prstat  displays  separate reports about processes
         and tasks at the same time.

     -u euidlist

         Report 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

         Report only processes whose real user ID is in the given
         list.  Each  user  ID may be specified as either a login

SunOS 5.10          Last change: 27 Feb 2011                    4

System Administration Commands                         prstat(1M)

         name or a numerical user ID.

     -v

         Report  verbose  process  usage.  This   output   format
         includes the percentage of time the process has spent in
         user  mode,  in  system  mode,  and  sleeping.  It  also
         includes the number of voluntary and involuntary context
         switches,  system  calls  and  the  number  of   signals
         received.  Statistics  that  are not reported are marked
         with the - sign.

     -z zoneidlist

         Report only processes or LWPs whose zone ID  is  in  the
         given  list.  Each  zone ID can be specified as either a
         zone name or a numerical zone ID. See zones(5).

     -Z

         Report information about processes and  zones.  In  this
         mode,  prstat  displays separate reports about processes
         and zones at the same time.

OUTPUT

     The following list defines the column headings and the mean-
     ings of a prstat report:

     PID

         The process ID of the process.

     USERNAME

         The real user (login) name or real user ID.

     SWAP

         The sum of swap reservations of the associated processes
         for  each  user,  project,  task,  or  zone. This counts
         shared memory only once for each user, project, task, or
         zone.  Swap  is  reserved when anonymous memory is allo-
         cated or files are mapped private. The value of swap  is
         expressed  in kilobytes (K), megabytes (M), or gigabytes
         (G).

SunOS 5.10          Last change: 27 Feb 2011                    5

System Administration Commands                         prstat(1M)

     RSS

         The resident set size of the process (RSS), in kilobytes
         (K),  megabytes  (M), or gigabytes (G). The RSS value is
         an estimate provided by proc(4) that might underestimate
         the actual resident set size. Users who want to get more
         accurate usage information for capacity planning  should
         use the -x option to pmap(1) instead.

     STATE

         The state of the process:

         cpuN

             Process is running on CPU N.

         sleep

             Sleeping: process is waiting for an  event  to  com-
             plete.

         wait

             Waiting: process is waiting for CPU usage to drop to
             the CPU-caps enforced limits. See the description of
             CPU-caps in resource_controls(5).

         run

             Runnable: process in on run queue.

         zombie

             Zombie state:  process  terminated  and  parent  not
             waiting.

         stop

             Process is stopped.

     PRI

         The priority of the process. Larger numbers mean  higher

SunOS 5.10          Last change: 27 Feb 2011                    6

System Administration Commands                         prstat(1M)

         priority.

     NICE

         Nice value used in priority computation. Only  processes
         in certain scheduling classes have a nice value.

     TIME

         The cumulative execution time for the process.

     CPU

         The percentage of recent CPU time used by  the  process.
         If executing in a non-global zone and the pools facility
         is active, the percentage will be that of the processors
         in  the  processor  set  in use by the pool to which the
         zone is bound.

     PROCESS

         The name of the process (name of executed file).

     LWPID

         The lwp ID of the lwp being reported.

     NLWP

         The number of lwps in the process.

     With the some options, in addition to a number of the column
     headings shown above, there are:

     NPROC

         Number of processes in a specified collection.

     MEMORY

         Percentage of memory used by a specified  collection  of
         processes.

SunOS 5.10          Last change: 27 Feb 2011                    7

System Administration Commands                         prstat(1M)

     The following columns are displayed when the -v or -m option
     is specified

     USR

         The percentage of time the process  has  spent  in  user
         mode.

     SYS

         The percentage of time the process has spent  in  system
         mode.

     TRP

         The percentage of time the process has spent in process-
         ing system traps.

     TFL

         The percentage of time the process has spent  processing
         text page faults.

     DFL

         The percentage of time the process has spent  processing
         data page faults.

     LCK

         The percentage of time the process has spent waiting for
         user locks.

     SLP

         The percentage of time the process has spent sleeping.

     LAT

         The percentage of time the process has spent waiting for
         CPU.

     VCX

SunOS 5.10          Last change: 27 Feb 2011                    8

System Administration Commands                         prstat(1M)

         The number of voluntary context switches.

     ICX

         The number of involuntary context switches.

     SCL

         The number of system calls.

     SIG

         The number of signals received.

     Under the -L option, one line is printed for each lwp in the
     process  and  some  reporting fields show the values for the
     lwp, not the process.

     The following column is displayed  when  the  -H  option  is
     specified:

     LGRP

         The home lgroup of the process or lwp.

OPERANDS

     The following operands are supported:

     count

         Specifies the number of times that  the  statistics  are
         repeated.  By default, prstat reports statistics until a
         termination signal is received.

     interval

         Specifies the sampling interval in seconds; the  default
         interval is 5 seconds.

EXAMPLES

     Example  1  Reporting  the  Five  Most   Active   Super-User
     Processes

SunOS 5.10          Last change: 27 Feb 2011                    9

System Administration Commands                         prstat(1M)

     The following command reports the five  most  active  super-
     user processes running on CPU1 and CPU2:

       example% prstat -u root -n 5 -P 1,2 1 1

       PID   USERNAME  SWAP   RSS STATE  PRI  NICE      TIME  CPU PROCESS/LWP
        306   root     3024K 1448K sleep   58    0   0:00.00 0.3% sendmail/1
        102   root     1600K  592K sleep   59    0   0:00.00 0.1% in.rdisc/1
        250   root     1000K  552K sleep   58    0   0:00.00 0.0% utmpd/1
        288   root     1720K 1032K sleep   58    0   0:00.00 0.0% sac/1
          1   root      744K  168K sleep   58    0   0:00.00 0.0% init/1
       TOTAL:       25, load averages:  0.05, 0.08, 0.12

     Example 2 Displaying Verbose Process Usage Information

     The following command displays verbose process usage  infor-
     mation  about processes with lowest resident set sizes owned
     by users root and john.

       example% prstat -S rss -n 5 -vc -u root,john

        PID USERNAME USR SYS TRP TFL DFL LCK SLP LAT VCX ICX SCL SIG PROCESS/LWP
          1 root     0.0 0.0  -   -   -   -  100  -    0   0   0   0 init/1
        102 root     0.0 0.0  -   -   -   -  100  -    0   0   3   0 in.rdisc/1
        250 root     0.0 0.0  -   -   -   -  100  -    0   0   0   0 utmpd/1
       1185 john    0.0 0.0  -   -   -   -  100  -    0   0   0   0 csh/1
        240 root     0.0 0.0  -   -   -   -  100  -    0   0   0   0 powerd/4
        TOTAL:       71, load averages:  0.02, 0.04, 0.08

EXIT STATUS

     The following exit values are returned:

     0

         Successful completion.

     1

         An error occurred.

ATTRIBUTES

SunOS 5.10          Last change: 27 Feb 2011                   10

System Administration Commands                         prstat(1M)

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|

SEE ALSO

     proc(1),   ps(1),    psrinfo(1M),    psrset(1M),    sar(1M),
     pset_getloadavg(3C),   proc(4),  project(4),  attributes(5),
     resource_controls(5), zones(5)

NOTES

     The snapshot of system usage displayed  by  prstat  is  true
     only  for  a split-second, and it may not be accurate by the
     time it is displayed.  When  the  -m  option  is  specified,
     prstat  tries to turn on microstate accounting for each pro-
     cess; the original state is restored when prstat exits.  See
     proc(4)  for  additional  information  about  the microstate
     accounting facility.

     The total memory size reported in the SWAP and  RSS  columns
     for  groups  of  processes  can  sometimes  overestimate the
     actual amount of memory used by processes with shared memory
     segments.

SunOS 5.10          Last change: 27 Feb 2011                   11

No manual entry for 1.