gpm - a cut and paste utility and mouse server for virtual consoles
gpm [ options ]
This package tries to be a useful mouse server for applications running on the Linux con-
sole. It is based on the "selection" package, and some of its code comes from selection
itself. This package is intended as a replacement for "selection" as a cut-and-paste mech-
anism; it also provides additional facilities. The "selection" package offered the first
cut-and-paste implementation for Linux using two mouse buttons, and the cut buffer is
still called "selection buffer" or just "selection" throughout this document. The infor-
mation below is extracted from the texinfo file, which is the preferred source of informa-
The `gpm' executable is meant to act like a daemon (thus, `gpmd' would be a better name
for it). This section is meant to describe the command-line options for `gpm', while its
internals are outlined in the next section.
Due to restrictions in the `ioctl(TIOCLINUX)' system call, `gpm' must be run by the supe-
ruser. The restrictions have been added in the last 1.1 kernels to fix a security hole
related to selection and screen dumping.
The server can be configured to match the user's taste, and any application using the
mouse will inherit the server's attitude. From release 1.02 up to 1.19.2 is was possible
for any user logged on the system console to change the mouse feeling using the -q option.
This is no longer possible for security reasons.
As of 0.97 the server program puts itself in the background. To kill `gpm' you can just
reinvoke it with the `-k' cmdline switch, although `killall gpm' can be a better choice.
Version 1.10 adds the capability to execute special commands on certain circumstances.
Special commands default to rebooting and halting the system, but the user can specify
his/her personal choice. The capability to invoke commands using the mouse is a handy one
for programmers, because it allows to issue a clean shutdown when the keyboard is locked
and no network is available to restore the system to a sane state.
Special commands are toggled by triple-clicking the left and right button -- an unlikely
event during normal mouse usage. The easiest way to triple-click is pressing one of the
buttons and triple-click the other one. When special processing is toggled, a message
appears on the console (and the speaker beeps twice, if you have a speaker); if the user
releases all the buttons and presses one of them again within three seconds, then the spe-
cial command corresponding to the button is executed.
The default special commands are:
Reboot the system by signalling the init process
middle button (if any)
Execute `/sbin/shutdown -h now'
Execute `/sbin/shutdown -r now'
The `-S' command line switch enables special command processing and allows to change the
three special commands. To accept the default commands use `-S ""' (i.e., specify an empty
argument). To specify your own commands, use a colon-separated list to specify commands
associated to the left, middle and right button. If any of the commands is empty, it is
interpreted as `send a signal to the init process'. This particular operation is sup-
ported, in addition to executing external commands, because sometimes bad bugs put the
system to the impossibility to fork; in these rare case the programmer should be able to
shutdown the system anyways, and killing init from a running process is the only way to do
As an example, `-S ":telinit 1:/sbin/halt"', associates killing init to the left button,
going single user to the middle one, and halting the system to the right button.
System administrators should obviously be careful about special commands, as gpm runs with
superuser permissions. Special commands are best suited for computers whose mouse can be
physically accessed only by trusted people.
COMMAND LINE OPTIONS
Available command line options are the following:
Set the acceleration value used when a single motion event is longer than delta
Start up with selection pasting disabled. This is intended as a security measure;
a plausible attack on a system seems to be to stuff a nasty shell command into the
selection buffer (`rm -rf /') including the terminating line break, then all the
victim has to do is click the middle mouse button .. As of version 1.17.2, this
has developed into a more general aging mechanism; the gpm daemon can disable (age)
selection pasting automatically after a period of inactivity. To enable this mode
just give the optional limit parameter which is interpreted as the time in seconds
for which a selection is considered valid and pastable. As of version 1.15.7, a
trivial program called `disable-paste' is provided. The following makes a good
addition to `/etc/profile' if you allow multiple users to work on your console.
`case $( /usr/bin/tty ) in
/dev/tty[0-9]*) /usr/bin/disable-paste ;;
Set the baud rate.
Set the button sequence. `123' is the normal sequence, `321' can be used by left-
handed people, and `132' can be useful with two-button mice (especially within
Emacs). All the button permutations are allowable.
Set the delta value. When a single motion event is longer than delta, accel is used
as a multiplying factor. (Must be 2 or above)
-D Do not automatically enter background operation when started, and log messages to
the standard error stream, not the syslog mechanism. This is useful for debugging;
in previous releases it was done with a compile-time option.
With glidepoint devices, emulate the specified button with tapping. number must be
`1', `2', or `3', and refers to the button number before the `-B' button remapping
is performed. This option applies to the mman and ps2 decoding. No button is emu-
lated by default because the ps2 tapping is incompatible with some normal ps2 mice
-h Print a summary of command line options.
Set interval to be used as an upper time limit for multiple clicks. If the interval
between button-up and button-down events is less than limit, the press is consid-
ered a double or triple click. Time is in milliseconds.
-k Kill a running gpm. This can be used by busmouse users to kill gpm before running X
(unless they use `-R' or the single-open limitation is removed from the kernel).
Choose the `inword()' look up table. The charset argument is a list of characters.
`-' is used to specify a range and `\ ' is used to escape the next character or to
provide octal codes. Only visible character can appear in charset because control
characters can't appear in text-mode video memory, whence selection is cut.
Choose the mouse file to open. It defaults to `/dev/mouse'.
-M Enable multiple mode. The daemon will read two different mouse devices. Any subse-
quent option will refer to the second device, while any preceding option will be
used for the first device. This option automatically forces the repeater (`-R')
The option works similary to the ``-o'' option of mount; it is used to specify a
list of ``extra options'' that are specific to each mouse type. The list is comma-
separated. The options `dtr', `rts' or `both' are used by the serial initialization
to toggle the modem lines like, compatibly with earlier gpm versions; note however
that using -o dtr associated with non-plain-serial mouse types may now generate an
-p Forces the pointer to be visible while selecting. This is the behaviour of `selec-
tion-1.7', but it is sometimes confusing. The default is not to show the pointer,
which can be confusing as well.
Set the responsiveness. A higher responsiveness is used for a faster cursor motion.
Causes `gpm' to act as a repeater: any mouse data received while in graphic mode
will be produced on the fifo `/dev/gpmdata' in protocol name. In principle, you
can use the same names as for the `-t' option, although repeating into some proto-
cols may not be implemented for a while. In addition, you can specify `raw' as the
name, to repeat the mouse data byte by byte, without any protocol translation. If
name is omitted, it defaults to `msc'. Using gpm in repeater mode, you can config-
ure the X server to use its fifo as a mouse device. This option is useful for bus-
mouse owners to override the single-open limitation. It is also an easy way to man-
age those stupid dual-mode mice which force you to keep the middle button down
while changing video mode. The option is forced on by the `-M' option.
Set the sample rate for the mouse device.
Enable special-command processing, and optionally specify custom commands as a
colon-separated list. See above for a detailed description of special commands.
Set the mouse type. Use `-t help' to get a list of allowable types. Since version
1.18.1, the list also shows which protocols are available as repeaters (see -R
above), by marking them with an asterisk (``*'').
-v Print version information and exit.
-V verbosity increment
Raise or decrease the maximum level of messages that will be logged. Thus a posi-
tive argument has the effect of making the program more verbose. One can also give
a negative argument to hush the program; however, note that due to getopt(3) rules
a negative argument must follow the option with no space betwixt (that is, `-V-1'
but not `-V -1'). The argument is optional and its default value is 1. Default
verbosity level is 5 (`LOG_NOTICE').
-2 Force two buttons. This means that the middle button, if any, will be taken as it
was the right one.
-3 Force three buttons. By default the mouse is considered to be a 2-buttons one,
until the middle button is pressed. If three buttons are there, the right one is
used to extend the selection, and the middle one is used to paste it. Beware: if
you use the `-3' option with a 2-buttons mouse, you won't be able to paste the
To select text press the left mouse button and drag the mouse. To paste text in the same
or another console, press the middle button. The right button is used to extend the
selection, like in `xterm'.
Two-button mice use the right button to paste text.
Double and triple clicks select whole word and whole lines. Use of the `-p' option is rec-
ommended for best visual feedback.
If a trailing space after the contents of a line is highlighted, and if there is no other
text on the remainder of the line, the rest of the line will be selected automatically. If
a number of lines are selected, highlighted trailing spaces on each line will be removed
from the selection buffer.
Any output on the virtual console holding the selection will clear the highlighted selec-
tion from the screen, to maintain integrity of the display, although the contents of the
paste buffer will be unaffected.
The selection mechanism is disabled if the controlling virtual console is placed in graph-
ics mode, for example when running X11, and is re-enabled when text mode is resumed. (But
see BUGS section below.)
The `gpm' server may have problems interacting with X: if your mouse is a single-open
device (i.e. a bus mouse), you should kill `gpm' before starting X, or use the `-R' option
(see above). To kill `gpm' just invoke `gpm -k'. This problem doesn't apply to serial
Two instances of gpm can't run on the same system. If you have two mice use the `-M'
option (see above).
While the current console is in graphic mode, `gpm' sleeps until text mode is back (unless
`-R' is used). Thus, it won't reply to clients. Anyways, it is unlikely that mouse-eager
clients will spur out in hidden consoles.
Andrew Haylett <email@example.com> (the original selection code)
Alessandro Rubini <firstname.lastname@example.org> (new features)
Ian Zimmerman <email@example.com> (co-maintainer)
Many many contributors, to both selection and gpm.
The maintainers are Alessandro Rubini and Ian Zimmerman. The development mailing list
(and the CVS tree) are hosted by Prosa Srl, which we thank. The mailing list can be
reached as firstname.lastname@example.org. More information on the list and CVS is in the README file part
of the source distribution of gpm.
/dev/mouse The default mouse device
/var/run/gpm.pid The PID of the running gpm
/dev/gpmctl A control socket for clients
/dev/gpmdata The fifo written to by a repeater (`-R') daemon.
mev(1) A sample client for the gpm daemon.
gpm-root(1) An handler for Control-Mouse events.
The info file about `gpm', which gives more complete information and explains how to write
a gpm client.
4th Berkeley Distribution July 2000 GPM(8)