top

display and update sorted information about processes

Each version of *nix has their own implementaition of top.
This document reflects Apple Mac OS X El Captian.

top [-a | -d | -e | -c mode] [-F | -f] [-h] [-i interval] [-l samples] [-ncols columns] [-o key] [-O ]
      [-R | -r] [-S] [-s delay] [-n nprocs] [-stats keys] [-pid processid] [-user username] [-U username] [-u]

Periodically displays a list of system processes. The default sorting key is pid

Option specifications are processed from left to right. For repeated options: later specifications override earlier ones. This makes it viable to create a shell alias for top with preferred defaults then override those preferred defaults as desired on the command line.

-c mode
d Delta mode. Since previous sample. Default.
a Accumulative mode. Count events, CPU usage and time, since the launch of top.
Disables the memory object map reporting, re-enabled with -r or the interactive r command.
e Absolute mode. (i.e. since startup)
n Non-event mode (default). Calculate CPU usage since the previous sample.
-d
-a
-e
Delta
Accumulative
Absolute

-f Calculate statistics on shared libraries, also known as frameworks (default).
-F Do not "
-h help
-i samples Update framework info every samples ; see the PERFORMANCE vs. ACCURACY section below for more details.
-l samples logging mode and display samples samples
Rather than redisplaying, output is periodically output in raw form.
The first sample will have an invalid %CPU for each process, as it is calculated using the delta between samples.
-ncols columns Display columns in logging mode.
-n nprocs Only display nprocs processes.
-o key Order the process display by sorting on key in descending order.
A + or - can be prefixed to the key name to specify ascending or descending
-O skey Use skey as a secondary key
 
              pid      (default).  
              command   
              cpu       
              time       Execution time.  
              #th        threads (total/running).
              threads
              wq     
              #wq workqueue total/running.
              ports  
              prt    Mach ports.  
              mem    Internal memory  (0B zero bytes)
              PURG   purgable
              CMPR   compressed

              pgrp   Process group id.  
              ppid   Parent process id.  

              state  running | sleeping | stuck
              boosts held by the process transitions from unboosted to boosted ]
                      An asterisk indicates that the  process was  able to send boosts at some point since the previous update. See  xpc_transaction_begin(3). 
              cpu_me     CPU time charged to me by other processes.  
              cpu_others CPU time charged to other processes by me.  
              uid    User ID.  
              faults    page faults.  
              cow       copy-on-write faults.  

              msgsent   mach messages sent.  
              msgrecv   mach messages received.  
              sysbsd    BSD syscalls.  
              sysmach   Mach syscalls.
              csw        context switches.  
              pageins   pageins.
              idle
              power

              mregion
              mreg 
              reg     memory regions.

              rprvt  Resident private address space 
              purg   Purgeable
              vprvt  Private address space 
              kprvt  kernel Private
              kshrd  kernel Shared
              vsize  Total 

              pstate Process state.



              user   alias: username Username.
-u -o cpu -O time.
-r Traverse and report the memory object map for each process (default).
-R Do not ""
-S Display the global statistics for swap and purgeable memory.
-s delay Set the delay between updates to delay seconds. Default: 1 second.
-stats keys Only display the comma separated statistics.
-pid processid Only display processid in top.
-user user
-U
Only display processes owned by user.

DISPLAY


prio / nice is not displayed! (see ps -o nice -o pri
The first several lines of show global state.
Procs Total number of processes and number of processes in each process state.
Threads Number of threads.
Time in logging mode YYYY/MM/DD HH:MM:SS format by default. overridden with accumulative mode.
When running in accumulative event counting mode, the Time is in HH:MM:SS since the beginning of the top process.
 
LoadAvg Load average over 1, 5, and 15 minutes. i.e. average number of jobs in the run queue.
CPU Percentage of processor usage, by user, system, and idle components.
The time period for which these percentages are calculated depends on the event counting mode.
SharedLibs Resident sizes of code and data segments, and link editor memory usage.
MemRegions Number and total size of memory regions, and total size of memory regions by private (by non-library and library) and shared components.
 
PhysMem Physical memory usage, broken into wired, active, inactive, used, and free components.
VirtMem Total virtual memory, virtual memory consumed by shared libraries, and number of pageins and pageouts.
Networks Number and total size of input and output network packets.
Disks Number and total size of disk reads and writes.
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 purgeable.

Below the global state fields, a list of processes is displayed. The pid field displays the following for the architecture: + for 64-bit native or - for 32-bit native or * for a non-native .

INTERACTION
Each command is one character, arguments are prompted for, (default shown in brackets), selected by pressing enter.
? Display the help screen.
^L Redraw the screen.
c mode
o key sorting on key A + or - prefix ascending or descending
O skey skey is secondary key
q Quit.
r Toggle traversal and reporting of the memory object map for each process.
S signal pid Send sig to pid The default signal starts out as TERM. Each time a signal is successfully sent, the default signal is updated to be that signal.
sdelay between updates
Uuser Only display processes owned by user. Either the username or uid number
To display all processes, press enter

PERFORMANCE vs. ACCURACY

Calculating detailed memory statistics is resource-intensive. To reduce the cpu usage framework stats will be updated once every 10 samples. Specifying -i 1 will result in the most accurate display, at the expense of system resources.

N/A - Not Available: Caused by the memory object map reporting being disabled. (default in delta mode)
, but may be enabled via -r or the interactive r command after any -c

EXAMPLES

Sort the processes according to CPU usage (descending) and resident memory size (ascending), sample and update the display at 5 second intervals, and limit the display to 20 processes.
top -o cpu -O +rsize -s 5 -n 20
Run top in delta mode.
top -c d
Display only the specified statistics, regardless of any growth of the terminal. If the terminal is too small, only the statistics that fit will be displayed.
top -stats pid,command,cpu,th,pstate,time

SEE ALSO

kill(2), vm_stat(1), signal(3), vmmap(1)