manpagez: man pages & more
man top(1)
Home | html | info | man
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>]
              [-l <samples>]
              [-ncols <columns>]
              [-o <key>] [-O <skey>]
              [-R | -r]
              [-S]
              [-s <delay>]
              [-n <nprocs>]
              [-stats <keys>]
              [-pid <processid>]
              [-user <username>]
              [-U <username>]
              [-u]


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     Equivalent to -c a.

       -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.
                     This mode by default disables the memory object  map  re-
                     porting.   The  memory object map reporting may be re-en-
                     abled with the -r option or the interactive r command.

              e      Absolute mode.  Count events using absolute counters.

              n      Non-event mode (default).  Calculate CPU usage since  the
                     previous sample.

       -d     Equivalent to -c d.

       -e     Equivalent to -c e.

       -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.

       -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.

       -ncols  <columns>
              Display <columns> when using logging mode.  The default is infi-
              nite.  The number must be > 0 or an error will occur.

       -n <nprocs>
              Only display up to <nprocs> processes.

       -O <skey>
              Use <skey> as a secondary key when ordering the process display.
              See -o for key names (pid is the 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:

              pid    Process ID (default).

              command
                     Command name.

              cpu    CPU usage.

              csw    Number of context switches.

              time   Execution time.

              threads
                     alias: th
                     Number of threads (total/running).

              ports  alias: prt
                     Number of Mach ports.

              mregion
                     alias: mreg, reg
                     Number of memory regions.

              mem    Internal memory size.

              rprvt  Resident private address space size.

              purg   Purgeable memory size.

              vsize  Total memory size.

              vprvt  Private address space size.

              kprvt  Private kernel memory size.

              kshrd  Shared kernel memory size.

              pgrp   Process group id.

              ppid   Parent process id.

              state  alias: pstate
                     Process state.

              uid    User ID.

              wq     alias: #wq, workqueue
                     The workqueue total/running.

              faults alias: fault
                     The number of page faults.

              cow    alias: cow_faults
                     The copy-on-write faults.

              user   alias: username Username.

              msgsent
                     Total number of mach messages sent.

              msgrecv
                     Total number of mach messages received.

              sysbsd Total BSD syscalls.

              sysmach
                     Total Mach syscalls.

              pageins
                     Total pageins.

       -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 the global statistics for swap and purgeable memory.

       -s <delay>
              Set the delay between updates to <delay> seconds.   The  default
              delay between updates is 1 second.

       -stats <keys>
              Only  display  the  comma separated statistics.  See the -o flag
              for the valid <keys>.

       -pid <processid>
              Only display <processid> in top.

       -user <user>
              Only display processes owned by <user>.

       -U <user>
              This is an alias for -user.

       -u     This is an alias equivalent to: -o cpu -O time.



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 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  Resident  sizes  of code and data segments, and link editor
                   memory usage.

       Threads     Number of threads.

       Time        Time, in H:MM:SS format.  When running in logging mode Time
                   is  in  YYYY/MM/DD  HH:MM:SS  format by default, but may be
                   overridden with accumulative mode.  When running in accumu-
                   lative  event  counting mode, the Time is in HH:MM:SS since
                   the beginning of the top process.

       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.  The  pid
       field displays the following for the architecture:

       +             for  64-bit  native  architecture, or - for 32-bit native
                     architecture, or * for a non-native architecture.


       INTERACTION
              When top is run in interactive (non-logging) mode, it is  possi-
              ble  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 arguments prompt interactively for the  argu-
              ments,  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 inter-
              active 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.

       O<skey>
              Use <skey> as a secondary key when ordering the process display.
              See the -o option 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
              and alises are listed with the -o option above.


       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.

       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.


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.


N/A - Not Available

       When this occurs in a stat it's caused by the memory object map report-
       ing being disabled.  Memory object map reporting is disabled by default
       in  delta mode, but may be optionally enabled via -r or the interactive
       r command.  To enable the -r option use it after any -c mode options.


EXAMPLES

       top -o cpu -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 -c d
              Run top in delta mode.


       top -stats pid,command,cpu,th,pstate,time
              Display only the specified statistics, regardless of any  growth
              of the terminal.  If the terminal is too small, only the statis-
              tics that fit will be displayed.



SEE ALSO

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



                                      top                               top(1)

Mac OS X 10.9 - Generated Sun Oct 13 13:25:55 CDT 2013
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.