Manual Pages for UNIX Darwin command on man top

top(1) top(1)

NAME

top - display and update sorted information about processes

SYNOPSIS

ttoopp [-aa | -dd | -ee | -cc ]

[-FF | -ff]

[-hh]

[-ii ]

[-kk]

[-LL | -ll ]

[-oo ] [-OO ]

[-pp ] [-PP ]

[-RR | -rr]

[-SS]

[-ss ]

[-TT | -tt]

[-UU ]

[-uu]

[-WW | -ww]

[-XX | -xx]

[[-nn] ]

DESCRIPTION

The ttoopp program periodically displays a sorted list of system process-

es. The default sorting key is pid, but other keys can be used in-

stead. Various output options are available. OOPPTTIIOONNSS Command line option specifications are processed from left to right. Options can be specified more than once. If conflicting options are specified, later specifications override earlier ones. This makes it

viable to create a shell alias for ttoopp with preferred defaults speci-

fied, then override those preferred defaults as desired on the command line.

-aa Deprecated, equivalent to -ccaa.

-cc

Set event counting mode to . The supported modes are: aa Accumulative mode. Count events cumulatively, starting at the launch of ttoopp. Calculate CPU usage and CPU time since the launch of ttoopp.

dd Delta mode. Count events relative to the previous sam-

ple. Calculate CPU usage since the previous sample. ee Absolute mode. Count events using absolute counters.

nn Non-event mode (default). Calculate CPU usage since the

previous sample.

-dd Deprecated, equivalent to -ccdd.

-ee Deprecated, equivalent to -ccee.

-FF Do not calculate statistics on shared libraries, also known as

frameworks.

-ff Calculate statistics on shared libraries, also known as frame-

works (default).

-hh Print command line usage information and exit.

-ii

Update framework (-f) info every samples; see the

PPEERRFFOORRMMAANNCCEE vvss.. AACCCCUURRAACCYY section below for more details.

-kk Deprecated (does nothing). This flag used to turn on memory ob-

ject reporting for process 0 (kerneltask), but this is now done by default.

-LL Use non-logging mode. If not running on a terminal, exit with

an error rather than running in logging mode.

-ll

Use logging mode and display samples, even if standard output is a terminal. 0 is treated as infinity. Rather than redisplaying, output is periodically printed in raw form. Note

that the first sample displayed will have an invalid %CPU dis-

played for each process, as it is calculated using the delta be-

tween samples.

-nn

Only display up to processes. can be speci-

fied as the last command line argument without the -nn flag pre-

ceding it. However, doing so is deprecated command line usage.

-OO

Use as a secondary key when ordering the process display.

See -oo for key names (ppiidd is default).

-oo

Order the process display by sorting on in descending or-

der. A ++ or - can be prefixed to the key name to specify as-

cending or descending order, respectively. The supported keys are: ccoommmmaanndd Command name. ccppuu CPU usage. ppiidd Process ID (default).. pprrtt Number of Mach ports. rreegg Number of memory regions. rrpprrvvtt Resident private address space size. rrsshhrrdd Resident shared address space size. rrssiizzee Resident memory size. tthh Number of threads. ttiimmee Execution time. uuiidd User ID. uusseerrnnaammee Username. vvpprrvvtt Private address space size. vvssiizzee Total memory size.

-PP

Set a custom legend string (containing the column headings); this should usually be used with a custom format string.

-pp

Set a custom format string to display process info; see the CCUUSS-

TTOOMM DDIISSPPLLAAYY FFOORRMMAATT section for more information on this option.

-RR Do not traverse and report the memory object map for each

process.

-rr Traverse and report the memory object map for each process (de-

fault).

-SS Display information about swap usage and purgeable memory.

-ss

Set the delay between updates to seconds. The default delay between updates is 1 second.

-TT Do not translate uid numbers to usernames (default).

-tt Translate uid numbers to usernames.

-UU

Only display processes owned by . Either the username or uid number can be specified.

-uu Deprecated, equivalent to -ooccppuu -OOttiimmee.

-WW Display ++ or - to indicate deltas (default).

-ww Display delta values, rather than just ++ or -.

-XX Run using the legacy display format.

-xx Run using the nominal display format.

DDIISSPPLLAAYY The first several lines of the ttoopp display show various global

state. All of the information is labeled. Following is an al-

phabetical list of global state fields and their descriptions. CCPPUU Percentage of processor usage, broken into user, system,

and idle components. The time period for which these per-

centages are calculated depends on the event counting mode. DDiisskkss Number and total size of disk reads and writes. LLooaaddAAvvgg Load average over 1, 5, and 15 minutes. The load average is the average number of jobs in the run queue. MMeemmRReeggiioonnss Number and total size of memory regions, and total size of

memory regions broken into private (broken into non-library

and library) and shared components. NNeettwwoorrkkss Number and total size of input and output network packets. PPhhyyssMMeemm Physical memory usage, broken into wired, active, inactive, used, and free components. PPrrooccss Total number of processes and number of processes in each process state. SShhaarreeddLLiibbss Number of shared libraries, resident sizes of code and data segments, and link editor memory usage. TThhrreeaaddss Number of threads.

TTiimmee Time, in YYYY/MM/DD HH:MM:SS format. When running in accu-

mulative event counting mode, the time since top started is

printed in parentheses in H:MM:SS format.

VViirrttMMeemm Total virtual memory, virtual memory consumed by shared li-

braries, and number of pageins and pageouts. SSwwaapp Swap usage: total size of swap areas, amount of swap space in use and amount of swap space available.

PPuurrggeeaabbllee Number of pages purged and number of pages currently purge-

able. Below the global state fields, a list of processes is displayed. The

fields that are displayed depend on the options that are set. Follow-

ing is an alphabetical list of fields and their descriptions. BBSSYYSSCCAALLLL Number of BSD system calls made. CCOOMMMMAANNDD Command name. CCOOWWFFAAUULLTTSS Number of faults that caused a page to be copied.

%%CCPPUU Percentage of processor time consumed (kernel and user).

CCSSWWIITTCCHH Number of context switches. FFAAUULLTTSS Number of faults. MMSSYYSSCCAALLLL Number of Mach system calls made. RREEGG Number of memory regions. MMSSGGSSRRCCVVDD Number of Mach messages received. MMSSGGSSSSEENNTT Number of Mach messages sent. PPAAGGEEIINNSS Number of requests for pages from a pager. PPIIDD Process ID. PPRRTT((ddeellttaa)) Number of Mach ports. RRPPRRVVTT((ddeellttaa)) Resident private memory size. RRSSHHRRDD((ddeellttaa)) Resident shared memory size. RRSSIIZZEE((ddeellttaa)) Total resident memory size, including shared pages. TTHH Number of threads. TTIIMMEE Absolute processor time consumed. UUIIDD User ID of process owner.

USERNAME srae f rcs onr

VVPPRRVVTT((ddeellttaa)) Private address space size. VVSSIIZZEE((ddeellttaa)) Total address space allocated, including shared pages. IINNTTEERRAACCTTIIOONN

When ttoopp is run in interactive (non-logging) mode, it is possible to

control the output of ttoopp, as well as interactively send signals to processes. The interactive command syntax is terse. Each command is

one character, followed by 0 to 2 arguments. Commands that take argu-

ments prompt interactively for the arguments, and where applicable, the default value is shown in square brackets. The default value can be

selected by leaving the input field blank and pressing enter. ^^GG es-

capes the interactive argument prompt, and has the same effect as leav-

ing the input field blank and pressing enter. The following commands are supported: ?? Display the help screen. Any character exits help screen mode. This command always works, even in the middle of a command. ^^LL Redraw the screen. cc Set output mode to . The supported modes are: aa Accumulative mode. dd Delta mode. ee Event mode.

nn Non-event mode.

ff Toggle shared library statistics reporting. nn

Only display up to processes. 0 is treated as infini-

ty. OO Use as a secondary key when ordering the process display. See the oo command for key names. oo

Order the process display by sorting on in descending or-

der. A ++ or - can be prefixed to the key name to specify as-

cending or descending order, respectively. The supported keys are: ccoommmmaanndd Command name. ccppuu CPU usage. ppiidd Process ID. pprrtt Number of Mach ports. rreegg Number of memory regions. rrpprrvvtt Resident private address space size. rrsshhrrdd Resident shared address space size. rrssiizzee Resident memory size. tthh Number of threads. ttiimmee Execution time. uuiidd User ID. uusseerrnnaammee Username. vvpprrvvtt Private address space size. vvssiizzee Total memory size. qq Quit. rr Toggle traversal and reporting of the memory object map for each process. SS Send to . can be specified either as a number or as a name (for example, HHUUPP). The default signal starts out as TTEERRMM. Each time a signal is successfully sent, the default signal is updated to be that signal. is a process id. ss Set the delay between updates to seconds. tt Toggle translation of uid numbers to usernames. UU Only display processes owned by . Either the username or uid number can be specified. To display all processes, press enter without entering a username or uid number. ww Toggle wide/narrow delta mode. xx Toggle display formats. PPEERRFFOORRMMAANNCCEE vvss.. AACCCCUURRAACCYY

Calculating detailed memory statistics is fundamentally resource-inten-

sive. To reduce the cpu usage in top, the -i parameter has been intro-

duced to allow the user to tune this tradeoff. With the default value

of 10, framework stats will be updated once every 10 samples. Specify-

ing -i 1 will result in the most accurate display, at the expense of

system resources. CCUUSSTTOOMM DDIISSPPLLAAYY FFOORRMMAATTSS

Users who would like to change the format of the top process display

lines may use the -p option to specify a custom format. Any number of

fields may be specified, and the the order of these fields and their widths may be specified by using the following special syntax. The following fields are available: aa Process ID (PID) bb command string cc CPU usage (percentage) dd CPU usage (time) ee threads ff Mach ports gg memory regions hh RPRVT ii RSHRD jj RSIZE kk VPRVT ll VSIZE mm UID nn username oo page faults pp pageins qq COW faults rr messages sent ss messages received tt bsyscall uu msyscall vv cswitch ww time (in HH:MM:SS) format

Each format specification is introduced by either the carat (^) charac-

ter (indicating left justification) or the dollar ($) character (indi-

cating right justification). It is then followed by the desired format character; this character may be repeated to delineate the field width. (For example,

Certain fields (f, h, i, j, l) may be followed by one or more dash (-)

characters; this will cause a delta to be displayed. One dash will

display `-', `+' or ' ' to indicate a decrease, increase, or no change

in the value. Multiple dashes will result in an actual delta value be-

ing displayed. The backslash character may be used to escape any character, including itself. Any other character will be displayed as a literal.

The -P flag may be used to specify a custom legend line. Specifying

either -P or -p without a following format string will cause top to

display the default legend and format for the selected display mode. EEXXAAMMPPLLEESS

top -ocpu -O+rsize -s 5 -n 20

Sort the processes according to CPU usage (descending) and resi-

dent memory size (ascending), sample and update the display at 5 second intervals, and limit the display to 20 processes.

top -ce

Run top in event counter mode.

top -tl 10

Translate uid numbers to usernames and run in logging mode, tak-

ing 10 samples at 2 second intervals.

top -P ' PID COMMAND %CPU TIME #TH #PRTS #MREGS RPRVT RSHRD

RSIZE VSIZE' \

-p '$aaaa ^bbbbbbbbb $cccc% $www $ee $ffff-$ggggg $hhhh-

$iiii- $jjjj- $llll-' This will recreate the default process

display.