gpm



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




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 capabil-
       ity 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 but-
       ton  -- 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 con-
       sole (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  exe-
       cuted.


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




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 con-
              sidered  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-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
              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  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 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 lim-
              itation 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 cant 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. 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,  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. Since version 1.18.1, the list also shows which protocols
              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 but-
              tons 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. Any-
       ways,  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 poten-
       tial 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  him
       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

        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)

Man(1) output converted with man2html