gpm
GPM(8) GPM(8)
NAME
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 applications 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
replacement for "selection" as a cut-and-paste mechanism; it also pro-
vides 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 information.
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 com-
mand-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 appli-
cation 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.
SPECIAL COMMANDS
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 capabil-
ity 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 but-
ton -- 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 con-
sole (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 corresponding to the button is exe-
cuted.
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 processing and
allows to change the three special commands. To accept the default com-
mands 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 particu-
lar operation is supported, 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
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 com-
mands, 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:
-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 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/pro-
file' 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 (especially within Emacs). All the button permuta-
tions 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 button with tap-
ping. 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.
-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 selec-
tion is cut.
-m filename
Choose the mouse file to open. It defaults to `/dev/mouse'.
-M Enable multiple mode. The daemon will read two different 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 earlier 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 sometimes confusing.
The default is not to show 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 principle, 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 translation. 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 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 but-
tons 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 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 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'. This problem doesn't apply to serial mice.
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 hid-
den 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 develop-
ment 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 informa-
tion on the list and CVS is in the README file part of the source dis-
tribution 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.
4th Berkeley Distribution July 2000 GPM(8)
