6a. PERSONAL Configuration File
This file is created or updated via the 'W' interactive command.
The legacy version is written as `$HOME/.your-name-4-top' + `rc'
with a leading period.
A newly created configuration file is written as
procps/your-name-4-top' + `rc' without a leading period. The
procps directory will be subordinate to either $XDG_CONFIG_HOME
when set as an absolute path or the $HOME/.config directory.
While not intended to be edited manually, here is the general
layout:
global # line 1: the program name/alias notation
" # line 2: id,altscr,irixps,delay,curwin
per ea # line a: winname,fieldscur
window # line b: winflags,sortindx,maxtasks,etc
" # line c: summclr,msgsclr,headclr,taskclr
global # line 15: additional miscellaneous settings
" # any remaining lines are devoted to optional
" # active 'other filters' discussed in section 5e above
" # plus 'inspect' entries discussed in section 6b below
If a valid absolute path to the rcfile cannot be established,
customizations made to a running top will be impossible to
preserve.
6b. ADDING INSPECT Entries
To exploit the `Y' interactive command, you must add entries at
the end of the top personal configuration file. Such entries
simply reflect a file to be read or command/pipeline to be
executed whose results will then be displayed in a separate
scrollable, searchable window.
If you don't know the location or name of your top rcfile, use
the `W' interactive command to rewrite it and note those details.
Inspect entries can be added with a redirected echo or by editing
the configuration file. Redirecting an echo risks overwriting
the rcfile should it replace (>) rather than append (>>) to that
file. Conversely, when using an editor care must be taken not to
corrupt existing lines, some of which will contain unprintable
data or unusual characters.
Those Inspect entries beginning with a `#' character are ignored,
regardless of content. Otherwise they consist of the following 3
elements, each of which must be separated by a tab character
(thus 2 `\t' total):
.type: literal `file' or `pipe'
.name: selection shown on the Inspect screen
.fmts: string representing a path or command
The two types of Inspect entries are not interchangeable. Those
designated `file' will be accessed using fopen and must reference
a single file in the `.fmts' element. Entries specifying `pipe'
will employ popen, their `.fmts' element could contain many
pipelined commands and, none can be interactive.
If the file or pipeline represented in your `.fmts' deals with
the specific PID input or accepted when prompted, then the format
string must also contain the `%d' specifier, as these examples
illustrate.
.fmts= /proc/%d/numa_maps
.fmts= lsof -P -p %d
For `pipe' type entries only, you may also wish to redirect
stderr to stdout for a more comprehensive result. Thus the
format string becomes:
.fmts= pmap -x %d 2>&1
Here are examples of both types of Inspect entries as they might
appear in the rcfile. The first entry will be ignored due to the
initial `#' character. For clarity, the pseudo tab depictions
(^I) are surrounded by an extra space but the actual tabs would
not be.
# pipe ^I Sockets ^I lsof -n -P -i 2>&1
pipe ^I Open Files ^I lsof -P -p %d 2>&1
file ^I NUMA Info ^I /proc/%d/numa_maps
pipe ^I Log ^I tail -n100 /var/log/syslog | sort -Mr
Except for the commented entry above, these next examples show
what could be echoed to achieve similar results, assuming the
rcfile name was `.toprc'. However, due to the embedded tab
characters, each of these lines should be preceded by `/bin/echo
-e', not just a simple an `echo', to enable backslash
interpretation regardless of which shell you use.
"pipe\tOpen Files\tlsof -P -p %d 2>&1" >> ~/.toprc
"file\tNUMA Info\t/proc/%d/numa_maps" >> ~/.toprc
"pipe\tLog\ttail -n200 /var/log/syslog | sort -Mr" >> ~/.toprc
If any inspect entry you create produces output with unprintable
characters they will be displayed in either the ^C notation or
hexadecimal <FF> form, depending on their value. This applies to
tab characters as well, which will show as `^I'. If you want a
truer representation, any embedded tabs should be expanded. The
following example takes what could have been a `file' entry but
employs a `pipe' instead so as to expand the embedded tabs.
# next would have contained `\t' ...
# file ^I <your_name> ^I /proc/%d/status
# but this will eliminate embedded `\t' ...
pipe ^I <your_name> ^I cat /proc/%d/status | expand -
Note: Some programs might rely on SIGINT to end. Therefore, if a
`pipe' such as the following is established, one must use Ctrl-C
to terminate it in order to review the results. This is the
single occasion where a `^C' will not also terminate top.
pipe ^I Trace ^I /usr/bin/strace -p %d 2>&1
Lastly, while `pipe' type entries have been discussed in terms of
pipelines and commands, there is nothing to prevent you from
including shell scripts as well. Perhaps even newly created
scripts designed specifically for the `Y' interactive command.
For example, as the number of your Inspect entries grows over
time, the `Options:' row will be truncated when screen width is
exceeded. That does not affect operation other than to make some
selections invisible. However, if some choices are lost to
truncation but you want to see more options, there is an easy
solution hinted at below.
Inspection Pause at pid ...
Use: left/right then <Enter> ...
Options: help 1 2 3 4 5 6 7 8 9 10 11 ...
The entries in the top rcfile would have a number for the `.name'
element and the `help' entry would identify a shell script you've
written explaining what those numbered selections actually mean.
In that way, many more choices can be made visible.
6c. SYSTEM Configuration File
This configuration file represents defaults for users who have
not saved their own configuration file. The format mirrors
exactly the personal configuration file and can also include
`inspect' entries as explained above.
Creating it is a simple process.
1. Configure top appropriately for your installation and preserve
that configuration with the `W' interactive command.
2. Add and test any desired `inspect' entries.
3. Copy that configuration file to the /etc/ directory as
`topdefaultrc'.
6d. SYSTEM Restrictions File
The presence of this file will influence which version of the
help screen is shown to an ordinary user.
More importantly, it will limit what ordinary users are allowed
to do when top is running. They will not be able to issue the
following commands.
k Kill a task
r Renice a task
d or s Change delay/sleep interval
This configuration file is not created by top. Rather, it is
created manually and placed it in the /etc/ directory as `toprc'.
It should have exactly two lines, as shown in this example:
s # line 1: secure mode switch
5.0 # line 2: delay interval in seconds
