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.

              cpu_me CPU time charged to me by other processes.

              cpu_others
                     CPU time charged to other processes by me.

              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.

              boosts The number of boosts held by the process.  This  is  fol-
                     lowed by the number of times the process has transitioned
                     from unboosted to boosted in brackets.  An  asterisk  be-
                     fore  the  value  indicates  that the process was able to
                     send boosts at some point since the previous update.  For
                     more  information  about  boosts, see xpc_transaction_be-
                     gin(3).

       -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.  This option may  be  specified
              multiple times.

       -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.12.3 - Generated Sat Feb 4 14:59:47 CST 2017
© manpagez.com 2000-2017
Individual documents may contain additional copyright information.