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 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 ear-
	      lier gpm versions; note however that using  -o  dtr
	      associated  with	non-plain-serial  mouse types may
	      now generate an error.

       -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'.
	      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 (``*'').

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



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

       Many many contributors, to both selection and gpm.



MAINTAINERS
       The  maintainers	 are Alessandro Rubini and Ian Zimmerman.
       The development mailing list (and the CVS tree) are hosted
       by  Prosa  Srl,	which  we  thank. The mailing list can be
       reached as gpm@prosa.it.	 More information on the list and
       CVS  is in the README file part of the source distribution
       of gpm.


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.



			   January 2000				7





GPM(8)							   GPM(8)


	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.





















































			   January 2000				8


