prstat(1M) (man pages section 1M: System Administration Commands)

man pages section 1M: System Administration Commands

prstat(1M)

NAME

prstat- report active process statistics

SYNOPSIS

prstat

-acLmRtv

-C

psrsetlist

-n

nprocs

nusers

-p

pidlist

-P

cpulist

-s

key

-S

key

-u

euidlist

-U

uidlist

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 examine only processes matching specified PIDs, UIDs, CPU IDs, and processor set IDs.

The -C, -p, -P, -u, and -U 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 processor sets in the given list. Each processor set is identified by an integer as reported by psrset(1M).

-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 (latency time).

-n nproc[,nusers]

Restrict number of output lines. The nproc argument determines how many lines of process or lwp statistics are reported, and the nusers argument determines how many lines of user statistics are reported if the -a or -t options are specified. By default, prstat can display as many lines of output as will fit within a window or terminal.

-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 identified 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 available 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.
time: Sort by process execution time.
size: Sort by size of process image.
rss: Sort by resident set size.
pri: Sort by process priority.

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

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

OUTPUT

The following list defines the column headings and the meanings of a prstat report:

PID

The process ID of the process.

USERNAME

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

SIZE

The total virtual memory size of the process, including all mapped files and devices, in kilobytes (K), megabytes (M), or gigabytes (G). The resident set size of the process (RSS), in kilobytes (K), megabytes (M), or gigabytes (G).

STATE

The state of the process:

cpuN: Process is running on CPU N.
sleep: Sleeping: process is witing for an event to complete.
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 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.

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.

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 processing 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 in
VCX: 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.

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

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  SIZE   RSS STATE  PRI NICE      TIME  CPU PROCESS/LWP
   42    root     1280K  856K sleep   55    0   0:00.00 0.2% devfseventd/7
   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 information 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

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsu

NOTES

The snap-shot 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 process; the original state is restored when prstat exits. See proc(4) for additional information about the microstate accounting facility.

SunOS 5.8 Last Revised 28 May 1999