Ubuntu Manpage: gpm - a cut and paste utility and mouse server for virtual consoles

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 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
       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 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 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
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 special command corresponding 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 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 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 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:

-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 (no space in between !) 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 ;;
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
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 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 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. Must be before -t and -o.

-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 similarly 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. And by the way, use -o after -m and after -t.

-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 as a percentage of motion (1 to 100, default 10). A lower number can be
used to slow down cursor motion, this can not be used to make a mouse move faster, see `-a'.

-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, given as an optional argument (no space in between
!). 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. Use -t after you selected the
mouse device with -m.

-v Print version information and exit.

-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 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 hidden
       consoles.

       The clients shipped out with gpm are not updated, thus there are  potential  security  risks  when  using
       them.

AUTHORS

       Andrew Haylett <ajh@gec-mrc.co.uk> (the original selection code)
       Ian Zimmerman <itz@speakeasy.org> (old maintainer)
       Alessandro Rubini <rubini@linux.it> (old maintainer (still helps a lot))
       Nico Schottelius <nico@schottelius.org> (maintainer)

       Many many contributors, to both selection and gpm.

MAINTAINERS

       The  current  maintainer  is  Nico Schottelius. But without the help of Alessandro Rubini and the mailing
       list it would be impossible for me to maintain gpm. The development mailing list  can  be  reached  under
       gpm@lists.linux.it. More information on the list is in the README file part of the source distribution of
       gpm.

FILES

       /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.