GPS(1x) User Manuals GPS(1x)NAMEgps - graphical tool to report process status
SYNOPSISgps [-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]
DESCRIPTION
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 Net‐
work 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 but‐
tons, 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 com‐
mand 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 supe‐
ruser 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.
COMMAND-LINE OPTIONS
-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 Net‐
work | 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 avail‐
able. 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 repre‐
senting 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 stan‐
dard output and exit.
--version
same as -v.
EXTENDED KILL MODEgps provides a mode where it emulates the kill command with some fil‐
tering extras. In Extended Kill Mode (EKM) gps will not open any graph‐
ical 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 (includ‐
ing 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, supresses 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.
EKM RETURN VALUE
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 suc‐
cessfully. 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.
EKM EXAMPLES
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.
QUICKBAR MODE
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 histo‐
ries 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 cen‐
tered (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.
FIELD DESCRIPTIONS
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 hundreths of seconds of the process's possible timeslice.
Start The process' start time.
FIELD DESCRIPTIONS FOR THE DETAILS DIALOG
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).
FILTERINGgps 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 mem‐
ory 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 com‐
piled this in that 64/128/(256<<n)-bit Linux box you got getting dust
in the corner.
NETWORK WATCHgps allows the watching of processes on remote machines. These machines
must be running a special poller (see rgpsp(1)) that will gather infor‐
mation on each host. The Network contains the commands needed to set up
the watched hosts. The host configuration is saved in the ~/.gpsrc
file.
RANDOM NOTES
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 infor‐
mation.
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+ applica‐
tion) will need to be relinked with the new library.
PORTABILITYgps works on Linux (all architectures) and FreeBSD (i386 only). It may
work under other POSIX systems using the rather limited piped top
poller.
BUGS
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.
UNRESTRICTIONSgps 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.
FILES
The file paths stated below assume gps was installed in the default
installation prefix, /usr/local. If you installed gps from a RPM pack‐
age 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
AUTHORSgps was written by Felipe Bergo <bergo@seul.org>, with contributions
from Beat Christen (Network watch ideas, rtop) <spiff@seul.org>
WEB SITE
http://gps.seul.org
SEE ALSOproc(5), signal(7), ps(1), top(1), renice(8), kill(1), rpm(8), rgpsp(1)Linux March 2002 GPS(1x)
