diff options
Diffstat (limited to 'doc/screen.info-3')
| -rw-r--r-- | doc/screen.info-3 | 1381 |
1 files changed, 1381 insertions, 0 deletions
diff --git a/doc/screen.info-3 b/doc/screen.info-3 new file mode 100644 index 0000000..66f750a --- /dev/null +++ b/doc/screen.info-3 @@ -0,0 +1,1381 @@ +This is Info file screen.info, produced by Makeinfo-1.55 from the input +file ./screen.texinfo. + + This file documents the `Screen' virtual terminal manager. + + Copyright (c) 1993 Free Software Foundation, Inc. + + 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. + + 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 Foundation. + + +File: screen.info, Node: Key Binding, Next: Flow Control, Prev: Subprocess Execution, Up: Top + +Key Binding +*********** + + You may disagree with some of the default bindings (I know I do). +The `bind' command allows you to redefine them to suit your preferences. + +* Menu: + +* Bind:: `bind' syntax. +* Bind Examples:: Using `bind'. +* Command Character:: The character used to start keyboard commands. +* Help:: Show current key bindings. +* Bindkey:: `bindkey' syntax. +* Bindkey Examples:: Some easy examples. +* Bindkey Control:: How to control the bindkey mechanism. + + +File: screen.info, Node: Bind, Next: Bind Examples, Up: Key Binding + +The `bind' command +================== + + - Command: bind KEY [COMMAND [ARGS]] + (none) + Bind a command to a key. The KEY argument is either a single + character, a two-character sequence of the form `^x' (meaning + `C-x'), a backslash followed by an octal number (specifying the + ASCII code of the character), or a backslash followed by a second + character, such as `\^' or `\\'. The argument can also be quoted, + if you like. If no further argument is given, any previously + established binding for this key is removed. The COMMAND argument + can be any command (*note Command Index::.). + + By default, most suitable commands are bound to one or more keys + (*note Default Key Bindings::.; for instance, the command to + create a new window is bound to `C-c' and `c'. The `bind' command + can be used to redefine the key bindings and to define new + bindings. + + +File: screen.info, Node: Bind Examples, Next: Command Character, Prev: Bind, Up: Key Binding + +Examples of the `bind' command +============================== + +Some examples: + + bind ' ' windows + bind ^f screen telnet foobar + bind \033 screen -ln -t root -h 1000 9 su + +would bind the space key to the command that displays a list of windows +(so that the command usually invoked by `C-a C-w' would also be +available as `C-a space'), bind `C-f' to the command "create a window +with a TELNET connection to foobar", and bind ESC to the command that +creates an non-login window with title `root' in slot #9, with a +super-user shell and a scrollbackbuffer of 1000 lines. + + +File: screen.info, Node: Command Character, Next: Help, Prev: Bind Examples, Up: Key Binding + +Command Character +================= + + - Command: escape XY + (none) + Set the command character to X and the character generating a + literal command character to Y (just like with the `-e' option). + Each argument is either a single character, a two-character + sequence of the form `^x' (meaning `C-x'), a backslash followed by + an octal number (specifying the ASCII code of the character), or a + backslash followed by a second character, such as `\^' or `\\'. + The default is `^Aa', but ```' is recommended by one of the + authors. + + - Command: defescape XY + (none) + Set the default command characters. This is equivalent to the + command `escape' except that it is useful for multiuser sessions + only. In a multiuser session `escape' changes the command + character of the calling user, where `defescape' changes the + default command characters for users that will be added later. + + - Command: meta + (`C-a a') + Send the command character (`C-a') to the process in the current + window. The keystroke for this command is the second parameter to + the `-e' command line switch (*note Invoking Screen::.), or the + `escape' .screenrc directive. + + - Command: command + (none) + This command has the same effect as typing the screen escape + character (`C-a'). It is probably only useful for key bindings. + *Note Bindkey::. + + +File: screen.info, Node: Help, Next: Bindkey, Prev: Command Character, Up: Key Binding + +Help +==== + + - Command: help + (`C-a ?') + Displays a help screen showing you all the key bindings. The first + pages list all the internal commands followed by their bindings. + Subsequent pages will display the custom commands, one command per + key. Press space when you're done reading each page, or return to + exit early. All other characters are ignored. *Note Default Key + Bindings::. + + +File: screen.info, Node: Bindkey, Next: Bindkey Examples, Prev: Help, Up: Key Binding + +Bindkey +======= + + - Command: bindkey [OPTS] [STRING [CMD ARGS]] + (none) + This command manages screen's input translation tables. Every + entry in one of the tables tells screen how to react if a certain + sequence of characters is encountered. There are three tables: one + that should contain actions programmed by the user, one for the + default actions used for terminal emulation and one for screen's + copy mode to do cursor movement. *Note Input Translation:: for a + list of default key bindings. + + If the `-d' option is given, bindkey modifies the default table, + `-m' changes the copy mode table and with neither option the user + table is selected. The argument `string' is the sequence of + characters to which an action is bound. This can either be a fixed + tring or a termcap keyboard capability name (selectable with the + `-k' option). + + Some keys on a VT100 terminal can send a different string if + application mode is turned on (e.g. the cursor keys). Such keys + have two entries in the translation table. You can select the + application mode entry by specifying the `-a' option. + + The `-t' option tells screen not to do intercharacter timing. One + cannot turn off the timing if a termcap capabilty is used. + + `cmd' can be any of screen's commands with an arbitrary number of + `args'. If `cmd' is omitted the keybinding is removed from the + table. + + +File: screen.info, Node: Bindkey Examples, Next: Bindkey Control, Prev: Bindkey, Up: Key Binding + +Bindkey Examples +================ + +Here are some examples of keyboard bindings: + + bindkey -d + +Show all of the default key bindings. The application mode entries are +marked with [A]. + + bindkey -k k1 select 1 + +Make the "F1" key switch to window one. + + bindkey -t foo stuff barfoo + +Make `foo' an abrevation of the word `barfoo'. Timeout is disabled so +that users can type slowly. + + bindkey "\024" mapdefault + +This keybinding makes `C-t' an escape character for keybindings. If you +did the above `stuff barfoo' binding, you can enter the word `foo' by +typing `C-t foo'. If you want to insert a `C-t' you have to press the +key twice (i.e. escape the escape binding). + + bindkey -k F1 command + +Make the F11 (not F1!) key an alternative screen escape (besides `C-a'). + + +File: screen.info, Node: Bindkey Control, Prev: Bindkey Examples, Up: Key Binding + +Bindkey Control +=============== + + - Command: mapdefault + (none) + Tell screen that the next input character should only be looked up + in the default bindkey table. + + - Command: mapnotnext + (none) + Like mapdefault, but don't even look in the default bindkey table. + + - Command: maptimeout TIMO + (none) + Set the intercharacter timer for input sequence detection to a + timeout of TIMO ms. The default timeout is 300ms. Maptimeout with + no arguments shows the current setting. + + +File: screen.info, Node: Flow Control, Next: Termcap, Prev: Key Binding, Up: Top + +Flow Control +************ + + `screen' can trap flow control characters or pass them to the +program, as you see fit. This is useful when your terminal wants to use +XON/XOFF flow control and you are running a program which wants to use +^S/^Q for other purposes (i.e. `emacs'). + +* Menu: + +* Flow Control Summary:: The effect of `screen' flow control +* Flow:: Setting the flow control behavior +* XON/XOFF:: Sending XON or XOFF to the window + + +File: screen.info, Node: Flow Control Summary, Next: Flow, Up: Flow Control + +About `screen' flow control settings +==================================== + + Each window has a flow-control setting that determines how screen +deals with the XON and XOFF characters (and perhaps the interrupt +character). When flow-control is turned off, screen ignores the XON +and XOFF characters, which allows the user to send them to the current +program by simply typing them (useful for the `emacs' editor, for +instance). The trade-off is that it will take longer for output from a +"normal" program to pause in response to an XOFF. With flow-control +turned on, XON and XOFF characters are used to immediately pause the +output of the current window. You can still send these characters to +the current program, but you must use the appropriate two-character +screen commands (typically `C-a q' (xon) and `C-a s' (xoff)). The +xon/xoff commands are also useful for typing C-s and C-q past a +terminal that intercepts these characters. + + Each window has an initial flow-control value set with either the +`-f' option or the `defflow' command. By default the windows are set +to automatic flow-switching. It can then be toggled between the three +states 'fixed on', 'fixed off' and 'automatic' interactively with the +`flow' command bound to `C-a f'. + + The automatic flow-switching mode deals with flow control using the +TIOCPKT mode (like `rlogin' does). If the tty driver does not support +TIOCPKT, screen tries to determine the right mode based on the current +setting of the application keypad -- when it is enabled, flow-control +is turned off and visa versa. Of course, you can still manipulate +flow-control manually when needed. + + If you're running with flow-control enabled and find that pressing +the interrupt key (usually C-c) does not interrupt the display until +another 6-8 lines have scrolled by, try running screen with the +`interrupt' option (add the `interrupt' flag to the `flow' command in +your .screenrc, or use the `-i' command-line option). This causes the +output that `screen' has accumulated from the interrupted program to be +flushed. One disadvantage is that the virtual terminal's memory +contains the non-flushed version of the output, which in rare cases can +cause minor inaccuracies in the output. For example, if you switch +screens and return, or update the screen with `C-a l' you would see the +version of the output you would have gotten without `interrupt' being +on. Also, you might need to turn off flow-control (or use auto-flow +mode to turn it off automatically) when running a program that expects +you to type the interrupt character as input, as the `interrupt' +parameter only takes effect when flow-control is enabled. If your +program's output is interrupted by mistake, a simple refresh of the +screen with `C-a l' will restore it. Give each mode a try, and use +whichever mode you find more comfortable. + + +File: screen.info, Node: Flow, Next: XON/XOFF, Prev: Flow Control Summary, Up: Flow Control + +Flow +==== + + - Command: defflow FSTATE [INTERRUPT] + (none) + Same as the `flow' command except that the default setting for new + windows is changed. Initial setting is `auto'. Specifying `flow + auto interrupt' has the same effect as the command-line options + `-fa' and `-i'. Note that if `interrupt' is enabled, all existing + displays are changed immediately to forward interrupt signals. + + - Command: flow [FSTATE] + (`C-a f', `C-a C-f') + Sets the flow-control mode for this window to FSTATE, which can be + `on', `off' or `auto'. Without parameters it cycles the current + window's flow-control setting. Default is set by `defflow'. + + +File: screen.info, Node: XON/XOFF, Prev: Flow, Up: Flow Control + +XON and XOFF +============ + + - Command: xon + (`C-a q', `C-a C-q') + Send a ^Q (ASCII XON) to the program in the current window. + Redundant if flow control is set to `off' or `auto'. + + - Command: xoff + (`C-a s', `C-a C-s') + Send a ^S (ASCII XOFF) to the program in the current window. + + +File: screen.info, Node: Termcap, Next: Message Line, Prev: Flow Control, Up: Top + +Termcap +******* + + `screen' demands the most out of your terminal so that it can +perform its VT100 emulation most efficiently. These functions provide +means for tweaking the termcap entries for both your physical terminal +and the one simulated by `screen'. + +* Menu: + +* Window Termcap:: Choosing a termcap entry for the window. +* Dump Termcap:: Write out a termcap entry for the window. +* Termcap Syntax:: The `termcap' and `terminfo' commands. +* Termcap Examples:: Uses for `termcap'. +* Special Capabilities:: Non-standard capabilities used by `screen'. +* Autonuke:: Flush unseen output +* Obuflimit:: Allow pending output when reading more +* Character Translation:: Emulating fonts and charsets. + + +File: screen.info, Node: Window Termcap, Next: Dump Termcap, Up: Termcap + +Choosing the termcap entry for a window +======================================= + + Usually `screen' tries to emulate as much of the VT100/ANSI standard +as possible. But if your terminal lacks certain capabilities the +emulation may not be complete. In these cases `screen' has to tell the +applications that some of the features are missing. This is no problem +on machines using termcap, because `screen' can use the `$TERMCAP' +variable to customize the standard screen termcap. + + But if you do a rlogin on another machine or your machine supports +only terminfo this method fails. Because of this `screen' offers a way +to deal with these cases. Here is how it works: + + When `screen' tries to figure out a terminal name for itself, it +first looks for an entry named `screen.TERM', where TERM is the +contents of your `$TERM' variable. If no such entry exists, `screen' +tries `screen' (or `screen-w', if the terminal is wide (132 cols or +more)). If even this entry cannot be found, `vt100' is used as a +substitute. + + The idea is that if you have a terminal which doesn't support an +important feature (e.g. delete char or clear to EOS) you can build a new +termcap/terminfo entry for `screen' (named `screen.DUMBTERM') in which +this capability has been disabled. If this entry is installed on your +machines you are able to do a rlogin and still keep the correct +termcap/terminfo entry. The terminal name is put in the `$TERM' +variable of all new windows. `screen' also sets the `$TERMCAP' +variable reflecting the capabilities of the virtual terminal emulated. +Furthermore, the variable `$WINDOW' is set to the window number of each +window. + + The actual set of capabilities supported by the virtual terminal +depends on the capabilities supported by the physical terminal. If, for +instance, the physical terminal does not support underscore mode, +`screen' does not put the `us' and `ue' capabilities into the window's +`$TERMCAP' variable, accordingly. However, a minimum number of +capabilities must be supported by a terminal in order to run `screen'; +namely scrolling, clear screen, and direct cursor addressing (in +addition, `screen' does not run on hardcopy terminals or on terminals +that over-strike). + + Also, you can customize the `$TERMCAP' value used by `screen' by +using the `termcap' command, or by defining the variable `$SCREENCAP' +prior to startup. When the latter defined, its value will be copied +verbatim into each window's `$TERMCAP' variable. This can either be +the full terminal definition, or a filename where the terminal `screen' +(and/or `screen-w') is defined. + + Note that `screen' honors the `terminfo' command if the system uses +the terminfo database rather than termcap. On such machines the +`$TERMCAP' variable has no effect and you must use the `dumptermcap' +command (*note Dump Termcap::.) and the `tic' program to generate +terminfo entries for `screen' windows. + + When the boolean `G0' capability is present in the termcap entry for +the terminal on which `screen' has been called, the terminal emulation +of `screen' supports multiple character sets. This allows an +application to make use of, for instance, the VT100 graphics character +set or national character sets. The following control functions from +ISO 2022 are supported: `lock shift G0' (`SI'), `lock shift G1' (`SO'), +`lock shift G2', `lock shift G3', `single shift G2', and `single shift +G3'. When a virtual terminal is created or reset, the ASCII character +set is designated as `G0' through `G3'. When the `G0' capability is +present, screen evaluates the capabilities `S0', `E0', and `C0' if +present. `S0' is the sequence the terminal uses to enable and start the +graphics character set rather than `SI'. `E0' is the corresponding +replacement for `SO'. `C0' gives a character by character translation +string that is used during semi-graphics mode. This string is built +like the `acsc' terminfo capability. + + When the `po' and `pf' capabilities are present in the terminal's +termcap entry, applications running in a `screen' window can send +output to the printer port of the terminal. This allows a user to have +an application in one window sending output to a printer connected to +the terminal, while all other windows are still active (the printer +port is enabled and disabled again for each chunk of output). As a +side-effect, programs running in different windows can send output to +the printer simultaneously. Data sent to the printer is not displayed +in the window. + + Some capabilities are only put into the `$TERMCAP' variable of the +virtual terminal if they can be efficiently implemented by the physical +terminal. For instance, `dl' (delete line) is only put into the +`$TERMCAP' variable if the terminal supports either delete line itself +or scrolling regions. Note that this may provoke confusion, when the +session is reattached on a different terminal, as the value of +`$TERMCAP' cannot be modified by parent processes. You can force +`screen' to include all capabilities in `$TERMCAP' with the `-a' +command-line option (*note Invoking Screen::.). + + +File: screen.info, Node: Dump Termcap, Next: Termcap Syntax, Prev: Window Termcap, Up: Termcap + +Write out the window's termcap entry +==================================== + + - Command: dumptermcap + (`C-a .') + Write the termcap entry for the virtual terminal optimized for the + currently active window to the file `.termcap' in the user's + `$HOME/.screen' directory (or wherever `screen' stores its + sockets. *note Files::.). This termcap entry is identical to the + value of the environment variable `$TERMCAP' that is set up by + `screen' for each window. For terminfo based systems you will need + to run a converter like `captoinfo' and then compile the entry with + `tic'. + + +File: screen.info, Node: Termcap Syntax, Next: Termcap Examples, Prev: Dump Termcap, Up: Termcap + +The `termcap' command +===================== + + - Command: termcap TERM TERMINAL-TWEAKS [WINDOW-TWEAKS] + - Command: terminfo TERM TERMINAL-TWEAKS [WINDOW-TWEAKS] + - Command: termcapinfo TERM TERMINAL-TWEAKS [WINDOW-TWEAKS] + (none) + Use this command to modify your terminal's termcap entry without + going through all the hassles involved in creating a custom + termcap entry. Plus, you can optionally customize the termcap + generated for the windows. You have to place these commands in + one of the screenrc starup files, as they are meaningless once the + terminal emulator is booted. + + If your system uses the terminfo database rather than termcap, + `screen' will understand the `terminfo' command which has the same + effects as the `termcap' command. Two separate commands are + provided, as there are subtle syntactic differences, e.g. when + parameter interpolation (using `%') is required. Note that the + termcap names of the capabilities have to be used with the + `terminfo' command. + + In many cases, where the arguments are valid in both terminfo and + termcap syntax, you can use the command `termcapinfo', which is + just a shorthand for a pair of `termcap' and `terminfo' commands + with identical arguments. + + The first argument specifies which terminal(s) should be affected by +this definition. You can specify multiple terminal names by separating +them with `|'s. Use `*' to match all terminals and `vt*' to match all +terminals that begin with `vt'. + + Each TWEAK argument contains one or more termcap defines (separated +by `:'s) to be inserted at the start of the appropriate termcap entry, +enhancing it or overriding existing values. The first tweak modifies +your terminal's termcap, and contains definitions that your terminal +uses to perform certain functions. Specify a null string to leave this +unchanged (e.g. ""). The second (optional) tweak modifies all the +window termcaps, and should contain definitions that screen understands +(*note Virtual Terminal::.). + + +File: screen.info, Node: Termcap Examples, Next: Special Capabilities, Prev: Termcap Syntax, Up: Termcap + +Termcap Examples +================ + + Some examples: + + termcap xterm* xn:hs@ + +Informs `screen' that all terminals that begin with `xterm' have firm +auto-margins that allow the last position on the screen to be updated +(xn), but they don't really have a status line (no 'hs' - append `@' to +turn entries off). Note that we assume `xn' for all terminal names +that start with `vt', but only if you don't specify a termcap command +for that terminal. + + termcap vt* xn + termcap vt102|vt220 Z0=\E[?3h:Z1=\E[?3l + +Specifies the firm-margined `xn' capability for all terminals that +begin with `vt', and the second line will also add the escape-sequences +to switch into (Z0) and back out of (Z1) 132-character-per-line mode if +this is a VT102 or VT220. (You must specify Z0 and Z1 in your termcap +to use the width-changing commands.) + + termcap vt100 "" l0=PF1:l1=PF2:l2=PF3:l3=PF4 + +This leaves your vt100 termcap alone and adds the function key labels to +each window's termcap entry. + + termcap h19|z19 am@:im=\E@:ei=\EO dc=\E[P + +Takes a h19 or z19 termcap and turns off auto-margins (am@) and enables +the insert mode (im) and end-insert (ei) capabilities (the `@' in the +`im' string is after the `=', so it is part of the string). Having the +`im' and `ei' definitions put into your terminal's termcap will cause +screen to automatically advertise the character-insert capability in +each window's termcap. Each window will also get the delete-character +capability (dc) added to its termcap, which screen will translate into +a line-update for the terminal (we're pretending it doesn't support +character deletion). + + If you would like to fully specify each window's termcap entry, you +should instead set the `$SCREENCAP' variable prior to running `screen'. +*Note Virtual Terminal::, for the details of the `screen' terminal +emulation. *Note Termcap: (termcap)Top, for more information on +termcap definitions. + + +File: screen.info, Node: Special Capabilities, Next: Autonuke, Prev: Termcap Examples, Up: Termcap + +Special Terminal Capabilities +============================= + + The following table describes all terminal capabilities that are +recognized by `screen' and are not in the termcap manual (*note +Termcap: (termcap)Top.). You can place these capabilities in your +termcap entries (in `/etc/termcap') or use them with the commands +`termcap', `terminfo' and `termcapinfo' in your `screenrc' files. It is +often not possible to place these capabilities in the terminfo database. +`LP' + (bool) + Terminal has VT100 style margins (`magic margins'). Note that this + capability is obsolete -- `screen' now uses the standard `xn' + instead. + +`Z0' + (str) + Change width to 132 columns. + +`Z1' + (str) + Change width to 80 columns. + +`WS' + (str) + Resize display. This capability has the desired width and height as + arguments. SunView(tm) example: `\E[8;%d;%dt'. + +`NF' + (bool) + Terminal doesn't need flow control. Send ^S and ^Q direct to the + application. Same as `flow off'. The opposite of this capability + is `nx'. + +`G0' + (bool) + Terminal can deal with ISO 2022 font selection sequences. + +`S0' + (str) + Switch charset `G0' to the specified charset. Default is `\E(%.'. + +`E0' + (str) + Switch charset `G0' back to standard charset. Default is `\E(B'. + +`C0' + (str) + Use the string as a conversion table for font 0. See the `ac' + capability for more details. + +`CS' + (str) + Switch cursor keys to application mode. + +`CE' + (str) + Switch cursor keys to cursor mode. + +`AN' + (bool) + Enable autonuke for displays of this terminal type. (*note + Autonuke::.). + +`OL' + (num) + Set the output buffer limit. See the `obuflimit' command (*note + Obuflimit::.) for more details. + +`KJ' + (str) + Set the kanji type of the terminal. Valid strings are `jis', `euc' + and `sjis'. + +`AF' + (str) + Change character forground color in an ANSI conform way. This + capability will almost always be set to `\E[3%dm' (`\E[3%p1%dm' on + terminfo machines). + +`AB' + (str) + Same as `AF', but change background color. + +`AX' + (bool) + Does understand ANSI set default fg/bg color (`\E[39m / \E[49m'). + +`XC' + (str) + Describe a translation of characters to strings depending on the + current font. (*note Character Translation::.). + + +File: screen.info, Node: Autonuke, Next: Obuflimit, Prev: Special Capabilities, Up: Termcap + +Autonuke +======== + + - Command: autonuke STATE + (none) + Sets whether a clear screen sequence should nuke all the output + that has not been written to the terminal. *Note Obuflimit::. + This property is set per display, not per window. + + - Command: defautonuke STATE + (none) + Same as the `autonuke' command except that the default setting for + new displays is also changed. Initial setting is `off'. Note that + you can use the special `AN' terminal capability if you want to + have a terminal type dependent setting. + + +File: screen.info, Node: Obuflimit, Next: Character Translation, Prev: Autonuke, Up: Termcap + +Obuflimit +========= + + - Command: obuflimit [LIMIT] + (none) + If the output buffer contains more bytes than the specified limit, + no more data will be read from the windows. The default value is + 256. If you have a fast display (like `xterm'), you can set it to + some higher value. If no argument is specified, the current + setting is displayed. This property is set per display, not per + window. + + - Command: defobuflimit LIMIT + (none) + Same as the `obuflimit' command except that the default setting + for new displays is also changed. Initial setting is 256 bytes. + Note that you can use the special `OL' terminal capability if you + want to have a terminal type dependent limit. + + +File: screen.info, Node: Character Translation, Prev: Obuflimit, Up: Termcap + +Character Translation +===================== + + `Screen' has a powerful mechanism to translate characters to +arbitrary strings depending on the current font and terminal type. Use +this feature if you want to work with a common standard character set +(say ISO8851-latin1) even on terminals that scatter the more unusual +characters over several national language font pages. + + Syntax: + + XC=<CHARSET-MAPPING>{,,<CHARSET-MAPPING>} + <CHARSET-MAPPING> := <DESIGNATOR><TEMPLATE>{,<MAPPING>} + <MAPPING> := <CHAR-TO-BE-MAPPED><TEMPLATE-ARG> + + The things in braces may be repeated any number of times. + + A <CHARSET-MAPPING> tells screen how to map characters in font +<DESIGNATOR> (`B': Ascii, `A': UK, `K': german, etc.) to strings. Every +<MAPPING> describes to what string a single character will be +translated. A template mechanism is used, as most of the time the codes +have a lot in common (for example strings to switch to and from another +charset). Each occurence of `%' in <TEMPLATE> gets substituted with the +TEMPLATE-ARG specified together with the character. If your strings are +not similar at all, then use `%' as a template and place the full +string in <TEMPLATE-ARG>. A quoting mechanism was added to make it +possible to use a real `%'. The `\' character quotes the special +characters `\', `%', and `,'. + + Here is an example: + + termcap hp700 'XC=B\E(K%\E(B,\304[,\326\\\\,\334]' + + This tells `screen', how to translate ISOlatin1 (charset `B') upper +case umlaut characters on a `hp700' terminal that has a german charset. +`\304' gets translated to `\E(K[\E(B' and so on. Note that this line +gets parsed *three* times before the internal lookup table is built, +therefore a lot of quoting is needed to create a single `\'. + + Another extension was added to allow more emulation: If a mapping +translates the unquoted `%' char, it will be sent to the terminal +whenever screen switches to the corresponding <DESIGNATOR>. In this +special case the template is assumed to be just `%' because the charset +switch sequence and the character mappings normaly haven't much in +common. + + This example shows one use of the extension: + termcap xterm 'XC=K%,%\E(B,[\304,\\\\\326,]\334' + + Here, a part of the german (`K') charset is emulated on an xterm. +If screen has to change to the `K' charset, `\E(B' will be sent to the +terminal, i.e. the ASCII charset is used instead. The template is just +`%', so the mapping is straightforward: `[' to `\304', `\' to `\326', +and `]' to `\334'. + + +File: screen.info, Node: Message Line, Next: Logging, Prev: Termcap, Up: Top + +The Message Line +**************** + + `screen' displays informational messages and other diagnostics in a +"message line" at the bottom of the screen. If your terminal has a +status line defined in its termcap, screen will use this for displaying +its messages, otherwise the last line of the screen will be temporarily +overwritten and output will be momentarily interrupted. The message +line is automatically removed after a few seconds delay, but it can also +be removed early (on terminals without a status line) by beginning to +type. + +* Menu: + +* Privacy Message:: Using the message line from your program. +* Hardware Status Line:: Use the terminal's hardware status line. +* Last Message:: Redisplay the last message. +* Message Wait:: Control how long messages are displayed. + + +File: screen.info, Node: Privacy Message, Next: Hardware Status Line, Up: Message Line + +Using the message line from your program +======================================== + + The message line facility can be used by an application running in +the current window by means of the ANSI "Privacy message" control +sequence. For instance, from within the shell, try something like: + + echo "^Hello world from window $WINDOW\" + + where `' is ASCII ESC and `^' is a literal caret or up-arrow. + + +File: screen.info, Node: Hardware Status Line, Next: Last Message, Prev: Privacy Message, Up: Message Line + +Hardware Status Line +==================== + + - Command: hardstatus [STATE] + (none) + Toggles the use of the terminal's hardware status line. If `on', + `screen' will use this facility to display one line messages. + Otherwise these messages are overlayed in reverse video mode at the + display line. Note that the hardstatus feature can only be used if + the termcap/terminfo capabilities "hs", "ts", "fs" and "ds" are set + properly. Default is `on' whenever the "hs" capability is present. + + +File: screen.info, Node: Last Message, Next: Message Wait, Prev: Hardware Status Line, Up: Message Line + +Display Last Message +==================== + + - Command: lastmsg + (`C-a m', `C-a C-m') + Repeat the last message displayed in the message line. Useful if + you're typing when a message appears, because (unless your + terminal has a hardware status line) the message goes away when + you press a key. + + +File: screen.info, Node: Message Wait, Prev: Last Message, Up: Message Line + +Message Wait +============ + + - Command: msgminwait SEC + (none) + Defines the time `screen' delays a new message when another is + currently displayed. Defaults to 1 second. + + - Command: msgwait SEC + (none) + Defines the time a message is displayed, if `screen' is not + disturbed by other activity. Defaults to 5 seconds. + + +File: screen.info, Node: Logging, Next: Startup, Prev: Message Line, Up: Top + +Logging +******* + + This section describes the commands for keeping a record of your +session. + +* Menu: + +* Hardcopy:: Dump the current screen to a file +* Log:: Log the output of a window to a file + + +File: screen.info, Node: Hardcopy, Next: Log, Up: Logging + +hardcopy +======== + + - Command: hardcopy + (`C-a h', `C-a C-h') + Writes out the current display contents to the file `hardcopy.N' + in the window's default directory, where N is the number of the + current window. This either appends or overwrites the file if it + exists, as determined by the `hardcopy_append' command. + + - Command: hardcopy_append STATE + (none) + If set to `on', `screen' will append to the `hardcopy.N' files + created by the command `hardcopy'; otherwise, these files are + overwritten each time. + + - Command: hardcopydir DIRECTORY + (none) + Defines a directory where hardcopy files will be placed. If unset + hardcopys are dumped in screen's current working directory. + + +File: screen.info, Node: Log, Prev: Hardcopy, Up: Logging + +log +=== + + - Command: log [STATE] + (`C-a H') + Begins/ends logging of the current window to the file + `screenlog.N' in the window's default directory, where N is the + number of the current window. This filename can be changed with + the `logfile' command. If no parameter is given, the logging + state is toggled. The session log is appended to the previous + contents of the file if it already exists. The current contents + and the contents of the scrollback history are not included in the + session log. Default is `off'. + + - Command: logfile FILENAME + (none) + Defines the name the logfiles will get. The default is + `screenlog.%n'. + + +File: screen.info, Node: Startup, Next: Miscellaneous, Prev: Logging, Up: Top + +Startup +******* + + This section describes commands which are only useful in the +`.screenrc' file, for use at startup. + +* Menu: + +* echo:: Display a message. +* sleep:: Pause execution of the `.screenrc'. +* Startup Message:: Control display of the copyright notice. + + +File: screen.info, Node: echo, Next: sleep, Up: Startup + +echo +==== + + - Command: echo [-n] MESSAGE + (none) + The echo command may be used to annoy `screen' users with a + 'message of the day'. Typically installed in a global screenrc. + The option `-n' may be used to suppress the line feed. See also + `sleep'. Echo is also useful for online checking of environment + variables. + + +File: screen.info, Node: sleep, Next: Startup Message, Prev: echo, Up: Startup + +sleep +===== + + - Command: sleep NUM + (none) + This command will pause the execution of a .screenrc file for NUM + seconds. Keyboard activity will end the sleep. It may be used to + give users a chance to read the messages output by `echo'. + + +File: screen.info, Node: Startup Message, Prev: sleep, Up: Startup + +Startup Message +=============== + + - Command: startup_message STATE + (none) + Select whether you want to see the copyright notice during startup. + Default is `on', as you probably noticed. + + +File: screen.info, Node: Miscellaneous, Next: Environment, Prev: Startup, Up: Top + +Miscellaneous commands +********************** + + The commands described here do not fit well under any of the other +categories. + +* Menu: + +* At:: Execute a command at other displays or windows. +* Break:: Send a break signal to the window. +* Debug:: Suppress/allow debugging output. +* License:: Display the disclaimer page. +* Nethack:: Use `nethack'-like error messages. +* Number:: Change the current window's number. +* Silence:: Notify on inactivity. +* Time:: Display the time and load average. +* Version:: Display the version of `screen'. +* Zombie:: Keep dead windows. +* Printcmd:: Set command for VT100 printer port emulation. +* Sorendition:: Change the text highlighting method. + + +File: screen.info, Node: At, Next: Break, Up: Miscellaneous + +At +== + + - Command: at [IDENTIFIER][#|*|%] COMMAND [ARGS] + (none) + Execute a command at other displays or windows as if it had been + entered there. `At' changes the context (the `current window' or + `current display' setting) of the command. If the first parameter + describes a non-unique context, the command will be executed + multiple times. If the first parameter is of the form + `IDENTIFIER*' then identifier is matched against user names. The + command is executed once for each display of the selected user(s). + If the first parameter is of the form `IDENTIFIER%' identifier is + matched against displays. Displays are named after the ttys they + attach. The prefix `/dev/' or `/dev/tty' may be omitted from the + identifier. If IDENTIFIER has a `#' or nothing appended it is + matched against window numbers and titles. Omitting an identifier + in front of the `#', `*' or `%' character selects all users, + displays or windows because a prefix-match is performed. Note that + on the affected display(s) a short message will describe what + happened. Caution: Permission is checked for the owners or the + affected display(s), not for the initiator of the `at' command. + + +File: screen.info, Node: Break, Next: Debug, Prev: At, Up: Miscellaneous + +Break +===== + + - Command: break [DURATION] + (none) + Send a break signal for DURATION*0.25 seconds to this window. + Most useful if a character device is attached to the window rather + than a shell process. + + - Command: pow_break + (none) + Reopen the window's terminal line and send a break condition. + + +File: screen.info, Node: Debug, Next: License, Prev: Break, Up: Miscellaneous + +Debug +===== + + - Command: debug [ON|OFF] + (none) + Turns runtime debugging on or off. If `screen' has been compiled + with option `-DDEBUG' debugging is available and is turned on per + default. Note that this command only affects debugging output + from the main `SCREEN' process. + + +File: screen.info, Node: License, Next: Nethack, Prev: Debug, Up: Miscellaneous + +License +======= + + - Command: license + (none) + Display the disclaimer page. This is done whenever `screen' is + started without options, which should be often enough. + + +File: screen.info, Node: Nethack, Next: Number, Prev: License, Up: Miscellaneous + +Nethack +======= + + - Command: nethack STATE + (none) + Changes the kind of error messages used by `screen'. When you are + familiar with the game `nethack', you may enjoy the nethack-style + messages which will often blur the facts a little, but are much + funnier to read. Anyway, standard messages often tend to be + unclear as well. + + This option is only available if `screen' was compiled with the + NETHACK flag defined (*note Installation::.). The default setting + is then determined by the presence of the environment variable + `$NETHACKOPTIONS'. + + +File: screen.info, Node: Number, Next: Silence, Prev: Nethack, Up: Miscellaneous + +Number +====== + + - Command: number [N] + (`C-a N') + Change the current window's number. If the given number N is + already used by another window, both windows exchange their + numbers. If no argument is specified, the current window number + (and title) is shown. + + +File: screen.info, Node: Silence, Next: Time, Prev: Number, Up: Miscellaneous + +Silence +======= + + - Command: silence [STATE|SEC] + (none) + Toggles silence monitoring of windows. When silence is turned on + and an affected window is switched into the background, you will + receive the silence notification message in the status line after + a specified period of inactivity (silence). The default timeout + can be changed with the `silencewait' command or by specifying a + number of seconds instead of `on' or `off'. Silence is initially + off for all windows. + + - Command: silencewait SECONDS + (none) + Define the time that all windows monitored for silence should wait + before displaying a message. Default is 30 seconds. + + +File: screen.info, Node: Time, Next: Version, Prev: Silence, Up: Miscellaneous + +Time +==== + + - Command: time + (`C-a t', `C-a C-t') + Uses the message line to display the time of day, the host name, + and the load averages over 1, 5, and 15 minutes (if this is + available on your system). For window-specific information use + `info' (*note Info::.). + + +File: screen.info, Node: Version, Next: Zombie, Prev: Time, Up: Miscellaneous + +Version +======= + + - Command: version + (`C-a v') + Display the version and modification date in the message line. + + +File: screen.info, Node: Zombie, Next: Printcmd, Prev: Version, Up: Miscellaneous + +Zombie +====== + + - Command: zombie [KEYX] + - Command: defzombie [KEYX] + (none) + Per default windows are removed from the window list as soon as the + windows process (e.g. shell) exits. When a string of two keys is + specified to the zombie command, `dead' windows will remain in the + list. The `kill' kommand may be used to remove the window. + Pressing the first key in the dead window has the same effect. + Pressing the second key, however, screen will attempt to resurrect + the window. The process that was initially running in the window + will be launched again. Calling `zombie' without parameters will + clear the zombie setting, thus making windows disappear when the + process terminates. + + As the zombie setting is affected globally for all windows, this + command should only be called `defzombie'. Until we need this as a + per window setting, the commands `zombie' and `defzombie' are + synonymous. + + +File: screen.info, Node: Printcmd, Next: Sorendition, Prev: Zombie, Up: Miscellaneous + +Printcmd +======== + + - Command: printcmd [CMD] + (none) + If CMD is not an empty string, screen will not use the terminal + capabilities `po/pf' for printing if it detects an ansi print + sequence `ESC [ 5 i', but pipe the output into CMD. This should + normally be a command like `lpr' or `cat > /tmp/scrprint'. + `Printcmd' without an argument displays the current setting. The + ansi sequence `ESC \' ends printing and closes the pipe. + + Warning: Be careful with this command! If other user have write + access to your terminal, they will be able to fire off print + commands. + + +File: screen.info, Node: Sorendition, Prev: Printcmd, Up: Miscellaneous + +Sorendition +=========== + + - Command: sorendition [ATTR [COLOR]] + (none) + Change the way screen does highlighting for text marking and + printing messages. ATTR is a hexadecimal number and describes the + attributes (inverse, underline, ...) the text will get. COLOR is + a 2 digit number and changes the forground/background of the + highlighted text. Some knowledge of screen's internal character + representation is needed to make the characters appear in the + desired way. The default is currently `10 99' (standout, default + colors). + + +File: screen.info, Node: Environment, Next: Files, Prev: Miscellaneous, Up: Top + +Environment Variables +********************* + +`COLUMNS' + Number of columns on the terminal (overrides termcap entry). + +`HOME' + Directory in which to look for .screenrc. + +`ISCREENRC' + Alternate user screenrc file. + +`LINES' + Number of lines on the terminal (overrides termcap entry). + +`LOCKPRG' + Screen lock program. + +`NETHACKOPTIONS' + Turns on `nethack' option. + +`PATH' + Used for locating programs to run. + +`SCREENCAP' + For customizing a terminal's `TERMCAP' value. + +`SCREENDIR' + Alternate socket directory. + +`SCREENRC' + Alternate user screenrc file. + +`SHELL' + Default shell program for opening windows (default `/bin/sh'). + +`STY' + Alternate socket name. If `screen' is invoked, and the environment + variable `STY' is set, then it creates only a window in the + running `screen' session rather than starting a new session. + +`SYSSCREENRC' + Alternate system screenrc file. + +`TERM' + Terminal name. + +`TERMCAP' + Terminal description. + + +File: screen.info, Node: Files, Next: Credits, Prev: Environment, Up: Top + +Files Referenced +**************** + +`.../screen-3.?.??/etc/screenrc' +`.../screen-3.?.??/etc/etcscreenrc' + Examples in the `screen' distribution package for private and + global initialization files. + +``$SYSSCREENRC'' +`/local/etc/screenrc' + `screen' initialization commands + +``$ISCREENRC'' +``$SCREENRC'' +``$HOME'/.iscreenrc' +``$HOME'/.screenrc' + Read in after /local/etc/screenrc + +``$ISCREENDIR'/S-LOGIN' +``$SCREENDIR'/S-LOGIN' +`/local/screens/S-LOGIN' + Socket directories (default) + +`/usr/tmp/screens/S-LOGIN' + Alternate socket directories. + +`SOCKET DIRECTORY/.termcap' + Written by the `dumptermcap' command + +`/usr/tmp/screens/screen-exchange or' +`/tmp/screen-exchange' + `screen' interprocess communication buffer + +`hardcopy.[0-9]' + Screen images created by the hardcopy command + +`screenlog.[0-9]' + Output log files created by the log command + +`/usr/lib/terminfo/?/* or' +`/etc/termcap' + Terminal capability databases + +`/etc/utmp' + Login records + +``$LOCKPRG'' + Program for locking the terminal. + + +File: screen.info, Node: Credits, Next: Bugs, Prev: Files, Up: Top + +Credits +******* + +Authors +======= + + Originally created by Oliver Laumann, this latest version was +produced by Wayne Davison, Juergen Weigert and Michael Schroeder. + +Contributors +============ + + Ken Beal (kbeal@amber.ssd.csd.harris.com), + Rudolf Koenig (rfkoenig@informatik.uni-erlangen.de), + Toerless Eckert (eckert@informatik.uni-erlangen.de), + Wayne Davison (davison@borland.com), + Patrick Wolfe (pat@kai.com, kailand!pat), + Bart Schaefer (schaefer@cse.ogi.edu), + Nathan Glasser (nathan@brokaw.lcs.mit.edu), + Larry W. Virden (lvirden@cas.org), + Howard Chu (hyc@hanauma.jpl.nasa.gov), + Tim MacKenzie (tym@dibbler.cs.monash.edu.au), + Markku Jarvinen (mta@{cc,cs,ee}.tut.fi), + Marc Boucher (marc@CAM.ORG), + Doug Siebert (dsiebert@isca.uiowa.edu), + Ken Stillson (stillson@tsfsrv.mitre.org), + Ian Frechett (frechett@spot.Colorado.EDU), + Brian Koehmstedt (bpk@gnu.ai.mit.edu), + Don Smith (djs6015@ultb.isc.rit.edu), + Frank van der Linden (vdlinden@fwi.uva.nl), + Martin Schweikert (schweik@cpp.ob.open.de), + David Vrona (dave@sashimi.lcu.com), + E. Tye McQueen (tye%spillman.UUCP@uunet.uu.net), + Matthew Green (mrgreen@mame.mu.oz.au), + Christopher Williams (cgw@unt.edu), + Matt Mosley (mattm@access.digex.net), + Gregory Neil Shapiro (gshapiro@wpi.WPI.EDU), + Jason Merrill (jason@jarthur.Claremont.EDU). + +Version +======= + + This manual describes version 3.7.0 of the `screen' program. Its +roots are a merge of a custom version 2.3PR7 by Wayne Davison and +several enhancements to Oliver Laumann's version 2.0. Note that all +versions numbered 2.x are copyright by Oliver Laumann. + + See also *Note Availability::. + + +File: screen.info, Node: Bugs, Next: Installation, Prev: Credits, Up: Top + +Bugs +**** + + Just like any other significant piece of software, `screen' has a +few bugs and missing features. Please send in a bug report if you have +found a bug not mentioned here. + +* Menu: + +* Known Bugs:: Problems we know about. +* Reporting Bugs:: How to contact the maintainers. +* Availability:: Where to find the lastest screen version. + + +File: screen.info, Node: Known Bugs, Next: Reporting Bugs, Up: Bugs + +Known Bugs +========== + + * `dm' (delete mode) and `xs' are not handled correctly (they are + ignored). `xn' is treated as a magic-margin indicator. + + * `screen' has no clue about double-high or double-wide characters. + But this is the only area where `vttest' is allowed to fail. + + * It is not possible to change the environment variable `$TERMCAP' + when reattaching under a different terminal type. + + * The support of terminfo based systems is very limited. Adding extra + capabilities to `$TERMCAP' may not have any effects. + + * `screen' does not make use of hardware tabs. + + * `screen' must be installed setuid root in order to be able to + correctly change the owner of the tty device file for each window. + Special permission may also be required to write the file + `/etc/utmp'. + + * Entries in `/etc/utmp' are not removed when `screen' is killed + with SIGKILL. This will cause some programs (like "w" or "rwho") + to advertise that a user is logged on who really isn't. + + * `screen' may give a strange warning when your tty has no utmp + entry. + + * When the modem line was hung up, `screen' may not automatically + detach (or quit) unless the device driver sends a HANGUP signal. + To detach such a `screen' session use the -D or -d command line + option. + + * A weird imagination is most useful to gain full advantage of all + the features. + |