GPM linux command manual

GPM(8)                                                                     GPM(8)

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

       gpm [ options ]

       This  package  tries to be a useful mouse server for applications run-
       ning 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  mecha-
       nism;  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

       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

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

       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 kil-
       lall gpm can be a better choice.

       Version 1.10 adds the capability to execute special commands  on  cer-
       tain  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 pro-
       grammers, 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 corresponding to the button is

       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  associ-
       ated  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 impossibil-
       ity to fork; in these rare case the programmer should be able to shut-
       down 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.

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

              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  vic-
              tim  has  to do is click the middle mouse button ..  As of ver-
              sion 1.17.2, this has developed into a more general aging mech-
              anism; the gpm daemon can disable (age) selection pasting auto-
              matically 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  selec-
              tion 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 ;;

       -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-but-
              ton 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

       -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 num-
              ber 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  nor-
              mal 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 charac-
              ters 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  tog-
              gle 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

       -r number
              Set  the  responsiveness. A higher responsiveness is used for a
              faster cursor motion.

              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 cus-
              tom 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  proto-
              cols are available as repeaters (see -R above), by marking them
              with an asterisk (''*'').

              Use -t after you selected the mouse device with -m.

       -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; due to getopt(3) rules, any optional argument
              needs to be passed without a space in between!   When  omitting
              the  argument,  the increment defaults to 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
              buttons  are  there, the right one is used to extend the selec-
              tion, 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.

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

       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.

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

       Andrew Haylett  (the original selection code)
       Ian Zimmerman  (old maintainer)
       Alessandro Rubini  (old maintainer (still helps a lot))
       Nico Schottelius  (maintainer)

       Many many contributors, to both selection and gpm.

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

       /var/run/ The PID of the running gpm
       /dev/gpmctl     A control socket for clients
       /dev/gpmdata    The fifo written to by a repeater ('-R') daemon.

        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       February 2002                          GPM(8)