1TOP(1)                           User Commands                          TOP(1)
2
3
4

NAME

6       top - display Linux processes
7
8

SYNOPSIS

10       top -hv|-bcEHiOSs1 -d secs -n max -u|U user -p pid -o fld -w [cols]
11
12       The traditional switches `-' and whitespace are optional.
13
14

DESCRIPTION

16       The  top program provides a dynamic real-time view of a running system.
17       It can display system summary information as well as  a  list  of  pro‐
18       cesses  or  threads  currently  being managed by the Linux kernel.  The
19       types of system summary information shown and the types, order and size
20       of  information  displayed  for processes are all user configurable and
21       that configuration can be made persistent across restarts.
22
23       The program provides a limited interactive interface for process manip‐
24       ulation as well as a much more extensive interface for personal config‐
25       uration  --  encompassing every aspect of its operation.  And while top
26       is  referred to throughout this document, you are free to name the pro‐
27       gram anything you wish.  That new name, possibly an alias, will then be
28       reflected on top's display and used when reading and writing a configu‐
29       ration file.
30
31

OVERVIEW

33   Documentation
34       The remaining Table of Contents
35
36           OVERVIEW
37              Operation
38              Linux Memory Types
39           1. COMMAND-LINE Options
40           2. SUMMARY Display
41              a. UPTIME and LOAD Averages
42              b. TASK and CPU States
43              c. MEMORY Usage
44           3. FIELDS / Columns Display
45              a. DESCRIPTIONS of Fields
46              b. MANAGING Fields
47           4. INTERACTIVE Commands
48              a. GLOBAL Commands
49              b. SUMMARY AREA Commands
50              c. TASK AREA Commands
51                 1. Appearance
52                 2. Content
53                 3. Size
54                 4. Sorting
55              d. COLOR Mapping
56           5. ALTERNATE-DISPLAY Provisions
57              a. WINDOWS Overview
58              b. COMMANDS for Windows
59              c. SCROLLING a Window
60              d. SEARCHING in a Window
61              e. FILTERING in a Window
62           6. FILES
63              a. PERSONAL Configuration File
64              b. ADDING INSPECT Entries
65              c. SYSTEM Configuration File
66              d. SYSTEM Restrictions File
67           7. STUPID TRICKS Sampler
68              a. Kernel Magic
69              b. Bouncing Windows
70              c. The Big Bird Window
71              d. The Ol' Switcheroo
72           8. BUGS, 9. SEE Also
73
74
75   Operation
76       When operating top, the two most important keys are the help (h  or  ?)
77       key and quit (`q') key.  Alternatively, you could simply use the tradi‐
78       tional interrupt key (^C) when you're done.
79
80       When started for the first time, you'll be presented with these  tradi‐
81       tional elements on the main top screen: 1) Summary Area; 2) Fields/Col‐
82       umns Header; 3) Task Area.  Each of these will be explored in the  sec‐
83       tions  that  follow.   There  is also an Input/Message line between the
84       Summary Area and Columns Header which needs no further explanation.
85
86       The main top screen is generally quite adaptive to changes in  terminal
87       dimensions  under  X-Windows.   Other top screens may be less so, espe‐
88       cially those with static text.  It ultimately depends, however, on your
89       particular  window  manager  and terminal emulator.  There may be occa‐
90       sions when their view of terminal size  and  current  contents  differs
91       from top's view, which is always based on operating system calls.
92
93       Following  any re-size operation, if a top screen is corrupted, appears
94       incomplete or disordered, simply  typing  something  innocuous  like  a
95       punctuation character or cursor motion key will usually restore it.  In
96       extreme cases, the following sequence almost certainly will:
97              key/cmd  objective
98              ^Z       suspend top
99              fg       resume top
100              <Left>   force a screen redraw (if necessary)
101
102       But if the display is still corrupted, there is one more step you could
103       try.   Insert  this  command  after  top  has been suspended but before
104       resuming it.
105              key/cmd  objective
106              reset    restore your terminal settings
107
108       Note: the width of top's display will  be  limited  to  512  positions.
109       Displaying all fields requires approximately 250 characters.  Remaining
110       screen width is usually allocated to any variable  width  columns  cur‐
111       rently visible.  The variable width columns, such as COMMAND, are noted
112       in topic 3a. DESCRIPTIONS of Fields.  Actual output width may  also  be
113       influenced  by  the  -w  switch,  which  is  discussed in topic 1. COM‐
114       MAND-LINE Options.
115
116       Lastly, some of top's screens or functions require the  use  of  cursor
117       motion  keys  like the standard arrow keys plus the Home, End, PgUp and
118       PgDn keys.  If your terminal or emulator does not provide  those  keys,
119       the following combinations are accepted as alternatives:
120              key      equivalent-keys
121              Left     alt + h
122              Down     alt + j
123              Up       alt + k
124              Right    alt + l
125              Home     alt + ctrl + h
126              PgDn     alt + ctrl + j
127              PgUp     alt + ctrl + k
128              End      alt + ctrl + l
129
130       The  Up and Down arrow keys have special significance when prompted for
131       line input terminated with the  <Enter>  key.   Those  keys,  or  their
132       aliases, can be used to retrieve previous input lines which can then be
133       edited and re-input.  And there are four additional keys available with
134       line oriented input.
135              key      special-significance
136              Up       recall older strings for re-editing
137              Down     recall newer strings or erase entire line
138              Insert   toggle between insert and overtype modes
139              Delete   character removed at cursor, moving others left
140              Home     jump to beginning of input line
141              End      jump to end of input line
142
143
144   Linux Memory Types
145       For  our purposes there are three types of memory, and one is optional.
146       First is physical memory, a limited resource where code and  data  must
147       reside  when  executed  or referenced.  Next is the optional swap file,
148       where modified (dirty) memory can be saved and later retrieved  if  too
149       many  demands are made on physical memory.  Lastly we have virtual mem‐
150       ory, a nearly unlimited resource serving the following goals:
151
152          1. abstraction, free from physical memory addresses/limits
153          2. isolation, every process in a separate address space
154          3. sharing, a single mapping can serve multiple needs
155          4. flexibility, assign a virtual address to a file
156
157       Regardless of which of these forms memory may take, all are managed  as
158       pages  (typically  4096  bytes)  but expressed by default in top as KiB
159       (kibibyte).  The memory discussed under topic `2c. MEMORY Usage'  deals
160       with  physical memory and the swap file for the system as a whole.  The
161       memory reviewed in topic `3. FIELDS /  Columns  Display'  embraces  all
162       three memory types, but for individual processes.
163
164       For  each  such  process,  every  memory page is restricted to a single
165       quadrant from the table below.  Both physical memory and virtual memory
166       can  include  any  of  the  four,  while the swap file only includes #1
167       through #3.  The memory in quadrant #4, when modified, acts as its  own
168       dedicated swap file.
169
170                                     Private | Shared
171                                 1           |          2
172            Anonymous  . stack               |
173                       . malloc()            |
174                       . brk()/sbrk()        | . POSIX shm*
175                       . mmap(PRIVATE, ANON) | . mmap(SHARED, ANON)
176                      -----------------------+----------------------
177                       . mmap(PRIVATE, fd)   | . mmap(SHARED, fd)
178          File-backed  . pgms/shared libs    |
179                                 3           |          4
180
181       The following may help in interpreting process level memory values dis‐
182       played as scalable columns and discussed under topic `3a.  DESCRIPTIONS
183       of Fields'.
184
185          %MEM - simply RES divided by total physical memory
186          CODE - the `pgms' portion of quadrant 3
187          DATA - the entire quadrant 1 portion of VIRT plus all
188                 explicit mmap file-backed pages of quadrant 3
189          RES  - anything occupying physical memory which, beginning with
190                 Linux-4.5, is the sum of the following three fields:
191                 RSan - quadrant 1 pages, which include any
192                        former quadrant 3 pages if modified
193                 RSfd - quadrant 3 and quadrant 4 pages
194                 RSsh - quadrant 2 pages
195          RSlk - subset of RES which cannot be swapped out (any quadrant)
196          SHR  - subset of RES (excludes 1, includes all 2 & 4, some 3)
197          SWAP - potentially any quadrant except 4
198          USED - simply the sum of RES and SWAP
199          VIRT - everything in-use and/or reserved (all quadrants)
200
201       Note:  Even  though  program images and shared libraries are considered
202       private to a process, they will be accounted for as shared (SHR) by the
203       kernel.
204
205

1. COMMAND-LINE Options

207       The command-line syntax for top consists of:
208
209         -hv|-bcEHiOSs1 -d secs -n max -u|U user -p pid -o fld -w [cols]
210
211       The typically mandatory switch (`-') and even whitespace are completely
212       optional.
213
214
215       -h | -v  :Help/Version
216            Show library version and the usage prompt, then quit.
217
218
219       -b  :Batch-mode operation
220            Starts top in Batch mode, which could be useful for sending output
221            from  top  to other programs or to a file.  In this mode, top will
222            not accept input and runs until the iterations  limit  you've  set
223            with the `-n' command-line option or until killed.
224
225
226       -c  :Command-line/Program-name toggle
227            Starts  top with the last remembered `c' state reversed.  Thus, if
228            top was displaying command lines, now that field will show program
229            names,  and vice versa.  See the `c' interactive command for addi‐
230            tional information.
231
232
233       -d  :Delay-time interval as:  -d ss.t (secs.tenths)
234            Specifies the delay between screen updates, and overrides the cor‐
235            responding  value  in  one's  personal  configuration  file or the
236            startup default.  Later this can be changed with the  `d'  or  `s'
237            interactive commands.
238
239            Fractional  seconds  are  honored,  but  a  negative number is not
240            allowed.  In all cases, however, such changes  are  prohibited  if
241            top  is  running  in  Secure mode, except for root (unless the `s'
242            command-line option was  used).   For  additional  information  on
243            Secure mode see topic 6d. SYSTEM Restrictions File.
244
245
246       -E  :Extend-Memory-Scaling as:  -E  k | m | g | t | p | e
247            Instructs top to force summary area memory to be scaled as:
248               k - kibibytes
249               m - mebibytes
250               g - gibibytes
251               t - tebibytes
252               p - pebibytes
253               e - exbibytes
254
255            Later this can be changed with the `E' command toggle.
256
257
258       -H  :Threads-mode operation
259            Instructs  top  to  display individual threads.  Without this com‐
260            mand-line option a summation of all threads  in  each  process  is
261            shown.   Later  this  can be changed with the `H' interactive com‐
262            mand.
263
264
265       -i  :Idle-process toggle
266            Starts top with the last remembered `i' state reversed.  When this
267            toggle  is  Off,  tasks  that have not used any CPU since the last
268            update will not be displayed.  For additional information  regard‐
269            ing this toggle see topic 4c. TASK AREA Commands, SIZE.
270
271
272       -n  :Number-of-iterations limit as:  -n number
273            Specifies  the maximum number of iterations, or frames, top should
274            produce before ending.
275
276
277       -o  :Override-sort-field as:  -o fieldname
278            Specifies the name of the field on which  tasks  will  be  sorted,
279            independent  of  what is reflected in the configuration file.  You
280            can prepend a `+' or `-' to the field name to  also  override  the
281            sort  direction.   A  leading  `+' will force sorting high to low,
282            whereas a `-' will ensure a low to high ordering.
283
284            This option exists primarily to support  automated/scripted  batch
285            mode operation.
286
287
288       -O  :Output-field-names
289            This  option  acts  as a form of help for the above -o option.  It
290            will cause top to print each of the available  field  names  on  a
291            separate line, then quit.  Such names are subject to NLS (National
292            Language Support) translation.
293
294
295       -p  :Monitor-PIDs mode as:  -pN1 -pN2 ...  or  -pN1,N2,N3 ...
296            Monitor only processes with specified process  IDs.   This  option
297            can  be given up to 20 times, or you can provide a comma delimited
298            list with up to 20 pids.  Co-mingling both approaches  is  permit‐
299            ted.
300
301            A  pid  value of zero will be treated as the process id of the top
302            program itself once it is running.
303
304            This is a command-line option only and should you wish  to  return
305            to  normal  operation, it is not necessary to quit and restart top
306             --  just issue any of these interactive  commands:  `=',  `u'  or
307            `U'.
308
309            The `p', `u' and `U' command-line options are mutually exclusive.
310
311
312       -s  :Secure-mode operation
313            Starts  top  with secure mode forced, even for root.  This mode is
314            far better controlled through a  system  configuration  file  (see
315            topic 6. FILES).
316
317
318       -S  :Cumulative-time toggle
319            Starts  top  with  the  last  remembered `S' state reversed.  When
320            Cumulative time mode is On, each process is listed  with  the  cpu
321            time  that it and its dead children have used.  See the `S' inter‐
322            active command for additional information regarding this mode.
323
324
325       -u | -U  :User-filter-mode as:  -u | -U number or name
326            Display only processes with a user id or user name  matching  that
327            given.   The  `-u'  option  matches on  effective user whereas the
328            `-U' option matches  on  any  user  (real,  effective,  saved,  or
329            filesystem).
330
331            Prepending  an  exclamation  point  (`!')  to  the user id or name
332            instructs top to display only processes with  users  not  matching
333            the one provided.
334
335            The `p', `u' and `U' command-line options are mutually exclusive.
336
337
338       -w  :Output-width-override as:  -w [ number ]
339            In  Batch mode, when used without an argument top will format out‐
340            put using the COLUMNS= and LINES= environment variables,  if  set.
341            Otherwise,  width  will be fixed at the maximum 512 columns.  With
342            an argument, output width can be decreased  or  increased  (up  to
343            512) but the number of rows is considered unlimited.
344
345            In  normal  display  mode,  when used without an argument top will
346            attempt to format output using the COLUMNS= and LINES= environment
347            variables,  if  set.   With  an argument, output width can only be
348            decreased, not increased.  Whether using environment variables  or
349            an argument with -w, when not in Batch mode actual terminal dimen‐
350            sions can never be exceeded.
351
352            Note: Without the use of this command-line option, output width is
353            always  based  on the terminal at which top was invoked whether or
354            not in Batch mode.
355
356
357       -1  :Single/Separate-Cpu-States toggle
358            Starts top with the last remembered Cpu States portion of the sum‐
359            mary  area reversed.  Either all cpu information will be displayed
360            in a single line or each cpu will be displayed separately, depend‐
361            ing on the state of the NUMA Node command toggle ('2').
362
363            See  the  `1' and '2' interactive commands for additional informa‐
364            tion.
365
366

2. SUMMARY Display

368       Each of the following three areas are individually  controlled  through
369       one  or more interactive commands.  See topic 4b. SUMMARY AREA Commands
370       for additional information regarding these provisions.
371
372
373   2a. UPTIME and LOAD Averages
374       This portion consists of a single line containing:
375           program or window name, depending on display mode
376           current time and length of time since last boot
377           total number of users
378           system load avg over the last 1, 5 and 15 minutes
379
380
381   2b. TASK and CPU States
382       This portion consists of a minimum of two lines.  In  an  SMP  environ‐
383       ment, additional lines can reflect individual CPU state percentages.
384
385       Line  1  shows  total  tasks  or threads, depending on the state of the
386       Threads-mode toggle.  That total is further classified as:
387           running; sleeping; stopped; zombie
388
389       Line 2 shows CPU state percentages based on the interval since the last
390       refresh.
391
392       As  a  default,  percentages  for  these individual categories are dis‐
393       played.  Where two labels are shown below, those for more recent kernel
394       versions are shown first.
395           us, user    : time running un-niced user processes
396           sy, system  : time running kernel processes
397           ni, nice    : time running niced user processes
398           id, idle    : time spent in the kernel idle handler
399           wa, IO-wait : time waiting for I/O completion
400           hi : time spent servicing hardware interrupts
401           si : time spent servicing software interrupts
402           st : time stolen from this vm by the hypervisor
403
404       In   the   alternate   cpu  states  display  modes,  beyond  the  first
405       tasks/threads line, an abbreviated summary is shown consisting of these
406       elements:
407                      a    b     c    d
408           %Cpu(s):  75.0/25.0  100[ ...
409
410
411       Where:  a)  is the combined us and ni percentage; b) is the sy percent‐
412       age; c) is the total; and d) is one of two visual graphs of those  rep‐
413       resentations.   See topic 4b. SUMMARY AREA Commands and the `t' command
414       for additional information on that special 4-way toggle.
415
416
417   2c. MEMORY Usage
418       This portion  consists  of  two  lines  which  may  express  values  in
419       kibibytes (KiB) through exbibytes (EiB) depending on the scaling factor
420       enforced with the `E' interactive command.
421
422       As a default, Line 1 reflects physical memory, classified as:
423           total, free, used and buff/cache
424
425       Line 2 reflects mostly virtual memory, classified as:
426           total, free, used and avail (which is physical memory)
427
428       The avail number on line 2 is an estimation of physical  memory  avail‐
429       able  for starting new applications, without swapping.  Unlike the free
430       field, it attempts to account for readily reclaimable  page  cache  and
431       memory  slabs.   It  is  available on kernels 3.14, emulated on kernels
432       2.6.27+, otherwise the same as free.
433
434       In the alternate memory display modes, two  abbreviated  summary  lines
435       are shown consisting of these elements:
436                      a    b          c
437           GiB Mem : 18.7/15.738   [ ...
438           GiB Swap:  0.0/7.999    [ ...
439
440       Where:  a) is the percentage used; b) is the total available; and c) is
441       one of two visual graphs of those representations.
442
443       In the case of physical memory, the  percentage  represents  the  total
444       minus  the  estimated  avail  noted  above.   The `Mem' graph itself is
445       divided between used and any remaining memory not  otherwise  accounted
446       for  by avail.  See topic 4b. SUMMARY AREA Commands and the `m' command
447       for additional information on that special 4-way toggle.
448
449       This table may help in interpreting the scaled values displayed:
450           KiB = kibibyte = 1024 bytes
451           MiB = mebibyte = 1024 KiB = 1,048,576 bytes
452           GiB = gibibyte = 1024 MiB = 1,073,741,824 bytes
453           TiB = tebibyte = 1024 GiB = 1,099,511,627,776 bytes
454           PiB = pebibyte = 1024 TiB = 1,125,899,906,842,624 bytes
455           EiB = exbibyte = 1024 PiB = 1,152,921,504,606,846,976 bytes
456
457

3. FIELDS / Columns

459   3a. DESCRIPTIONS of Fields
460       Listed below are top's available process fields  (columns).   They  are
461       shown  in  strict  ascii  alphabetical  order.  You may customize their
462       position and whether or not they are displayable with the  `f'  or  `F'
463       (Fields Management) interactive commands.
464
465       Any field is selectable as the sort field, and you control whether they
466       are sorted high-to-low or low-to-high.  For additional  information  on
467       sort provisions see topic 4c. TASK AREA Commands, SORTING.
468
469       The  fields  related  to  physical  memory  or virtual memory reference
470       `(KiB)' which is the unsuffixed display mode.  Such  fields  may,  how‐
471       ever,  be  scaled from KiB through PiB.  That scaling is influenced via
472       the `e' interactive command or established for startup through a  build
473       option.
474
475
476        1. %CPU  --  CPU Usage
477           The  task's  share  of  the  elapsed CPU time since the last screen
478           update, expressed as a percentage of total CPU time.
479
480           In a true SMP environment, if a process is multi-threaded  and  top
481           is  not operating in Threads mode, amounts greater than 100% may be
482           reported.  You toggle Threads mode with the  `H'  interactive  com‐
483           mand.
484
485           Also  for  multi-processor  environments,  if Irix mode is Off, top
486           will operate in Solaris mode where  a  task's  cpu  usage  will  be
487           divided by the total number of CPUs.  You toggle Irix/Solaris modes
488           with the `I' interactive command.
489
490           Note: When running in forest view mode  (`V')  with  children  col‐
491           lapsed  (`v'),  this  field will also include the CPU time of those
492           unseen children.  See topic 4c. TASK  AREA  Commands,  CONTENT  for
493           more information regarding the `V' and `v' toggles.
494
495
496        2. %MEM  --  Memory Usage (RES)
497           A task's currently resident share of available physical memory.
498
499           See `OVERVIEW, Linux Memory Types' for additional details.
500
501
502        3. CGNAME  --  Control Group Name
503           The name of the control group to which a process belongs, or `-' if
504           not applicable for that process.
505
506           This will typically be the last entry in the full list  of  control
507           groups  as  shown under the next heading (CGROUPS).  And as is true
508           there, this field is also variable width.
509
510
511        4. CGROUPS  --  Control Groups
512           The names of the control group(s) to which a  process  belongs,  or
513           `-' if not applicable for that process.
514
515           Control  Groups provide for allocating resources (cpu, memory, net‐
516           work bandwidth, etc.) among  installation-defined  groups  of  pro‐
517           cesses.  They enable fine-grained control over allocating, denying,
518           prioritizing, managing and monitoring those resources.
519
520           Many different hierarchies of cgroups can exist simultaneously on a
521           system and each hierarchy is attached to one or more subsystems.  A
522           subsystem represents a single resource.
523
524           Note: The CGROUPS field, unlike most columns, is  not  fixed-width.
525           When  displayed,  it  plus any other variable width columns will be
526           allocated all remaining screen width (up to the maximum 512 charac‐
527           ters).   Even  so,  such  variable  width fields could still suffer
528           truncation.  See topic 5c. SCROLLING a Window for additional infor‐
529           mation on accessing any truncated data.
530
531
532        5. CODE  --  Code Size (KiB)
533           The amount of physical memory currently devoted to executable code,
534           also known as the Text Resident Set size or TRS.
535
536           See `OVERVIEW, Linux Memory Types' for additional details.
537
538
539        6. COMMAND  --  Command Name or Command Line
540           Display the command line used to start a task or the  name  of  the
541           associated  program.  You toggle between command line and name with
542           `c', which is both a command-line option and  an  interactive  com‐
543           mand.
544
545           When  you've  chosen  to display command lines, processes without a
546           command line (like kernel threads) will be shown with only the pro‐
547           gram name in brackets, as in this example:
548               [kthreadd]
549
550           This  field  may  also be impacted by the forest view display mode.
551           See the `V' interactive command for additional information  regard‐
552           ing that mode.
553
554           Note:  The  COMMAND field, unlike most columns, is not fixed-width.
555           When displayed, it plus any other variable width  columns  will  be
556           allocated all remaining screen width (up to the maximum 512 charac‐
557           ters).  Even so, such variable  width  fields  could  still  suffer
558           truncation.   This  is  especially true for this field when command
559           lines are being displayed (the `c' interactive command.)  See topic
560           5c.  SCROLLING a Window for additional information on accessing any
561           truncated data.
562
563
564        7. DATA  --  Data + Stack Size (KiB)
565           The amount of private memory reserved by a  process.   It  is  also
566           known  as the Data Resident Set or DRS.  Such memory may not yet be
567           mapped to physical memory (RES) but will always be included in  the
568           virtual memory (VIRT) amount.
569
570           See `OVERVIEW, Linux Memory Types' for additional details.
571
572
573        8. ENVIRON  --  Environment variables
574           Display  all  of  the environment variables, if any, as seen by the
575           respective processes.  These variables will be displayed  in  their
576           raw native order, not the sorted order you are accustomed to seeing
577           with an unqualified `set'.
578
579           Note: The ENVIRON field, unlike most columns, is  not  fixed-width.
580           When  displayed,  it  plus any other variable width columns will be
581           allocated all remaining screen width (up to the maximum 512 charac‐
582           ters).   Even  so,  such  variable  width fields could still suffer
583           truncation.  This is especially true for this field.  See topic 5c.
584           SCROLLING  a  Window  for  additional  information on accessing any
585           truncated data.
586
587
588        9. Flags  --  Task Flags
589           This column represents the task's current  scheduling  flags  which
590           are  expressed  in  hexadecimal notation and with zeros suppressed.
591           These flags are officially documented in <linux/sched.h>.
592
593
594       10. GID  --  Group Id
595           The effective group ID.
596
597
598       11. GROUP  --  Group Name
599           The effective group name.
600
601
602       12. LXC  --  Lxc Container Name
603           The name of the lxc container within which a task is running.  If a
604           process  is  not  running  inside a container, a dash (`-') will be
605           shown.
606
607
608       13. NI  --  Nice Value
609           The nice value of the task.  A negative  nice  value  means  higher
610           priority, whereas a positive nice value means lower priority.  Zero
611           in this field simply means priority will not be adjusted in  deter‐
612           mining a task's dispatch-ability.
613
614
615       14. NU  --  Last known NUMA node
616           A  number  representing the NUMA node associated with the last used
617           processor (`P').  When -1 is displayed it means that NUMA  informa‐
618           tion is not available.
619
620           See  the `'2' and `3' interactive commands for additional NUMA pro‐
621           visions affecting the summary area.
622
623
624       15. OOMa  --  Out of Memory Adjustment Factor
625           The value, ranging from -1000 to +1000, added to the current out of
626           memory  score  (OOMs) which is then used to determine which task to
627           kill when memory is exhausted.
628
629
630       16. OOMs  --  Out of Memory Score
631           The value, ranging from 0 to +1000, used to select task(s) to  kill
632           when  memory is exhausted.  Zero translates to `never kill' whereas
633           1000 means `always kill'.
634
635
636       17. P  --  Last used CPU (SMP)
637           A number representing the last used processor.  In a true SMP envi‐
638           ronment  this will likely change frequently since the kernel inten‐
639           tionally uses weak affinity.  Also, the very act of running top may
640           break  this  weak  affinity and cause more processes to change CPUs
641           more often (because of the extra demand for cpu time).
642
643
644       18. PGRP  --  Process Group Id
645           Every process is member of a unique process group which is used for
646           distribution  of signals and by terminals to arbitrate requests for
647           their input and output.  When a process  is  created  (forked),  it
648           becomes  a  member  of the process group of its parent.  By conven‐
649           tion, this value equals the process ID (see PID) of the first  mem‐
650           ber of a process group, called the process group leader.
651
652
653       19. PID  --  Process Id
654           The  task's  unique  process  ID,  which periodically wraps, though
655           never restarting at zero.  In kernel terms, it  is  a  dispatchable
656           entity defined by a task_struct.
657
658           This  value  may  also be used as: a process group ID (see PGRP); a
659           session ID for the session leader (see SID); a thread group ID  for
660           the  thread group leader (see TGID); and a TTY process group ID for
661           the process group leader (see TPGID).
662
663
664       20. PPID  --  Parent Process Id
665           The process ID (pid) of a task's parent.
666
667
668       21. PR  --  Priority
669           The scheduling priority of the task.   If  you  see  `rt'  in  this
670           field, it means the task is running under real time scheduling pri‐
671           ority.
672
673           Under linux, real time priority is somewhat misleading since tradi‐
674           tionally  the  operating itself was not preemptible.  And while the
675           2.6 kernel can be made mostly preemptible, it is not always so.
676
677
678       22. RES  --  Resident Memory Size (KiB)
679           A subset of the virtual address space (VIRT) representing the  non-
680           swapped  physical memory a task is currently using.  It is also the
681           sum of the RSan, RSfd and RSsh fields.
682
683           It can include private anonymous pages,  private  pages  mapped  to
684           files  (including  program images and shared libraries) plus shared
685           anonymous pages.  All such memory is backed by the swap file repre‐
686           sented separately under SWAP.
687
688           Lastly, this field may also include shared file-backed pages which,
689           when modified, act as a dedicated swap file  and  thus  will  never
690           impact SWAP.
691
692           See `OVERVIEW, Linux Memory Types' for additional details.
693
694
695       23. RSan  --  Resident Anonymous Memory Size (KiB)
696           A  subset  of  resident memory (RES) representing private pages not
697           mapped to a file.
698
699
700       24. RSfd  --  Resident File-Backed Memory Size (KiB)
701           A subset of  resident  memory  (RES)  representing  the  implicitly
702           shared  pages  supporting  program images and shared libraries.  It
703           also includes explicit file mappings, both private and shared.
704
705
706       25. RSlk  --  Resident Locked Memory Size (KiB)
707           A subset of resident memory (RES) which cannot be swapped out.
708
709
710       26. RSsh  --  Resident Shared Memory Size (KiB)
711           A subset of  resident  memory  (RES)  representing  the  explicitly
712           shared anonymous shm*/mmap pages.
713
714
715       27. RUID  --  Real User Id
716           The real user ID.
717
718
719       28. RUSER  --  Real User Name
720           The real user name.
721
722
723       29. S  --  Process Status
724           The status of the task which can be one of:
725               D = uninterruptible sleep
726               I = idle
727               R = running
728               S = sleeping
729               T = stopped by job control signal
730               t = stopped by debugger during trace
731               Z = zombie
732
733           Tasks  shown as running should be more properly thought of as ready
734           to run  --  their task_struct is simply represented  on  the  Linux
735           run-queue.   Even  without a true SMP machine, you may see numerous
736           tasks in this state depending on  top's  delay  interval  and  nice
737           value.
738
739
740       30. SHR  --  Shared Memory Size (KiB)
741           A  subset  of  resident memory (RES) that may be used by other pro‐
742           cesses.  It will include shared anonymous pages  and  shared  file-
743           backed  pages.  It also includes private pages mapped to files rep‐
744           resenting program images and shared libraries.
745
746           See `OVERVIEW, Linux Memory Types' for additional details.
747
748
749       31. SID  --  Session Id
750           A session is a collection of process  groups  (see  PGRP),  usually
751           established  by  the login shell.  A newly forked process joins the
752           session of its creator.   By  convention,  this  value  equals  the
753           process ID (see PID) of the first member of the session, called the
754           session leader, which is usually the login shell.
755
756
757       32. SUID  --  Saved User Id
758           The saved user ID.
759
760
761       33. SUPGIDS  --  Supplementary Group IDs
762           The IDs of any  supplementary  group(s)  established  at  login  or
763           inherited  from  a  task's  parent.   They are displayed in a comma
764           delimited list.
765
766           Note: The SUPGIDS field, unlike most columns, is  not  fixed-width.
767           When  displayed,  it  plus any other variable width columns will be
768           allocated all remaining screen width (up to the maximum 512 charac‐
769           ters).   Even  so,  such  variable  width fields could still suffer
770           truncation.  See topic 5c. SCROLLING a Window for additional infor‐
771           mation on accessing any truncated data.
772
773
774       34. SUPGRPS  --  Supplementary Group Names
775           The  names  of  any  supplementary group(s) established at login or
776           inherited from a task's parent.  They  are  displayed  in  a  comma
777           delimited list.
778
779           Note:  The  SUPGRPS field, unlike most columns, is not fixed-width.
780           When displayed, it plus any other variable width  columns  will  be
781           allocated all remaining screen width (up to the maximum 512 charac‐
782           ters).  Even so, such variable  width  fields  could  still  suffer
783           truncation.  See topic 5c. SCROLLING a Window for additional infor‐
784           mation on accessing any truncated data.
785
786
787       35. SUSER  --  Saved User Name
788           The saved user name.
789
790
791       36. SWAP  --  Swapped Size (KiB)
792           The formerly resident portion of a task's address space written  to
793           the swap file when physical memory becomes over committed.
794
795           See `OVERVIEW, Linux Memory Types' for additional details.
796
797
798       37. TGID  --  Thread Group Id
799           The  ID of the thread group to which a task belongs.  It is the PID
800           of the thread group leader.  In kernel terms, it  represents  those
801           tasks that share an mm_struct.
802
803
804       38. TIME  --  CPU Time
805           Total CPU time the task has used since it started.  When Cumulative
806           mode is On, each process is listed with the cpu time  that  it  and
807           its  dead children have used.  You toggle Cumulative mode with `S',
808           which is both a command-line option  and  an  interactive  command.
809           See  the `S' interactive command for additional information regard‐
810           ing this mode.
811
812
813       39. TIME+  --  CPU Time, hundredths
814           The same as TIME, but  reflecting  more  granularity  through  hun‐
815           dredths of a second.
816
817
818       40. TPGID  --  Tty Process Group Id
819           The  process  group  ID of the foreground process for the connected
820           tty, or -1 if a process is not connected to a terminal.  By conven‐
821           tion,  this  value  equals  the process ID (see PID) of the process
822           group leader (see PGRP).
823
824
825       41. TTY  --  Controlling Tty
826           The name of the controlling terminal.  This is usually  the  device
827           (serial  port,  pty,  etc.) from which the process was started, and
828           which it uses for input or output.  However, a  task  need  not  be
829           associated with a terminal, in which case you'll see `?' displayed.
830
831
832       42. UID  --  User Id
833           The effective user ID of the task's owner.
834
835
836       43. USED  --  Memory in Use (KiB)
837           This  field  represents  the  non-swapped physical memory a task is
838           using (RES) plus the swapped  out  portion  of  its  address  space
839           (SWAP).
840
841           See `OVERVIEW, Linux Memory Types' for additional details.
842
843
844       44. USER  --  User Name
845           The effective user name of the task's owner.
846
847
848       45. VIRT  --  Virtual Memory Size (KiB)
849           The  total  amount of virtual memory used by the task.  It includes
850           all code, data and shared  libraries  plus  pages  that  have  been
851           swapped out and pages that have been mapped but not used.
852
853           See `OVERVIEW, Linux Memory Types' for additional details.
854
855
856       46. WCHAN  --  Sleeping in Function
857           This  field  will show the name of the kernel function in which the
858           task is currently sleeping.  Running  tasks  will  display  a  dash
859           (`-') in this column.
860
861
862       47. nDRT  --  Dirty Pages Count
863           The  number  of  pages that have been modified since they were last
864           written to auxiliary storage.  Dirty pages must be written to  aux‐
865           iliary  storage  before  the corresponding physical memory location
866           can be used for some other virtual page.
867
868           This field was deprecated with linux 2.6 and is always zero.
869
870
871       48. nMaj  --  Major Page Fault Count
872           The number of major page faults that have occurred for a  task.   A
873           page  fault occurs when a process attempts to read from or write to
874           a virtual page that is not currently present in its address  space.
875           A  major page fault is when auxiliary storage access is involved in
876           making that page available.
877
878
879       49. nMin  --  Minor Page Fault count
880           The number of minor page faults that have occurred for a  task.   A
881           page  fault occurs when a process attempts to read from or write to
882           a virtual page that is not currently present in its address  space.
883           A  minor  page  fault  does not involve auxiliary storage access in
884           making that page available.
885
886
887       50. nTH  --  Number of Threads
888           The number of threads associated with a process.
889
890
891       51. nsIPC  --  IPC namespace
892           The Inode of the namespace used to isolate interprocess  communica‐
893           tion (IPC) resources such as System V IPC objects and POSIX message
894           queues.
895
896
897       52. nsMNT  --  MNT namespace
898           The Inode of the namespace used to isolate filesystem mount  points
899           thus offering different views of the filesystem hierarchy.
900
901
902       53. nsNET  --  NET namespace
903           The  Inode  of the namespace used to isolate resources such as net‐
904           work devices, IP addresses, IP routing, port numbers, etc.
905
906
907       54. nsPID  --  PID namespace
908           The Inode of the namespace used to isolate process ID numbers mean‐
909           ing  they  need not remain unique.  Thus, each such namespace could
910           have its own `init/systemd' (PID #1) to manage various  initializa‐
911           tion tasks and reap orphaned child processes.
912
913
914       55. nsUSER  --  USER namespace
915           The  Inode  of  the namespace used to isolate the user and group ID
916           numbers.  Thus, a process could have a normal unprivileged user  ID
917           outside  a  user  namespace  while having a user ID of 0, with full
918           root privileges, inside that namespace.
919
920
921       56. nsUTS  --  UTS namespace
922           The Inode of the namespace used to isolate hostname and NIS  domain
923           name.  UTS simply means "UNIX Time-sharing System".
924
925
926       57. vMj  --  Major Page Fault Count Delta
927           The  number  of major page faults that have occurred since the last
928           update (see nMaj).
929
930
931       58. vMn  --  Minor Page Fault Count Delta
932           The number of minor page faults that have occurred since  the  last
933           update (see nMin).
934
935
936   3b. MANAGING Fields
937       After  pressing  the interactive command `f' or `F' (Fields Management)
938       you will be presented with a screen showing: 1)  the  `current'  window
939       name;  2)  the  designated  sort  field; 3) all fields in their current
940       order along with descriptions.  Entries marked with an asterisk are the
941       currently displayed fields, screen width permitting.
942
943
944           ·  As  the  on screen instructions indicate, you navigate among the
945              fields with the Up and Down arrow keys.  The  PgUp,  PgDn,  Home
946              and End keys can also be used to quickly reach the first or last
947              available field.
948
949
950           ·  The Right arrow key selects a field for  repositioning  and  the
951              Left  arrow  key  or the <Enter> key commits that field's place‐
952              ment.
953
954
955           ·  The `d' key or the <Space> bar toggles a field's display status,
956              and thus the presence or absence of the asterisk.
957
958
959           ·  The `s' key designates a field as the sort field.  See topic 4c.
960              TASK AREA Commands, SORTING for additional information regarding
961              your selection of a sort field.
962
963
964           ·  The  `a' and `w' keys can be used to cycle through all available
965              windows and the `q' or <Esc> keys exit Fields Management.
966
967
968       The Fields Management screen can also be used to change  the  `current'
969       window/field  group  in  either  full-screen  mode or alternate-display
970       mode.  Whatever was targeted when `q' or <Esc> was pressed will be made
971       current  as you return to the top display.  See topic 5. ALTERNATE-DIS‐
972       PLAY Provisions and the `g' interactive command for insight into  `cur‐
973       rent' windows and field groups.
974
975
976       Note:  Any  window that has been scrolled horizontally will be reset if
977       any field changes are made via the Fields Management screen.  Any  ver‐
978       tical  scrolled position, however, will not be affected.  See topic 5c.
979       SCROLLING a Window for additional information  regarding  vertical  and
980       horizontal scrolling.
981
982

4. INTERACTIVE Commands

984       Listed below is a brief index of commands within categories.  Some com‐
985       mands appear more than once   --   their  meaning  or  scope  may  vary
986       depending on the context in which they are issued.
987
988         4a. Global-Commands
989               <Ent/Sp> ?, =, 0,
990               A, B, d, E, e, g, h, H, I, k, q, r, s, W, X, Y, Z
991         4b. Summary-Area-Commands
992               C, l, t, m, 1, 2, 3
993         4c. Task-Area-Commands
994               Appearance:  b, J, j, x, y, z
995               Content:     c, f, F, o, O, S, u, U, V, v
996               Size:        #, i, n
997               Sorting:     <, >, f, F, R
998         4d. Color-Mapping
999               <Ret>, a, B, b, H, M, q, S, T, w, z, 0 - 7
1000         5b. Commands-for-Windows
1001               -, _, =, +, A, a, g, G, w
1002         5c. Scrolling-a-Window
1003               C, Up, Dn, Left, Right, PgUp, PgDn, Home, End
1004         5d. Searching-in-a-Window
1005               L, &
1006
1007
1008   4a. GLOBAL Commands
1009       The   global   interactive   commands  are  always  available  in  both
1010       full-screen mode and alternate-display mode.  However,  some  of  these
1011       interactive commands are not available when running in Secure mode.
1012
1013       If  you  wish  to  know  in  advance  whether  or not your top has been
1014       secured, simply ask for help and view the system summary on the  second
1015       line.
1016
1017
1018         <Enter> or <Space>  :Refresh-Display
1019              These commands awaken top and following receipt of any input the
1020              entire display will be repainted.  They also force an update  of
1021              any hotplugged cpu or physical memory changes.
1022
1023              Use  either of these keys if you have a large delay interval and
1024              wish to see current status,
1025
1026
1027          ? | h  :Help
1028              There are two help levels available.  The first will  provide  a
1029              reminder  of  all  the  basic  interactive  commands.  If top is
1030              secured, that screen will be abbreviated.
1031
1032              Typing `h' or `?' on that help screen will take you to help  for
1033              those interactive commands applicable to alternate-display mode.
1034
1035
1036          =  :Exit-Task-Limits
1037              Removes  restrictions  on  which  tasks are shown.  This command
1038              will reverse any `i' (idle tasks), `n' (max tasks) and `v' (hide
1039              children)  commands  that might be active.  It also provides for
1040              an exit from PID monitoring, User filtering, Other filtering and
1041              Locate processing.
1042
1043              Additionally,  if  the window has been scrolled it will be reset
1044              with this command.
1045
1046
1047          0  :Zero-Suppress toggle
1048              This command determines whether zeros are  shown  or  suppressed
1049              for  many of the fields in a task window.  Fields like UID, GID,
1050              NI, PR or P are not affected by this toggle.
1051
1052
1053          A  :Alternate-Display-Mode toggle
1054              This command will switch between  full-screen  mode  and  alter‐
1055              nate-display  mode.   See  topic 5. ALTERNATE-DISPLAY Provisions
1056              and the `g' interactive command for insight into `current'  win‐
1057              dows and field groups.
1058
1059
1060          B  :Bold-Disable/Enable toggle
1061              This  command will influence use of the bold terminfo capability
1062              and alters both the summary area and task area for the `current'
1063              window.  While it is intended primarily for use with dumb termi‐
1064              nals, it can be applied anytime.
1065
1066              Note: When this toggle is On and top is operating in  monochrome
1067              mode,  the  entire  display  will  appear as normal text.  Thus,
1068              unless the `x' and/or `y' toggles are using reverse  for  empha‐
1069              sis, there will be no visual confirmation that they are even on.
1070
1071
1072       *  d | s  :Change-Delay-Time-interval
1073              You  will  be  prompted  to  enter  the  delay time, in seconds,
1074              between display updates.
1075
1076              Fractional seconds are honored, but a  negative  number  is  not
1077              allowed.  Entering 0 causes (nearly) continuous updates, with an
1078              unsatisfactory display as the system and tty driver try to  keep
1079              up  with  top's  demands.   The delay value is inversely propor‐
1080              tional to system loading, so set it with care.
1081
1082              If at any time you wish to know the current delay  time,  simply
1083              ask for help and view the system summary on the second line.
1084
1085
1086          E  :Extend-Memory-Scale in Summary Area
1087              With  this  command  you can cycle through the available summary
1088              area memory scaling which ranges from KiB  (kibibytes  or  1,024
1089              bytes)   through  EiB  (exbibytes  or  1,152,921,504,606,846,976
1090              bytes).
1091
1092              If you see a `+' between a displayed number  and  the  following
1093              label,  it means that top was forced to truncate some portion of
1094              that number.  By raising the scaling factor, such truncation can
1095              be avoided.
1096
1097
1098          e  :Extend-Memory-Scale in Task Windows
1099              With  this command you can cycle through the available task win‐
1100              dow memory scaling which ranges from  KiB  (kibibytes  or  1,024
1101              bytes) through PiB (pebibytes or 1,125,899,906,842,624 bytes).
1102
1103              While  top  will  try  to honor the selected target range, addi‐
1104              tional scaling might still be necessary in order to  accommodate
1105              current values.  If you wish to see a more homogeneous result in
1106              the memory columns,  raising  the  scaling  range  will  usually
1107              accomplish  that  goal.  Raising it too high, however, is likely
1108              to produce an all zero result which cannot  be  suppressed  with
1109              the `0' interactive command.
1110
1111
1112          g  :Choose-Another-Window/Field-Group
1113              You will be prompted to enter a number between 1 and 4 designat‐
1114              ing the field group which should be made the  `current'  window.
1115              You  will soon grow comfortable with these 4 windows, especially
1116              after experimenting with alternate-display mode.
1117
1118
1119          H  :Threads-mode toggle
1120              When this toggle is On, individual threads will be displayed for
1121              all  processes in all visible task windows.  Otherwise, top dis‐
1122              plays a summation of all threads in each process.
1123
1124
1125          I  :Irix/Solaris-Mode toggle
1126              When operating in Solaris mode (`I' toggled Off), a  task's  cpu
1127              usage  will be divided by the total number of CPUs.  After issu‐
1128              ing this command, you'll be told the new state of this toggle.
1129
1130
1131       *  k  :Kill-a-task
1132              You will be prompted for a PID and then the signal to send.
1133
1134              Entering no PID or a negative number will be interpreted as  the
1135              default  shown  in the prompt (the first task displayed).  A PID
1136              value of zero means the top program itself.
1137
1138              The default signal, as reflected  in  the  prompt,  is  SIGTERM.
1139              However, you can send any signal, via number or name.
1140
1141              If  you  wish to abort the kill process, do one of the following
1142              depending on your progress:
1143                  1) at the pid prompt, type an invalid number
1144                  2) at the signal prompt, type 0 (or any invalid signal)
1145                  3) at any prompt, type <Esc>
1146
1147
1148          q  :Quit
1149
1150
1151       *  r  :Renice-a-Task
1152              You will be prompted for a PID and then the value to nice it to.
1153
1154              Entering no PID or a negative number will be interpreted as  the
1155              default  shown  in the prompt (the first task displayed).  A PID
1156              value of zero means the top program itself.
1157
1158              A positive nice value will cause a  process  to  lose  priority.
1159              Conversely,  a  negative  nice  value will cause a process to be
1160              viewed more favorably by the kernel.  As a general  rule,  ordi‐
1161              nary  users  can  only increase the nice value and are prevented
1162              from lowering it.
1163
1164              If you wish to abort the renice process, do one of the following
1165              depending on your progress:
1166                  1) at the pid prompt, type an invalid number
1167                  2) at the nice prompt, type <Enter> with no input
1168                  3) at any prompt, type <Esc>
1169
1170
1171          W  :Write-the-Configuration-File
1172              This  will save all of your options and toggles plus the current
1173              display mode and delay  time.   By  issuing  this  command  just
1174              before  quitting  top, you will be able restart later in exactly
1175              that same state.
1176
1177
1178          X  :Extra-Fixed-Width
1179              Some fields are fixed width and not scalable.  As such, they are
1180              subject  to  truncation which would be indicated by a `+' in the
1181              last position.
1182
1183              This interactive command can be used to alter the widths of  the
1184              following fields:
1185
1186                  field  default    field  default    field  default
1187                  GID       5       GROUP     8       WCHAN    10
1188                  RUID      5       LXC       8       nsIPC    10
1189                  SUID      5       RUSER     8       nsMNT    10
1190                  UID       5       SUSER     8       nsNET    10
1191                                    TTY       8       nsPID    10
1192                                    USER      8       nsUSER   10
1193                                                      nsUTS    10
1194
1195              You  will  be prompted for the amount to be added to the default
1196              widths shown above.  Entering zero  forces  a  return  to  those
1197              defaults.
1198
1199              If  you enter a negative number, top will automatically increase
1200              the column size as needed until there is no more truncated data.
1201              You  can  accelerate this process by reducing the delay interval
1202              or holding down the <Space> bar.
1203
1204              Note: Whether explicitly or automatically increased, the  widths
1205              for these fields are never decreased by top.  To narrow them you
1206              must specify a smaller number or restore the defaults.
1207
1208
1209          Y  :Inspect-Other-Output
1210              After issuing the `Y' interactive command, you will be  prompted
1211              for  a  target  PID.   Typing  a  value or accepting the default
1212              results in a separate screen.  That screen can be used to view a
1213              variety  of  files  or piped command output while the normal top
1214              iterative display is paused.
1215
1216              Note: This interactive command is only fully realized when  sup‐
1217              porting  entries  have been manually added to the end of the top
1218              configuration file.  For details on creating those entries,  see
1219              topic 6b. ADDING INSPECT Entries.
1220
1221              Most  of  the  keys  used  to  navigate  the Inspect feature are
1222              reflected in its header prologue.   There  are,  however,  addi‐
1223              tional  keys  available once you have selected a particular file
1224              or command.  They are familiar to anyone who has used the  pager
1225              `less' and are summarized here for future reference.
1226
1227                  key      function
1228                  =        alternate status-line, file or pipeline
1229                  /        find, equivalent to `L' locate
1230                  n        find next, equivalent to `&' locate next
1231                  <Space>  scroll down, equivalent to <PgDn>
1232                  b        scroll up, equivalent to <PgUp>
1233                  g        first line, equivalent to <Home>
1234                  G        last line, equivalent to <End>
1235
1236
1237          Z  :Change-Color-Mapping
1238              This key will take you to a separate screen where you can change
1239              the colors for the `current' window, or for  all  windows.   For
1240              details  regarding  this interactive command see topic 4d. COLOR
1241              Mapping.
1242
1243
1244       *  The commands shown with an  asterisk  (`*')  are  not  available  in
1245          Secure mode, nor will they be shown on the level-1 help screen.
1246
1247
1248   4b. SUMMARY AREA Commands
1249       The  summary  area  interactive  commands  are always available in both
1250       full-screen mode and alternate-display mode.  They affect the beginning
1251       lines  of  your display and will determine the position of messages and
1252       prompts.
1253
1254       These commands always impact just  the  `current'  window/field  group.
1255       See  topic 5. ALTERNATE-DISPLAY Provisions and the `g' interactive com‐
1256       mand for insight into `current' windows and field groups.
1257
1258
1259          C  :Show-scroll-coordinates toggle
1260              Toggle an informational message which is displayed whenever  the
1261              message line is not otherwise being used.  For additional infor‐
1262              mation see topic 5c. SCROLLING a Window.
1263
1264
1265          l  :Load-Average/Uptime toggle
1266              This is also the line containing the program name  (possibly  an
1267              alias)  when operating in full-screen mode or the `current' win‐
1268              dow name when operating in alternate-display mode.
1269
1270
1271          t  :Task/Cpu-States toggle
1272              This command affects from 2 to many summary area lines,  depend‐
1273              ing  on  the  state  of  the `1', `2' or `3' command toggles and
1274              whether or not top is running under true SMP.
1275
1276              This portion of the summary area is also influenced by  the  `H'
1277              interactive  command  toggle,  as  reflected  in the total label
1278              which shows either Tasks or Threads.
1279
1280              This command serves as a 4-way  toggle,  cycling  through  these
1281              modes:
1282                  1. detailed percentages by category
1283                  2. abbreviated user/system and total % + bar graph
1284                  3. abbreviated user/system and total % + block graph
1285                  4. turn off task and cpu states display
1286
1287              When  operating  in  either  of  the  graphic modes, the display
1288              becomes much more meaningful when individual CPUs or NUMA  nodes
1289              are also displayed.  See the the `1', `2' and `3' commands below
1290              for additional information.
1291
1292
1293          m  :Memory/Swap-Usage toggle
1294              This command affects the two summary  area  lines  dealing  with
1295              physical and virtual memory.
1296
1297              This  command  serves  as  a 4-way toggle, cycling through these
1298              modes:
1299                  1. detailed percentages by memory type
1300                  2. abbreviated % used/total available + bar graph
1301                  3. abbreviated % used/total available + block graph
1302                  4. turn off memory display
1303
1304
1305          1  :Single/Separate-Cpu-States toggle
1306              This command affects how the `t' command's Cpu States portion is
1307              shown.   Although  this  toggle  exists  primarily to serve mas‐
1308              sively-parallel SMP machines, it is not restricted to solely SMP
1309              environments.
1310
1311              When  you  see `%Cpu(s):' in the summary area, the `1' toggle is
1312              On and all cpu information is gathered in a single line.  Other‐
1313              wise,  each  cpu is displayed separately as: `%Cpu0, %Cpu1, ...'
1314              up to available screen height.
1315
1316
1317          2  :NUMA-Nodes/Cpu-Summary toggle
1318              This command toggles between the `1' command cpu summary display
1319              (only)  or  a  summary display plus the cpu usage statistics for
1320              each NUMA Node.  It is only available if a system has the requi‐
1321              site NUMA support.
1322
1323
1324          3  :Expand-NUMA-Node
1325              You  will be invited to enter a number representing a NUMA Node.
1326              Thereafter, a node summary plus the statistics for each  cpu  in
1327              that node will be shown until either the `1' or `2' command tog‐
1328              gle is pressed.  This interactive command is only available if a
1329              system has the requisite NUMA support.
1330
1331
1332       Note:  If  the entire summary area has been toggled Off for any window,
1333       you would be left with just the message line.  In that  way,  you  will
1334       have  maximized  available  task  rows but (temporarily) sacrificed the
1335       program name in full-screen mode or the `current' window name  when  in
1336       alternate-display mode.
1337
1338
1339   4c. TASK AREA Commands
1340       The  task area interactive commands are always available in full-screen
1341       mode.
1342
1343       The task area  interactive  commands  are  never  available  in  alter‐
1344       nate-display  mode if the `current' window's task display has been tog‐
1345       gled Off (see topic 5. ALTERNATE-DISPLAY Provisions).
1346
1347
1348       APPEARANCE of task window
1349
1350
1351          J  :Justify-Numeric-Columns toggle
1352              Alternates between right-justified (the default) and left-justi‐
1353              fied  numeric  data.   If  the numeric data completely fills the
1354              available column, this command  toggle  may  impact  the  column
1355              header only.
1356
1357
1358          j  :Justify-Character-Columns toggle
1359              Alternates between left-justified (the default) and right-justi‐
1360              fied character data.  If the character data completely fills the
1361              available  column,  this  command  toggle  may impact the column
1362              header only.
1363
1364
1365         The following commands will also be influenced by the  state  of  the
1366         global `B' (bold enable) toggle.
1367
1368
1369          b  :Bold/Reverse toggle
1370              This  command  will  impact how the `x' and `y' toggles are dis‐
1371              played.  It may also impact the summary area when  a  bar  graph
1372              has  been selected for cpu states or memory usage via the `t' or
1373              `m' toggles.
1374
1375
1376          x  :Column-Highlight toggle
1377              Changes highlighting for the current sort field.  If you  forget
1378              which  field  is  being sorted this command can serve as a quick
1379              visual reminder, providing the sort field  is  being  displayed.
1380              The sort field might not be visible because:
1381                  1) there is insufficient Screen Width
1382                  2) the `f' interactive command turned it Off
1383
1384              Note:  Whenever  Searching and/or Other Filtering is active in a
1385              window, column highlighting is temporarily  disabled.   See  the
1386              notes  at  the end of topics 5d. SEARCHING and 5e. FILTERING for
1387              an explanation why.
1388
1389
1390          y  :Row-Highlight toggle
1391              Changes  highlighting  for  "running"  tasks.   For   additional
1392              insight  into  this  task  state,  see topic 3a. DESCRIPTIONS of
1393              Fields, the `S' field (Process Status).
1394
1395              Use of this provision provides important insight into your  sys‐
1396              tem's  health.   The  only  costs  will  be a few additional tty
1397              escape sequences.
1398
1399
1400          z  :Color/Monochrome toggle
1401              Switches the `current'  window  between  your  last  used  color
1402              scheme  and  the older form of black-on-white or white-on-black.
1403              This command will alter both the summary area and task area  but
1404              does not affect the state of the `x', `y' or `b' toggles.
1405
1406
1407       CONTENT of task window
1408
1409
1410          c  :Command-Line/Program-Name toggle
1411              This  command  will be honored whether or not the COMMAND column
1412              is currently visible.  Later, should that field come into  view,
1413              the change you applied will be seen.
1414
1415
1416          f | F  :Fields-Management
1417              These  keys display a separate screen where you can change which
1418              fields are displayed, their order and also  designate  the  sort
1419              field.  For additional information on these interactive commands
1420              see topic 3b. MANAGING Fields.
1421
1422
1423          o | O  :Other-Filtering
1424              You will be prompted  for  the  selection  criteria  which  then
1425              determines  which  tasks  will be shown in the `current' window.
1426              Your criteria can be made case sensitive or case can be ignored.
1427              And  you  determine  if  top  should include or exclude matching
1428              tasks.
1429
1430              See topic 5e. FILTERING in a window for  details  on  these  and
1431              additional related interactive commands.
1432
1433
1434          S  :Cumulative-Time-Mode toggle
1435              When  Cumulative mode is On, each process is listed with the cpu
1436              time that it and its dead children have used.
1437
1438              When Off, programs that  fork  into  many  separate  tasks  will
1439              appear less demanding.  For programs like `init' or a shell this
1440              is appropriate but for  others,  like  compilers,  perhaps  not.
1441              Experiment with two task windows sharing the same sort field but
1442              with different `S' states and see which representation you  pre‐
1443              fer.
1444
1445              After  issuing this command, you'll be informed of the new state
1446              of this toggle.  If you wish to know in advance whether  or  not
1447              Cumulative  mode  is in effect, simply ask for help and view the
1448              window summary on the second line.
1449
1450
1451          u | U  :Show-Specific-User-Only
1452              You will be prompted for the uid or name of the user to display.
1453              The  -u  option matches on  effective user whereas the -U option
1454              matches on any user (real, effective, saved, or filesystem).
1455
1456              Thereafter, in that task window  only  matching  users  will  be
1457              shown,  or  possibly  no processes will be shown.  Prepending an
1458              exclamation point (`!') to the user id or name instructs top  to
1459              display only processes with users not matching the one provided.
1460
1461              Different  task  windows  can be used to filter different users.
1462              Later, if you wish to monitor all users again in  the  `current'
1463              window,  re-issue  this  command  but  just press <Enter> at the
1464              prompt.
1465
1466
1467          V  :Forest-View-Mode toggle
1468              In this mode, processes are reordered according to their parents
1469              and  the  layout of the COMMAND column resembles that of a tree.
1470              In forest view mode it is still possible to toggle between  pro‐
1471              gram  name and command line (see the `c' interactive command) or
1472              between processes and threads (see the `H' interactive command).
1473
1474              Note: Typing any key affecting the sort order will  exit  forest
1475              view mode in the `current' window.  See topic 4c. TASK AREA Com‐
1476              mands, SORTING for information on those keys.
1477
1478
1479          v  :Hide/Show-Children toggle
1480              When in forest view mode, this key serves as a  toggle  to  col‐
1481              lapse or expand the children of a parent.
1482
1483              The toggle is applied against the first (topmost) process in the
1484              `current' window.  See topic 5c. SCROLLING a  Window  for  addi‐
1485              tional information regarding vertical scrolling.
1486
1487              If  the target process has not forked any children, this key has
1488              no effect.  It also has no effect when not in forest view mode.
1489
1490
1491       SIZE of task window
1492
1493
1494          i  :Idle-Process toggle
1495              Displays all tasks or just active tasks.  When  this  toggle  is
1496              Off, tasks that have not used any CPU since the last update will
1497              not be displayed.  However, due to the granularity of  the  %CPU
1498              and  TIME+  fields,  some  processes may still be displayed that
1499              appear to have used no CPU.
1500
1501              If this command is applied to the  last  task  display  when  in
1502              alternate-display  mode,  then  it  will not affect the window's
1503              size, as all prior task displays will have already been painted.
1504
1505
1506          n | #  :Set-Maximum-Tasks
1507              You will be prompted to enter the number of  tasks  to  display.
1508              The  lessor  of  your  number  and available screen rows will be
1509              used.
1510
1511              When used in alternate-display mode, this is  the  command  that
1512              gives  you precise control over the size of each currently visi‐
1513              ble task display, except for the very last.  It will not  affect
1514              the  last  window's  size,  as all prior task displays will have
1515              already been painted.
1516
1517              Note: If you wish to increase the size of the last visible  task
1518              display when in alternate-display mode, simply decrease the size
1519              of the task display(s) above it.
1520
1521       SORTING of task window
1522
1523          For compatibility, this top supports most of  the  former  top  sort
1524          keys.   Since this is primarily a service to former top users, these
1525          commands do not appear on any help screen.
1526                command   sorted-field                  supported
1527                A         start time (non-display)      No
1528                M         %MEM                          Yes
1529                N         PID                           Yes
1530                P         %CPU                          Yes
1531                T         TIME+                         Yes
1532
1533          Before using any of the following sort provisions, top suggests that
1534          you  temporarily  turn on column highlighting using the `x' interac‐
1535          tive command.  That will help ensure that the actual  sort  environ‐
1536          ment matches your intent.
1537
1538          The  following  interactive  commands  will only be honored when the
1539          current sort field is visible.  The sort field might not be  visible
1540          because:
1541                1) there is insufficient Screen Width
1542                2) the `f' interactive command turned it Off
1543
1544
1545             <  :Move-Sort-Field-Left
1546                 Moves  the  sort  column  to the left unless the current sort
1547                 field is the first field being displayed.
1548
1549
1550             >  :Move-Sort-Field-Right
1551                 Moves the sort column to the right unless  the  current  sort
1552                 field is the last field being displayed.
1553
1554
1555          The following interactive commands will always be honored whether or
1556          not the current sort field is visible.
1557
1558
1559             f | F  :Fields-Management
1560                 These keys display a separate screen  where  you  can  change
1561                 which  field  is  used  as the sort column, among other func‐
1562                 tions.  This can be a convenient way  to  simply  verify  the
1563                 current sort field, when running top with column highlighting
1564                 turned Off.
1565
1566
1567             R  :Reverse/Normal-Sort-Field toggle
1568                 Using this interactive  command  you  can  alternate  between
1569                 high-to-low and low-to-high sorts.
1570
1571
1572          Note:  Field  sorting uses internal values, not those in column dis‐
1573          play.  Thus, the TTY and WCHAN fields will violate strict ASCII col‐
1574          lating sequence.
1575
1576
1577   4d. COLOR Mapping
1578       When  you issue the `Z' interactive command, you will be presented with
1579       a separate screen.  That screen can be used to  change  the  colors  in
1580       just  the  `current'  window or in all four windows before returning to
1581       the top display.
1582
1583
1584       The following interactive commands are available.
1585           4 upper case letters to select a target
1586           8 numbers to select a color
1587           normal toggles available
1588               B         :bold disable/enable
1589               b         :running tasks "bold"/reverse
1590               z         :color/mono
1591           other commands available
1592               a/w       :apply, then go to next/prior
1593               <Enter>   :apply and exit
1594               q         :abandon current changes and exit
1595
1596       If you use `a' or `w' to cycle  the  targeted  window,  you  will  have
1597       applied  the color scheme that was displayed when you left that window.
1598       You can, of course, easily return to any window and  reapply  different
1599       colors or turn colors Off completely with the `z' toggle.
1600
1601       The  Color Mapping screen can also be used to change the `current' win‐
1602       dow/field group in either full-screen mode or  alternate-display  mode.
1603       Whatever was targeted when `q' or <Enter> was pressed will be made cur‐
1604       rent as you return to the top display.
1605

5. ALTERNATE-DISPLAY Provisions

1607   5a. WINDOWS Overview
1608       Field Groups/Windows:
1609          In full-screen mode there is a  single  window  represented  by  the
1610          entire screen.  That single window can still be changed to display 1
1611          of 4 different  field  groups  (see  the  `g'  interactive  command,
1612          repeated below).  Each of the 4 field groups has a unique separately
1613          configurable summary area and its own configurable task area.
1614
1615          In alternate-display mode, those 4 underlying field groups  can  now
1616          be made visible simultaneously, or can be turned Off individually at
1617          your command.
1618
1619          The summary area will always exist, even if it's  only  the  message
1620          line.   At  any  given  time only one summary area can be displayed.
1621          However, depending on your commands, there could  be  from  zero  to
1622          four separate task displays currently showing on the screen.
1623
1624       Current Window:
1625          The  `current' window is the window associated with the summary area
1626          and the window to which task related commands are  always  directed.
1627          Since in alternate-display mode you can toggle the task display Off,
1628          some commands might be restricted for the `current' window.
1629
1630          A further complication arises when you have toggled the  first  sum‐
1631          mary  area line Off.  With the loss of the window name (the `l' tog‐
1632          gled line), you'll not easily know what window is the `current' win‐
1633          dow.
1634
1635
1636   5b. COMMANDS for Windows
1637          - | _  :Show/Hide-Window(s) toggles
1638              The  `-'  key  turns  the `current' window's task display On and
1639              Off.  When On, that task area will show a minimum of the columns
1640              header  you've established with the `f' interactive command.  It
1641              will also reflect any other  task  area  options/toggles  you've
1642              applied yielding zero or more tasks.
1643
1644              The  `_'  key  does  the  same  for all task displays.  In other
1645              words, it switches between the currently visible task display(s)
1646              and any task display(s) you had toggled Off.  If all 4 task dis‐
1647              plays are currently visible, this interactive command will leave
1648              the summary area as the only display element.
1649
1650
1651       *  = | +  :Equalize-(reinitialize)-Window(s)
1652              The  `='  key  forces  the `current' window's task display to be
1653              visible.  It also reverses any active `i' (idle tasks), `n' (max
1654              tasks),  `u/U'  (user  filter),  `o/O' (other filter), `v' (hide
1655              children) and 'L' (locate) commands.  Also, if  the  window  had
1656              been  scrolled,  it  will be reset with this command.  See topic
1657              5c. SCROLLING a Window for additional information regarding ver‐
1658              tical and horizontal scrolling.
1659
1660              The  `+'  key does the same for all windows.  The four task dis‐
1661              plays will reappear,  evenly  balanced.   They  will  also  have
1662              retained  any  customizations you had previously applied, except
1663              for the `i' (idle tasks), `n' (max tasks), `u/U' (user  filter),
1664              `o/O'  (other  filter),  `v'  (hide  children), `L' (locate) and
1665              scrolling interactive commands.
1666
1667
1668       *  A  :Alternate-Display-Mode toggle
1669              This command will switch between  full-screen  mode  and  alter‐
1670              nate-display mode.
1671
1672              The  first  time  you issue this command, all four task displays
1673              will be shown.  Thereafter when you switch modes, you  will  see
1674              only the task display(s) you've chosen to make visible.
1675
1676
1677       *  a | w  :Next-Window-Forward/Backward
1678              This will change the `current' window, which in turn changes the
1679              window to which commands are directed.  These keys act in a cir‐
1680              cular  fashion  so you can reach any desired window using either
1681              key.
1682
1683              Assuming the window name is visible (you have  not  toggled  `l'
1684              Off),  whenever  the  `current'  window  name  loses  its empha‐
1685              sis/color, that's a reminder the task display is  Off  and  many
1686              commands will be restricted.
1687
1688
1689       *  g  :Choose-Another-Window/Field-Group
1690              You will be prompted to enter a number between 1 and 4 designat‐
1691              ing the field group which should be made the `current' window.
1692
1693              In full-screen mode, this command  is  necessary  to  alter  the
1694              `current'  window.   In  alternate-display  mode, it is simply a
1695              less convenient alternative to the `a' and `w' commands.
1696
1697
1698          G  :Change-Window/Field-Group-Name
1699              You will be prompted for a new name to be applied to  the  `cur‐
1700              rent' window.  It does not require that the window name be visi‐
1701              ble (the `l' toggle to be On).
1702
1703
1704       *  The interactive commands shown  with  an  asterisk  (`*')  have  use
1705          beyond alternate-display mode.
1706              =, A, g    are always available
1707              a, w       act the same with color mapping
1708                         and fields management
1709
1710
1711   5c. SCROLLING a Window
1712       Typically  a  task  window  is  a  partial  view into a systems's total
1713       tasks/threads which shows only some of  the  available  fields/columns.
1714       With  these  scrolling keys, you can move that view vertically or hori‐
1715       zontally to reveal any desired task or column.
1716
1717
1718       Up,PgUp  :Scroll-Tasks
1719           Move the view up toward the first task row, until the first task is
1720           displayed  at  the  top  of the `current' window.  The Up arrow key
1721           moves a single line while PgUp scrolls the entire window.
1722
1723
1724       Down,PgDn  :Scroll-Tasks
1725           Move the view down toward the last task row, until the last task is
1726           the  only  task  displayed at the top of the `current' window.  The
1727           Down arrow key moves a single line while PgDn  scrolls  the  entire
1728           window.
1729
1730
1731       Left,Right  :Scroll-Columns
1732           Move  the  view  of displayable fields horizontally one column at a
1733           time.
1734
1735           Note: As a reminder, some fields/columns are  not  fixed-width  but
1736           allocated  all remaining screen width when visible.  When scrolling
1737           right or left, that feature may  produce  some  unexpected  results
1738           initially.
1739
1740           Additionally,  there  are special provisions for any variable width
1741           field when positioned as the last displayed field.  Once that field
1742           is  reached  via  the  right arrow key, and is thus the only column
1743           shown, you can continue scrolling horizontally within such a field.
1744           See the `C' interactive command below for additional information.
1745
1746
1747       Home  :Jump-to-Home-Position
1748           Reposition the display to the un-scrolled coordinates.
1749
1750
1751       End  :Jump-to-End-Position
1752           Reposition  the  display  so that the rightmost column reflects the
1753           last displayable field and the bottom task row represents the  last
1754           task.
1755
1756           Note:  From  this  position it is still possible to scroll down and
1757           right using the arrow keys.  This is true until a single column and
1758           a single task is left as the only display element.
1759
1760
1761       C  :Show-scroll-coordinates toggle
1762           Toggle  an  informational  message  which is displayed whenever the
1763           message line is not otherwise being used.  That message  will  take
1764           one  of two forms depending on whether or not a variable width col‐
1765           umn has also been scrolled.
1766
1767             scroll coordinates: y = n/n (tasks), x = n/n (fields)
1768             scroll coordinates: y = n/n (tasks), x = n/n (fields) + nn
1769
1770           The coordinates shown as n/n are relative to the upper left  corner
1771           of the `current' window.  The additional `+ nn' represents the dis‐
1772           placement into a variable width column when it  has  been  scrolled
1773           horizontally.   Such  displacement occurs in normal 8 character tab
1774           stop amounts via the right and left arrow keys.
1775
1776
1777           y = n/n (tasks)
1778               The first n represents the topmost visible  task  and  is  con‐
1779               trolled  by  scrolling keys.  The second n is updated automati‐
1780               cally to reflect total tasks.
1781
1782
1783           x = n/n (fields)
1784               The first n represents the leftmost  displayed  column  and  is
1785               controlled by scrolling keys.  The second n is the total number
1786               of displayable fields and is established with the `f'  interac‐
1787               tive command.
1788
1789
1790       The above interactive commands are always available in full-screen mode
1791       but never available in alternate-display mode if the `current' window's
1792       task display has been toggled Off.
1793
1794       Note:  When any form of filtering is active, you can expect some slight
1795       aberrations when scrolling since not all tasks will be  visible.   This
1796       is particularly apparent when using the Up/Down arrow keys.
1797
1798
1799   5d. SEARCHING in a Window
1800       You  can use these interactive commands to locate a task row containing
1801       a particular value.
1802
1803
1804       L  :Locate-a-string
1805           You will be prompted for the case-sensitive string to locate start‐
1806           ing from the current window coordinates.  There are no restrictions
1807           on search string content.
1808
1809           Searches are not limited to values from a single field  or  column.
1810           All  of  the values displayed in a task row are allowed in a search
1811           string.  You may include spaces, numbers, symbols and  even  forest
1812           view artwork.
1813
1814           Keying  <Enter>  with no input will effectively disable the `&' key
1815           until a new search string is entered.
1816
1817
1818       &  :Locate-next
1819           Assuming a search string has been established, top will attempt  to
1820           locate the next occurrence.
1821
1822
1823       When a match is found, the current window is repositioned vertically so
1824       the task row containing that string is first.  The  scroll  coordinates
1825       message  can  provide  confirmation of such vertical repositioning (see
1826       the `C' interactive command).  Horizontal scrolling, however, is  never
1827       altered via searching.
1828
1829       The availability of a matching string will be influenced by the follow‐
1830       ing factors.
1831
1832          a. Which fields are displayable from the total available,
1833             see topic 3b. MANAGING Fields.
1834
1835          b. Scrolling a window vertically and/or horizontally,
1836             see topic 5c. SCROLLING a Window.
1837
1838          c. The state of the command/command-line toggle,
1839             see the `c' interactive command.
1840
1841          d. The stability of the chosen sort column,
1842             for example PID is good but %CPU bad.
1843
1844
1845       If a search fails, restoring the  `current'  window  home  (unscrolled)
1846       position,  scrolling horizontally, displaying command-lines or choosing
1847       a more stable sort field could yet produce a successful `&' search.
1848
1849       The above interactive commands are always available in full-screen mode
1850       but never available in alternate-display mode if the `current' window's
1851       task display has been toggled Off.
1852
1853       Note: Whenever a Search is active in a window,  top  will  turn  column
1854       highlighting  Off  to  prevent  false  matches  on internal non-display
1855       escape sequences.  Such highlighting will be restored when  a  window's
1856       search string is empty.  See the `x' interactive command for additional
1857       information on sort column highlighting.
1858
1859
1860   5e. FILTERING in a Window
1861       You can use this `Other Filter' feature to establish selection criteria
1862       which  will  then determine which tasks are shown in the `current' win‐
1863       dow.  Such filters can be made presistent if preserved  in  the  rcfile
1864       via the 'W' interactive command.
1865
1866       Establishing a filter requires: 1) a field name; 2) an operator; and 3)
1867       a selection value, as a minimum.  This is the  most  complex  of  top's
1868       user  input  requirements  so,  when you make a mistake, command recall
1869       will be your friend.  Remember the Up/Down arrow keys or their  aliases
1870       when prompted for input.
1871
1872       Filter Basics
1873
1874          1. field names are case sensitive and spelled as in the header
1875
1876          2. selection values need not comprise the full displayed field
1877
1878          3. a selection is either case insensitive or sensitive to case
1879
1880          4. the default is inclusion, prepending `!' denotes exclusions
1881
1882          5. multiple selection criteria can be applied to a task window
1883
1884          6. inclusion and exclusion criteria can be used simultaneously
1885
1886          7. the 1 equality and 2 relational filters can be freely mixed
1887
1888          8. separate unique filters are maintained for each task window
1889
1890          If  a  field is not turned on or is not currently in view, then your
1891          selection criteria will not affect the  display.   Later,  should  a
1892          filtered  field  become visible, the selection criteria will then be
1893          applied.
1894
1895       Keyboard Summary
1896
1897         o  :Other-Filter (lower case)
1898             You will be prompted to establish a filter that ignores case when
1899             matching.
1900
1901
1902         O  :Other-Filter (upper case)
1903             You will be prompted to establish a case sensitive filter.
1904
1905
1906        ^O  :Show-Active-Filters (Ctrl key + `o')
1907             This  can  serve as a reminder of which filters are active in the
1908             `current' window.  A summary will be shown on  the  message  line
1909             until you press the <Enter> key.
1910
1911
1912         =  :Reset-Filtering in current window
1913             This  clears all of your selection criteria in the `current' win‐
1914             dow.  It also has additional  impact  so  please  see  topic  4a.
1915             GLOBAL Commands.
1916
1917
1918         +  :Reset-Filtering in all windows
1919             This  clears  the selection criteria in all windows, assuming you
1920             are in alternate-display mode.  As with the `=' interactive  com‐
1921             mand, it too has additional consequences so you might wish to see
1922             topic 5b. COMMANDS for Windows.
1923
1924       Input Requirements
1925
1926          When prompted for selection criteria, the data you provide must take
1927          one  of two forms.  There are 3 required pieces of information, with
1928          a 4th as optional.  These examples use spaces for clarity  but  your
1929          input generally would not.
1930                  #1           #2  #3              ( required )
1931                  Field-Name   ?   include-if-value
1932               !  Field-Name   ?   exclude-if-value
1933               #4                                  ( optional )
1934
1935          Items  #1, #3 and #4 should be self-explanatory.  Item #2 represents
1936          both a required delimiter and the operator  which  must  be  one  of
1937          either equality (`=') or relation (`<' or `>').
1938
1939          The `=' equality operator requires only a partial match and that can
1940          reduce your `if-value' input requirements.  The  `>'  or  `<'  rela‐
1941          tional operators always employ string comparisons, even with numeric
1942          fields.  They are designed to work with a field's default justifica‐
1943          tion  and  with homogeneous data.  When some field's numeric amounts
1944          have been subjected to scaling while others have not, that  data  is
1945          no longer homogeneous.
1946
1947          If  you  establish  a  relational  filter  and  you have changed the
1948          default Numeric or Character justification, that filter is likely to
1949          fail.  When a relational filter is applied to a memory field and you
1950          have not changed the scaling, it  may  produce  misleading  results.
1951          This  happens,  for  example,  because  `100.0m'  (MiB) would appear
1952          greater than `1.000g' (GiB) when compared as strings.
1953
1954          If your filtered results appear suspect, simply altering  justifica‐
1955          tion or scaling may yet achieve the desired objective.  See the `j',
1956          `J' and `e' interactive commands for additional information.
1957
1958       Potential Problems
1959
1960          These GROUP filters could produce the exact same results or the sec‐
1961          ond one might not display anything at all, just a blank task window.
1962               GROUP=root        ( only the same results when )
1963               GROUP=ROOT        ( invoked via lower case `o' )
1964
1965          Either of these RES filters might yield inconsistent and/or mislead‐
1966          ing results, depending on the current  memory  scaling  factor.   Or
1967          both filters could produce the exact same results.
1968               RES>9999          ( only the same results when )
1969               !RES<10000        ( memory scaling is at `KiB' )
1970
1971          This  nMin  filter  illustrates a problem unique to scalable fields.
1972          This particular field can display a  maximum  of  4  digits,  beyond
1973          which  values  are  automatically  scaled to KiB or above.  So while
1974          amounts greater than 9999 exist, they will  appear  as  2.6m,  197k,
1975          etc.
1976               nMin>9999         ( always a blank task window )
1977
1978       Potential Solutions
1979
1980          These  examples  illustrate  how  Other  Filtering can be creatively
1981          applied to achieve almost any desired  result.   Single  quotes  are
1982          sometimes  shown to delimit the spaces which are part of a filter or
1983          to represent a request for status (^O) accurately.  But if you  used
1984          them with if-values in real life, no matches would be found.
1985
1986          Assuming  field  nTH  is  displayed, the first filter will result in
1987          only multi-threaded processes being shown.  It also reminds us  that
1988          a  trailing space is part of every displayed field.  The second fil‐
1989          ter achieves the exact same results with less typing.
1990               !nTH=` 1 '                ( ' for clarity only )
1991               nTH>1                     ( same with less i/p )
1992
1993          With Forest View mode active and the COMMAND column  in  view,  this
1994          filter  effectively  collapses child processes so that just 3 levels
1995          are shown.
1996               !COMMAND=`       `- '     ( ' for clarity only )
1997
1998          The final two filters appear as in response to  the  status  request
1999          key  (^O).   In  reality,  each  filter would have required separate
2000          input.  The PR example shows the two concurrent filters necessary to
2001          display  tasks  with  priorities  of 20 or more, since some might be
2002          negative.  Then by exploiting trailing spaces, the  nMin  series  of
2003          filters could achieve the failed `9999' objective discussed above.
2004               `PR>20' + `!PR=-'         ( 2 for right result )
2005               `!nMin=0 ' + `!nMin=1 ' + `!nMin=2 ' + `!nMin=3 ' ...
2006
2007       Note:  Whenever  Other  Filtering  is active in a window, top will turn
2008       column highlighting Off to prevent false matches on  internal  non-dis‐
2009       play  escape sequences.  Such highlighting will be restored when a win‐
2010       dow is no longer subject to filtering.  See the `x' interactive command
2011       for additional information on sort column highlighting.
2012
2013

6. FILES

2015   6a. PERSONAL Configuration File
2016       This file is created or updated via the 'W' interactive command.
2017
2018       The legacy version is written as `$HOME/.your-name-4-top' + `rc' with a
2019       leading period.
2020
2021       A    newly    created    configuration    file    is     written     as
2022       procps/your-name-4-top'  +  `rc'  without a leading period.  The procps
2023       directory will be subordinate to either $XDG_CONFIG_HOME when set as an
2024       absolute path or the $HOME/.config directory.
2025
2026       While not intended to be edited manually, here is the general layout:
2027           global   # line  1: the program name/alias notation
2028             "      # line  2: id,altscr,irixps,delay,curwin
2029           per ea   # line  a: winname,fieldscur
2030           window   # line  b: winflags,sortindx,maxtasks,graph modes
2031             "      # line  c: summclr,msgsclr,headclr,taskclr
2032           global   # line 15: additional miscellaneous settings
2033             "      # any remaining lines are devoted to optional
2034             "      # active 'other filters' discussed in section 5e above
2035             "      # plus 'inspect' entries discussed in section 6b below
2036
2037       If  a  valid  absolute  path  to the rcfile cannot be established, cus‐
2038       tomizations made to a running top will be impossible to preserve.
2039
2040
2041   6b. ADDING INSPECT Entries
2042       To exploit the `Y' interactive command, you must add entries at the end
2043       of  the top personal configuration file.  Such entries simply reflect a
2044       file to be read or command/pipeline to be executed whose  results  will
2045       then be displayed in a separate scrollable, searchable window.
2046
2047       If  you don't know the location or name of your top rcfile, use the `W'
2048       interactive command to rewrite it and note those details.
2049
2050       Inspect entries can be added with a redirected echo or by  editing  the
2051       configuration  file.   Redirecting an echo risks overwriting the rcfile
2052       should it replace (>) rather than  append  (>>)  to  that  file.   Con‐
2053       versely,  when using an editor care must be taken not to corrupt exist‐
2054       ing lines, some of which will contain unprintable data or unusual char‐
2055       acters.
2056
2057       Those  Inspect  entries  beginning  with  a  `#' character are ignored,
2058       regardless of content.  Otherwise they consist of the following 3  ele‐
2059       ments,  each of which must be separated by a tab character (thus 2 `\t'
2060       total):
2061
2062         .type:  literal `file' or `pipe'
2063         .name:  selection shown on the Inspect screen
2064         .fmts:  string representing a path or command
2065
2066       The two types of Inspect entries are not interchangeable.  Those desig‐
2067       nated  `file'  will be accessed using fopen and must reference a single
2068       file in the `.fmts' element.  Entries  specifying  `pipe'  will  employ
2069       popen, their `.fmts' element could contain many pipelined commands and,
2070       none can be interactive.
2071
2072       If the file or pipeline represented in your `.fmts' deals with the spe‐
2073       cific  PID input or accepted when prompted, then the format string must
2074       also contain the `%d' specifier, as these examples illustrate.
2075
2076         .fmts=  /proc/%d/numa_maps
2077         .fmts=  lsof -P -p %d
2078
2079       For `pipe' type entries only, you may also wish to redirect  stderr  to
2080       stdout  for  a  more  comprehensive  result.   Thus  the  format string
2081       becomes:
2082
2083         .fmts=  pmap -x %d 2>&1
2084
2085       Here are examples of both types of Inspect entries as they might appear
2086       in  the rcfile.  The first entry will be ignored due to the initial `#'
2087       character.  For clarity, the pseudo tab depictions (^I) are  surrounded
2088       by an extra space but the actual tabs would not be.
2089
2090         # pipe ^I Sockets ^I lsof -n -P -i 2>&1
2091         pipe ^I Open Files ^I lsof -P -p %d 2>&1
2092         file ^I NUMA Info ^I /proc/%d/numa_maps
2093         pipe ^I Log ^I tail -n100 /var/log/syslog | sort -Mr
2094
2095       Except  for  the  commented  entry above, these next examples show what
2096       could be echoed to achieve similar results, assuming  the  rcfile  name
2097       was  `.toprc'.   However,  due  to the embedded tab characters, each of
2098       these lines should be preceded by `/bin/echo -e', not just a simple  an
2099       `echo',  to  enable  backslash interpretation regardless of which shell
2100       you use.
2101
2102         "pipe\tOpen Files\tlsof -P -p %d 2>&1" >> ~/.toprc
2103         "file\tNUMA Info\t/proc/%d/numa_maps" >> ~/.toprc
2104         "pipe\tLog\ttail -n200 /var/log/syslog | sort -Mr" >> ~/.toprc
2105
2106       If any inspect entry you create produces output with unprintable  char‐
2107       acters  they will be displayed in either the ^C notation or hexadecimal
2108       <FF> form, depending on their value.  This applies to tab characters as
2109       well, which will show as `^I'.  If you want a truer representation, any
2110       embedded tabs should be expanded.  The  following  example  takes  what
2111       could  have  been  a `file' entry but employs a `pipe' instead so as to
2112       expand the embedded tabs.
2113
2114         # next would have contained `\t' ...
2115         # file ^I <your_name> ^I /proc/%d/status
2116         # but this will eliminate embedded `\t' ...
2117         pipe ^I <your_name> ^I cat /proc/%d/status | expand -
2118
2119       Note: Some programs might rely on  SIGINT  to  end.   Therefore,  if  a
2120       `pipe'  such  as  the  following is established, one must use Ctrl-C to
2121       terminate it in order to review the results.  This is the single  occa‐
2122       sion where a `^C' will not also terminate top.
2123
2124         pipe ^I Trace ^I /usr/bin/strace -p %d 2>&1
2125
2126       Lastly, while `pipe' type entries have been discussed in terms of pipe‐
2127       lines and commands, there is nothing  to  prevent  you  from  including
2128       shell  scripts  as  well.   Perhaps even newly created scripts designed
2129       specifically for the `Y' interactive command.
2130
2131       For example, as the number of your Inspect entries grows over time, the
2132       `Options:'  row  will be truncated when screen width is exceeded.  That
2133       does not affect operation other than to make some selections invisible.
2134       However,  if  some  choices  are lost to truncation but you want to see
2135       more options, there is an easy solution hinted at below.
2136
2137         Inspection Pause at pid ...
2138         Use:  left/right then <Enter> ...
2139         Options:  help  1  2  3  4  5  6  7  8  9  10  11 ...
2140
2141       The entries in the top rcfile would have a number for the `.name'  ele‐
2142       ment  and the `help' entry would identify a shell script you've written
2143       explaining what those numbered selections actually mean.  In that  way,
2144       many more choices can be made visible.
2145
2146   6c. SYSTEM Configuration File
2147       This  configuration  file  represents  defaults  for users who have not
2148       saved their own configuration file.  The  format  mirrors  exactly  the
2149       personal  configuration  file and can also include `inspect' entries as
2150       explained above.
2151
2152       Creating it is a simple process.
2153
2154       1. Configure top appropriately for your installation and preserve  that
2155       configuration with the `W' interactive command.
2156
2157       2. Add and test any desired `inspect' entries.
2158
2159       3.  Copy  that  configuration  file  to  the /etc/ directory as `topde‐
2160       faultrc'.
2161
2162
2163   6d. SYSTEM Restrictions File
2164       The presence of this file will influence  which  version  of  the  help
2165       screen is shown to an ordinary user.
2166
2167       More  importantly,  it will limit what ordinary users are allowed to do
2168       when top is running.  They will not be able to issue the following com‐
2169       mands.
2170           k        Kill a task
2171           r        Renice a task
2172           d or s   Change delay/sleep interval
2173
2174       This  configuration  file is not created by top.  Rather, it is created
2175       manually and placed it in the /etc/ directory as `toprc'.
2176
2177       It should have exactly two lines, as shown in this example:
2178           s        # line 1: secure mode switch
2179           5.0      # line 2: delay interval in seconds
2180
2181

7. STUPID TRICKS Sampler

2183       Many of these tricks work best when you give top  a  scheduling  boost.
2184       So  plan  on starting him with a nice value of -10, assuming you've got
2185       the authority.
2186
2187
2188   7a. Kernel Magic
2189       For these stupid tricks, top needs full-screen mode.
2190
2191
2192       ·  The user interface, through prompts and help, intentionally  implies
2193          that  the delay interval is limited to tenths of a second.  However,
2194          you're free to set any desired delay.  If you want to see  Linux  at
2195          his scheduling best, try a delay of .09 seconds or less.
2196
2197          For  this experiment, under x-windows open an xterm and maximize it.
2198          Then do the following:
2199            . provide a scheduling boost and tiny delay via:
2200                nice -n -10 top -d.09
2201            . keep sorted column highlighting Off so as to
2202              minimize path length
2203            . turn On reverse row highlighting for emphasis
2204            . try various sort columns (TIME/MEM work well),
2205              and normal or reverse sorts to bring the most
2206              active processes into view
2207
2208          What you'll see is a very busy Linux doing what he's always done for
2209          you, but there was no program available to illustrate this.
2210
2211
2212       ·  Under an xterm using `white-on-black' colors, on top's Color Mapping
2213          screen set the task color to black and be sure that task  highlight‐
2214          ing  is  set  to  bold, not reverse.  Then set the delay interval to
2215          around .3 seconds.
2216
2217          After bringing the most active processes into view, what you'll  see
2218          are the ghostly images of just the currently running tasks.
2219
2220
2221       ·  Delete the existing rcfile, or create a new symlink.  Start this new
2222          version then type `T' (a secret key, see topic 4c.  Task  Area  Com‐
2223          mands,  SORTING) followed by `W' and `q'.  Finally, restart the pro‐
2224          gram with -d0 (zero delay).
2225
2226          Your display will be refreshed at three times the rate of the former
2227          top,  a  300% speed advantage.  As top climbs the TIME ladder, be as
2228          patient as you can while speculating on whether or not top will ever
2229          reach the top.
2230
2231
2232   7b. Bouncing Windows
2233       For these stupid tricks, top needs alternate-display mode.
2234
2235
2236       ·  With  3  or  4 task displays visible, pick any window other than the
2237          last and turn idle processes  Off  using  the  `i'  command  toggle.
2238          Depending  on where you applied `i', sometimes several task displays
2239          are bouncing and sometimes it's like an accordion, as top tries  his
2240          best to allocate space.
2241
2242
2243       ·  Set  each  window's  summary  lines  differently: one with no memory
2244          (`m'); another with no states (`t'); maybe one with nothing at  all,
2245          just the message line.  Then hold down `a' or `w' and watch a varia‐
2246          tion on bouncing windows  --  hopping windows.
2247
2248
2249       ·  Display all 4 windows and for each, in turn, set idle  processes  to
2250          Off  using the `i' command toggle.  You've just entered the "extreme
2251          bounce" zone.
2252
2253
2254   7c. The Big Bird Window
2255       This stupid trick also requires alternate-display mode.
2256
2257
2258       ·  Display all 4 windows and make sure that 1:Def is the `current' win‐
2259          dow.   Then,  keep  increasing  window size with the `n' interactive
2260          command until all the other task displays are  "pushed  out  of  the
2261          nest".
2262
2263          When  they've all been displaced, toggle between all visible/invisi‐
2264          ble windows using the `_' command toggle.  Then ponder this:
2265             is top fibbing or telling honestly your imposed truth?
2266
2267
2268   7d. The Ol' Switcheroo
2269       This stupid trick works best without alternate-display mode, since jus‐
2270       tification is active on a per window basis.
2271
2272
2273       ·  Start  top  and  make COMMAND the last (rightmost) column displayed.
2274          If necessary, use the `c' command toggle to  display  command  lines
2275          and ensure that forest view mode is active with the `V' command tog‐
2276          gle.
2277
2278          Then use the up/down arrow keys to position the display so that some
2279          truncated  command  lines are shown (`+' in last position).  You may
2280          have to resize your xterm to produce truncation.
2281
2282          Lastly, use the `j' command toggle to make the COMMAND column  right
2283          justified.
2284
2285          Now use the right arrow key to reach the COMMAND column.  Continuing
2286          with the right arrow key, watch closely the direction of travel  for
2287          the command lines being shown.
2288
2289             some lines travel left, while others travel right
2290
2291             eventually all lines will Switcheroo, and move right
2292
2293

8. BUGS

2295       Please send bug reports to ⟨procps@freelists.org⟩.
2296
2297
2298

9. SEE Also

2300       free(1), ps(1), uptime(1), atop(1), slabtop(1), vmstat(8), w(1)
2301
2302
2303
2304procps-ng                        October 2019                           TOP(1)
Impressum