gps - graphical tool to report process status

gps [-c] [-l] [-sc column] [-sa | -sd] [-dn] [-pt] [-gb | -gl] [-v | --version]

Extended Kill Mode (EKM) syntax:

gps k<n|u|g|e|s><q|v|h>[<i|o|b>] [-signal] match-text [match-text ...]

Quickbar Mode syntax:

gps -qb [top | bottom] [left | center | right] [-w width] [-r]

This man page documents version 1.0.1 of gps on the "Linux" operating system.

gps shows the list of processes in the machine it is run. It may refresh continuously every second or wait for refresh requests from the user. It also shows gauges and history for CPU and memory usage. It is also possible to watch processes on remote computers when the Network Watch feature is enabled.

The default behavior is to refresh only when the user clicks the Refresh button.

Alternatively, gps may send signals to some processes and exit without opening any graphical interface, see Extended Kill Mode section for details.

Processes may be selected in the list (one at a time) so that the user may send it SIGHUP and SIGKILL signals with the Hang Up and Kill buttons, respectively, or renice it with the Renice... command from the Action menu. Read the signal (7) man page before using the Send POSIX Signal command in the Action menu if you don't know what each of those signals mean. Remote processes cannot be killed, signaled or reniced, for security reasons.

To hide some fields (columns) of the process list or change the auto-refresh interval you can use the View | Settings... command.

To show the details of the selected process double-click it in the list, press Enter, or choose the Details... command from the Action menu.

gps sorts the list on whichever field you wish. Click the column title to sort on that column, click again to reverse sorting order. The default is to sort PIDs in ascending order if no -sc, -sd or -sa command line options are specified.

The Action menu is enabled only when a process is selected in the list. A process may only be signaled or reniced if you own it. Only the superuser may lower Nice values.

gps also filters processes via the Filter | Set filter... command. The current filtering is shown in the status bar.

To show gauges and history on CPU and memory usage use the View | CPU and memory usage... command. On multi-processor machines (SMP, Linux-only) CPU average is shown as a green bar and each individual CPU is shown as a blue bar. Each vertical range delimited by vertical bars in the histories means 240 periods (1 minute with the default 250 msec refresh interval).

To see a per-user usage of CPU and memory use the View | CPU and memory usage per user... commands. This display is refreshed once a second. The memory usage is based on the Size field, so it includes swapped out data.

To see the processes organized in a tree use the View | Tree view... command. It is not updated continuously.

-c

start in continuous refresh mode

-dn

start without connecting to the remote hosts configured through Network watch. When you use this option, the connections may be started later via Network | Restart connections or via the Network | Network watch... dialog.

-gb

Use gradient-style bars in the CPU/Memory window, instead of the stripped default.

-gl

Use gray tonalities instead of colors in diagrams, for low bit depth systems.

-l

start showing long filenames, i.e., the command-line of each process in the name field.

-pt

Use the top poller instead of the native one. The top poller provides much less information about processes, and is intended for use only in platforms where a native poller is not available. If the piped top poller isn't compiled in gps's binary, this option has no effect.

-qb

Run in quickbar mode (no process list, just bar graphs), see the Quickbar Mode section for mode-specific parameters.

-sa

sets sorting direction to ascending (lesser values on top). This is already the default if neither -sa nor -sd are specified.

-sd

sets sorting direction to descending (greater values on top)

-sc column

sorts the list on column, which is a number from 0 to 10 representing the column to sort (0=PID, 1=Name, 2=Owner, 3=Machine, 4=State, 5=%CPU, 6=Size, 7=RSS, 8=Nice, 9=Pri, 10=Start). When this parameter is not specified gps sorts on the PID column.

-v

causes gps to print version and copyright information to standard output and exit.

--version

same as -v.

gps provides a mode where it emulates the kill command with some filtering extras. In Extended Kill Mode (EKM) gps will not open any graphical interface elements. The syntax to call gps in EKM mode is

gps k<filter type><verbosity>[<pipe-mode>] [-signal] text [text ...]

where:

Filter Type is one of these:

n

kill by PID, text arguments are PID values. gps will select/signal all processes that match the given PIDs.

u

kill by owner, text are user names. gps will select/signal all processes that are owned by given user names.

g

kill by group, text are group names. gps will select/signal all processes that are owned by users of the given groups.

e

kill by exact name match, text is free form text. gps will select/signal all processes whose name matches exactly (including case) any of given text values.

s

kill by substring match in name/long name, text is free form text. gps will select/signal all processes whose names or long names (command line) contain any of the given text values as substrings.

Verbosity

is one of these:

q

Quiet. Work silently.

v

Verbose. Will print a summary of successes and the count of processes that matched the filter.

h

High Verbosity. Will list progress of each matched process, as well as some process information. The number inside parenthesis is the return value of the kill function, 0 means success, -1 means error.

Pipe mode

is only needed when piping several gps instances in EKM. It is one of these:

o

Output to pipe, suppresses normal output (verbosity is ignored) and formats output to serve as input to a gps process in EKM.

i

Input from pipe, reads a list of pre-filtered PIDs from stdin, usually coming from another gps process in EKM.

b

Both (Input from pipe, Output to pipe), combines i mode and o mode.

-signal

Indicates which signal to send to processes that match the criteria. If not specified, -HUP (SIGHUP) is sent. Only the last command in a sequence of piped gps in EKM need to specify this. -signal is one of -HUP, -INT, -QUIT, -ILL, -ABRT, -FPE, -KILL, -SEGV, -PIPE, -ALRM, -TERM, -USR1, -USR2, -CHLD, -STOP, -CONT, -TSTP, -TTIN, -TTOU.

gps's return value (in EKM) depends on the success of process matching and killing: It returns 0 (full success) when at least one process matched the criteria and all processes that matched were signaled successfully. Returns 1 (partial success) when at least one process matched the criteria and at least one was signaled successfully. Returns 2 (failure) when at least one process matched the criteria but no one could be signaled. Returns 3 (not found) when no process matched the criteria.

Kill all processes owned by user trindade with SIGKILL:

gps kuv -KILL trindade

Kill all xboard processes owned by people from group nib with SIGSEGV:

gps keqo xboard | gps kgvi -SEGV nib

Kill all snes9x processes owned by user ricbit that contain the FF5.SMC string in the command line with SIGTERM:

gps kuqo ricbit | gps keqb snes9x | gps ksvi -TERM FF5.SMC

Netscape browsers are so reliable that you'll never need this one:

gps ksq -KILL netscape

Note on pipe modes: the first process in the pipe sequence must be in o mode, all processes but first and last must be in b mode, and the last process must be in i mode.

Note on self-mutilation: gps will not kill gps processes in EKM.

The -qb command-line switch runs gPS in quickbar mode, where gPS is only a tiny window with bar graphs for CPU, Memory and Swap usage. Clicking on the graph window switches between the bar graph and histories for each of the resources measured. There are some command-line parameters specific to this mode:

top

vertical alignment, places the graph window at the top of the screen.

bottom

vertical alignment, places the graph window at the bottom of the screen (default).

left

horizontal alignment, places the graph window at the left of the screen.

center

horizontal alignment, places the graph window horizontally centered (default).

right

horizontal alignment, places the graph window at the right of the screen.

-w width

specifies the width of the window, in pixels. If not specified, defaults to 256 pixels. Maximum value is 1024.

-r

makes the graph window be a regular window (with decorations) instead of a topmost popup.

PID

The unique (per machine) id number of each process.

Name

The process' name or command-line, depending on the Show long process names setting in the View menu.

Owner

The process owner's username.

Machine

The host where the process is running.

State

The process' current state, made up of 3 fields. The first field is R for runnable, S for sleeping, D for uninterruptible sleep, T for stopped or traced, or Z for a zombie process. The second field contains W if the process has no resident pages. The third field is N if the process has a positive nice value (Nice field).

%CPU

shows the cputime/realtime percentage. It will not add up to 100% unless you are lucky. It is time used divided by the time the process has been running.

Size

The process' memory fingerprint. It is (code+data+stack).

RSS

The amount of Size (code+data+stack) currently in memory.

Nice

Standard unix nice value; a positive value means less cpu time.

Pri

This is the counter field in the task struct. It is the time in hundredths of seconds of the process's possible timeslice.

Start

The process' start time.

The details dialog shows many "gut" details of processes. Some fields are redundant with the main window list, others are explained below.

Jiffies - some fields show values in jiffies. One jiffy is 1/100 of a second.

PPID

The unique id number of a process' parent.

Flags

Various flags set for each process. These are:

ALIGNWARN

Process will print alignment warning messages.

STARTING

Process is starting.

EXITING

Process is dying.

PTRACED

Set when ptrace(0) is called.

TRACESYS

Tracing system calls.

FORKNOEXEC

Process forked but did not exec. This is not either an error or bad.

SUPERPRIV

Process used super-user privileges.

DUMPCORE

Process dumped core and left someone unhappy.

SIGNALED

Process was killed by a signal.

MEMALLOC

Process is allocating memory.

VFORK

Wake up parent in mm_release. If you understand it, document better.

USEDFPU

Task used FPU in its last timeslice.

DTRACE

Process uses delayed trace (used on 1, m68k).

RSS Limit

The limit on RSS size, usually 2 GB.

Minor Faults (Process / Children)

Minor faults are page faults that do not require loading the missing pages from disk.

Major Faults (Process / Children)

Major faults are page faults that require loading the missing pages from disk.

Maximum jiffies in next timeslice

This is the Pri value from the main list.

Please mind that the values in the details dialog are static (they are not refreshed continuously, not even when the main list is).

gps decides which processes to include in the list (when a filter is set) by comparison with a value, as set in the Set filter... dialog. To enter values use the same notation used in the table, i.e.:

Memory: 420K

The start time field has special input. Aside from accepting values as those in the list, it will accept the following syntax

today

yesterday

<number> <time-unit> ago

where <time-unit> can be: seconds, minutes, hours, days, weeks, months, years. Both plural and singular forms are accepted. Examples of valid input:

5 days ago

1 month ago

The other fields are compared numerically / lexicographically as expected.

Special note on memory filtering: memory is formatted with suffixes K, M, G, T, P to indicate Kilo, Mega, Giga, Tera and Peta, and no suffix to indicate byte values. gps uses a higher unit if the numeric value is higher than 99K (99<<10). So the M suffix will be used whenever a memory size is greater than (99K)K=99M and K is used when size is greater than 99K. gps considers a K-ended memory string always lesser than an M-ended string and so on. As most processes use more than 99K but less than 99M of memory (and most of the exceptions use 0), using K-ended strings should give you the filtering you want.

Second note on memory: on 32-bit x86 machines you'll never get T or P memory strings. I just included Tera and Peta in case you there compiled this in that 64/128/(256<<n)-bit Linux box you got getting dust in the corner.

gps allows the watching of processes on remote machines. These machines must be running a special poller (see rgpsp(1)) that will gather information on each host. The Network contains the commands needed to set up the watched hosts. The host configuration is saved in the ~/.gpsrc file.

Different polling methods may provide different values for the same thing, especially memory. The concept of free memory is not clear and some pollers may include caches and buffers in "free memory", while others may not. Usually the native poller provides more accurate information.

gps uses the gtk+ library (The Gimp Toolkit, http://www.gtk.org). If someday gps stops working, says something funny about library versions and refuses to run, you may have installed a different version of the gtk+ shared library files, and gps (as well as any other gtk+ application) will need to be relinked with the new library.

gps works on Linux (all architectures) and FreeBSD (i386 only). It may work under other POSIX systems using the rather limited piped top poller.

FreeBSD: FreeBSD's process 0 makes a little mess with the tree view. The piped top poller won't work with FreeBSD's top, but as there is a native poller for FreeBSD, you don't need it. Also, GTK+ 1.2.9 won't allow GTK setuid-root applications, so you won't (probably) be able to run gPS+FreeBSD+GTK>=1.2.9.

Linux: none that I know of.

gps is free; anyone may redistribute copies of gps to anyone under the terms stated in the GNU General Public License. A copy of the license accompanies each copy of gps.

The file paths stated below assume gps was installed in the default installation prefix, /usr/local. If you installed gps from a RPM package the default prefix is /usr.

~/.gpsrc

/usr/local/doc/gps-1.0.1/README

/usr/local/doc/gps-1.0.1/INSTALL

/usr/local/doc/gps-1.0.1/COPYING

/usr/local/share/icons/xray-tux.xpm

gps was written by Felipe Bergo <bergo@seul.org>, with contributions from Beat Christen (Network watch ideas, rtop) <spiff@seul.org>

http://gps.seul.org

proc(5), signal(7), ps(1), top(1), renice(8), kill(1), rpm(8), rgpsp(1)