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  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. Beginning from release 1.02, the mouse
       feeling can be reconfigured by each user  logging  on  the
       system console.  Server Invocation, for the description of
       `-q'.

       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
       commands  using  the mouse is a handy one for programmers,
       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.

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 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 to execute `gpm -A -q'.  This  is  because
              the  last  command, like `gpm -q' in general, needs
              root privilege; `disable-paste' is installed setuid
              to  root.   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 but-
              ton 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.  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 lines
              Toggle modem  lines.  The  lines  argument  can  be
              `dtr',  `rts'  or  `both'.  This is needed for some
              strange serial mice.

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

       -q     Quit   after  changing  mouse  behaviour.  This  is
              intended to allow users to change the mouse feeling
              (`-a',  `-B',  `-d',  `-i', `-l', `-p', `-r', `-V',
              `-A') without restarting  the  server.  Since  this
              needs  root  permissions, the system administrators
              can use the `set-uid' bits to  enable/disable  such
              capability.  Changing  mouse parameters is nonethe-
              less only allowed from one of the virtual consoles.
              Options are transferred only for the first mouse.

       -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'.
              This  means  that you can configure the X server to
              use that 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.

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

       -2     Force  two buttons. This means that the middle but-
              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'.
       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.

       pre-1.0  gpm  releases have problems with kernel 1.2.9 and
       later, because the clients must have write  permission  on
       the  node  `/dev/gpmctl'. You should invoke `chmod' on the
       node or install `gpm-1.0' or later (you  have  this  docu-
       ment, you have the updated software).

AUTHORS
       Andrew Haylett <ajh@gec-mrc.co.uk> (the original selection code)
       Alessandro Rubini <rubini@linux.it> (new features)

       Many many contributors, to both selection and gpm.

MAINTAINERS
       Beginning  with  version  1.14  I  release exclusive main-
       tainance. Ian Zimmerman and Prosa Inc. are going  to  sup-
       port  gpm  development.  The official contact point is now
       the mailing list <gpm@animal.unipv.it>, thanks to my  Uni-
       versity  which  generously hosts gpm discussions. The list
       is managed by SmartList and anyone is welcome.

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.

                          February 1995                         1