1TOP(1) User Commands TOP(1)
2
3
4
6 top - display Linux processes
7
8
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
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
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
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
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
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
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
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
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
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
2295 Please send bug reports to ⟨procps@freelists.org⟩.
2296
2297
2298
2300 free(1), ps(1), uptime(1), atop(1), slabtop(1), vmstat(8), w(1)
2301
2302
2303
2304procps-ng October 2019 TOP(1)