1GPM(8)                      System Manager's Manual                     GPM(8)
2
3
4

NAME

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

SYNOPSIS

9       gpm [ options ]
10

DESCRIPTION

12       This package tries to be a useful mouse server for applications running
13       on the Linux console.  It is based on the "selection" package, and some
14       of  its code comes from selection itself. This package is intended as a
15       replacement for "selection" as a cut-and-paste mechanism; it also  pro‐
16       vides  additional facilities. The "selection" package offered the first
17       cut-and-paste implementation for Linux using two mouse buttons, and the
18       cut  buffer  is  still  called  "selection  buffer" or just "selection"
19       throughout this document.  The information below is extracted from  the
20       texinfo file, which is the preferred source of information.
21
22
23       The gpm executable is meant to act like a daemon (thus, gpmd would be a
24       better name for it). This section is meant to describe the command-line
25       options for gpm, while its internals are outlined in the next section.
26
27
28       Due  to  restrictions  in the ioctl(TIOCLINUX) system call, gpm must be
29       run by the superuser. The restrictions have been added in the last  1.1
30       kernels to fix a security hole related to selection and screen dumping.
31
32
33       The  server can be configured to match the user's taste, and any appli‐
34       cation using the mouse will inherit the server's attitude. From release
35       1.02  up  to  1.19.2  is was possible for any user logged on the system
36       console to change the mouse feeling using the -q  option.  This  is  no
37       longer possible for security reasons.
38
39
40       As  of  0.97  the server program puts itself in the background. To kill
41       gpm you can just reinvoke it with the -k cmdline switch, although  kil‐
42       lall gpm can be a better choice.
43
44

SPECIAL COMMANDS

46       Version 1.10 adds the capability to execute special commands on certain
47       circumstances. Special commands default to rebooting  and  halting  the
48       system,  but the user can specify his/her personal choice. The capabil‐
49       ity to invoke commands using the mouse is a handy one for  programmers,
50       because it allows to issue a clean shutdown when the keyboard is locked
51       and no network is available to restore the system to a sane state.
52
53
54       Special commands are toggled by triple-clicking the left and right but‐
55       ton  -- an unlikely event during normal mouse usage. The easiest way to
56       triple-click is pressing one of the buttons and triple-click the  other
57       one.  When special processing is toggled, a message appears on the con‐
58       sole (and the speaker beeps twice, if you have a speaker); if the  user
59       releases  all  the  buttons  and presses one of them again within three
60       seconds, then the special command corresponding to the button  is  exe‐
61       cuted.
62
63
64       The default special commands are:
65
66       left button
67              Reboot the system by signalling the init process
68
69       middle button (if any)
70              Execute /sbin/shutdown -h now
71
72       right button
73              Execute /sbin/shutdown -r now
74
75
76       The  -S  command  line  switch  enables  special command processing and
77       allows to change the three special commands. To accept the default com‐
78       mands use -S "" (i.e., specify an empty argument).  To specify your own
79       commands, use a colon-separated list to specify commands associated  to
80       the  left, middle and right button. If any of the commands is empty, it
81       is interpreted as `send a signal to the init process'. This  particular
82       operation  is  supported,  in  addition to executing external commands,
83       because sometimes bad bugs put the system to the impossibility to fork;
84       in these rare case the programmer should be able to shutdown the system
85       anyways, and killing init from a running process is the only way to  do
86       it.
87
88
89       As  an  example, -S ":telinit 1:/sbin/halt", associates killing init to
90       the left button, going single user to the middle one, and  halting  the
91       system to the right button.
92
93
94       System  administrators  should  obviously be careful about special com‐
95       mands, as gpm runs with superuser  permissions.  Special  commands  are
96       best  suited  for computers whose mouse can be physically accessed only
97       by trusted people.
98
99

COMMAND LINE OPTIONS

101       Available command line options are the following:
102
103       -a accel
104              Set the acceleration value used when a single  motion  event  is
105              longer than delta (see -d).
106
107       -A[limit]
108              Start up with selection pasting disabled.  This is intended as a
109              security measure; a plausible attack on a system seems to be  to
110              stuff a nasty shell command into the selection buffer (rm -rf /)
111              including the terminating line break, then all the victim has to
112              do  is  click  the middle mouse button ..  As of version 1.17.2,
113              this has developed into a more general aging mechanism; the  gpm
114              daemon can disable (age) selection pasting automatically after a
115              period of  inactivity.   To  enable  this  mode  just  give  the
116              optional  limit  parameter  (no  space  in  between !)  which is
117              interpreted as the time in seconds for which a selection is con‐
118              sidered  valid  and  pastable.   As of version 1.15.7, a trivial
119              program called disable-paste is provided. The following makes  a
120              good  addition  to  /etc/profile  if you allow multiple users to
121              work on your console.
122
123
124       case $( /usr/bin/tty ) in
125       /dev/tty[0-9]*) /usr/bin/disable-paste ;;
126       esac
127
128       -b baud
129              Set the baud rate.
130
131       -B sequence
132              Set the button sequence. 123 is the normal sequence, 321 can  be
133              used  by left-handed people, and 132 can be useful with two-but‐
134              ton mice (especially within Emacs). All the button  permutations
135              are allowable.
136
137       -d delta
138              Set  the  delta value. When a single motion event is longer than
139              delta, accel is used as a multiplying  factor.  (Must  be  2  or
140              above)
141
142       -D     Do  not  automatically  enter background operation when started,
143              and log messages to the standard error stream,  not  the  syslog
144              mechanism.   This  is useful for debugging; in previous releases
145              it was done with a compile-time option.
146
147       -g number
148              With glidepoint devices, emulate the specified button with  tap‐
149              ping.   number must be 1, 2, or 3, and refers to the button num‐
150              ber before the -B button remapping is  performed.   This  option
151              applies  to  the mman and ps2 decoding. No button is emulated by
152              default because the ps2 tapping is incompatible with some normal
153              ps2 mice
154
155       -h     Print a summary of command line options.
156
157       -i interval
158              Set  interval  to  be  used  as an upper time limit for multiple
159              clicks. If the interval between button-up and button-down events
160              is  less  than limit, the press is considered a double or triple
161              click. Time is in milliseconds.
162
163       -k     Kill a running gpm. This can be used by busmouse users  to  kill
164              gpm before running X (unless they use -R or the single-open lim‐
165              itation is removed from the kernel).
166
167       -l charset
168              Choose the inword() look up table. The  charset  argument  is  a
169              list  of characters. - is used to specify a range and \  is used
170              to escape the next character or to provide  octal  codes.   Only
171              visible  character can appear in charset because control charac‐
172              ters can't appear in text-mode video memory, whence selection is
173              cut.
174
175       -m filename
176              Choose the mouse file to open. Must be before -t and -o.
177
178       -M     Enable  multiple  mode. The daemon will read two different mouse
179              devices.  Any subsequent option will refer to the second device,
180              while  any  preceding  option will be used for the first device.
181              This option automatically forces the repeater (-R) option on.
182
183       -o list-of-extra-options
184              The option works similary to the ``-o'' option of mount;  it  is
185              used to specify a list of ``extra options'' that are specific to
186              each mouse type. The list is comma-separated. The  options  dtr,
187              rts  or both are used by the serial initialization to toggle the
188              modem lines like, compatibly with  earlier  gpm  versions;  note
189              however that using -o dtr associated with non-plain-serial mouse
190              types may now generate an error.  And by the way, use  -o  after
191              -m and after -t.
192
193
194       -p     Forces  the  pointer  to be visible while selecting. This is the
195              behaviour of selection-1.7, but it is sometimes confusing.   The
196              default  is  not  to show the pointer, which can be confusing as
197              well.
198
199       -r number
200              Set the responsiveness. A higher responsiveness is  used  for  a
201              faster cursor motion.
202
203       -R[name]
204              Causes  gpm  to act as a repeater: any mouse data received while
205              in graphic mode will be produced on  the  fifo  /dev/gpmdata  in
206              protocol  name,  given  as  an  optional  argument  (no space in
207              between !).  In principle, you can use the same names as for the
208              -t  option,  although  repeating  into some protocols may not be
209              implemented for a while.  In addition, you can  specify  raw  as
210              the  name,  to  repeat  the mouse data byte by byte, without any
211              protocol translation.  If name is omitted, it defaults  to  msc.
212              Using  gpm  in  repeater mode, you can configure the X server to
213              use its fifo as a mouse device. This option is useful  for  bus-
214              mouse  owners to override the single-open limitation. It is also
215              an easy way to manage those stupid dual-mode  mice  which  force
216              you  to  keep  the middle button down while changing video mode.
217              The option is forced on by the -M option.
218
219       -s number
220              Set the sample rate for the mouse device.
221
222       -S commands
223              Enable special-command processing, and optionally specify custom
224              commands  as  a  colon-separated  list. See above for a detailed
225              description of special commands.
226
227       -t name
228              Set the mouse type. Use -t help  to  get  a  list  of  allowable
229              types. Since version 1.18.1, the list also shows which protocols
230              are available as repeaters (see -R above), by marking them  with
231              an asterisk (``*'').
232
233              Use -t after you selected the mouse device with -m.
234
235       -v     Print version information and exit.
236
237       -2     Force  two  buttons.  This means that the middle button, if any,
238              will be taken as it was the right one.
239
240       -3     Force three buttons. By default the mouse is considered to be  a
241              2-buttons one, until the middle button is pressed. If three but‐
242              tons are there, the right one is used to extend  the  selection,
243              and  the middle one is used to paste it.  Beware: if you use the
244              -3 option with a 2-buttons mouse, you won't be able to paste the
245              selection.
246
247

OPERATION

249       To  select  text  press  the  left mouse button and drag the mouse.  To
250       paste text in the same or another console,  press  the  middle  button.
251       The right button is used to extend the selection, like in `xterm'.
252
253
254       Two-button mice use the right button to paste text.
255
256
257       Double  and triple clicks select whole word and whole lines. Use of the
258       `-p' option is recommended for best visual feedback.
259
260
261       If a trailing space after the contents of a line is highlighted, and if
262       there  is  no  other text on the remainder of the line, the rest of the
263       line will be selected automatically. If a number of lines are selected,
264       highlighted  trailing  spaces  on  each  line  will be removed from the
265       selection buffer.
266
267
268       Any output on the virtual console holding the selection will clear  the
269       highlighted  selection  from  the  screen, to maintain integrity of the
270       display, although the contents of the paste buffer will be unaffected.
271
272
273       The selection mechanism is disabled if the controlling virtual  console
274       is  placed  in  graphics mode, for example when running X11, and is re-
275       enabled when text mode is resumed. (But see BUGS section below.)
276
277

BUGS

279       The gpm server may have problems interacting with X: if your mouse is a
280       single-open  device  (i.e.  a  bus  mouse),  you should kill gpm before
281       starting X, or use the -R option (see above).  To kill gpm just  invoke
282       gpm -k. This problem doesn't apply to serial mice.
283
284
285       Two instances of gpm can't run on the same system. If you have two mice
286       use the -M option (see above).
287
288
289       While the current console is in graphic mode,  gpm  sleeps  until  text
290       mode is back (unless -R is used). Thus, it won't reply to clients. Any‐
291       ways, it is unlikely that mouse-eager clients will spur out  in  hidden
292       consoles.
293
294
295       The clients shipped out with gpm are not updated, thus there are poten‐
296       tial security risks when using them.
297
298

AUTHORS

300       Andrew Haylett <ajh@gec-mrc.co.uk> (the original selection code)
301       Ian Zimmerman <itz@speakeasy.org> (old maintainer)
302       Alessandro Rubini <rubini@linux.it> (old maintainer (still helps a lot))
303       Nico Schottelius <nico@schottelius.org> (maintainer)
304
305       Many many contributors, to both selection and gpm.
306
307

MAINTAINERS

309       The current maintainer is Nico Schottelius. But  without  the  help  of
310       Alessandro Rubini and the mailing list it would be impossible for me to
311       maintain gpm.  The  development  mailing  list  can  be  reached  under
312       gpm@lists.linux.it.  More information on the list is in the README file
313       part of the source distribution of gpm.
314
315

FILES

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

SEE ALSO

323        mev(1)        A sample client for the gpm daemon.
324        gpm-root(1)   An handler for Control-Mouse events.
325
326       The info file about `gpm', which gives more  complete  information  and
327       explains how to write a gpm client.
328
329
330
3314th Berkeley Distribution        February 2002                          GPM(8)
Impressum