gpm

GPM(1)                      General Commands Manual                     GPM(1)



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 heavily based on the "selection" package,
       and quite a good deal of code comes from selection itself. This package
       is intended as a replacement for "selection", to provide additional
       facilities.  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), in just the same way as selection used to. This
       section is meant to describe the command-line options for gpm, while
       its internals are outlined in the next section.  Gpm Internals.


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


       No user-wide configuration file is provided, because the mouse is a
       machine-wide resource. If you feel that different users on a Linux
       machine could benefit from personal mouse setup at login, feel free to
       email me, and I'll look about it. As of this release, only the inword()
       look up table can be changed without restarting the server (but to be
       able to do it, you have to install gpm with the "set-user-id" bit
       turned on).


       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.


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
       capability 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
       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
       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 commandline 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 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 s:/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.

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

       -D     Dirty operation (debug only). It causes gpm to kill an already
              running gpm, if any. The default behaviour is to not kill it.
              Bugs and Problems.

       -g number
              With glidepoint devices, emulate the specified button 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).

       -K     Run kernel-mouse. /dev/kmouse is configured according to the
              other command line options, and the gpm functionality is run in
              kernel space. This requires the kmouse module, currently
              available from tsx-11.mit.edu. This is experimental.

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

       -L charset
              Modify the  inword() look up table. This option is obsolete and
              will be dropped soon. Use ``-q -l'' instead.

       -m filename
              Choose the mouse file to open. It defaults to /dev/mouse.

       -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 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) 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 nonetheless 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     Causes gpm to act as a repeater: any mouse data received while
              in graphic mode will be produced on the fifo /dev/gpmdata in
              mouse-system protocol. 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. Mouse Types.

       -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
              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 wird 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, and with
       selection.


       With X11 gpm has the same problems as selection. If your mouse is a
       single-open device (i.e. a bus mouse), you should kill gpm before
       strating X, or use the ``-R'' option (see above).  To kill gpm just
       invoke gpm -k. This doesn't apply to serial mice.


       gpm and selection can't run together, because they will contend the
       mouse. They can control two mice independently, however.


       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. Thus, it won't reply to clients. Anyways, it is unlikely
       that mouse-eager clients will spur out in hidden consoles. This is not
       true if gpm acts as a repeater.


       pre-1.0 gpm releases have problems with kernel 1.2.9 and later, because
       the clients must have write permission on the node /var/run/gpmctl. You
       should invoke chmod on the node or install gpm-1.0 or later (you have
       this docs, you have the software).


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

       Many many contributors, to both selection and gpm.


FILES
       /dev/mouse      The default mouse device
       /var/run/gpmpid The PID of the running gpm
       /var/run/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 1995                          GPM(1)