1GPM(8) System Manager's Manual GPM(8)
2
6 gpm - a cut and paste utility and mouse server for virtual consoles
7
9 gpm [ options ]
10
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 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 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 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 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
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 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 The default special commands are:
65 left button
67 Reboot the system by signalling the init process
68 middle button (if any)
70 Execute /sbin/shutdown -h now
71 right button
73 Execute /sbin/shutdown -r now
74 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 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 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
101 Available command line options are the following:
102 -a accel
104 Set the acceleration value used when a single motion event is
105 longer than delta (see -d).
106 -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 case $( /usr/bin/tty ) in
125 /dev/tty[0-9]*) /usr/bin/disable-paste ;;
126 esac
127 -b baud
129 Set the baud rate.
130 -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 -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 -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 -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 -h Print a summary of command line options.
156 -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 -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 -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 -m filename
176 Choose the mouse file to open. Must be before -t and -o.
177 -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 -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 -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 -r number
200 Set the responsiveness. A higher responsiveness is used for a
201 faster cursor motion.
202 -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 -s number
220 Set the sample rate for the mouse device.
221 -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 -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 Use -t after you selected the mouse device with -m.
234 -v Print version information and exit.
236 -2 Force two buttons. This means that the middle button, if any,
238 will be taken as it was the right one.
239 -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
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 Two-button mice use the right button to paste text.
255 Double and triple clicks select whole word and whole lines. Use of the
258 `-p' option is recommended for best visual feedback.
259 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 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 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
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 Two instances of gpm can't run on the same system. If you have two mice
286 use the -M option (see above).
287 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 The clients shipped out with gpm are not updated, thus there are poten‐
296 tial security risks when using them.
297
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 Many many contributors, to both selection and gpm.
306
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
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
323 mev(1) A sample client for the gpm daemon.
324 gpm-root(1) An handler for Control-Mouse events.
325 The info file about `gpm', which gives more complete information and
327 explains how to write a gpm client.
3284th Berkeley Distribution February 2002 GPM(8)