TOPRUMP(1)

NAME
toprump - display and update information about the top CPU processes

SYNOPSIS
toprump [-12bCcIimnqSTuvXz] [-B user] [-d count] [-G graph] [-g string] [-L threshold] [-M pid] [-o field] [-p pid] [-s time] [-U user] [number]

DESCRIPTION
toprump displays the top processes on the system and periodically updates this information. If standard output is an intelligent terminal (see below) then as many processes as will fit on the terminal screen are displayed by default. Otherwise, a good number of them are shown (around 20). Raw CPU percentage is used to rank the processes. If number is given, then the top number processes will be displayed instead of the default.

toprump makes a distinction between terminals that support advanced capabilities and those that do not. This distinction affects the choice of defaults for certain options. In the remainder of this document, an intelligent terminal is one that supports cursor addressing, clear screen, and clear to end of line. Conversely, a dumb terminal is one that does not support such features. If the output of toprump is redirected to a file, it acts as if it were being run on a dumb terminal.

The options are as follows:

-1  Display combined CPU statistics for all processors on a single line instead of one line per CPU.

-2  Hide the top summary lines from view.

-B user
    Highlight (make bold) a specific users' processes.

-b  Use batch mode. In this mode, all input from the terminal is ignored. Interrupt characters (such as ‘^C’ and ‘^\’) still have an effect. This is the default on a dumb terminal, or when the output is not a terminal.

-C  Show command line arguments as well as the process itself.

-c  Same as 'C' but hide certain columns to show longer command line arguments.

-d count
    Show only count displays, then exit. A display is considered to be one update of the screen. This option allows the user to select the number of displays to be shown before toprump automatically exits. For intelligent terminals, no upper limit is set. The default is 1 for dumb terminals.

-G graph
    Select one or more graphs for viewing, current options are l, c, n, m, s, a, b, 0. The first three options display single graphs for general machine metrics, they are: l load averages, c CPU utilisation and n number of processes. The following two are specific to a monitored process (see 'M' below): m monitored process CPU utilisation. s size of monitored process memory (SIZE). These options can be combined to view more than one graph, depending on the size of the screen. In addition, a will attempt to display all graphs related to machine metrics and b will attempt to display all graphs related to a specific monitored process. The size of the screen will determine how many, if any, are shown. 0 hides any viewable graphs.

-g string
    Display only processes that contain string in their command name.

-I  Do not display idle processes. By default, toprump displays both active and idle processes.

-i  Use interactive mode. In this mode, any input is immediately read for processing. See the section on INTERACTIVE MODE for an explanation of which keys perform what functions. After the command is processed, the screen will immediately be updated, even if the command was not understood. This mode is the default when standard output is an intelligent terminal.

-L threshold
    Highlight the load average figures when they breach threshold. Setting threshold to ‘0’ switches highlighting off.

-M pid
    Monitor a process. toprump will monitor itself if no other process is defined on the command line.

-m  Toggle viewing of a monitored process.

-n  Use non-interactive mode. This is identical to batch mode.

-o field
    Sort the process display area using the specified field as the primary key. The field name is the name of the column as seen in the output, but in lower case. This version of toprump supports cpu, size, res, time, pri, pid, and command.

-p pid
    Show only the process pid.

-q  Renice toprump to -20 so that it will run faster. This can be used when the system is being very sluggish to improve the possibility of discovering the problem. This option can only be used by root.

-S  Show system processes in the display. Normally, system processes such as the pager and the swapper are not shown. This option makes them visible.

-s time
    Set the delay between screen updates to time seconds. The value may be fractional, to permit delays of less than 1 second. The default delay between updates is 5 seconds.

-T  Show process threads in the display. Normally, only the main process is shown. This option makes all threads visible.

-U user
    Show only those processes owned by user. This option currently only accepts usernames and will not understand UID numbers. Placing '!' before user will remove processes belonging to the corresponding user. Entering '!' on its own will remove processes owned by "root"

-u  Do not take the time to map UID numbers to usernames. Normally, toprump will read as much of the password database as is necessary to map all the user ID numbers it encounters into login names. This option disables all that, while possibly decreasing execution time. The UID numbers are displayed instead of the names.

-v  Display version information. All other options are ignored.

-X  Hide the default load average graph.

-z  Display only zombie processes.

Both count and number fields can be specified as infinite, indicating that they can stretch as far as possible. This is accomplished by using any proper prefix of the keywords infinity, maximum, or all. The default for count on an intelligent terminal is, in fact, infinity.

The environment variable TOPRUMP is examined for options before the command line is scanned. This enables a user to set his or her own defaults. The number of processes to display can also be specified in the environment variable TOPRUMP.

The options -1, -2, -C, -c, -I, -m, -S, -T, -u, and -z are actually toggles. A second specification of any of these options will negate the first. Thus a user who has the environment variable TOPRUMP set to “-I” may use the command “toprump -I” to see idle processes.

INTERACTIVE MODE
When toprump is running in interactive mode, it reads commands from the terminal and acts upon them accordingly. In this mode, the terminal is put in CBREAK, so that a character will be processed as soon as it is typed. Almost always, a key will be pressed when toprump is between displays; that is, while it is waiting for time seconds to elapse. If this is the case, the command will be processed and the display will be updated immediately thereafter (reflecting any changes that the command may have specified). This happens even if the command was incorrect. If a key is pressed while toprump is in the middle of updating the display, it will finish the update and then process the command. Some commands require additional information, and the user will be prompted accordingly. While typing this information in, the user's erase and kill keys (as set up by the command stty(1)) are recognized, and a newline terminates the input.

These commands are currently recognized (^G refers to control-G):

h?  Display a summary of the interactive commands. Commands are split between two help screens, presing 'h' twice will show both screens.

^G  Show status of filter commands.

^L  Redraw the screen.

q   Quit toprump.

+   Reset any filters put in place by the ‘g’, ‘p’, and ‘u’ interactive commands, or their command line equivalents, or any process highlighting put in place by the ‘B’ or ‘P’ interactive commands.

1   Toggle the display of CPU statistics.

2   Toggle displaying the top summary lines.

B user
    Toggle the highlighting of a specific users' processes.

C   Toggle the display of process command line arguments.

c   Toggle the display of longer process command line arguments.

d count
    Show only count displays, then exit.

e   Display a list of system errors (if any) generated by the last kill or renice command.

G graph
    Select one or more graphs for viewing. Values are the same as for the -G flag, as detailed above.

g string
    Display only processes that contain string in their command name. ‘g+’ shows all processes.

I i Toggle the display of idle processes. This is infact a tristate toggle. The default view of toprump is to show idle processes. Pressing either I i once will hide idle processes and only show those that are in the state of SRUN (this is the same as OpenBSD top). Pressing either I i a third time will show processes in the state of SSLEEP, SSTOP and SRUN.

k   [-sig] pid Send signal -sig (TERM by default) to process pid. This acts similarly to the command kill(1).

L threshold
    Set the load average highlighting threshold. Setting threshold to ‘0’ switches highlighting off.

M pid
    Monitor a process.

m   Toggle viewing of a monitored process and all processes.

n# count
    Show count processes.

o field
    Sort the process display area using the specified field as the primary key. Values are the same as for the -o flag, as detailed above.

P pid
    Highlight a specific process, selected by pid. ‘P+’ removes process highlighting.

p pid
    Show only the process pid. ‘p+’ shows all processes.

r count pid
    Change the priority (the nice) of a list of processes to count for process pid. This acts similarly to the command renice(8).

S   Toggle the display of system processes. This is infact a tristate toggle. By default toprump doesn't show system processes. Pressing S once will show system and non-system processes. Pressing S a third time will show only system processes.

s time
    Set the delay between screen updates to time seconds.

T   Toggle the display of process threads.

u user
    Show only those processes owned by user. ‘u+’ shows processes belonging to all users. Additional options are the same as '-U' above.

v   Display version information.

x   When only one graph is being viewed or viewable, switch between viewing the other graphs being hidden.

X   Toggle the display of any ASCII graphs being viewed. This is a shortcut for the G option to hide/show graphs.

z   Toggle the display of zombie processes.

THE DISPLAY
The top few lines of the display show general information about the state of the system, including the three load average numbers, the hostname, the current time, the number of existing processes, the number of processes in each state (starting, running, idle, stopped, zombie, dead, and on processor), and a percentage of time spent in each of the processor states (user, nice, system, interrupt, and idle). It also includes information about physical and virtual memory allocation. The load average numbers give the number of jobs in the run queue averaged over 1, 5, and 15 minutes.

The remainder of the screen displays information about individual processes. This display is similar in spirit to ps(1) but it is not exactly the same. The following fields are displayed:

PID The process ID.

USERNAME
    The name of the process's owner.

UID Used instead of USERNAME if -u is specified.

PRI The current priority of the process.

NICE
    The nice amount (in the range -20 to 20).

SIZE
    The total size of the process (the text, data, and stack segments).

RES The current amount of resident memory.

STATE
    The current state (one of start, run, sleep, stop, idle, zomb, dead, or onproc). On multi-processor systems, this is followed by a slash and the CPU number on which the process is bound.

WAIT
    A description of the wait channel the process is sleeping on if it's asleep.

TIME
    The number of system and user CPU seconds that the process has used.

CPU The raw percentage of CPU usage and the default field on which the display is sorted.

COMMAND
    The name of the command that the process is currently running. (If the process is swapped out, this column is enclosed by angle brackets.)

THE GRAPHS
The Y-axis of each graph is divided into 10 rows. Each row represents a variable increase shown by the figures located on the lefthand side. Each row can hold one of three characters: '.', 'x' and 'X' (or similar). They indicate a one third proportion increase. For example if the scale of the graph is increasing by 10, '.' = 0 to 3.33, 'x' = 3.34 to 6.66 and 'X' = 6.67 to 10. There are two exceptions to the above ASCII notation. When a sample is negligible (e.g 0.001%), no character is displayed. This is to facilitate viewing an almost non-existant metric . Similarly, a 'C' character is displayed when a figure is recorded that is over the maximum allowed. The X-axis represents one time sample of toprump.

By default toprump displays a load average graph. This graph uses the 1 minute load average figure.

The CPU utilisation graph uses the inverse of the idle figure to represent CPU activity. If multiple CPUs are present the idle figure is averaged.

The total number of processes graph does not include system processes.

Initially, a vertical bar comprising of the ':' character moves from right to left. This is useful if a machine is reporting an unchanging value, most usually either a negligible value or one over the maximum.

ENVIRONMENT

TOPRUMP
    User-configurable defaults for options.

FILES
/dev/kmem
    kernel memory
/dev/mem
    physical memory
/etc/passwd
    used to map user ID to user
/bsd
    kernel image
/bsd.mp
    multi-processor kernel image

EXAMPLES
Run toprump and do not display an ASCII graph:

    $ toprump -X

Display ASCII graphs for only general machine information if there is enough screen real estate and show one line for CPU state information:

    $ toprump -G a -1

Select process '1234' to be monitored and view the corresponding process CPU% graph and process history, while also hiding the top summary lines:

    $ toprump -m2G m -M 1234

SEE ALSO
fstat(1), kill(1), netstat(1), ps(1), stty(1), systat(1), mem(4), iostat(8), pstat(8), renice(8), vmstat(8)

AUTHORS
William LeFebvre, EECS Department, Northwestern University wrote the original top(1) which is included in OpenBSD. Mark Lumsden forked the top(1) included with OpenBSD in March 2007 and created toprump.

BUGS
As with ps(1), things can change while toprump is collecting information for an update. The picture it gives is only a close approximation to reality.

A process being monitored [-M pid] will not have data kept if it is filtered from view.