Man Linux: Main Page and Category List

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