gpm - a cut and paste utility and mouse server for virtual
consoles
SYNOPSIS
gpm [ options ]
DESCRIPTION
This package tries to be a useful mouse server for appli
cations running on the Linux console. It is based on the
"selection" package, and some of its code comes from
selection itself. This package is intended as a replace
ment for "selection" as a cut-and-paste mechanism; 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 information below is extracted from
the texinfo file, which is the preferred source of infor
mation.
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 superuser. 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 back
ground. To kill `gpm' you can just reinvoke it with the
`-k' cmdline switch, although `killall gpm' can be a bet
ter choice.
SPECIAL COMMANDS
Version 1.10 adds the capability to execute special com
mands 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
because it allows to issue a clean shutdown when the key
board 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 special command cor
responding to the button is executed.
The default special commands are:
left button
Reboot the system by signalling the init process
middle button (if any)
Execute `/sbin/shutdown -h now'
right button
Execute `/sbin/shutdown -r now'
The `-S' command line switch enables special command pro
cessing 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 supported, in addi
tion 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 it.
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.
Available command line options are the following:
-a accel
Set the acceleration value used when a single
motion event is longer than delta (see `-d').
-A [limit]
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 com
mand into the selection buffer (`rm -rf /') includ
ing 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 inter
preted 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 ;;
esac'
-b baud
Set the baud rate.
-B sequence
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 (espe
cially within Emacs). All the button permutations
are allowable.
-d delta
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.
-g number
With glidepoint devices, emulate the specified
`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
emulated by default because the ps2 tapping is
incompatible with some normal ps2 mice
-h Print a summary of command line options.
-i interval
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 considered 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).
-l charset
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.
-m filename
Choose the mouse file to open. It defaults to
`/dev/mouse'.
-M Enable multiple mode. The daemon will read two dif
ferent mouse devices. Any subsequent 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')
option on.
-o list-of-extra-options
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 ear
lier gpm versions; note however that using -o dtr
associated with non-plain-serial mouse types may
now generate an error.
-p Forces the pointer to be visible while selecting.
This is the behaviour of `selection-1.7', but it is
the pointer, which can be confusing as well.
-r number
Set the responsiveness. A higher responsiveness is
used for a faster cursor motion.
-R name
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 prin
ciple, you can use the same names as for the `-t'
option, although repeating into some protocols 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 transla
tion. If name is omitted, it defaults to `msc'.
Using gpm in repeater mode, you can configure 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 manage 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.
-s number
Set the sample rate for the mouse device.
-S commands
Enable special-command processing, and optionally
specify custom commands as a colon-separated list.
See above for a detailed description of special
commands.
-t name
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 positive argument has
the effect of making the program more verbose. One
can also give a negative argument to hush the pro
gram; 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').
ton, if any, will be taken as it was the right one.
-3 Force three buttons. By default the mouse is con
sidered 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 selection.
OPERATION
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 recommended for best
visual feedback.
If a trailing space after the contents of a line is high
lighted, and if there is no other text on the remainder of
the line, the rest of the line will be selected automati
cally. 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 selection 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 graphics mode, for example
when running X11, and is re-enabled when text mode is
resumed. (But see BUGS section below.)
BUGS
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'.
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.
AUTHORS
Andrew Haylett <ajh@gec-mrc.co.uk> (the original selection code)
Alessandro Rubini <rubini@linux.it> (new features)
Ian Zimmerman <itz@speakeasy.org> (co-maintainer)
Many many contributors, to both selection and gpm.
MAINTAINERS
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 gpm@prosa.it. More information on the list and
CVS is in the README file part of the source distribution
of gpm.
FILES
/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.
SEE ALSO
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.
Man(1) output converted with
man2html