\input texinfo @c -*-texinfo-*- % % doc.gpm - main file for the documentation % % Copyright 1994,1995,1998 rubini@linux.it (Alessandro Rubini) % Copyright (C) 1998 Ian Zimmerman % Copyright (C) 2001-2005 Nico Schottelius % %%%% %------------------------------------------------------------------------------ % % NOTE FOR THE UNAWARE USER % ========================= % % This file is a texinfo source. It isn't the binary file of some strange % editor of mine. If you want ASCII, you should "make gpm.txt". % % Some strings maybe changed from the configure script. % %------------------------------------------------------------------------------ % % This is not a conventional info file... % I use two extra features: % - The '%' as a comment marker ("\%" -> "%") % - leading blanks are allowed (and removed) % @comment %**start of header @setfilename gpm.info @settitle gpm @value{version} @iftex @afourpaper @end iftex @comment %**end of header @ifinfo @format @dircategory Miscellaneous @direntry * Gpm: (gpm). Text-mode mouse library and server daemon. @end direntry @end format @end ifinfo @setchapternewpage off @set version @release@ @set update-month @release_date@ @finalout @ifinfo %ASCII_BEGIN This file is a user's and programmer's manual for gpm @value{version}. Copyright (C) 1994,1995,1998 Alessandro Rubini Copyright (C) 2001-2005 Nico Schottelius Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @ignore Permission is granted to process this file through TeX and print the results, provided the printed document carries copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). @end ignore Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end ifinfo @setchapternewpage odd @titlepage @c use the new format for titles @title gpm @value{version} @subtitle A general purpose mouse server for the Linux console @subtitle @value{update-month} @author by Nico Schottelius @end titlepage @setchapternewpage off @headings single @ifinfo This file documents the @value{version} release of the "General Purpose Mouse" (gpm) server for the Linux text console (@value{update-month}). @node Top, Overview, (dir), (dir) @top gpm @menu * Overview:: * Server Invocation:: * Gpm Internals:: * The ClientLib:: * Demo Clients:: * Type Index:: * Function Index:: * Variable Index:: @end menu @end ifinfo %########################################################################## %########################################################################## @node Overview, Server Invocation, Top, Top @chapter Overview @cindex Overview of Gpm @cindex Gpm Overview The @dfn{gpm} package is a mouse server for the Linux console. It is meant to provide cooked mouse events to text-only applications, such as editors and simple menu-based apps. The daemon is also able to repeat packets in "msc" format to a graphic application. This last feature is meant to override the single-open problem of busmice. The roots of @code{gpm} come from the @file{selection-1.5} package, by Andrew Haylett. The first application to support the mouse has been The Midnight Commander, by Miguel de Icaza. @file{mc-0.11} and later releases offer mouse support if you have the mouse server running on your system. The file @file{t-mouse.el} provides support for using the mouse from within Emacs. @xref{Emacs Support}. As of release 0.96, a default-handler is released with gpm, and can be used to handle Control-Mouse events to draw menus on the screen. The @code{gpm-root} program, however, needs kernel 1.1.73 or newer. @xref{gpm-root}. Release 1.00 has been an incompatible one (is is incompatible with releases older than 0.97), but is compatible with the kernel-level mouse driver (available as @file{kmouse-?.??.tar.gz} from the mirrors of @uref{ftp://tsx-11.mit.edu}. With 1.0 the high level library is available, together with a demonstration/test program. A small utility to help in detecting your mouse-type is also included. As of release 1.20.0 the default device is removed. Now -m is a must. Release 1.20.1 introduces the must for -t and a specific way to use -m,-t,-o: Now you've got to use -m first, then -t and at last -o. This seems to be more complex, but makes using of multiply mice possible with clean code. @menu * Building the Release:: @end menu %========================================================================= @node Building the Release, , Overview, Overview @section Compiling and Installing @cindex Building Gpm Just say @code{./configure && make && make install} to your shell. You'll need gpm installed to compile the latest release of The Midnight Commander with mouse support enabled. Binaries are not released with the package because it's safer for you to compile the package by yourself. %========================================================================= %@node Kernel Patches %@section Kernel Patches %@cindex Kernel Patches %@cindex Patches to Apply % %Old Linux kernels need to be patched to provide features I rely on. As %of 1.1.32, however, my patches are in the official release, so you won't %need any kernel recompilation. Remember, anyway, to enable selection while %compiling the kernel, or this package won't work. Refer to %@file{kernel/README} to probe further. % %Other features are needed to run the @t{gpm-root} client. They are %really functional only since 1.1.73. 1.1.68, however, should be sufficient. % %########################################################################## @node Server Invocation, Gpm Internals, Overview, Top @chapter Server Invocation @cindex The Server @cindex Command Line (gpm) %MANPAGE gpm.8 %M .TH GPM 8 "February 2002" %M .UC 4 %M .SH NAME %M gpm \- a cut and paste utility and mouse server for virtual consoles %M .SH SYNOPSIS %M .B gpm %M [ %M .I options %M ] %M .br %M .SH DESCRIPTION %M This package tries to be a useful %M mouse server for applications running on the Linux console. It is %M based on the "selection" package, and some of its code %M comes from selection itself. This package is intended as a replacement %M for "selection" as a cut-and-paste mechanism; it also provides %M additional facilities. The "selection" %M package offered the first cut-and-paste implementation for Linux using %M two mouse buttons, and the cut buffer is still called "selection buffer" %M or just "selection" throughout this document. %M %M The information below is extracted from the texinfo file, which is the %M preferred source of information. The @code{gpm} executable is meant to act like a daemon (thus, @code{gpmd} would be a better name for it). This section is meant to describe the command-line options for @code{gpm}, while its internals are outlined in the next section. @xref{Gpm Internals}. Due to restrictions in the @code{ioctl(TIOCLINUX)} system call, @code{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. From release 1.02 up to 1.19.2 is was possible for any user logged on the system console to change the mouse @emph{feeling} using the @t{-q} option. This is no longer possible for security reasons. As of 0.97 the server program puts itself in the background. To kill @code{gpm} you can just reinvoke it with the @samp{-k} cmdline switch, although @code{killall gpm} can be a better choice. @menu * Special Commands:: * Command Line:: * Bugs and Problems:: * Mouse Types:: @end menu %M .SH SPECIAL COMMANDS %========================================================================== @node Special Commands, Command Line, Server Invocation, Server Invocation @section Special Commands Version 1.10 adds the capability to execute @emph{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: @table @var @item left button Reboot the system by signalling the init process @item middle button (if any) Execute @code{/sbin/shutdown -h now} @item right button Execute @code{/sbin/shutdown -r now} @end table The @samp{-S} command line switch enables special command processing and allows to change the three special commands. To accept the default commands use @samp{-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, @samp{-S ":telinit 1:/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. %M .SH COMMAND LINE OPTIONS %========================================================================== @node Command Line, Bugs and Problems, Special Commands, Server Invocation @section Command Line Options Available command line options are the following: @table @code @item -a @var{accel} Set the acceleration value used when a single motion event is longer than @var{delta} (see @samp{-d}). @item -A[@var{limit}] Start up with selection pasting disabled. This is intended as a security measure; a plausible attack on a system seems to be to stuff a nasty shell command into the selection buffer (@code{rm -rf /}) including the terminating line break, then all the victim has to do is click the middle mouse button .. As of version 1.17.2, this has developed into a more general aging mechanism; the gpm daemon can disable (@emph{age}) selection pasting automatically after a period of inactivity. To enable this mode just give the optional @var{limit} parameter (no space in between !) which is interpreted as the time in seconds for which a selection is considered valid and pastable. As of version 1.15.7, a trivial program called @code{disable-paste} is provided. The following makes a good addition to @file{/etc/profile} if you allow multiple users to work on your console. @code{case $( /usr/bin/tty ) in @* /dev/tty[0-9]*) /usr/bin/disable-paste ;; @* esac} @item -b @var{baud} Set the baud rate. @item -B @var{sequence} Set the button sequence. @samp{123} is the normal sequence, @samp{321} can be used by left-handed people, and @samp{132} can be useful with two-button mice (especially within Emacs). All the button permutations are allowable. @item -d @var{delta} Set the delta value. When a single motion event is longer than @var{delta}, @var{accel} is used as a multiplying factor. (Must be 2 or above) @item -D Do not automatically enter background operation when started, and log messages to the standard error stream, not the syslog mechanism. This is useful for debugging; in previous releases it was done with a compile-time option. @item -g @var{number} With glidepoint devices, emulate the specified button with tapping. @var{number} must be @samp{1}, @samp{2}, or @samp{3}, and refers to the button number @emph{before} the @samp{-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 @item -h Print a summary of command line options. @item -i @var{interval} Set @var{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 @var{limit}, the press is considered a double or triple click. Time is in milliseconds. @item -k Kill a running gpm. This can be used by busmouse users to kill gpm before running X (unless they use @samp{-R} or the single-open limitation is removed from the kernel). @item -l @var{charset} Choose the @code{inword()} look up table. The @var{charset} argument is a list of characters. @samp{-} is used to specify a range and @samp{\ } is used to escape the next character or to provide octal codes. Only visible character can appear in @var{charset} because control characters can't appear in text-mode video memory, whence selection is cut. @item -m @var{filename} Choose the mouse file to open. Must be before -t and -o. @item -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 @emph{repeater} (@samp{-R}) option on. @item -o @var{list-of-extra-options} The option works similary to the ``-o'' option of mount; it is used to specify a list of ``extra options'' that are specific to each mouse type. The list is comma-separated. The options @samp{dtr}, @samp{rts} or @samp{both} are used by the serial initialization to toggle the modem lines like, compatibly with earlier @i{gpm} versions; note however that using @t{-o dtr} associated with non-plain-serial mouse types may now generate an error. @xref{Mouse Types}. And by the way, use -o after -m and after -t. @item -p Forces the pointer to be visible while selecting. This is the behaviour of @file{selection-1.7}, but it is sometimes confusing. The default is not to show the pointer, which can be confusing as well. @item -r @var{number} Set the responsiveness. A higher responsiveness is used for a faster cursor motion. @item -R[@var{name}] Causes @code{gpm} to act as a repeater: any mouse data received while in graphic mode will be produced on the fifo @file{/dev/gpmdata} in protocol @var{name}, given as an optional argument (no space in between !). In principle, you can use the same names as for the @samp{-t} option, although repeating into some protocols may not be implemented for a while. @xref{Mouse Types}. In addition, you can specify @samp{raw} as the @var{name}, to repeat the mouse data byte by byte, without any protocol translation. If @var{name} is omitted, it defaults to @samp{msc}. Using @i{gpm} in repeater mode, you can configure the X server to use its 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 @samp{-M} option. @item -s @var{number} Set the sample rate for the mouse device. @item -S @var{commands} Enable special-command processing, and optionally specify custom commands as a colon-separated list. See above for a detailed description of special commands. @item -t @var{name} Set the mouse type. Use @samp{-t help} to get a list of allowable types. Since version 1.18.1, the list also shows which protocols are available as repeaters (see @t{-R} above), by marking them with an asterisk (``@t{*}''). @xref{Mouse Types}. Use -t after you selected the mouse device with -m. @item -v Print version information and exit. @item -V[@var{verbosity increment}] Raise or decrease the maximum level of messages that will be logged. Thus a positive argument has the effect of making the program more verbose. One can also give a negative argument to hush the program; due to @b{getopt(3)} rules, any optional argument needs to be passed without a space in between! When omitting the argument, the increment defaults to 1. Default verbosity level is 5 (@code{LOG_NOTICE}). @xref{Program Arguments,,,libc}. @item -2 Force two buttons. This means that the middle button, if any, will be taken as it was the right one. @item -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 @samp{-3} option with a 2-buttons mouse, you won't be able to paste the selection. @end table @ignore .SH 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 word 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.) @end ignore %MSKIP @menu * Bugs and Problems:: @end menu @node Bugs and Problems, Mouse Types, Command Line, Server Invocation @section Bugs and Problems %M .SH BUGS The @code{gpm} server may have problems interacting with X: if your mouse is a single-open device (i.e. a bus mouse), you should kill @code{gpm} before starting X, or use the @samp{-R} option (see above). To kill @code{gpm} just invoke @code{gpm -k}. This problem doesn't apply to serial mice. Two instances of gpm can't run on the same system. If you have two mice use the @samp{-M} option (see above). While the current console is in graphic mode, @code{gpm} sleeps until text mode is back (unless @samp{-R} is used). Thus, it won't reply to clients. Anyways, it is unlikely that mouse-eager clients will spur out in hidden consoles. The clients shipped out with gpm are not updated, thus there are potential security risks when using them. @ignore .SH AUTHORS .nf Andrew Haylett (the original selection code) Ian Zimmerman (old maintainer) Alessandro Rubini (old maintainer (still helps a lot)) Nico Schottelius (maintainer) Many many contributors, to both selection and gpm. .fi .SH MAINTAINERS The current maintainer is Nico Schottelius. But without the help of Alessandro Rubini and the mailing list it would be impossible for him to maintain gpm. The development mailing list can be reached under gpm@lists.linux.it. More information on the list is in the README file part of the source distribution of gpm. .SH FILES .nf /var/run/gpm.pid The PID of the running gpm /dev/gpmctl A control socket for clients /dev/gpmdata The fifo written to by a \fBrepeater\fP (`-R') daemon. .fi .SH SEE ALSO .nf \fB mev(1)\fP A sample client for the gpm daemon. \fB gpm-root(1)\fP An handler for Control-Mouse events. .fi The info file about `gpm', which gives more complete information and explains how to write a gpm client. @end ignore %MANPAGE END %========================================================================== @node Mouse Types, , Bugs and Problems, Server Invocation @section Mouse Types %MANPAGE gpm-types.7 %M .TH GPM-TYPES 7 "July 2000" %M .UC 4 %M .SH NAME %M gpm-types \- pointer types (mice, tablets, etc.) managed by gpm. %M .br %M The information below is extracted from the texinfo file, which is the %M preferred source of information. %M .SH DESCRIPTION %MSKIP This section of the gpm documentation manual %M This manpage describes the various pointer types currently available in @i{gpm}. If you look at the source code, you'll find that pointer-specific code is confined to @file{mice.c} (while it used to only include mouse decoders, @i{gpm} now supports tablets and touchscreens as well). The mouse type is specified on command line with the @samp{-t} option. The option takes an argument, which represents the name of a mouse type. Each type can be associated to different names. For old mouse types, one name is the old selection-compatible name, and another is the XFree name. After version 1.18.1 of @i{gpm}, the number of synonyms was made arbitrary and the actual name being used is made available to the function responsible for mouse initialization. Therefore it is possible for a mouse decoder to behave slightly differently according to the name being used for the device (if this feature was already present, we wouldn't have for example @t{ms+} and @t{ms+lr} as different mouse types). The initialization procedure of each mouse type can also receive extra option, by means of the @t{-o} command line option. Since interpretation of the option string is decoder-specific, the allowed options are described in association to each mouse type. When no description of option strings is provided, that means the option string is unused for that mouse type and specifying one generates an error. When the document refer to ``standard serial options'' it means that one of @t{-o dtr}, @t{-o rts}, @t{-o both} can be specified to toggle the control lines of the serial port. The following mouse type are corrently recognized: @table @code @item bare Microsoft The Microsoft protocol, without any extension. It only reports two buttons. If your device has three, you should either try running the @t{mman} decoder or @t{msc}. In the latter case, you need to tell the mouse to talk @t{msc} protocol by toggling the DTR and RTS lines (with one of @t{-o drt}, @t{-o rts} or @t{-o both}) or invoking @code{gpm -t msc} while keeping the middle button pressed. Very annoying, indeed. This mouse decoder accepts standard serial options, although they should not be needed. @item ms This is the original Microsoft protocol, with a middle-button extension. Some old two-button devices send some spurious packets which can be misunderstood as middle-button events. If this is your case, use the @samp{bare} mouse type. Some new two-button devices are ``plug and play'', and they don't play fair at all; in this case try @t{-t pnp}. Many (most) three-button devices that use the microsoft protocol fail to report some middle-button events during mouse motion. Since the protocol does not distinguish between the middle button going up and the middle button going down it would be liable to get out of step, so this decoder declares the middle button to be up whenever the mouse moves. This prevents dragging with the middle button, so you should probably use @samp{-t ms+lr} instead of this decoder, especially if you want to use X. This mouse decoder accepts standard serial options, although they should not be needed. @item ms+ This is the same as @samp{-t ms} except that the middle button is not reset during mouse motion. So you can drag with the middle button. However, if your mouse exhibits the usual buggy behaviour the decoder is likely to get out of step with reality, thinking the middle button is up when it's down and vice versa. You should probably use @samp{-t ms+lr} instead of this decoder. This mouse decoder accepts standard serial options, although they should not be needed. @item ms+lr This is the same as @samp{-t ms+} except that there is an additional facility to reset the state of the middle button by pressing the other two buttons together. Do this when the decoder gets into a confused state where it thinks the middle button is up when it's down and vice versa. (If you get sick of having to do this, please don't blame gpm; blame your buggy mouse! Note that most three-button mice that do the microsoft protocol can be made to do the MouseSystems protocol instead. The ``3 Button Serial Mouse mini-HOWTO'' has information about this.) This mouse decoder accepts standard serial options, although they should not be needed. @item msc MouseSystems This is the standard protocol for three-button serial devices. Some of such devices only enter MouseSystem mode if the RTS, DTR or both lines are pushed low. Thus, you may try @t{-t msc} associated with @t{-o rts}, @t{-o dtr} or @t{-o both}. @item mman Mouseman The protocol used by the new Logitech devices with three buttons. It is backward compatible with the Microsoft protocol, so if your mouse has three buttons and works with @t{-t ms} or similar decoders you may try @t{-t mman} instead to use the middle button. This mouse decoder accepts standard serial options, although they should not be needed. @item sun The protocol used on Sparc computers and a few others. This mouse decoder accepts standard serial options, although they should not be needed. @item mm MMSeries Title says it all. This mouse decoder accepts standard serial options, although they should not be needed. @item logi Logitech This is the protocol used by old serial Logitech mice. @item bm BusMouse Some bus devices use this protocol, including those produced by Logitech. @item ps2 PS/2 The protocol used by most busmice. @item ncr This `type' is able to decode the pointing pen found on some laptops (the NCR 3125 pen) @item wacom The protocol used by the Wacom tablet. Since version 1.18.1 we have a new Wacom decoder, as the old one was not working with new tablets. This decoder was tested with Ultrapad, PenPartner, and Graphire tablets. Options: @t{-o relative} (default) for relative mode, @t{-o absolute} for absolute mode. @item genitizer The \"Genitizer\" tablet, in relative mode. This mouse decoder accepts standard serial options, although they should not be needed. @item logim Used to turn Logitech mice into Mouse-Systems-Compatible. Obviously, it only works with some of the Logitech mice. @item pnp This decoder works with the new mice produces by our friend Bill, and maybe with the old ones as well. The Pnp protocol is hardwired at 1200 baud and is upset by normal initialization, so this is a @t{-t bare} decoder with no initialization at all. This mouse decoder accepts standard serial options, although they should not be needed. @item ms3 A decoder for the new serial IntelliMouse devices, the ones with three buttons and a protocol incompatible with older ones. The wheel is currently unused. @item imps2 ``IntelliMouse'' on the ps/2 port. This type can also be used for a generic 2-button ps/2 mouse too, since it will auto-detect the type. @item netmouse Decodes the ``Genius NetMouse'' type of devices on the ps/2 port. For serial ``Netmouse'' devices, use the ``ms3'' decoder. @item cal A decoder of the ``Calcomp UltraSlate device. @item calr Same as above, but in relative mode. @item twid Support for the twiddler keyboard. As of gpm-1.14 this decoder includes a char generator for the text console, but doesn't yet support X keycodes. If used with @samp{-R}, @code{gpm} will anyway repeat mouse events to the X server. More information about twiddler support can be found in @file{README.twiddler}, in the gpm distribution. @item syn synaptics A decoder for the Synaptics TouchPad connected to the serial port. This mouse decoder accepts standard serial options, although they should not be needed. @item synps2 synaptics_ps2 Same as above, but for the devices attached to the ps2 port. @item brw A decoder for the Fellowes Browser, a device with 4 buttons and a wheel. This mouse decoder accepts standard serial options, although they should not be needed. @item js Joystick This mouse type uses the joystick device to generate mouse events. It is only available if the header @file{linux/joystick.h} is found at compile time. The header (and the device as well) has been introduced only during 2.1 development, and is not present in version 2.0 of the kernel. @item summa This is a decode for the Symmagraphics of Genius tablet, run in absolute mode. A repeater is associated to this decoder, so it can @t{-R summa} can be used to generate X events even for other absolute-pointing devices, like touchscreens. To use the repeated data from X, you need a modified @t{xf86Summa.o} module. @item mtouch A decoder for the MicroTouch touch screen. Please refer to the file @file{README.microtouch} in the source tree of gpm for further information. In the near future, anyways, I plan to fold back to this documentation the content of that file. @item gunze A decoder for the gunze touch screen. Please refer to the file @file{README.gunze} in the source tree of gpm for further information. In the near future, anyways, I plan to fold back to this documentation the content of that file. The decoder accepts the following options: @t{smooth=}, @t{debounce=}. An higher smoothness results in slower motion as well; a smaller smoothness gives faster motion but, obviously, less smooth. The default smoothness is 9. The debounce time is express in milliseconds and is the minimum duration of an up-down event to be taken as a tap. Smaller bounces are ignored. @item acecad The Acecad tablet in absolute mode. @item wp wizardpad Genius WizardPad tablet @end table @ignore .SH FILES .nf src/mice.c The source file for pointer decoders .fi .SH SEE ALSO .nf \fB gpm(8) \fP The General Purpose Mouse server .fi The info file about `gpm', which gives more complete information and explains how to write a gpm client. @end ignore %MANPAGE END %########################################################################## @node Gpm Internals, The ClientLib, Server Invocation, Top @chapter Gpm Internals @cindex Internals The server is organized as a main loop built around a @code{select()} system call. It responds both to mouse events and to input from the clients, which are connected to the server through a unix domain socket. The connection is used to tell the server what a client is interested in, and to get mouse events. When no clients are connected to the active console, the server runs the selection mechanism (cut and paste of text). The selection mechanism is a simple and well-designed application, whose behaviour can be cloned by clients, by telling the server to inherit the default response for certain mouse events (motion being the most interesting). @menu * Events:: * Margins:: * Event Types:: * Connection Details:: * Default Handlers:: @end menu %========================================================================== @node Events, Margins, Gpm Internals, Gpm Internals @section Events @cindex Events Whenever the mouse generates an event, the event is dispatched to the active client for the current console, or to the default handler, if present. Otherwise selection is run. A default handler is a client process which gets mouse events form all the virtual consoles. @xref{Default Handlers}. When a client is involved, it is handled a @code{Gpm_Event} structure, built by the server. The fields for @code{Gpm_Event} are the following: @tindex Gpm_Event @table @code @item unsigned char buttons; An or-mask of the values @code{GPM_B_LEFT}, @code{GPM_B_MIDDLE} and @code{GPM_B_RIGHT}. It corresponds to the state of the mouse buttons when the event is reported. The current implementation of gpm allows at most three buttons. @item unsigned char modifiers; The value of the kernel variable @code{shift_state}, as of @file{keyboard.c}, when the event is reported. It is a bitmask value, and corresponds to the least significant byte of the value used by the @code{loadkeys} program. Use of symbolic names in source code is available after inclusion of @file{linux/keyboard.h}, as exemplified in @file{mev.c}. @item unsigned short vc; The number of the active virtual console when the event is reported. The client is not expected to use this value, which corresponds to the controlling terminal of the client process, unless it gets events form multiple consoles. @xref{Default Handlers}. @item short x, y; The position of the mouse pointer where the event is reported. It is 1-based by default, to be compatible with @code{selection} and @code{libcurses}. This behavior can be overriden, though, by setting the library variable @code{gpm_zerobased}. @xref{Variables}. @item short dx, dy; The change in position since the last reported event. @item enum Gpm_Etype type; A bit-mask, representing the type of reported event, as described later. @xref{Event Types}. @item int clicks; A counter, which is valid at button-down, drag or button-up. It can be 0, 1 or 2 to mean single, double or triple click. @item enum Gpm_Margin margin; A bit-mask, telling if the pointer has gone out of the visible screen. The indivudual bits are named @code{GPM_TOP}, @code{GPM_BOT}, @code{GPM_LFT}, @code{GPM_RGT}. Only one of them is active at a time, to allow using @code{switch} on the value. Vertical outrun takes precedence on horizontal outrun. @xref{Margins}. @end table %========================================================================== @node Margins, Event Types, Events, Gpm Internals @section How margins are managed Motion and button-press events are constrained to remain within the visible screen. This means that the @code{x} will be within 1 and 80 and @code{y} will be within 1 and 25 when the console is 80x25 cells. However, a client can keep track of movements outside the screen, by using the @code{dx} and @code{dy} fields, which aren't subject to clipping. The server helps applications in detecting margin conditions by filling the @code{margin} field. Whenever the pointer tries to cross screen boundaries, it is forced to remain on the border, but a flag is set in @code{margin}. A different policy is in force for drag and button-release events. In this case the pointer is allowed to go outside the physical screen by exactly one position. This allows, for example, selecting to end of line by dragging down-left. The peculiar situation is nonetheless signaled through the @code{margin} flags. The client should be careful to fit the values within the screen if needed. @xref{Utility Functions}. %========================================================================== @node Event Types, Connection Details, Margins, Gpm Internals @section Event Types The @code{type} field in @code{Gpm_Event} is made up of bit-wide flags. The existing bit masks belong to two groups: bare events and cooked events. The bit-mask @code{GPM_BARE_EVENTS} is provided to extract bare events, by and-ing (@samp{&}) it with the @code{type} field. For any event, exactly one bit will be set in the resulting bitmask. Bare events are the following: @table @code @item GPM_MOVE A motion event, with all buttons up. @item GPM_DRAG A motion event, but one or more buttons are kept pressed. @item GPM_DOWN A button press event. The @code{buttons} field will report which buttons are pressed after the event. @item GPM_UP A button release event. The @code{buttons} field will report which buttons are being released. Note that this is different from the previous case. @item GPM_ENTER This means "enter in the current Region of Interest", and such event can only happen if the high-level library is used. When the type is @code{GPM_ENTER}, all the other fields are undefined. @xref{High Level Lib}. @item GPM_LEAVE This is only delivered by the high level library, too. Events of type @code{GPM_LEAVE} have all other fields undefined. @end table Cooked events are the following: @table @code @item GPM_SINGLE This bit may be set at button-press, drag and button release events, and can be used to identify a single press. The time interval used to choose a double click from two single clicks is set by a parameter in the daemon (configurable at daemon invocation). @item GPM_DOUBLE Used to identify a double click (press, drag, release) @item GPM_TRIPLE Used to identify a triple click (press, drag, release) @item GPM_MFLAG The ``motion flag'' is true if some dragging happened between button-press and button-release. It can be used by those applications which respond to events at button release. It is available at drag and release. @end table %========================================================================== @node Connection Details, Default Handlers, Event Types, Gpm Internals @section Connection Details Each virtual console has a stack of clients attached to it. They talk to gpm by writing to a control socket and get mouse events by reading it. All the clients in the stack can receive events. Gpm-1.10 and earlier only sent events to the top client, but sometimes users play with multiple programs using suspend-resume (thanks Ian). In addition to the per-console stacks, another stack is there to store default-handling clients. @xref{Default Handlers}. Each client registers with the server and tells which events it is interested in. Events not managed by the client can be handled by the selection mechanism, which is compiled in the server itself. This approach simplifies writing clients which respond only to button press/release events, because highlighting the mouse pointer can be performed by the server. A default handler in turn can respond only to mouse events associated with modifier keys, so that selection is used for any mouse-only event. Clients are required to fill a @code{Gpm_Connect} structure and pass it to the server. The structure is made up by four @code{unsigned int} fields. @xref{Open and Close}. @tindex Gpm_Connect @table @code @item eventMask A bitmask of the events the client wants to receive. Both bare and cooked events are allowed to appear in the mask. @item defaultMask A mask to tell which events allow a default treatment (the selection one). These are mouse events, independent of the modifier keys. @item minMod The minimum amount of modifiers required by the client. This field is used for default-handlers which manage control-mouse events without interfering with mouse-only ones. @xref{Default Handlers}. @item maxMod The maximum amount of modifiers the client is willing to receive. Events featuring a modifier key not included in @code{maxMod} won't be passed to the client. @end table @noindent Two more fields are there to tell about the connection itself, and you're not asked to fill them, because @code{Gpm_Open} will do it for you. @table @code @item int pid The process id of the connecting application. @item int vc Which virtual console to gain control of. @end table Keyboard modifiers are used to multiplex clients on the same virtual console. You (as a programmer) don't need to care about the internal workings. They are detailed in @ref{Default Handlers}, but you only need to choose the right values for your application. Examples: @table @code @item minMod=0; maxMod=0; specifies a client which senses mouse-only events, but neither shift-mouse nor alt-mouse nor control-mouse. @item minMod=0; maxMod=~0; is a client which gets any mouse event. @item minMod=1< .br Ian Zimmerman .SH FILES .nf /dev/gpmctl The socket used to connect to gpm. .fi .SH SEE ALSO .nf \fB gpm(8) \fP The mouse server \fB gpm-root(1) \fP An handler for Control-Mouse events. .fi The info file about `gpm', which gives more complete information and explains how to write a gpm client. @end ignore %MANPAGE END %========================================================================== @node sample/rmev, Emacs Support, mev, Demo Clients @section @code{sample/rmev} @code{rmev} is a reduced version of @code{mev}, but it is designed to be as portable as possible. It uses a subset of the capabilities of @file{libgpm.a}, but works smoothly on both xterm and the Linux console. It is distributed with @code{gpm} to show how a curses based application can support the mouse with a small effort. Most of the xterm decoding is by Janne Kukonlehto. @xref{Xterm}. %========================================================================== @node Emacs Support, gpm-root, sample/rmev, Demo Clients @section Emacs Support Emacs support is quite complete as of 0.14. The enclosed file @file{t-mouse.el}, also available in byte-compiled form, is used to pass mouse events to emacs. @file{t-mouse.elc} is installed in the correct @t{site-lisp} directory for you emacs installation (as detected by the configure phase). Events with modifiers other than Meta, Control, and Shift are not managed by the library. Managed events are passed to the lisp program, which converts them to be similar to X mouse events inside emacs. Actions are then invoked through a local keymap. In my own environment I can use mouse-only and meta mouse within emacs, shift-mouse to run selection and control-mouse to run @code{gpm-root}. @xref{gpm-root}. I suggest to put the following form in your own @file{.emacs} file, to avoid loading @code{t-mouse} when you aren't working on the Linux console: @lisp (if (and (string-match ".*-linux" system-configuration) (or (string-match "linux" (getenv "TERM")) (string-match "con.*" (getenv "TERM")))) (load-library "t-mouse")) @end lisp Mouse events are appended to the list variable @code{unread-command-events} where the Emacs main event loop will find them. They can be made to trigger any command (or interactive function, in Emacs Lisp terminology) at all. Actually Emacs already comes with reasonable bindings for most mouse events, so usually you won't have to do anything beyond installing @code{t-mouse}. If you want to modify what Emacs does in response to mouse events, please see @ref{Keymaps,,,elisp}. The scrollbar sits on the last column of the screen, though it is not visible. When you click on the last column, a scroll-bar action is taken. If this annoys you, again it can be turned off by changing the appropriate Emacs keymap. If you kill the @code{gpm} server, Emacs won't respond to mouse events any more. If the server is then restarted, you can invoke `@kbd{M-x t-mouse-run}' to restart mouse responsiveness in the editor. %========================================================================== @node gpm-root, hltest, Emacs Support, Demo Clients @section The ``gpm-root'' program %MANPAGE gpm-root.1 %M .TH GPM-ROOT 1 "February 1995" %M .UC 4 %M .SH NAME %M gpm-root \- a default handler for gpm, used to draw menus on %M the root window %M %M .SH SYNOPSIS %M .B gpm-root %M [ %M .I options %M ] %M .br %M .SH DESCRIPTION The program @code{gpm-root} is designed to handle Control-Mouse events to draw menus on the background of the current tty. The actual menus are described by a configuration file in the user's home directory. Please note that @code{gpm-root} needs to run with Linux 1.1.73 or newer, because previous kernels lack some screen handling capabilities required by the program. The program uses the files @file{/dev/vcs*} to draw to the console screen. These are available only from kernel 1.1.81 onward. If you miss those device nodes, you should create them using @code{create_vcs} in the distribution directory. The tool won't run with kernels older than 1.1.81, because they lacked a full screen dump/restore capability. Available command line options are the following: @table @code @item -m @var{number} Choose the modifier to use (by default: @samp{control}). The modifier can be provided either as a number or as a symbolic string. Allowed strings are @samp{shift}, @samp{anyAlt}, @samp{leftAlt}, @samp{rightAlt}, @samp{control}. @item -u Deny using user-specific configuration files. With this option on, only @file{/etc/gpm-root.conf} will be used as a source of configuration information. This option is intended for those system administrators who fear security could be broken by this daemon. Things should be sufficiently secure, but if you find a hole please tell me about it. @item -D Do not automatically enter background operation when started, and log messages to the standard error stream, not the syslog mechanism. This is useful for debugging; in previous releases it was done with a compile-time option. @item -V @var{verbosity increment} Raise the maximum level of messages that will be logged. Thus a positive argument has the effect of making the program more verbose. One can also give a negative argument to hush the program; however, note that due to @b{getopt(3)} rules a negative argument must follow the option with no space betwixt (that is, @samp{-V-1} but not @samp{-V -1}). @xref{Program Arguments,,,libc}. The argument is optional and its default value is 1. @end table Each time a menu is drawn, the configuration file is reparsed if it has changed. This allows modification of personal setup without reinvoking the daemon. %M The actual configuration file is better introduced by looking at your %M @file{/etc/gpm-root.conf}. %M %MSKIP The actual configuration file is better introduced by an example: @lisp # sample configuration file for gpm-root # edit it to suit your taste button 2 @{ name "system status" foreground red background black border yellow head bright yellow "" f.nop "load: " f.load "free:" f.free "---------" f.nop "disk usage" f.bgcmd "du | sort -rn > /tmp/du" @} button 3 @{ name "jump" foreground black background red border bright yellow head bright yellow "tty1" f.jptty "1" "tty2" f.jptty "2" "tty3" f.jptty "3" "tty4" f.jptty "4" "tty5" f.jptty "5" "tty6" f.jptty "6" "" f.nop "more of them..." @{ "tty 17" f.jptty "17" @} @} @end lisp %M .fi The syntax for the file won't be described here, being it quite apparent from the example above. Blanks and newlines are unused in parsing the file, and the layout of the file is free. Comments are allowed in the file: any hash mark (@samp{#}) found at the beginning of the line or after white space makes the parser discard anything up to the next line. To insert quotes (@samp{"}) in strings precede them with a backslash. Note that recursive menus are allowed, to any level of recursion. Keywords belong to three groups: the button keyword, the cfg keywords and the action keywords. They are all described in the table below: @table @code @item button @var{number} @var{menu} The @code{button} keyword is used to introduce a menu. It is followed by the number of the relevant button (1=left, 2=middle, 3=right), an open brace, a menu and a closed brace. A menu is made up of cfg statements, followed by action statements. Cfg statements can come in any order, while the order of action statements tells the actual order in which actions will appear on the screen, top to bottom. @end table The following statements belong to the cfg set. @table @code @item name @var{string} If the @code{name} keyword is present, the specified @var{string} will be used as the name for the current menu. @item background @var{color} This statements is used to specify the background color to be used in the current menu. The @var{color} can be specified with one of the eight canonical strings @samp{black}, @samp{red}, @samp{cyan} etc. The background defaults to black. @item foreground @var{color} This statements is used to specify the foreground color for menu items. Its value defaults to @samp{white}. An optional @samp{bright} keyword can appear before the actual color. @item border @var{color} @code{border} is used to specify the border color for the menu. Its value defaults to @samp{white}. An optional @samp{bright} keyword can appear before the actual color. @item head @var{color} @code{head} is used to specify the foreground color for the title of the menu. Its value defaults to @samp{white}. An optional @samp{bright} keyword can appear before the actual color. @end table The following statements belong to the action set. @table @code @item @var{string} f.fgcmd @var{cmdstring} When the mouse button is released above the corresponding menu item, the @var{cmdstring} is pasted in the keyboard queue of the current console. This is not yet implemented. @item @var{string} f.bgcmd @var{cmdstring} When the mouse button is released above the corresponding menu item, a shell (@file{/bin/sh}) is forked to execute the specified command, with @code{stdin} connected to @file{/dev/null}, and @code{stdout}, @code{stderr} connected to the active console. @item @var{string} f.jptty @var{ttynumber} When the mouse button is released above the corresponding menu item, the console is switched to the one specified. The @var{ttynumber} must be specified as a string. Any tty can be reached this way, even those which are not accessible via the keyboard. @item @var{string} f.mktty @var{ttynumber} When the mouse button is released above the corresponding menu item, an unused console is selected, and @file{/sbin/mingetty} is executed in it. The current console is switched to the newly opened console. I use this command to save kernel memory by opening a single console through @file{/etc/inittab} and requesting the others only when i need to login. @item @var{string} @var{Whole-menu} A menu can directly follow the label string. When the mouse pointer leaves the menu frame at the level of @var{string}, a second menu is posted on screen. @item @var{string} f.lock When the mouse button is released above the corresponding menu item, the keyboard and the screen are locked, and only the locking user or the superuser can unlock them. This is not yet implemented. @item @var{string} f.load The current loadavg when the menu is posted is concatenated to @var{string} to build the actual message displayed on screen. Nothing happens at button release. @item @var{string} f.free The free memory and swap when the menu is posted is concatenated to @var{string} to build the actual message displayed on screen. Nothing happens at button release. @item @var{string} f.time The current time is formatted with @b{strftime(3)}, according to @var{string}. The resulting string is the actual message displayed on screen. Nothing happens at button release. @item @var{string} f.pipe @var{cmdline} When the mouse pointer leaves the menu frame at the level of @var{string}, a message box is posted on screen showing the last ten lines of the output of @var{cmdline}. @var{cmdline} is executed by @file{/bin/sh}. This is not yet implemented. @item @var{string} f.nop This does nothing, it only displays @var{string} on the menu. @end table The @code{HOME}, @code{LOGNAME} and @code{USER} environment variables are setup to the values for the invoking user before spawning an external process (@code{f.bgcmd}, @code{f.pipe}). The current directory is always @file{/}. %M .SH BUGS Known bugs have been fixed. In particular, if you invoke @code{gpm-root} right after @code{gpm}, it will delay a few seconds before trying to connect to the daemon. @ignore .SH AUTHOR Alessandro Rubini .SH FILES .nf /dev/gpmctl The socket used to connect to gpm. /etc/gpm-root.conf The default configuration file. $(HOME)/.gpm-root The user configuration file. /dev/vcs* Virtual Console Screens .fi .SH SEE ALSO .nf \fB gpm(8) \fP .fi The info file about `gpm', which gives more complete information and explains how to write a gpm client. @end ignore %MANPAGE END %========================================================================== @node hltest, mouse-test, gpm-root, Demo Clients @section @code{hltest} High-level test is a simple sample application using the high-level library. It implements something like a window manager for text windows, though it is small and unuseful. The application is meant to be read by programmers trying to use the high-level library. It is equipped with event reporting to help in understanding the internal workings. %========================================================================== @node mouse-test, , hltest, Demo Clients @section @code{mouse-test} %MANPAGE mouse-test.1 %M .TH mouse-test 1 "March 26, 1998" "" %M .SH NAME %M mouse-test \- a tool for determining mouse type and device it's attached to. %M .SH SYNTAX %M \fBmouse-test\fR [ \fIdevice\fR ... ] %M .SH DESCRIPTION This experimental and incomplete application tries to help in detecting which protocol does your mouse speak. It is able to detect MouseMan devices, and to choose between @samp{-t ms} (three-buttons aware) and @samp{-t bare} old two-buttons-only serial mice. %M .SH BUGS I know the application is buggy, but I only own one mouse device. If you are interested in this application, just call me and awake me from my laziness. @ignore .SS OPTIONS .IP \fIdevice\fP [ \fIdevice\fP ... ] .PP Check this \fIdevice\fP for a mouse. If no devices are listed, mouse-test will try all possible devices. .SH AUTHOR Alessandro Rubini .SH FILES .nf /dev/* The devices used to search for a mouse .fi .SH SEE ALSO .nf gpm(8) .fi @end ignore %MANPAGE END %########################################################################## @node Type Index, Function Index, Demo Clients, Top @unnumbered Type Index @printindex tp @node Function Index, Variable Index, Type Index, Top @unnumbered API Index @printindex fn @node Variable Index, , Function Index, Top @unnumbered Variable Index @printindex vr %@iftex %@unnumbered Table of Contents %@contents %@end iftex @bye /* * This is because Linus uses 4-wide tabstops, * forcing me to use the same default to manage kernel sources */ /* Local Variables: */ /* tab-width:8 */ /* End: */