SELECTION(1)

NAME
selection - the cut and paste utility for Linux virtual consoles

SYNOPSIS
selection [-a accel] [-b baud-rate] [-c [a-][c-][s-]l|m|r] [-d delta] [-e [a-][c-][s-]l|m|r] [-k] [-l charset] [-L charset] [-m mouse-device] [-o dtr|rts|both] [-p [a-][c-][s-]l|m|r] [-s sample-rate] [-t mouse-type] [-v] [-w slack]

DESCRIPTION
selection is a utility that allows characters to be selected from the current Linux virtual console using the mouse and pasted into any virtual console. selection is normally invoked at boot time from /etc/rc.local, and runs as a background process. If selection is invoked while another selection process is already running, the running process is terminated.

This manual page documents version 1.7 of selection.

OPTIONS

-a accel
    movements of more than delta pixels are multiplied by accel (default 2).

-b baud-rate
    set the baud rate of the mouse (default 1200 baud).

-c [a-][c-][s-]l|m|r
    set the copy button to be the left, middle or right button (default `l'). If a- is specified as a prefix, the ALT key must be held down before the button is pressed. If c- is specified as a prefix, the CNTRL key must be held down. If s- is specified, the SHIFT key must be held down. If more than one prefix is specified, all specified keys must be held down.

-d delta
    movements of more than delta pixels are multiplied by accel (default 25).

-e [a-][c-][s-]l|m|r
    set the extend button to be the left, middle or right button (default `c-l'). The button specifier may be prefixed as for the -c option.

-k  locate and terminate any running selection process, then exit.

-l charset
    define the set of characters which are considered to be part of the same word; analogous to the xterm charClass resource. The charset argument is a list of chars and ranges. `-' is interpreted as a range specifier unless it appears at the beginning or end of the string. The string `0-9A-Za-z_@./' could be used to enable whole pathnames and email addresses to be selected as single words. The default value is `0-9A-Za-z_'.

-L charset
    as for -l, but exit after loading the lookup table (to modify the behaviour of a running selection process).

-m mouse-device
    specify the mouse device (default /dev/mouse).

-o dtr|rts|both
    toggle the DTR, RTS or both DTR and RTS mouse modem lines on initialization.

-p [a-][c-][s-]l|m|r
    set the paste button to be the left, middle or right button (default `r'). The button specifier may be prefixed as for the -c option.

-s sample-rate
    set the sample rate of the mouse (default 100).

-t mouse-type
    specify the mouse type (Microsoft = `ms', Mouse Systems Corp = `msc', MM Series = `mm', Logitech = `logi', BusMouse = `bm', MSC 3-bytes = `sun', PS/2 = `ps2'; default = `ms').

-v  print version number and exit.

-w slack
    turn on wrap-around, specifying the amount of slack before the pointer reappears at the other side of the screen (default off).

OPERATION
When selection is running, moving the mouse will cause a highlighted block to move about the screen.

Move the block to the first character of the selection, then press and hold down the copy button (left by default).

Drag out the selection; the selected text will be highlighted. Then release the copy button. You can take the end of the selection to before the start of the selection if necessary.

Double-clicking the copy button while the highlighted block is on the screen selects text by word boundaries; treble-clicking selects by entire lines. If the button is held down after double- or treble-clicking, multiple words or lines may be selected. A word consists of a set of alphanumeric characters and underscores, unless redefined by the -l or -L options described above.

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.

Pressing the extend button (cntrl-left by default) will allow the extent of the selection to be altered while retaining the location of its start. (To make a three-button mouse behave as in X, invoke selection with the options `-p m -e r'.)

Pressing the paste button (right by default) in any virtual console pastes the selected text into the read queue of the associated tty.

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.

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

XTERM EVENT SUPPORT
The xterm program supports basic mouse event reporting (as used by programs such as tin, elvis and ipick among others), and this feature is supported by virtual consoles when selection is running. If the sequence ESC [ ? 9 h is sent to the console by the application, button-down events are sent to the application in an encoded stream. If the string ESC [ ? 1000 h is sent, button-up events are reported as well. Event reporting is disabled by sending the sequence ESC [ ? 9 l. The event report stream takes the form ESC [ M b x y, where b has the value ` ' for the left button, `!' for the middle button, `"' for the right button and `#' for button up events, and x and y have the value of `!' added to the x and y coordinates, zero-referenced from the top-left corner of the screen.

When event reporting is enabled, the normal selection copy and paste function may be temporarily restored by holding down the ALT key.

FILES
/dev/mouse
    default mouse device.
/dev/tty0
    current VC device.
/tmp/selection.pid
    file containing process ID of the currently active selection process. May be used to terminate selection when necessary using the -k option.

DIAGNOSTICS
selection complains if any of the devices it requires cannot be located. In addition, errors detected during operation will be indicated and the selection process terminated.

BUGS
The size of the paste buffer is set at 2048 bytes by default. This may be changed at kernel build; consult the file INSTALL in the source distribution.

The selection mechanism doesn't work very well with graphics characters, or indeed with any characters where a mapping between the typed character and the displayed character is performed by the console driver. The selection mechanism pastes into the input buffer the character codes as they are displayed on the screen, not those originally typed in by the user.

Because of the way that the kernel bus mouse drivers work, allowing only one process to have the mouse device open at once, selection cannot co-exist with X11 using ATI XL, Logitech and Microsoft bus mice or with a PS/2 mouse. The X server will not start while selection is running. This problem is not present with serial mice. To work around this problem, use the -k option to terminate any running selection process before running X, starting it again afterwards. A typical invocation would be:

/sbin/selection -k
startx
/sbin/selection [options]

This approach has the disadvantage that switching into a text virtual console while running X does not reenable selection. Note that selection must be installed set-UID for the -k option to work correctly.

AUTHOR
Andrew Haylett <ajh@gec-mrc.co.uk>

ACKNOWLEDGEMENTS
See the file CREDITS in the source distribution.