ADC Home > Reference Library > Reference > Mac OS X > Mac OS X Man Pages

 

This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).



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 processes.  The default sorting key is
       pid, but other keys can be used instead.  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  specified,  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.  Calcu-late Calculate
                     late CPU usage and CPU time since the launch of top.

              d      Delta mode.  Count events relative to the previous sample.  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 frameworks (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 object 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 displayed for each process,  as
              it is calculated using the delta between samples.

       -n <nprocs>
              Only display up to <nprocs> processes.  <nprocs> can be specified as the last command line ar-gument argument
              gument without the -n flag preceding 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 order.  A + or - can  be  prefixed
              to  the  key  name to specify ascending 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 CUSTOM 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 (default).

       -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 sec-ond. second.
              ond.

       -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 alphabetical 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 percentages 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 accumulative 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 libraries, 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 purgeable.

       Below the global state fields, a list of processes is displayed.  The fields that are  displayed  de-pend depend
       pend  on  the  options  that are set.  Following is an alphabetical list of fields and their descrip-tions. descriptions.
       tions.

       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 com-mand command
       mand is one character, followed by 0 to 2 arguments.  Commands that take  arguments  prompt  interac-tively interactively
       tively  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  escapes  the
       interactive  argument  prompt,  and has the same effect as leaving 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 infinity.

       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 order.  A + or - can  be  prefixed
              to  the  key  name to specify ascending 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-intensive.  To reduce the cpu usage
       in top, the -i parameter has been introduced to allow the user to tune this tradeoff.  With  the  de-fault default
       fault  value  of 10, framework stats will be updated once every 10 samples.  Specifying -i 1 will re-sult result
       sult 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 (^) character (indicating left justifica-tion) justification)
       tion)  or  the dollar ($) character (indicating right justification).  It is then followed by the de-sired desired
       sired 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 being 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 fol-lowing following
       lowing 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 resident 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, taking 10 samples at 2 second  in-tervals. intervals.
              tervals.

       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)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.