Provided by: gpm_1.20.7-11_amd64 bug

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.

SEE ALSO

        gpm-types(7)  Description of current pointer types supported by gpm

       The info file about `gpm', which gives more complete information and explains how to write
       a gpm client.