XPS(1)

NAME
xps - Process tree display and manipulation for the X Window System.

SYNOPSIS
xps [ "-help" | "-version" ]

xps ["-interval" time-in-seconds ]
       ["-metoo"]
       ["-kernel"]
       ["-allprocs"]
       ["-iconic"]
       ["-beep"]
       ["-zoomed"]
       ["-kill"]
       ["-debugging" integer-debug-value]
       ["-zfont" X-fontname]
       ["-zfn" X-fontname]
       ["-zgeometry" X-geometry]
       ["-swap" X-color]
       ["-waiting" X-color]
       ["-active" X- color]
       ["-selected" X-color]
       ["-running" X-color]
       ["-zombie" X-color]
       ["-idle" X-color]
       ["-stopped" X-color]
       ["-pscmdline" ps-command]
       ["-pscmdinfo" ps-command]
       [X-options...]

DESCRIPTION
xps is sort of an X-windows front end to ps(1), kill(1), and "nice" (and maybe uptime(1) too); perhaps an X-windows version of a continually running pstree(1) with the intent of dynamically showing in color what process are running or stopped, being spawned or zombies. The "sort of" part in the first sentence of this section is that for efficiency, "ps" is not in fact called in generating the tree display. And for that matter, neither are the command line versions of kill(1), or nice(1).

The main part of the display show processes as a tree or forest, the roots of the tree are on the left-hand side and the leaf processes (with no children) are on the right-hand side. Which processes shown is determined various settings. Once can select viewing all processes, or processes owned by specific users, and possibly kernel processes as well.

Process status (running, sleeping, stopped, etc.) of shown processes is indicated by a color.

Within each level, processes are grouped so that those with the same parent process id are grouped together. Within this, processes are arranged by userid with lower number uid's appearing towards the top.

This means root processes always appear at the extreme top, assuming the processes' parent was also a root process. Finally, among processes that have a common parent (or no parent) and belong to the same userid, those with lower process numbers appear towards the top. In general, the order of children is the order in which they were spawned, with the older processes appearing towards towards the top.

In contrast to "pstree" and many tree-widget based programs, the overall tree display uses diagonal lines, and some effort is made to effectively use the full 2-dimensional area of the screen by balancing levels and centering the children of a node between their parent. But since a goal of the program is to visually give a picture of what's going on, when possible processes are kept close to their parents so one needn't scroll around too much and so that doesn't there isn't a lot of redrawing as processes are created or destroyed.

One can click on a process to get more information (via "ps") about that process, send a signal to the process, or set its priority (assuming you have the permission to do so).

The majority of processes in a system, one hopes, are sleeping processes. The color to be selected for uid's of sleeping process can be specified in the "X RESOURCES" section. If however a color is not specified, one is chosen at random. Generally, all processes belonging to a given user will be a unique color. For certain terminal programs like "xterm" or "telnet", the name if the user is displayed rather than the program name.

When the program starts there are basically two windows. A "normal" window and a "zoomed" window. Each has a certain state that can be set independently.

  Options
As the Perl motto goes "There's more than one way to do it," and that's true here as well. All of the following options can be set via "X RESOURCES", and many values can be toggled in the course of the execution of the program through "MENUS, DIALOGS, AND BUTTONS".

But setting "help" or the "version" as a resource does not make much sense as these are typically not done in the normal course of things, so a couple things are unique to this section.

Options can be abbreviated to the extent that they are unique. So "-help" can be abbreviated as short as "-h".

-help
    Print a usage message on standard error and exit with a return code of 100.

-version
    Print on standard output the version release and various configuration parameters that have been set for this program and then exit with a return code of 2.

-interval secs
    Set the interval in seconds that xps should wait between status updates. Obviously this must be an integer greater than 0; it also has to be less than 64 a number which is compiled into the program. This value can also set more statically in X using the "interval" resource, and can be changed via the "Refresh Rate Dialog".

-metoo
    Normally we lie about the state of xps and pretend it is sleeping when in fact it's generally running at the time it is gathering statistics. This option is not fully functional.

-kernel
    Show kernel processes. This may or may not be implemented or even make sense depending on your architecture. This value can also set more statically in X using the "kernel" resource.

-allprocs
    Show all processes rather than just those that belong to a single userid. This value can also set more statically in X using the "allprocs" resource, and can be changed at runtime through the "Kernel" radio buttons.

-beep
    Beep when the the number of processes change. This value can also set more statically in X using the "beep" resource, and can be changed at runtime through a "Beep" toggle button.

-kill
    Sets the "QuickKill" button initially on. This value can also set more statically in X using the "quickkill" resource.

-zoomed
    Display using a (presumably larger) window rather than the normal one. This value can also set more statically in X using the "zoom" resource, and can be changed at runtime through the "Zoom" toggle button.

-stopped color
    Set the color for stopped processes. This value can also set more statically in X using the "stopped" resource.

-idle color
    Set the color for idle processes. This value can also set more statically in X using the "idle" resource.

-running color
    Set the color for running processes. This value can also set more statically in X using the "running" resource.

-zombie color
    Set the color for zombie processes. This value can also set more statically in X using the "zombie" resource.

-selected color
    Set the color for the selected process. This value can also set more statically in X using the "selected" resource.

-pscmdline ps command
    "ps" command which can be run to give information about a process. This value can also set more statically in X using the "pscmdline" resource. See that section for more information.

-pscmdinfo ps command
    "ps" command which can be run to give information about a process. This value can also set more statically in X using the "pscmdinfo" resource. See that section for more information.

X-options
    In addition the standard set of X-Window options are allowed. For example things like the window geometry ("-geometry"), the window name ("-name"), the foreground and background colors ("-fg", "-bg"), the font used ("-fn"), whether the window starts out iconified ("-iconic") and so on.

MENUS, DIALOGS, AND BUTTONS
The main window is divided into three sections:

a menu bar
    The menu bar contains a menu selection and various toggle buttons.

a process tree display area in the middle
    This is the meat of the program.

some overall status information.
    This contains load average information, how many and a count of the number of processes shown. And on another line the version number and refresh rate.

Each of the pop up menus has its own context-specific help.

  Toggle Buttons
Options "-allprocs", "-kernel", "-beep", and "-zoomed" mentioned above in Options, set the initial state for various display parameters. In addition, there are buttons which allow toggling between the two states. When a button is depressed (or looks depressed), the feature described below is "on."

Beep
    The program can arrange to beep when the number of processes grows or diminishes. The utility of such a feature, I'm not certain of. Perhaps the night watchman uses to find out when someone's telnet'd into one his server, or logged out. The keyboard-translation equivalent of this is togglebeep().

    The tune to play can be set by resources "beepup" and "beepdown".

QuickKill
    The program can be arrange to point-and-kill processes. This button is like the safety latch on the trigger. Also, the default behavior is to allow only the right mouse button in this endeavor. (I am left-handed.)

    Depending on the shifting activity of processes, you might have to be quick though to get the right one!

    The default behavior is to be nice to the process and send it a "TERM" signal. However serial killers and die-hard sysadmins can arrange for the default signal to be "KILL" (-9) or another signal using the "Set Quick Kill Signal Dialog".

    Having QuickKill button depressed will also cause the default signal in the process popup window to be set to that value.

Kernel/All/User
    The program can show all processes, all processes including kernel processes or those associated with a particular userid or pattern. Buttons may vary depending on the capabilities of your system. The keyboard-translation functions which roughly correspond are toggleprocs() and togglekernel().

    Only push button in this group can be selected at any given time.

Zoom
    The program maintains two windows, a "zoomed" or maximized window and a normal one. The geometry, text font, and scrollable canvas window can all be set independently for the zoomed and normal windows. The keyboard-translation equivalent of this is zoom().

There is probably room for much much much more improvement here. I'm not a guiologist. Some of the "features" are inherited that I didn't have the heart to remove, although I rarely use them: the beep and zoom "features" in particular. And the GUI that has been added is pretty bare bones. For example perhaps a "combo box" (combination text entry and slider) for setting the refresh interval might be more to folks liking. The debugging options could be a bunch of push buttons in a menu rather than entering as a number.

  Process Dialog Box
When a process name is selected on the process-tree canvas, a dialog box for that process pops up if it is not already open. If it is already open and a different process is selected underneath, the process information changes. In order to show the which process is selected on process-tree canvas, the process name changes color to the color specified by the "selected" resource.

The Process Dialog Box lists information about the process. Also it can be used to set the priority of the process or process group and can be used to send a signal to the process or process group.

The top part of the dialog box gives information gathered from "ps" command. Since a command invocation may be rather long, this is listed on a separate line.

Below that to the left side is scrollable list of signals which can be sent to the process. This list is automatically generated when the program was compiled via the program "makesig.pl". The list of signals is in sorted order, but the most common signals are listed at the top according to my preference. If the "Quick Kill" toggle button had been depressed, the signal selected in the "Set Quick Kill Signal Dialog" is selected. Otherwise "NO ACTION" will be selected and you will have to select a signal if you want to send a signal to a process.

To the right of the scrollable list of signals is a slider which can be used to set the process priority. The initial value is the value at the time for that process at the time the process was selected.

There is a notion in Unix called a process group which is a group of processes that are usually related in some way; perhaps they were spawned from a common parent. Instead of sending a kill signal to a specific process, the signal can be sent to the set process of processes in the process group. Likewise instead of setting the priority for a single process it can be set for the process group. The process group toggle button in the process dialog is used to indicate that a signal or priority should be applied to the process group rather than the process that is selected.

Note that in order for a kill signal or a change in priority to take effect, you may need sufficient permission to do so. This is no different than say if you were to run kill(1) or nice(1) from a shell.

If there is a problem performing the action requested (and the program catches you), the old value is kept.

  Set Quick Kill Signal Dialog
In the top line is a "Quick Kill" toggle button for those of you who like to massacre processes.

In order for point-and-kill to work, one has to arrange in advance what signal will be sent; that is what this menu is for.

In contrast to the signal menu found in the "Process Dialog Box", there is no "NO ACTION" signal. Also, this menu remembers the signal last used and has this selected in the menu list.

  Refresh Rate Dialog
The Set Refresh Rate Menu is used to set how frequently this program should retrieve process information. The units displayed are in seconds.

Changing the refresh rate does not have an immediate effect, but takes effect the next time the polling occurs.

No matter what the refresh rate interval is set to, the display is updated only when it is visible--this program can consume lots of CPU time.

  Set ps command Dialog Box
In the top part of the process popup window, process information is shown by running a "ps"-like program. What command to invoke is determined initially by the value associated with the "-pscmdline" option or the pscmdline X resource if it is not set as a command option, or if neither of these are set then by a platform-specific "ps" command string set when this xps was configured and compiled.

Well, this is not the whole truth. Having written all of the above, you can dynamically change this here as the program is running! Should you want different information or in a different format, here is where you can customize.

The "ps"-like command string should have %d or %ld as a placeholder for the process id or "pid". Chances are that the command string will want to refer to the process id somewhere. The process id of the selected process will be substituted for the first occurrence of %d or %ld (if any) found. After substitution, the command string is executed and the output, which might be several lines, will be put in the scrolled window.

Example (for Linux):

 /bin/ps w %d

If you have "lsof" installed, another interesting possibility is:

 lsof -p %d

  Set Watch User Dialog Box
When the "All" radio button is depressed, the program generally shows all processes. It is possible that on some systems the program has not been compiled in a way to show processes other than the ones you own. On some systems there is a "Kernel" button as well and this shows all processes as well as additional kernel processes.

When the "User" radio button is depressed, the program shows only some portion of all the processes, initially the processes associated with the userid that invokes the program. However you can change that with the "Set Watch User" dialog box.

On systems that have a regular-expression library and where the program has been compiled to support patterns, there will be a "pattern" toggle button which allows one to select a pattern for a user name. See your system documentation for the regular-expression syntax. Selection by pattern match may slow the program down a bit, so it should be used with caution for complex patterns and systems with a very large number of processes.

When pattern-match selection is not indicated, the user name only changes if the newly-entered one is a name known on the system. If pattern-match selection the pattern changes if it is syntactically correct. In case, if there is an error in entry the old value is kept and method of matching (pattern-match or not) is kept.

It is possible to set the watch user for the zoomed and normal windows separately. However if you want to change the view in both windows, check the "Set both windows" box.

  Set User Color Dialog Box
The Set User Color Menu can be used to change the color associated a given user in the process tree display. You enter a user name (not a uid) and an X color name like "blue" or "#DA7".

Each user in the process tree is assigned a color, often a different color. If a color assignment is not specified explicitly, the program will generate a color based on a hash of the uid. Sometimes this is a pleasing color; sometimes it is ghastly. This menu lets you assign the color for a user interactively.

However internally, there is a table for a fixed number of associations between users and colors. The default is 10 but this can be changed when the program is built. If a color for the user had previously been set it that color will be overwritten. If the user not in the internal table yet, the program looks for a free spot and inserts the user in the table. If however the table is full, a reserved spare slot is used. After the table is full, each time a new user color is assigned the last "spare" slot is overwritten with the new user and color.

If you are going to be using the program over and over again on a system where the user's don't change that frequently, or at least the important ones that you want to track, you may want to consider setting the user color via the "X RESOURCES" "uid1" and "usercolor1". The default resource file sets the color for root which has uid 0 to be black.

  Debugging Menu
If you should be so unfortunate as to want to debug this program, you can set this integer value and output should appear on stdout. So if you set debugging you should have some way to see stdout of this program. For example running this command from a window menu is probably a lose.

The debug value is interpreted as a bitstring the individual bits determine what's displayed. The bit values are:
   1 for callbacks and events handling
   2 for display debug messages
   4 for menu-oriented messages
   8 for the virtual position in the tree-level
  16 for tree sorting debugging messages

Anybody wanna turn this menu into a nice check-box menu?

X RESOURCES
See also Xps.ad for a complete example of a full X resources file for this program. There are numerous comments in that file too that mimic what is in here. (I hope the two are consistent and complete!)

interval
    Resource associated with the "-interval" option, an integer value greater than 0.

    Example:

      *interval: 2

    This value can be changed while running via a pop-up menu. See "Refresh Rate Dialog".

kernel
    Resource associated with the "-kernel" option. This option may be machine specific. A Boolean value. When set true kernel processes are shown, if your platform has and supports this.

    Example:

      *kernel: False

allprocs
    Resource associated with the "-allprocs" option, a Boolean value. This value can be changed while running via a toggle button, and selects whether to show all processes or some subset of them.

    Example:

      *allprocs: False

beep
    Resource associated with the "-beep" option and "Beep" toggle button, a Boolean value. See "Beep" for more information.

    Example:

      *beep:  False

beepup
    The "tune" to place when the number of processes increases This parameter should be a string. The format is pitch (Hz), duration (msec), ...

    Example:

      *beepup: "55 50 110 50 220 50 440 100"

    The above plays three A-pitches each an octave higher than the last, ending in A440; each pitch is held for .05 seconds.

beepdown
    Resource associated with the "-allprocs" option.

    The "tune" to place when the number of processes increases This parameter should be a string. The format is pitch (Hz), duration (msec), ...

    Example:

      *beepdown: "440 50 220 50 110 50 55 100"

    The above plays three A-pitches each an octave lower than the last, starting at A44; each pitch is held for .05 seconds.

quickkill
    Resource associated with the "-kill" option and "QuickKill" toggle button, a Boolean value. See "QuickKill" for more information. This value can be changed while running via the "QuickKill" toggle button.

    Example:

      *quickkill:  False

selected
    Resource associated with the "-selected" option, an X color name or color value. The process name that is under consideration in the "Process Dialog Box" will have this color.

    Example:

      *selected: cyan

running
    Resource associated with the "-running" option, an X color name or color value. Processes which are currently running will have this color in the Process Tree Window. You probably won't see too many of these, unless your computer is CPU bound.

    Example:

      *running:  green

idle
    Resource associated with the "-idle" option, an X color name or value.

    Example:

      *idle: orange

stopped
    Resource associated with the "-stopped" option, an X color name or value. Processes whose process state is "stopped" (e.g. being debugged or suspended), will have this color.

    Example:

      *stopped: red

zombie
    Resource associated with the "-zombie" option, an X color name or value. Zombie processes will have this color.

    Example:

      *zombie: yellow

uid1 .. uid9, usercolor1 .. usercolor9
    Sometimes you may want to select a particular color for a particular userid. The program allow you to do this for 10 uids. (The source can be changed for more.) You assign a color for a specific userid by adding two lines in your resource file: one for the uid, and another for the color that that uid should have.

    Example:

      *uid1:       0
      *usercolor1: black

    This ensures that root processes, (those with a 0 uid), are displayed in black.

    This value can be changed at run time via the a popup menu. See "Set User Color Dialog Box". Note however that a user is specified via a uid, not a user name.

pscmdinfo
    Resource associated with the "-pscmdinfo" option, a string. When the program was configured for your platform, a platform-specific "ps" command is chosen to give lots of information about a process. This command has %d or %ld as a placeholder for the process id. It is replaced by the process id of the selected process. Should you want different information or in a different format, you can customize here.

    Example (for Solaris):

      *pscmdinfo:  "/bin/ps -f -o user,pid,ppid,tty,nice,pcpu -p %ld"

pscmdline
    Resource associated with the "-pscmdline" option, an string. When the program was configured for your platform, a platform-specific "ps" command is chosen to show the command invocation for the selected process. This command has %d or %ld as a placeholder for the process id. It is replaced by the process id of the selected process. Should you want different information or in a different format, you can also customize here.

    Example (for BSDI):

      *pscmdline:  "/bin/ps -w -w -o command -p %ld"

    or if you prefer not to have the leading header line listed:

      *pscmdline:  "/bin/ps -w -w -o command -p %ld | sed -n '2,$p'"

    This value can also be changed at run time via the a popup menu. See "Set ps command Dialog Box".

  Default Key/Mouse Bindings
Below are the default key and mouse bindings. They can be overridden via "X RESOURCES". See also Xps installed in your app-defaults directory or Xps.ad that comes with the distribution.

   Key         Menu
   ------------------------------
   c           Set user color menu
   d           Debugging menu
   h           Help menu
   i           Refresh Interval menu
   k           Set kill signal
   u           User to watch menu
   v           Show version and configuration information
   w           Show No Warranty

The below commands work everywhere except in text input menus:

   Key(s)       function
   --------------------------------
   a, A         :  toggleprocs()
   b, B         :  togglebeep()
   -            :  changespeed(-1)
   f            :  changespeed(-1)
   F            :  changespeed(-5)
   Ctrl-k       :  togglekernel()
   K            :  togglekill()
   +            :  changespeed(1)
   s            :  changespeed(1)
   S            :  changespeed(5)
   r            :  redisplay()
   Ctrl-X       :  quit()
   z            :  zoom()

The below commands work only in the process-tree display or canvas area.

   space, return, mouse:  showprocess()
   right mouse         :  showprocess(K)

See "X Keyboard Translations" below for more information on functions such as "toggleprocs", "showprocess".

  X Keyboard Translations
Listed below are the functions or actions that can be performed by binding mouse or keyboard events to them.

changespeed(num)
    Decrease display refresh interval by num "ticks". This can be positive or negative. A "tick" is defined when compiling the program. The value is of a tick can be shown by running this command with the "-version" option.

    The fastest and slowest value is set in configuring the program. The minimum and maximum values can be shown by running this command with the "-version" option.

showprocess()
    This pops up the process dialog menu over the selected process. One can also give a single parameter that starts with the letter 'K'. This will kill the process over the cursor, provided "QuickKill" is set. Otherwise, the same as showprocess().

quit()
    Terminates this fine program.

togglebeep()
    This is the same as hitting the "Beep" toggle button.

    One can also give a single parameter with a value of 0, 1, or 2; 0 means set the state off, 1 means set the state on, and 2 toggle the state. So togglebeep() is the same as togglebeep(2).

toggleprocs()
    This is the same as hitting the "All" radio button.

togglekernel()
    This is the same as hitting the "Kernel" radio button assuming the "All" radio button had been depressed. If not, this has no effect until the next "toggleprocs" is run.

    One can also give a single parameter with a value of 0, 1, or 2; 0 means set the state off, 1 means set the state on, and 2 toggle the state. So togglekernel() is the same as togglekernel(2).

redisplay()
    This causes a redisplay of all information.

zoom()
    This is the same as hitting the "Zoom" toggle button

LOW-LEVEL DETAILS
The program lies about the state of xps itself since it is always running at the time it checks.

The program can consume a bit of resources both in itself and in the X server. Of course, the fewer processes that need to be tracked and the slower the refresh interval, the less run time consumed.

However some effort is made to not gather or redraw the display when not shown. The program tries to track whether it is iconified or if the process tree display window is fully obscured. If so, the program will not try to obtain data or refresh its display. But unless I've coded the program properly, it's possible for the program to think it is not visible when in fact it is.

As a further measure to reduce overhead, the program takes a sum of all of the process ID's, the sum of the process states and number of nodes and will not update its process-tree display if these sums haven't changed. But it is possible that the sum can be the same even though things have changed.

There is a debug menu; if debug values are set, debugging output will appear in standard output. Debugging values are a series of bits. Look in common.h of the source code for the values of the bits.

SEE ALSO
gnopstree(1) <http://gnopstree.sourceforge.net> ps(1), pstree(1), kill(1), nice(1), uptime(1).

Another interesting package similar to this one is George MacDonald's (gmd@orbit2orbit.com) program, "treeps". That can be obtained at <http://www.treeps.org>.

BUGS
At times, lines from a prodigious parent with a short label name (like "nfsd") will cross over a sibling with a longer name (like "rpc.mountd"). I think the program still core dumps occasionally.

Some process tables are fixed in size, somewhere at around 1,000 processes. Perhaps some will consider this a bug, but the display algorithm is not linear. As things grow the redisplay will slow down the program will consume quite a bit of CPU time. The whole paradigm of this program may not be suitable for displaying thousands of processes.

Just about everything could be improved: configuration management, tree layout, GUI design, toolkit used (via gtk+), algorithms, more platforms supported. See the file TODO distributed with the source.

The way process selection is done may be hokey in that the names of the processes aren't really widgets at all but strings drawn on a canvas so when you click on a process, in fact the program is doing its own range searching to figure out what node is meant at the mouse position. That is, there is no callback for the "widget" just the overall canvas! That is why for example we can't, say, put a box around the selected process but change very limited things like the color (or the font) of the string.

AUTHORS
The current version is maintained (or not) by rocky@panix.com. However, this code reflects the work of a number of people.

Derek Lieber wrote the first version of the code for the now defunct IBM RT/PC. Although just about everything has been rewritten and extended, many of the key ideas come from this: showing a process tree from left to right, changing the color of the process to show process activity, allowing a process to be selected on the canvas and then renice'd or kill'ed.

Subsequently Steve James added the first Motif code, although nothing in the way of command menus, dialog boxes, push buttons, or scroll windows or signal menus. Mark Kennedy extended the code to allow users to customize the pop up list via an X resources file, and allow a user-specified set of signals that could be sent to processes. (This code is has been completely replaced although the signal-list data structure still exists.) John Prager added the code to list different userids in different colors, sort by user within tree levels and beep when the processes change. Also he put more information in the popup status and replaced some of the terminal shells (like "aixterm") with user names.

Rocky Bernstein added code to restrict the process tree to a single selectable user process, added even more info in the popup about a process (via "ps"), all the other dialogs, sorting by userid and process ID, the Motif scroll window canvas, toggle buttons, and this initial manual page. He also ported to Solaris and Linux, wrote the current tree-layout algorithm, and did major restructuring and rewriting to separate the code into machine-dependent components in separate directories. He revised to use "autoconf" and generate machine-dependent signal lists.

Kazuki Sakamoto (sakamoto@cec.co.jp, sakamoto@netbsd.org) ported to NetBSD. See also the file THANKS for a more complete list of contributors.