TOP

Section: User Commands (1)
Index Return to Main Contents

BSD mandoc
Mac OS X  

NAME

top - show system usage statistics  

SYNOPSIS

top [-u ] [-w ] [-k ] [-s interval ] [-e | -d | -a ] [-l samples ] [number ]  

DESCRIPTION

top displays an ongoing sample of system usage statistics. It operates in various modes, but by default shows cpu utilization and memory usage for each process in the system.

The options are as follows:

-u
When the -u option is specified, processes are first sorted by cpu usage and then displayed starting with the highest consumers.
-w
Specifying the -w option generates additional columns in the output producing a much wider display of data. The additional columns include VPRVT, along with the delta information for #PRTS, RPRVT, RSHRD, RSIZE and VSIZE (see descriptions following).
-k
The -k option causes top to traverse and report the memory object map for pid 0 (the kernel task). It is optional because it is fairly expensive to traverse the object maps and the kernel task may have a huge number of entries.
-s
By default, top updates its output at one second intervals. This sampling interval may be changed by specifying the -s option. Enter the interval in seconds.
-e
Using the -e option switches from the default output to an event counting mode where the counts reported are absolute counters. The -w and -k options are ignored when running in event counting mode.
-d
Using the -d option switches from the default output to an event counting mode where the counts are reported as deltas relative to the previous sample. The -w and -k options are ignored when running in event counting, delta mode.
-a
Using the -a option switches from the default output to an event counting mode where the counts are reported as cumulative counters relative to when top was launched. The -w and -k options are ignored when running in event counting, accumulate mode.
-l
Using the -l option switches from the default screen mode to a logging mode suitable for saving the output to a file. You may specify the number of samples to be output before top exits, the default is 1 sample.
number
If you wish to limit the number of processes displayed by top, specify the desired number of output lines in this last argument.

The columns displayed in the default data mode are as follows:

PID
the Unix process id.
COMMAND
the Unix command name.
%CPU
the percentage of cpu consumed (kernel and user).
TIME
the absolute cpu consumption (min:secs.hundreths).
#TH
the number of threads.
#PRTS(delta)
the number of mach ports.
#MREG
the number of memory regions.
VPRVT(-w only)
the private address space currently allocated.
RPRVT(delta)
the resident private memory.
RSHRD(delta)
the resident shared memory (as represented by the resident page count of each shared memory object).
RSIZE(delta)
the total resident memory (real pages that this process currently has associated with it. Some may be shared by other processes).
VSIZE(delta)
the total address space currently allocated (including shared).

The delta columns are enabled by the -w option. The deltas for #PRTS and VSIZE are relative to the numbers observed when top was launched. The deltas for RPRVT, RSHRD and RSIZE are relative to the previous sample. If the -w option was not specified, top will append either a '+' or a '-' to the RPRVT, RSHRD, RSIZE or VSIZE columns indicating either a gain or a loss relative to the previous sample.

The columns displayed in the event counting modes (ie: -e | -d | -a options) are as follows:

PID
the Unix process id.
COMMAND
the Unix command name.
%CPU
the percentage of cpu consumed (kernel and user).
TIME
the absolute cpu consumption (min:secs.hundreths).
FAULTS
the number of page faults.
PAGEINS
the number of requests for pages from a pager.
COW_FAULTS
the number of faults that caused a page to be copied.
MSGS_SENT
the number of mach messages sent by the process.
MSGS_RCVD
the number of mach messages received by the process.
BSDSYSCALL
the number of BSD system calls made by the process.
MACHSYSCALL
the number of MACH system calls made by the process.
CSWITCH
the number of context switches to this process.

The top command also displays some global state in the first few lines of output, including load averages, cpu utilization and idleness, process and thread counts and memory breakdowns for shared libraries and processes. The top command is SIGWINCH savvy, so adjusting your window geometry may change the number of processes and number of columns displayed. Typing a 'q' will cause top to exit immediately. Typing any other character will cause top to immediately update it's display.  

SAMPLE USAGE

top -u -s5 20

top will sort the processes according to cpu usage, update the output at 5 second intervals, and limit the display to the top 20 processes.  

SEE ALSO

vm_stat1


 

Index

NAME
SYNOPSIS
DESCRIPTION
SAMPLE USAGE
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 04:29:37 GMT, April 24, 2025