top(1) top(1)
NNAAMMEE
top - display and update sorted information about processes
SSYYNNOOPPSSIISS
ttoopp [--aa | --dd | --ee | --cc _<_m_o_d_e_>]
[--FF | --ff]
[--hh]
[--kk]
[--LL | --ll _<_s_a_m_p_l_e_s_>]
[--oo _<_k_e_y_>] [--OO _<_s_k_e_y_>]
[--RR | --rr]
[--ss _<_d_e_l_a_y_>]
[--TT | --tt]
[--UU _<_u_s_e_r_>]
[--uu]
[--WW | --ww]
[--XX | --xx]
[[--nn] _<_n_p_r_o_c_s_>]
DDEESSCCRRIIPPTTIIOONN
The ttoopp program periodically displays a list of processes on the system
in sorted order. The default key for sorting is pid, but other keys
can be used instead. 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 _<_m_o_d_e_>
Set event counting mode to _<_m_o_d_e_>. 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. This substantially reduces the amount of processor
time ttoopp consumes.
--ff Calculate statistics on shared libraries, also known as frame-
works (default).
--hh Print command line usage information and exit.
--kk Deprecated (does nothing). This flag used to turn on memory ob-
ject reporting for process 0 (kernel_task), but this is now done
by default.
--LL Use interactive (non-logging) mode. If not running on a termi-
nal, exit with an error rather than running in logging mode.
--ll _<_s_a_m_p_l_e_s_>
Use logging mode and display _<_s_a_m_p_l_e_s_> samples, even if standard
output is a terminal. 0 is treated as infinity. Rather than
redisplaying, output is periodically printed in raw form.
--nn _<_n_p_r_o_c_s_>
Only display up to _<_n_p_r_o_c_s_> processes. _<_n_p_r_o_c_s_> 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 _<_s_k_e_y_>
Use _<_s_k_e_y_> as a secondary key when ordering the process display.
See --oo for key names (ppiidd is default).
--oo _<_k_e_y_>
Order the process display by sorting on _<_k_e_y_> 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.
--RR Do not traverse and report the memory object map for each pro-
cess. This substantially reduces the amount of processor time
ttoopp consumes.
--rr Traverse and report the memory object map for each process (de-
fault).
--ss _<_d_e_l_a_y_>
Set the delay between updates to _<_d_e_l_a_y_> 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 _<_u_s_e_r_>
Only display processes owned by _<_u_s_e_r_>. 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 in compatibility mode.
--xx Do not run in compatibility mode (default). This causes ttoopp to
display output in the same format as the version of top included
with Jaguar. Specifying this flag in combination with options
that did not exist in Jaguar's ttoopp may produce meaningless out-
put in some cases. For documentation on the usage and output of
Jaguar's ttoopp, see top(1) on a Jaguar system. When this option
is specified, all interactive key bindings are the same as in
Jaguar's top, except that the xx key switches to compatibility
mode.
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.
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.
CCOOWW__FFAAUULLTTSS 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.
MMSSGGSS__RRCCVVDD Number of Mach messages received.
MMSSGGSS__SSEENNTT 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.
UUSSEERRNNAAMMEE Username of process owner.
VVPPRRVVTT((ddeellttaa)) Private address space size.
VVSSIIZZEE((ddeellttaa)) Total address space allocated, including shared pages.
IINNTTEERRAACCTTIIOONN
When ttoopp is run in interactive mode, it is possible to control the out-
put 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 arguments prompt in-
teractively 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 escapes the in-
teractive argument prompt, and has the same effect as leaving the input
field blank and pressing enter.
Keypresses that do not correspond to a command cause an immediate sam-
ple update. 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_<_m_o_d_e_>
Set output mode to _<_m_o_d_e_>. The supported modes are:
aa Accumulative mode.
dd Delta mode.
ee Event mode.
nn Non-event mode.
ff Toggle shared library statistics reporting.
nn_<_n_p_r_o_c_s_>
Only display up to _<_n_p_r_o_c_s_> processes. 0 is treated as infini-
ty.
OO_<_s_k_e_y_>
Use _<_s_k_e_y_> as a secondary key when ordering the process display.
See the oo command for key names.
oo_<_k_e_y_>
Order the process display by sorting on _<_k_e_y_> 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_<_s_i_g_n_a_l_>_<_p_i_d_>
Send _<_s_i_g_> to _<_p_i_d_>_. _<_s_i_g_> 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. _<_p_i_d_> is a process id.
ss_<_d_e_l_a_y_>
Set the delay between updates to _<_d_e_l_a_y_> seconds.
tt Toggle translation of uid numbers to usernames.
UU_<_u_s_e_r_>
Only display processes owned by _<_u_s_e_r_>. 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 deprecated/normal 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.
SSEEEE AALLSSOO
kill(2), top(1)[Jaguar], vm_stat(1), signal(3)
top top(1)