top(1) top(1)
NAME
top - display and update sorted information about processes
SYNOPSIS
top [-a | -d | -e | -c <mode>]
[-F | -f]
[-h]
[-i <interval>]
[-k]
[-L | -l <samples>]
[-o <key>] [-O <skey>]
[-p <format>] [-P <legend>]
[-R | -r]
[-S]
[-s <delay>]
[-T | -t]
[-U <user>]
[-u]
[-W | -w]
[-X | -x]
[[-n] <nprocs>]
DESCRIPTION
The top 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.
OPTIONS
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 top with preferred defaults speci-
fied, then override those preferred defaults as desired on the command
line.
-a Deprecated, equivalent to -ca.
-c <mode>
Set event counting mode to <mode>. The supported modes are:
a Accumulative mode. Count events cumulatively, starting
at the launch of top. Calculate CPU usage and CPU time
since the launch of top.
d Delta mode. Count events relative to the previous sam-
ple. Calculate CPU usage since the previous sample.
e Absolute mode. Count events using absolute counters.
n Non-event mode (default). Calculate CPU usage since the
previous sample.
-d Deprecated, equivalent to -cd.
-e Deprecated, equivalent to -ce.
-F Do not calculate statistics on shared libraries, also known as
frameworks.
-f Calculate statistics on shared libraries, also known as frame-
works (default).
-h Print command line usage information and exit.
-i <interval>
Update framework (-f) info every <interval> samples; see the
PERFORMANCE vs. ACCURACY section below for more details.
-k 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.
-L Use non-logging mode. If not running on a terminal, exit with
an error rather than running in logging mode.
-l <samples>
Use logging mode and display <samples> 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.
-n <nprocs>
Only display up to <nprocs> processes. <nprocs> can be speci-
fied as the last command line argument without the -n flag pre-
ceding it. However, doing so is deprecated command line usage.
-O <skey>
Use <skey> as a secondary key when ordering the process display.
See -o for key names (pid is default).
-o <key>
Order the process display by sorting on <key> 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:
command
Command name.
cpu CPU usage.
pid Process ID (default)..
prt Number of Mach ports.
reg Number of memory regions.
rprvt Resident private address space size.
rshrd Resident shared address space size.
rsize Resident memory size.
th Number of threads.
time Execution time.
uid User ID.
username
Username.
vprvt Private address space size.
vsize Total memory size.
-P <legend>
Set a custom legend string (containing the column headings);
this should usually be used with a custom format string.
-p <format>
Set a custom format string to display process info; see the CUS-
TOM DISPLAY FORMAT section for more information on this option.
-R Do not traverse and report the memory object map for each
process.
-r Traverse and report the memory object map for each process (de-
fault).
-S Display information about swap usage and purgeable memory.
-s <delay>
Set the delay between updates to <delay> seconds. The default
delay between updates is 1 second.
-T Do not translate uid numbers to usernames (default).
-t Translate uid numbers to usernames.
-U <user>
Only display processes owned by <user>. Either the username or
uid number can be specified.
-u Deprecated, equivalent to -ocpu -Otime.
-W Display + or - to indicate deltas (default).
-w Display delta values, rather than just + or -.
-X Run using the legacy display format.
-x Run using the nominal display format.
DISPLAY
The first several lines of the top display show various global
state. All of the information is labeled. Following is an al-
phabetical list of global state fields and their descriptions.
CPU 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.
Disks Number and total size of disk reads and writes.
LoadAvg Load average over 1, 5, and 15 minutes. The load average
is the average number of jobs in the run queue.
MemRegions 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.
Networks Number and total size of input and output network packets.
PhysMem Physical memory usage, broken into wired, active, inactive,
used, and free components.
Procs Total number of processes and number of processes in each
process state.
SharedLibs Number of shared libraries, resident sizes of code and data
segments, and link editor memory usage.
Threads Number of threads.
Time 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.
VirtMem Total virtual memory, virtual memory consumed by shared li-
braries, and number of pageins and pageouts.
Swap Swap usage: total size of swap areas, amount of swap space
in use and amount of swap space available.
Purgeable 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.
BSYSCALL Number of BSD system calls made.
COMMAND Command name.
COW_FAULTS Number of faults that caused a page to be copied.
%CPU Percentage of processor time consumed (kernel and user).
CSWITCH Number of context switches.
FAULTS Number of faults.
MSYSCALL Number of Mach system calls made.
REG Number of memory regions.
MSGS_RCVD Number of Mach messages received.
MSGS_SENT Number of Mach messages sent.
PAGEINS Number of requests for pages from a pager.
PID Process ID.
PRT(delta) Number of Mach ports.
RPRVT(delta) Resident private memory size.
RSHRD(delta) Resident shared memory size.
RSIZE(delta) Total resident memory size, including shared pages.
TH Number of threads.
TIME Absolute processor time consumed.
UID User ID of process owner.
USERNAME Username of process owner.
VPRVT(delta) Private address space size.
VSIZE(delta) Total address space allocated, including shared pages.
INTERACTION
When top is run in interactive (non-logging) mode, it is possible to
control the output of top, 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. ^G 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.
^L Redraw the screen.
c<mode>
Set output mode to <mode>. The supported modes are:
a Accumulative mode.
d Delta mode.
e Event mode.
n Non-event mode.
f Toggle shared library statistics reporting.
n<nprocs>
Only display up to <nprocs> processes. 0 is treated as infini-
ty.
O<skey>
Use <skey> as a secondary key when ordering the process display.
See the o command for key names.
o<key>
Order the process display by sorting on <key> 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:
command
Command name.
cpu CPU usage.
pid Process ID.
prt Number of Mach ports.
reg Number of memory regions.
rprvt Resident private address space size.
rshrd Resident shared address space size.
rsize Resident memory size.
th Number of threads.
time Execution time.
uid User ID.
username
Username.
vprvt Private address space size.
vsize Total memory size.
q Quit.
r Toggle traversal and reporting of the memory object map for each
process.
S<signal><pid>
Send <sig> to <pid>. <sig> can be specified either as a number
or as a name (for example, HUP). The default signal starts out
as TERM. Each time a signal is successfully sent, the default
signal is updated to be that signal. <pid> is a process id.
s<delay>
Set the delay between updates to <delay> seconds.
t Toggle translation of uid numbers to usernames.
U<user>
Only display processes owned by <user>. Either the username or
uid number can be specified. To display all processes, press
enter without entering a username or uid number.
w Toggle wide/narrow delta mode.
x Toggle display formats.
PERFORMANCE vs. ACCURACY
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.
CUSTOM DISPLAY FORMATS
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:
a Process ID (PID)
b command string
c CPU usage (percentage)
d CPU usage (time)
e threads
f Mach ports
g memory regions
h RPRVT
i RSHRD
j RSIZE
k VPRVT
l VSIZE
m UID
n username
o page faults
p pageins
q COW faults
r messages sent
s messages received
t bsyscall
u msyscall
v cswitch
w 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.
EXAMPLES
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% $wwwwwww $ee $ffff-$ggggg $hhhh-
$iiii- $jjjj- $llll-' This will recreate the default process
display.
SEE ALSO
kill(2), vm_stat(1), signal(3)
top top(1)
Mac OS X 10.5 - Generated Sun Oct 28 21:03:19 EDT 2007