Debian Codegraph @

upstream/debian-unstable/man8/gpm.8

raw
1 .TH GPM 8 "February 2002"
2 .UC 4
3 .SH NAME
4 gpm \- a cut and paste utility and mouse server for virtual consoles
5 .SH SYNOPSIS
6 .B gpm
7 [
8 .I options
9 ]
10 .br
11 .SH DESCRIPTION
12 This package tries to be a useful
13 mouse server for applications running on the Linux console. It is
14 based on the "selection" package, and some of its code
15 comes from selection itself. This package is intended as a replacement
16 for "selection" as a cut-and-paste mechanism; it also provides
17 additional facilities. The "selection"
18 package offered the first cut-and-paste implementation for Linux using
19 two mouse buttons, and the cut buffer is still called "selection buffer"
20 or just "selection" throughout this document.
21 The information below is extracted from the texinfo file, which is the
22 preferred source of information.
23
24 .LP
25 The `gpm' executable is meant to act like a daemon (thus, `gpmd'
26 would be a better name for it). This section is meant to describe the
27 command-line options for `gpm', while its internals are outlined in
28 the next section.
29
30 .LP
31 Due to restrictions in the `ioctl(TIOCLINUX)' system call, `gpm' must
32 be run by the superuser. The restrictions have been added in the last 1.1
33 kernels to fix a security hole related to selection and screen dumping.
34
35 .LP
36 The server can be configured to match the user's taste, and any
37 application using the mouse will inherit the server's
38 attitude. From release 1.02 up to 1.19.2 is was possible
39 for any user logged on the system console to change the mouse feeling
40 using the \-q option. This is no longer possible for security
41 reasons.
42
43 .LP
44 As of 0.97 the server program puts itself in the background. To kill
45 `gpm' you can just reinvoke it with the `\-k' cmdline switch,
46 although `killall gpm' can be a better choice.
47
48 .LP
49 .SH SPECIAL COMMANDS
50
51 .LP
52 Version 1.10 adds the capability to execute special commands on
53 certain circumstances. Special commands default to rebooting and halting
54 the system, but the user can specify his/her personal choice. The
55 capability to invoke commands using the mouse is a handy one for
56 programmers, because it allows to issue a clean shutdown when the
57 keyboard is locked and no network is available to restore the system to
58 a sane state.
59
60 .LP
61 Special commands are toggled by triple-clicking the left and right button --
62 an unlikely event during normal mouse usage. The easiest way to triple-click
63 is pressing one of the buttons and triple-click the other one. When special
64 processing is toggled, a message appears on the console (and the speaker
65 beeps twice, if you have a speaker); if the user releases all the buttons
66 and presses one of them again within three seconds, then the special
67 command corresponding to the button is executed.
68
69 .LP
70 The default special commands are:
71 .TP
72 left button
73 Reboot the system by signalling the init process
74 .TP
75 middle button (if any)
76 Execute `/sbin/shutdown \-h now'
77 .TP
78 right button
79 Execute `/sbin/shutdown \-r now'
80
81 .LP
82 The `\-S' command line switch enables special command processing and
83 allows to change the three special commands. To accept the default
84 commands use `\-S ""' (i.e., specify an empty argument). To specify
85 your own commands, use a colon-separated list to specify commands
86 associated to the left, middle and right button. If any of the commands
87 is empty, it is interpreted as `send a signal to the init process'. This
88 particular operation is supported, in addition to executing external
89 commands, because sometimes bad bugs put the system to the impossibility
90 to fork; in these rare case the programmer should be able to shutdown
91 the system anyways, and killing init from a running process is the only
92 way to do it.
93
94 .LP
95 As an example, `\-S ":telinit 1:/sbin/halt"', associates killing
96 init to the left button, going single user to the middle one, and halting
97 the system to the right button.
98
99 .LP
100 System administrators should obviously be careful about special
101 commands, as gpm runs with superuser permissions. Special commands are
102 best suited for computers whose mouse can be physically accessed only by
103 trusted people.
104
105 .LP
106 .SH COMMAND LINE OPTIONS
107
108 .LP
109 Available command line options are the following:
110 .TP
111 \-a \fIaccel\fP
112 Set the acceleration value used when a single motion event is
113 longer than \fIdelta\fP (see `\-d').
114 .TP
115 \-A[\fIlimit\fP]
116 Start up with selection pasting disabled. This is intended as a
117 security measure; a plausible attack on a system seems to be to
118 stuff a nasty shell command into the selection buffer
119 (`rm \-rf /') including the terminating line break, then all the
120 victim has to do is click the middle mouse button ..
121 As of version 1.17.2, this has developed
122 into a more general aging mechanism; the
123 gpm daemon can disable (age) selection pasting
124 automatically after a period of inactivity. To enable this mode
125 just give the optional \fIlimit\fP parameter (no space in between !)
126 which is interpreted as the time in seconds for which a selection is
127 considered valid and pastable.
128 As of version 1.15.7, a trivial program called
129 `disable-paste' is provided. The following makes a good
130 addition to `/etc/profile' if you allow multiple users to
131 work on your console.
132
133 .LP
134 `case $( /usr/bin/tty ) in
135 .br
136 /dev/tty[0\-9]*) /usr/bin/disable-paste ;;
137 .br
138 esac'
139 .TP
140 \-b \fIbaud\fP
141 Set the baud rate.
142 .TP
143 \-B \fIsequence\fP
144 Set the button sequence. `123' is the
145 normal sequence, `321' can be used by left-handed people,
146 and `132' can be useful with two-button mice (especially within
147 Emacs). All the button permutations are allowable.
148 .TP
149 \-d \fIdelta\fP
150 Set the delta value. When a single motion event
151 is longer than \fIdelta\fP, \fIaccel\fP is used as a multiplying
152 factor. (Must be 2 or above)
153 .TP
154 \-D
155 Do not automatically enter background operation when started,
156 and log messages to the standard error stream, not the syslog
157 mechanism. This is useful for debugging; in previous releases
158 it was done with a compile-time option.
159 .TP
160 \-g \fInumber\fP
161 With glidepoint devices, emulate the specified button with tapping.
162 \fInumber\fP must be `1', `2', or `3', and refers to the
163 button number before the `\-B' button remapping is performed.
164 This option applies to the mman and ps2 decoding. No button is
165 emulated by default because the ps2 tapping is incompatible with
166 some normal ps2 mice
167 .TP
168 \-h
169 Print a summary of command line options.
170 .TP
171 \-i \fIinterval\fP
172 Set \fIinterval\fP to be used as an upper time limit
173 for multiple clicks. If the interval between button-up and
174 button-down events is less than \fIlimit\fP, the press is considered
175 a double or triple click. Time is in milliseconds.
176 .TP
177 \-k
178 Kill a running gpm. This can be used by busmouse users to kill gpm
179 before running X (unless they use `\-R' or the single-open
180 limitation is removed from the kernel).
181 .TP
182 \-l \fIcharset\fP
183 Choose the `inword()' look up table. The
184 \fIcharset\fP argument is a list of characters. `\-' is used to
185 specify a range and `\\ ' is used to escape the next character
186 or to provide octal codes.
187 Only visible character can appear in \fIcharset\fP because control
188 characters can't appear in text-mode video memory, whence selection
189 is cut.
190 .TP
191 \-m \fIfilename\fP
192 Choose the mouse file to open. Must be before \-t and \-o.
193 .TP
194 \-M
195 Enable multiple mode. The daemon will read two different mouse devices.
196 Any subsequent option will refer to the second device, while any
197 preceding option will be used for the first device. This option
198 automatically forces the repeater (`\-R') option on.
199 .TP
200 \-o \fIlist-of-extra-options\fP
201 The option works similarly to the ``\-o'' option of mount; it is
202 used to specify a list of ``extra options'' that are specific
203 to each mouse type. The list is comma-separated. The options
204 `dtr', `rts' or `both' are used by the serial
205 initialization to toggle the modem lines like, compatibly with
206 earlier gpm versions; note however that using \-o dtr
207 associated with non-plain-serial mouse types may now generate
208 an error.
209 And by the way, use \-o after \-m and after \-t.
210 .TP
211 \-p
212 Forces the pointer to be visible while selecting. This is the
213 behaviour of `selection-1.7', but it is sometimes confusing.
214 The default is not to show the pointer, which can be confusing as well.
215 .TP
216 \-r \fInumber\fP
217 Set the responsiveness as a percentage of motion (1 to 100, default
218 10). A lower number can be used to slow down cursor motion, this can
219 not be used to make a mouse move faster, see `-a'.
220 .TP
221 \-R[\fIname\fP]
222 Causes `gpm' to act as a repeater: any mouse data received while
223 in graphic mode will be produced on the fifo `/dev/gpmdata'
224 in protocol \fIname\fP, given as an optional argument (no space in
225 between !). In principle, you can use the same
226 names as for the `\-t' option, although repeating into some
227 protocols may not be implemented for a while.
228 In addition, you can specify `raw' as the \fIname\fP, to repeat
229 the mouse data byte by byte, without any protocol translation.
230 If \fIname\fP is omitted, it defaults to `msc'.
231 Using gpm in repeater mode, you can configure the X
232 server to use its fifo as a mouse device. This option is useful for
233 bus-mouse owners to override the single-open limitation. It is also
234 an easy way to manage those stupid dual-mode mice which force you
235 to keep the middle button down while changing video mode. The option
236 is forced on by the `\-M' option.
237 .TP
238 \-s \fInumber\fP
239 Set the sample rate for the mouse device.
240 .TP
241 \-S \fIcommands\fP
242 Enable special-command processing, and optionally specify custom
243 commands as a colon-separated list. See above for a detailed
244 description of special commands.
245 .TP
246 \-t \fIname\fP
247 Set the mouse type. Use `\-t help' to get a list
248 of allowable types.
249 Use \-t after you selected the mouse device with \-m.
250 .TP
251 \-v
252 Print version information and exit.
253 .TP
254 \-2
255 Force two buttons. This means that the middle button, if any,
256 will be taken as it was the right one.
257 .TP
258 \-3
259 Force three buttons. By default the
260 mouse is considered to be a 2-buttons one, until the middle button
261 is pressed. If three buttons are there, the right one is used
262 to extend the selection, and the middle one is used to paste it.
263 Beware: if you use the `\-3' option with a 2-buttons mouse, you
264 won't be able to paste the selection.
265
266 .LP
267 .SH OPERATION
268
269 .LP
270 To select text press the left mouse button and drag the mouse.
271 To paste text in the same or another console, press the middle button.
272 The right button is used to extend the selection, like in `xterm'.
273
274 .LP
275 Two-button mice use the right button to paste text.
276
277 .LP
278 Double and triple clicks select whole word and whole lines. Use of
279 the `\-p' option is recommended for best visual feedback.
280
281 .LP
282 If a trailing space after the contents of a line is highlighted, and if
283 there is no other text on the remainder of the line, the rest of the
284 line will be selected automatically. If a number of lines are selected,
285 highlighted trailing spaces on each line will be removed from the
286 selection buffer.
287
288 .LP
289 Any output on the virtual console holding the selection will clear the
290 highlighted selection from the screen, to maintain integrity of the
291 display, although the contents of the paste buffer will be unaffected.
292
293 .LP
294 The selection mechanism is disabled if the controlling virtual console
295 is placed in graphics mode, for example when running X11, and is
296 re-enabled when text mode is resumed. (But see BUGS section below.)
297
298 .LP
299 .SH BUGS
300 The `gpm' server may have problems interacting with X: if your
301 mouse is a single-open device (i.e. a bus mouse), you should kill
302 `gpm' before starting X, or use the `\-R' option (see
303 above). To kill `gpm' just invoke `gpm \-k'. This problem doesn't
304 apply to serial mice.
305
306 .LP
307 Two instances of gpm can't run on the same system. If you have two mice use
308 the `\-M' option (see above).
309
310 .LP
311 While the current console is in graphic mode, `gpm' sleeps until
312 text mode is back (unless `\-R' is used). Thus, it won't reply to
313 clients. Anyways, it is unlikely that mouse-eager clients will spur
314 out in hidden consoles.
315
316 .LP
317 The clients shipped out with gpm are not updated, thus there are potential
318 security risks when using them.
319
320 .LP
321 .SH AUTHORS
322 .nf
323 Andrew Haylett <[email protected]> (the original selection code)
324 Ian Zimmerman <[email protected]> (old maintainer)
325 Alessandro Rubini <[email protected]> (old maintainer (still helps a lot))
326 Nico Schottelius <[email protected]> (maintainer)
327
328 Many many contributors, to both selection and gpm.
329 .fi
330
331 .LP
332 .SH MAINTAINERS
333
334 .LP
335 The current maintainer is Nico Schottelius. But without the help of
336 Alessandro Rubini and the mailing list it would be impossible for me to
337 maintain gpm. The development mailing list can be reached under
338 [email protected]. More information on the list is in the README file part of
339 the source distribution of gpm.
340
341 .LP
342 .SH FILES
343 .nf
344 /var/run/gpm.pid The PID of the running gpm
345 /dev/gpmctl A control socket for clients
346 /dev/gpmdata The fifo written to by a \fBrepeater\fP (`\-R') daemon.
347 .fi
348
349 .LP
350 .SH SEE ALSO
351 .nf
352 \fB gpm-types(7)\fP Description of current pointer types supported by gpm
353
354 .fi
355 The info file about `gpm', which gives more complete information and
356 explains how to write a gpm client.