diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/screen.texinfo | 6097 |
1 files changed, 6097 insertions, 0 deletions
diff --git a/doc/screen.texinfo b/doc/screen.texinfo new file mode 100644 index 0000000..cb14aae --- /dev/null +++ b/doc/screen.texinfo @@ -0,0 +1,6097 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@c vi:set wm=5 +@setfilename screen.info +@settitle Screen User's Manual +@dircategory General Commands +@finalout +@setchapternewpage odd +@c %**end of header +@set version 4.6.2 + +@direntry +* Screen: (screen). Full-screen window manager. +@end direntry + +@c For examples, use a literal escape in info. +@ifinfo +@set esc ^[ +@end ifinfo +@iftex +@set esc <ESC> +@end iftex + +@ifinfo +This file documents the @code{Screen} virtual terminal manager. + +Copyright (c) 1993-2017 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. + +@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 Foundation. +@end ifinfo + +@titlepage +@title Screen +@subtitle The virtual terminal manager +@subtitle for Version @value{version} +@subtitle Feb 2017 + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1993-2017 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. +@end titlepage + +@shortcontents +@contents + +@node Top, Overview, (dir), (dir) + +@ifinfo +@top Screen +This file documents the @code{Screen} virtual terminal manager, version +@value{version}. +@end ifinfo + +@menu +* Overview:: Preliminary information. +* Getting Started:: An introduction to @code{screen}. +* Invoking Screen:: Command line options for @code{screen}. +* Customization:: The @file{.screenrc} file. +* Commands:: List all of the commands. +* New Window:: Running a program in a new window. +* Selecting:: Selecting a window to display. +* Session Management:: Suspend/detach, grant access, connect sessions. +* Regions:: Split-screen commands. +* Window Settings:: Titles, logging, etc. +* Virtual Terminal:: Controlling the @code{screen} VT100 emulation. +* Copy and Paste:: Exchanging text between windows and sessions. +* Subprocess Execution:: I/O filtering with @code{exec}. +* Key Binding:: Binding commands to keys. +* Flow Control:: Trap or pass flow control characters. +* Termcap:: Tweaking your terminal's termcap entry. +* Message Line:: The @code{screen} message line. +* Logging:: Keeping a record of your session. +* Startup:: Functions only useful at @code{screen} startup. +* Miscellaneous:: Various other commands. +* String Escapes:: Inserting current information into strings +* Environment:: Environment variables used by @code{screen}. +* Files:: Files used by @code{screen}. +* Credits:: Who's who of @code{screen}. +* Bugs:: What to do if you find a bug. +* Installation:: Getting @code{screen} running on your system. +* Concept Index:: Index of concepts. +* Command Index:: Index of all @code{screen} commands. +* Keystroke Index:: Index of default key bindings. +@end menu + +@node Overview, Getting Started, Top, Top +@chapter Overview +@cindex overview + +Screen is a full-screen window manager that multiplexes a physical +terminal between several processes, typically interactive shells. Each +virtual terminal provides the functions of the DEC VT100 terminal and, +in addition, several control functions from the ISO 6429 (ECMA 48, ANSI X3.64) +and ISO 2022 standards (e.g. insert/delete line and support for multiple +character sets). There is a scrollback history buffer for each virtual +terminal and a copy-and-paste mechanism that allows the user to move +text regions between windows. + +When @code{screen} is called, it creates a single window with a shell in +it (or the specified command) and then gets out of your way so that you +can use the program as you normally would. Then, at any time, you can +create new (full-screen) windows with other programs in them (including +more shells), kill the current window, view a list of the active +windows, turn output logging on and off, copy text between windows, view +the scrollback history, switch between windows, etc. All windows run +their programs completely independent of each other. Programs continue +to run when their window is currently not visible and even when the +whole screen session is detached from the user's terminal. + +When a program terminates, @code{screen} (per default) kills the window +that contained it. If this window was in the foreground, the display +switches to the previously displayed window; if none are left, +@code{screen} exits. Shells usually distinguish between running as login-shell or sub-shell. +Screen runs them as sub-shells, unless told otherwise (See @code{shell} .screenrc command). + +Everything you type is sent to the program running in the current +window. The only exception to this is the one keystroke that is used to +initiate a command to the window manager. By default, each command +begins with a control-a (abbreviated @kbd{C-a} from now on), and is +followed by one other keystroke. The command character (@pxref{Command +Character}) and all the key bindings (@pxref{Key Binding}) can be fully +customized to be anything you like, though they are always two +characters in length. + +@code{Screen} does not understand the prefix @kbd{C-} to mean control, although +this notation is used in this manual for readability. +Please use the caret notation (@kbd{^A} instead of @kbd{C-a}) as arguments +to e.g. the @code{escape} command or the @code{-e} option. @code{Screen} +will also print out control characters in caret notation. + +The standard way to create a new window is to type @kbd{C-a c}. This +creates a new window running a shell and switches to that window +immediately, regardless of the state of the process running in the +current window. Similarly, you can create a new window with a custom +command in it by first binding the command to a keystroke (in your +@file{.screenrc} file or at the @kbd{C-a :} command line) and then using it +just like the @kbd{C-a c} command. In addition, new windows can be created by +running a command like: + +@example +screen emacs prog.c +@end example + +@noindent +from a shell prompt within a previously created window. This will not +run another copy of @code{screen}, but will instead supply the command +name and its arguments to the window manager (specified in the $STY environment +variable) who will use it to create the new window. The above example would +start the @code{emacs} editor (editing @file{prog.c}) and switch to its window. +- Note that you cannot transport environment variables from +the invoking shell to the application (emacs in this case), because it is +forked from the parent screen process, not from the invoking shell. + +If @file{/etc/utmp} is writable by @code{screen}, an appropriate record +will be written to this file for each window, and removed when the +window is closed. This is useful for working with @code{talk}, +@code{script}, @code{shutdown}, @code{rsend}, @code{sccs} and other +similar programs that use the utmp file to determine who you are. As +long as @code{screen} is active on your terminal, the terminal's own +record is removed from the utmp file. @xref{Login}. + +@node Getting Started, Invoking Screen, Overview, Top +@chapter Getting Started +@cindex introduction + +Before you begin to use @code{screen} you'll need to make sure you have +correctly selected your terminal type, just as you would for any other +termcap/terminfo program. (You can do this by using @code{tset}, +@code{qterm}, or just @code{set term=mytermtype}, for example.) + +If you're impatient and want to get started without doing a lot more +reading, you should remember this one command: @kbd{C-a ?} (@pxref{Key +Binding}). Typing these two characters will display a list of the +available @code{screen} commands and their bindings. Each keystroke is +discussed in the section on keystrokes (@pxref{Default Key Bindings}). +Another section (@pxref{Customization}) deals with the contents of your +@file{.screenrc}. + +If your terminal is a ``true'' auto-margin terminal (it doesn't allow +the last position on the screen to be updated without scrolling the +screen) consider using a version of your terminal's termcap that has +automatic margins turned @emph{off}. This will ensure an accurate +and optimal update of the screen in all circumstances. Most terminals +nowadays have ``magic'' margins (automatic margins plus usable last +column). This is the VT100 style type and perfectly suited for +@code{screen}. +If all you've got is a ``true'' auto-margin terminal @code{screen} +will be content to use it, but updating a character put into the last +position on the screen may not be possible until the screen scrolls or +the character is moved into a safe position in some other way. This +delay can be shortened by using a terminal with insert-character +capability. + +@xref{Special Capabilities}, for more information about telling +@code{screen} what kind of terminal you have. + +@node Invoking Screen, Customization, Getting Started, Top +@chapter Invoking @code{Screen} +@cindex invoking +@cindex options +@cindex command line options + +Screen has the following command-line options: + +@table @samp +@item -a +Include @emph{all} capabilities (with some minor exceptions) in each +window's termcap, even if @code{screen} must redraw parts of the display +in order to implement a function. + +@item -A +Adapt the sizes of all windows to the size of the display. By default, +@code{screen} may try to restore its old window sizes when attaching to +resizable terminals (those with @samp{WS} in their descriptions, e.g. +@code{suncmd} or some varieties of @code{xterm}). + +@item -c @var{file} +Use @var{file} as the user's configuration file instead of the default +of @file{$HOME/.screenrc}. + +@item -d [@var{pid.sessionname}] +@itemx -D [@var{pid.sessionname}] +Do not start @code{screen}, but instead detach a @code{screen} session +running elsewhere (@pxref{Detach}). @samp{-d} has the same effect as +typing @kbd{C-a d} from the controlling terminal for the session. +@samp{-D} is the equivalent to the power detach key. If no session can +be detached, this option is ignored. In combination with the +@code{-r}/@code{-R} option more powerful effects can be achieved: + +@table @code +@item -d -r +Reattach a session and if necessary detach it first. +@item -d -R +Reattach a session and if necessary detach or even create it first. +@item -d -RR +Reattach a session and if necessary detach or create it. +Use the first session if more than one session is available. +@item -D -r +Reattach a session. If necessary detach and logout remotely first. +@item -D -R +Attach here and now. In detail this means: If a session is running, +then reattach. If necessary detach and logout remotely first. If it +was not running create it and notify the user. +This is the author's favorite. +@item -D -RR +Attach here and now. Whatever that means, just do it. +@end table + +@emph{Note}: It is a good idea to check the status of your sessions +with @code{screen -list} before using this option. + +@item -e @var{xy} +Set the command character to @var{x}, and the character generating a +literal command character (when typed after the command character) to +@var{y}. The defaults are @kbd{C-a} and @kbd{a}, which can be specified +as @samp{-e^Aa}. When creating a @code{screen} session, this option +sets the default command character. In a multiuser session all users +added will start off with this command character. But when attaching +to an already running session, this option only changes the command +character of the attaching user. +This option is equivalent to the commands @code{defescape} or +@code{escape} respectively. (@pxref{Command Character}). + +@item -f +@itemx -fn +@itemx -fa +Set flow-control to on, off, or automatic switching mode, respectively. +This option is equivalent to the @code{defflow} command (@pxref{Flow +Control}). + +@item -h @var{num} +Set the history scrollback buffer to be @var{num} lines high. +Equivalent to the @code{defscrollback} command (@pxref{Copy}). + +@item -i +Cause the interrupt key (usually @kbd{C-c}) to interrupt the display +immediately when flow control is on. This option is equivalent to the +@code{interrupt} argument to the @code{defflow} command (@pxref{Flow +Control}). Its use is discouraged. + +@item -l +@itemx -ln +Turn login mode on or off (for @file{/etc/utmp} updating). This option +is equivalent to the @code{deflogin} command (@pxref{Login}). + +@item -ls [@var{match}] +@itemx -list [@var{match}] +Do not start @code{screen}, but instead print a list of session +identification strings (usually of the form @var{pid.tty.host}; +@pxref{Session Name}). Sessions marked @samp{detached} can be resumed +with @code{screen -r}. Those marked @samp{attached} are running and +have a controlling terminal. If the session runs in multiuser mode, +it is marked @samp{multi}. Sessions marked as @samp{unreachable} either +live on a different host or are dead. +An unreachable session is considered dead, when its name matches either the +name of the local host, or the specified parameter, if any. +See the @code{-r} flag for a description how to construct matches. +Sessions marked as @samp{dead} should be thoroughly checked and removed. +Ask your system administrator if you are not sure. +Remove sessions with the @samp{-wipe} option. + +@item -L +Tell @code{screen} to turn on automatic output logging for the +windows. + +@item -Logfile "file" +By default logfile name is "screenlog.0". You can set new logfile name +with the @code{-Logfile} option. + +@item -m +Tell @code{screen} to ignore the @code{$STY} environment variable. When +this option is used, a new session will always be created, regardless of +whether @code{screen} is being called from within another @code{screen} +session or not. This flag has a special meaning in connection +with the @samp{-d} option: +@table @code +@item -d -m +Start @code{screen} in @emph{detached} mode. This creates a new +session but doesn't attach to it. This is useful for system startup +scripts. +@item -D -m +This also starts @code{screen} in @emph{detached} mode, but doesn't fork +a new process. The command exits if the session terminates. +@end table + +@item -O +Select a more optimal output mode for your terminal rather than true VT100 +emulation (only affects auto-margin terminals without @samp{LP}). This +can also be set in your @file{.screenrc} by specifying @samp{OP} in the +@code{termcap} command. + +@item -p @var{name_or_number}|-|=|+ +Preselect a window. This is useful when you want to reattach to a +specific window or you want to send a command via the @samp{-X} +option to a specific window. As with screen's select command, @samp{-} +selects the blank window. As a special case for reattach, @samp{=} +brings up the windowlist on the blank window, while a @samp{+} will +create new window. The command will not be executed if the specified +window could not be found. + +@item -q +Suppress printing of error messages. In combination with @samp{-ls} the exit +value is set as follows: 9 indicates a directory without sessions. 10 +indicates a directory with running but not attachable sessions. 11 (or more) +indicates 1 (or more) usable sessions. +In combination with @samp{-r} the exit value is as follows: 10 indicates that +there is no session to resume. 12 (or more) indicates that there are 2 (or +more) sessions to resume and you should specify which one to choose. +In all other cases @samp{-q} has no effect. + +@item -Q +Some commands now can be queried from a remote session using this +flag, e.g. 'screen -Q windows'. The commands will send the +response to the stdout of the querying process. If there was an +error in the command, then the querying process will exit with +a non-zero status. + +The commands that can be queried now are: + @code{echo} + @code{info} + @code{lastmsg} + @code{number} + @code{select} + @code{time} + @code{title} + @code{windows} + +@item -r [@var{pid.sessionname}] +@itemx -r @var{sessionowner}/[@var{pid.sessionname}] +Resume a detached @code{screen} session. No other options (except +combinations with @samp{-d} or @samp{-D}) may be specified, though +the session name +(@pxref{Session Name}) may be needed to distinguish between multiple +detached @code{screen} sessions. +The second form is used to connect to another user's screen session which +runs in multiuser mode. This indicates that screen should look for +sessions in another user's directory. This requires setuid-root. + +@item -R +resumes screen only when it's unambiguous which one to attach, usually +when only one @code{screen} is detached. Otherwise lists available sessions. + +@item -RR +Resume the first appropriate detached @code{screen} session. If +successful, all other command-line options are ignored. If no detached +session exists, start a new session using the specified options, just as +if @samp{-R} had not been specified. This option is set by default if +screen is run as a login-shell (actually screen uses @samp{-xRR} in +that case). +For combinations with the +@samp{-D}/@samp{-d} option see there. + +@item -s @var{program} +Set the default shell to be @var{program}. By default, @code{screen} +uses the value of the environment variable @code{$SHELL}, or +@file{/bin/sh} if it is not defined. This option is equivalent to the +@code{shell} command (@pxref{Shell}). See also there. + +@item -S @var{sessionname} +Set the name of the new session to @var{sessionname}. This option can +be used to specify a meaningful name for the session in place of the +default @var{tty.host} suffix. This name identifies the session for the +@code{screen -list} and @code{screen -r} commands. This option is +equivalent to the @code{sessionname} command (@pxref{Session Name}). + +@item -t @var{name} +Set the title (name) for the default shell or specified program. +This option is equivalent to the @code{shelltitle} command +(@pxref{Shell}). + +@item -T @var{term} +Set the $TERM enviroment variable using the specified @emph{term} as +opposed to the default setting of @code{screen}. + +@item -U +Run screen in UTF-8 mode. This option tells screen that your terminal +sends and understands UTF-8 encoded characters. It also sets the default +encoding for new windows to @samp{utf8}. + +@item -v +Print the version number. + +@item -wipe [@var{match}] +List available screens like @code{screen -ls}, but remove destroyed +sessions instead of marking them as @samp{dead}. +An unreachable session is considered dead, when its name matches either +the name of the local host, or the explicitly given parameter, if any. +See the @code{-r} flag for a description how to construct matches. + +@item -x +Attach to a session which is already attached elsewhere (multi-display +mode). +@code{Screen} refuses to attach from within itself. +But when cascading multiple screens, loops are not detected; take care. + + +@item -X +Send the specified command to a running screen session. You may use +the @code{-S} option to specify the screen session if you have several +running. You can use the @code{-d} or @code{-r} option to tell screen +to look only for attached or detached screen sessions. Note that this +command doesn't work if the session is password protected. + +@end table + +@node Customization, Commands, Invoking Screen, Top +@chapter Customizing @code{Screen} +@cindex customization + +You can modify the default settings for @code{screen} to fit your tastes +either through a personal @file{.screenrc} file which contains commands +to be executed at startup, or on the fly using the @code{colon} command. + +@menu +* Startup Files:: The @file{.screenrc} file. +* Source:: Read commands from a file. +* Colon:: Entering customization commands interactively. +@end menu + +@node Startup Files, Source, , Customization +@section The @file{.screenrc} file +@cindex .screenrc +@cindex screenrc +When @code{screen} is invoked, it executes initialization commands from +the files @file{.screenrc} in the user's home directory and +@file{/usr/local/etc/screenrc}. These defaults can be overridden in the +following ways: +For the global screenrc file @code{screen} searches for the environment +variable @code{$SYSSCREENRC} (this override feature may be disabled at +compile-time). The user specific screenrc file is +searched for in @code{$SCREENRC}, then +@file{@code{$HOME}/.screenrc}. The command line option @samp{-c} +specifies which file to use (@pxref{Invoking Screen}. Commands in these +files are used to set options, bind commands to keys, and to +automatically establish one or more windows at the beginning of +your @code{screen} session. Commands are listed one per line, with +empty lines being ignored. A command's arguments are separated by tabs +or spaces, and may be surrounded by single or double quotes. A @samp{#} +turns the rest of the line into a comment, except in quotes. +Unintelligible lines are warned about and ignored. Commands may contain +references to environment variables. The syntax is the shell-like +@code{$VAR} or @code{$@{VAR@}}. Note that this causes incompatibility +with previous @code{screen} versions, as now the '$'-character has to be +protected with '\' if no variable substitution is intended. A string in +single-quotes is also protected from variable substitution. + +Two configuration files are shipped as examples with your screen +distribution: @file{etc/screenrc} and @file{etc/etcscreenrc}. They +contain a number of useful examples for various commands. + +@node Source, Colon, Startup Files, Customization +@section Source +@deffn Command source file +(none)@* +Read and execute commands from file @var{file}. Source commands +may be nested to a maximum recursion level of ten. If @var{file} +is not an absolute path and screen is already processing a +source command, the parent directory of the running source +command file is used to search for the new command file before +screen's current directory. + +Note that termcap/terminfo/termcapinfo commands only work +at startup and reattach time, so they must be reached via +the default screenrc files to have an effect. +@end deffn + +@node Colon, , Source, Customization +@section Colon +Customization can also be done online, with this command: + +@kindex : +@deffn Command colon +(@kbd{C-a :})@* +Allows you to enter @file{.screenrc} command lines. Useful for +on-the-fly modification of key bindings, specific window creation and +changing settings. Note that the @code{set} keyword no longer exists, +as of version 3.3. Change default settings with commands starting with +@samp{def}. You might think of this as the @code{ex} command mode of +@code{screen}, with @code{copy} as its @code{vi} command mode +(@pxref{Copy and Paste}). +@end deffn + +@node Commands, New Window, Customization, Top +@chapter Commands + +A command in @code{screen} can either be bound to a key, invoked from a +screenrc file, or called from the @code{colon} prompt +(@pxref{Customization}). As of version 3.3, all commands can be bound +to keys, although some may be less useful than others. +For a number of real life working examples of the most important +commands see the files @file{etc/screenrc} and @file{etc/etcscreenrc} +of your screen distribution. + +In this manual, a command definition looks like this: + +@table @asis +@item -- Command: command [-n] ARG1 [ARG2] @dots{} +(@var{keybindings})@* +This command does something, but I can't remember what. +@end table + +An argument in square brackets (@samp{[]}) is optional. Many commands +take an argument of @samp{on} or @samp{off}, which is indicated as +@var{state} in the definition. + +@menu +* Default Key Bindings:: @code{screen} keyboard commands. +* Command Summary:: List of all commands. +@end menu + +@node Default Key Bindings, Command Summary, , Commands +@section Default Key Bindings + +As mentioned previously, each keyboard command consists of a +@kbd{C-a} followed by one other character. For your convenience, all +commands that are bound to lower-case letters are also bound to their +control character counterparts (with the exception of @kbd{C-a a}; see +below). Thus, both @kbd{C-a c} and @kbd{C-a C-c} can be used to create +a window. + +The following table shows the default key bindings: + +@table @asis +@item @kbd{C-a '} +(select)@* +Prompt for a window identifier and switch. +@xref{Selecting}. + +@item @kbd{C-a "} +(windowlist -b)@* +Present a list of all windows for selection. +@xref{Selecting}. + +@item @kbd{C-a 0@dots{}9, -} +(select 0@dots{}select 9, select -)@* +Switch to window number 0@dots{}9, or the blank window. +@xref{Selecting}. + +@item @kbd{C-a @key{Tab}} +(focus)@* +Switch the input focus to the next region. @xref{Regions}. + +@item @kbd{C-a C-a} +(other)@* +Toggle to the window displayed previously. If this window does no +longer exist, @code{other} has the same effect as @code{next}. +@xref{Selecting}. + +@item @kbd{C-a a} +(meta)@* +Send the command character (C-a) to window. See @code{escape} command. +@xref{Command Character}. + +@item @kbd{C-a A} +(title)@* +Allow the user to enter a title for the current window. +@xref{Naming Windows}. + +@item @kbd{C-a b} +@itemx @kbd{C-a C-b} +(break)@* +Send a break to the tty. +@xref{Break}. + +@item @kbd{C-a B} +(pow_break)@* +Close and reopen the tty-line. +@xref{Break}. + +@item @kbd{C-a c} +@itemx @kbd{C-a C-c} +(screen)@* +Create a new window with a shell and switch to that window. +@xref{Screen Command}. + +@item @kbd{C-a C} +(clear)@* +Clear the screen. @xref{Clear}. + +@item @kbd{C-a d} +@itemx @kbd{C-a C-d} +(detach)@* +Detach @code{screen} from this terminal. @xref{Detach}. + +@item @kbd{C-a D D} +(pow_detach)@* +Detach and logout. @xref{Power Detach}. + +@item @kbd{C-a f} +@itemx @kbd{C-a C-f} +(flow)@* +Cycle flow among @samp{on}, @samp{off} or @samp{auto}. @xref{Flow}. + +@item @kbd{C-a F} +(fit)@* +Resize the window to the current region size. @xref{Fit}. + +@item @kbd{C-a C-g} +(vbell)@* +Toggle visual bell mode. @xref{Bell}. + +@item @kbd{C-a h} +(hardcopy)@* +Write a hardcopy of the current window to the file ``hardcopy.@var{n}''. +@xref{Hardcopy}. + +@item @kbd{C-a H} +(log)@* +Toggle logging of the current window to the file ``screenlog.@var{n}''. +@xref{Log}. + +@item @kbd{C-a i} +@itemx @kbd{C-a C-i} +(info)@* +Show info about the current window. @xref{Info}. + +@item @kbd{C-a k} +@itemx @kbd{C-a C-k} +(kill)@* +Destroy the current window. @xref{Kill}. + +@item @kbd{C-a l} +@itemx @kbd{C-a C-l} +(redisplay)@* +Fully refresh the current window. @xref{Redisplay}. + +@item @kbd{C-a L} +(login)@* +Toggle the current window's login state. @xref{Login}. + +@item @kbd{C-a m} +@itemx @kbd{C-a C-m} +(lastmsg)@* +Repeat the last message displayed in the message line. +@xref{Last Message}. + +@item @kbd{C-a M} +(monitor) +Toggle monitoring of the current window. @xref{Monitor}. + +@item @kbd{C-a @key{SPC}} +@itemx @kbd{C-a n} +@itemx @kbd{C-a C-n} +(next)@* +Switch to the next window. @xref{Selecting}. + +@item @kbd{C-a N} +(number)@* +Show the number (and title) of the current window. @xref{Number}. + +@item @kbd{C-a p} +@itemx @kbd{C-a C-p} +@itemx @kbd{C-a C-h} +@itemx @kbd{C-a @key{BackSpace}} +(prev)@* +Switch to the previous window (opposite of @kbd{C-a n}). +@xref{Selecting}. + +@item @kbd{C-a q} +@itemx @kbd{C-a C-q} +(xon)@* +Send a ^Q (ASCII XON) to the current window. @xref{XON/XOFF}. + +@item @kbd{C-a Q} +(only)@* +Delete all regions but the current one. @xref{Regions}. + +@item @kbd{C-a r} +@itemx @kbd{C-a C-r} +(wrap)@* +Toggle the current window's line-wrap setting (turn the current window's +automatic margins on or off). @xref{Wrap}. + +@item @kbd{C-a s} +@itemx @kbd{C-a C-s} +(xoff)@* +Send a ^S (ASCII XOFF) to the current window. @xref{XON/XOFF}. + +@item @kbd{C-a S} +(split)@* +Split the current region horizontally into two new ones. @xref{Regions}. + +@item @kbd{C-a t} +@itemx @kbd{C-a C-t} +(time)@* +Show the load average and xref. @xref{Time}. + +@item @kbd{C-a v} +(version)@* +Display the version and compilation date. @xref{Version}. + +@item @kbd{C-a C-v} +(digraph)@* +Enter digraph. @xref{Digraph}. + +@item @kbd{C-a w} +@itemx @kbd{C-a C-w} +(windows)@* +Show a list of active windows. @xref{Windows}. + +@item @kbd{C-a W} +(width)@* +Toggle between 80 and 132 columns. @xref{Window Size}. + +@item @kbd{C-a x} +@itemx @kbd{C-a C-x} +(lockscreen)@* +Lock your terminal. @xref{Lock}. + +@item @kbd{C-a X} +(remove)@* +Kill the current region. @xref{Regions}. + +@item @kbd{C-a z} +@itemx @kbd{C-a C-z} +(suspend)@* +Suspend @code{screen}. @xref{Suspend}. + +@item @kbd{C-a Z} +(reset)@* +Reset the virtual terminal to its ``power-on'' values. +@xref{Reset}. + +@item @kbd{C-a .} +(dumptermcap)@* +Write out a @file{.termcap} file. @xref{Dump Termcap}. + +@item @kbd{C-a ?} +(help)@* +Show key bindings. @xref{Help}. + +@item @kbd{C-a \} +(quit)@* +Kill all windows and terminate @code{screen}. @xref{Quit}. + +@item @kbd{C-a :} +(colon)@* +Enter a command line. @xref{Colon}. + +@item @kbd{C-a [} +@itemx @kbd{C-a C-[} +@itemx @kbd{C-a @key{ESC}} +(copy)@* +Enter copy/scrollback mode. @xref{Copy}. + +@item @kbd{C-a ]} +@itemx @kbd{C-a C-]} +(paste .)@* +Write the contents of the paste buffer to the stdin queue of the +current window. @xref{Paste}. + +@item @kbd{C-a @{} +@itemx @kbd{C-a @}} +(history)@* +Copy and paste a previous (command) line. @xref{History}. + +@item @kbd{C-a >} +(writebuf)@* +Write the paste buffer out to the screen-exchange file. +@xref{Screen Exchange}. + +@item @kbd{C-a <} +(readbuf)@* +Read the screen-exchange file into the paste buffer. +@xref{Screen Exchange}. + +@item @kbd{C-a =} +(removebuf)@* +Delete the screen-exchange file. @xref{Screen Exchange}. + +@item @kbd{C-a _} +(silence)@* +Start/stop monitoring the current window for inactivity. @xref{Monitor}. + +@item @kbd{C-a |} +(split -v)@* +Split the current region vertically into two new ones. @xref{Regions}. + +@item @kbd{C-a ,} +(license)@* +Show the copyright page. @xref{License}. + +@item @kbd{C-a *} +(displays)@* +Show the listing of attached displays. @xref{Displays}. +@end table + +@node Command Summary, , Default Key Bindings, Commands +@section Command Summary +@cindex command summary + +@table @code +@item acladd @var{usernames} +Allow other users in this session. @xref{Multiuser Session}. +@item aclchg @var{usernames permbits list} +Change a user's permissions. @xref{Multiuser Session}. +@item acldel @var{username} +Disallow other user in this session. @xref{Multiuser Session}. +@item aclgrp @var{usrname} [@var{groupname}] +Inherit permissions granted to a group leader. @xref{Multiuser Session}. +@item aclumask [@var{users}]+/-@var{bits} ... +Predefine access to new windows. @xref{Umask}. +@item activity @var{message} +Set the activity notification message. @xref{Monitor}. +@item addacl @var{usernames} +Synonym to @code{acladd}. @xref{Multiuser Session}. +@item allpartial @var{state} +Set all windows to partial refresh. @xref{Redisplay}. +@item altscreen @var{state} +Enables support for the "alternate screen" terminal capability. @xref{Redisplay}. +@item at [@var{ident}][@kbd{#}@var{|}@kbd{*}@var{|}@kbd{%}] @var{command} [@var{args}] +Execute a command at other displays or windows. @xref{At}. +@item attrcolor @var{attrib} [@var{attribute/color-modifier}] +Map attributes to colors. @xref{Attrcolor}. +@item autodetach @var{state} +Automatically detach the session on SIGHUP. @xref{Detach}. +@item autonuke @var{state} +Enable a clear screen to discard unwritten output. @xref{Autonuke}. +@item backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}] +Define a command for the backtick string escape. @xref{Backtick}. +@item bce [@var{state}] +Change background color erase. @xref{Character Processing}. +@item bell_msg [@var{message}] +Set the bell notification message. @xref{Bell}. +@item bind [-c @var{class}] @var{key} [@var{command} [@var{args}]] +Bind a command to a key. @xref{Bind}. +@item bindkey [@var{opts}] [@var{string} [@var{cmd args}]] +Bind a string to a series of keystrokes. @xref{Bindkey}. +@item blanker +Blank the screen. @xref{Screen Saver}. +@item blankerprg +Define a blanker program. @xref{Screen Saver}. +@item break [@var{duration}] +Send a break signal to the current window. @xref{Break}. +@item breaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}] +Specify how to generate breaks. @xref{Break}. +@item bufferfile [@var{exchange-file}] +Select a file for screen-exchange. @xref{Screen Exchange}. +@item bumpleft +Swaps window with previous one on window list. @xref{Bumpleft}. +@item bumpright +Swaps window with previous one on window list. @xref{Bumpright}. +@item c1 [@var{state}] +Change c1 code processing. @xref{Character Processing}. +@item caption @var{mode} [@var{string}] +Change caption mode and string. @xref{Regions}. +@item chacl @var{usernames permbits list} +Synonym to @code{aclchg}. @xref{Multiuser Session}. +@item charset @var{set} +Change character set slot designation. @xref{Character Processing}. +@item chdir [@var{directory}] +Change the current directory for future windows. @xref{Chdir}. +@item cjkwidth +Treat ambiguous width characters as full/half width. @xref{Character Processing}. +@item clear +Clear the window screen. @xref{Clear}. +@item colon +Enter a @code{screen} command. @xref{Colon}. +@item collapse +Reorders window on window list, removing number gaps between them. @xref{Collapse}. +@item command [-c @var{class}] +Simulate the screen escape key. @xref{Command Character}. +@item compacthist [@var{state}] +Selects compaction of trailing empty lines. @xref{Scrollback}. +@item console [@var{state}] +Grab or ungrab console output. @xref{Console}. +@item copy +Enter copy mode. @xref{Copy}. +@item copy_reg [@var{key}] +Removed. Use @code{paste} instead. @xref{Registers}. +@item crlf @var{state} +Select line break behavior for copying. @xref{Line Termination}. +@item debug @var{state} +Suppress/allow debugging output. @xref{Debug}. +@item defautonuke @var{state} +Select default autonuke behavior. @xref{Autonuke}. +@item defbce @var{state} +Select background color erase. @xref{Character Processing}. +@item defbreaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}] +Specify the default for generating breaks. @xref{Break}. +@item defc1 @var{state} +Select default c1 processing behavior. @xref{Character Processing}. +@item defcharset [@var{set}] +Change defaul character set slot designation. @xref{Character Processing}. +@item defencoding @var{enc} +Select default window encoding. @xref{Character Processing}. +@item defescape @var{xy} +Set the default command and @code{meta} characters. @xref{Command Character}. +@item defflow @var{fstate} +Select default flow control behavior. @xref{Flow}. +@item defgr @var{state} +Select default GR processing behavior. @xref{Character Processing}. +@item defhstatus [@var{status}] +Select default window hardstatus line. @xref{Hardstatus}. +@item deflog @var{state} +Select default window logging behavior. @xref{Log}. +@item deflogin @var{state} +Select default utmp logging behavior. @xref{Login}. +@item defmode @var{mode} +Select default file mode for ptys. @xref{Mode}. +@item defmonitor @var{state} +Select default activity monitoring behavior. @xref{Monitor}. +@item defmousetrack @var{on}|@var{off} +Select the default mouse tracking behavior. @xref{Mousetrack}. +@item defnonblock @var{state}|@var{numsecs} +Select default nonblock mode. @xref{Nonblock}. +@item defobuflimit @var{limit} +Select default output buffer limit. @xref{Obuflimit}. +@item defscrollback @var{num} +Set default lines of scrollback. @xref{Scrollback}. +@item defshell @var{command} +Set the default program for new windows. @xref{Shell}. +@item defsilence @var{state} +Select default idle monitoring behavior. @xref{Monitor}. +@item defslowpaste @var{msec} +Select the default inter-character timeout when pasting. @xref{Paste}. +@item defutf8 @var{state} +Select default character encoding. @xref{Character Processing}. +@item defwrap @var{state} +Set default line-wrapping behavior. @xref{Wrap}. +@item defwritelock @var{on|off|auto} +Set default writelock behavior. @xref{Multiuser Session}. +@item zombie_timeout [@var{seconds}] +Try to reconnect dead windows after timeout. @xref{Zombie}. +@item detach [-h] +Disconnect @code{screen} from the terminal. @xref{Detach}. +@item digraph [@var{preset} [@var{unicode-value}]] +Enter a digraph sequence. @xref{Digraph}. +@item dinfo +Display terminal information. @xref{Info}. +@item displays +List currently active user interfaces. @xref{Displays}. +@item dumptermcap +Write the window's termcap entry to a file. @xref{Dump Termcap}. +@item echo [-n] @var{message} +Display a message on startup. @xref{Startup}. +@item encoding @var{enc} [@var{denc}] +Set the encoding of a window. @xref{Character Processing}. +@item escape @var{xy} +Set the command and @code{meta} characters. @xref{Command Character}. +@item eval @var{command1} [@var{command2} ...] +Parse and execute each argument. @xref{Eval}. +@item exec [[@var{fdpat}] @var{command} [@var{args} ...]] +Run a subprocess (filter). @xref{Exec}. +@item fit +Change window size to current display size. @xref{Window Size}. +@item flow [@var{fstate}] +Set flow control behavior. @xref{Flow}. +@item focus [@code{next}|@code{prev}|@code{up}|@code{down}|@code{left}|@code{right}|@code{top}|@code{bottom}] +Move focus to next region. @xref{Regions}. +@item focusminsize +Force the current region to a certain size. @xref{Focusminsize}. +@item gr [@var{state}] +Change GR charset processing. @xref{Character Processing}. +@item group [@var{grouptitle}] +Change or show the group the current window belongs to. @xref{Window Groups}. +@item hardcopy [-h] [@var{file}] +Write out the contents of the current window. @xref{Hardcopy}. +@item hardcopy_append @var{state} +Append to hardcopy files. @xref{Hardcopy}. +@item hardcopydir @var{directory} +Place, where to dump hardcopy files. @xref{Hardcopy}. +@item hardstatus [@var{state}] +Use the hardware status line. @xref{Hardware Status Line}. +@item height [@var{lines} [@var{cols}]] +Set display height. @xref{Window Size}. +@item help [-c @var{class}] +Display current key bindings. @xref{Help}. +@item history +Find previous command beginning @dots{}. @xref{History}. +@item hstatus @var{status} +Change the window's hardstatus line. @xref{Hardstatus}. +@item idle [@var{timeout} [@var{cmd} @var{args}]] +Define a screen saver command. @xref{Screen Saver}. +@item ignorecase [on|off] +Ignore character case in searches. @xref{Searching}. +@item info +Display window settings. @xref{Info}. +@item ins_reg [@var{key}] +Removed, use @code{paste} instead. @xref{Registers}. +@item kill +Destroy the current window. @xref{Kill}. +@item lastmsg +Redisplay the last message. @xref{Last Message}. +@item layout new [@var{title}] +Create a layout. @xref{Layout}. +@item layout remove [@var{n}|@var{title}] +Delete a layout. @xref{Layout}. +@item layout next +Select the next layout. @xref{Layout}. +@item layout prev +Select the previous layout. @xref{Layout}. +@item layout select [@var{n}|@var{title}] +Jump to a layout. @xref{Layout}. +@item layout show +List the available layouts. @xref{Layout}. +@item layout title [@var{title}] +Show or set the title of a layout. @xref{Layout}. +@item layout number [@var{n}] +Show or set the number of a layout. @xref{Layout}. +@item layout attach [@var{title}|:last] +Show or set which layout to reattach to. @xref{Layout}. +@item layout save [@var{n}|@var{title}] +Remember the organization of a layout. @xref{Layout}. +@item layout autosave [@var{on}|@var{off}] +Show or set the status of layout saving. @xref{Layout}. +@item layout dump [filename] +Save the layout arrangement to a file. @xref{Layout}. +@item license +Display licensing information. @xref{Startup}. +@item lockscreen +Lock the controlling terminal. @xref{Lock}. +@item log [@var{state}] +Log all output in the current window. @xref{Log}. +@item logfile @var{filename} +Place where to collect logfiles. @xref{Log}. +@item login [@var{state}] +Log the window in @file{/etc/utmp}. @xref{Login}. +@item logtstamp [@var{state}] +Configure logfile time-stamps. @xref{Log}. +@item mapdefault +Use only the default mapping table for the next keystroke. @xref{Bindkey Control}. +@item mapnotnext +Don't try to do keymapping on the next keystroke. @xref{Bindkey Control}. +@item maptimeout @var{n} +Set the inter-character timeout used for keymapping. @xref{Bindkey Control}. +@item markkeys @var{string} +Rebind keys in copy mode. @xref{Copy Mode Keys}. +@item maxwin @var{n} +Set the maximum window number. @xref{Maxwin}. +@item meta +Insert the command character. @xref{Command Character}. +@item monitor [@var{state}] +Monitor activity in window. @xref{Monitor}. +@item mousetrack [@var{on}|@var{off}] +Enable selecting split regions with mouse clicks. @xref{Mousetrack}. +@item msgminwait @var{sec} +Set minimum message wait. @xref{Message Wait}. +@item msgwait @var{sec} +Set default message wait. @xref{Message Wait}. +@item multiuser @var{state} +Go into single or multi user mode. @xref{Multiuser Session}. +@item nethack @var{state} +Use @code{nethack}-like error messages. @xref{Nethack}. +@item next +Switch to the next window. @xref{Selecting}. +@item nonblock [@var{state}|@var{numsecs}] +Disable flow control to the current display. @xref{Nonblock}.|@var{numsecs}] +@item number [@var{n}] +Change/display the current window's number. @xref{Number}. +@item obuflimit [@var{limit}] +Select output buffer limit. @xref{Obuflimit}. +@item only +Kill all other regions. @xref{Regions}. +@item other +Switch to the window you were in last. @xref{Selecting}. +@item partial @var{state} +Set window to partial refresh. @xref{Redisplay}. +@item password [@var{crypted_pw}] +Set reattach password. @xref{Detach}. +@item paste [@var{src_regs} [@var{dest_reg}]] +Paste contents of paste buffer or registers somewhere. @xref{Paste}. +@item pastefont [@var{state}] +Include font information in the paste buffer. @xref{Paste}. +@item pow_break +Close and Reopen the window's terminal. @xref{Break}. +@item pow_detach +Detach and hang up. @xref{Power Detach}. +@item pow_detach_msg [@var{message}] +Set message displayed on @code{pow_detach}. @xref{Power Detach}. +@item prev +Switch to the previous window. @xref{Selecting}. +@item printcmd [@var{cmd}] +Set a command for VT100 printer port emulation. @xref{Printcmd}. +@item process [@var{key}] +Treat a register as input to @code{screen}. @xref{Registers}. +@item quit +Kill all windows and exit. @xref{Quit}. +@item readbuf [-e @var{encoding}] [@var{filename}] +Read the paste buffer from the screen-exchange file. @xref{Screen Exchange}. +@item readreg [-e @var{encoding}] [@var{reg} [@var{file}]] +Load a register from paste buffer or file. @xref{Registers}. +@item redisplay +Redisplay the current window. @xref{Redisplay}. +@item register [-e @var{encoding}] @var{key} @var{string} +Store a string to a register. @xref{Registers}. +@item remove +Kill current region. @xref{Regions}. +@item removebuf +Delete the screen-exchange file. @xref{Screen Exchange}. +@item rendition bell | monitor | silence | so @var{attr} [@var{color}] +Change text attributes in caption for flagged windows. @xref{Rendition}. +@item reset +Reset the terminal settings for the window. @xref{Reset}. +@item resize [(+/-)lines] +Grow or shrink a region. @xref{Resize}. +@item screen [@var{opts}] [@var{n}] [@var{cmd} [@var{args}] | //group] +Create a new window. @xref{Screen Command}. +@item scrollback @var{num} +Set size of scrollback buffer. @xref{Scrollback}. +@item select [@var{n}|-|.] +Switch to a specified window. @xref{Selecting}. +@item sessionname [@var{name}] +Name this session. @xref{Session Name}. +@item setenv [@var{var} [@var{string}]] +Set an environment variable for new windows. @xref{Setenv}. +@item setsid @var{state} +Controll process group creation for windows. @xref{Setsid}. +@item shell @var{command} +Set the default program for new windows. @xref{Shell}. +@item shelltitle @var{title} +Set the default name for new windows. @xref{Shell}. +@item silence [@var{state}|@var{seconds}] +Monitor a window for inactivity. @xref{Monitor}. +@item silencewait @var{seconds} +Default timeout to trigger an inactivity notify. @xref{Monitor}. +@item sleep @var{num} +Pause during startup. @xref{Startup}. +@item slowpaste @var{msec} +Slow down pasting in windows. @xref{Paste}. +@item source @var{file} +Run commands from a file. @xref{Source}. +@item sorendition [@var{attr} [@var{color}]] +Deprecated. Use @code{rendition so} instead. @xref{Rendition}. +@item split +Split region into two parts. @xref{Regions}. +@item startup_message @var{state} +Display copyright notice on startup. @xref{Startup}. +@item stuff [@var{string}] +Stuff a string in the input buffer of a window. @xref{Paste}. +@item su [@var{username} [@var{password} [@var{password2}]]] +Identify a user. @xref{Multiuser Session}. +@item suspend +Put session in background. @xref{Suspend}. +@item term @var{term} +Set @code{$TERM} for new windows. @xref{Term}. +@item termcap @var{term} @var{terminal-tweaks} [@var{window-tweaks}] +Tweak termcap entries for best performance. @xref{Termcap Syntax}. +@item terminfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}] +Ditto, for terminfo systems. @xref{Termcap Syntax}. +@item termcapinfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}] +Ditto, for both systems. @xref{Termcap Syntax}. +@item time [@var{string}] +Display time and load average. @xref{Time}. +@item title [@var{windowtitle}] +Set the name of the current window. @xref{Title Command}. +@item umask [@var{users}]+/-@var{bits} ... +Synonym to @code{aclumask}. @xref{Umask}. +@item unbindall +Unset all keybindings. @xref{Bind}. +@item unsetenv @var{var} +Unset environment variable for new windows. @xref{Setenv}. +@item utf8 [@var{state} [@var{dstate}]] +Select character encoding of the current window. @xref{Character Processing}. +@item vbell [@var{state}] +Use visual bell. @xref{Bell}. +@item vbell_msg [@var{message}] +Set vbell message. @xref{Bell}. +@item vbellwait @var{sec} +Set delay for vbell message. @xref{Bell}. +@item version +Display @code{screen} version. @xref{Version}. +@item wall @var{message} +Write a message to all displays. @xref{Multiuser Session}. +@item width [@var{cols} [@var{lines}]] +Set the width of the window. @xref{Window Size}. +@item windowlist [[-b] [-m] [-g]] | string [@var{string}] | title [@var{title}] +Present a list of all windows for selection. @xref{Windowlist}. +@item windows +List active windows. @xref{Windows}. +@item wrap [ on | off ] +Control line-wrap behavior. @xref{Wrap}. +@item writebuf [-e @var{encoding}] [@var{filename}] +Write paste buffer to screen-exchange file. @xref{Screen Exchange}. +@item writelock @var{on}|@var{off}|@var{auto} +Grant exclusive write permission. @xref{Multiuser Session}. +@item xoff +Send an XOFF character. @xref{XON/XOFF}. +@item xon +Send an XON character. @xref{XON/XOFF}. +@item zmodem [off|auto|catch|pass] +Define how screen treats zmodem requests. @xref{Zmodem}. +@item zombie [@var{keys} [onerror] ] +Keep dead windows. @xref{Zombie}. +@end table + +@node New Window, Selecting, Commands, Top +@chapter New Window + +This section describes the commands for creating a new window for +running programs. When a new window is created, the first available +number is assigned to it. +The number of windows is limited at compile-time by the MAXWIN +configuration parameter (which defaults to 40). + +@menu +* Chdir:: Change the working directory for new windows. +* Screen Command:: Create a new window. +* Setenv:: Set environment variables for new windows. +* Shell:: Parameters for shell windows. +* Term:: Set the terminal type for new windows. +* Window Types:: Creating different types of windows. +* Window Groups:: Grouping windows together +@end menu + +@node Chdir, Screen Command, , New Window +@section Chdir +@deffn Command chdir [directory] +(none)@* +Change the current directory of @code{screen} to the specified directory +or, if called without an argument, to your home directory (the value of +the environment variable @code{$HOME}). All windows that are created by means +of the @code{screen} command from within @file{.screenrc} or by means of +@kbd{C-a : screen @dots{}} or @kbd{C-a c} use this as their default +directory. Without a @code{chdir} command, this would be the directory +from which @code{screen} was invoked. Hardcopy and log files are always +written to the @emph{window's} default directory, @emph{not} the current +directory of the process running in the window. You can use this +command multiple times in your @file{.screenrc} to start various windows +in different default directories, but the last @code{chdir} value will +affect all the windows you create interactively. +@end deffn + +@node Screen Command, Setenv, Chdir, New Window +@section Screen Command +@kindex c +@kindex C-c +@deffn Command screen [opts] [n] [cmd [args] @var{| //group}] +(@kbd{C-a c}, @kbd{C-a C-c})@* +Establish a new window. The flow-control options (@samp{-f}, @samp{-fn} +and @samp{-fa}), title option (@samp{-t}), login options +(@samp{-l} and @samp{-ln}) , terminal type option (@samp{-T @var{term}}), +the all-capability-flag (@samp{-a}) and scrollback option +(@samp{-h @var{num}}) may be specified with each command. +The option (@samp{-M}) turns monitoring on for this window. +The option (@samp{-L}) turns output logging on for this window. +If an optional number @var{n} in the range 0@dots{}MAXWIN-1 is given, +the window number @var{n} is assigned to the newly created window (or, +if this number is already in-use, the next available number). If a +command is specified after @code{screen}, this command (with the given +arguments) is started in the window; otherwise, a shell is created. +If @samp{//group} is supplied, a container-type window is created in +which other windows may be created inside it. @xref{Window Groups}. + +Screen has built in some functionality of @samp{cu} and @samp{telnet}. +@xref{Window Types}. +@end deffn + +Thus, if your @file{.screenrc} contains the lines + +@example +# example for .screenrc: +screen 1 +screen -fn -t foobar 2 -L telnet foobar +@end example + +@noindent +@code{screen} creates a shell window (in window #1) and a window with a +TELNET connection to the machine foobar (with no flow-control using the +title @samp{foobar} in window #2) and will write a logfile @samp{screenlog.2} +of the telnet session. If you do not include any +@code{screen} commands in your @file{.screenrc} file, then @code{screen} +defaults to creating a single shell window, number zero. When the +initialization is completed, @code{screen} switches to the last window +specified in your .screenrc file or, if none, it opens default window +#0. + +@node Setenv, Shell, Screen Command, New Window +@section Setenv +@deffn Command setenv var string +(none)@* +Set the environment variable @var{var} to value @var{string}. +If only @var{var} is specified, the user will be prompted to enter a value. +If no parameters are specified, the user will be prompted for both variable +and value. The environment is inherited by all subsequently forked shells. +@end deffn + +@deffn Command unsetenv var +(none)@* +Unset an environment variable. +@end deffn + +@node Shell, Term, Setenv, New Window +@section Shell +@deffn Command shell command +@deffnx Command defshell command +(none)@* +Set the command to be used to create a new shell. This overrides the +value of the environment variable @code{$SHELL}. This is useful if +you'd like to run a tty-enhancer which is expecting to execute the +program specified in @code{$SHELL}. +If the command begins with a @samp{-} character, the shell will be started as a +login-shell. Typical shells do only minimal initialization when not started as a login-shell. +E.g. Bash will not read your @file{~/.bashrc} unless it is a login-shell. + +@code{defshell} is currently a synonym to the @code{shell} .screenrc command. +@end deffn + +@deffn Command shelltitle title +(none)@* +Set the title for all shells created during startup or by the C-a C-c +command. @xref{Naming Windows}, for details about what titles are. +@end deffn + +@node Term, Window Types , Shell, New Window +@section Term +@deffn Command term term +(none)@* +In each window @code{screen} opens, it sets the @code{$TERM} +variable to @code{screen} by default, unless no description for +@code{screen} is installed in the local termcap or terminfo data base. +In that case it pretends that the terminal emulator is @samp{vt100}. +This won't do much harm, as @code{screen} is VT100/ANSI compatible. The +use of the @code{term} command is discouraged for non-default purpose. +That is, one may want to specify special @code{$TERM} settings (e.g. vt100) for +the next @code{screen rlogin othermachine} command. Use the command +@code{screen -T vt100 rlogin othermachine} rather than setting +and resetting the default. +@end deffn + +@node Window Types, Window Groups, Term, New Window +@section Window Types +@cindex window types +Screen provides three different window types. New windows are created +with @code{screen}'s @samp{screen} command (@pxref{Screen Command}). +The first parameter to the @samp{screen} command defines which +type of window is created. The different window types are all +special cases of the normal type. They have been added in order +to allow @code{screen} to be used efficiently as a console +with 100 or more windows. +@itemize @bullet +@item +The normal window contains a shell (default, if no parameter is given) +or any other system command that could be executed from a shell. +(e.g. @samp{slogin}, etc...). + +@item +If a tty (character special device) name (e.g. @samp{/dev/ttya}) +is specified as the first parameter, then the window is directly +connected to this device. +This window type is similar to @samp{screen cu -l /dev/ttya}. +Read and write access is required on the device node, +an exclusive open is attempted on the node to mark the connection line +as busy. +An optional parameter is allowed consisting of a comma separated +list of flags in the notation used by @samp{stty(1)}: +@table @code +@item <baud_rate> +Usually 300, 1200, 9600 or 19200. This affects transmission as well as +receive speed. +@item cs8 or cs7 +Specify the transmission of eight (or seven) bits per byte. +@item ixon or -ixon +Enables (or disables) software flow-control (CTRL-S/CTRL-Q) for sending +data. +@item ixoff or -ixoff +Enables (or disables) software flow-control for receiving data. +@item istrip or -istrip +Clear (or keep) the eight bit in each received byte. +@end table + +You may want to specify as many of these options as applicable. +Unspecified options cause the terminal driver to make up the parameter +values of the connection. These values are system-dependent and may be +in defaults or values saved from a previous connection. + +For tty windows, the @code{info} command shows some of the modem +control lines in the status line. +These may include @samp{RTS}, @samp{CTS}, @samp{DTR}, @samp{CD} and +more. This depends rather on on the available @code{ioctl()}'s and system +header files than on the physical capabilities of the serial board. +The name of a logical low (inactive) signal is preceded by an +exclamation mark (@samp{!}), otherwise the signal is logical high (active). +Unsupported but shown signals are usually shown low. +When the @code{CLOCAL} status bit is true, the whole set of modem signals is +placed inside curly braces (@samp{@{} and @samp{@}}). +When the @code{CRTSCTS} or @code{TIOCSOFTCAR} bit is true, the signals +@samp{CTS} or @samp{CD} are shown in parenthesis, respectively. + +For tty windows, the command @code{break} causes the Data transmission +line (TxD) to go low for a specified period of time. This is expected +to be interpreted as break signal on the other side. +No data is sent and no modem control line is changed when a +@code{break} is issued. + +@item +If the first parameter is @code{//telnet}, the second parameter is +expected to be a host name, and an optional third parameter may specify +a TCP port number (default decimal 23). Screen will connect to a +server listening on the remote host and use the telnet protocol to +communicate with that server. + +For telnet windows, the command @code{info} shows details about +the connection in square brackets (@samp{[} and @samp{]}) at the end of +the status line. +@table @code +@item b +BINARY. The connection is in binary mode. +@item e +ECHO. Local echo is disabled. +@item c +SGA. The connection is in `character mode' (default: `line mode'). +@item t +TTYPE. The terminal type has been requested by the remote host. Screen +sends the name @code{screen} unless instructed otherwise (see also the +command @samp{term}). +@item w +NAWS. The remote site is notified about window size changes. +@item f +LFLOW. The remote host will send flow control information. +(Ignored at the moment.) +@end table +Additional flags for debugging are @samp{x}, @samp{t} and @samp{n} +(XDISPLOC, TSPEED and NEWENV). + +For telnet windows, the command @code{break} sends the telnet code +@code{IAC BREAK} (decimal 243) to the remote host. + +@end itemize + +@node Window Groups, , Window Types, New Window +@section Window Groups +@cindex window groups +Screen provides a method for grouping windows together. Windows can be +organized in a hierarchical fashion, resembling a tree structure. New +screens are created using the @code{screen} command while new groups +are created using @code{screen //group}. @xref{Screen Command}. + +Once a new group is created, it will act as a container for windows +and even other groups. When a group is selected, you will see the +output of the @code{windowlist} command, allowing you to select a +window inside. If there are no windows inside a group, use the +@code{screen} command to create one. Once inside a group, using the +commands @code{next} and @code{prev} will switch between windows only +in that group. Using the @code{windowlist} command will give you the +opportunity to leave the group you are in. @xref{Windowlist}. + +@deffn Command group [grouptitle] +(none)@* +Change or show the group the current window belongs to. Windows can +be moved around between different groups by specifying the name of +the destination group. Without specifying a group, the title of the +current group is displayed. +@end deffn + +Using groups in combination with layouts will help create a +multi-desktop experience. One group can be assigned for each +layout made. Windows can be made, split, and organized within each +group as desired. Afterwhich, switching between groups can be as easy +as switching layouts. + +@node Selecting, Session Management, New Window, Top +@chapter Selecting a Window + +This section describes the commands for switching between windows in an +@code{screen} session. The windows are numbered from 0 to 9, and are created +in that order by default (@pxref{New Window}). + +@menu +* Next and Previous:: Forward or back one window. +* Other Window:: Switch back and forth between two windows. +* Select:: Switch to a window (and to one after @code{kill}). +* Windowlist:: Present a list of all windows for selection. +@end menu + +@node Next and Previous, Other Window, , Selecting +@section Moving Back and Forth +@kindex SPC +@kindex n +@kindex C-n +@deffn Command next +(@kbd{C-a @key{SPC}}, @kbd{C-a n}, @kbd{C-a C-n})@* +Switch to the next window. This command can be used repeatedly to +cycle through the list of windows. (On some terminals, C-@key{SPC} +generates a NUL character, so you must release the control key before +pressing space.) +@end deffn + +@kindex p +@kindex C-p +@kindex C-h +@kindex Backspace +@deffn Command prev +(@kbd{C-a p}, @kbd{C-a C-p}, @kbd{C-a C-h}, @kbd{C-a @key{Backspace}})@* +Switch to the previous window (the opposite of @kbd{C-a n}). +@end deffn + +@node Other Window, Select, Next and Previous, Selecting +@section Other Window +@kindex C-a +@deffn Command other +(@kbd{C-a C-a})@* +Switch to the last window displayed. Note that this command +defaults to the command character typed twice, unless overridden. +For instance, if you use the option @samp{-e]x}, +this command becomes @kbd{]]} (@pxref{Command Character}). +@end deffn + +@node Select, Windowlist, Other Window, Selecting +@section Select +@kindex 0@dots{}9 +@kindex ' +@deffn Command select [n @var{|-|.}] +(@kbd{C-a @var{n}}, @kbd{C-a '})@* +Switch to the window with the number @var{n}. +If no window number is specified, you get prompted for an +identifier. This can be a window name (title) or a number. +When a new window is established, the lowest available number +is assigned to this window. +Thus, the first window can be activated by @code{select 0}; there +can be no more than 10 windows present simultaneously (unless screen is +compiled with a higher MAXWIN setting). +There are two special arguments, @code{select -} switches to the +internal blank window and @code{select .} switches to the +current window. The latter is useful if used with screen's +@code{-X} option. + +@end deffn + +@node Windowlist, , Select, Selecting +@section Windowlist +@kindex " +@deffn Command windowlist [-b] [-m] [-g] +@deffnx Command windowlist string [@var{string}] +@deffnx Command windowlist title [@var{title}] +(@kbd{C-a "})@* +Display all windows in a table for visual window selection. +If screen was in a window group, screen will +back out of the group and then display the windows in that +group. If the @code{-b} option is given, screen will +switch to the blank window before presenting the list, so +that the current window is also selectable. +The @code{-m} option changes the order of the windows, instead of +sorting by window numbers screen uses its internal most-recently-used +list. The @code{-g} option will show the windows inside any groups +in that level and downwards. + +The following keys are used to navigate in @code{windowlist}: + +@noindent +@kbd{k}, @kbd{C-p}, or @kbd{up} Move up one line. + +@noindent +@kbd{j}, @kbd{C-n}, or @kbd{down} Move down one line. + +@noindent +@kbd{C-g} or @kbd{escape} Exit windowlist. + +@noindent +@kbd{C-a} or @kbd{home} Move to the first line. + +@noindent +@kbd{C-e} or @kbd{end} Move to the last line. + +@noindent +@kbd{C-u} or @kbd{C-d} Move one half page up or down. + +@noindent +@kbd{C-b} or @kbd{C-f} Move one full page up or down. + +@indent +@kbd{0..9} Using the number keys, move to the selected line. + +@noindent +@kbd{mouseclick} Move to the selected line. Available when +@code{mousetrack} is set to @code{on}. + +@noindent +@kbd{/} Search. + +@noindent +@kbd{n} Repeat search in the forward direction. + +@noindent +@kbd{N} Repeat search in the backward direction. + +@noindent +@kbd{m} Toggle MRU. + +@noindent +@kbd{g} Toggle group nesting. + +@noindent +@kbd{a} All window view. + +@noindent +@kbd{C-h} or @kbd{backspace} Back out the group. + +@noindent +@kbd{,} Switch numbers with the previous window. + +@noindent +@kbd{.} Switch numbers with the next window. + +@noindent +@kbd{K} Kill that window. + +@noindent +@kbd{space} or @kbd{enter} Select that window. + +The table format can be changed with the string and title +option, the title is displayed as table heading, while the +lines are made by using the string setting. The default +setting is @samp{Num Name%=Flags} for the title and +@samp{%3n %t%=%f} for the lines. See the string escapes chapter +(@pxref{String Escapes}) for more codes (e.g. color settings). + +@code{Windowlist} needs a region size of at least 10 characters +wide and 6 characters high in order to display. +@end deffn + +@node Session Management, Regions, Selecting, Top +@chapter Session Management Commands + +Perhaps the most useful feature of @code{screen} is the way it allows +the user to move a session between terminals, by detaching and +reattaching. This also makes life easier for modem users who have to +deal with unexpected loss of carrier. + +@menu +* Detach:: Disconnect @code{screen} from your terminal. +* Power Detach:: Detach and log out. +* Lock:: Lock your terminal temporarily. +* Multiuser Session:: Changing number of allowed users. +* Session Name:: Rename your session for later reattachment. +* Suspend:: Suspend your session. +* Quit:: Terminate your session. +@end menu + +@node Detach, Power Detach, , Session Management +@section Detach + +@deffn Command autodetach state +(none)@* +Sets whether @code{screen} will automatically detach upon hangup, which +saves all your running programs until they are resumed with a +@code{screen -r} command. When turned off, a hangup signal will +terminate @code{screen} and all the processes it contains. Autodetach is +on by default. +@end deffn + +@kindex d +@kindex C-d +@deffn Command detach +(@kbd{C-a d}, @kbd{C-a C-d})@* +Detach the @code{screen} session (disconnect it from the terminal and +put it into the background). A detached @code{screen} can be resumed by +invoking @code{screen} with the @code{-r} option (@pxref{Invoking +Screen}). +The @code{-h} option tells screen to immediately close the connection +to the terminal (@samp{hangup}). +@end deffn + +@deffn Command password [crypted_pw] +(none)@* +Present a crypted password in your @file{.screenrc} file and screen will +ask for it, whenever someone attempts to resume a detached session. This +is useful, if you have privileged programs running under @code{screen} +and you want to protect your session from reattach attempts by users +that managed to assume your uid. (I.e. any superuser.) If no crypted +password is specified, screen prompts twice a password and places its +encryption in the paste buffer. Default is `none', which disables +password checking. +@end deffn + +@node Power Detach, Lock, Detach, Session Management +@section Power Detach + +@kindex D +@deffn Command pow_detach +(@kbd{C-a D D})@* +Mainly the same as @code{detach}, but also sends a HANGUP signal +to the parent process of @code{screen}.@* +@emph{Caution}: This will result in a +logout if @code{screen} was started from your login-shell. +@end deffn + +@deffn Command pow_detach_msg [message] +(none)@* +The @var{message} specified here is output whenever a power detach is +performed. It may be used as a replacement for a logout message or to reset +baud rate, etc. +Without a parameter, the current message is shown. +@end deffn + +@node Lock, Multiuser Session, Power Detach, Session Management +@section Lock +@kindex x +@kindex C-x +@deffn Command lockscreen +(@kbd{C-a x}, @kbd{C-a C-x})@* +Call a screenlock program (@file{/local/bin/lck} or @file{/usr/bin/lock} +or a builtin, if no other is available). Screen does not accept any +command keys until this program terminates. Meanwhile processes in the +windows may continue, as the windows are in the detached state. +The screenlock program may be changed through the environment variable +@code{$LOCKPRG} (which must be set in the shell from which @code{screen} +is started) and is executed with the user's uid and gid. + +Warning: When you leave other shells unlocked and have no password set +on @code{screen}, the lock is void: One could easily re-attach from an +unlocked shell. This feature should rather be called +@code{lockterminal}. +@end deffn + +@node Multiuser Session, Session Name, Lock, Session Management +@section Multiuser Session +@cindex multiuser session + +These commands allow other users to gain access to one single @code{screen} +session. When attaching to a multiuser @code{screen} the sessionname is +specified as @code{username/sessionname} to the @code{-S} command line option. +@code{Screen} must be compiled with multiuser support to enable features +described here. + +@menu +* Multiuser:: Enable / Disable multiuser mode. +* Acladd:: Enable a specific user. +* Aclchg:: Change a users permissions. +* Acldel:: Disable a specific user. +* Aclgrp:: Grant a user permissions to other users. +* Displays:: List all active users at their displays. +* Umask:: Predefine access to new windows. +* Wall:: Write a message to all users. +* Writelock:: Grant exclusive window access. +* Su:: Substitute user. +@end menu + +@node Multiuser, Acladd, , Multiuser Session +@subsection Multiuser +@deffn Command multiuser @var{state} +(none)@* +Switch between single-user and multi-user mode. Standard screen operation is +single-user. In multi-user mode the commands @code{acladd}, @code{aclchg} and +@code{acldel} can be used to enable (and disable) other users accessing this +@code{screen}. +@end deffn + +@node Acladd, Aclchg, Multiuser, Multiuser Session +@subsection Acladd +@deffn Command acladd @var{usernames} +@deffnx Command addacl @var{usernames} +(none)@* +Enable users to fully access this screen session. @var{Usernames} can be one +user or a comma separated list of users. This command enables to attach to +the @code{screen} session and performs the equivalent of +@code{aclchg @var{usernames} +rwx "#?"}. To add a user with restricted access, +use the @code{aclchg} command below. +@code{Addacl} is a synonym to @code{acladd}. +Multi-user mode only. +@end deffn + +@node Aclchg, Acldel, Acladd, Multiuser Session +@subsection Aclchg +@deffn Command aclchg @var{usernames permbits list} +@deffnx Command chacl @var{usernames permbits list} +(none)@* +Change permissions for a comma separated list of users. +Permission bits are represented as @samp{r}, @samp{w} and @samp{x}. +Prefixing @samp{+} grants the permission, @samp{-} removes it. The third +parameter is a comma separated list of commands or windows (specified either +by number or title). The special list @samp{#} refers to all windows, @samp{?} +to all commands. If @var{usernames} consists of a single @samp{*}, all +known users are affected. +A command can be executed when the user has the @samp{x} bit for it. The user +can type input to a window when he has its @samp{w} bit set and no other +user obtains a writelock for this window. Other bits are currently ignored. +To withdraw the writelock from another user in e.g. window 2: +@samp{aclchg @var{username} -w+w 2}. To allow read-only access +to the session: @samp{aclchg @var{username} -w "#"}. As soon as a user's name +is known to screen, he can attach to the session and (per default) has full +permissions for all command and windows. Execution permission for the acl +commands, @code{at} and others should also be removed or the user may be able +to regain write permission. +@code{Chacl} is a synonym to @code{aclchg}. +Multi-user mode only. +@end deffn + +@node Acldel, Aclgrp, Aclchg, Multiuser Session +@subsection Acldel +@deffn Command acldel @var{username} +(none)@* +Remove a user from screen's access control list. If currently attached, all the +user's displays are detached from the session. He cannot attach again. +Multi-user mode only. +@end deffn + +@node Aclgrp, Displays, Acldel, Multiuser Session +@subsection Aclgrp +@deffn Command aclgrp @var{username} [@var{groupname}] +(none)@* +Creates groups of users that share common access rights. The +name of the group is the username of the group leader. Each +member of the group inherits the permissions that are +granted to the group leader. That means, if a user fails an +access check, another check is made for the group leader. +A user is removed from all groups the special value @samp{none} +is used for @var{groupname}. If the second parameter is omitted +all groups the user is in are listed. +@end deffn + +@node Displays, Umask, Aclgrp, Multiuser Session +@subsection Displays +@kindex * +@deffn Command displays +(@kbd{C-a *})@* +Shows a tabular listing of all currently connected user +front-ends (displays). This is most useful for multiuser +sessions. + +The following keys can be used in @code{displays} list: + +@noindent +@kbd{k}, @kbd{C-p}, or @kbd{up} Move up one line. + +@noindent +@kbd{j}, @kbd{C-n}, or @kbd{down} Move down one line. + +@noindent +@kbd{C-a} or @kbd{home} Move to the first line. + +@noindent +@kbd{C-e} or @kbd{end} Move to the last line. + +@noindent +@kbd{C-u} or @kbd{C-d} Move one half page up or down. + +@noindent +@kbd{C-b} or @kbd{C-f} Move one full page up or down. + +@noindent +@kbd{mouseclick} Move to the selected line. Available when +@code{mousetrack} is set to @code{on}. + +@noindent +@kbd{space} Refresh the list. + +@noindent +@kbd{d} Detach the selected display. + +@noindent +@kbd{D} Power detach the selected display. + +@noindent +@kbd{C-g}, @kbd{enter}, or @kbd{escape} Exit the list. + + +The following is an example of what @code{displays} could +look like: + +@example +xterm 80x42 jnweiger@@/dev/ttyp4 0(m11) &rWx +facit 80x24 mlschroe@@/dev/ttyhf nb 11(tcsh) rwx +xterm 80x42 jnhollma@@/dev/ttyp5 0(m11) &R.x + (A) (B) (C) (D) (E) (F)(G) (H)(I) +@end example + +The legend is as follows: +@*(A) The terminal type known by @code{screen} for this display. +@*(B) Displays geometry as width x height. +@*(C) Username who is logged in at the display. +@*(D) Device name of the display or the attached device +@*(E) Display is in blocking or nonblocking mode. The available + modes are "nb", "NB", "Z<", "Z>", and "BL". +@*(F) Number of the window +@*(G) Name/title of window +@*(H) Whether the window is shared +@*(I) Window permissions. Made up of three characters: +@display +(1st character) + @samp{-} : no read + @samp{r} : read + @samp{R} : read only due to foreign wlock +(2nd character) + @samp{-} : no write + @samp{.} : write suppressed by foreign wlock + @samp{w} : write + @samp{W} : own wlock +(3rd character) + @samp{-} : no execute + @samp{x} : execute +@end display + +@code{Displays} needs a region size of at least 10 characters +wide and 5 characters high in order to display. +@end deffn + +@node Umask, Wall, Displays, Multiuser Session +@subsection aclumask +@deffn Command aclumask [@var{users}]+/-@var{bits} ... +@deffnx Command umask [@var{users}]+/-@var{bits} ... +(none)@* +This specifies the access other users have to windows that +will be created by the caller of the command. @var{Users} may be no, +one or a comma separated list of known usernames. If no users are +specified, a list of all currently known users is assumed. +@var{Bits} is any combination of access control bits allowed +defined with the @code{aclchg} command. The special username @samp{?} +predefines the access that not yet known users will be +granted to any window initially. The special username @samp{??} +predefines the access that not yet known users are granted +to any command. Rights of the special username nobody cannot +be changed (see the @code{su} command). +@code{Umask} is a synonym to @code{aclumask}. +@end deffn + + +@node Wall, Writelock, Umask, Multiuser Session +@subsection Wall +@deffn Command wall @var{message} +(none)@* +Write a message to all displays. The message will appear in the terminal's +status line. +@end deffn + +@node Writelock, Su , Wall, Multiuser Session +@subsection Writelock +@deffn Command writelock @var{on|off|auto} +(none)@* +In addition to access control lists, not all users may be able to write to +the same window at once. Per default, writelock is in @samp{auto} mode and +grants exclusive input permission to the user who is the first to switch +to the particular window. When he leaves the window, other users may obtain +the writelock (automatically). The writelock of the current window is disabled +by the command @code{writelock off}. If the user issues the command +@code{writelock on} he keeps the exclusive write permission while switching +to other windows. +@end deffn + +@deffn Command defwritelock @var{on|off|auto} +(none)@* +Sets the default writelock behavior for new windows. Initially all windows +will be created with no writelocks. +@end deffn + +@node Su, , Writelock, Multiuser Session +@subsection Su +@deffn Command su [@var{username} [@var{password} [@var{password2}]]] +(none)@* +Substitute the user of a display. The command prompts for +all parameters that are omitted. If passwords are specified +as parameters, they have to be specified un-crypted. The +first password is matched against the systems passwd database, +the second password is matched against the @code{screen} +password as set with the commands @code{acladd} or @code{password}. +@code{Su} may be useful for the @code{screen} administrator to test +multiuser setups. +When the identification fails, the user has +access to the commands available for user @samp{nobody}. These are +@code{detach}, @code{license}, @code{version}, @code{help} and +@code{displays}. +@end deffn + +@node Session Name, Suspend, Multiuser Session, Session Management +@section Session Name +@deffn Command sessionname [@var{name}] +(none)@* +Rename the current session. Note that for @code{screen -list} the name +shows up with the process-id prepended. If the argument @var{name} is +omitted, the name of this session is displayed.@* +@emph{Caution}: The @code{$STY} +environment variable will still reflect the old name in pre-existing +shells. This may result in +confusion. Use of this command is generally +discouraged. Use the @code{-S} command-line option if you want to +name a new session.The default is constructed from the tty and host names. +@end deffn + +@node Suspend, Quit, Session Name, Session Management +@section Suspend +@kindex z +@kindex C-z +@deffn Command suspend +(@kbd{C-a z}, @kbd{C-a C-z})@* +Suspend @code{screen}. The windows are in the detached state while +@code{screen} is suspended. This feature relies on the parent shell +being able to do job control. +@end deffn + +@node Quit, , Suspend, Session Management +@section Quit +@kindex \ +@deffn Command quit +(@kbd{C-a \})@* +Kill all windows and terminate @code{screen}. +(@pxref{Key Binding}). +@end deffn + +@node Regions, Window Settings, Session Management, Top +@chapter Regions +@cindex regions +Screen has the ability to display more than one window on the +user's display. This is done by splitting the screen in regions, +which can contain different windows. + +@menu +* Split:: Split a region into two +* Focus:: Change to the next region +* Only:: Delete all other regions +* Remove:: Delete the current region +* Resize:: Grow or shrink a region +* Caption:: Control the window's caption +* Fit:: Resize a window to fit the region +* Focusminsize:: Force a minimum size on a current region +* Layout:: Manage groups of regions +@end menu + +@node Split, Focus, , Regions +@section Split +@kindex S +@kindex | +@deffn Command split [-v] +(@kbd{C-a S}, @kbd{C-a |})@* +Split the current region into two new ones. All regions on the +display are resized to make room for the new region. The blank +window is displayed in the new region. The default is to create +a horizontal split, putting the new regions on the top and +bottom of each other. Using @samp{-v} will create a vertical split, +causing the new regions to appear side by side of each other. +Use the @code{remove} or the @code{only} command to delete regions. +Use @code{focus} to toggle between regions. + +When a region is split opposite of how it was previously split +(that is, vertical then horizontal or horizontal then vertical), +a new layer is created. The layer is used to group together the +regions that are split the same. Normally, as a user, you should +not see nor have to worry about layers, but they will affect how +some commands (@code{focus} and @code{resize}) behave. + +With this current implementation of @code{screen}, scrolling data +will appear much slower in a vertically split region than one +that is not. This should be taken into consideration if you need +to use system commands such as @code{cat} or @code{tail -f}. +@end deffn + +@node Focus, Only, Split, Regions +@section Focus +@kindex TAB +@deffn Command focus [ @code{next|prev|up|down|left|right|top|bottom} ] +(@kbd{C-a @key{Tab}})@* +Move the input focus to the next region. This is done in a cyclic +way so that the top left region is selected after the bottom right +one. If no option is given it defaults to @code{next}. The next +region to be selected is determined by how the regions are layered. +Normally, the next region in the same layer would be selected. +However, if that next region contains one or more layers, the first +region in the highest layer is selected first. If you are at the +last region of the current layer, @code{next} will move the focus +to the next region in the lower layer (if there is a lower layer). +@code{Prev} cycles in the opposite order. @xref{Split} for more +information about layers. + +The rest of the options (@code{up}, @code{down}, @code{left}, +@code{right}, @code{top}, and @code{bottom}) are more indifferent +to layers. The option @code{up} will move the focus upward to the +region that is touching the upper left corner of the current region. +@code{Down} will move downward to the region that is touching the +lower left corner of the current region. The option @code{left} +will move the focus leftward to the region that is touching the +upper left corner of the current region, while @code{right} will +move rightward to the region that is touching the upper right corner +of the current region. Moving left from a left most region or moving +right from a right most region will result in no action. + +The option @code{top} will move the focus to the very first region +in the upper list corner of the screen, and @code{bottom} will move +to the region in the bottom right corner of the screen. Moving up from +a top most region or moving down from a bottom most region will result +in no action. + +Useful bindings are (h, j, k, and l as in vi): +@example +bind h focus left +bind j focus down +bind k focus up +bind l focus right +bind t focus top +bind b focus bottom +@end example + +Note that @samp{k} is traditionally bound to the @code{kill} command. +@end deffn + +@node Only, Remove, Focus, Regions +@section Only +@kindex Q +@deffn Command only +(@kbd{C-a Q})@* +Kill all regions but the current one. +@end deffn + +@node Remove, Resize, Only, Regions +@section Remove +@kindex X +@deffn Command remove +(@kbd{C-a X})@* +Kill the current region. This is a no-op if there is only one region. +@end deffn + +@node Resize, Caption, Remove, Regions +@section Resize +@deffn Command resize [@code{-h|-v|-b|-l|-p}] [ [+|-]@var{n}[@code{%}] | @code{=} | @code{max} | @code{min} | @code{_} | @code{0} ] +(none)@* +Resize the current region. The space will be removed from or added to +the surrounding regions depending on the order of the splits. +The available options for resizing are @samp{-h}(horizontal), +@samp{-v}(vertical), @samp{-b}(both), @samp{-l}(local to layer), +and @samp{-p}(perpendicular). Horizontal resizes will add or remove width +to a region, vertical will add or remove height, and both will add or +remove size from both dimensions. Local and perpendicular are similar to +horizontal and vertical, but they take in account of how a region was split. +If a region's last split was horizontal, a local resize will work like a +vertical resize. If a region's last split was vertical, a local resize will +work like a horizontal resize. Perpendicular resizes work in opposite of +local resizes. If no option is specified, local is the default. + +The amount of lines to add or remove can be expressed a couple of different +ways. By specifying a number @var{n} by itself will resize the region by +that absolute amount. You can specify a relative amount by prefixing a +plus @samp{+} or minus @samp{-} to the amount, such as adding @code{+n} lines +or removing @code{-n} lines. Resizing can also be expressed as an absolute +or relative percentage by postfixing a percent sign @samp{%}. Using zero +@samp{0} is a synonym for @code{min} and using an underscore @samp{_} is a +synonym for @code{max}. + +Some examples are: +@example +resize +N increase current region by N +resize -N decrease current region by N +resize N set current region to N +resize 20% set current region to 20% of original size +resize +20% increase current region by 20% +resize -b = make all windows equally +resize max maximize current region +resize min minimize current region +@end example + +Without any arguments, @code{screen} will prompt for how you would +like to resize the current region. + +See @code{focusminsize} if you want to restrict the minimun size a region can have. + +@end deffn + +@node Caption, Fit, Resize, Regions +@section Caption +@deffn Command caption @code{always}|@code{splitonly} [string] +@deffnx Command caption @code{string} [string] +(none)@* +This command controls the display of the window captions. Normally +a caption is only used if more than one window is shown on the +display (split screen mode). But if the type is set to +@code{always}, @code{screen} shows a caption +even if only one window is displayed. The default +is @samp{splitonly}. + +The second form changes the text used for the caption. You can use +all string escapes (@pxref{String Escapes}). @code{Screen} uses +a default of @samp{%3n %t}. + +You can mix both forms by providing the string as an additional +argument. +@end deffn + +@node Fit, Focusminsize, Caption, Regions +@section Fit +@kindex F +@deffn Command fit +(@kbd{C-a F})@* +Change the window size to the size of the current region. This +command is needed because screen doesn't adapt the window size +automatically if the window is displayed more than once. +@end deffn + +@node Focusminsize, Layout, Fit, Regions +@section Focusminsize +@deffn Command focusminsize [ (width|@code{max}|@code{_}) (height|@code{max}|@code{_}) ] +(none)@* +This forces any currently selected region to be automatically +resized at least a certain @var{width} and @var{height}. All +other surrounding regions will be resized in order to accommodate. +This constraint follows every time the @code{focus} command is +used. The @code{resize} command can be used to increase either +dimension of a region, but never below what is set with +@code{focusminsize}. The underscore @samp{_} is a synonym for +@code{max}. Setting a @var{width} and @var{height} of @code{0 0} +(zero zero) will undo any constraints and allow for manual resizing. +Without any parameters, the minimum width and height is shown. +@end deffn + +@node Layout, , Focusminsize, Regions +@section Layout +@cindex layout +Using regions, and perhaps a large enough terminal, you can give +@code{screen} more of a desktop feel. By being able to split +regions horizontally or vertically, you can take advantage of the +lesser used spaces of your terminal. The catch to these splits has +been that they're not kept between screen detachments and reattachments. + +Layouts will help organize your regions. You can create one +layout of four horizontal regions and then create a separate layout +of regions in a two by two array. The regions could contain the same windows, +but they don't have to. You can easily switch between layouts and keep +them between detachments and reattachments. + +Note that there are several subcommands to @code{layout}. + +@deffn Command layout @code{new} [title] +(none)@* +Create a new layout. The screen will change to one whole region +and be switched to the blank window. From here, you build the +regions and the windows they show as you desire. The new layout +will be numbered with the smallest available integer, starting +with zero. You can optionally give a title to your new layout. +Otherwise, it will have a default title of @code{layout}. You +can always change the title later by using the command +@code{layout title}. +@end deffn + +@deffn Command layout @code{remove} [n|title] +(none)@* +Remove, or in other words, delete the specified layout. Either +the number or the title can be specified. Without either +specification, @code{screen} will remove the current layout. + +Removing a layout does not affect your set windows or regions. +@end deffn + +@deffn Command layout @code{next} +(none)@* +Switch to the next layout available +@end deffn + +@deffn Command layout @code{prev} +(none)@* +Switch to the previous layout available +@end deffn + +@deffn Command layout @code{select} [n|title] +(none)@* +Select the desired layout. Either the number or the title can +be specified. Without either specification, @code{screen} will +prompt and ask which screen is desired. To see which layouts are +available, use the @code{layout show} command. +@end deffn + +@deffn Command layout @code{show} +(none)@* +List on the message line the number(s) and title(s) of the available +layout(s). The current layout is flagged. +@end deffn + +@deffn Command layout @code{title} [title] +(none)@* +Change or display the title of the current layout. A string given +will be used to name the layout. Without any options, the current +title and number is displayed on the message line. +@end deffn + +@deffn Command layout @code{number} [n] +(none)@* +Change or display the number of the current layout. An integer given +will be used to number the layout. Without any options, the current +number and title is displayed on the message line. +@end deffn + +@deffn Command layout @code{attach} [title|@code{:last}] +(none)@* +Change or display which layout to reattach back to. The default is +@code{:last}, which tells @code{screen} to reattach back to the last +used layout just before detachment. By supplying a title, You can +instruct @code{screen} to reattach to a particular layout regardless +which one was used at the time of detachment. Without any options, +the layout to reattach to will be shown in the message line. +@end deffn + +@deffn Command layout @code{save} [n|title] +(none)@* +Remember the current arrangement of regions. When used, @code{screen} +will remember the arrangement of vertically and horizontally split +regions. This arrangement is restored when a @code{screen} session +is reattached or switched back from a different layout. If the +session ends or the @code{screen} process dies, the layout +arrangements are lost. The @code{layout dump} command should help +in this siutation. If a number +or title is supplied, @code{screen} will remember the arrangement of +that particular layout. Without any options, @code{screen} will +remember the current layout. + +Saving your regions can be done automatically by using the +@code{layout autosave} command. +@end deffn + +@deffn Command layout @code{autosave} [@code{on}|@code{off}] +(none)@* +Change or display the status of automatically saving layouts. The +default is @code{on}, meaning when @code{screen} is detached or +changed to a different layout, the arrangement of regions and windows +will be remembered at the time of change and restored upon return. +If autosave is set to @code{off}, that arrangement will only be +restored to either to the last manual save, using @code{layout save}, +or to when the layout was first created, to a single region with +a single window. Without either an @code{on} or an @code{off}, the +current status is displayed on the message line. +@end deffn + +@deffn Command layout @code{dump} [filename] +(none)@* +Write to a file the order of splits made in the current layout. This +is useful to recreate the order of your regions used in your current +layout. Only the current layout is recorded. While the order of the +regions are recorded, the sizes of those regions and which windows +correspond to which regions are not. If no filename is specified, +the default is @file{layout-dump}, saved in the directory that the +@code{screen} process was started in. If the file already exists, +@code{layout dump} will append to that file. As an example: +@example +layout dump /home/user/.screenrc +@end example +will save or append the layout to the user's @file{.screenrc} file. +@end deffn + +@node Window Settings, Virtual Terminal, Regions, Top +@chapter Window Settings + +These commands control the way @code{screen} treats individual windows +in a session. @xref{Virtual Terminal}, for commands to control the +terminal emulation itself. + +@menu +* Naming Windows:: Control the name of the window +* Console:: See the host's console messages +* Kill:: Destroy an unwanted window +* Login:: Control @file{/etc/utmp} logging +* Mode:: Control the file mode of the pty +* Monitor:: Watch for activity or inactivity in a window +* Windows:: List the active windows +* Hardstatus:: Set a window's hardstatus line +@end menu + +@node Naming Windows, Console, , Window Settings +@section Naming Windows (Titles) +@cindex title + +You can customize each window's name in the window display (viewed with +the @code{windows} command (@pxref{Windows}) by setting it with +one of the title commands. Normally the name displayed is the actual +command name of the program created in the window. However, it is +sometimes useful to distinguish various programs of the same name or to +change the name on-the-fly to reflect the current state of the window. + +The default name for all shell windows can be set with the +@code{shelltitle} command (@pxref{Shell}). You can specify the name you +want for a window with the @samp{-t} option to the @code{screen} command +when the window is created (@pxref{Screen Command}). To change the name after +the window has been created you can use the title-string escape-sequence +(@kbd{@key{ESC} k @var{name} @key{ESC} \}) and the @code{title} command +(C-a A). The former can be output from an application to control the +window's name under software control, and the latter will prompt for a +name when typed. You can also bind predefined names to keys with the +@code{title} command to set things quickly without prompting. + +@menu +* Title Command:: The @code{title} command. +* Dynamic Titles:: Make shell windows change titles dynamically. +* Title Prompts:: Set up your shell prompt for dynamic Titles. +* Title Screenrc:: Set up Titles in your @file{.screenrc}. +@end menu + +@node Title Command, Dynamic Titles, , Naming Windows +@subsection Title Command +@kindex A +@deffn Command title [windowtitle] +(@kbd{C-a A})@* +Set the name of the current window to @var{windowtitle}. If no name is +specified, screen prompts for one. +@end deffn + +@node Dynamic Titles, Title Prompts, Title Command, Naming Windows +@subsection Dynamic Titles +@code{screen} has a shell-specific heuristic that is enabled by +setting the window's name to @var{search|name} and arranging to have a +null title escape-sequence output as a part of your prompt. The +@var{search} portion specifies an end-of-prompt search string, while the +@var{name} portion specifies the default shell name for the window. If +the @var{name} ends in a @samp{:} @code{screen} will add what it +believes to be the current command running in the window to the end of +the specified name (e.g. @var{name:cmd}). Otherwise the current +command name supersedes the shell name while it is running. + +Here's how it works: you must modify your shell prompt to output a null +title-escape-sequence (@key{ESC} k @key{ESC} \) as a part of your prompt. +The last part of your prompt must be the same as the string you +specified for the @var{search} portion of the title. Once this is set +up, @code{screen} will use the title-escape-sequence to clear the previous +command name and get ready for the next command. Then, when a newline +is received from the shell, a search is made for the end of the prompt. +If found, it will grab the first word after the matched string and use +it as the command name. If the command name begins with @samp{!}, +@samp{%}, or @samp{^}, @code{screen} will use the first word on the +following line (if found) in preference to the just-found name. This +helps csh users get more accurate titles when using job control or +history recall commands. + +@node Title Prompts, Title Screenrc, Dynamic Titles, Naming Windows +@subsection Setting up your prompt for shell titles +One thing to keep in mind when adding a null title-escape-sequence to your +prompt is that some shells (like the csh) count all the non-control +characters as part of the prompt's length. If these invisible +characters aren't a multiple of 8 then backspacing over a tab will +result in an incorrect display. One way to get around this is to use a +prompt like this: + +@example +set prompt='@value{esc}[0000m@value{esc}k@value{esc}\% ' +@end example + +The escape-sequence @samp{@value{esc}[0000m} not only normalizes the +character attributes, but all the zeros round the length of the +invisible characters up to 8. + +Tcsh handles escape codes in the prompt more intelligently, so you can +specify your prompt like this: + +@example +set prompt="%@{\ek\e\\%@}\% " +@end example + +Bash users will probably want to echo the escape sequence in the +PROMPT_COMMAND: + +@example +PROMPT_COMMAND='printf "\033k\033\134"' +@end example + +(I used @samp{\134} to output a @samp{\} because of a bug in v1.04). + +@node Title Screenrc, , Title Prompts, Naming Windows +@subsection Setting up shell titles in your @file{.screenrc} +Here are some .screenrc examples: + +@example +screen -t top 2 nice top +@end example + +Adding this line to your .screenrc would start a niced version of the +@code{top} command in window 2 named @samp{top} rather than @samp{nice}. + +@example +shelltitle '> |csh' +screen 1 +@end example + +This file would start a shell using the given shelltitle. The title +specified is an auto-title that would expect the prompt and the typed +command to look something like the following: + +@example +/usr/joe/src/dir> trn +@end example + +(it looks after the '> ' for the command name). +The window status would show the name @samp{trn} while the command was +running, and revert to @samp{csh} upon completion. + +@example +bind R screen -t '% |root:' su +@end example + +Having this command in your .screenrc would bind the key sequence +@kbd{C-a R} to the @code{su} command and give it an auto-title name of +@samp{root:}. For this auto-title to work, the screen could look +something like this: + +@example +% !em +emacs file.c +@end example + +Here the user typed the csh history command @code{!em} which ran the +previously entered @code{emacs} command. The window status would show +@samp{root:emacs} during the execution of the command, and revert to +simply @samp{root:} at its completion. + +@example +bind o title +bind E title "" +bind u title (unknown) +@end example + +The first binding doesn't have any arguments, so it would prompt you for +a title when you type @kbd{C-a o}. The second binding would clear an +auto-titles current setting (C-a E). The third binding would set the +current window's title to @samp{(unknown)} (C-a u). + +@node Console, Kill, Naming Windows, Window Settings +@section Console +@deffn Command console [@var{state}] +(none)@* +Grabs or un-grabs the machines console output to a window. When the argument +is omitted the current state is displayed. +@emph{Note}: Only the owner of @file{/dev/console} can grab the console +output. This command is only available if the host supports the ioctl +@code{TIOCCONS}. +@end deffn + +@node Kill, Login, Console, Window Settings +@section Kill + +@kindex k +@kindex C-k +@deffn Command kill +(@kbd{C-a k}, @kbd{C-a C-k})@* +Kill the current window.@* +If there is an @code{exec} command running (@pxref{Exec}) then it is killed. +Otherwise the process (e.g. shell) running in the window receives a +@code{HANGUP} condition, +the window structure is removed and screen (your display) switches to another +window. When the last window is destroyed, @code{screen} exits. +After a kill screen switches to the previously displayed window. +@* +@emph{Caution}: @code{emacs} users may find themselves killing their +@code{emacs} session when trying to delete the current line. For this +reason, it is probably wise to use a different command character +(@pxref{Command Character}) or rebind @code{kill} to another key +sequence, such as @kbd{C-a K} (@pxref{Key Binding}). +@end deffn + +@node Login, Mode, Kill, Window Settings +@section Login + +@deffn Command deflogin state +(none)@* +Same as the @code{login} command except that the default setting for new +windows is changed. This defaults to `on' unless otherwise specified at +compile time (@pxref{Installation}). Both commands are only present when +@code{screen} has been compiled with utmp support. +@end deffn + +@kindex L +@deffn Command login [state] +(@kbd{C-a L})@* +Adds or removes the entry in @file{/etc/utmp} for the current window. +This controls whether or not the window is @dfn{logged in}. In addition +to this toggle, it is convenient to have ``log in'' and ``log out'' +keys. For instance, @code{bind I login on} and @code{bind O +login off} will map these keys to be @kbd{C-a I} and @kbd{C-a O} +(@pxref{Key Binding}). +@end deffn + +@node Mode, Monitor, Login, Window Settings +@section Mode +@deffn Command defmode mode +(none)@* +The mode of each newly allocated pseudo-tty is set to @var{mode}. +@var{mode} is an octal number as used by chmod(1). Defaults to 0622 for +windows which are logged in, 0600 for others (e.g. when @code{-ln} was +specified for creation, @pxref{Screen Command}). +@end deffn + +@node Monitor, Windows, Mode, Window Settings +@section Monitoring + +@deffn Command activity message +(none)@* +When any activity occurs in a background window that is being monitored, +@code{screen} displays a notification in the message line. The +notification message can be redefined by means of the @code{activity} +command. Each occurrence of @samp{%} in @var{message} is replaced by +the number of the window in which activity has occurred, and each +occurrence of @samp{^G} is replaced by the definition for bell in your +termcap (usually an audible bell). The default message is + +@example +'Activity in window %n' +@end example + +Note that monitoring is off for all windows by default, but can be altered +by use of the @code{monitor} command (@kbd{C-a M}). +@end deffn + +@deffn Command defmonitor state +(none)@* +Same as the @code{monitor} command except that the default setting for +new windows is changed. Initial setting is `off'. +@end deffn + +@kindex M +@deffn Command monitor [state] +(@kbd{C-a M})@* +Toggles monitoring of the current window. When monitoring is turned on +and the affected window is switched into the background, the activity +notification message will be displayed in the status line at the first +sign of output, and the window will also be marked with an @samp{@@} in +the window-status display (@pxref{Windows}). Monitoring defaults to +@samp{off} for all windows. +@end deffn + +@kindex _ +@deffn Command silence [@var{state}|@var{sec}] +(@kbd{C-a _})@* +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 +@code{silencewait} command or by specifying a number of seconds instead of +@code{on} or @code{off}. Silence is initially off for all windows. +@end deffn + +@deffn Command defsilence state +(none)@* +Same as the @code{silence} command except that the default setting for +new windows is changed. Initial setting is `off'. +@end deffn + +@deffn Command silencewait @var{seconds} +(none)@* +Define the time that all windows monitored for silence should wait +before displaying a message. Default is 30 seconds. +@end deffn + +@node Windows, Hardstatus, Monitor, Window Settings +@section Windows +@kindex w +@kindex C-w +@deffn Command windows [ string ] +(@kbd{C-a w}, @kbd{C-a C-w})@* +Uses the message line to display a list of all the windows. Each +window is listed by number with the name of the program running in the +window (or its title). + +The current window is marked with a @samp{*}; +the previous window is marked with a @samp{-}; +all the windows that are logged in are marked with a @samp{$} (@pxref{Login}); +a background window that has received a bell is marked with a @samp{!}; +a background window that is being monitored and has had activity occur is +marked with an @samp{@@} (@pxref{Monitor}); +a window which has output logging turned on is marked with @samp{(L)}; +windows occupied by other users are marked with @samp{&} +or @samp{&&} if the window is shared by other users; +windows in the zombie state are marked with @samp{Z}. + +If this list is too long to fit on the terminal's status line only the +portion around the current window is displayed. + +You can customize the output format to any string you like including +string escapes (@pxref{String Escapes}). +In this case, if the string parameter is passed, the maximum output +size is unlimited (instead of 1024 bytes if no parameter is passed). +@end deffn + +@node Hardstatus, Mousetrack, Windows, Window Settings +@section Hardstatus + +@code{Screen} maintains a hardstatus line for every window. If a window +gets selected, the display's hardstatus will be updated to match +the window's hardstatus line. +The hardstatus line can be changed with the ANSI Application +Program Command (APC): @samp{ESC_<string>ESC\}. As a convenience +for xterm users the sequence @samp{ESC]0..2;<string>^G} is +also accepted. + +@deffn Command defhstatus [status] +(none)@* +The hardstatus line that all new windows will get is set to +@var{status}. +This command is useful to make the hardstatus of every window +display the window number or title or the like. @var{status} +may contain the same directives as in the window messages, but +the directive escape character is @samp{^E} (octal 005) instead +of @samp{%}. This was done to make a misinterpretation of program +generated hardstatus lines impossible. +If the parameter @var{status} +is omitted, the current default string is displayed. +Per default the hardstatus line of new windows is empty. +@end deffn + +@deffn Command hstatus status +(none)@* +Changes the current window's hardstatus line to @var{status}. +@end deffn + +@node Mousetrack, , Hardstatus, Miscellaneous +@section Mousetrack + +@deffn Command mousetrack [ @code{on|off} ] +(none)@* +This command determines whether @code{screen} will watch for +mouse clicks. When this command is enabled, regions that have +been split in various ways can be selected by pointing to them +with a mouse and left-clicking them. Without specifying @var{on} +or @var{off}, the current state is displayed. The default state +is determined by the @code{defmousetrack} command. +@end deffn + +@deffn Command defmousetrack @code{on|off} +(none)@* +This command determines the default state of the @code{mousetrack} +command, currently defaulting of @var{off}. +@end deffn + +@node Virtual Terminal, Copy and Paste, Window Settings, Top +@chapter Virtual Terminal + +Each window in a @code{screen} session emulates a VT100 terminal, with +some extra functions added. The VT100 emulator is hard-coded, no other +terminal types can be emulated. +The commands described here modify the terminal emulation. + +@menu +* Control Sequences:: Details of the internal VT100 emulation. +* Input Translation:: How keystrokes are remapped. +* Digraph:: Entering digraph sequences. +* Bell:: Getting your attention. +* Clear:: Clear the window display. +* Info:: Terminal emulation statistics. +* Redisplay:: When the display gets confusing. +* Wrap:: Automatic margins. +* Reset:: Recovering from ill-behaved applications. +* Window Size:: Changing the size of your terminal. +* Character Processing:: Change the effect of special characters. +@end menu + +@node Control Sequences, Input Translation, , Virtual Terminal +@section Control Sequences +@cindex control sequences +The following is a list of control sequences recognized by +@code{screen}. @samp{(V)} and @samp{(A)} indicate VT100-specific and +ANSI- or ISO-specific functions, respectively. + +@example +ESC E Next Line +ESC D Index +ESC M Reverse Index +ESC H Horizontal Tab Set +ESC Z Send VT100 Identification String +ESC 7 (V) Save Cursor and Attributes +ESC 8 (V) Restore Cursor and Attributes +ESC [s (A) Save Cursor and Attributes +ESC [u (A) Restore Cursor and Attributes +ESC c Reset to Initial State +ESC g Visual Bell +ESC Pn p Cursor Visibility (97801) + Pn = 6 Invisible + 7 Visible +ESC = (V) Application Keypad Mode +ESC > (V) Numeric Keypad Mode +ESC # 8 (V) Fill Screen with E's +ESC \ (A) String Terminator +ESC ^ (A) Privacy Message String (Message Line) +ESC ! Global Message String (Message Line) +ESC k Title Definition String +ESC P (A) Device Control String + Outputs a string directly to the host + terminal without interpretation. +ESC _ (A) Application Program Command (Hardstatus) +ESC ] 0 ; string ^G (A) Operating System Command (Hardstatus, xterm + title hack) +ESC ] 83 ; cmd ^G (A) Execute screen command. This only works if + multi-user support is compiled into screen. + The pseudo-user ":window:" is used to check + the access control list. Use "addacl :window: + -rwx #?" to create a user with no rights and + allow only the needed commands. +Control-N (A) Lock Shift G1 (SO) +Control-O (A) Lock Shift G0 (SI) +ESC n (A) Lock Shift G2 +ESC o (A) Lock Shift G3 +ESC N (A) Single Shift G2 +ESC O (A) Single Shift G3 +ESC ( Pcs (A) Designate character set as G0 +ESC ) Pcs (A) Designate character set as G1 +ESC * Pcs (A) Designate character set as G2 +ESC + Pcs (A) Designate character set as G3 +ESC [ Pn ; Pn H Direct Cursor Addressing +ESC [ Pn ; Pn f same as above +ESC [ Pn J Erase in Display + Pn = None or 0 From Cursor to End of Screen + 1 From Beginning of Screen to Cursor + 2 Entire Screen +ESC [ Pn K Erase in Line + Pn = None or 0 From Cursor to End of Line + 1 From Beginning of Line to Cursor + 2 Entire Line +ESC [ Pn X Erase character +ESC [ Pn A Cursor Up +ESC [ Pn B Cursor Down +ESC [ Pn C Cursor Right +ESC [ Pn D Cursor Left +ESC [ Pn E Cursor next line +ESC [ Pn F Cursor previous line +ESC [ Pn G Cursor horizontal position +ESC [ Pn ` same as above +ESC [ Pn d Cursor vertical position +ESC [ Ps ;...; Ps m Select Graphic Rendition + Ps = None or 0 Default Rendition + 1 Bold + 2 (A) Faint + 3 (A) @i{Standout} Mode (ANSI: Italicized) + 4 Underlined + 5 Blinking + 7 Negative Image + 22 (A) Normal Intensity + 23 (A) @i{Standout} Mode off (ANSI: Italicized off) + 24 (A) Not Underlined + 25 (A) Not Blinking + 27 (A) Positive Image + 30 (A) Foreground Black + 31 (A) Foreground Red + 32 (A) Foreground Green + 33 (A) Foreground Yellow + 34 (A) Foreground Blue + 35 (A) Foreground Magenta + 36 (A) Foreground Cyan + 37 (A) Foreground White + 39 (A) Foreground Default + 40 (A) Background Black + ... ... + 49 (A) Background Default +ESC [ Pn g Tab Clear + Pn = None or 0 Clear Tab at Current Position + 3 Clear All Tabs +ESC [ Pn ; Pn r (V) Set Scrolling Region +ESC [ Pn I (A) Horizontal Tab +ESC [ Pn Z (A) Backward Tab +ESC [ Pn L (A) Insert Line +ESC [ Pn M (A) Delete Line +ESC [ Pn @@ (A) Insert Character +ESC [ Pn P (A) Delete Character +ESC [ Pn S Scroll Scrolling Region Up +ESC [ Pn T Scroll Scrolling Region Down +ESC [ Pn ^ same as above +ESC [ Ps ;...; Ps h Set Mode +ESC [ Ps ;...; Ps l Reset Mode + Ps = 4 (A) Insert Mode + 20 (A) @samp{Automatic Linefeed} Mode. + 34 Normal Cursor Visibility + ?1 (V) Application Cursor Keys + ?3 (V) Change Terminal Width to 132 columns + ?5 (V) Reverse Video + ?6 (V) @samp{Origin} Mode + ?7 (V) @samp{Wrap} Mode + ?9 X10 mouse tracking + ?25 (V) Visible Cursor + ?47 Alternate Screen (old xterm code) + ?1000 (V) VT200 mouse tracking + ?1047 Alternate Screen (new xterm code) + ?1049 Alternate Screen (new xterm code) +ESC [ 5 i (A) Start relay to printer (ANSI Media Copy) +ESC [ 4 i (A) Stop relay to printer (ANSI Media Copy) +ESC [ 8 ; Ph ; Pw t Resize the window to @samp{Ph} lines and + @samp{Pw} columns (SunView special) +ESC [ c Send VT100 Identification String +ESC [ x (V) Send Terminal Parameter Report +ESC [ > c Send Secondary Device Attributes String +ESC [ 6 n Send Cursor Position Report + +@end example + + +@node Input Translation, Digraph, Control Sequences, Virtual Terminal +@section Input Translation +@cindex input translation +In order to do a full VT100 emulation @code{screen} has to detect +that a sequence of characters in the input stream was generated +by a keypress on the user's keyboard and insert the VT100 +style escape sequence. @code{Screen} has a very flexible way of doing +this by making it possible to map arbitrary commands on arbitrary +sequences of characters. For standard VT100 emulation the command +will always insert a string in the input buffer of the window +(see also command @code{stuff}, @pxref{Paste}). +Because the sequences generated by a keypress can +change after a reattach from a different terminal type, it is +possible to bind commands to the termcap name of the keys. +@code{Screen} will insert the correct binding after each +reattach. See @ref{Bindkey} for further details on the syntax and examples. + +Here is the table of the default key bindings. (A) means that the +command is executed if the keyboard is switched into application +mode. +@example + +Key name Termcap name Command +----------------------------------------------------- +Cursor up ku stuff \033[A + stuff \033OA (A) +Cursor down kd stuff \033[B + stuff \033OB (A) +Cursor right kr stuff \033[C + stuff \033OC (A) +Cursor left kl stuff \033[D + stuff \033OD (A) +Function key 0 k0 stuff \033[10~ +Function key 1 k1 stuff \033OP +Function key 2 k2 stuff \033OQ +Function key 3 k3 stuff \033OR +Function key 4 k4 stuff \033OS +Function key 5 k5 stuff \033[15~ +Function key 6 k6 stuff \033[17~ +Function key 7 k7 stuff \033[18~ +Function key 8 k8 stuff \033[19~ +Function key 9 k9 stuff \033[20~ +Function key 10 k; stuff \033[21~ +Function key 11 F1 stuff \033[23~ +Function key 12 F2 stuff \033[24~ +Home kh stuff \033[1~ +End kH stuff \033[4~ +Insert kI stuff \033[2~ +Delete kD stuff \033[3~ +Page up kP stuff \033[5~ +Page down kN stuff \033[6~ +Keypad 0 f0 stuff 0 + stuff \033Op (A) +Keypad 1 f1 stuff 1 + stuff \033Oq (A) +Keypad 2 f2 stuff 2 + stuff \033Or (A) +Keypad 3 f3 stuff 3 + stuff \033Os (A) +Keypad 4 f4 stuff 4 + stuff \033Ot (A) +Keypad 5 f5 stuff 5 + stuff \033Ou (A) +Keypad 6 f6 stuff 6 + stuff \033Ov (A) +Keypad 7 f7 stuff 7 + stuff \033Ow (A) +Keypad 8 f8 stuff 8 + stuff \033Ox (A) +Keypad 9 f9 stuff 9 + stuff \033Oy (A) +Keypad + f+ stuff + + stuff \033Ok (A) +Keypad - f- stuff - + stuff \033Om (A) +Keypad * f* stuff * + stuff \033Oj (A) +Keypad / f/ stuff / + stuff \033Oo (A) +Keypad = fq stuff = + stuff \033OX (A) +Keypad . f. stuff . + stuff \033On (A) +Keypad , f, stuff , + stuff \033Ol (A) +Keypad enter fe stuff \015 + stuff \033OM (A) +@end example + +@node Digraph, Bell, Input Translation, Virtual Terminal +@section Digraph + +@kindex C-v +@deffn Command digraph [preset [unicode-value]] +(@kbd{C-a C-v})@* +This command prompts the user for a digraph sequence. The next +two characters typed are looked up in a builtin table and the +resulting character is inserted in the input stream. For example, +if the user enters @samp{a"}, an a-umlaut will be inserted. If the +first character entered is a 0 (zero), @code{screen} +will treat the following characters (up to three) as an octal +number instead. The optional argument @var{preset} +is treated as user input, thus one can create an "umlaut" key. +For example the command @samp{bindkey ^K digraph '"'} enables the user +to generate an a-umlaut by typing @samp{CTRL-K a}. When a non-zero +@var{unicode-value} is specified, a new digraph is created with the +specified preset. The digraph is unset if a zero value is provided +for the @var{unicode-value}. + +The following table is the builtin sequences. + +@documentencoding ISO-8859-1 +@example + Sequence Octal Digraph Unicode Equivalent + ----------------------------------------------- + ' ', ' ' 160 (space) U+00A0 + 'N', 'S' 160 (space) U+00A0 + '~', '!' 161 ¡ U+00A1 + '!', '!' 161 ¡ U+00A1 + '!', 'I' 161 ¡ U+00A1 + 'c', '|' 162 ¢ U+00A2 + 'c', 't' 162 ¢ U+00A2 + '$', '$' 163 £ U+00A3 + 'P', 'd' 163 £ U+00A3 + 'o', 'x' 164 ¤ U+00A4 + 'C', 'u' 164 ¤ U+00A4 + 'C', 'u' 164 ¤ U+00A4 + 'E', 'u' 164 ¤ U+00A4 + 'Y', '-' 165 ¥ U+00A5 + 'Y', 'e' 165 ¥ U+00A5 + '|', '|' 166 ¦ U+00A6 + 'B', 'B' 166 ¦ U+00A6 + 'p', 'a' 167 § U+00A7 + 'S', 'E' 167 § U+00A7 + '"', '"' 168 ¨ U+00A8 + ''', ':' 168 ¨ U+00A8 + 'c', 'O' 169 © U+00A9 + 'C', 'o' 169 © U+00A9 + 'a', '-' 170 ª U+00AA + '<', '<' 171 « U+00AB + '-', ',' 172 ¬ U+00AC + 'N', 'O' 172 ¬ U+00AC + '-', '-' 173 U+00AD + 'r', 'O' 174 ® U+00AE + 'R', 'g' 174 ® U+00AE + '-', '=' 175 ¯ U+00AF + ''', 'm' 175 ¯ U+00AF + '~', 'o' 176 ° U+00B0 + 'D', 'G' 176 ° U+00B0 + '+', '-' 177 ± U+00B1 + '2', '2' 178 ² U+00B2 + '2', 'S' 178 ² U+00B2 + '3', '3' 179 ³ U+00B3 + '3', 'S' 179 ³ U+00B3 + ''', ''' 180 ´ U+00B4 + 'j', 'u' 181 µ U+00B5 + 'M', 'y' 181 µ U+00B5 + 'p', 'p' 182 ¶ U+00B6 + 'P', 'I' 182 ¶ U+00B6 + '~', '.' 183 · U+00B7 + '.', 'M' 183 · U+00B7 + ',', ',' 184 ¸ U+00B8 + ''', ',' 184 ¸ U+00B8 + '1', '1' 185 ¹ U+00B9 + '1', 'S' 185 ¹ U+00B9 + 'o', '-' 186 º U+00BA + '>', '>' 187 » U+00BB + '1', '4' 188 ¼ U+00BC + '1', '2' 189 ½ U+00BD + '3', '4' 190 ¾ U+00BE + '~', '?' 191 ¿ U+00BF + '?', '?' 191 ¿ U+00BF + '?', 'I' 191 ¿ U+00BF + 'A', '`' 192 À U+00C0 + 'A', '!' 192 À U+00C0 + 'A', ''' 193 Á U+00C1 + 'A', '^' 194 Â U+00C2 + 'A', '>' 194 Â U+00C2 + 'A', '~' 195 Ã U+00C3 + 'A', '?' 195 Ã U+00C3 + 'A', '"' 196 Ä U+00C4 + 'A', ':' 196 Ä U+00C4 + 'A', '@@' 197 Å U+00C5 + 'A', 'A' 197 Å U+00C5 + 'A', 'E' 198 Æ U+00C6 + 'C', ',' 199 Ç U+00C7 + 'E', '`' 200 È U+00C8 + 'E', '!' 200 È U+00C8 + 'E', ''' 201 É U+00C9 + 'E', '^' 202 Ê U+00CA + 'E', '>' 202 Ê U+00CA + 'E', '"' 203 Ë U+00CB + 'E', ':' 203 Ë U+00CB + 'I', '`' 204 Ì U+00CC + 'I', '!' 204 Ì U+00CC + 'I', ''' 205 Í U+00CD + 'I', '^' 206 Î U+00CE + 'I', '>' 206 Î U+00CE + 'I', '"' 207 Ï U+00CF + 'I', ':' 207 Ï U+00CF + 'D', '-' 208 Ð U+00D0 + 'N', '~' 209 Ñ U+00D1 + 'N', '?' 209 Ñ U+00D1 + 'O', '`' 210 Ò U+00D2 + 'O', '!' 210 Ò U+00D2 + 'O', ''' 211 Ó U+00D3 + 'O', '^' 212 Ô U+00D4 + 'O', '>' 212 Ô U+00D4 + 'O', '~' 213 Õ U+00D5 + 'O', '?' 213 Õ U+00D5 + 'O', '"' 214 Ö U+00D6 + 'O', ':' 214 Ö U+00D6 + '/', '\' 215 × U+00D7 + '*', 'x' 215 × U+00D7 + 'O', '/' 216 Ø U+00D8 + 'U', '`' 217 Ù U+00D9 + 'U', '!' 217 Ù U+00D9 + 'U', ''' 218 Ú U+00DA + 'U', '^' 219 Û U+00DB + 'U', '>' 219 Û U+00DB + 'U', '"' 220 Ü U+00DC + 'U', ':' 220 Ü U+00DC + 'Y', ''' 221 Ý U+00DD + 'I', 'p' 222 Þ U+00DE + 'T', 'H' 222 Þ U+00DE + 's', 's' 223 ß U+00DF + 's', '"' 223 ß U+00DF + 'a', '`' 224 à U+00E0 + 'a', '!' 224 à U+00E0 + 'a', ''' 225 á U+00E1 + 'a', '^' 226 â U+00E2 + 'a', '>' 226 â U+00E2 + 'a', '~' 227 ã U+00E3 + 'a', '?' 227 ã U+00E3 + 'a', '"' 228 ä U+00E4 + 'a', ':' 228 ä U+00E4 + 'a', 'a' 229 å U+00E5 + 'a', 'e' 230 æ U+00E6 + 'c', ',' 231 ç U+00E7 + 'e', '`' 232 è U+00E8 + 'e', '!' 232 è U+00E8 + 'e', ''' 233 é U+00E9 + 'e', '^' 234 ê U+00EA + 'e', '>' 234 ê U+00EA + 'e', '"' 235 ë U+00EB + 'e', ':' 235 ë U+00EB + 'i', '`' 236 ì U+00EC + 'i', '!' 236 ì U+00EC + 'i', ''' 237 í U+00ED + 'i', '^' 238 î U+00EE + 'i', '>' 238 î U+00EE + 'i', '"' 239 ï U+00EF + 'i', ':' 239 ï U+00EF + 'd', '-' 240 ð U+00F0 + 'n', '~' 241 ñ U+00F1 + 'n', '?' 241 ñ U+00F1 + 'o', '`' 242 ò U+00F2 + 'o', '!' 242 ò U+00F2 + 'o', ''' 243 ó U+00F3 + 'o', '^' 244 ô U+00F4 + 'o', '>' 244 ô U+00F4 + 'o', '~' 245 õ U+00F5 + 'o', '?' 245 õ U+00F5 + 'o', '"' 246 ö U+00F6 + 'o', ':' 246 ö U+00F6 + ':', '-' 247 ÷ U+00F7 + 'o', '/' 248 ø U+00F8 + 'u', '`' 249 ù U+00F9 + 'u', '!' 249 ù U+00F9 + 'u', ''' 250 ú U+00FA + 'u', '^' 251 û U+00FB + 'u', '>' 251 û U+00FB + 'u', '"' 252 ü U+00FC + 'u', ':' 252 ü U+00FC + 'y', ''' 253 ý U+00FD + 'i', 'p' 254 þ U+00FE + 't', 'h' 254 þ U+00FE + 'y', '"' 255 ÿ U+00FF + 'y', ':' 255 ÿ U+00FF + '"', '[' 196 Ä U+00C4 + '"', '\' 214 Ö U+00D6 + '"', ']' 220 Ü U+00DC + '"', '@{' 228 ä U+00E4 + '"', '|' 246 ö U+00F6 + '"', '@}' 252 ü U+00FC + '"', '~' 223 ß U+00DF +@end example + +@end deffn + +@node Bell, Clear, Digraph, Virtual Terminal +@section Bell + +@deffn Command bell_msg [message] +(none)@* +When a bell character is sent to a background window, @code{screen} +displays a notification in the message line. The notification message +can be re-defined by this command. Each occurrence +of @samp{%} in @var{message} is replaced by the number of the window to +which a bell has been sent, and each occurrence of @samp{^G} is replaced +by the definition for bell in your termcap (usually an audible bell). +The default message is + +@example +'Bell in window %n' +@end example + +An empty message can be supplied to the @code{bell_msg} command to suppress +output of a message line (@code{bell_msg ""}). +Without a parameter, the current message is shown. +@end deffn + +@kindex C-g +@deffn Command vbell [state] +(@kbd{C-a C-g})@* +Sets or toggles the visual bell setting for the current window. If +@code{vbell} is switched to @samp{on}, but your +terminal does not support a visual bell, the visual bell message is +displayed in the status line when the bell character is received. +Visual bell support of a terminal is +defined by the termcap variable @code{vb}. @xref{Bell, , Visual Bell, +termcap, The Termcap Manual}, for more information on visual bells. +The equivalent terminfo capability is @code{flash}. + +Per default, @code{vbell} is @samp{off}, thus the audible bell is used. +@end deffn + +@deffn Command vbell_msg [message] +(none)@* +Sets the visual bell message. @var{Message} is printed to the status +line if the window receives a bell character (^G), @code{vbell} is +set to @samp{on} and the terminal does not support a visual bell. +The default message is @samp{Wuff, Wuff!!}. +Without a parameter, the current message is shown. +@end deffn + +@deffn Command vbellwait sec +(none)@* +Define a delay in seconds after each display of @code{screen} 's visual +bell message. The default is 1 second. +@end deffn + +@node Clear, Info, Bell, Virtual Terminal +@section Clear +@kindex C +@deffn Command clear +(@kbd{C-a C})@* +Clears the screen and saves its contents to the scrollback buffer. +@end deffn + +@node Info, Redisplay, Clear, Virtual Terminal +@section Info +@kindex i +@kindex C-i +@deffn Command info +(@kbd{C-a i}, @kbd{C-a C-i})@* +Uses the message line to display some information about the current +window: the cursor position in the form @samp{(@var{column},@var{row})} +starting with @samp{(1,1)}, the terminal width and height plus the size +of the scrollback buffer in lines, like in @samp{(80,24)+50}, +the current state of window XON/XOFF flow control is shown like this +(@pxref{Flow Control}): +@example + +flow automatic flow control, currently on. + -flow automatic flow control, currently off. + +(+)flow flow control enabled. Agrees with automatic control. + -(+)flow flow control disabled. Disagrees with automatic control. + +(-)flow flow control enabled. Disagrees with automatic control. + -(-)flow flow control disabled. Agrees with automatic control. +@end example + +The current line wrap setting (@samp{+wrap} indicates enabled, @samp{-wrap} +not) is also shown. The flags @samp{ins}, @samp{org}, @samp{app}, @samp{log}, +@samp{mon} and @samp{nored} are displayed when the window is in insert mode, +origin mode, application-keypad mode, has output logging, +activity monitoring or partial redraw enabled. + +The currently active +character set (@samp{G0}, @samp{G1}, @samp{G2}, or @samp{G3}), and in +square brackets the terminal character sets that are currently +designated as @samp{G0} through @samp{G3}. +If the window is in UTF-8 mode, the string @samp{UTF-8} is shown instead. +Additional modes depending on the type of the window are displayed at +the end of the status line (@pxref{Window Types}). + +If the state machine of the terminal emulator is in a non-default state, +the info line is started with a string identifying the current state. + +For system information use @code{time}. +@end deffn + +@deffn Command dinfo +(none)@* +Show what @code{screen} thinks about your terminal. Useful if you want to know +why features like color or the alternate charset don't work. +@end deffn + +@node Redisplay, Wrap, Info, Virtual Terminal +@section Redisplay + +@deffn Command allpartial state +(none)@* +If set to on, only the current cursor line is refreshed on window change. +This affects all windows and is useful for slow terminal lines. The +previous setting of full/partial refresh for each window is restored +with @code{allpartial off}. This is a global flag that immediately takes effect +on all windows overriding the @code{partial} settings. It does not change the +default redraw behavior of newly created windows. +@end deffn + +@deffn Command altscreen state +(none)@* +If set to on, "alternate screen" support is enabled in virtual terminals, +just like in xterm. Initial setting is @samp{off}. +@end deffn + +@deffn Command partial state +(none)@* +Defines whether the display should be refreshed (as with +@code{redisplay}) after switching to the current window. This command +only affects the current window. To immediately affect all windows use the +@code{allpartial} command. Default is @samp{off}, of course. This default is +fixed, as there is currently no @code{defpartial} command. +@end deffn + +@kindex l +@kindex C-l +@deffn Command redisplay +(@kbd{C-a l}, @kbd{C-a C-l})@* +Redisplay the current window. Needed to get a full redisplay in +partial redraw mode. +@end deffn + +@node Wrap, Reset, Redisplay, Virtual Terminal +@section Wrap + +@kindex r +@kindex C-r +@deffn Command wrap [ on | off ] +(@kbd{C-a r}, @kbd{C-a C-r}) @* +Sets the line-wrap setting for the current window. When line-wrap is +on, the second consecutive printable character output at the last column +of a line will wrap to the start of the following line. As an added +feature, backspace (^H) will also wrap through the left margin to the +previous line. Default is @samp{on}. Without any options, the state of +@code{wrap} is toggled. +@end deffn + +@deffn Command defwrap state +(none) @* +Same as the @code{wrap} command except that the default setting for new +windows is changed. Initially line-wrap is on and can be toggled with the +@code{wrap} command (@kbd{C-a r}) or by means of "C-a : wrap on|off". +@end deffn + +@node Reset, Window Size, Wrap, Virtual Terminal +@section Reset +@kindex Z +@deffn Command reset +(@kbd{C-a Z})@* +Reset the virtual terminal to its ``power-on'' values. Useful when strange +settings (like scroll regions or graphics character set) are left over from +an application. +@end deffn + +@node Window Size, Character Processing, Reset, Virtual Terminal +@section Window Size +@kindex W +@deffn Command width [@code{-w}|@code{-d}] [cols [lines]] +(@kbd{C-a W})@* +Toggle the window width between 80 and 132 columns, or set it to +@var{cols} columns if an argument is specified. This requires a +capable terminal and the termcap entries @samp{Z0} and @samp{Z1}. See +the @code{termcap} command (@pxref{Termcap}), for more information. +You can also specify a height if you want to +change both values. The @code{-w} option tells screen to leave +the display size unchanged and just set the window size, +@code{-d} vice versa. +@end deffn + +@deffn Command height [@code{-w}|@code{-d}] [lines [cols]] +(none)@* +Set the display height to a specified number of lines. When no +argument is given it toggles between 24 and 42 lines display. +@end deffn + +@node Character Processing, ,Window Size, Virtual Terminal +@section Character Processing + +@deffn Command c1 [state] +(none)@* +Change c1 code processing. @samp{c1 on} tells screen to treat +the input characters between 128 and 159 as control functions. +Such an 8-bit code is normally the same as ESC followed by the +corresponding 7-bit code. The default setting is to process c1 +codes and can be changed with the @samp{defc1} command. +Users with fonts that have usable characters in the +c1 positions may want to turn this off. + +@end deffn +@deffn Command gr [state] +(none)@* +Turn GR charset switching on/off. Whenever screen sees an input +char with an 8th bit set, it will use the charset stored in the +GR slot and print the character with the 8th bit stripped. The +default (see also @samp{defgr}) is not to process GR switching because +otherwise the ISO88591 charset would not work. +@end deffn + +@deffn Command bce [state] +(none)@* +Change background-color-erase setting. If @samp{bce} is set to +on, all characters cleared by an erase/insert/scroll/clear +operation will be displayed in the current background color. +Otherwise the default background color is used. +@end deffn + +@deffn Command encoding enc [denc] +(none)@* +Tell screen how to interpret the input/output. The first argument +sets the encoding of the current window. +Each window can emulate a different encoding. The optional second +parameter overwrites the encoding of the connected terminal. +It should never be needed as screen uses the locale setting to detect +the encoding. +There is also a way to select a terminal encoding depending on +the terminal type by using the @samp{KJ} termcap entry. @xref{Special Capabilities}. + +Supported encodings are +@code{eucJP}, @code{SJIS}, @code{eucKR}, +@code{eucCN}, @code{Big5}, @code{GBK}, @code{KOI8-R}, @code{CP1251}, +@code{UTF-8}, @code{ISO8859-2}, @code{ISO8859-3}, +@code{ISO8859-4}, @code{ISO8859-5}, @code{ISO8859-6}, +@code{ISO8859-7}, @code{ISO8859-8}, @code{ISO8859-9}, +@code{ISO8859-10}, @code{ISO8859-15}, @code{jis}. + +See also @samp{defencoding}, which changes the default setting of a new +window. +@end deffn + +@deffn Command charset set +(none)@* +Change the current character set slot designation and charset +mapping. The first four character of @var{set} +are treated as charset designators while the fifth and sixth +character must be in range @samp{0} to @samp{3} and set the GL/GR +charset mapping. On every position a @samp{.} may be used to indicate +that the corresponding charset/mapping should not be changed +(@var{set} is padded to six characters internally by appending +@samp{.} chars). New windows have @samp{BBBB02} as default +charset, unless a @samp{encoding} command is active. + +The current setting can be viewed with the @ref{Info} command. +@end deffn + +@deffn Command utf8 [state [dstate]] +(none)@* +Change the encoding used in the current window. If utf8 is enabled, the +strings sent to the window will be UTF-8 encoded and vice versa. +Omitting the +parameter toggles the setting. If a second parameter is given, the +display's +encoding is also changed (this should rather be done with screen's +@samp{-U} option). +See also @samp{defutf8}, which changes the default setting of a new +window. +@end deffn + +@deffn Command defc1 state +(none)@* +Same as the @samp{c1} command except that the default setting for +new windows is changed. Initial setting is @samp{on}. +@end deffn + +@deffn Command defgr state +(none)@* +Same as the @samp{gr} command except that the default setting for +new windows is changed. Initial setting is @samp{off}. +@end deffn + +@deffn Command defbce state +(none)@* +Same as the @samp{bce} command except that the default setting for +new windows is changed. Initial setting is @samp{off}. +@end deffn + +@deffn Command defencoding enc +(none)@* +Same as the @samp{encoding} command except that the default setting for +new windows is changed. Initial setting is the encoding taken from the +terminal. +@end deffn + +@deffn Command defcharset [set] +(none)@* +Like the @samp{charset} command except that the default setting for +new windows is changed. Shows current default if called without +argument. +@end deffn + +@deffn Command defutf8 state +(none)@* +Same as the @samp{utf8} command except that the default setting for new +windows is changed. Initial setting is @code{on} if screen was started +with @samp{-U}, otherwise @code{off}. +@end deffn + +@deffn Command cjkwidth [state] +(none)@* +Toggle how ambiguoous characters are treated. If cjkwidth is on screen +interprets them as double (full) width characters. If off then they are seen +as one cell (half) width characters. +@end deffn + + +@node Copy and Paste, Subprocess Execution, Virtual Terminal, Top +@chapter Copy and Paste +@cindex copy and paste + +For those confined to a hardware terminal, these commands provide a cut +and paste facility more powerful than those provided by most windowing +systems. + +@menu +* Copy:: Copy from scrollback to buffer +* Paste:: Paste from buffer into window +* Registers:: Longer-term storage +* Screen Exchange:: Sharing data between screen users +* History:: Recalling previous input +@end menu + +@node Copy, Paste, , Copy and Paste +@section Copying +@cindex marking +@cindex scrollback +@kindex [ +@kindex C-[ +@kindex ESC +@deffn Command copy +(@kbd{C-a [}, @kbd{C-a C-[}, @kbd{C-a @key{ESC}})@* +Enter copy/scrollback mode. This allows you to copy text from the +current window and its history into the paste buffer. In this mode a +@code{vi}-like full screen editor is active, with controls as +outlined below. +@end deffn + +@menu +* Line Termination:: End copied lines with CR/LF +* Scrollback:: Set the size of the scrollback buffer +* Copy Mode Keys:: Remap keys in copy mode +* Movement:: Move around in the scrollback buffer +* Marking:: Select the text you want +* Repeat count:: Repeat a command +* Searching:: Find the text you want +* Specials:: Other random keys +@end menu + +@node Line Termination, Scrollback, , Copy +@subsection CR/LF +@deffn Command crlf [state] +(none)@* +This affects the copying of text regions with the @code{copy} command. +If it is set to @samp{on}, lines will be separated by the two character +sequence @samp{CR}/@samp{LF}. Otherwise only @samp{LF} is used. +@code{crlf} is off by default. +When no parameter is given, the state is toggled. +@end deffn + +@node Scrollback, Copy Mode Keys, Line Termination, Copy +@subsection Scrollback +To access and use the contents in the scrollback buffer, use the @code{copy} command. @xref{Copy}. +@deffn Command defscrollback num +(none)@* +Same as the @code{scrollback} command except that the default setting +for new windows is changed. Defaults to 100. +@end deffn + +@deffn Command scrollback num +(none)@* +Set the size of the scrollback buffer for the current window to +@var{num} lines. The default scrollback is 100 lines. Use @code{info} +to view the current setting. +@end deffn + +@deffn Command compacthist [state] +(none)@* +This tells screen whether to suppress trailing blank lines when +scrolling up text into the history buffer. Turn compacting @samp{on} +to hold more useful lines in your scrollback buffer. +@end deffn + +@node Copy Mode Keys, Movement, Scrollback, Copy +@subsection Markkeys +@deffn Command markkeys string +(none)@* +This is a method of changing the keymap used for copy/history mode. The +string is made up of @var{oldchar}=@var{newchar} pairs which are +separated by @samp{:}. Example: The command @code{markkeys +h=^B:l=^F:$=^E} would set some keys to be more familiar to @code{emacs} +users. +If your terminal sends characters, that cause you to abort copy mode, +then this command may help by binding these characters to do nothing. +The no-op character is `@@' and is used like this: @code{markkeys @@=L=H} +if you do not want to use the `H' or `L' commands any longer. +As shown in this example, multiple keys can be assigned to one function +in a single statement. +@end deffn + +@node Movement, Marking, Copy Mode Keys, Copy +@subsection Movement Keys + +@noindent +@kbd{h}, @kbd{C-h}, or @kbd{left arrow} move the cursor left. + +@noindent +@kbd{j}, @kbd{C-n}, or @kbd{down arrow} move the cursor down. + +@noindent +@kbd{k}, @kbd{C-p}, or @kbd{up arrow} move the cursor up. + +@noindent +@kbd{l} ('el'), or @kbd{right arrow} move the cursor right. + +@noindent +@kbd{0} (zero) or @kbd{C-a} move to the leftmost column. + +@noindent +@kbd{+} and @kbd{-} move the cursor to the leftmost column of the next +or previous line. + +@noindent +@kbd{H}, @kbd{M} and @kbd{L} move the cursor to the leftmost column +of the top, center or bottom line of the window. + +@noindent +@kbd{|} moves to the specified absolute column. + +@noindent +@kbd{g} or @kbd{home} moves to the beginning of the buffer. + +@noindent +@kbd{G} or @kbd{end} moves to the specified absolute line (default: end of buffer). + +@noindent +@kbd{%} jumps to the specified percentage of the buffer. + +@noindent +@kbd{^} or @kbd{$} move to the first +or last non-whitespace character on the line. + +@noindent +@kbd{w}, @kbd{b}, and @kbd{e} move the cursor word by word. + +@noindent +@kbd{B}, @kbd{E} move the cursor WORD by WORD (as in vi). + +@noindent +@kbd{f}/@kbd{F}, @kbd{t}/@kbd{T} move the cursor forward/backward to the +next occurence of the target. (eg, '3fy' will move the cursor to the 3rd +'y' to the right.) + +@noindent +@kbd{;} and @kbd{,} Repeat the last f/F/t/T command in the same/opposite direction. + +@noindent +@kbd{C-e} and @kbd{C-y} scroll the display up/down by one line +while preserving the cursor position. + +@noindent +@kbd{C-u} and @kbd{C-d} scroll the display up/down by the specified +amount of lines while preserving the cursor position. (Default: half +screenful). + +@noindent +@kbd{C-b} and @kbd{C-f} move the cursor up/down a full screen. + +Note that Emacs-style movement keys can be specified by a .screenrc +command. (@code{markkeys "h=^B:l=^F:$=^E"}) There is no simple method for +a full emacs-style keymap, however, as this involves multi-character codes. + +@node Marking, Repeat count, Movement, Copy +@subsection Marking + +The copy range is specified by setting two marks. The text between these +marks will be highlighted. Press: + +@noindent +@kbd{space} or @kbd{enter} to set the first or second mark respectively. +If @code{mousetrack} is set to @code{on}, marks can also be set using +@kbd{left mouse click}. + +@noindent +@kbd{Y} and @kbd{y} can be used to mark one whole line or to mark from +start of line. + +@noindent +@kbd{W} marks exactly one word. + +@node Repeat count, Searching, Marking, Copy +@subsection Repeat Count + +Any command in copy mode can be prefixed with a number (by pressing +digits @kbd{0@dots{}9}) which is taken as a repeat count. Example: +@example +@kbd{C-a C-[ H 10 j 5 Y} +@end example +@noindent +will copy lines 11 to 15 into the paste buffer. + +@node Searching, Specials, Repeat count, Copy +@subsection Searching + +@noindent +@kbd{/} @code{vi}-like search forward. + +@noindent +@kbd{?} @code{vi}-like search backward. + +@noindent +@kbd{C-a s} @code{emacs} style incremental search forward. + +@noindent +@kbd{C-r} @code{emacs} style reverse i-search. + +@deffn Command ignorecase [on|off] +(none)@* +Tell screen to ignore the case of characters in searches. Default is +@code{off}. Without any options, the state of @code{ignorecase} +is toggled. +@end deffn + +@noindent +@kbd{n} Repeat search in forward direction. + +@noindent +@kbd{N} Repeat search in backward direction. + +@node Specials, , Searching, Copy +@subsection Specials + +There are, however, some keys that act differently here from in +@code{vi}. @code{Vi} does not allow to yank rectangular blocks of text, +but @code{screen} does. Press: + +@noindent +@kbd{c} or @kbd{C} to set the left or right margin respectively. If no +repeat count is given, both default to the current cursor position.@* +Example: Try this on a rather full text screen: +@example +@kbd{C-a [ M 20 l SPACE c 10 l 5 j C SPACE}. +@end example + +@noindent +This moves one to the middle line of the screen, moves in 20 columns left, +marks the beginning of the paste buffer, sets the left column, moves 5 columns +down, sets the right column, and then marks the end of +the paste buffer. Now try: +@example +@kbd{C-a [ M 20 l SPACE 10 l 5 j SPACE} +@end example + +@noindent +and notice the difference in the amount of text copied. + +@noindent +@kbd{J} joins lines. It toggles between 4 modes: lines separated by a +newline character (012), lines glued seamless, lines separated by a single +space or comma separated lines. Note that you can prepend the newline +character with a carriage return character, by issuing a @code{set crlf +on}. + +@noindent +@kbd{v} or @kbd{V} is for all the @code{vi} users who use @code{:set numbers} - it +toggles the left margin between column 9 and 1. + +@noindent +@kbd{a} before the final @kbd{space} key turns on append mode. Thus +the contents of the paste buffer will not be overwritten, but appended to. + +@noindent +@kbd{A} turns on append mode and sets a (second) mark. + +@noindent +@kbd{>} sets the (second) mark and writes the contents of the paste buffer +to the screen-exchange file (@file{/tmp/screen-exchange} per default) +once copy-mode is finished. @xref{Screen Exchange}.@* +This example demonstrates how to dump the +whole scrollback buffer to that file: +@example +@kbd{C-a [ g SPACE G $ >}. +@end example + +@noindent +@kbd{C-g} gives information about the current line and column. + +@noindent +@kbd{x} or @kbd{o} ('oh') exchanges the first mark and the current cursor position. You +can use this to adjust an already placed mark. + +@noindent +@kbd{C-l} ('el') will redraw the screen. + +@noindent +@kbd{@@} does nothing. Absolutely nothing. Does not even exit copy +mode. + +@noindent +All keys not described here exit copy mode. + +@node Paste, Registers, Copy, Copy and Paste +@section Paste + +@kindex ] +@kindex C-] +@deffn Command paste [registers [destination]] +(@kbd{C-a ]}, @kbd{C-a C-]})@* +Write the (concatenated) contents of the specified registers to the stdin +stream of the current window. The register @samp{.} is treated as the +paste buffer. If no parameter is specified the user is prompted to enter a +single register. The paste buffer can be filled with the +@code{copy}, @code{history} and @code{readbuf} commands. +Other registers can be filled with the @code{register}, @code{readreg} and +@code{paste} commands. +If @code{paste} is called with a second argument, the contents of the specified +registers is pasted into the named destination register rather than +the window. If @samp{.} is used as the second argument, the display's paste +buffer is the destination. +Note, that @code{paste} uses a wide variety of resources: Usually both, a +current window and a current display are required. But whenever a second +argument is specified no current window is needed. When the source specification +only contains registers (not the paste buffer) then there need not be a current +display (terminal attached), as the registers are a global resource. The +paste buffer exists once for every user. +@end deffn + +@deffn Command stuff [string] +(none)@* +Stuff the string @var{string} in the input buffer of the current window. +This is like the @code{paste} command, but with much less overhead. +Without a paramter, @code{screen} will prompt for a string to stuff. +You cannot paste large buffers with the @code{stuff} command. It is most +useful for key bindings. @xref{Bindkey}. +@end deffn + +@deffn Command pastefont [state] +Tell screen to include font information in the paste buffer. The +default is not to do so. This command is especially useful for +multi character fonts like kanji. +@end deffn + +@deffn Command slowpaste msec +@deffnx Command defslowpaste msec +(none)@* +Define the speed text is inserted in the current window by the @code{paste} +command. If the slowpaste value is nonzero text is written character by +character. +@code{screen} will pause for @var{msec} milliseconds after each write +to allow the application to process the input. only use @code{slowpaste} if +your underlying system exposes flow control problems while pasting large +amounts of text. +@code{defslowpaste} specifies the default for new windows. +@end deffn + +@deffn Command readreg [-e encoding] [register [filename]] +(none)@* +Does one of two things, dependent on number of arguments: with zero or one +arguments it it duplicates the paste buffer contents into the register specified +or entered at the prompt. With two arguments it reads the contents of the named +file into the register, just as @code{readbuf} reads the screen-exchange file +into the paste buffer. +You can tell screen the encoding of the file via the @code{-e} option. +The following example will paste the system's password file into +the screen window (using register p, where a copy remains): + +@example +C-a : readreg p /etc/passwd +C-a : paste p +@end example +@end deffn + +@node Registers, Screen Exchange, Paste, Copy and Paste +@section Registers + +@deffn Command copy_reg [key] +(none)@* +Removed. Use @code{readreg} instead. +@end deffn + +@deffn Command ins_reg [key] +(none)@* +Removed. Use @code{paste} instead. +@end deffn + +@deffn Command process [key] +(none)@* +Stuff the contents of the specified register into the @code{screen} +input queue. If no argument is given you are prompted for a +register name. The text is parsed as if it had been typed in from the user's +keyboard. This command can be used to bind multiple actions to a single key. +@end deffn + +@deffn Command register [-e encoding] key string +(none)@* +Save the specified @var{string} to the register @var{key}. +The encoding of the string can be specified via the @code{-e} option. +@end deffn + +@node Screen Exchange, History, Registers, Copy and Paste +@section Screen Exchange + +@deffn Command bufferfile [@var{exchange-file}] +(none)@* +Change the filename used for reading and writing with the paste buffer. +If the @var{exchange-file} parameter is omitted, @code{screen} reverts +to the default of @file{/tmp/screen-exchange}. The following example +will paste the system's password file into the screen window (using the +paste buffer, where a copy remains): + +@example +C-a : bufferfile /etc/passwd +C-a < C-a ] +C-a : bufferfile +@end example +@end deffn + +@kindex < +@deffn Command readbuf [-e @var{encoding}] [@var{filename}] +(@kbd{C-a <})@* +Reads the contents of the specified file into the paste buffer. +You can tell screen the encoding of the file via the @code{-e} option. +If no file is specified, the screen-exchange filename is used. +@end deffn + +@kindex = +@deffn Command removebuf +(@kbd{C-a =})@* +Unlinks the screen-exchange file. +@end deffn + +@kindex > +@deffn Command writebuf [-e @var{encoding}] [@var{filename}] +(@kbd{C-a >})@* +Writes the contents of the paste buffer to the specified file, or the +public accessible screen-exchange file if no filename is given. +This is thought of as a primitive means of +communication between @code{screen} users on the same host. +If an encoding is specified the paste buffer is recoded on the fly to +match the encoding. +See also +@kbd{C-a @key{ESC}} (@pxref{Copy}). +@end deffn + +@node History, , Screen Exchange, Copy and Paste +@section History + +@kindex @{ +@kindex @} +@deffn Command history +(@kbd{C-a @{}, @kbd{C-a @}})@* +Usually users work with a shell that allows easy access to previous +commands. For example, @code{csh} has the command @code{!!} to repeat +the last command executed. @code{screen} provides a primitive way of +recalling ``the command that started @dots{}'': You just type the first +letter of that command, then hit @kbd{C-a @{} and @code{screen} tries to +find a previous line that matches with the prompt character to the left +of the cursor. This line is pasted into this window's input queue. Thus +you have a crude command history (made up by the visible window and its +scrollback buffer). +@end deffn + +@node Subprocess Execution, Key Binding, Copy and Paste, Top +@chapter Subprocess Execution +Control Input or Output of a window by another filter process. +Use with care! + +@menu +* Exec:: The @code{exec} command syntax. +* Using Exec:: Weird things that filters can do. +@end menu + +@node Exec, Using Exec, , Subprocess Execution +@section Exec +@deffn Command exec [[@var{fdpat}] @var{newcommand} [@var{args} ... ]] +(none)@* +Run a unix subprocess (specified by an executable path @var{newcommand} and +its optional arguments) in the current window. The flow of data between +newcommands stdin/stdout/stderr, the process originally started (let us call it +"application-process") and +screen itself (window) is controlled by the file descriptor pattern @var{fdpat}. +This pattern is basically a three character sequence representing stdin, stdout +and stderr of newcommand. A dot (@code{.}) connects the file descriptor +to screen. An exclamation mark (@code{!}) causes the file descriptor to be +connected to the application-process. A colon (@code{:}) combines both. +@* +User input will go to newcommand unless newcommand receives the +application-process' +output (@var{fdpat}s first character is @samp{!} or @samp{:}) or a pipe symbol +(@samp{|}) is added to the end of @var{fdpat}. +@* +Invoking @code{exec} without arguments shows name and arguments of the currently +running subprocess in this window. Only one subprocess can be running per +window. +@* +When a subprocess is running the @code{kill} command will affect it instead of +the windows process. Only one subprocess a time can be running in each window. +@* +Refer to the postscript file @file{doc/fdpat.ps} for a confusing +illustration of all 21 possible combinations. Each drawing shows the digits +2, 1, 0 representing the three file descriptors of newcommand. The box +marked `W' is usual pty that has the application-process on its slave side. +The box marked `P' is the secondary pty that now has screen at its master +side. +@end deffn + +@node Using Exec, , Exec, Subprocess Execution +@section Using Exec +@noindent +Abbreviations: + +@itemize @bullet +@item +Whitespace between the word @samp{exec} and @var{fdpat} and the command name +can be omitted. + +@item +Trailing dots and a @var{fdpat} consisting only of dots can be omitted. + +@item +A simple @samp{|} is synonymous for the @samp{!..|} pattern. + +@item +The word @samp{exec} can be omitted when the @samp{|} abbreviation is used. + +@item +The word @samp{exec} can always be replaced by leading @samp{!}. +@end itemize + +@noindent +Examples: + +@table @code +@item !/bin/sh +@itemx exec /bin/sh +@itemx exec ... /bin/sh +All of the above are equivalent. +Creates another shell in the same window, while the original shell is still +running. Output of both shells is displayed and user input is sent to the new +@file{/bin/sh}. + +@item !!stty 19200 +@itemx exec!stty 19200 +@itemx exec !.. stty 19200 +All of the above are equivalent. +Set the speed of the window's tty. If your stty command operates on stdout, +then add another @samp{!}. This is a useful command, when a screen window +is directly connected to a serial line that needs to be configured. + +@item |less +@itemx exec !..| less +Both are equivalent. +This adds a pager to the window output. The special character @samp{|} is +needed to give the user control over the pager although it gets its input from +the window's process. This works, because @samp{less} listens on stderr +(a behavior that @code{screen} would not expect without the @samp{|}) +when its stdin is not a tty. @code{Less} versions newer than 177 fail miserably +here; good old @code{pg} still works. + +@item !:sed -n s/.*Error.*/\007/p +Sends window output to both, the user and the sed command. The sed inserts an +additional bell character (oct. 007) to the window output seen by screen. +This will cause 'Bell in window x' messages, whenever the string @samp{Error} +appears in the window. +@end table + +@node Key Binding, Flow Control, Subprocess Execution, Top +@chapter Key Binding +@cindex key binding +@cindex binding + +You may disagree with some of the default bindings (I know I do). The +@code{bind} command allows you to redefine them to suit your +preferences. + +@menu +* Bind:: @code{bind} syntax. +* Bind Examples:: Using @code{bind}. +* Command Character:: The character used to start keyboard commands. +* Help:: Show current key bindings. +* Bindkey:: @code{bindkey} syntax. +* Bindkey Examples:: Some easy examples. +* Bindkey Control:: How to control the bindkey mechanism. +@end menu + +@node Bind, Bind Examples, , Key Binding +@section The @code{bind} command +@deffn Command bind [-c class] key [command [args]] +(none)@* +Bind a command to a key. The @var{key} argument is either a single +character, a two-character sequence of the form @samp{^x} (meaning +@kbd{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 @samp{\^} or @samp{\\}. 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 @var{command} +argument can be any command (@pxref{Command Index}). + +If a command class is specified via the @code{-c} option, the +key is bound for the specified class. Use the @code{command} +command to activate a class. Command classes can be used +to create multiple command keys or multi-character bindings. + +By default, most suitable commands are bound to one or more keys +(@pxref{Default Key Bindings}); for instance, the command to create a +new window is bound to @kbd{C-c} and @kbd{c}. The @code{bind} command +can be used to redefine the key bindings and to define new bindings. +@end deffn + +@deffn Command unbindall +(none)@* +Unbind all the bindings. This can be useful when +screen is used solely for its detaching abilities, such as when +letting a console application run as a daemon. If, for some reason, +it is necessary to bind commands after this, use 'screen -X'. +@end deffn + +@node Bind Examples, Command Character, Bind, Key Binding +@section Examples of the @code{bind} command +@noindent +Some examples: + +@example +bind ' ' windows +bind ^f screen telnet foobar +bind \033 screen -ln -t root -h 1000 9 su +@end example + +@noindent +would bind the space key to the command that displays a list of windows +(so that the command usually invoked by @kbd{C-a C-w} would also be +available as @kbd{C-a space}), bind @kbd{C-f} to the command +``create a window with a TELNET connection to foobar'', and bind +@key{ESC} to the command that creates an non-login window with title +@samp{root} in slot #9, with a superuser shell and a scrollback buffer +of 1000 lines. + +@example +bind -c demo1 0 select 10 +bind -c demo1 1 select 11 +bind -c demo1 2 select 12 +bindkey "^B" command -c demo1 +@end example +makes @kbd{C-b 0} select window 10, @kbd{C-b 1} window 11, etc. + +@example +bind -c demo2 0 select 10 +bind -c demo2 1 select 11 +bind -c demo2 2 select 12 +bind - command -c demo2 +@end example +makes @kbd{C-a - 0} select window 10, @kbd{C-a - 1} window 11, etc. + +@node Command Character, Help, Bind Examples, Key Binding +@cindex escape character +@cindex command character +@section Command Character + +@deffn Command escape xy +(none)@* +Set the command character to @var{x} and the character generating a +literal command character (by triggering the @code{meta} command) +to @var{y} (similar to the @samp{-e} option). +Each argument is either a single character, a two-character +sequence of the form @samp{^x} (meaning @kbd{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 @samp{\^} or +@samp{\\}. The default is @samp{^Aa}, but @samp{``} is recommended by +one of the authors. +@end deffn + +@deffn Command defescape xy +(none)@* +Set the default command characters. This is equivalent to the command +@code{escape} except that it is useful for multiuser sessions only. +In a multiuser session +@code{escape} changes the command character of the calling user, where +@code{defescape} changes the default command characters for users that +will be added later. +@end deffn + +@kindex a +@deffn Command meta +(@kbd{C-a a})@* +Send the command character (@kbd{C-a}) to the process in the current +window. The keystroke for this command is the second parameter to the +@samp{-e} command line switch (@pxref{Invoking Screen}), or the +@code{escape} .screenrc directive. +@end deffn + +@deffn Command command [-c @var{class}] +(none)@* +This command has the same effect as typing the screen escape character +(@kbd{C-a}). It is probably only useful for key bindings. +If the @samp{-c} option is given, select the specified command class. +@xref{Bind}, @xref{Bindkey}. +@end deffn + +@node Help, Bindkey, Command Character, Key Binding +@section Help +@kindex ? +@deffn Command help +(@kbd{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. +If the @samp{-c} option is given, display all bound commands for the +specified command class. +@xref{Default Key Bindings}. +@end deffn + +@node Bindkey, Bindkey Examples, Help, Key Binding +@section Bindkey +@deffn Command bindkey [@var{opts}] [@var{string} [@var{cmd} @var{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. See @ref{Input Translation} +for a list of default key bindings. + +If the @samp{-d} +option is given, bindkey modifies the default table, @samp{-m} +changes the copy mode table and with neither option the user +table is selected. The argument @samp{string} is the sequence of +characters to which an action is bound. This can either be a fixed +string or a termcap keyboard capability name (selectable with the +@samp{-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 @samp{-a} +option. + +The @samp{-t} option tells screen not to do inter-character +timing. One cannot turn off the timing if a termcap capability is +used. + +@samp{cmd} can be any of screen's commands with an arbitrary +number of @samp{args}. If @samp{cmd} is omitted the key-binding is +removed from the table. +@end deffn + +@node Bindkey Examples, Bindkey Control,Bindkey, Key Binding +@section Bindkey Examples +@noindent +Here are some examples of keyboard bindings: + +@example +bindkey -d +@end example +@noindent +Show all of the default key bindings. The application mode entries +are marked with [A]. + +@example +bindkey -k k1 select 1 +@end example +@noindent +Make the "F1" key switch to window one. + +@example +bindkey -t foo stuff barfoo +@end example +@noindent +Make @samp{foo} an abbreviation of the word @samp{barfoo}. Timeout is +disabled so that users can type slowly. + +@example +bindkey "\024" mapdefault +@end example +@noindent +This key-binding makes @samp{C-t} an escape character for key-bindings. If +you did the above @samp{stuff barfoo} binding, you can enter the word +@samp{foo} by typing @samp{C-t foo}. If you want to insert a +@samp{C-t} you have to press the key twice (i.e., escape the escape +binding). + +@example +bindkey -k F1 command +@end example +@noindent +Make the F11 (not F1!) key an alternative screen +escape (besides @samp{C-a}). + +@node Bindkey Control, , Bindkey Examples, Key Binding +@section Bindkey Control +@deffn Command mapdefault +(none)@* +Tell screen that the next input character should only be looked up +in the default bindkey table. +@end deffn +@deffn Command mapnotnext +(none)@* +Like mapdefault, but don't even look in the default bindkey table. +@end deffn +@deffn Command maptimeout n +(none)@* +Set the inter-character timer for input sequence detection to a timeout +of @var{n} ms. The default timeout is 300ms. Maptimeout with no +arguments shows the current setting. +@end deffn + +@node Flow Control, Termcap, Key Binding, Top +@chapter Flow Control +@cindex flow control + +@code{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. @code{emacs}). + +@menu +* Flow Control Summary:: The effect of @code{screen} flow control +* Flow:: Setting the flow control behavior +* XON/XOFF:: Sending XON or XOFF to the window +@end menu + +@node Flow Control Summary, Flow, , Flow Control +@section About @code{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 @code{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 @kbd{C-a q} (xon) and @kbd{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 +@samp{-f} option or the @code{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 @code{flow} command bound to @kbd{C-a f}. + +The automatic flow-switching mode deals with flow control using the +TIOCPKT mode (like @code{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 @samp{interrupt} +option (add the @samp{interrupt} flag to the @code{flow} command in your +.screenrc, or use the @samp{-i} command-line option). This causes the +output that @code{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 @kbd{C-a l} you would see +the version of the output you would have gotten without @samp{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 +@samp{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 @kbd{C-a l} will restore it. Give each mode +a try, and use whichever mode you find more comfortable. + +@node Flow, XON/XOFF, Flow Control Summary, Flow Control +@section Flow +@deffn Command defflow fstate [interrupt] +(none)@* +Same as the @code{flow} command except that the default setting for new +windows is changed. Initial setting is `auto'. +Specifying @code{flow auto interrupt} has the same effect as the +command-line options @samp{-fa} and @samp{-i}. +Note that if @samp{interrupt} is enabled, all existing displays are +changed immediately to forward interrupt signals. +@end deffn + +@kindex f +@kindex C-f +@deffn Command flow [fstate] +(@kbd{C-a f}, @kbd{C-a C-f})@* +Sets the flow-control mode for this window to @var{fstate}, which can be +@samp{on}, @samp{off} or @samp{auto}. +Without parameters it cycles the current window's +flow-control setting. Default is set by `defflow'. +@end deffn + +@node XON/XOFF, , Flow, Flow Control +@section XON and XOFF +@kindex q +@kindex C-q +@deffn Command xon +(@kbd{C-a q}, @kbd{C-a C-q})@* +Send a ^Q (ASCII XON) to the program in the current window. Redundant +if flow control is set to @samp{off} or @samp{auto}. +@end deffn + +@kindex s +@kindex C-s +@deffn Command xoff +(@kbd{C-a s}, @kbd{C-a C-s})@* +Send a ^S (ASCII XOFF) to the program in the current window. +@end deffn + +@node Termcap, Message Line, Flow Control, Top +@chapter Termcap + +@code{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 @code{screen}. + +@menu +* Window Termcap:: Choosing a termcap entry for the window. +* Dump Termcap:: Write out a termcap entry for the window. +* Termcap Syntax:: The @code{termcap} and @code{terminfo} commands. +* Termcap Examples:: Uses for @code{termcap}. +* Special Capabilities:: Non-standard capabilities used by @code{screen}. +* Autonuke:: Flush unseen output +* Obuflimit:: Allow pending output when reading more +* Character Translation:: Emulating fonts and charsets. +@end menu + +@node Window Termcap, Dump Termcap, , Termcap +@section Choosing the termcap entry for a window +Usually @code{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 @code{screen} has to +tell the applications that some of the features are missing. This is no +problem on machines using termcap, because @code{screen} can use the +@code{$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 @code{screen} offers a way +to deal with these cases. Here is how it works: + +When @code{screen} tries to figure out a terminal name for itself, it +first looks for an entry named @code{screen.@var{term}}, where +@var{term} is the contents of your @code{$TERM} variable. If no such entry +exists, @code{screen} tries @samp{screen} (or @samp{screen-w}, if the +terminal is wide (132 cols or more)). If even this entry cannot be +found, @samp{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 @code{screen} (named +@samp{screen.@var{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 @code{$TERM} variable of all new windows. +@code{screen} also sets the @code{$TERMCAP} variable reflecting the +capabilities of the virtual terminal emulated. +Furthermore, the variable @code{$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, +@code{screen} does not put the @samp{us} and @samp{ue} capabilities into +the window's @code{$TERMCAP} variable, accordingly. However, a minimum number +of capabilities must be supported by a terminal in order to run +@code{screen}; namely scrolling, clear screen, and direct cursor +addressing (in addition, @code{screen} does not run on hardcopy +terminals or on terminals that over-strike). + +Also, you can customize the @code{$TERMCAP} value used by @code{screen} by +using the @code{termcap} command, or by defining the variable +@code{$SCREENCAP} prior to startup. When the latter defined, its value will be +copied verbatim into each window's @code{$TERMCAP} variable. This can either +be the full terminal definition, or a filename where the terminal +@samp{screen} (and/or @samp{screen-w}) is defined. + +Note that @code{screen} honors the @code{terminfo} command if the system +uses the terminfo database rather than termcap. On such machines the +@code{$TERMCAP} variable has no effect and you must use the +@code{dumptermcap} command (@pxref{Dump Termcap}) and the @code{tic} +program to generate terminfo entries for @code{screen} windows. + +When the boolean @samp{G0} capability is present in the termcap entry +for the terminal on which @code{screen} has been called, the terminal +emulation of @code{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: @samp{lock shift G0} (@samp{SI}), +@samp{lock shift G1} (@samp{SO}), @samp{lock shift G2}, @samp{lock shift +G3}, @samp{single shift G2}, and @samp{single shift G3}. When a virtual +terminal is created or reset, the ASCII character set is designated as +@samp{G0} through @samp{G3}. When the @samp{G0} capability is present, +screen evaluates the capabilities @samp{S0}, @samp{E0}, and @samp{C0} if +present. @samp{S0} is the sequence the terminal uses to enable and start +the graphics character set rather than @samp{SI}. @samp{E0} is the +corresponding replacement for @samp{SO}. @samp{C0} gives a character by +character translation string that is used during semi-graphics mode. +This string is built like the @samp{acsc} terminfo capability. + +When the @samp{po} and @samp{pf} capabilities are present in the +terminal's termcap entry, applications running in a @code{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. The @code{info} command displays a line starting +with @samp{PRIN} while the printer is active. + +Some capabilities are only put into the @code{$TERMCAP} variable of the virtual +terminal if they can be efficiently implemented by the physical +terminal. For instance, @samp{dl} (delete line) is only put into the +@code{$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 @code{$TERMCAP} +cannot be modified by parent processes. You can force @code{screen} to +include all capabilities in @code{$TERMCAP} with the @samp{-a} +command-line option (@pxref{Invoking Screen}). + +The "alternate screen" capability is not enabled by default. +Set the @code{altscreen} @file{.screenrc} command to enable it. + +@node Dump Termcap, Termcap Syntax, Window Termcap, Termcap +@section Write out the window's termcap entry +@kindex . +@deffn Command dumptermcap +(@kbd{C-a .})@* +Write the termcap entry for the virtual terminal optimized for the +currently active window to the file @file{.termcap} in the user's +@file{$HOME/.screen} directory (or wherever @code{screen} stores its +sockets. @pxref{Files}). This termcap entry is identical to +the value of the environment variable @code{$TERMCAP} that is set up by +@code{screen} for each window. For terminfo based systems you will need +to run a converter like @code{captoinfo} and then compile the entry with +@code{tic}. +@end deffn + +@node Termcap Syntax, Termcap Examples, Dump Termcap, Termcap +@section The @code{termcap} command +@deffn Command termcap term terminal-tweaks [window-tweaks] +@deffnx Command terminfo term terminal-tweaks [window-tweaks] +@deffnx 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 startup files, as they +are meaningless once the terminal emulator is booted. + +If your system uses the terminfo database rather than termcap, +@code{screen} will understand the @code{terminfo} command, which has the +same effects as the @code{termcap} command. Two separate commands are +provided, as there are subtle syntactic differences, e.g. when parameter +interpolation (using @samp{%}) is required. Note that the termcap names of +the capabilities should also be used with the @code{terminfo} command. + +In many cases, where the arguments are valid in both terminfo and termcap +syntax, you can use the command @code{termcapinfo}, which is just a +shorthand for a pair of @code{termcap} and @code{terminfo} commands with +identical arguments. +@end deffn + +The first argument specifies which terminal(s) should be affected by +this definition. You can specify multiple terminal names by separating +them with @samp{|}s. Use @samp{*} to match all terminals and @samp{vt*} +to match all terminals that begin with @samp{vt}. + +Each @var{tweak} argument contains one or more termcap defines +(separated by @samp{:}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 (@pxref{Virtual Terminal}). + +@node Termcap Examples, Special Capabilities, Termcap Syntax, Termcap +@section Termcap Examples +Some examples: + +@example +termcap xterm* xn:hs@@ +@end example + +@noindent +Informs @code{screen} that all terminals that begin with @samp{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 @samp{@@} to turn entries off). Note that we assume @samp{xn} for +all terminal names that start with @samp{vt}, but only if you don't +specify a termcap command for that terminal. + +@example +termcap vt* xn +termcap vt102|vt220 Z0=\E[?3h:Z1=\E[?3l +@end example + +@noindent +Specifies the firm-margined @samp{xn} capability for all terminals that +begin with @samp{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.) + +@example +termcap vt100 "" l0=PF1:l1=PF2:l2=PF3:l3=PF4 +@end example + +@noindent +This leaves your vt100 termcap alone and adds the function key labels to +each window's termcap entry. + +@example +termcap h19|z19 am@@:im=\E@@:ei=\EO dc=\E[P +@end example + +@noindent +Takes a h19 or z19 termcap and turns off auto-margins (am@@) and enables +the insert mode (im) and end-insert (ei) capabilities (the @samp{@@} in +the @samp{im} string is after the @samp{=}, so it is part of the +string). Having the @samp{im} and @samp{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 @code{$SCREENCAP} variable prior to running +@code{screen}. @xref{Virtual Terminal}, for the details of the +@code{screen} terminal emulation. @xref{Top, , Termcap, termcap, The +Termcap Manual}, for more information on termcap definitions. + +@node Special Capabilities, Autonuke, Termcap Examples, Termcap +@section Special Terminal Capabilities +@cindex terminal capabilities +@cindex capabilities +The following table describes all terminal capabilities that are +recognized by @code{screen} and are not in the termcap manual +(@pxref{Top, , Termcap, termcap, The Termcap Manual}). +You can place these capabilities in your termcap entries (in +@file{/etc/termcap}) or use them with the commands @code{termcap}, +@code{terminfo} and @code{termcapinfo} in your @code{screenrc} files. It is +often not possible to place these capabilities in the terminfo database. +@table @samp +@item LP +(bool)@* +Terminal has VT100 style margins (`magic margins'). Note that +this capability is obsolete --- @code{screen} now uses the standard +@samp{xn} instead. + +@item Z0 +(str)@* +Change width to 132 columns. + +@item Z1 +(str)@* +Change width to 80 columns. + +@item WS +(str)@* +Resize display. This capability has the desired width and height as +arguments. SunView(tm) example: @samp{\E[8;%d;%dt}. + +@item NF +(bool)@* +Terminal doesn't need flow control. Send ^S and ^Q direct to +the application. Same as @code{flow off}. The opposite of this +capability is @samp{nx}. + +@item G0 +(bool)@* +Terminal can deal with ISO 2022 font selection sequences. + +@item S0 +(str)@* +Switch charset @samp{G0} to the specified charset. Default +is @samp{\E(%.}. + +@item E0 +(str)@* +Switch charset @samp{G0} back to standard charset. Default +is @samp{\E(B}. + +@item C0 +(str)@* +Use the string as a conversion table for font 0. See +the @samp{ac} capability for more details. + +@item CS +(str)@* +Switch cursor-keys to application mode. + +@item CE +(str)@* +Switch cursor-keys to cursor mode. + +@item AN +(bool)@* +Enable autonuke for displays of this terminal type. +(@pxref{Autonuke}). + +@item OL +(num)@* +Set the output buffer limit. See the @samp{obuflimit} command +(@pxref{Obuflimit}) for more details. + +@item KJ +(str)@* +Set the encoding of the terminal. See the @samp{encoding} command +(@pxref{Character Processing}) for valid encodings. + +@item AF +(str)@* +Change character foreground color in an ANSI conform way. This +capability will almost always be set to @samp{\E[3%dm} +(@samp{\E[3%p1%dm} on terminfo machines). + +@item AB +(str)@* +Same as @samp{AF}, but change background color. + +@item AX +(bool)@* +Does understand ANSI set default fg/bg color (@samp{\E[39m / \E[49m}). + +@item XC +(str)@* +Describe a translation of characters to strings depending on the +current font. (@pxref{Character Translation}). + +@item XT +(bool)@* +Terminal understands special xterm sequences (OSC, mouse tracking). + +@item C8 +(bool)@* +Terminal needs bold to display high-intensity colors (e.g. Eterm). + +@item TF +(bool)@* +Add missing capabilities to the termcap/info entry. (Set by default). +@end table + +@node Autonuke, Obuflimit, Special Capabilities, Termcap +@section Autonuke +@deffn Command autonuke @var{state} +(none)@* +Sets whether a clear screen sequence should nuke all the output +that has not been written to the terminal. @xref{Obuflimit}. +This property is set per display, not per window. +@end deffn + +@deffn Command defautonuke @var{state} +(none)@* +Same as the @code{autonuke} command except that the default setting for +new displays is also changed. Initial setting is @code{off}. +Note that you can use the special @code{AN} terminal capability if you +want to have a terminal type dependent setting. +@end deffn + +@node Obuflimit, Character Translation, Autonuke, Termcap +@section Obuflimit +@deffn Command obuflimit [@var{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 @code{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. +@end deffn + +@deffn Command defobuflimit @var{limit} +(none)@* +Same as the @code{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 @code{OL} terminal capability if you want to have a terminal +type dependent limit. +@end deffn + +@node Character Translation, , Obuflimit, Termcap +@section Character Translation +@code{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: + +@example + XC=@var{<charset-mapping>}@{,,@var{<charset-mapping>}@} + @var{<charset-mapping>} := @var{<designator>}@var{<template>}@{,@var{<mapping>}@} + @var{<mapping>} := @var{<char-to-be-mapped>}@var{<template-arg>} +@end example + +The things in braces may be repeated any number of times. + +A @var{<charset-mapping>} tells screen how to map characters +in font @var{<designator>} (@samp{B}: Ascii, @samp{A}: UK, +@samp{K}: german, etc.) +to strings. Every @var{<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 occurrence +of @samp{%} in @var{<template>} gets substituted with the +@var{template-arg} +specified together with the character. If your strings are not +similar at all, then use @samp{%} as a template and place the full +string in @var{<template-arg>}. A quoting mechanism was added to make +it possible to use a real @samp{%}. The @samp{\} character quotes the +special characters @samp{\}, @samp{%}, and @samp{,}. + +Here is an example: + +@example + termcap hp700 'XC=B\E(K%\E(B,\304[,\326\\\\,\334]' +@end example + +This tells @code{screen}, how to translate ISOlatin1 (charset @samp{B}) +upper case umlaut characters on a @code{hp700} terminal that has a +German charset. @samp{\304} gets translated to +@samp{\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 @samp{\}. + +Another extension was added to allow more emulation: If a mapping +translates the unquoted @samp{%} char, it will be sent to the terminal +whenever screen switches to the corresponding @var{<designator>}. +In this +special case the template is assumed to be just @samp{%} because +the charset switch sequence and the character mappings normally +haven't much in common. + +This example shows one use of the extension: +@example + termcap xterm 'XC=K%,%\E(B,[\304,\\\\\326,]\334' +@end example + +Here, a part of the German (@samp{K}) charset is emulated on an xterm. +If screen has to change to the @samp{K} charset, @samp{\E(B} will be +sent +to the terminal, i.e. the ASCII charset is used instead. The +template is just @samp{%}, so the mapping is straightforward: +@samp{[} to @samp{\304}, @samp{\} to @samp{\326}, and @samp{]} to +@samp{\334}. + +@node Message Line, Logging, Termcap, Top +@chapter The Message Line +@cindex message line + +@code{Screen} displays informational messages and other diagnostics in a +@dfn{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. +@end menu + +@node Privacy Message, Hardware Status Line, , Message Line +@section 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 @dfn{Privacy message} control +sequence. For instance, from within the shell, try something like: + +@example +echo "@value{esc}^Hello world from window $WINDOW@value{esc}\" +@end example + +where @samp{@value{esc}} is ASCII ESC and the @samp{^} that follows it +is a literal caret or up-arrow. + +@node Hardware Status Line, Last Message, Privacy Message, Message Line +@section Hardware Status Line +@deffn Command hardstatus [state] +@deffnx Command hardstatus [@code{always}]@code{firstline}|@code{lastline}|@code{message}|@code{ignore} [string] +@deffnx Command hardstatus @code{string} [string] +(none)@* +This command configures the use and emulation of the terminal's +hardstatus line. The first form toggles whether @code{screen} +will use the hardware status line to display messages. If the +flag is set to @samp{off}, these messages +are overlaid in reverse video mode at the display line. The default +setting is @samp{on}. + +The second form tells screen what to do if the terminal doesn't +have a hardstatus line (i.e. the termcap/terminfo capabilities +"hs", "ts", "fs" and "ds" are not set). If the type +@code{firstline}/@code{lastline} is used, screen will reserve the first/last +line of the display for the hardstatus. @code{message} uses +@code{screen}'s message mechanism and +@code{ignore} tells @code{screen} never to display the hardstatus. +If you prepend the word @code{always} to the type (e.g., @code{alwayslastline}), @code{screen} will use +the type even if the terminal supports a hardstatus line. + +The third form specifies the contents of the hardstatus line. +@code{%h} is used as default string, i.e., the stored hardstatus of the +current window (settable via @samp{ESC]0;^G} or @samp{ESC_\\}) is +displayed. +You can customize this to any string you like including +string escapes (@pxref{String Escapes}). +If you leave +out the argument @var{string}, the current string is displayed. + +You can mix the second and third form by providing the string as +additional argument. +@end deffn + +@node Last Message, Message Wait, Hardware Status Line, Message Line +@section Display Last Message +@kindex m +@kindex C-m +@deffn Command lastmsg +(@kbd{C-a m}, @kbd{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. +@end deffn + +@node Message Wait, , Last Message, Message Line +@section Message Wait +@deffn Command msgminwait sec +(none)@* +Defines the time @code{screen} delays a new message when another is +currently displayed. Defaults to 1 second. +@end deffn + +@deffn Command msgwait sec +(none)@* +Defines the time a message is displayed, if @code{screen} is not +disturbed by other activity. Defaults to 5 seconds. +@end deffn + +@node Logging, Startup, Message Line, Top +@chapter 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 +@end menu + +@node Hardcopy, Log, , Logging +@section hardcopy +@kindex h +@deffn Command hardcopy [-h] [@var{file}] +(@kbd{C-a h})@* +Writes out the currently displayed image to the file @var{file}, or, +if no filename is specified, to @file{hardcopy.@var{n}} +in the default directory, where @var{n} is the number of the +current window. This either appends or overwrites the file if it +exists, as determined by the @code{hardcopy_append} command. +If the option @code{-h} is specified, dump also the +contents of the scrollback buffer. +@end deffn + +@deffn Command hardcopy_append state +(none)@* +If set to @samp{on}, @code{screen} will append to the +@file{hardcopy.@var{n}} files created by the command @code{hardcopy}; +otherwise, these files are overwritten each time. +@end deffn + +@deffn Command hardcopydir directory +(none)@* +Defines a directory where hardcopy files will be placed. +If unset, hardcopys are dumped in screen's current working +directory. +@end deffn + +@node Log, , Hardcopy, Logging +@section log + +@deffn Command deflog state +(none)@* +Same as the @code{log} command except that the default setting for new +windows is changed. Initial setting is `off'. +@end deffn + +@kindex H +@deffn Command log [state] +(@kbd{C-a H})@* +Begins/ends logging of the current window to the file +@file{screenlog.@var{n}} in the window's default directory, where +@var{n} is the number of the current window. +This filename can be changed with the @samp{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 @samp{off}. +@end deffn + +@deffn Command logfile filename +@deffnx Command logfile flush secs +(none)@* +Defines the name the log files will get. The default is @samp{screenlog.%n}. +The second form changes the number of seconds @code{screen} +will wait before flushing the logfile buffer to the file-system. The +default value is 10 seconds. +@end deffn + +@deffn Command logtstamp [state] +@deffnx Command logtstamp @code{after} secs +@deffnx Command logtstamp @code{string} string +(none)@* +This command controls logfile time-stamp mechanism of screen. If +time-stamps are turned @samp{on}, screen adds a string containing +the current time to the logfile after two minutes of inactivity. +When output continues and more than another two minutes have passed, +a second time-stamp is added to document the restart of the +output. You can change this timeout with the second form +of the command. The third form is used for customizing the time-stamp +string (@samp{-- %n:%t -- time-stamp -- %M/%d/%y %c:%s --\n} by +default). +@end deffn + +@node Startup, Miscellaneous, Logging, Top +@chapter Startup + +This section describes commands which are only useful in the +@file{.screenrc} file, for use at startup. + +@menu +* echo:: Display a message. +* sleep:: Pause execution of the @file{.screenrc}. +* Startup Message:: Control display of the copyright notice. +@end menu + +@node echo, sleep, , Startup +@section echo +@deffn Command echo [@samp{-n}] message +(none)@* +The echo command may be used to annoy @code{screen} users with a +'message of the day'. Typically installed in a global screenrc. +The option @samp{-n} may be used to suppress the line feed. +See also @code{sleep}. +Echo is also useful for online checking of environment variables. +@end deffn + +@node sleep, Startup Message, echo, Startup +@section sleep +@deffn Command sleep num +(none)@* +This command will pause the execution of a .screenrc file for @var{num} +seconds. Keyboard activity will end the sleep. It may be used to give +users a chance to read the messages output by @code{echo}. +@end deffn + +@node Startup Message, , sleep, Startup +@section Startup Message +@deffn Command startup_message state +(none)@* +Select whether you want to see the copyright notice during startup. +Default is @samp{on}, as you probably noticed. +@end deffn + +@node Miscellaneous, String Escapes, Startup, Top +@chapter 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. +* Bumpleft:: Swaps window with previous one on window list. +* Bumpright:: Swaps window with next one on window list. +* Collapse:: Collapses window list. +* Debug:: Suppress/allow debugging output. +* License:: Display the disclaimer page. +* Nethack:: Use @code{nethack}-like error messages. +* Nonblock:: Disable flow-control to a display. +* Number:: Change the current window's number. +* Time:: Display the time and load average. +* Verbose:: Display window creation commands. +* Version:: Display the version of @code{screen}. +* Zombie:: Keep dead windows. +* Printcmd:: Set command for VT100 printer port emulation. +* Rendition:: Change text attributes in caption for flagged windows. +* Sorendition:: Change the text highlighting method. +* Attrcolor:: Map attributes to colors. +* Setsid:: Change process group management. +* Eval:: Parse and execute arguments. +* Maxwin:: Set the maximum window number. +* Backtick:: Program a command for a backtick string escape. +* Screen Saver:: Define a screen safer. +* Zmodem:: Define how screen treats zmodem requests. +* Mousetrack:: Set whether screen should track mouse events. +@end menu + +@node At, Break, , Miscellaneous +@section At +@deffn Command at [identifier][#|*|%] command [args] +(none)@* +Execute a command at other displays or windows as if it had been entered there. +@code{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 @samp{@var{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 @samp{@var{identifier}%} identifier is +matched against displays. Displays are named after the ttys they attach. The +prefix @samp{/dev/} or @samp{/dev/tty} may be omitted from the identifier. +If @var{identifier} has a @code{#} or nothing appended it is matched against +window numbers and titles. Omitting an identifier in front of the @code{#}, +@code{*} or @code{%} 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. +Note that the @code{#} character works as a comment introducer when it is +preceded by whitespace. This can be escaped by prefixing @code{#} with a +@code{\}. +Permission is checked for the initiator of the @code{at} command, not for the +owners of the affected display(s). +Caveat: +When matching against windows, the command is executed at least +once per window. Commands that change the internal arrangement of windows +(like @code{other}) may be called again. In shared windows the command will +be repeated for each attached display. Beware, when issuing toggle commands +like @code{login}! +Some commands (e.g. @code{\*Qprocess}) require +that a display is associated with the target windows. These commands may not +work correctly under @code{at} looping over windows. +@end deffn + +@node Break, Bumpleft, At, Miscellaneous +@section Break +@kindex b +@kindex C-b +@deffn Command break [duration] +(@kbd{C-a b}, @kbd{C-a C-b})@* +Send a break signal for @var{duration}*0.25 seconds to this window. +For non-Posix systems the time interval is rounded up to full seconds. +Most useful if a character device is attached to the window rather than +a shell process (@pxref{Window Types}). The maximum duration of +a break signal is limited to 15 seconds. +@end deffn + +@kindex B +@deffn Command pow_break +(@kbd{C-a B})@* +Reopen the window's terminal line and send a break condition. +@end deffn + +@deffn Command breaktype [tcsendbreak|TIOCSBRK|TCSBRK] +(none)@* +Choose one of the available methods of generating a break signal for +terminal devices. This command should affect the current window only. +But it still behaves identical to @code{defbreaktype}. This will be changed in +the future. +Calling @code{breaktype} with no parameter displays the break setting for the +current window. +@end deffn + +@deffn Command defbreaktype [tcsendbreak|TIOCSBRK|TCSBRK] +(none)@* +Choose one of the available methods of generating a break signal for +terminal devices opened afterwards. The preferred methods are +@code{tcsendbreak} and +@code{TIOCSBRK}. The third, @code{TCSBRK}, blocks the complete @code{screen} +session for the duration of the break, but it may be the only way to +generate long breaks. @code{tcsendbreak} and @code{TIOCSBRK} may or may not +produce long breaks with spikes (e.g. 4 per second). This is not only system +dependent, this also differs between serial board drivers. +Calling @code{defbreaktype} with no parameter displays the current setting. +@end deffn + +@node Bumpleft, Bumpright, Break, Miscellaneous +@section Bumpleft +@deffn Command bumpleft +(none)@* +Exchanges windows positions on window list, with window having lower number +(left to current one). +@end deffn + +@node Bumpright, Collapse, Bumpleft, Miscellaneous +@section Bumpright +@deffn Command bumpright +(none)@* +Exchanges windows positions on window list, with window having bigger number +(right to current one). +@end deffn + +@node Collapse, Debug, Bumpright, Miscellaneous +@section Collapse +@deffn Command collapse +(none)@* +Changes windows numbers, so there is no gaps between them. +@end deffn + +@node Debug, License, Collapse, Miscellaneous +@section Debug +@deffn Command debug [on|off] +(none)@* +Turns runtime debugging on or off. If @code{screen} has been compiled with +option @code{-DDEBUG} debugging is available and is turned on per default. +Note that this command only affects debugging output from the main +@samp{SCREEN} process correctly. Debug output from attacher processes can only +be turned off once and forever. +@end deffn + +@node License, Nethack, Debug, Miscellaneous +@section License +@kindex , +@deffn Command license +(@kbd{C-a ,})@* +Display the disclaimer page. This is done whenever @code{screen} is +started without options, which should be often enough. +@end deffn + +@node Nethack, Nonblock, License, Miscellaneous +@section Nethack +@deffn Command nethack state +(none)@* +Changes the kind of error messages used by @code{screen}. When you are +familiar with the game @code{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 @code{screen} was compiled with the +NETHACK flag defined (@pxref{Installation}). The default setting is then +determined by the presence of the environment variable +@code{$NETHACKOPTIONS} and the file @code{~/.nethackrc} - if either one is +present, the default is @code{on}. +@end deffn + +@node Nonblock, Number, Nethack, Miscellaneous +@section Nonblock +@deffn Command nonblock [@var{state}|@var{numsecs}] +Tell screen how to deal with user interfaces (displays) that cease to +accept output. This can happen if a user presses ^S or a TCP/modem +connection gets cut but no hangup is received. If nonblock is +@code{off} (this is the default) screen waits until the display +restarts to accept the output. If nonblock is @code{on}, screen +waits until the timeout is reached (@code{on} is treated as 1s). If the +display still doesn't receive characters, screen will consider +it ``blocked'' and stop sending characters to it. If at +some time it restarts to accept characters, screen will unblock +the display and redisplay the updated window contents. +@end deffn + +@deffn Command defnonblock @var{state}|@var{numsecs} +Same as the @code{nonblock} command except that the default setting for +displays is changed. Initial setting is @code{off}. +@end deffn + +@node Number, Time, Nonblock, Miscellaneous +@section Number +@kindex N +@deffn Command number [[+|-]@var{n}] +(@kbd{C-a N})@* +Change the current window's number. If the given number @var{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. Using either a +plus (`+') or minus (`-') will change the window's number by the relative +amount specified. +@end deffn + +@node Time, Verbose, Number, Miscellaneous +@section Time +@kindex t +@kindex C-t +@deffn Command time [@var{string}] +(@kbd{C-a t}, @kbd{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 @code{info} (@pxref{Info}). +If a @var{string} is specified, it changes the format of the time report +like it is described in the string escapes chapter (@pxref{String Escapes}). Screen uses a default of @samp{%c:%s %M %d %H%? %l%?}. +@end deffn + +@node Verbose, Version, Time, Miscellaneous +@section Verbose +@deffn Command verbose [on|off] +If verbose is switched on, the command name is echoed, whenever a window +is created (or resurrected from zombie state). Default is off. +Without a parameter, the current setting is shown. +@end deffn + +@node Version, Zombie, Verbose, Miscellaneous +@section Version +@kindex v +@deffn Command version +(@kbd{C-a v})@* +Display the version and modification date in the message line. +@end deffn + +@node Zombie, Printcmd, Version, Miscellaneous +@section Zombie +@deffn Command zombie [@var{keys} [onerror] ] +@deffn Command zombie_timeout [@var{seconds}] +@end deffn +(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 @code{kill} command 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 @code{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 probably be called @code{defzombie}, but it isn't. + +Optionally you can put the word @code{onerror} after the keys. This will +cause screen to monitor exit status of the process running in the window. +If it exits normally ('0'), the window disappears. Any other exit value +causes the window to become a zombie. + +Additionally the @code{zombie_timeout} command exists. +If a window is declared ``dead'', screen will automatically try to +resurrect the window after the timeout. +It only works if zombie keys are defined via @code{zombie} command. +@end deffn + +@node Printcmd, Rendition, Zombie, Miscellaneous +@section Printcmd +@deffn Command printcmd [@var{cmd}] +(none)@* +If @var{cmd} is not an empty string, screen will not use the terminal +capabilities @code{po/pf} for printing if it detects an ansi print +sequence @code{ESC [ 5 i}, but pipe the output into @var{cmd}. +This should normally be a command like @samp{lpr} or +@samp{cat > /tmp/scrprint}. +@code{Printcmd} without an argument displays the current setting. +The ansi sequence @code{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. +@end deffn + +@node Rendition, Sorendition, Printcmd, Miscellaneous +@section Rendition +@deffn Command rendition bell | monitor | silence | so @var{attr} [@var{color}] +(none)@* +Change the way screen renders the titles of windows that have monitor +or bell flags set in caption or hardstatus or windowlist. +See the chapter +about string escapes (@pxref{String Escapes}) for the syntax of +the modifiers. The default for monitor is currently @samp{=b} (bold, +active colors), for bell @samp{=ub} (underline, bold and active colors), and +for silence @samp{=u}. +@end deffn + +@node Sorendition, Attrcolor, Rendition, Miscellaneous +@section Sorendition +@deffn Command sorendition [@var{attr} [@var{color}]] +(none)@* +This command has been deprecated. Use @code{rendition so} instead. +@end deffn + +@node Attrcolor, Setsid, Sorendition, Miscellaneous +@section Attrcolor +@deffn Command attrcolor @var{attrib} [@var{attribute/color-modifier}] +(none)@* +This command can be used to highlight attributes by changing the color of +the text. If the attribute +@var{attrib} +is in use, the specified attribute/color modifier is also applied. If no +modifier is given, the current one is deleted. See the chapter +about string escapes (@pxref{String Escapes}) for the syntax of +the modifier. @code{Screen} understands two pseudo-attributes, @code{i} +stands for high-intensity foreground color and @code{I} for +high-intensity background color. + +@noindent +Examples: +@table @code +@item attrcolor b "R" +Change the color to bright red if bold text is to be printed. +@item attrcolor u "-u b" +Use blue text instead of underline. +@item attrcolor b ".I" +Use bright colors for bold text. Most terminal emulators do this +already. +@item attrcolor i "+b" +Make bright colored text also bold. +@end table +@end deffn + +@node Setsid, Eval, Attrcolor, Miscellaneous +@section Setsid +@deffn Command setsid state +(none)@* +Normally @code{screen} uses different sessions and process groups for +the windows. If setsid is turned @code{off}, this is not done +anymore and all windows will be in the same process group as the +screen backend process. This also breaks job-control, so be careful. +The default is @code{on}, of course. This command is probably useful +only in rare circumstances. +@end deffn + +@node Eval, Maxwin, Setsid, Miscellaneous +@section Eval +@deffn Command eval @var{command1} [@var{command2} ...] +(none)@* +Parses and executes each argument as separate command. +@end deffn + +@node Maxwin, Backtick, Eval, Miscellaneous +@section Maxwin +@deffn Command maxwin @var{n} +(none)@* +Set the maximum window number screen will create. Doesn't affect +already existing windows. The number can be increased only when there are no +existing windows. +@end deffn + +@node Backtick, Screen Saver, Maxwin, Miscellaneous +@section Backtick +@deffn Command backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}] +@deffnx Command backtick @var{id} +(none)@* +Program the backtick command with the numerical id @var{id}. +The output of such a command is used for substitution of the +@code{%`} string escape (@pxref{String Escapes}). +The specified @var{lifespan} is the number +of seconds the output is considered valid. After this time, the +command is run again if a corresponding string escape is encountered. +The @var{autorefresh} parameter triggers an +automatic refresh for caption and hardstatus strings after the +specified number of seconds. Only the last line of output is used +for substitution. + +If both the @var{lifespan} and the @var{autorefresh} parameters +are zero, the backtick program is expected to stay in the +background and generate output once in a while. +In this case, the command is executed right away and screen stores +the last line of output. If a new line gets printed screen will +automatically refresh the hardstatus or the captions. + +The second form of the command deletes the backtick command +with the numerical id @var{id}. +@end deffn + +@node Screen Saver, Zmodem, Backtick, Miscellaneous +@section Screen Saver +@deffn Command idle [@var{timeout} [@var{cmd} @var{args}]] +(none)@* +Sets a command that is run after the specified number of +seconds inactivity is reached. This command will normally +be the @code{blanker} command to create a screen blanker, but +it can be any screen command. If no command is specified, +only the timeout is set. A timeout of zero (ot the special +timeout @code{off}) disables the timer. If no arguments are +given, the current settings are displayed. +@end deffn + +@deffn Command blanker +(none)@* +Activate the screen blanker. First the screen is cleared. +If no blanker program is defined, the cursor is turned +off, otherwise, the program is started and it's output is +written to the screen. The screen blanker is killed with +the first keypress, the read key is discarded. + +This command is normally used together with the @code{idle} +command. +@end deffn + +@deffn Command blankerprg [@var{program args}] +Defines a blanker program. Disables the blanker program if an +empty argument is given. Shows the currently set blanker program if no +arguments are given. + +@end deffn + +@node Zmodem, , Screen Saver, Miscellaneous +@section Zmodem +@deffn Command zmodem [off|auto|catch|pass] +@deffnx Command zmodem sendcmd [string] +@deffnx Command zmodem recvcmd [string] +(none)@* +Define zmodem support for @code{screen}. @code{Screen} understands two +different modes when it detects a zmodem request: @code{pass} +and @code{catch}. If the mode is set to @code{pass}, screen will +relay all data to the attacher until the end of the +transmission is reached. In @code{catch} mode screen acts as a +zmodem endpoint and starts the corresponding rz/sz commands. +If the mode is set to @code{auto}, screen will use @code{catch} if +the window is a tty (e.g. a serial line), otherwise it +will use @code{pass}. + +You can define the templates screen uses in @code{catch} mode +via the second and the third form. + +Note also that this is an experimental feature. +@end deffn + +@node String Escapes, Environment, Miscellaneous, Top +@chapter String Escapes +@cindex string escapes +Screen provides an escape mechanism to insert information like the +current time into messages or file names. The escape character +is @code{%} with one exception: inside of a window's hardstatus +@code{^%} (@code{^E}) is used instead. + +Here is the full list of supported escapes: + +@table @code +@item % +the escape character itself +@item a +either @code{am} or @code{pm} +@item A +either @code{AM} or @code{PM} +@item c +current time @code{HH:MM} in 24h format +@item C +current time @code{HH:MM} in 12h format +@item d +day number +@item D +weekday name +@item E +sets %? to true if the escape character has been pressed. +@item f +flags of the window. @xref{Windows}, for meanings of the various flags. +@item F +sets %? to true if the window has the focus +@item h +hardstatus of the window +@item H +hostname of the system +@item l +current load of the system +@item m +month number +@item M +month name +@item n +window number +@item P +sets %? to true if the current region is in copy/paste mode +@item s +seconds +@item S +session name +@item t +window title +@item u +all other users on this window +@item w +all window numbers and names. With @code{-} qualifier: up to the current +window; with @code{+} qualifier: starting with the window after the current +one. +@item W +all window numbers and names except the current one +@item y +last two digits of the year number +@item Y +full year number +@item ? +the part to the next @code{%?} is displayed only if a @code{%} escape +inside the part expands to a non-empty string +@item : +else part of @code{%?} +@item = +pad the string to the display's width (like TeX's hfill). If a +number is specified, pad to the percentage of the window's width. +A @code{0} qualifier tells screen to treat the number as absolute position. +You can specify to pad relative to the last absolute pad position +by adding a @code{+} qualifier or to pad relative to the right margin +by using @code{-}. The padding truncates the string if the specified +position lies before the current position. Add the @code{L} qualifier +to change this. +@item < +same as @code{%=} but just do truncation, do not fill with spaces +@item > +mark the current text position for the next truncation. When +screen needs to do truncation, it tries to do it in a way that +the marked position gets moved to the specified percentage of +the output area. (The area starts from the last absolute pad +position and ends with the position specified by the truncation +operator.) The @code{L} qualifier tells screen to mark the truncated +parts with @samp{...}. +@item @{ +attribute/color modifier string terminated by the next @code{@}} +@item ` +Substitute with the output of a `backtick' command. The length +qualifier is misused to identify one of the commands. @xref{Backtick}. +@end table +The @code{c} and @code{C} escape may be qualified with a @code{0} to +make screen use +zero instead of space as fill character. +The @code{n} and +@code{=} escapes understand +a length qualifier (e.g. @code{%3n}), @code{D} and @code{M} can be +prefixed with @code{L} to generate long names, @code{w} and +@code{W} also show the window flags if @code{L} is given. + +An attribute/color modifier is is used to change the attributes or the +color settings. Its format +is @samp{[attribute modifier] [color description]}. The attribute modifier +must be prefixed by a change type indicator if it can be confused with +a color description. The following change types are known: +@table @code +@item + +add the specified set to the current attributes +@item - +remove the set from the current attributes +@item ! +invert the set in the current attributes +@item = +change the current attributes to the specified set +@end table +The attribute set can either be specified as a hexadecimal number or +a combination of the following letters: +@table @code +@item d +dim +@item u +underline +@item b +bold +@item r +reverse +@item s +standout +@item B +blinking +@end table +Colors are coded either as a hexadecimal number or two letters specifying +the desired background and foreground color (in that order). The following +colors are known: +@table @code +@item k +black +@item r +red +@item g +green +@item y +yellow +@item b +blue +@item m +magenta +@item c +cyan +@item w +white +@item d +default color +@item . +leave color unchanged +@end table +The capitalized versions of the letter specify bright colors. You can also +use the pseudo-color @samp{i} to set just the brightness and leave the color +unchanged. + +A one digit/letter color description is treated as foreground or +background color dependent on the current attributes: if reverse mode is +set, the background color is changed instead of the foreground color. +If you don't like this, prefix the color with a @samp{.}. If you want +the same behavior for two-letter color descriptions, also prefix them +with a @samp{.}. + +As a special case, @samp{%@{-@}} restores the attributes and colors that +were set before the last change was made (i.e. pops one level of the +color-change stack). + +@noindent +Examples: +@table @samp +@item G +set color to bright green +@item +b r +use bold red +@item = yd +clear all attributes, write in default color on yellow background. +@item %-Lw%@{= BW@}%50>%n%f* %t%@{-@}%+Lw%< +The available windows centered at the current win dow and truncated to +the available width. The current window is displayed white on blue. +This can be used with @samp{hardstatus alwayslastline}. +@item %?%F%@{.R.@}%?%3n %t%? [%h]%? +The window number and title and the window's hardstatus, if one is set. +Also use a red background if this is the active focus. +Useful for @samp{caption string}. +@end table + + +@node Environment, Files, String Escapes, Top +@chapter Environment Variables +@cindex environment + +@table @code +@item COLUMNS +Number of columns on the terminal (overrides termcap entry). + +@item HOME +Directory in which to look for .screenrc. + +@item LINES +Number of lines on the terminal (overrides termcap entry). + +@item LOCKPRG +Screen lock program. + +@item NETHACKOPTIONS +Turns on @code{nethack} option. + +@item PATH +Used for locating programs to run. + +@item SCREENCAP +For customizing a terminal's @code{TERMCAP} value. + +@item SCREENDIR +Alternate socket directory. + +@item SCREENRC +Alternate user screenrc file. + +@item SHELL +Default shell program for opening windows (default @file{/bin/sh}). +See also @code{shell} .screenrc command. + +@item STY +Alternate socket name. If @code{screen} is invoked, and the environment variable +@code{STY} is set, then it creates only a window in the running @code{screen} +session rather than starting a new session. + +@item SYSSCREENRC +Alternate system screenrc file. + +@item TERM +Terminal name. + +@item TERMCAP +Terminal description. + +@item WINDOW +Window number of a window (at creation time). +@end table + +@node Files, Credits, Environment, Top +@chapter Files Referenced +@cindex files + +@table @file +@item .../screen-4.?.??/etc/screenrc +@itemx .../screen-4.?.??/etc/etcscreenrc +Examples in the @code{screen} distribution package for private and +global initialization files. + +@item @code{$SYSSCREENRC} +@itemx /local/etc/screenrc +@code{screen} initialization commands + +@item @code{$SCREENRC} +@itemx @code{$HOME}/.iscreenrc +@itemx @code{$HOME}/.screenrc +Read in after /local/etc/screenrc + +@item @code{$SCREENDIR}/S-@var{login} + +@item /local/screens/S-@var{login} +Socket directories (default) + +@item /usr/tmp/screens/S-@var{login} +Alternate socket directories. + +@item @var{socket directory}/.termcap +Written by the @code{dumptermcap} command + +@item /usr/tmp/screens/screen-exchange or +@itemx /tmp/screen-exchange +@code{screen} interprocess communication buffer + +@item hardcopy.[0-9] +Screen images created by the hardcopy command + +@item screenlog.[0-9] +Output log files created by the log command + +@item /usr/lib/terminfo/?/* or +@itemx /etc/termcap +Terminal capability databases + +@item /etc/utmp +Login records + +@item @code{$LOCKPRG} +Program for locking the terminal. +@end table + +@node Credits, Bugs, Files, Top +@chapter Credits + +@noindent +Authors @* +======= + +Originally created by Oliver Laumann. For a long time maintained +and developed by Juergen Weigert, Michael Schroeder, Micah Cowan +and Sadrul Habib Chowdhury. This latest version was produced by +Amadeusz Slawinski <amade@@asmblr.net> +and Alexander Naumov <alexander_naumov@@opensuse.org>. + +@noindent +Contributors @* +============ + +@verbatim + Thomas Renninger <treen@suse.com>, + Axel Beckert <abe@deuxchevaux.org>, + 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 <mrg@@eterna.com.au>, + Christopher Williams <cgw@@pobox.com>, + Matt Mosley <mattm@@access.digex.net>, + Gregory Neil Shapiro <gshapiro@@wpi.WPI.EDU>, + Jason Merrill <jason@@jarthur.Claremont.EDU>, + Johannes Zellner <johannes@@zellner.org>, + Pablo Averbuj <pablo@@averbuj.com>. +@end verbatim + +@noindent +Version @* +======= + +This manual describes version @value{version} of the @code{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 @xref{Availability}. + +@node Bugs, Installation, Credits, Top +@chapter Bugs +@cindex bugs + +Just like any other significant piece of software, @code{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 latest screen version. +@end menu + +@node Known Bugs, Reporting Bugs, , Bugs +@section Known Bugs + +@itemize @bullet +@item +@samp{dm} (delete mode) and @samp{xs} are not handled correctly (they +are ignored). @samp{xn} is treated as a magic-margin indicator. + +@item +@code{screen} has no clue about double-high or double-wide characters. +But this is the only area where @code{vttest} is allowed to fail. + +@item +It is not possible to change the environment variable @code{$TERMCAP} +when reattaching under a different terminal type. + +@item +The support of terminfo based systems is very limited. Adding extra +capabilities to @code{$TERMCAP} may not have any effects. + +@item +@code{screen} does not make use of hardware tabs. + +@item +@code{screen} must be installed setuid root on most systems +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 +@file{/etc/utmp}. + +@item +Entries in @file{/etc/utmp} are not removed when @code{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. + +@item +@code{screen} may give a strange warning when your tty has no utmp +entry. + +@item +When the modem line was hung up, @code{screen} may not automatically detach +(or quit) unless the device driver sends a HANGUP signal. To detach such a +@code{screen} session use the -D or -d command line option. + +@item +If a password is set, the command line options -d and -D still detach a +session without asking. + +@item +Both @code{breaktype} and @code{defbreaktype} change the break generating +method used by all terminal devices. The first should change a window +specific setting, where the latter should change only the default for new +windows. + +@item +When attaching to a multiuser session, the user's @file{.screenrc} file is not +sourced. Each users personal settings have to be included in the +@file{.screenrc} file from which the session is booted, or have to be +changed manually. + +@item +A weird imagination is most useful to gain full advantage of all the +features. +@end itemize + +@node Reporting Bugs, Availability, Known Bugs, Bugs +@section Reporting Bugs +@cindex bug report + +If you find a bug in @code{Screen}, please send electronic mail to +@w{@samp{screen-devel@@gnu.org}}. Include the version number +of @code{Screen} which you are using. Also include in your message the +hardware and operating system, the compiler used to compile, a +description of the bug behavior, and the conditions that triggered the +bug. Please recompile @code{screen} with the @samp{-DDEBUG} options +enabled, reproduce the bug, and have a look at the debug output written to +the directory @file{/tmp/debug}. If necessary quote suspect passages from the +debug output and show the contents of your @file{config.h} if it matters. + +@node Availability, , Reporting Bugs, Bugs +@section Availability +@cindex availability + +@code{Screen} is available under the @code{GNU} copyleft. + +The latest official release of @code{screen} available via anonymous +ftp from @samp{prep.ai.mit.edu}, @samp{nic.funet.fi} or any other +@code{GNU} distribution site. The home site of +@code{screen} is @samp{ftp.uni-erlangen.de +(131.188.3.71)}, in the directory @file{pub/utilities/screen}. +The subdirectory @samp{private} contains the latest beta testing release. +If you want to help, send a note to screen-devel@@gnu.org. + +@node Installation, Concept Index, Bugs, Top +@chapter Installation +@cindex installation + +Since @code{screen} uses pseudo-ttys, the select system call, and +UNIX-domain sockets/named pipes, it will not run under a system that +does not include these features of 4.2 and 4.3 BSD UNIX. + +@menu +* Socket Directory:: Where screen stores its handle. +* Compiling Screen:: +@end menu + +@node Socket Directory, +@section Socket Directory +@cindex socket directory + +The socket directory defaults either to @file{$HOME/.screen} or simply to +@file{/tmp/screens} or preferably to @file{/usr/local/screens} chosen at +compile-time. If @code{screen} is installed +setuid root, then the administrator should compile screen with an +adequate (not NFS mounted) @code{SOCKDIR}. If @code{screen} is not +running setuid-root, the user can specify any mode 700 directory in the +environment variable @code{$SCREENDIR}. + +@node Compiling Screen, , Socket Directory, Installation +@section Compiling Screen +@cindex compiling screen + +To compile and install screen: + +The @code{screen} package comes with a @code{GNU Autoconf} configuration +script. Before you compile the package run + +@center @code{sh ./configure} + +This will create a @file{config.h} and @file{Makefile} for your machine. +If @code{configure} fails for some reason, then look at the examples and +comments found in the @file{Makefile.in} and @file{config.h.in} templates. +Rename @file{config.status} to @file{config.status.@var{machine}} when +you want to keep configuration data for multiple architectures. Running +@code{sh ./config.status.@var{machine}} recreates your configuration +significantly faster than rerunning @code{configure}. +@* +Read through the "User Configuration" section of @file{config.h}, and verify +that it suits your needs. +A comment near the top of this section explains why it's best to +install screen setuid to root. +Check for the place for the global @file{screenrc}-file and for the socket +directory. +@* +Check the compiler used in @file{Makefile}, the prefix path where to install +@code{screen}. Then run + +@center @code{make} + +If @code{make} fails to produce one of the files @file{term.h}, @file{comm.h} +or @file{tty.c}, then use @code{@var{filename.x}.dist} instead. +For additional information about installation of @code{screen} refer to the +file @file{INSTALLATION}, coming with this package. + +@node Concept Index, Command Index, Installation, Top +@unnumbered Concept Index + +@printindex cp + +@node Command Index, Keystroke Index, Concept Index, Top +@unnumbered Command Index + +This is a list of all the commands supported by @code{screen}. + +@printindex fn + +@node Keystroke Index, , Command Index, Top +@unnumbered Keystroke Index + +This is a list of the default key bindings. + +The leading escape character (@pxref{Command Character}) has been omitted +from the key sequences, since it is the same for all bindings. + +@printindex ky + +@bye + |