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