gpm man page on aLinux

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
aLinux logo
[printable version]

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

       -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 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
	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)
[top]

List of man pages available for aLinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net