--- name: "gps" section: "1x" platform: "linux" package: "gps" version: "1.1.0.0-2" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/gps/1x" --- # gps(1x) graphical tool to report process status ## NAME gps - graphical tool to report process status ## SYNOPSIS 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**\] ## 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 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. ## 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 **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**. ## EXTENDED KILL MODE **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\\\[\\] \[-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. ## 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 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. ## 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 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. ## 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 hundredths 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 i386, 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). ## FILTERING **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**\ **\ \ ago** where **\** 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\<\=1.2.9. **Linux**: none that I know of. ## UNRESTRICTIONS **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**. ## FILES 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*\ ## AUTHORS **gps** was written by Felipe Bergo \, with contributions from Beat Christen (Network watch ideas, rtop) \ ## WEB SITE http://gps.seul.org ## SEE ALSO [**proc**(5)](/proc/5.md), [**signal**(7)](/signal/7.md), [**ps**(1)](/ps/1.md), [**top**(1)](/top/1.md), [**renice**(8)](/renice/8.md), [**kill**(1)](/kill/1.md), [**rpm**(8)](/rpm/8.md), [**rgpsp**(1)](/rgpsp/1.md)