5a. WINDOWS Overview
Field Groups/Windows:
In full-screen mode there is a single window represented by
the entire screen. That single window can still be changed to
display 1 of 4 different field groups (see the `g' interactive
command, repeated below). Each of the 4 field groups has a
unique separately configurable summary area and its own
configurable task area.
In alternate-display mode, those 4 underlying field groups can
now be made visible simultaneously, or can be turned Off
individually at your command.
The summary area will always exist, even if it's only the
message line. At any given time only one summary area can be
displayed. However, depending on your commands, there could
be from zero to four separate task displays currently showing
on the screen.
Current Window:
The `current' window is the window associated with the summary
area and the window to which task related commands are always
directed. Since in alternate-display mode you can toggle the
task display Off, some commands might be restricted for the
`current' window.
A further complication arises when you have toggled the first
summary area line Off. With the loss of the window name (the
`l' toggled line), you'll not easily know what window is the
`current' window.
5b. COMMANDS for Windows
- | _ :Show/Hide-Window(s) toggles
The `-' key turns the `current' window's task display On
and Off. When On, that task area will show a minimum of
the columns header you've established with the `f'
interactive command. It will also reflect any other task
area options/toggles you've applied yielding zero or more
tasks.
The `_' key does the same for all task displays. In other
words, it switches between the currently visible task
display(s) and any task display(s) you had toggled Off.
If all 4 task displays are currently visible, this
interactive command will leave the summary area as the
only display element.
* = | + :Equalize/Reset-Window(s)
The `=' key forces the `current' window's task display to
be visible. It also reverses any active `i' (idle tasks),
`n' (max tasks), `u/U' (user filter), `o/O' (other
filter), `v' (hide children), `F' focused, `L' (locate)
and `!' (combine cpus) commands. Also, if the window had
been scrolled, it will be reset with this command. See
topic 5c. SCROLLING a Window for additional information
regarding vertical and horizontal scrolling.
The `+' key does the same for all windows. The four task
displays will reappear, evenly balanced, while retaining
any customizations previously applied beyond those noted
for the `=' command toggle.
* A :Alternate-Display-Mode toggle
This command will switch between full-screen mode and
alternate-display mode.
The first time you issue this command, all four task
displays will be shown. Thereafter when you switch modes,
you will see only the task display(s) you've chosen to
make visible.
* a | w :Next-Window-Forward/Backward
This will change the `current' window, which in turn
changes the window to which commands are directed. These
keys act in a circular fashion so you can reach any
desired window using either key.
Assuming the window name is visible (you have not toggled
`l' Off), whenever the `current' window name loses its
emphasis/color, that's a reminder the task display is Off
and many commands will be restricted.
* g :Choose-Another-Window/Field-Group
You will be prompted to enter a number between 1 and 4
designating the field group which should be made the
`current' window.
In full-screen mode, this command is necessary to alter
the `current' window. In alternate-display mode, it is
simply a less convenient alternative to the `a' and `w'
commands.
G :Change-Window/Field-Group-Name
You will be prompted for a new name to be applied to the
`current' window. It does not require that the window
name be visible (the `l' toggle to be On).
* The interactive commands shown with an asterisk (`*') have use
beyond alternate-display mode.
=, A, g are always available
a, w act the same with color mapping
and fields management
5c. SCROLLING a Window
Typically a task window is a partial view into a system's total
tasks/threads which shows only some of the available
fields/columns. With these scrolling keys, you can move that
view vertically or horizontally to reveal any desired task or
column.
Up,PgUp :Scroll-Tasks
Move the view up toward the first task row, until the first
task is displayed at the top of the `current' window. The Up
arrow key moves a single line while PgUp scrolls the entire
window.
Down,PgDn :Scroll-Tasks
Move the view down toward the last task row, until the last
task is the only task displayed at the top of the `current'
window. The Down arrow key moves a single line while PgDn
scrolls the entire window.
Left,Right :Scroll-Columns
Move the view of displayable fields horizontally one column
at a time.
Note: As a reminder, some fields/columns are not fixed-width
but allocated all remaining screen width when visible. When
scrolling right or left, that feature may produce some
unexpected results initially.
Additionally, there are special provisions for any variable
width field when positioned as the last displayed field.
Once that field is reached via the right arrow key, and is
thus the only column shown, you can continue scrolling
horizontally within such a field. See the `C' interactive
command below for additional information.
Home :Jump-to-Home-Position
Reposition the display to the un-scrolled coordinates.
End :Jump-to-End-Position
Reposition the display so that the rightmost column reflects
the last displayable field and the bottom task row represents
the last task.
Note: From this position it is still possible to scroll down
and right using the arrow keys. This is true until a single
column and a single task is left as the only display element.
C :Show-scroll-coordinates toggle
Toggle an informational message which is displayed whenever
the message line is not otherwise being used. That message
will take one of two forms depending on whether or not a
variable width column has also been scrolled.
scroll coordinates: y = n/n (tasks), x = n/n (fields)
scroll coordinates: y = n/n (tasks), x = n/n (fields) + nn
The coordinates shown as n/n are relative to the upper left
corner of the `current' window. The additional `+ nn'
represents the displacement into a variable width column when
it has been scrolled horizontally. Such displacement occurs
in normal 8 character tab stop amounts via the right and left
arrow keys.
y = n/n (tasks)
The first n represents the topmost visible task and is
controlled by scrolling keys. The second n is updated
automatically to reflect total tasks.
x = n/n (fields)
The first n represents the leftmost displayed column and
is controlled by scrolling keys. The second n is the
total number of displayable fields and is established
with the `f' interactive command.
The above interactive commands are always available in
full-screen mode but never available in alternate-display mode if
the `current' window's task display has been toggled Off.
Note: When any form of filtering is active, you can expect some
slight aberrations when scrolling since not all tasks will be
visible. This is particularly apparent when using the Up/Down
arrow keys.
5d. SEARCHING in a Window
You can use these interactive commands to locate a task row
containing a particular value.
L :Locate-a-string
You will be prompted for the case-sensitive string to locate
starting from the current window coordinates. There are no
restrictions on search string content.
Searches are not limited to values from a single field or
column. All of the values displayed in a task row are
allowed in a search string. You may include spaces, numbers,
symbols and even forest view artwork.
Keying <Enter> with no input will effectively disable the `&'
key until a new search string is entered.
& :Locate-next
Assuming a search string has been established, top will
attempt to locate the next occurrence.
When a match is found, the current window is repositioned
vertically so the task row containing that string is first. The
scroll coordinates message can provide confirmation of such
vertical repositioning (see the `C' interactive command).
Horizontal scrolling, however, is never altered via searching.
The availability of a matching string will be influenced by the
following factors.
a. Which fields are displayable from the total available,
see topic 3b. MANAGING Fields.
b. Scrolling a window vertically and/or horizontally,
see topic 5c. SCROLLING a Window.
c. The state of the command/command-line toggle,
see the `c' interactive command.
d. The stability of the chosen sort column,
for example PID is good but %CPU bad.
If a search fails, restoring the `current' window home
(unscrolled) position, scrolling horizontally, displaying
command-lines or choosing a more stable sort field could yet
produce a successful `&' search.
The above interactive commands are always available in
full-screen mode but never available in alternate-display mode if
the `current' window's task display has been toggled Off.
Note: Whenever a Search is active in a window, top will turn
column highlighting Off to prevent false matches on internal non-
display escape sequences. Such highlighting will be restored
when a window's search string is empty. See the `x' interactive
command for additional information on sort column highlighting.
5e. FILTERING in a Window
You can use this `Other Filter' feature to establish selection
criteria which will then determine which tasks are shown in the
`current' window. Such filters can be made persistent if
preserved in the rcfile via the 'W' interactive command.
Establishing a filter requires: 1) a field name; 2) an operator;
and 3) a selection value, as a minimum. This is the most complex
of top's user input requirements so, when you make a mistake,
command recall will be your friend. Remember the Up/Down arrow
keys or their aliases when prompted for input.
Filter Basics
1. field names are case sensitive and spelled as in the header
2. selection values need not comprise the full displayed field
3. a selection is either case insensitive or sensitive to case
4. the default is inclusion, prepending `!' denotes exclusions
5. multiple selection criteria can be applied to a task window
6. inclusion and exclusion criteria can be used simultaneously
7. the 1 equality and 2 relational filters can be freely mixed
8. separate unique filters are maintained for each task window
If a field is not turned on or is not currently in view, then
your selection criteria will not affect the display. Later,
should a filtered field become visible, the selection criteria
will then be applied.
Keyboard Summary
o :Other-Filter (lower case)
You will be prompted to establish a filter that ignores
case when matching.
O :Other-Filter (upper case)
You will be prompted to establish a case sensitive filter.
^O :Show-Active-Filters (Ctrl key + `o')
This can serve as a reminder of which filters are active in
the `current' window. A summary will be shown on the
message line until you press the <Enter> key.
= :Reset-Filtering in current window
This clears all of your selection criteria in the `current'
window. It also has additional impact so please see topic
4a. GLOBAL Commands.
+ :Reset-Filtering in all windows
This clears the selection criteria in all windows, assuming
you are in alternate-display mode. As with the `='
interactive command, it too has additional consequences so
you might wish to see topic 5b. COMMANDS for Windows.
Input Requirements
When prompted for selection criteria, the data you provide
must take one of two forms. There are 3 required pieces of
information, with a 4th as optional. These examples use
spaces for clarity but your input generally would not.
#1 #2 #3 ( required )
Field-Name ? include-if-value
! Field-Name ? exclude-if-value
#4 ( optional )
Items #1, #3 and #4 should be self-explanatory. Item #2
represents both a required delimiter and the operator which
must be one of either equality (`=') or relation (`<' or `>').
The `=' equality operator requires only a partial match and
that can reduce your `if-value' input requirements. The `>'
or `<' relational operators always employ string comparisons,
even with numeric fields. They are designed to work with a
field's default justification and with homogeneous data. When
some field's numeric amounts have been subjected to scaling
while others have not, that data is no longer homogeneous.
If you establish a relational filter and you have changed the
default Numeric or Character justification, that filter is
likely to fail. When a relational filter is applied to a
memory field and you have not changed the scaling, it may
produce misleading results. This happens, for example,
because `100.0m' (MiB) would appear greater than `1.000g'
(GiB) when compared as strings.
If your filtered results appear suspect, simply altering
justification or scaling may yet achieve the desired
objective. See the `j', `J' and `e' interactive commands for
additional information.
Potential Problems
These GROUP filters could produce the exact same results or
the second one might not display anything at all, just a blank
task window.
GROUP=root ( only the same results when )
GROUP=ROOT ( invoked via lower case `o' )
Either of these RES filters might yield inconsistent and/or
misleading results, depending on the current memory scaling
factor. Or both filters could produce the exact same results.
RES>9999 ( only the same results when )
!RES<10000 ( memory scaling is at `KiB' )
This nMin filter illustrates a problem unique to scalable
fields. This particular field can display a maximum of 4
digits, beyond which values are automatically scaled to KiB or
above. So while amounts greater than 9999 exist, they will
appear as 2.6m, 197k, etc.
nMin>9999 ( always a blank task window )
Potential Solutions
These examples illustrate how Other Filtering can be
creatively applied to achieve almost any desired result.
Single quotes are sometimes shown to delimit the spaces which
are part of a filter or to represent a request for status (^O)
accurately. But if you used them with if-values in real life,
no matches would be found.
Assuming field nTH is displayed, the first filter will result
in only multi-threaded processes being shown. It also reminds
us that a trailing space is part of every displayed field.
The second filter achieves the exact same results with less
typing.
!nTH=` 1 ' ( ' for clarity only )
nTH>1 ( same with less i/p )
With Forest View mode active and the COMMAND column in view,
this filter effectively collapses child processes so that just
3 levels are shown.
!COMMAND=` `- ' ( ' for clarity only )
The final two filters appear as in response to the status
request key (^O). In reality, each filter would have required
separate input. The PR example shows the two concurrent
filters necessary to display tasks with priorities of 20 or
more, since some might be negative. Then by exploiting
trailing spaces, the nMin series of filters could achieve the
failed `9999' objective discussed above.
`PR>20' + `!PR=-' ( 2 for right result )
`!nMin=0 ' + `!nMin=1 ' + `!nMin=2 ' + `!nMin=3 ' ...
Note: Whenever Other Filtering is active in a window, top will
turn column highlighting Off to prevent false matches on internal
non-display escape sequences. Such highlighting will be restored
when a window is no longer subject to filtering. See the `x'
interactive command for additional information on sort column
highlighting.
