Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

prstat(8)

Name

prstat - report active process statistics

Synopsis

prstat [-acDHJLmNRrtTvx] [-d u | d] [-C psrsetlist] [-h lgrplist]
     [-j projlist] [-k tasklist] [-n ntop[,nbottom]] [-p pidlist]
     [-P cpulist] [-s key | -S key ] [--scale[=item1,item2,...]]
     [-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 examine 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.

The options -J, -T and -Z are mutually exclusive. The -H and -m options are mutually exclusive. The -L and -D options are mutually exclusive.

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. The -a option cannot be used with -t, -J, -T or -Z.

–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(8). 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 in the given list are reported even when the –L option is not used.

–D

Print command and arguments as modified by processes instead of executable file name. Command and arguments are limited to 80 characters, less may be displayed if terminal window is not wide enough. Instead of appending NLWPS to the end of the arguments, this information appears in its own field just ahead of the command and arguments.

–d u | d

Specify u for a printed representation of the internal representation of time. See time(2). Specify d for standard date format. See date(1).

–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(5).

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

–L

Display output for each light-weight process (LWP) on a separate line. Includes LWP name (if set) and LWPID in output. By default, prstat reports only the number of LWPs for each process. This argument will cause output to wrap when displaying long LWP names on narrow terminals.

–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

Show values with better precision by increasing the number of characters for applicable columns. Columns reporting microstate data, CPU, and MEMORY will be increased from 3 to 5 characters to keep rounding error less than 1%. SIZE, RSS, and SWAP columns will be increased from 5 to 8 characters in order to show data with a unit prefix of finer granularity. This option will cause output to wrap if terminal width is insufficient.

The –N option is equivalent to using the –scale=minwide option.

Note that if the terminal is wide enough, this better precision is used by default, but it will not cause the lines to wrap.

–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 specified. By default, prstat displays as many lines of output 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 identified by an integer as reported by psrinfo(8).

–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 requires the {PRIV_PROC_PRIOCNTL} privilege.

–r

Disable lookups for user names and project names. (Note that this does not apply to lookups for the –j, –u, or –U options.)

–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

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.

–scale[=item1,item2,...]

Specify display options for the SIZE, RSS, and SWAP columns. These columns are displayed in a scaled human readable format. Scaling is done by repetitively dividing by a scale factor of 1024, unless otherwise specified.

–scale specified without arguments enables default scaled output, and is equivalent to –scale=min,1024.

–scale can be specified with the following arguments.

binary

Scaling is done by repetitively dividing by a scale factor of 1024. The use of binary scaling is indicated by the addition of an 'i' modifier to the suffix (Ki, Mi, Gi, ...).

max

Values are scaled to the largest unit for which the result retains a non-zero integer part. Up to 2 decimal places of fractional output may be shown.

min

Values are scaled to the smallest unit capable of showing the full value within the allotted space of 5 columns, and displayed without the use of fractional output.

minwide

Values are scaled to the smallest unit capable of showing the full value within the allotted space of 8 columns, and displayed without the use of fractional output. See the –N option.

1000

Scaling is done by repetitively dividing by a scale factor of 1000.

1024

Scaling is done by repetitively dividing by a scale factor of 1024.

–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. The -t option cannot be used with -v, -m -a, -J, -T or -Z.

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

–x

Report the associated SMF service for a given process.

–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(7).

–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 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), gigabytes (G), or terabytes (T).

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 allocated or files are mapped private. The value of swap is expressed in kilobytes (K), megabytes (M), gigabytes (G), or terabytes (T).

RSS

The resident set size of the process (RSS), in kilobytes (K), megabytes (M), gigabytes (G), or terabytes (T). The RSS value is an estimate provided by proc(5) 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 complete.

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

run

Runnable: process is 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. 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 some of the 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.

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 and kernel 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

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

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
 306   root     3024K 1448K sleep   58    0   0:00.00 0.3% sendmail/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
 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 switchd/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(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/core-os
Interface Stability
See below.

The command name and options are Committed. The output format is not committed.

See Also

date(1), lgrpinfo(1), plgrp(1), proc(1), ps(1), time(2), pset_getloadavg(3C), proc(5), project(5), attributes(7), privileges(7), resource-controls(7), zones(7), psrinfo(8), psrset(8), sar(8)

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 process; the original state is restored when prstat exits. See proc(5) 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.

History

The –scale option was added to the prstat command in Oracle Solaris 11.4.30.

The –x option was added to the prstat command in Oracle Solaris 11.4.12.

The –D and –N options were added to the prstat command in Oracle Solaris 11.3.26.

The –d, –h, –H, and –r options were added to the prstat command in Oracle Solaris 11.0.0.

The –z and –Z options were added to the prstat command in Solaris 10 3/05.

The –j, –J, –k, and –T options were added to the prstat command Solaris 9.

The prstat command; with support for the –a, –c, –C, –L, –m, –n, –p, –P, –R, –s, –S, –t, –u, –U, and –v options; was introduced in the Solaris 8 release.