1 \input texinfo @c -*-texinfo-*-
4 @setfilename screen.info
5 @settitle Screen User's Manual
6 @dircategory General Commands
13 * Screen: (screen). Full-screen window manager.
16 @c For examples, use a literal escape in info.
25 This file documents the @code{Screen} virtual terminal manager.
27 Copyright (c) 1993-2003 Free Software Foundation, Inc.
29 Permission is granted to make and distribute verbatim copies of
30 this manual provided the copyright notice and this permission notice
31 are preserved on all copies.
34 Permission is granted to process this file through TeX and print the
35 results, provided the printed document carries copying permission
36 notice identical to this one except for the removal of this paragraph
37 (this paragraph not being relevant to the printed manual).
40 Permission is granted to copy and distribute modified versions of this
41 manual under the conditions for verbatim copying, provided that the entire
42 resulting derived work is distributed under the terms of a permission
43 notice identical to this one.
45 Permission is granted to copy and distribute translations of this manual
46 into another language, under the above conditions for modified versions,
47 except that this permission notice may be stated in a translation approved
53 @subtitle The virtual terminal manager
54 @subtitle for Version @value{version}
58 @vskip 0pt plus 1filll
59 Copyright @copyright{} 1993-2003 Free Software Foundation, Inc.
61 Permission is granted to make and distribute verbatim copies of
62 this manual provided the copyright notice and this permission notice
63 are preserved on all copies.
65 Permission is granted to copy and distribute modified versions of this
66 manual under the conditions for verbatim copying, provided that the entire
67 resulting derived work is distributed under the terms of a permission
68 notice identical to this one.
70 Permission is granted to copy and distribute translations of this manual
71 into another language, under the above conditions for modified versions,
72 except that this permission notice may be stated in a translation approved
79 @node Top, Overview, (dir), (dir)
83 This file documents the @code{Screen} virtual terminal manager, version
88 * Overview:: Preliminary information.
89 * Getting Started:: An introduction to @code{screen}.
90 * Invoking Screen:: Command line options for @code{screen}.
91 * Customization:: The @file{.screenrc} file.
92 * Commands:: List all of the commands.
93 * New Window:: Running a program in a new window.
94 * Selecting:: Selecting a window to display.
95 * Session Management:: Suspend/detach, grant access, connect sessions.
96 * Regions:: Split-screen commands.
97 * Window Settings:: Titles, logging, etc.
98 * Virtual Terminal:: Controlling the @code{screen} VT100 emulation.
99 * Copy and Paste:: Exchanging text between windows and sessions.
100 * Subprocess Execution:: I/O filtering with @code{exec}.
101 * Key Binding:: Binding commands to keys.
102 * Flow Control:: Trap or pass flow control characters.
103 * Termcap:: Tweaking your terminal's termcap entry.
104 * Message Line:: The @code{screen} message line.
105 * Logging:: Keeping a record of your session.
106 * Startup:: Functions only useful at @code{screen} startup.
107 * Miscellaneous:: Various other commands.
108 * String Escapes:: Inserting current information into strings
109 * Environment:: Environment variables used by @code{screen}.
110 * Files:: Files used by @code{screen}.
111 * Credits:: Who's who of @code{screen}.
112 * Bugs:: What to do if you find a bug.
113 * Installation:: Getting @code{screen} running on your system.
114 * Concept Index:: Index of concepts.
115 * Command Index:: Index of all @code{screen} commands.
116 * Keystroke Index:: Index of default key bindings.
119 @node Overview, Getting Started, Top, Top
123 Screen is a full-screen window manager that multiplexes a physical
124 terminal between several processes, typically interactive shells. Each
125 virtual terminal provides the functions of the DEC VT100 terminal and,
126 in addition, several control functions from the ISO 6429 (ECMA 48, ANSI X3.64)
127 and ISO 2022 standards (e.g. insert/delete line and support for multiple
128 character sets). There is a scrollback history buffer for each virtual
129 terminal and a copy-and-paste mechanism that allows the user to move
130 text regions between windows.
132 When @code{screen} is called, it creates a single window with a shell in
133 it (or the specified command) and then gets out of your way so that you
134 can use the program as you normally would. Then, at any time, you can
135 create new (full-screen) windows with other programs in them (including
136 more shells), kill the current window, view a list of the active
137 windows, turn output logging on and off, copy text between windows, view
138 the scrollback history, switch between windows, etc. All windows run
139 their programs completely independent of each other. Programs continue
140 to run when their window is currently not visible and even when the
141 whole screen session is detached from the user's terminal.
143 When a program terminates, @code{screen} (per default) kills the window
144 that contained it. If this window was in the foreground, the display
145 switches to the previously displayed window; if none are left,
148 Everything you type is sent to the program running in the current
149 window. The only exception to this is the one keystroke that is used to
150 initiate a command to the window manager. By default, each command
151 begins with a control-a (abbreviated @kbd{C-a} from now on), and is
152 followed by one other keystroke. The command character (@pxref{Command
153 Character}) and all the key bindings (@pxref{Key Binding}) can be fully
154 customized to be anything you like, though they are always two
155 characters in length.
157 @code{Screen} does not understand the prefix @kbd{C-} to mean control.
158 Please use the caret notation (@kbd{^A} instead of @kbd{C-a}) as arguments
159 to e.g. the @code{escape} command or the @code{-e} option. @code{Screen}
160 will also print out control characters in caret notation.
162 The standard way to create a new window is to type @kbd{C-a c}. This
163 creates a new window running a shell and switches to that window
164 immediately, regardless of the state of the process running in the
165 current window. Similarly, you can create a new window with a custom
166 command in it by first binding the command to a keystroke (in your
167 @file{.screenrc} file or at the @kbd{C-a :} command line) and then using it
168 just like the @kbd{C-a c} command. In addition, new windows can be created by
169 running a command like:
176 from a shell prompt within a previously created window. This will not
177 run another copy of @code{screen}, but will instead supply the command
178 name and its arguments to the window manager (specified in the $STY environment
179 variable) who will use it to create the new window. The above example would
180 start the @code{emacs} editor (editing @file{prog.c}) and switch to its window.
181 - Note that you cannot transport environment variables from
182 the invoking shell to the application (emacs in this case), because it is
183 forked from the parent screen process, not from the invoking shell.
185 If @file{/etc/utmp} is writable by @code{screen}, an appropriate record
186 will be written to this file for each window, and removed when the
187 window is closed. This is useful for working with @code{talk},
188 @code{script}, @code{shutdown}, @code{rsend}, @code{sccs} and other
189 similar programs that use the utmp file to determine who you are. As
190 long as @code{screen} is active on your terminal, the terminal's own
191 record is removed from the utmp file. @xref{Login}.
193 @node Getting Started, Invoking Screen, Overview, Top
194 @chapter Getting Started
197 Before you begin to use @code{screen} you'll need to make sure you have
198 correctly selected your terminal type, just as you would for any other
199 termcap/terminfo program. (You can do this by using @code{tset},
200 @code{qterm}, or just @code{set term=mytermtype}, for example.)
202 If you're impatient and want to get started without doing a lot more
203 reading, you should remember this one command: @kbd{C-a ?} (@pxref{Key
204 Binding}). Typing these two characters will display a list of the
205 available @code{screen} commands and their bindings. Each keystroke is
206 discussed in the section on keystrokes (@pxref{Default Key Bindings}).
207 Another section (@pxref{Customization}) deals with the contents of your
210 If your terminal is a ``true'' auto-margin terminal (it doesn't allow
211 the last position on the screen to be updated without scrolling the
212 screen) consider using a version of your terminal's termcap that has
213 automatic margins turned @emph{off}. This will ensure an accurate
214 and optimal update of the screen in all circumstances. Most terminals
215 nowadays have ``magic'' margins (automatic margins plus usable last
216 column). This is the VT100 style type and perfectly suited for
218 If all you've got is a ``true'' auto-margin terminal @code{screen}
219 will be content to use it, but updating a character put into the last
220 position on the screen may not be possible until the screen scrolls or
221 the character is moved into a safe position in some other way. This
222 delay can be shortened by using a terminal with insert-character
225 @xref{Special Capabilities}, for more information about telling
226 @code{screen} what kind of terminal you have.
228 @node Invoking Screen, Customization, Getting Started, Top
229 @chapter Invoking @code{Screen}
232 @cindex command line options
234 Screen has the following command-line options:
238 Include @emph{all} capabilities (with some minor exceptions) in each
239 window's termcap, even if @code{screen} must redraw parts of the display
240 in order to implement a function.
243 Adapt the sizes of all windows to the size of the display. By default,
244 @code{screen} may try to restore its old window sizes when attaching to
245 resizable terminals (those with @samp{WS} in their descriptions, e.g.
246 @code{suncmd} or some varieties of @code{xterm}).
249 Use @var{file} as the user's configuration file instead of the default
250 of @file{$HOME/.screenrc}.
252 @item -d [@var{pid.sessionname}]
253 @itemx -D [@var{pid.sessionname}]
254 Do not start @code{screen}, but instead detach a @code{screen} session
255 running elsewhere (@pxref{Detach}). @samp{-d} has the same effect as
256 typing @kbd{C-a d} from the controlling terminal for the session.
257 @samp{-D} is the equivalent to the power detach key. If no session can
258 be detached, this option is ignored. In combination with the
259 @code{-r}/@code{-R} option more powerful effects can be achieved:
263 Reattach a session and if necessary detach it first.
265 Reattach a session and if necessary detach or even create it first.
267 Reattach a session and if necessary detach or create it.
268 Use the first session if more than one session is available.
270 Reattach a session. If necessary detach and logout remotely first.
272 Attach here and now. In detail this means: If a session is running,
273 then reattach. If necessary detach and logout remotely first. If it
274 was not running create it and notify the user.
275 This is the author's favorite.
277 Attach here and now. Whatever that means, just do it.
280 @emph{Note}: It is a good idea to check the status of your sessions
281 with @code{screen -list} before using this option.
284 Set the command character to @var{x}, and the character generating a
285 literal command character (when typed after the command character) to
286 @var{y}. The defaults are @kbd{C-a} and @kbd{a}, which can be specified
287 as @samp{-e^Aa}. When creating a @code{screen} session, this option
288 sets the default command character. In a multiuser session all users
289 added will start off with this command character. But when attaching
290 to an already running session, this option only changes the command
291 character of the attaching user.
292 This option is equivalent to the commands @code{defescape} or
293 @code{escape} respectively. (@pxref{Command Character}).
298 Set flow-control to on, off, or automatic switching mode, respectively.
299 This option is equivalent to the @code{defflow} command (@pxref{Flow
303 Set the history scrollback buffer to be @var{num} lines high.
304 Equivalent to the @code{defscrollback} command (@pxref{Copy}).
307 Cause the interrupt key (usually @kbd{C-c}) to interrupt the display
308 immediately when flow control is on. This option is equivalent to the
309 @code{interrupt} argument to the @code{defflow} command (@pxref{Flow
310 Control}). Its use is discouraged.
314 Turn login mode on or off (for @file{/etc/utmp} updating). This option
315 is equivalent to the @code{deflogin} command (@pxref{Login}).
317 @item -ls [@var{match}]
318 @itemx -list [@var{match}]
319 Do not start @code{screen}, but instead print a list of session
320 identification strings (usually of the form @var{pid.tty.host};
321 @pxref{Session Name}). Sessions marked @samp{detached} can be resumed
322 with @code{screen -r}. Those marked @samp{attached} are running and
323 have a controlling terminal. If the session runs in multiuser mode,
324 it is marked @samp{multi}. Sessions marked as @samp{unreachable} either
325 live on a different host or are dead.
326 An unreachable session is considered dead, when its name matches either the
327 name of the local host, or the specified parameter, if any.
328 See the @code{-r} flag for a description how to construct matches.
329 Sessions marked as @samp{dead} should be thoroughly checked and removed.
330 Ask your system administrator if you are not sure.
331 Remove sessions with the @samp{-wipe} option.
334 Tell @code{screen} to turn on automatic output logging for the
338 Tell @code{screen} to ignore the @code{$STY} environment variable. When
339 this option is used, a new session will always be created, regardless of
340 whether @code{screen} is being called from within another @code{screen}
341 session or not. This flag has a special meaning in connection
342 with the @samp{-d} option:
345 Start @code{screen} in @emph{detached} mode. This creates a new
346 session but doesn't attach to it. This is useful for system startup
349 This also starts @code{screen} in @emph{detached} mode, but doesn't fork
350 a new process. The command exits if the session terminates.
354 Select a more optimal output mode for your terminal rather than true VT100
355 emulation (only affects auto-margin terminals without @samp{LP}). This
356 can also be set in your @file{.screenrc} by specifying @samp{OP} in the
357 @code{termcap} command.
359 @item -p @var{name_or_number}|-|=|+
360 Preselect a window. This is useful when you want to reattach to a
361 specific window or you want to send a command via the @samp{-X}
362 option to a specific window. As with screen's select command, @samp{-}
363 selects the blank window. As a special case for reattach, @samp{=}
364 brings up the windowlist on the blank window, while a @samp{+} will
365 create new window. The command will not be executed if the specified
366 window could not be found.
369 Suppress printing of error messages. In combination with @samp{-ls} the exit
370 value is set as follows: 9 indicates a directory without sessions. 10
371 indicates a directory with running but not attachable sessions. 11 (or more)
372 indicates 1 (or more) usable sessions.
373 In combination with @samp{-r} the exit value is as follows: 10 indicates that
374 there is no session to resume. 12 (or more) indicates that there are 2 (or
375 more) sessions to resume and you should specify which one to choose.
376 In all other cases @samp{-q} has no effect.
379 Some commands now can be queried from a remote session using this
380 flag, e.g. 'screen -Q windows'. The commands will send the
381 response to the stdout of the querying process. If there was an
382 error in the command, then the querying process will exit with
385 The commands that can be queried now are:
395 @item -r [@var{pid.sessionname}]
396 @itemx -r @var{sessionowner}/[@var{pid.sessionname}]
397 Resume a detached @code{screen} session. No other options (except
398 combinations with @samp{-d} or @samp{-D}) may be specified, though
400 (@pxref{Session Name}) may be needed to distinguish between multiple
401 detached @code{screen} sessions.
402 The second form is used to connect to another user's screen session which
403 runs in multiuser mode. This indicates that screen should look for
404 sessions in another user's directory. This requires setuid-root.
407 Resume the first appropriate detached @code{screen} session. If
408 successful, all other command-line options are ignored. If no detached
409 session exists, start a new session using the specified options, just as
410 if @samp{-R} had not been specified. This option is set by default if
411 screen is run as a login-shell (actually screen uses @samp{-xRR} in
413 For combinations with the
414 @samp{-D}/@samp{-d} option see there.
416 @item -s @var{program}
417 Set the default shell to be @var{program}. By default, @code{screen}
418 uses the value of the environment variable @code{$SHELL}, or
419 @file{/bin/sh} if it is not defined. This option is equivalent to the
420 @code{shell} command (@pxref{Shell}).
422 @item -S @var{sessionname}
423 Set the name of the new session to @var{sessionname}. This option can
424 be used to specify a meaningful name for the session in place of the
425 default @var{tty.host} suffix. This name identifies the session for the
426 @code{screen -list} and @code{screen -r} commands. This option is
427 equivalent to the @code{sessionname} command (@pxref{Session Name}).
430 Set the title (name) for the default shell or specified program.
431 This option is equivalent to the @code{shelltitle} command
435 Set the $TERM enviroment varible using the spcified @emph{term} as
436 opposed to the defualt setting of @code{screen}.
439 Run screen in UTF-8 mode. This option tells screen that your terminal
440 sends and understands UTF-8 encoded characters. It also sets the default
441 encoding for new windows to @samp{utf8}.
444 Print the version number.
446 @item -wipe [@var{match}]
447 List available screens like @code{screen -ls}, but remove destroyed
448 sessions instead of marking them as @samp{dead}.
449 An unreachable session is considered dead, when its name matches either
450 the name of the local host, or the explicitly given parameter, if any.
451 See the @code{-r} flag for a description how to construct matches.
454 Attach to a session which is already attached elsewhere (multi-display
456 @code{Screen} refuses to attach from within itself.
457 But when cascading multiple screens, loops are not detected; take care.
461 Send the specified command to a running screen session. You can use
462 the @code{-d} or @code{-r} option to tell screen to look only for
463 attached or detached screen sessions. Note that this command doesn't
464 work if the session is password protected.
468 @node Customization, Commands, Invoking Screen, Top
469 @chapter Customizing @code{Screen}
470 @cindex customization
472 You can modify the default settings for @code{screen} to fit your tastes
473 either through a personal @file{.screenrc} file which contains commands
474 to be executed at startup, or on the fly using the @code{colon} command.
477 * Startup Files:: The @file{.screenrc} file.
478 * Source:: Read commands from a file.
479 * Colon:: Entering customization commands interactively.
482 @node Startup Files, Source, , Customization
483 @section The @file{.screenrc} file
486 When @code{screen} is invoked, it executes initialization commands from
487 the files @file{.screenrc} in the user's home directory and
488 @file{/usr/local/etc/screenrc}. These defaults can be overridden in the
490 For the global screenrc file @code{screen} searches for the environment
491 variable @code{$SYSSCREENRC} (this override feature may be disabled at
492 compile-time). The user specific screenrc file is
493 searched for in @code{$SCREENRC}, then
494 @file{@code{$HOME}/.screenrc}. The command line option @samp{-c}
495 specifies which file to use (@pxref{Invoking Screen}. Commands in these
496 files are used to set options, bind commands to keys, and to
497 automatically establish one or more windows at the beginning of
498 your @code{screen} session. Commands are listed one per line, with
499 empty lines being ignored. A command's arguments are separated by tabs
500 or spaces, and may be surrounded by single or double quotes. A @samp{#}
501 turns the rest of the line into a comment, except in quotes.
502 Unintelligible lines are warned about and ignored. Commands may contain
503 references to environment variables. The syntax is the shell-like
504 @code{$VAR} or @code{$@{VAR@}}. Note that this causes incompatibility
505 with previous @code{screen} versions, as now the '$'-character has to be
506 protected with '\' if no variable substitution is intended. A string in
507 single-quotes is also protected from variable substitution.
509 Two configuration files are shipped as examples with your screen
510 distribution: @file{etc/screenrc} and @file{etc/etcscreenrc}. They
511 contain a number of useful examples for various commands.
513 @node Source, Colon, Startup Files, Customization
515 @deffn Command source file
517 Read and execute commands from file @var{file}. Source commands
518 may be nested to a maximum recursion level of ten. If @var{file}
519 is not an absolute path and screen is already processing a
520 source command, the parent directory of the running source
521 command file is used to search for the new command file before
522 screen's current directory.
524 Note that termcap/terminfo/termcapinfo commands only work
525 at startup and reattach time, so they must be reached via
526 the default screenrc files to have an effect.
529 @node Colon, , Source, Customization
531 Customization can also be done online, with this command:
536 Allows you to enter @file{.screenrc} command lines. Useful for
537 on-the-fly modification of key bindings, specific window creation and
538 changing settings. Note that the @code{set} keyword no longer exists,
539 as of version 3.3. Change default settings with commands starting with
540 @samp{def}. You might think of this as the @code{ex} command mode of
541 @code{screen}, with @code{copy} as its @code{vi} command mode
542 (@pxref{Copy and Paste}).
545 @node Commands, New Window, Customization, Top
548 A command in @code{screen} can either be bound to a key, invoked from a
549 screenrc file, or called from the @code{colon} prompt
550 (@pxref{Customization}). As of version 3.3, all commands can be bound
551 to keys, although some may be less useful than others.
552 For a number of real life working examples of the most important
553 commands see the files @file{etc/screenrc} and @file{etc/etcscreenrc}
554 of your screen distribution.
556 In this manual, a command definition looks like this:
559 @item -- Command: command [-n] ARG1 [ARG2] @dots{}
560 (@var{keybindings})@*
561 This command does something, but I can't remember what.
564 An argument in square brackets (@samp{[]}) is optional. Many commands
565 take an argument of @samp{on} or @samp{off}, which is indicated as
566 @var{state} in the definition.
569 * Default Key Bindings:: @code{screen} keyboard commands.
570 * Command Summary:: List of all commands.
573 @node Default Key Bindings, Command Summary, , Commands
574 @section Default Key Bindings
576 As mentioned previously, each keyboard command consists of a
577 @kbd{C-a} followed by one other character. For your convenience, all
578 commands that are bound to lower-case letters are also bound to their
579 control character counterparts (with the exception of @kbd{C-a a}; see
580 below). Thus, both @kbd{C-a c} and @kbd{C-a C-c} can be used to create
583 The following table shows the default key bindings:
588 Prompt for a window identifier and switch.
593 Present a list of all windows for selection.
596 @item @kbd{C-a 0@dots{}9, -}
597 (select 0@dots{}select 9, select -)@*
598 Switch to window number 0@dots{}9, or the blank window.
601 @item @kbd{C-a @key{Tab}}
603 Switch the input focus to the next region. @xref{Regions}.
607 Toggle to the window displayed previously. If this window does no
608 longer exist, @code{other} has the same effect as @code{next}.
613 Send the command character (C-a) to window. See @code{escape} command.
614 @xref{Command Character}.
618 Allow the user to enter a title for the current window.
619 @xref{Naming Windows}.
624 Send a break to the tty.
629 Close and reopen the tty-line.
635 Create a new window with a shell and switch to that window.
636 @xref{Screen Command}.
640 Clear the screen. @xref{Clear}.
645 Detach @code{screen} from this terminal. @xref{Detach}.
649 Detach and logout. @xref{Power Detach}.
654 Cycle flow among @samp{on}, @samp{off} or @samp{auto}. @xref{Flow}.
658 Resize the window to the current region size. @xref{Fit}.
662 Toggle visual bell mode. @xref{Bell}.
666 Write a hardcopy of the current window to the file ``hardcopy.@var{n}''.
671 Toggle logging of the current window to the file ``screenlog.@var{n}''.
677 Show info about the current window. @xref{Info}.
682 Destroy the current window. @xref{Kill}.
687 Fully refresh the current window. @xref{Redisplay}.
691 Toggle the current window's login state. @xref{Login}.
696 Repeat the last message displayed in the message line.
701 Toggle monitoring of the current window. @xref{Monitor}.
703 @item @kbd{C-a @key{SPC}}
707 Switch to the next window. @xref{Selecting}.
711 Show the number (and title) of the current window. @xref{Number}.
716 @itemx @kbd{C-a @key{BackSpace}}
718 Switch to the previous window (opposite of @kbd{C-a n}).
724 Send a ^Q (ASCII XON) to the current window. @xref{XON/XOFF}.
728 Delete all regions but the current one. @xref{Regions}.
733 Toggle the current window's line-wrap setting (turn the current window's
734 automatic margins on or off). @xref{Wrap}.
739 Send a ^S (ASCII XOFF) to the current window. @xref{XON/XOFF}.
743 Split the current region horizontally into two new ones. @xref{Regions}.
748 Show the load average and xref. @xref{Time}.
752 Display the version and compilation date. @xref{Version}.
756 Enter digraph. @xref{Digraph}.
761 Show a list of active windows. @xref{Windows}.
765 Toggle between 80 and 132 columns. @xref{Window Size}.
770 Lock your terminal. @xref{Lock}.
774 Kill the current region. @xref{Regions}.
779 Suspend @code{screen}. @xref{Suspend}.
783 Reset the virtual terminal to its ``power-on'' values.
788 Write out a @file{.termcap} file. @xref{Dump Termcap}.
792 Show key bindings. @xref{Help}.
796 Kill all windows and terminate @code{screen}. @xref{Quit}.
800 Enter a command line. @xref{Colon}.
804 @itemx @kbd{C-a @key{ESC}}
806 Enter copy/scrollback mode. @xref{Copy}.
811 Write the contents of the paste buffer to the stdin queue of the
812 current window. @xref{Paste}.
817 Copy and paste a previous (command) line. @xref{History}.
821 Write the paste buffer out to the screen-exchange file.
822 @xref{Screen Exchange}.
826 Read the screen-exchange file into the paste buffer.
827 @xref{Screen Exchange}.
831 Delete the screen-exchange file. @xref{Screen Exchange}.
835 Start/stop monitoring the current window for inactivity. @xref{Monitor}.
839 Split the current region vertically into two new ones. @xref{Regions}.
843 Show the copyright page. @xref{License}.
847 Show the listing of attached displays. @xref{Displays}.
850 @node Command Summary, , Default Key Bindings, Commands
851 @section Command Summary
852 @cindex command summary
855 @item acladd @var{usernames}
856 Allow other users in this session. @xref{Multiuser Session}.
857 @item aclchg @var{usernames permbits list}
858 Change a user's permissions. @xref{Multiuser Session}.
859 @item acldel @var{username}
860 Disallow other user in this session. @xref{Multiuser Session}.
861 @item aclgrp @var{usrname} [@var{groupname}]
862 Inherit permissions granted to a group leader. @xref{Multiuser Session}.
863 @item aclumask [@var{users}]+/-@var{bits} ...
864 Predefine access to new windows. @xref{Umask}.
865 @item activity @var{message}
866 Set the activity notification message. @xref{Monitor}.
867 @item addacl @var{usernames}
868 Synonym to @code{acladd}. @xref{Multiuser Session}.
869 @item allpartial @var{state}
870 Set all windows to partial refresh. @xref{Redisplay}.
871 @item altscreen @var{state}
872 Enables support for the "alternate screen" terminal capability. @xref{Redisplay}.
873 @item at [@var{ident}][@kbd{#}@var{|}@kbd{*}@var{|}@kbd{%}] @var{command} [@var{args}]
874 Execute a command at other displays or windows. @xref{At}.
875 @item attrcolor @var{attrib} [@var{attribute/color-modifier}]
876 Map attributes to colors. @xref{Attrcolor}.
877 @item autodetach @var{state}
878 Automatically detach the session on SIGHUP. @xref{Detach}.
879 @item autonuke @var{state}
880 Enable a clear screen to discard unwritten output. @xref{Autonuke}.
881 @item backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}]
882 Define a command for the backtick string escape. @xref{Backtick}.
883 @item bce [@var{state}]
884 Change background color erase. @xref{Character Processing}.
885 @item bell_msg [@var{message}]
886 Set the bell notification message. @xref{Bell}.
887 @item bind [-c @var{class}] @var{key} [@var{command} [@var{args}]]
888 Bind a command to a key. @xref{Bind}.
889 @item bindkey [@var{opts}] [@var{string} [@var{cmd args}]]
890 Bind a string to a series of keystrokes. @xref{Bindkey}.
892 Blank the screen. @xref{Screen Saver}.
894 Define a blanker program. @xref{Screen Saver}.
895 @item break [@var{duration}]
896 Send a break signal to the current window. @xref{Break}.
897 @item breaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}]
898 Specify how to generate breaks. @xref{Break}.
899 @item bufferfile [@var{exchange-file}]
900 Select a file for screen-exchange. @xref{Screen Exchange}.
901 @item c1 [@var{state}]
902 Change c1 code processing. @xref{Character Processing}.
903 @item caption @var{mode} [@var{string}]
904 Change caption mode and string. @xref{Regions}.
905 @item chacl @var{usernames permbits list}
906 Synonym to @code{aclchg}. @xref{Multiuser Session}.
907 @item charset @var{set}
908 Change character set slot designation. @xref{Character Processing}.
909 @item chdir [@var{directory}]
910 Change the current directory for future windows. @xref{Chdir}.
912 Clear the window screen. @xref{Clear}.
914 Enter a @code{screen} command. @xref{Colon}.
915 @item command [-c @var{class}]
916 Simulate the screen escape key. @xref{Command Character}.
917 @item compacthist [@var{state}]
918 Selects compaction of trailing empty lines. @xref{Scrollback}.
919 @item console [@var{state}]
920 Grab or ungrab console output. @xref{Console}.
922 Enter copy mode. @xref{Copy}.
923 @item copy_reg [@var{key}]
924 Removed. Use @code{paste} instead. @xref{Registers}.
925 @item crlf @var{state}
926 Select line break behavior for copying. @xref{Line Termination}.
927 @item debug @var{state}
928 Suppress/allow debugging output. @xref{Debug}.
929 @item defautonuke @var{state}
930 Select default autonuke behavior. @xref{Autonuke}.
931 @item defbce @var{state}
932 Select background color erase. @xref{Character Processing}.
933 @item defbreaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}]
934 Specify the default for generating breaks. @xref{Break}.
935 @item defc1 @var{state}
936 Select default c1 processing behavior. @xref{Character Processing}.
937 @item defcharset [@var{set}]
938 Change defaul character set slot designation. @xref{Character Processing}.
939 @item defencoding @var{enc}
940 Select default window encoding. @xref{Character Processing}.
941 @item defescape @var{xy}
942 Set the default command and @code{meta} characters. @xref{Command Character}.
943 @item defflow @var{fstate}
944 Select default flow control behavior. @xref{Flow}.
945 @item defgr @var{state}
946 Select default GR processing behavior. @xref{Character Processing}.
947 @item defhstatus [@var{status}]
948 Select default window hardstatus line. @xref{Hardstatus}.
949 @item deflog @var{state}
950 Select default window logging behavior. @xref{Log}.
951 @item deflogin @var{state}
952 Select default utmp logging behavior. @xref{Login}.
953 @item defmode @var{mode}
954 Select default file mode for ptys. @xref{Mode}.
955 @item defmonitor @var{state}
956 Select default activity monitoring behavior. @xref{Monitor}.
957 @item defmousetrack @var{on}|@var{off}
958 Select the default mouse tracking behavior. @xref{Mousetrack}.
959 @item defnonblock @var{state}|@var{numsecs}
960 Select default nonblock mode. @xref{Nonblock}.
961 @item defobuflimit @var{limit}
962 Select default output buffer limit. @xref{Obuflimit}.
963 @item defscrollback @var{num}
964 Set default lines of scrollback. @xref{Scrollback}.
965 @item defshell @var{command}
966 Set the default program for new windows. @xref{Shell}.
967 @item defsilence @var{state}
968 Select default idle monitoring behavior. @xref{Monitor}.
969 @item defslowpaste @var{msec}
970 Select the default inter-character timeout when pasting. @xref{Paste}.
971 @item defutf8 @var{state}
972 Select default character encoding. @xref{Character Processing}.
973 @item defwrap @var{state}
974 Set default line-wrapping behavior. @xref{Wrap}.
975 @item defwritelock @var{on|off|auto}
976 Set default writelock behavior. @xref{Multiuser Session}.
977 @item defzombie [@var{keys}]
978 Keep dead windows. @xref{Zombie}.
980 Disconnect @code{screen} from the terminal. @xref{Detach}.
981 @item digraph [@var{preset} [@var{unicode-value}]]
982 Enter a digraph sequence. @xref{Digraph}.
984 Display terminal information. @xref{Info}.
986 List currently active user interfaces. @xref{Displays}.
988 Write the window's termcap entry to a file. @xref{Dump Termcap}.
989 @item echo [-n] @var{message}
990 Display a message on startup. @xref{Startup}.
991 @item encoding @var{enc} [@var{denc}]
992 Set the encoding of a window. @xref{Character Processing}.
993 @item escape @var{xy}
994 Set the command and @code{meta} characters. @xref{Command Character}.
995 @item eval @var{command1} [@var{command2} ...]
996 Parse and execute each argument. @xref{Eval}.
997 @item exec [[@var{fdpat}] @var{command} [@var{args} ...]]
998 Run a subprocess (filter). @xref{Exec}.
1000 Change window size to current display size. @xref{Window Size}.
1001 @item flow [@var{fstate}]
1002 Set flow control behavior. @xref{Flow}.
1004 Move focus to next region. @xref{Regions}.
1006 Force the current region to a certain size. @xref{Focusminsize}.
1007 @item gr [@var{state}]
1008 Change GR charset processing. @xref{Character Processing}.
1009 @item group [@var{grouptitle}]
1010 Change or show the group the current window belongs to. @xref{Window Groups}.
1011 @item hardcopy [-h] [@var{file}]
1012 Write out the contents of the current window. @xref{Hardcopy}.
1013 @item hardcopy_append @var{state}
1014 Append to hardcopy files. @xref{Hardcopy}.
1015 @item hardcopydir @var{directory}
1016 Place, where to dump hardcopy files. @xref{Hardcopy}.
1017 @item hardstatus [@var{state}]
1018 Use the hardware status line. @xref{Hardware Status Line}.
1019 @item height [@var{lines} [@var{cols}]]
1020 Set display height. @xref{Window Size}.
1021 @item help [-c @var{class}]
1022 Display current key bindings. @xref{Help}.
1024 Find previous command beginning @dots{}. @xref{History}.
1025 @item hstatus @var{status}
1026 Change the window's hardstatus line. @xref{Hardstatus}.
1027 @item idle [@var{timeout} [@var{cmd} @var{args}]]
1028 Define a screen saver command. @xref{Screen Saver}.
1029 @item ignorecase [@var{state}]
1030 Ignore character case in searches. @xref{Searching}.
1032 Display window settings. @xref{Info}.
1033 @item ins_reg [@var{key}]
1034 Removed, use @code{paste} instead. @xref{Registers}.
1036 Destroy the current window. @xref{Kill}.
1038 Redisplay the last message. @xref{Last Message}.
1039 @item layout new [@var{title}]
1040 Create a layout. @xref{Layout}.
1041 @item layout remove [@var{n}|@var{title}]
1042 Delete a layout. @xref{Layout}.
1044 Select the next layout. @xref{Layout}.
1046 Select the previous layout. @xref{Layout}.
1047 @item layout select [@var{n}|@var{title}]
1048 Jump to a layout. @xref{Layout}.
1050 List the available layouts. @xref{Layout}.
1051 @item layout title [@var{title}]
1052 Show or set the title of a layout. @xref{Layout}.
1053 @item layout number [@var{n}]
1054 Show or set the number of a layout. @xref{Layout}.
1055 @item layout attach [@var{title}|:last]
1056 Show or set which layout to reattach to. @xref{Layout}.
1057 @item layout save [@var{n}|@var{title}]
1058 Remember the organization of a layout. @xref{Layout}.
1059 @item layout autosave [@var{on}|@var{off}]
1060 Show or set the status of layout saving. @xref{Layout}.
1061 @item layout dump [filename]
1062 Save the layout arrangement to a file. @xref{Layout}.
1064 Display licensing information. @xref{Startup}.
1066 Lock the controlling terminal. @xref{Lock}.
1067 @item log [@var{state}]
1068 Log all output in the current window. @xref{Log}.
1069 @item logfile @var{filename}
1070 Place where to collect logfiles. @xref{Log}.
1071 @item login [@var{state}]
1072 Log the window in @file{/etc/utmp}. @xref{Login}.
1073 @item logtstamp [@var{state}]
1074 Configure logfile time-stamps. @xref{Log}.
1076 Use only the default mapping table for the next keystroke. @xref{Bindkey Control}.
1078 Don't try to do keymapping on the next keystroke. @xref{Bindkey Control}.
1079 @item maptimeout @var{n}
1080 Set the inter-character timeout used for keymapping. @xref{Bindkey Control}.
1081 @item markkeys @var{string}
1082 Rebind keys in copy mode. @xref{Copy Mode Keys}.
1083 @item maxwin @var{n}
1084 Set the maximum window number. @xref{Maxwin}.
1086 Insert the command character. @xref{Command Character}.
1087 @item monitor [@var{state}]
1088 Monitor activity in window. @xref{Monitor}.
1089 @item mousetrack [@var{on}|@var{off}]
1090 Enable selecting split regions with mouse clicks. @xref{Mousetrack}.
1091 @item msgminwait @var{sec}
1092 Set minimum message wait. @xref{Message Wait}.
1093 @item msgwait @var{sec}
1094 Set default message wait. @xref{Message Wait}.
1095 @item multiuser @var{state}
1096 Go into single or multi user mode. @xref{Multiuser Session}.
1097 @item nethack @var{state}
1098 Use @code{nethack}-like error messages. @xref{Nethack}.
1100 Switch to the next window. @xref{Selecting}.
1101 @item nonblock [@var{state}|@var{numsecs}]
1102 Disable flow control to the current display. @xref{Nonblock}.|@var{numsecs}]
1103 @item number [@var{n}]
1104 Change/display the current window's number. @xref{Number}.
1105 @item obuflimit [@var{limit}]
1106 Select output buffer limit. @xref{Obuflimit}.
1108 Kill all other regions. @xref{Regions}.
1110 Switch to the window you were in last. @xref{Selecting}.
1111 @item partial @var{state}
1112 Set window to partial refresh. @xref{Redisplay}.
1113 @item password [@var{crypted_pw}]
1114 Set reattach password. @xref{Detach}.
1115 @item paste [@var{src_regs} [@var{dest_reg}]]
1116 Paste contents of paste buffer or registers somewhere. @xref{Paste}.
1117 @item pastefont [@var{state}]
1118 Include font information in the paste buffer. @xref{Paste}.
1120 Close and Reopen the window's terminal. @xref{Break}.
1122 Detach and hang up. @xref{Power Detach}.
1123 @item pow_detach_msg [@var{message}]
1124 Set message displayed on @code{pow_detach}. @xref{Power Detach}.
1126 Switch to the previous window. @xref{Selecting}.
1127 @item printcmd [@var{cmd}]
1128 Set a command for VT100 printer port emulation. @xref{Printcmd}.
1129 @item process [@var{key}]
1130 Treat a register as input to @code{screen}. @xref{Registers}.
1132 Kill all windows and exit. @xref{Quit}.
1133 @item readbuf [-e @var{encoding}] [@var{filename}]
1134 Read the paste buffer from the screen-exchange file. @xref{Screen Exchange}.
1135 @item readreg [-e @var{encoding}] [@var{reg} [@var{file}]]
1136 Load a register from paste buffer or file. @xref{Registers}.
1138 Redisplay the current window. @xref{Redisplay}.
1139 @item register [-e @var{encoding}] @var{key} @var{string}
1140 Store a string to a register. @xref{Registers}.
1142 Kill current region. @xref{Regions}.
1144 Delete the screen-exchange file. @xref{Screen Exchange}.
1145 @item rendition bell | monitor | silence | so @var{attr} [@var{color}]
1146 Change text attributes in caption for flagged windows. @xref{Rendition}.
1148 Reset the terminal settings for the window. @xref{Reset}.
1149 @item resize [(+/-)lines]
1150 Grow or shrink a region
1151 @item screen [@var{opts}] [@var{n}] [@var{cmd} [@var{args}] | //group]
1152 Create a new window. @xref{Screen Command}.
1153 @item scrollback @var{num}
1154 Set size of scrollback buffer. @xref{Scrollback}.
1155 @item select [@var{n}|-|.]
1156 Switch to a specified window. @xref{Selecting}.
1157 @item sessionname [@var{name}]
1158 Name this session. @xref{Session Name}.
1159 @item setenv [@var{var} [@var{string}]]
1160 Set an environment variable for new windows. @xref{Setenv}.
1161 @item setsid @var{state}
1162 Controll process group creation for windows. @xref{Setsid}.
1163 @item shell @var{command}
1164 Set the default program for new windows. @xref{Shell}.
1165 @item shelltitle @var{title}
1166 Set the default name for new windows. @xref{Shell}.
1167 @item silence [@var{state}|@var{seconds}]
1168 Monitor a window for inactivity. @xref{Monitor}.
1169 @item silencewait @var{seconds}
1170 Default timeout to trigger an inactivity notify. @xref{Monitor}.
1171 @item sleep @var{num}
1172 Pause during startup. @xref{Startup}.
1173 @item slowpaste @var{msec}
1174 Slow down pasting in windows. @xref{Paste}.
1175 @item source @var{file}
1176 Run commands from a file. @xref{Source}.
1177 @item sorendition [@var{attr} [@var{color}]]
1178 Deprecated. Use @code{rendition so} instead. @xref{Rendition}.
1180 Split region into two parts. @xref{Regions}.
1181 @item startup_message @var{state}
1182 Display copyright notice on startup. @xref{Startup}.
1183 @item stuff [@var{string}]
1184 Stuff a string in the input buffer of a window. @xref{Paste}.
1185 @item su [@var{username} [@var{password} [@var{password2}]]]
1186 Identify a user. @xref{Multiuser Session}.
1188 Put session in background. @xref{Suspend}.
1189 @item term @var{term}
1190 Set @code{$TERM} for new windows. @xref{Term}.
1191 @item termcap @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1192 Tweak termcap entries for best performance. @xref{Termcap Syntax}.
1193 @item terminfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1194 Ditto, for terminfo systems. @xref{Termcap Syntax}.
1195 @item termcapinfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1196 Ditto, for both systems. @xref{Termcap Syntax}.
1197 @item time [@var{string}]
1198 Display time and load average. @xref{Time}.
1199 @item title [@var{windowtitle}]
1200 Set the name of the current window. @xref{Title Command}.
1201 @item umask [@var{users}]+/-@var{bits} ...
1202 Synonym to @code{aclumask}. @xref{Umask}.
1204 Unset all keybindings. @xref{Bind}.
1205 @item unsetenv @var{var}
1206 Unset environment variable for new windows. @xref{Setenv}.
1207 @item utf8 [@var{state} [@var{dstate}]]
1208 Select character encoding of the current window. @xref{Character Processing}.
1209 @item vbell [@var{state}]
1210 Use visual bell. @xref{Bell}.
1211 @item vbell_msg [@var{message}]
1212 Set vbell message. @xref{Bell}.
1213 @item vbellwait @var{sec}
1214 Set delay for vbell message. @xref{Bell}.
1216 Display @code{screen} version. @xref{Version}.
1217 @item wall @var{message}
1218 Write a message to all displays. @xref{Multiuser Session}.
1219 @item width [@var{cols} [@var{lines}]]
1220 Set the width of the window. @xref{Window Size}.
1221 @item windowlist [[-b] [-m] [-g]] | string [@var{string}] | title [@var{title}]
1222 Present a list of all windows for selection. @xref{Windowlist}.
1224 List active windows. @xref{Windows}.
1225 @item wrap [@var{state}]
1226 Control line-wrap behavior. @xref{Wrap}.
1227 @item writebuf [-e @var{encoding}] [@var{filename}]
1228 Write paste buffer to screen-exchange file. @xref{Screen Exchange}.
1229 @item writelock @var{on}|@var{off}|@var{auto}
1230 Grant exclusive write permission. @xref{Multiuser Session}.
1232 Send an XOFF character. @xref{XON/XOFF}.
1234 Send an XON character. @xref{XON/XOFF}.
1235 @item zmodem [off|auto|catch|pass]
1236 Define how screen treats zmodem requests. @xref{Zmodem}.
1237 @item zombie [@var{keys} [onerror] ]
1238 Keep dead windows. @xref{Zombie}.
1241 @node New Window, Selecting, Commands, Top
1244 This section describes the commands for creating a new window for
1245 running programs. When a new window is created, the first available
1246 number is assigned to it.
1247 The number of windows is limited at compile-time by the MAXWIN
1248 configuration parameter (which defaults to 40).
1251 * Chdir:: Change the working directory for new windows.
1252 * Screen Command:: Create a new window.
1253 * Setenv:: Set environment variables for new windows.
1254 * Shell:: Parameters for shell windows.
1255 * Term:: Set the terminal type for new windows.
1256 * Window Types:: Creating different types of windows.
1257 * Window Groups:: Grouping windows together
1260 @node Chdir, Screen Command, , New Window
1262 @deffn Command chdir [directory]
1264 Change the current directory of @code{screen} to the specified directory
1265 or, if called without an argument, to your home directory (the value of
1266 the environment variable @code{$HOME}). All windows that are created by means
1267 of the @code{screen} command from within @file{.screenrc} or by means of
1268 @kbd{C-a : screen @dots{}} or @kbd{C-a c} use this as their default
1269 directory. Without a @code{chdir} command, this would be the directory
1270 from which @code{screen} was invoked. Hardcopy and log files are always
1271 written to the @emph{window's} default directory, @emph{not} the current
1272 directory of the process running in the window. You can use this
1273 command multiple times in your @file{.screenrc} to start various windows
1274 in different default directories, but the last @code{chdir} value will
1275 affect all the windows you create interactively.
1278 @node Screen Command, Setenv, Chdir, New Window
1279 @section Screen Command
1282 @deffn Command screen [opts] [n] [cmd [args] @var{| //group}]
1283 (@kbd{C-a c}, @kbd{C-a C-c})@*
1284 Establish a new window. The flow-control options (@samp{-f}, @samp{-fn}
1285 and @samp{-fa}), title option (@samp{-t}), login options
1286 (@samp{-l} and @samp{-ln}) , terminal type option (@samp{-T @var{term}}),
1287 the all-capability-flag (@samp{-a}) and scrollback option
1288 (@samp{-h @var{num}}) may be specified with each command.
1289 The option (@samp{-M}) turns monitoring on for this window.
1290 The option (@samp{-L}) turns output logging on for this window.
1291 If an optional number @var{n} in the range 0@dots{}MAXWIN-1 is given,
1292 the window number @var{n} is assigned to the newly created window (or,
1293 if this number is already in-use, the next available number). If a
1294 command is specified after @code{screen}, this command (with the given
1295 arguments) is started in the window; otherwise, a shell is created.
1296 If @samp{//group} is supplied, a container-type window is created in
1297 which other windows may be created inside it. @xref{Window Groups}.
1299 Screen has built in some functionality of @samp{cu} and @samp{telnet}.
1300 @xref{Window Types}.
1303 Thus, if your @file{.screenrc} contains the lines
1306 # example for .screenrc:
1308 screen -fn -t foobar 2 -L telnet foobar
1312 @code{screen} creates a shell window (in window #1) and a window with a
1313 TELNET connection to the machine foobar (with no flow-control using the
1314 title @samp{foobar} in window #2) and will write a logfile @samp{screenlog.2}
1315 of the telnet session. If you do not include any
1316 @code{screen} commands in your @file{.screenrc} file, then @code{screen}
1317 defaults to creating a single shell window, number zero. When the
1318 initialization is completed, @code{screen} switches to the last window
1319 specified in your .screenrc file or, if none, it opens default window
1322 @node Setenv, Shell, Screen Command, New Window
1324 @deffn Command setenv var string
1326 Set the environment variable @var{var} to value @var{string}.
1327 If only @var{var} is specified, the user will be prompted to enter a value.
1328 If no parameters are specified, the user will be prompted for both variable
1329 and value. The environment is inherited by all subsequently forked shells.
1332 @deffn Command unsetenv var
1334 Unset an environment variable.
1337 @node Shell, Term, Setenv, New Window
1339 @deffn Command shell command
1340 @deffnx Command defshell command
1342 Set the command to be used to create a new shell. This overrides the
1343 value of the environment variable @code{$SHELL}. This is useful if
1344 you'd like to run a tty-enhancer which is expecting to execute the
1345 program specified in @code{$SHELL}. If the command begins with
1346 a @samp{-} character, the shell will be started as a login-shell.
1348 @code{defshell} is currently a synonym to the @code{shell} command.
1351 @deffn Command shelltitle title
1353 Set the title for all shells created during startup or by the C-a C-c
1354 command. @xref{Naming Windows}, for details about what titles are.
1357 @node Term, Window Types , Shell, New Window
1359 @deffn Command term term
1361 In each window @code{screen} opens, it sets the @code{$TERM}
1362 variable to @code{screen} by default, unless no description for
1363 @code{screen} is installed in the local termcap or terminfo data base.
1364 In that case it pretends that the terminal emulator is @samp{vt100}.
1365 This won't do much harm, as @code{screen} is VT100/ANSI compatible. The
1366 use of the @code{term} command is discouraged for non-default purpose.
1367 That is, one may want to specify special @code{$TERM} settings (e.g. vt100) for
1368 the next @code{screen rlogin othermachine} command. Use the command
1369 @code{screen -T vt100 rlogin othermachine} rather than setting
1370 and resetting the default.
1373 @node Window Types, Window Groups, Term, New Window
1374 @section Window Types
1375 @cindex window types
1376 Screen provides three different window types. New windows are created
1377 with @code{screen}'s @samp{screen} command (@pxref{Screen Command}).
1378 The first parameter to the @samp{screen} command defines which
1379 type of window is created. The different window types are all
1380 special cases of the normal type. They have been added in order
1381 to allow @code{screen} to be used efficiently as a console
1382 with 100 or more windows.
1385 The normal window contains a shell (default, if no parameter is given)
1386 or any other system command that could be executed from a shell.
1387 (e.g. @samp{slogin}, etc...).
1390 If a tty (character special device) name (e.g. @samp{/dev/ttya})
1391 is specified as the first parameter, then the window is directly
1392 connected to this device.
1393 This window type is similar to @samp{screen cu -l /dev/ttya}.
1394 Read and write access is required on the device node,
1395 an exclusive open is attempted on the node to mark the connection line
1397 An optional parameter is allowed consisting of a comma separated
1398 list of flags in the notation used by @samp{stty(1)}:
1401 Usually 300, 1200, 9600 or 19200. This affects transmission as well as
1404 Specify the transmission of eight (or seven) bits per byte.
1406 Enables (or disables) software flow-control (CTRL-S/CTRL-Q) for sending
1408 @item ixoff or -ixoff
1409 Enables (or disables) software flow-control for receiving data.
1410 @item istrip or -istrip
1411 Clear (or keep) the eight bit in each received byte.
1414 You may want to specify as many of these options as applicable.
1415 Unspecified options cause the terminal driver to make up the parameter
1416 values of the connection. These values are system-dependent and may be
1417 in defaults or values saved from a previous connection.
1419 For tty windows, the @code{info} command shows some of the modem
1420 control lines in the status line.
1421 These may include @samp{RTS}, @samp{CTS}, @samp{DTR}, @samp{CD} and
1422 more. This depends rather on on the available @code{ioctl()}'s and system
1423 header files than on the physical capabilities of the serial board.
1424 The name of a logical low (inactive) signal is preceded by an
1425 exclamation mark (@samp{!}), otherwise the signal is logical high (active).
1426 Unsupported but shown signals are usually shown low.
1427 When the @code{CLOCAL} status bit is true, the whole set of modem signals is
1428 placed inside curly braces (@samp{@{} and @samp{@}}).
1429 When the @code{CRTSCTS} or @code{TIOCSOFTCAR} bit is true, the signals
1430 @samp{CTS} or @samp{CD} are shown in parenthesis, respectively.
1432 For tty windows, the command @code{break} causes the Data transmission
1433 line (TxD) to go low for a specified period of time. This is expected
1434 to be interpreted as break signal on the other side.
1435 No data is sent and no modem control line is changed when a
1436 @code{break} is issued.
1439 If the first parameter is @code{//telnet}, the second parameter is
1440 expected to be a host name, and an optional third parameter may specify
1441 a TCP port number (default decimal 23). Screen will connect to a
1442 server listening on the remote host and use the telnet protocol to
1443 communicate with that server.
1445 For telnet windows, the command @code{info} shows details about
1446 the connection in square brackets (@samp{[} and @samp{]}) at the end of
1450 BINARY. The connection is in binary mode.
1452 ECHO. Local echo is disabled.
1454 SGA. The connection is in `character mode' (default: `line mode').
1456 TTYPE. The terminal type has been requested by the remote host. Screen
1457 sends the name @code{screen} unless instructed otherwise (see also the
1458 command @samp{term}).
1460 NAWS. The remote site is notified about window size changes.
1462 LFLOW. The remote host will send flow control information.
1463 (Ignored at the moment.)
1465 Additional flags for debugging are @samp{x}, @samp{t} and @samp{n}
1466 (XDISPLOC, TSPEED and NEWENV).
1468 For telnet windows, the command @code{break} sends the telnet code
1469 @code{IAC BREAK} (decimal 243) to the remote host.
1473 @node Window Groups, , Window Types, New Window
1474 @section Window Groups
1475 @cindex window groups
1476 Screen provides a method for grouping windows together. Windows can be
1477 organized in a hierarchical fashion, resembling a tree structure. New
1478 screens are created using the @code{screen} command while new groups
1479 are created using @code{screen //group}. @xref{Screen Command}.
1481 Once a new group is created, it will act as a container for windows
1482 and even other groups. When a group is selected, you will see the
1483 output of the @code{windowlist} command, allowing you to select a
1484 window inside. If there are no windows inside a group, use the
1485 @code{screen} command to create one. Once inside a group, using the
1486 commands @code{next} and @code{prev} will switch between windows only
1487 in that group. Using the @code{windowlist} command will give you the
1488 opportunity to leave the group you are in. @xref{Windowlist}.
1490 @deffn Command group [grouptitle]
1492 Change or show the group the current window belongs to. Windows can
1493 be moved around between different groups by specifying the name of
1494 the destination group. Without specifying a group, the title of the
1495 current group is displayed.
1498 Using groups in combination with layouts will help create a
1499 multi-desktop experience. One group can be assigned for each
1500 layout made. Windows can be made, split, and organized within each
1501 group as desired. Afterwhich, switching between groups can be as easy
1502 as switching layouts.
1504 @node Selecting, Session Management, New Window, Top
1505 @chapter Selecting a Window
1507 This section describes the commands for switching between windows in an
1508 @code{screen} session. The windows are numbered from 0 to 9, and are created
1509 in that order by default (@pxref{New Window}).
1512 * Next and Previous:: Forward or back one window.
1513 * Other Window:: Switch back and forth between two windows.
1514 * Select:: Switch to a window (and to one after @code{kill}).
1515 * Windowlist:: Present a list of all windows for selection.
1518 @node Next and Previous, Other Window, , Selecting
1519 @section Moving Back and Forth
1524 (@kbd{C-a @key{SPC}}, @kbd{C-a n}, @kbd{C-a C-n})@*
1525 Switch to the next window. This command can be used repeatedly to
1526 cycle through the list of windows. (On some terminals, C-@key{SPC}
1527 generates a NUL character, so you must release the control key before
1536 (@kbd{C-a p}, @kbd{C-a C-p}, @kbd{C-a C-h}, @kbd{C-a @key{Backspace}})@*
1537 Switch to the previous window (the opposite of @kbd{C-a n}).
1540 @node Other Window, Select, Next and Previous, Selecting
1541 @section Other Window
1543 @deffn Command other
1545 Switch to the last window displayed. Note that this command
1546 defaults to the command character typed twice, unless overridden.
1547 For instance, if you use the option @samp{-e]x},
1548 this command becomes @kbd{]]} (@pxref{Command Character}).
1551 @node Select, Windowlist, Other Window, Selecting
1555 @deffn Command select [n @var{|-|.}]
1556 (@kbd{C-a @var{n}}, @kbd{C-a '})@*
1557 Switch to the window with the number @var{n}.
1558 If no window number is specified, you get prompted for an
1559 identifier. This can be a window name (title) or a number.
1560 When a new window is established, the lowest available number
1561 is assigned to this window.
1562 Thus, the first window can be activated by @code{select 0}; there
1563 can be no more than 10 windows present simultaneously (unless screen is
1564 compiled with a higher MAXWIN setting).
1565 There are two special arguments, @code{select -} switches to the
1566 internal blank window and @code{select .} switches to the
1567 current window. The latter is useful if used with screen's
1572 @node Windowlist, , Select, Selecting
1575 @deffn Command windowlist [-b] [-m] [-g]
1576 @deffnx Command windowlist string [@var{string}]
1577 @deffnx Command windowlist title [@var{title}]
1579 Display all windows in a table for visual window selection.
1580 If screen was in a window group, screen will
1581 back out of the group and then display the windows in that
1582 group. If the @code{-b} option is given, screen will
1583 switch to the blank window before presenting the list, so
1584 that the current window is also selectable.
1585 The @code{-m} option changes the order of the windows, instead of
1586 sorting by window numbers screen uses its internal most-recently-used
1587 list. The @code{-g} option will show the windows inside any groups
1588 in that level and downwards.
1590 The following keys are used to navigate in @code{windowlist}:
1593 @kbd{k}, @kbd{C-p}, or @kbd{up} Move up one line.
1596 @kbd{j}, @kbd{C-n}, or @kbd{down} Move down one line.
1599 @kbd{C-g} or @kbd{escape} Exit windowlist.
1602 @kbd{C-a} or @kbd{home} Move to the first line.
1605 @kbd{C-e} or @kbd{end} Move to the last line.
1608 @kbd{C-u} or @kbd{C-d} Move one half page up or down.
1611 @kbd{C-b} or @kbd{C-f} Move one full page up or down.
1614 @kbd{0..9} Using the number keys, move to the selected line.
1617 @kbd{mouseclick} Move to the selected line. Available when
1618 @code{mousetrack} is set to @code{on}.
1624 @kbd{n} Repeat search in the forward direction.
1627 @kbd{N} Repeat search in the backward direction.
1633 @kbd{g} Toggle group nesting.
1636 @kbd{a} All window view.
1639 @kbd{C-h} or @kbd{backspace} Back out the group.
1642 @kbd{,} Switch numbers with the previous window.
1645 @kbd{.} Switch numbers with the next window.
1648 @kbd{K} Kill that window.
1651 @kbd{space} or @kbd{enter} Select that window.
1653 The table format can be changed with the string and title
1654 option, the title is displayed as table heading, while the
1655 lines are made by using the string setting. The default
1656 setting is @samp{Num Name%=Flags} for the title and
1657 @samp{%3n %t%=%f} for the lines. See the string escapes chapter
1658 (@pxref{String Escapes}) for more codes (e.g. color settings).
1660 @code{Windowlist} needs a region size of at least 10 characters
1661 wide and 6 characters high in order to display.
1664 @node Session Management, Regions, Selecting, Top
1665 @chapter Session Management Commands
1667 Perhaps the most useful feature of @code{screen} is the way it allows
1668 the user to move a session between terminals, by detaching and
1669 reattaching. This also makes life easier for modem users who have to
1670 deal with unexpected loss of carrier.
1673 * Detach:: Disconnect @code{screen} from your terminal.
1674 * Power Detach:: Detach and log out.
1675 * Lock:: Lock your terminal temporarily.
1676 * Multiuser Session:: Changing number of allowed users.
1677 * Session Name:: Rename your session for later reattachment.
1678 * Suspend:: Suspend your session.
1679 * Quit:: Terminate your session.
1682 @node Detach, Power Detach, , Session Management
1685 @deffn Command autodetach state
1687 Sets whether @code{screen} will automatically detach upon hangup, which
1688 saves all your running programs until they are resumed with a
1689 @code{screen -r} command. When turned off, a hangup signal will
1690 terminate @code{screen} and all the processes it contains. Autodetach is
1696 @deffn Command detach
1697 (@kbd{C-a d}, @kbd{C-a C-d})@*
1698 Detach the @code{screen} session (disconnect it from the terminal and
1699 put it into the background). A detached @code{screen} can be resumed by
1700 invoking @code{screen} with the @code{-r} option (@pxref{Invoking
1702 The @code{-h} option tells screen to immediately close the connection
1703 to the terminal (@samp{hangup}).
1706 @deffn Command password [crypted_pw]
1708 Present a crypted password in your @file{.screenrc} file and screen will
1709 ask for it, whenever someone attempts to resume a detached session. This
1710 is useful, if you have privileged programs running under @code{screen}
1711 and you want to protect your session from reattach attempts by users
1712 that managed to assume your uid. (I.e. any superuser.) If no crypted
1713 password is specified, screen prompts twice a password and places its
1714 encryption in the paste buffer. Default is `none', which disables
1718 @node Power Detach, Lock, Detach, Session Management
1719 @section Power Detach
1722 @deffn Command pow_detach
1724 Mainly the same as @code{detach}, but also sends a HANGUP signal
1725 to the parent process of @code{screen}.@*
1726 @emph{Caution}: This will result in a
1727 logout if @code{screen} was started from your login shell.
1730 @deffn Command pow_detach_msg [message]
1732 The @var{message} specified here is output whenever a power detach is
1733 performed. It may be used as a replacement for a logout message or to reset
1735 Without a parameter, the current message is shown.
1738 @node Lock, Multiuser Session, Power Detach, Session Management
1742 @deffn Command lockscreen
1743 (@kbd{C-a x}, @kbd{C-a C-x})@*
1744 Call a screenlock program (@file{/local/bin/lck} or @file{/usr/bin/lock}
1745 or a builtin, if no other is available). Screen does not accept any
1746 command keys until this program terminates. Meanwhile processes in the
1747 windows may continue, as the windows are in the detached state.
1748 The screenlock program may be changed through the environment variable
1749 @code{$LOCKPRG} (which must be set in the shell from which @code{screen}
1750 is started) and is executed with the user's uid and gid.
1752 Warning: When you leave other shells unlocked and have no password set
1753 on @code{screen}, the lock is void: One could easily re-attach from an
1754 unlocked shell. This feature should rather be called
1755 @code{lockterminal}.
1758 @node Multiuser Session, Session Name, Lock, Session Management
1759 @section Multiuser Session
1760 @cindex multiuser session
1762 These commands allow other users to gain access to one single @code{screen}
1763 session. When attaching to a multiuser @code{screen} the sessionname is
1764 specified as @code{username/sessionname} to the @code{-S} command line option.
1765 @code{Screen} must be compiled with multiuser support to enable features
1769 * Multiuser:: Enable / Disable multiuser mode.
1770 * Acladd:: Enable a specific user.
1771 * Aclchg:: Change a users permissions.
1772 * Acldel:: Disable a specific user.
1773 * Aclgrp:: Grant a user permissions to other users.
1774 * Displays:: List all active users at their displays.
1775 * Umask:: Predefine access to new windows.
1776 * Wall:: Write a message to all users.
1777 * Writelock:: Grant exclusive window access.
1778 * Su:: Substitute user.
1781 @node Multiuser, Acladd, , Multiuser Session
1782 @subsection Multiuser
1783 @deffn Command multiuser @var{state}
1785 Switch between single-user and multi-user mode. Standard screen operation is
1786 single-user. In multi-user mode the commands @code{acladd}, @code{aclchg} and
1787 @code{acldel} can be used to enable (and disable) other users accessing this
1791 @node Acladd, Aclchg, Multiuser, Multiuser Session
1793 @deffn Command acladd @var{usernames}
1794 @deffnx Command addacl @var{usernames}
1796 Enable users to fully access this screen session. @var{Usernames} can be one
1797 user or a comma separated list of users. This command enables to attach to
1798 the @code{screen} session and performs the equivalent of
1799 @code{aclchg @var{usernames} +rwx "#?"}. To add a user with restricted access,
1800 use the @code{aclchg} command below.
1801 @code{Addacl} is a synonym to @code{acladd}.
1802 Multi-user mode only.
1805 @node Aclchg, Acldel, Acladd, Multiuser Session
1807 @deffn Command aclchg @var{usernames permbits list}
1808 @deffnx Command chacl @var{usernames permbits list}
1810 Change permissions for a comma separated list of users.
1811 Permission bits are represented as @samp{r}, @samp{w} and @samp{x}.
1812 Prefixing @samp{+} grants the permission, @samp{-} removes it. The third
1813 parameter is a comma separated list of commands or windows (specified either
1814 by number or title). The special list @samp{#} refers to all windows, @samp{?}
1815 to all commands. If @var{usernames} consists of a single @samp{*}, all
1816 known users are affected.
1817 A command can be executed when the user has the @samp{x} bit for it. The user
1818 can type input to a window when he has its @samp{w} bit set and no other
1819 user obtains a writelock for this window. Other bits are currently ignored.
1820 To withdraw the writelock from another user in e.g. window 2:
1821 @samp{aclchg @var{username} -w+w 2}. To allow read-only access
1822 to the session: @samp{aclchg @var{username} -w "#"}. As soon as a user's name
1823 is known to screen, he can attach to the session and (per default) has full
1824 permissions for all command and windows. Execution permission for the acl
1825 commands, @code{at} and others should also be removed or the user may be able
1826 to regain write permission.
1827 @code{Chacl} is a synonym to @code{aclchg}.
1828 Multi-user mode only.
1831 @node Acldel, Aclgrp, Aclchg, Multiuser Session
1833 @deffn Command acldel @var{username}
1835 Remove a user from screen's access control list. If currently attached, all the
1836 user's displays are detached from the session. He cannot attach again.
1837 Multi-user mode only.
1840 @node Aclgrp, Displays, Acldel, Multiuser Session
1842 @deffn Command aclgrp @var{username} [@var{groupname}]
1844 Creates groups of users that share common access rights. The
1845 name of the group is the username of the group leader. Each
1846 member of the group inherits the permissions that are
1847 granted to the group leader. That means, if a user fails an
1848 access check, another check is made for the group leader.
1849 A user is removed from all groups the special value @samp{none}
1850 is used for @var{groupname}. If the second parameter is omitted
1851 all groups the user is in are listed.
1854 @node Displays, Umask, Aclgrp, Multiuser Session
1855 @subsection Displays
1857 @deffn Command displays
1859 Shows a tabular listing of all currently connected user
1860 front-ends (displays). This is most useful for multiuser
1863 The following keys can be used in @code{displays} list:
1866 @kbd{k}, @kbd{C-p}, or @kbd{up} Move up one line.
1869 @kbd{j}, @kbd{C-n}, or @kbd{down} Move down one line.
1872 @kbd{C-a} or @kbd{home} Move to the first line.
1875 @kbd{C-e} or @kbd{end} Move to the last line.
1878 @kbd{C-u} or @kbd{C-d} Move one half page up or down.
1881 @kbd{C-b} or @kbd{C-f} Move one full page up or down.
1884 @kbd{mouseclick} Move to the selected line. Available when
1885 @code{mousetrack} is set to @code{on}.
1888 @kbd{space} Refresh the list.
1891 @kbd{d} Detach the selected display.
1894 @kbd{D} Power detach the selected display.
1897 @kbd{C-g}, @kbd{enter}, or @kbd{escape} Exit the list.
1900 The following is an example of what @code{displays} could
1904 xterm 80x42 jnweiger@@/dev/ttyp4 0(m11) &rWx
1905 facit 80x24 mlschroe@@/dev/ttyhf nb 11(tcsh) rwx
1906 xterm 80x42 jnhollma@@/dev/ttyp5 0(m11) &R.x
1907 (A) (B) (C) (D) (E) (F)(G) (H)(I)
1910 The legend is as follows:
1911 @*(A) The terminal type known by @code{screen} for this display.
1912 @*(B) Displays geometry as width x height.
1913 @*(C) Username who is logged in at the display.
1914 @*(D) Device name of the display or the attached device
1915 @*(E) Display is in blocking or nonblocking mode. The available
1916 modes are "nb", "NB", "Z<", "Z>", and "BL".
1917 @*(F) Number of the window
1918 @*(G) Name/title of window
1919 @*(H) Whether the window is shared
1920 @*(I) Window permissions. Made up of three characters:
1925 @samp{R} : read only due to foreign wlock
1928 @samp{.} : write suppressed by foreign wlock
1930 @samp{W} : own wlock
1932 @samp{-} : no execute
1936 @code{Displays} needs a region size of at least 10 characters
1937 wide and 5 characters high in order to display.
1940 @node Umask, Wall, Displays, Multiuser Session
1941 @subsection aclumask
1942 @deffn Command aclumask [@var{users}]+/-@var{bits} ...
1943 @deffnx Command umask [@var{users}]+/-@var{bits} ...
1945 This specifies the access other users have to windows that
1946 will be created by the caller of the command. @var{Users} may be no,
1947 one or a comma separated list of known usernames. If no users are
1948 specified, a list of all currently known users is assumed.
1949 @var{Bits} is any combination of access control bits allowed
1950 defined with the @code{aclchg} command. The special username @samp{?}
1951 predefines the access that not yet known users will be
1952 granted to any window initially. The special username @samp{??}
1953 predefines the access that not yet known users are granted
1954 to any command. Rights of the special username nobody cannot
1955 be changed (see the @code{su} command).
1956 @code{Umask} is a synonym to @code{aclumask}.
1960 @node Wall, Writelock, Umask, Multiuser Session
1962 @deffn Command wall @var{message}
1964 Write a message to all displays. The message will appear in the terminal's
1968 @node Writelock, Su , Wall, Multiuser Session
1969 @subsection Writelock
1970 @deffn Command writelock @var{on|off|auto}
1972 In addition to access control lists, not all users may be able to write to
1973 the same window at once. Per default, writelock is in @samp{auto} mode and
1974 grants exclusive input permission to the user who is the first to switch
1975 to the particular window. When he leaves the window, other users may obtain
1976 the writelock (automatically). The writelock of the current window is disabled
1977 by the command @code{writelock off}. If the user issues the command
1978 @code{writelock on} he keeps the exclusive write permission while switching
1982 @deffn Command defwritelock @var{on|off|auto}
1984 Sets the default writelock behavior for new windows. Initially all windows
1985 will be created with no writelocks.
1988 @node Su, , Writelock, Multiuser Session
1990 @deffn Command su [@var{username} [@var{password} [@var{password2}]]]
1992 Substitute the user of a display. The command prompts for
1993 all parameters that are omitted. If passwords are specified
1994 as parameters, they have to be specified un-crypted. The
1995 first password is matched against the systems passwd database,
1996 the second password is matched against the @code{screen}
1997 password as set with the commands @code{acladd} or @code{password}.
1998 @code{Su} may be useful for the @code{screen} administrator to test
2000 When the identification fails, the user has
2001 access to the commands available for user @samp{nobody}. These are
2002 @code{detach}, @code{license}, @code{version}, @code{help} and
2006 @node Session Name, Suspend, Multiuser Session, Session Management
2007 @section Session Name
2008 @deffn Command sessionname [@var{name}]
2010 Rename the current session. Note that for @code{screen -list} the name
2011 shows up with the process-id prepended. If the argument @var{name} is
2012 omitted, the name of this session is displayed.@*
2013 @emph{Caution}: The @code{$STY}
2014 environment variable will still reflect the old name in pre-existing
2015 shells. This may result in
2016 confusion. Use of this command is generally
2017 discouraged. Use the @code{-S} command-line option if you want to
2018 name a new session.The default is constructed from the tty and host names.
2021 @node Suspend, Quit, Session Name, Session Management
2025 @deffn Command suspend
2026 (@kbd{C-a z}, @kbd{C-a C-z})@*
2027 Suspend @code{screen}. The windows are in the detached state while
2028 @code{screen} is suspended. This feature relies on the parent shell
2029 being able to do job control.
2032 @node Quit, , Suspend, Session Management
2037 Kill all windows and terminate @code{screen}. Note that on VT100-style
2038 terminals the keys @kbd{C-4} and @kbd{C-\} are identical. So be careful
2039 not to type @kbd{C-a C-4} when selecting window no. 4. Use the empty
2040 bind command (as in @code{bind "^\"}) to remove a key binding
2041 (@pxref{Key Binding}).
2044 @node Regions, Window Settings, Session Management, Top
2047 Screen has the ability to display more than one window on the
2048 user's display. This is done by splitting the screen in regions,
2049 which can contain different windows.
2052 * Split:: Split a region into two
2053 * Focus:: Change to the next region
2054 * Only:: Delete all other regions
2055 * Remove:: Delete the current region
2056 * Resize:: Grow or shrink a region
2057 * Caption:: Control the window's caption
2058 * Fit:: Resize a window to fit the region
2059 * Focusminsize:: Force a minimum size on a current region
2060 * Layout:: Manage groups of regions
2063 @node Split, Focus, , Regions
2067 @deffn Command split [-v]
2068 (@kbd{C-a S}, @kbd{C-a |})@*
2069 Split the current region into two new ones. All regions on the
2070 display are resized to make room for the new region. The blank
2071 window is displayed on the new region. The default is to create
2072 a horizontal split, putting the new regions on the top and
2073 bottom of each other. Using -v will create a vertical split,
2074 causing the new regions to appear side by side of each other.
2076 With this current implementation of @code{screen}, scrolling data
2077 will appear much slower in a vertically split region than one
2078 that is not. This should be taken into consideration if you need
2079 to use system commands such as @code{cat} or @code{tail -f}.
2082 @node Focus, Only, Split, Regions
2085 @deffn Command focus
2086 (@kbd{C-a @key{Tab}})@*
2087 Move the input focus to the next region. This is done in a cyclic
2088 way so that the top region is selected after the bottom one. If
2089 no subcommand is given it defaults to `down'. `up' cycles in the
2090 opposite order, `top' and `bottom' go to the top and bottom
2091 region respectively. Useful bindings are (j and k as in vi)
2100 @node Only, Remove, Focus, Regions
2105 Kill all regions but the current one.
2108 @node Remove, Resize, Only, Regions
2111 @deffn Command remove
2113 Kill the current region. This is a no-op if there is only one region.
2116 @node Resize, Caption, Remove, Regions
2118 @deffn Command resize [(+/-)@var{lines}]
2120 Resize the current region. The space will be removed from or added to
2121 the region below or if there's not enough space from the region above.
2123 resize +N increase current region height by N
2124 resize -N decrease current region height by N
2125 resize N set current region height to N
2126 resize = make all windows equally high
2127 resize max maximize current region height
2128 resize min minimize current region height
2132 @node Caption, Fit, Resize, Regions
2134 @deffn Command caption @code{always}|@code{splitonly} [string]
2135 @deffnx Command caption @code{string} [string]
2137 This command controls the display of the window captions. Normally
2138 a caption is only used if more than one window is shown on the
2139 display (split screen mode). But if the type is set to
2140 @code{always}, @code{screen} shows a caption
2141 even if only one window is displayed. The default
2142 is @samp{splitonly}.
2144 The second form changes the text used for the caption. You can use
2145 all string escapes (@pxref{String Escapes}). @code{Screen} uses
2146 a default of @samp{%3n %t}.
2148 You can mix both forms by providing the string as an additional
2152 @node Fit, Focusminsize, Caption, Regions
2157 Change the window size to the size of the current region. This
2158 command is needed because screen doesn't adapt the window size
2159 automatically if the window is displayed more than once.
2162 @node Focusminsize, Layout, Fit, Regions
2163 @section Focusminsize
2164 @deffn Command focusminsize [ (width|@code{max}|@code{_}) (height|@code{max}|@code{_}) ]
2166 This forces any currently selected region to be automatically
2167 resized at least a certain @var{width} and @var{height}. All
2168 other surrounding regions will be resized in order to accommodate.
2169 This constraint follows every time the @code{focus} command is
2170 used. The @code{resize} command can be used to increase either
2171 dimension of a region, but never below what is set with
2172 @code{focusminsize}. The underscore @samp{_} is a synonym for
2173 @code{max}. Setting a @var{width} and @var{height} of @code{0 0}
2174 (zero zero) will undo any constraints and allow for manual resizing.
2175 Without any parameters, the minimum width and height is shown.
2178 @node Layout, , Focusminsize, Regions
2181 Using regions, and perhaps a large enough terminal, you can give
2182 @code{screen} more of a desktop feel. By being able to split
2183 regions horizontally or vertically, you can take advantage of the
2184 lesser used spaces of your terminal. The catch to these splits has
2185 been that they're not kept between screen detachments and reattachments.
2187 Layouts will help organize your regions. You can create one
2188 layout of four horizontal regions and then create a separate layout
2189 of regions in a two by two array. The regions could contain the same windows,
2190 but they don't have to. You can easily switch between layouts and keep
2191 them between detachments and reattachments.
2193 Note that there are several subcommands to @code{layout}.
2195 @deffn Command layout @code{new} [title]
2197 Create a new layout. The screen will change to one whole region
2198 and be switched to the blank window. From here, you build the
2199 regions and the windows they show as you desire. The new layout
2200 will be numbered with the smallest available integer, starting
2201 with zero. You can optionally give a title to your new layout.
2202 Otherwise, it will have a default title of @code{layout}. You
2203 can always change the title later by using the command
2204 @code{layout title}.
2207 @deffn Command layout @code{remove} [n|title]
2209 Remove, or in other words, delete the specified layout. Either
2210 the number or the title can be specified. Without either
2211 specification, @code{screen} will remove the current layout.
2213 Removing a layout does not affect your set windows or regions.
2216 @deffn Command layout @code{next}
2218 Switch to the next layout available
2221 @deffn Command layout @code{prev}
2223 Switch to the previous layout available
2226 @deffn Command layout @code{select} [n|title]
2228 Select the desired layout. Either the number or the title can
2229 be specified. Without either specification, @code{screen} will
2230 prompt and ask which screen is desired. To see which layouts are
2231 available, use the @code{layout show} command.
2234 @deffn Command layout @code{show}
2236 List on the message line the number(s) and title(s) of the available
2237 layout(s). The current layout is flagged.
2240 @deffn Command layout @code{title} [title]
2242 Change or display the title of the current layout. A string given
2243 will be used to name the layout. Without any options, the current
2244 title and number is displayed on the message line.
2247 @deffn Command layout @code{number} [n]
2249 Change or display the number of the current layout. An integer given
2250 will be used to number the layout. Without any options, the current
2251 number and title is displayed on the message line.
2254 @deffn Command layout @code{attach} [title|@code{:last}]
2256 Change or display which layout to reattach back to. The default is
2257 @code{:last}, which tells @code{screen} to reattach back to the last
2258 used layout just before detachment. By supplying a title, You can
2259 instruct @code{screen} to reattach to a particular layout regardless
2260 which one was used at the time of detachment. Without any options,
2261 the layout to reattach to will be shown in the message line.
2264 @deffn Command layout @code{save} [n|title]
2266 Remember the current arrangement of regions. When used, @code{screen}
2267 will remember the arrangement of vertically and horizontally split
2268 regions. This arrangement is restored when a @code{screen} session
2269 is reattached or switched back from a different layout. If the
2270 session ends or the @code{screen} process dies, the layout
2271 arrangements are lost. The @code{layout dump} command should help
2272 in this siutation. If a number
2273 or title is supplied, @code{screen} will remember the arrangement of
2274 that particular layout. Without any options, @code{screen} will
2275 remember the current layout.
2277 Saving your regions can be done automatically by using the
2278 @code{layout autosave} command.
2281 @deffn Command layout @code{autosave} [@code{on}|@code{off}]
2283 Change or display the status of automatically saving layouts. The
2284 default is @code{on}, meaning when @code{screen} is detached or
2285 changed to a different layout, the arrangement of regions and windows
2286 will be remembered at the time of change and restored upon return.
2287 If autosave is set to @code{off}, that arrangement will only be
2288 restored to either to the last manual save, using @code{layout save},
2289 or to when the layout was first created, to a single region with
2290 a single window. Without either an @code{on} or an @code{off}, the
2291 current status is displayed on the message line.
2294 @deffn Command layout @code{dump} [filename]
2296 Write to a file the order of splits made in the current layout. This
2297 is useful to recreate the order of your regions used in your current
2298 layout. Only the current layout is recorded. While the order of the
2299 regions are recorded, the sizes of those regions and which windows
2300 correspond to which regions are not. If no filename is specified,
2301 the default is @file{layout-dump}, saved in the directory that the
2302 @code{screen} process was started in. If the file already exists,
2303 @code{layout dump} will append to that file. As an example:
2305 layout dump /home/user/.screenrc
2307 will save or append the layout to the user's @file{.screenrc} file.
2310 @node Window Settings, Virtual Terminal, Regions, Top
2311 @chapter Window Settings
2313 These commands control the way @code{screen} treats individual windows
2314 in a session. @xref{Virtual Terminal}, for commands to control the
2315 terminal emulation itself.
2318 * Naming Windows:: Control the name of the window
2319 * Console:: See the host's console messages
2320 * Kill:: Destroy an unwanted window
2321 * Login:: Control @file{/etc/utmp} logging
2322 * Mode:: Control the file mode of the pty
2323 * Monitor:: Watch for activity or inactivity in a window
2324 * Windows:: List the active windows
2325 * Hardstatus:: Set a window's hardstatus line
2328 @node Naming Windows, Console, , Window Settings
2329 @section Naming Windows (Titles)
2332 You can customize each window's name in the window display (viewed with
2333 the @code{windows} command (@pxref{Windows}) by setting it with
2334 one of the title commands. Normally the name displayed is the actual
2335 command name of the program created in the window. However, it is
2336 sometimes useful to distinguish various programs of the same name or to
2337 change the name on-the-fly to reflect the current state of the window.
2339 The default name for all shell windows can be set with the
2340 @code{shelltitle} command (@pxref{Shell}). You can specify the name you
2341 want for a window with the @samp{-t} option to the @code{screen} command
2342 when the window is created (@pxref{Screen Command}). To change the name after
2343 the window has been created you can use the title-string escape-sequence
2344 (@kbd{@key{ESC} k @var{name} @key{ESC} \}) and the @code{title} command
2345 (C-a A). The former can be output from an application to control the
2346 window's name under software control, and the latter will prompt for a
2347 name when typed. You can also bind predefined names to keys with the
2348 @code{title} command to set things quickly without prompting.
2351 * Title Command:: The @code{title} command.
2352 * Dynamic Titles:: Make shell windows change titles dynamically.
2353 * Title Prompts:: Set up your shell prompt for dynamic Titles.
2354 * Title Screenrc:: Set up Titles in your @file{.screenrc}.
2357 @node Title Command, Dynamic Titles, , Naming Windows
2358 @subsection Title Command
2360 @deffn Command title [windowtitle]
2362 Set the name of the current window to @var{windowtitle}. If no name is
2363 specified, screen prompts for one.
2366 @node Dynamic Titles, Title Prompts, Title Command, Naming Windows
2367 @subsection Dynamic Titles
2368 @code{screen} has a shell-specific heuristic that is enabled by
2369 setting the window's name to @var{search|name} and arranging to have a
2370 null title escape-sequence output as a part of your prompt. The
2371 @var{search} portion specifies an end-of-prompt search string, while the
2372 @var{name} portion specifies the default shell name for the window. If
2373 the @var{name} ends in a @samp{:} @code{screen} will add what it
2374 believes to be the current command running in the window to the end of
2375 the specified name (e.g. @var{name:cmd}). Otherwise the current
2376 command name supersedes the shell name while it is running.
2378 Here's how it works: you must modify your shell prompt to output a null
2379 title-escape-sequence (@key{ESC} k @key{ESC} \) as a part of your prompt.
2380 The last part of your prompt must be the same as the string you
2381 specified for the @var{search} portion of the title. Once this is set
2382 up, @code{screen} will use the title-escape-sequence to clear the previous
2383 command name and get ready for the next command. Then, when a newline
2384 is received from the shell, a search is made for the end of the prompt.
2385 If found, it will grab the first word after the matched string and use
2386 it as the command name. If the command name begins with @samp{!},
2387 @samp{%}, or @samp{^}, @code{screen} will use the first word on the
2388 following line (if found) in preference to the just-found name. This
2389 helps csh users get more accurate titles when using job control or
2390 history recall commands.
2392 @node Title Prompts, Title Screenrc, Dynamic Titles, Naming Windows
2393 @subsection Setting up your prompt for shell titles
2394 One thing to keep in mind when adding a null title-escape-sequence to your
2395 prompt is that some shells (like the csh) count all the non-control
2396 characters as part of the prompt's length. If these invisible
2397 characters aren't a multiple of 8 then backspacing over a tab will
2398 result in an incorrect display. One way to get around this is to use a
2402 set prompt='@value{esc}[0000m@value{esc}k@value{esc}\% '
2405 The escape-sequence @samp{@value{esc}[0000m} not only normalizes the
2406 character attributes, but all the zeros round the length of the
2407 invisible characters up to 8.
2409 Tcsh handles escape codes in the prompt more intelligently, so you can
2410 specify your prompt like this:
2413 set prompt="%@{\ek\e\\%@}\% "
2416 Bash users will probably want to echo the escape sequence in the
2420 PROMPT_COMMAND='printf "\033k\033\134"'
2423 (I used @samp{\134} to output a @samp{\} because of a bug in v1.04).
2425 @node Title Screenrc, , Title Prompts, Naming Windows
2426 @subsection Setting up shell titles in your @file{.screenrc}
2427 Here are some .screenrc examples:
2430 screen -t top 2 nice top
2433 Adding this line to your .screenrc would start a niced version of the
2434 @code{top} command in window 2 named @samp{top} rather than @samp{nice}.
2441 This file would start a shell using the given shelltitle. The title
2442 specified is an auto-title that would expect the prompt and the typed
2443 command to look something like the following:
2446 /usr/joe/src/dir> trn
2449 (it looks after the '> ' for the command name).
2450 The window status would show the name @samp{trn} while the command was
2451 running, and revert to @samp{csh} upon completion.
2454 bind R screen -t '% |root:' su
2457 Having this command in your .screenrc would bind the key sequence
2458 @kbd{C-a R} to the @code{su} command and give it an auto-title name of
2459 @samp{root:}. For this auto-title to work, the screen could look
2460 something like this:
2467 Here the user typed the csh history command @code{!em} which ran the
2468 previously entered @code{emacs} command. The window status would show
2469 @samp{root:emacs} during the execution of the command, and revert to
2470 simply @samp{root:} at its completion.
2475 bind u title (unknown)
2478 The first binding doesn't have any arguments, so it would prompt you for
2479 a title when you type @kbd{C-a o}. The second binding would clear an
2480 auto-titles current setting (C-a E). The third binding would set the
2481 current window's title to @samp{(unknown)} (C-a u).
2483 @node Console, Kill, Naming Windows, Window Settings
2485 @deffn Command console [@var{state}]
2487 Grabs or un-grabs the machines console output to a window. When the argument
2488 is omitted the current state is displayed.
2489 @emph{Note}: Only the owner of @file{/dev/console} can grab the console
2490 output. This command is only available if the host supports the ioctl
2494 @node Kill, Login, Console, Window Settings
2500 (@kbd{C-a k}, @kbd{C-a C-k})@*
2501 Kill the current window.@*
2502 If there is an @code{exec} command running (@pxref{Exec}) then it is killed.
2503 Otherwise the process (e.g. shell) running in the window receives a
2504 @code{HANGUP} condition,
2505 the window structure is removed and screen (your display) switches to another
2506 window. When the last window is destroyed, @code{screen} exits.
2507 After a kill screen switches to the previously displayed window.
2509 @emph{Caution}: @code{emacs} users may find themselves killing their
2510 @code{emacs} session when trying to delete the current line. For this
2511 reason, it is probably wise to use a different command character
2512 (@pxref{Command Character}) or rebind @code{kill} to another key
2513 sequence, such as @kbd{C-a K} (@pxref{Key Binding}).
2516 @node Login, Mode, Kill, Window Settings
2519 @deffn Command deflogin state
2521 Same as the @code{login} command except that the default setting for new
2522 windows is changed. This defaults to `on' unless otherwise specified at
2523 compile time (@pxref{Installation}). Both commands are only present when
2524 @code{screen} has been compiled with utmp support.
2528 @deffn Command login [state]
2530 Adds or removes the entry in @file{/etc/utmp} for the current window.
2531 This controls whether or not the window is @dfn{logged in}. In addition
2532 to this toggle, it is convenient to have ``log in'' and ``log out''
2533 keys. For instance, @code{bind I login on} and @code{bind O
2534 login off} will map these keys to be @kbd{C-a I} and @kbd{C-a O}
2535 (@pxref{Key Binding}).
2538 @node Mode, Monitor, Login, Window Settings
2540 @deffn Command defmode mode
2542 The mode of each newly allocated pseudo-tty is set to @var{mode}.
2543 @var{mode} is an octal number as used by chmod(1). Defaults to 0622 for
2544 windows which are logged in, 0600 for others (e.g. when @code{-ln} was
2545 specified for creation, @pxref{Screen Command}).
2548 @node Monitor, Windows, Mode, Window Settings
2551 @deffn Command activity message
2553 When any activity occurs in a background window that is being monitored,
2554 @code{screen} displays a notification in the message line. The
2555 notification message can be redefined by means of the @code{activity}
2556 command. Each occurrence of @samp{%} in @var{message} is replaced by
2557 the number of the window in which activity has occurred, and each
2558 occurrence of @samp{^G} is replaced by the definition for bell in your
2559 termcap (usually an audible bell). The default message is
2562 'Activity in window %n'
2565 Note that monitoring is off for all windows by default, but can be altered
2566 by use of the @code{monitor} command (@kbd{C-a M}).
2569 @deffn Command defmonitor state
2571 Same as the @code{monitor} command except that the default setting for
2572 new windows is changed. Initial setting is `off'.
2576 @deffn Command monitor [state]
2578 Toggles monitoring of the current window. When monitoring is turned on
2579 and the affected window is switched into the background, the activity
2580 notification message will be displayed in the status line at the first
2581 sign of output, and the window will also be marked with an @samp{@@} in
2582 the window-status display (@pxref{Windows}). Monitoring defaults to
2583 @samp{off} for all windows.
2587 @deffn Command silence [@var{state}|@var{sec}]
2589 Toggles silence monitoring of windows. When silence is turned on and an
2590 affected window is switched into the background, you will receive the
2591 silence notification message in the status line after a specified period
2592 of inactivity (silence). The default timeout can be changed with the
2593 @code{silencewait} command or by specifying a number of seconds instead of
2594 @code{on} or @code{off}. Silence is initially off for all windows.
2597 @deffn Command defsilence state
2599 Same as the @code{silence} command except that the default setting for
2600 new windows is changed. Initial setting is `off'.
2603 @deffn Command silencewait @var{seconds}
2605 Define the time that all windows monitored for silence should wait
2606 before displaying a message. Default is 30 seconds.
2609 @node Windows, Hardstatus, Monitor, Window Settings
2613 @deffn Command windows
2614 (@kbd{C-a w}, @kbd{C-a C-w})@*
2615 Uses the message line to display a list of all the windows. Each
2616 window is listed by number with the name of the program running in the
2617 window (or its title).
2619 The current window is marked with a @samp{*};
2620 the previous window is marked with a @samp{-};
2621 all the windows that are logged in are marked with a @samp{$} (@pxref{Login});
2622 a background window that has received a bell is marked with a @samp{!};
2623 a background window that is being monitored and has had activity occur is
2624 marked with an @samp{@@} (@pxref{Monitor});
2625 a window which has output logging turned on is marked with @samp{(L)};
2626 windows occupied by other users are marked with @samp{&}
2627 or @samp{&&} if the window is shared by other users;
2628 windows in the zombie state are marked with @samp{Z}.
2630 If this list is too long to fit on the terminal's status line only the
2631 portion around the current window is displayed.
2634 @node Hardstatus, Mousetrack, Windows, Window Settings
2637 @code{Screen} maintains a hardstatus line for every window. If a window
2638 gets selected, the display's hardstatus will be updated to match
2639 the window's hardstatus line.
2640 The hardstatus line can be changed with the ANSI Application
2641 Program Command (APC): @samp{ESC_<string>ESC\}. As a convenience
2642 for xterm users the sequence @samp{ESC]0..2;<string>^G} is
2645 @deffn Command defhstatus [status]
2647 The hardstatus line that all new windows will get is set to
2649 This command is useful to make the hardstatus of every window
2650 display the window number or title or the like. @var{status}
2651 may contain the same directives as in the window messages, but
2652 the directive escape character is @samp{^E} (octal 005) instead
2653 of @samp{%}. This was done to make a misinterpretation of program
2654 generated hardstatus lines impossible.
2655 If the parameter @var{status}
2656 is omitted, the current default string is displayed.
2657 Per default the hardstatus line of new windows is empty.
2660 @deffn Command hstatus status
2662 Changes the current window's hardstatus line to @var{status}.
2665 @node Mousetrack, , Hardstatus, Miscellaneous
2668 @deffn Command mousetrack [ @code{on|off} ]
2670 This command determines whether @code{screen} will watch for
2671 mouse clicks. When this command is enabled, regions that have
2672 been split in various ways can be selected by pointing to them
2673 with a mouse and left-clicking them. Without specifying @var{on}
2674 or @var{off}, the current state is displayed. The default state
2675 is determined by the @code{defmousetrack} command.
2678 @deffn Command defmousetrack @code{on|off}
2680 This command determines the default state of the @code{mousetrack}
2681 command, currently defaulting of @var{off}.
2684 @node Virtual Terminal, Copy and Paste, Window Settings, Top
2685 @chapter Virtual Terminal
2687 Each window in a @code{screen} session emulates a VT100 terminal, with
2688 some extra functions added. The VT100 emulator is hard-coded, no other
2689 terminal types can be emulated.
2690 The commands described here modify the terminal emulation.
2693 * Control Sequences:: Details of the internal VT100 emulation.
2694 * Input Translation:: How keystrokes are remapped.
2695 * Digraph:: Entering digraph sequences.
2696 * Bell:: Getting your attention.
2697 * Clear:: Clear the window display.
2698 * Info:: Terminal emulation statistics.
2699 * Redisplay:: When the display gets confusing.
2700 * Wrap:: Automatic margins.
2701 * Reset:: Recovering from ill-behaved applications.
2702 * Window Size:: Changing the size of your terminal.
2703 * Character Processing:: Change the effect of special characters.
2706 @node Control Sequences, Input Translation, , Virtual Terminal
2707 @section Control Sequences
2708 @cindex control sequences
2709 The following is a list of control sequences recognized by
2710 @code{screen}. @samp{(V)} and @samp{(A)} indicate VT100-specific and
2711 ANSI- or ISO-specific functions, respectively.
2717 ESC H Horizontal Tab Set
2718 ESC Z Send VT100 Identification String
2719 ESC 7 (V) Save Cursor and Attributes
2720 ESC 8 (V) Restore Cursor and Attributes
2721 ESC [s (A) Save Cursor and Attributes
2722 ESC [u (A) Restore Cursor and Attributes
2723 ESC c Reset to Initial State
2725 ESC Pn p Cursor Visibility (97801)
2728 ESC = (V) Application Keypad Mode
2729 ESC > (V) Numeric Keypad Mode
2730 ESC # 8 (V) Fill Screen with E's
2731 ESC \ (A) String Terminator
2732 ESC ^ (A) Privacy Message String (Message Line)
2733 ESC ! Global Message String (Message Line)
2734 ESC k Title Definition String
2735 ESC P (A) Device Control String
2736 Outputs a string directly to the host
2737 terminal without interpretation.
2738 ESC _ (A) Application Program Command (Hardstatus)
2739 ESC ] 0 ; string ^G (A) Operating System Command (Hardstatus, xterm
2741 ESC ] 83 ; cmd ^G (A) Execute screen command. This only works if
2742 multi-user support is compiled into screen.
2743 The pseudo-user ":window:" is used to check
2744 the access control list. Use "addacl :window:
2745 -rwx #?" to create a user with no rights and
2746 allow only the needed commands.
2747 Control-N (A) Lock Shift G1 (SO)
2748 Control-O (A) Lock Shift G0 (SI)
2749 ESC n (A) Lock Shift G2
2750 ESC o (A) Lock Shift G3
2751 ESC N (A) Single Shift G2
2752 ESC O (A) Single Shift G3
2753 ESC ( Pcs (A) Designate character set as G0
2754 ESC ) Pcs (A) Designate character set as G1
2755 ESC * Pcs (A) Designate character set as G2
2756 ESC + Pcs (A) Designate character set as G3
2757 ESC [ Pn ; Pn H Direct Cursor Addressing
2758 ESC [ Pn ; Pn f same as above
2759 ESC [ Pn J Erase in Display
2760 Pn = None or 0 From Cursor to End of Screen
2761 1 From Beginning of Screen to Cursor
2763 ESC [ Pn K Erase in Line
2764 Pn = None or 0 From Cursor to End of Line
2765 1 From Beginning of Line to Cursor
2767 ESC [ Pn X Erase character
2768 ESC [ Pn A Cursor Up
2769 ESC [ Pn B Cursor Down
2770 ESC [ Pn C Cursor Right
2771 ESC [ Pn D Cursor Left
2772 ESC [ Pn E Cursor next line
2773 ESC [ Pn F Cursor previous line
2774 ESC [ Pn G Cursor horizontal position
2775 ESC [ Pn ` same as above
2776 ESC [ Pn d Cursor vertical position
2777 ESC [ Ps ;...; Ps m Select Graphic Rendition
2778 Ps = None or 0 Default Rendition
2781 3 (A) @i{Standout} Mode (ANSI: Italicized)
2785 22 (A) Normal Intensity
2786 23 (A) @i{Standout} Mode off (ANSI: Italicized off)
2787 24 (A) Not Underlined
2789 27 (A) Positive Image
2790 30 (A) Foreground Black
2791 31 (A) Foreground Red
2792 32 (A) Foreground Green
2793 33 (A) Foreground Yellow
2794 34 (A) Foreground Blue
2795 35 (A) Foreground Magenta
2796 36 (A) Foreground Cyan
2797 37 (A) Foreground White
2798 39 (A) Foreground Default
2799 40 (A) Background Black
2801 49 (A) Background Default
2802 ESC [ Pn g Tab Clear
2803 Pn = None or 0 Clear Tab at Current Position
2805 ESC [ Pn ; Pn r (V) Set Scrolling Region
2806 ESC [ Pn I (A) Horizontal Tab
2807 ESC [ Pn Z (A) Backward Tab
2808 ESC [ Pn L (A) Insert Line
2809 ESC [ Pn M (A) Delete Line
2810 ESC [ Pn @@ (A) Insert Character
2811 ESC [ Pn P (A) Delete Character
2812 ESC [ Pn S Scroll Scrolling Region Up
2813 ESC [ Pn T Scroll Scrolling Region Down
2814 ESC [ Pn ^ same as above
2815 ESC [ Ps ;...; Ps h Set Mode
2816 ESC [ Ps ;...; Ps l Reset Mode
2817 Ps = 4 (A) Insert Mode
2818 20 (A) @samp{Automatic Linefeed} Mode.
2819 34 Normal Cursor Visibility
2820 ?1 (V) Application Cursor Keys
2821 ?3 (V) Change Terminal Width to 132 columns
2822 ?5 (V) Reverse Video
2823 ?6 (V) @samp{Origin} Mode
2824 ?7 (V) @samp{Wrap} Mode
2825 ?9 X10 mouse tracking
2826 ?25 (V) Visible Cursor
2827 ?47 Alternate Screen (old xterm code)
2828 ?1000 (V) VT200 mouse tracking
2829 ?1047 Alternate Screen (new xterm code)
2830 ?1049 Alternate Screen (new xterm code)
2831 ESC [ 5 i (A) Start relay to printer (ANSI Media Copy)
2832 ESC [ 4 i (A) Stop relay to printer (ANSI Media Copy)
2833 ESC [ 8 ; Ph ; Pw t Resize the window to @samp{Ph} lines and
2834 @samp{Pw} columns (SunView special)
2835 ESC [ c Send VT100 Identification String
2836 ESC [ x (V) Send Terminal Parameter Report
2837 ESC [ > c Send Secondary Device Attributes String
2838 ESC [ 6 n Send Cursor Position Report
2843 @node Input Translation, Digraph, Control Sequences, Virtual Terminal
2844 @section Input Translation
2845 @cindex input translation
2846 In order to do a full VT100 emulation @code{screen} has to detect
2847 that a sequence of characters in the input stream was generated
2848 by a keypress on the user's keyboard and insert the VT100
2849 style escape sequence. @code{Screen} has a very flexible way of doing
2850 this by making it possible to map arbitrary commands on arbitrary
2851 sequences of characters. For standard VT100 emulation the command
2852 will always insert a string in the input buffer of the window
2853 (see also command @code{stuff}, @pxref{Paste}).
2854 Because the sequences generated by a keypress can
2855 change after a reattach from a different terminal type, it is
2856 possible to bind commands to the termcap name of the keys.
2857 @code{Screen} will insert the correct binding after each
2858 reattach. See @ref{Bindkey} for further details on the syntax and examples.
2860 Here is the table of the default key bindings. (A) means that the
2861 command is executed if the keyboard is switched into application
2865 Key name Termcap name Command
2866 -----------------------------------------------------
2867 Cursor up ku stuff \033[A
2869 Cursor down kd stuff \033[B
2871 Cursor right kr stuff \033[C
2873 Cursor left kl stuff \033[D
2875 Function key 0 k0 stuff \033[10~
2876 Function key 1 k1 stuff \033OP
2877 Function key 2 k2 stuff \033OQ
2878 Function key 3 k3 stuff \033OR
2879 Function key 4 k4 stuff \033OS
2880 Function key 5 k5 stuff \033[15~
2881 Function key 6 k6 stuff \033[17~
2882 Function key 7 k7 stuff \033[18~
2883 Function key 8 k8 stuff \033[19~
2884 Function key 9 k9 stuff \033[20~
2885 Function key 10 k; stuff \033[21~
2886 Function key 11 F1 stuff \033[23~
2887 Function key 12 F2 stuff \033[24~
2888 Home kh stuff \033[1~
2889 End kH stuff \033[4~
2890 Insert kI stuff \033[2~
2891 Delete kD stuff \033[3~
2892 Page up kP stuff \033[5~
2893 Page down kN stuff \033[6~
2928 Keypad enter fe stuff \015
2932 @node Digraph, Bell, Input Translation, Virtual Terminal
2936 @deffn Command digraph [preset [unicode-value]]
2938 This command prompts the user for a digraph sequence. The next
2939 two characters typed are looked up in a builtin table and the
2940 resulting character is inserted in the input stream. For example,
2941 if the user enters @samp{a"}, an a-umlaut will be inserted. If the
2942 first character entered is a 0 (zero), @code{screen}
2943 will treat the following characters (up to three) as an octal
2944 number instead. The optional argument @var{preset}
2945 is treated as user input, thus one can create an "umlaut" key.
2946 For example the command @samp{bindkey ^K digraph '"'} enables the user
2947 to generate an a-umlaut by typing @samp{CTRL-K a}. When a non-zero
2948 @var{unicode-value} is specified, a new digraph is created with the
2949 specified preset. The digraph is unset if a zero value is provided
2950 for the @var{unicode-value}.
2952 The following table is the builtin sequences.
2954 @documentencoding ISO-8859-1
2956 Sequence Octal Digraph Unicode Equivalent
2957 -----------------------------------------------
2958 ' ', ' ' 160 (space) U+00A0
2959 'N', 'S' 160 (space) U+00A0
2960 '~', '!' 161 ¡ U+00A1
2961 '!', '!' 161 ¡ U+00A1
2962 '!', 'I' 161 ¡ U+00A1
2963 'c', '|' 162 ¢ U+00A2
2964 'c', 't' 162 ¢ U+00A2
2965 '$', '$' 163 £ U+00A3
2966 'P', 'd' 163 £ U+00A3
2967 'o', 'x' 164 ¤ U+00A4
2968 'C', 'u' 164 ¤ U+00A4
2969 'C', 'u' 164 ¤ U+00A4
2970 'E', 'u' 164 ¤ U+00A4
2971 'Y', '-' 165 ¥ U+00A5
2972 'Y', 'e' 165 ¥ U+00A5
2973 '|', '|' 166 ¦ U+00A6
2974 'B', 'B' 166 ¦ U+00A6
2975 'p', 'a' 167 § U+00A7
2976 'S', 'E' 167 § U+00A7
2977 '"', '"' 168 ¨ U+00A8
2978 ''', ':' 168 ¨ U+00A8
2979 'c', 'O' 169 © U+00A9
2980 'C', 'o' 169 © U+00A9
2981 'a', '-' 170 ª U+00AA
2982 '<', '<' 171 « U+00AB
2983 '-', ',' 172 ¬ U+00AC
2984 'N', 'O' 172 ¬ U+00AC
2985 '-', '-' 173 U+00AD
2986 'r', 'O' 174 ® U+00AE
2987 'R', 'g' 174 ® U+00AE
2988 '-', '=' 175 ¯ U+00AF
2989 ''', 'm' 175 ¯ U+00AF
2990 '~', 'o' 176 ° U+00B0
2991 'D', 'G' 176 ° U+00B0
2992 '+', '-' 177 ± U+00B1
2993 '2', '2' 178 ² U+00B2
2994 '2', 'S' 178 ² U+00B2
2995 '3', '3' 179 ³ U+00B3
2996 '3', 'S' 179 ³ U+00B3
2997 ''', ''' 180 ´ U+00B4
2998 'j', 'u' 181 µ U+00B5
2999 'M', 'y' 181 µ U+00B5
3000 'p', 'p' 182 ¶ U+00B6
3001 'P', 'I' 182 ¶ U+00B6
3002 '~', '.' 183 · U+00B7
3003 '.', 'M' 183 · U+00B7
3004 ',', ',' 184 ¸ U+00B8
3005 ''', ',' 184 ¸ U+00B8
3006 '1', '1' 185 ¹ U+00B9
3007 '1', 'S' 185 ¹ U+00B9
3008 'o', '-' 186 º U+00BA
3009 '>', '>' 187 » U+00BB
3010 '1', '4' 188 ¼ U+00BC
3011 '1', '2' 189 ½ U+00BD
3012 '3', '4' 190 ¾ U+00BE
3013 '~', '?' 191 ¿ U+00BF
3014 '?', '?' 191 ¿ U+00BF
3015 '?', 'I' 191 ¿ U+00BF
3016 'A', '`' 192 À U+00C0
3017 'A', '!' 192 À U+00C0
3018 'A', ''' 193 Á U+00C1
3019 'A', '^' 194 Â U+00C2
3020 'A', '>' 194 Â U+00C2
3021 'A', '~' 195 Ã U+00C3
3022 'A', '?' 195 Ã U+00C3
3023 'A', '"' 196 Ä U+00C4
3024 'A', ':' 196 Ä U+00C4
3025 'A', '@@' 197 Å U+00C5
3026 'A', 'A' 197 Å U+00C5
3027 'A', 'E' 198 Æ U+00C6
3028 'C', ',' 199 Ç U+00C7
3029 'E', '`' 200 È U+00C8
3030 'E', '!' 200 È U+00C8
3031 'E', ''' 201 É U+00C9
3032 'E', '^' 202 Ê U+00CA
3033 'E', '>' 202 Ê U+00CA
3034 'E', '"' 203 Ë U+00CB
3035 'E', ':' 203 Ë U+00CB
3036 'I', '`' 204 Ì U+00CC
3037 'I', '!' 204 Ì U+00CC
3038 'I', ''' 205 Í U+00CD
3039 'I', '^' 206 Î U+00CE
3040 'I', '>' 206 Î U+00CE
3041 'I', '"' 207 Ï U+00CF
3042 'I', ':' 207 Ï U+00CF
3043 'D', '-' 208 Ð U+00D0
3044 'N', '~' 209 Ñ U+00D1
3045 'N', '?' 209 Ñ U+00D1
3046 'O', '`' 210 Ò U+00D2
3047 'O', '!' 210 Ò U+00D2
3048 'O', ''' 211 Ó U+00D3
3049 'O', '^' 212 Ô U+00D4
3050 'O', '>' 212 Ô U+00D4
3051 'O', '~' 213 Õ U+00D5
3052 'O', '?' 213 Õ U+00D5
3053 'O', '"' 214 Ö U+00D6
3054 'O', ':' 214 Ö U+00D6
3055 '/', '\' 215 × U+00D7
3056 '*', 'x' 215 × U+00D7
3057 'O', '/' 216 Ø U+00D8
3058 'U', '`' 217 Ù U+00D9
3059 'U', '!' 217 Ù U+00D9
3060 'U', ''' 218 Ú U+00DA
3061 'U', '^' 219 Û U+00DB
3062 'U', '>' 219 Û U+00DB
3063 'U', '"' 220 Ü U+00DC
3064 'U', ':' 220 Ü U+00DC
3065 'Y', ''' 221 Ý U+00DD
3066 'I', 'p' 222 Þ U+00DE
3067 'T', 'H' 222 Þ U+00DE
3068 's', 's' 223 ß U+00DF
3069 's', '"' 223 ß U+00DF
3070 'a', '`' 224 à U+00E0
3071 'a', '!' 224 à U+00E0
3072 'a', ''' 225 á U+00E1
3073 'a', '^' 226 â U+00E2
3074 'a', '>' 226 â U+00E2
3075 'a', '~' 227 ã U+00E3
3076 'a', '?' 227 ã U+00E3
3077 'a', '"' 228 ä U+00E4
3078 'a', ':' 228 ä U+00E4
3079 'a', 'a' 229 å U+00E5
3080 'a', 'e' 230 æ U+00E6
3081 'c', ',' 231 ç U+00E7
3082 'e', '`' 232 è U+00E8
3083 'e', '!' 232 è U+00E8
3084 'e', ''' 233 é U+00E9
3085 'e', '^' 234 ê U+00EA
3086 'e', '>' 234 ê U+00EA
3087 'e', '"' 235 ë U+00EB
3088 'e', ':' 235 ë U+00EB
3089 'i', '`' 236 ì U+00EC
3090 'i', '!' 236 ì U+00EC
3091 'i', ''' 237 í U+00ED
3092 'i', '^' 238 î U+00EE
3093 'i', '>' 238 î U+00EE
3094 'i', '"' 239 ï U+00EF
3095 'i', ':' 239 ï U+00EF
3096 'd', '-' 240 ð U+00F0
3097 'n', '~' 241 ñ U+00F1
3098 'n', '?' 241 ñ U+00F1
3099 'o', '`' 242 ò U+00F2
3100 'o', '!' 242 ò U+00F2
3101 'o', ''' 243 ó U+00F3
3102 'o', '^' 244 ô U+00F4
3103 'o', '>' 244 ô U+00F4
3104 'o', '~' 245 õ U+00F5
3105 'o', '?' 245 õ U+00F5
3106 'o', '"' 246 ö U+00F6
3107 'o', ':' 246 ö U+00F6
3108 ':', '-' 247 ÷ U+00F7
3109 'o', '/' 248 ø U+00F8
3110 'u', '`' 249 ù U+00F9
3111 'u', '!' 249 ù U+00F9
3112 'u', ''' 250 ú U+00FA
3113 'u', '^' 251 û U+00FB
3114 'u', '>' 251 û U+00FB
3115 'u', '"' 252 ü U+00FC
3116 'u', ':' 252 ü U+00FC
3117 'y', ''' 253 ý U+00FD
3118 'i', 'p' 254 þ U+00FE
3119 't', 'h' 254 þ U+00FE
3120 'y', '"' 255 ÿ U+00FF
3121 'y', ':' 255 ÿ U+00FF
3122 '"', '[' 196 Ä U+00C4
3123 '"', '\' 214 Ö U+00D6
3124 '"', ']' 220 Ü U+00DC
3125 '"', '@{' 228 ä U+00E4
3126 '"', '|' 246 ö U+00F6
3127 '"', '@}' 252 ü U+00FC
3128 '"', '~' 223 ß U+00DF
3133 @node Bell, Clear, Digraph, Virtual Terminal
3136 @deffn Command bell_msg [message]
3138 When a bell character is sent to a background window, @code{screen}
3139 displays a notification in the message line. The notification message
3140 can be re-defined by this command. Each occurrence
3141 of @samp{%} in @var{message} is replaced by the number of the window to
3142 which a bell has been sent, and each occurrence of @samp{^G} is replaced
3143 by the definition for bell in your termcap (usually an audible bell).
3144 The default message is
3150 An empty message can be supplied to the @code{bell_msg} command to suppress
3151 output of a message line (@code{bell_msg ""}).
3152 Without a parameter, the current message is shown.
3156 @deffn Command vbell [state]
3158 Sets or toggles the visual bell setting for the current window. If
3159 @code{vbell} is switched to @samp{on}, but your
3160 terminal does not support a visual bell, the visual bell message is
3161 displayed in the status line when the bell character is received.
3162 Visual bell support of a terminal is
3163 defined by the termcap variable @code{vb}. @xref{Bell, , Visual Bell,
3164 termcap, The Termcap Manual}, for more information on visual bells.
3165 The equivalent terminfo capability is @code{flash}.
3167 Per default, @code{vbell} is @samp{off}, thus the audible bell is used.
3170 @deffn Command vbell_msg [message]
3172 Sets the visual bell message. @var{Message} is printed to the status
3173 line if the window receives a bell character (^G), @code{vbell} is
3174 set to @samp{on} and the terminal does not support a visual bell.
3175 The default message is @samp{Wuff, Wuff!!}.
3176 Without a parameter, the current message is shown.
3179 @deffn Command vbellwait sec
3181 Define a delay in seconds after each display of @code{screen} 's visual
3182 bell message. The default is 1 second.
3185 @node Clear, Info, Bell, Virtual Terminal
3188 @deffn Command clear
3190 Clears the screen and saves its contents to the scrollback buffer.
3193 @node Info, Redisplay, Clear, Virtual Terminal
3198 (@kbd{C-a i}, @kbd{C-a C-i})@*
3199 Uses the message line to display some information about the current
3200 window: the cursor position in the form @samp{(@var{column},@var{row})}
3201 starting with @samp{(1,1)}, the terminal width and height plus the size
3202 of the scrollback buffer in lines, like in @samp{(80,24)+50},
3203 the current state of window XON/XOFF flow control is shown like this
3204 (@pxref{Flow Control}):
3206 +flow automatic flow control, currently on.
3207 -flow automatic flow control, currently off.
3208 +(+)flow flow control enabled. Agrees with automatic control.
3209 -(+)flow flow control disabled. Disagrees with automatic control.
3210 +(-)flow flow control enabled. Disagrees with automatic control.
3211 -(-)flow flow control disabled. Agrees with automatic control.
3214 The current line wrap setting (@samp{+wrap} indicates enabled, @samp{-wrap}
3215 not) is also shown. The flags @samp{ins}, @samp{org}, @samp{app}, @samp{log},
3216 @samp{mon} and @samp{nored} are displayed when the window is in insert mode,
3217 origin mode, application-keypad mode, has output logging,
3218 activity monitoring or partial redraw enabled.
3220 The currently active
3221 character set (@samp{G0}, @samp{G1}, @samp{G2}, or @samp{G3}), and in
3222 square brackets the terminal character sets that are currently
3223 designated as @samp{G0} through @samp{G3}.
3224 If the window is in UTF-8 mode, the string @samp{UTF-8} is shown instead.
3225 Additional modes depending on the type of the window are displayed at
3226 the end of the status line (@pxref{Window Types}).
3228 If the state machine of the terminal emulator is in a non-default state,
3229 the info line is started with a string identifying the current state.
3231 For system information use @code{time}.
3234 @deffn Command dinfo
3236 Show what @code{screen} thinks about your terminal. Useful if you want to know
3237 why features like color or the alternate charset don't work.
3240 @node Redisplay, Wrap, Info, Virtual Terminal
3243 @deffn Command allpartial state
3245 If set to on, only the current cursor line is refreshed on window change.
3246 This affects all windows and is useful for slow terminal lines. The
3247 previous setting of full/partial refresh for each window is restored
3248 with @code{allpartial off}. This is a global flag that immediately takes effect
3249 on all windows overriding the @code{partial} settings. It does not change the
3250 default redraw behavior of newly created windows.
3253 @deffn Command altscreen state
3255 If set to on, "alternate screen" support is enabled in virtual terminals,
3256 just like in xterm. Initial setting is @samp{off}.
3259 @deffn Command partial state
3261 Defines whether the display should be refreshed (as with
3262 @code{redisplay}) after switching to the current window. This command
3263 only affects the current window. To immediately affect all windows use the
3264 @code{allpartial} command. Default is @samp{off}, of course. This default is
3265 fixed, as there is currently no @code{defpartial} command.
3270 @deffn Command redisplay
3271 (@kbd{C-a l}, @kbd{C-a C-l})@*
3272 Redisplay the current window. Needed to get a full redisplay in
3273 partial redraw mode.
3276 @node Wrap, Reset, Redisplay, Virtual Terminal
3281 @deffn Command wrap state
3282 (@kbd{C-a r}, @kbd{C-a C-r}) @*
3283 Sets the line-wrap setting for the current window. When line-wrap is
3284 on, the second consecutive printable character output at the last column
3285 of a line will wrap to the start of the following line. As an added
3286 feature, backspace (^H) will also wrap through the left margin to the
3287 previous line. Default is @samp{on}.
3290 @deffn Command defwrap state
3292 Same as the @code{wrap} command except that the default setting for new
3293 windows is changed. Initially line-wrap is on and can be toggled with the
3294 @code{wrap} command (@kbd{C-a r}) or by means of "C-a : wrap on|off".
3297 @node Reset, Window Size, Wrap, Virtual Terminal
3300 @deffn Command reset
3302 Reset the virtual terminal to its ``power-on'' values. Useful when strange
3303 settings (like scroll regions or graphics character set) are left over from
3307 @node Window Size, Character Processing, Reset, Virtual Terminal
3308 @section Window Size
3310 @deffn Command width [@code{-w}|@code{-d}] [cols [lines]]
3312 Toggle the window width between 80 and 132 columns, or set it to
3313 @var{cols} columns if an argument is specified. This requires a
3314 capable terminal and the termcap entries @samp{Z0} and @samp{Z1}. See
3315 the @code{termcap} command (@pxref{Termcap}), for more information.
3316 You can also specify a height if you want to
3317 change both values. The @code{-w} option tells screen to leave
3318 the display size unchanged and just set the window size,
3319 @code{-d} vice versa.
3322 @deffn Command height [@code{-w}|@code{-d}] [lines [cols]]
3324 Set the display height to a specified number of lines. When no
3325 argument is given it toggles between 24 and 42 lines display.
3328 @node Character Processing, ,Window Size, Virtual Terminal
3329 @section Character Processing
3331 @deffn Command c1 [state]
3333 Change c1 code processing. @samp{c1 on} tells screen to treat
3334 the input characters between 128 and 159 as control functions.
3335 Such an 8-bit code is normally the same as ESC followed by the
3336 corresponding 7-bit code. The default setting is to process c1
3337 codes and can be changed with the @samp{defc1} command.
3338 Users with fonts that have usable characters in the
3339 c1 positions may want to turn this off.
3342 @deffn Command gr [state]
3344 Turn GR charset switching on/off. Whenever screen sees an input
3345 char with an 8th bit set, it will use the charset stored in the
3346 GR slot and print the character with the 8th bit stripped. The
3347 default (see also @samp{defgr}) is not to process GR switching because
3348 otherwise the ISO88591 charset would not work.
3351 @deffn Command bce [state]
3353 Change background-color-erase setting. If @samp{bce} is set to
3354 on, all characters cleared by an erase/insert/scroll/clear
3355 operation will be displayed in the current background color.
3356 Otherwise the default background color is used.
3359 @deffn Command encoding enc [denc]
3361 Tell screen how to interpret the input/output. The first argument
3362 sets the encoding of the current window.
3363 Each window can emulate a different encoding. The optional second
3364 parameter overwrites the encoding of the connected terminal.
3365 It should never be needed as screen uses the locale setting to detect
3367 There is also a way to select a terminal encoding depending on
3368 the terminal type by using the @samp{KJ} termcap entry. @xref{Special Capabilities}.
3370 Supported encodings are
3371 @code{eucJP}, @code{SJIS}, @code{eucKR},
3372 @code{eucCN}, @code{Big5}, @code{GBK}, @code{KOI8-R}, @code{CP1251},
3373 @code{UTF-8}, @code{ISO8859-2}, @code{ISO8859-3},
3374 @code{ISO8859-4}, @code{ISO8859-5}, @code{ISO8859-6},
3375 @code{ISO8859-7}, @code{ISO8859-8}, @code{ISO8859-9},
3376 @code{ISO8859-10}, @code{ISO8859-15}, @code{jis}.
3378 See also @samp{defencoding}, which changes the default setting of a new
3382 @deffn Command charset set
3384 Change the current character set slot designation and charset
3385 mapping. The first four character of @var{set}
3386 are treated as charset designators while the fifth and sixth
3387 character must be in range @samp{0} to @samp{3} and set the GL/GR
3388 charset mapping. On every position a @samp{.} may be used to indicate
3389 that the corresponding charset/mapping should not be changed
3390 (@var{set} is padded to six characters internally by appending
3391 @samp{.} chars). New windows have @samp{BBBB02} as default
3392 charset, unless a @samp{encoding} command is active.
3394 The current setting can be viewed with the @ref{Info} command.
3397 @deffn Command utf8 [state [dstate]]
3399 Change the encoding used in the current window. If utf8 is enabled, the
3400 strings sent to the window will be UTF-8 encoded and vice versa.
3402 parameter toggles the setting. If a second parameter is given, the
3404 encoding is also changed (this should rather be done with screen's
3406 See also @samp{defutf8}, which changes the default setting of a new
3410 @deffn Command defc1 state
3412 Same as the @samp{c1} command except that the default setting for
3413 new windows is changed. Initial setting is @samp{on}.
3416 @deffn Command defgr state
3418 Same as the @samp{gr} command except that the default setting for
3419 new windows is changed. Initial setting is @samp{off}.
3422 @deffn Command defbce state
3424 Same as the @samp{bce} command except that the default setting for
3425 new windows is changed. Initial setting is @samp{off}.
3428 @deffn Command defencoding enc
3430 Same as the @samp{encoding} command except that the default setting for
3431 new windows is changed. Initial setting is the encoding taken from the
3435 @deffn Command defcharset [set]
3436 Like the @samp{charset} command except that the default setting for
3437 new windows is changed. Shows current default if called without
3441 @deffn Command defutf8 state
3443 Same as the @samp{utf8} command except that the default setting for new
3444 windows is changed. Initial setting is @code{on} if screen was started
3445 with @samp{-U}, otherwise @code{off}.
3448 @node Copy and Paste, Subprocess Execution, Virtual Terminal, Top
3449 @chapter Copy and Paste
3450 @cindex copy and paste
3452 For those confined to a hardware terminal, these commands provide a cut
3453 and paste facility more powerful than those provided by most windowing
3457 * Copy:: Copy from scrollback to buffer
3458 * Paste:: Paste from buffer into window
3459 * Registers:: Longer-term storage
3460 * Screen Exchange:: Sharing data between screen users
3461 * History:: Recalling previous input
3464 @node Copy, Paste, , Copy and Paste
3472 (@kbd{C-a [}, @kbd{C-a C-[}, @kbd{C-a @key{ESC}})@*
3473 Enter copy/scrollback mode. This allows you to copy text from the
3474 current window and its history into the paste buffer. In this mode a
3475 @code{vi}-like full screen editor is active, with controls as
3480 * Line Termination:: End copied lines with CR/LF
3481 * Scrollback:: Set the size of the scrollback buffer
3482 * Copy Mode Keys:: Remap keys in copy mode
3483 * Movement:: Move around in the scrollback buffer
3484 * Marking:: Select the text you want
3485 * Repeat count:: Repeat a command
3486 * Searching:: Find the text you want
3487 * Specials:: Other random keys
3490 @node Line Termination, Scrollback, , Copy
3492 @deffn Command crlf [state]
3494 This affects the copying of text regions with the @code{copy} command.
3495 If it is set to @samp{on}, lines will be separated by the two character
3496 sequence @samp{CR}/@samp{LF}. Otherwise only @samp{LF} is used.
3497 @code{crlf} is off by default.
3498 When no parameter is given, the state is toggled.
3501 @node Scrollback, Copy Mode Keys, Line Termination, Copy
3502 @subsection Scrollback
3503 To access and use the contents in the scrollback buffer, use the @code{copy} command. @xref{Copy}.
3504 @deffn Command defscrollback num
3506 Same as the @code{scrollback} command except that the default setting
3507 for new windows is changed. Defaults to 100.
3510 @deffn Command scrollback num
3512 Set the size of the scrollback buffer for the current window to
3513 @var{num} lines. The default scrollback is 100 lines. Use @code{info}
3514 to view the current setting.
3517 @deffn Command compacthist [state]
3519 This tells screen whether to suppress trailing blank lines when
3520 scrolling up text into the history buffer. Turn compacting @samp{on}
3521 to hold more useful lines in your scrollback buffer.
3524 @node Copy Mode Keys, Movement, Scrollback, Copy
3525 @subsection markkeys
3526 @deffn Command markkeys string
3528 This is a method of changing the keymap used for copy/history mode. The
3529 string is made up of @var{oldchar}=@var{newchar} pairs which are
3530 separated by @samp{:}. Example: The command @code{markkeys
3531 h=^B:l=^F:$=^E} would set some keys to be more familiar to @code{emacs}
3533 If your terminal sends characters, that cause you to abort copy mode,
3534 then this command may help by binding these characters to do nothing.
3535 The no-op character is `@@' and is used like this: @code{markkeys @@=L=H}
3536 if you do not want to use the `H' or `L' commands any longer.
3537 As shown in this example, multiple keys can be assigned to one function
3538 in a single statement.
3541 @node Movement, Marking, Copy Mode Keys, Copy
3542 @subsection Movement Keys
3545 @kbd{h}, @kbd{C-h}, or @kbd{left arrow} move the cursor left.
3548 @kbd{j}, @kbd{C-n}, or @kbd{down arrow} move the cursor down.
3551 @kbd{k}, @kbd{C-p}, or @kbd{up arrow} move the cursor up.
3554 @kbd{l} ('el'), or @kbd{right arrow} move the cursor right.
3557 @kbd{0} (zero) or @kbd{C-a} move to the leftmost column.
3560 @kbd{+} and @kbd{-} move the cursor to the leftmost column of the next
3564 @kbd{H}, @kbd{M} and @kbd{L} move the cursor to the leftmost column
3565 of the top, center or bottom line of the window.
3568 @kbd{|} moves to the specified absolute column.
3571 @kbd{g} or @kbd{home} moves to the beginning of the buffer.
3574 @kbd{G} or @kbd{end} moves to the specified absolute line (default: end of buffer).
3577 @kbd{%} jumps to the specified percentage of the buffer.
3580 @kbd{^} or @kbd{$} move to the first
3581 or last non-whitespace character on the line.
3584 @kbd{w}, @kbd{b}, and @kbd{e} move the cursor word by word.
3587 @kbd{B}, @kbd{E} move the cursor WORD by WORD (as in vi).
3590 @kbd{f}/@kbd{F}, @kbd{t}/@kbd{T} move the cursor forward/backward to the
3591 next occurence of the target. (eg, '3fy' will move the cursor to the 3rd
3595 @kbd{;} and @kbd{,} Repeat the last f/F/t/T command in the same/opposite direction.
3598 @kbd{C-e} and @kbd{C-y} scroll the display up/down by one line
3599 while preserving the cursor position.
3602 @kbd{C-u} and @kbd{C-d} scroll the display up/down by the specified
3603 amount of lines while preserving the cursor position. (Default: half
3607 @kbd{C-b} and @kbd{C-f} move the cursor up/down a full screen.
3609 Note that Emacs-style movement keys can be specified by a .screenrc
3610 command. (@code{markkeys "h=^B:l=^F:$=^E"}) There is no simple method for
3611 a full emacs-style keymap, however, as this involves multi-character codes.
3613 @node Marking, Repeat count, Movement, Copy
3616 The copy range is specified by setting two marks. The text between these
3617 marks will be highlighted. Press:
3620 @kbd{space} or @kbd{enter} to set the first or second mark respectively.
3621 If @code{mousetrack} is set to @code{on}, marks can also be set using
3622 @kbd{left mouse click}.
3625 @kbd{Y} and @kbd{y} can be used to mark one whole line or to mark from
3629 @kbd{W} marks exactly one word.
3631 @node Repeat count, Searching, Marking, Copy
3632 @subsection Repeat Count
3634 Any command in copy mode can be prefixed with a number (by pressing
3635 digits @kbd{0@dots{}9}) which is taken as a repeat count. Example:
3637 @kbd{C-a C-[ H 10 j 5 Y}
3640 will copy lines 11 to 15 into the paste buffer.
3642 @node Searching, Specials, Repeat count, Copy
3643 @subsection Searching
3646 @kbd{/} @code{vi}-like search forward.
3649 @kbd{?} @code{vi}-like search backward.
3652 @kbd{C-a s} @code{emacs} style incremental search forward.
3655 @kbd{C-r} @code{emacs} style reverse i-search.
3657 @deffn Command ignorecase [state]
3659 Tell screen to ignore the case of characters in searches. Default is
3664 @kbd{n} Repeat search in forward direction.
3667 @kbd{N} Repeat search in backward direction.
3669 @node Specials, , Searching, Copy
3670 @subsection Specials
3672 There are, however, some keys that act differently here from in
3673 @code{vi}. @code{Vi} does not allow to yank rectangular blocks of text,
3674 but @code{screen} does. Press:
3677 @kbd{c} or @kbd{C} to set the left or right margin respectively. If no
3678 repeat count is given, both default to the current cursor position.@*
3679 Example: Try this on a rather full text screen:
3681 @kbd{C-a [ M 20 l SPACE c 10 l 5 j C SPACE}.
3685 This moves one to the middle line of the screen, moves in 20 columns left,
3686 marks the beginning of the paste buffer, sets the left column, moves 5 columns
3687 down, sets the right column, and then marks the end of
3688 the paste buffer. Now try:
3690 @kbd{C-a [ M 20 l SPACE 10 l 5 j SPACE}
3694 and notice the difference in the amount of text copied.
3697 @kbd{J} joins lines. It toggles between 4 modes: lines separated by a
3698 newline character (012), lines glued seamless, lines separated by a single
3699 space or comma separated lines. Note that you can prepend the newline
3700 character with a carriage return character, by issuing a @code{set crlf
3704 @kbd{v} or @kbd{V} is for all the @code{vi} users who use @code{:set numbers} - it
3705 toggles the left margin between column 9 and 1.
3708 @kbd{a} before the final @kbd{space} key turns on append mode. Thus
3709 the contents of the paste buffer will not be overwritten, but appended to.
3712 @kbd{A} turns on append mode and sets a (second) mark.
3715 @kbd{>} sets the (second) mark and writes the contents of the paste buffer
3716 to the screen-exchange file (@file{/tmp/screen-exchange} per default)
3717 once copy-mode is finished. @xref{Screen Exchange}.@*
3718 This example demonstrates how to dump the
3719 whole scrollback buffer to that file:
3721 @kbd{C-a [ g SPACE G $ >}.
3725 @kbd{C-g} gives information about the current line and column.
3728 @kbd{x} or @kbd{o} ('oh') exchanges the first mark and the current cursor position. You
3729 can use this to adjust an already placed mark.
3732 @kbd{C-l} ('el') will redraw the screen.
3735 @kbd{@@} does nothing. Absolutely nothing. Does not even exit copy
3739 All keys not described here exit copy mode.
3741 @node Paste, Registers, Copy, Copy and Paste
3746 @deffn Command paste [registers [destination]]
3747 (@kbd{C-a ]}, @kbd{C-a C-]})@*
3748 Write the (concatenated) contents of the specified registers to the stdin
3749 stream of the current window. The register @samp{.} is treated as the
3750 paste buffer. If no parameter is specified the user is prompted to enter a
3751 single register. The paste buffer can be filled with the
3752 @code{copy}, @code{history} and @code{readbuf} commands.
3753 Other registers can be filled with the @code{register}, @code{readreg} and
3754 @code{paste} commands.
3755 If @code{paste} is called with a second argument, the contents of the specified
3756 registers is pasted into the named destination register rather than
3757 the window. If @samp{.} is used as the second argument, the display's paste
3758 buffer is the destination.
3759 Note, that @code{paste} uses a wide variety of resources: Usually both, a
3760 current window and a current display are required. But whenever a second
3761 argument is specified no current window is needed. When the source specification
3762 only contains registers (not the paste buffer) then there need not be a current
3763 display (terminal attached), as the registers are a global resource. The
3764 paste buffer exists once for every user.
3767 @deffn Command stuff [string]
3769 Stuff the string @var{string} in the input buffer of the current window.
3770 This is like the @code{paste} command, but with much less overhead.
3771 Without a paramter, @code{screen} will prompt for a string to stuff.
3772 You cannot paste large buffers with the @code{stuff} command. It is most
3773 useful for key bindings. @xref{Bindkey}.
3776 @deffn Command pastefont [state]
3777 Tell screen to include font information in the paste buffer. The
3778 default is not to do so. This command is especially useful for
3779 multi character fonts like kanji.
3782 @deffn Command slowpaste msec
3783 @deffnx Command defslowpaste msec
3785 Define the speed text is inserted in the current window by the @code{paste}
3786 command. If the slowpaste value is nonzero text is written character by
3788 @code{screen} will pause for @var{msec} milliseconds after each write
3789 to allow the application to process the input. only use @code{slowpaste} if
3790 your underlying system exposes flow control problems while pasting large
3792 @code{defslowpaste} specifies the default for new windows.
3795 @deffn Command readreg [-e encoding] [register [filename]]
3797 Does one of two things, dependent on number of arguments: with zero or one
3798 arguments it it duplicates the paste buffer contents into the register specified
3799 or entered at the prompt. With two arguments it reads the contents of the named
3800 file into the register, just as @code{readbuf} reads the screen-exchange file
3801 into the paste buffer.
3802 You can tell screen the encoding of the file via the @code{-e} option.
3803 The following example will paste the system's password file into
3804 the screen window (using register p, where a copy remains):
3807 C-a : readreg p /etc/passwd
3812 @node Registers, Screen Exchange, Paste, Copy and Paste
3815 @deffn Command copy_reg [key]
3817 Removed. Use @code{readreg} instead.
3820 @deffn Command ins_reg [key]
3822 Removed. Use @code{paste} instead.
3825 @deffn Command process [key]
3827 Stuff the contents of the specified register into the @code{screen}
3828 input queue. If no argument is given you are prompted for a
3829 register name. The text is parsed as if it had been typed in from the user's
3830 keyboard. This command can be used to bind multiple actions to a single key.
3833 @deffn Command register [-e encoding] key string
3835 Save the specified @var{string} to the register @var{key}.
3836 The encoding of the string can be specified via the @code{-e} option.
3839 @node Screen Exchange, History, Registers, Copy and Paste
3840 @section Screen Exchange
3842 @deffn Command bufferfile [@var{exchange-file}]
3844 Change the filename used for reading and writing with the paste buffer.
3845 If the @var{exchange-file} parameter is omitted, @code{screen} reverts
3846 to the default of @file{/tmp/screen-exchange}. The following example
3847 will paste the system's password file into the screen window (using the
3848 paste buffer, where a copy remains):
3851 C-a : bufferfile /etc/passwd
3858 @deffn Command readbuf [-e @var{encoding}] [@var{filename}]
3860 Reads the contents of the specified file into the paste buffer.
3861 You can tell screen the encoding of the file via the @code{-e} option.
3862 If no file is specified, the screen-exchange filename is used.
3866 @deffn Command removebuf
3868 Unlinks the screen-exchange file.
3872 @deffn Command writebuf [-e @var{encoding}] [@var{filename}]
3874 Writes the contents of the paste buffer to the specified file, or the
3875 public accessible screen-exchange file if no filename is given.
3876 This is thought of as a primitive means of
3877 communication between @code{screen} users on the same host.
3878 If an encoding is specified the paste buffer is recoded on the fly to
3881 @kbd{C-a @key{ESC}} (@pxref{Copy}).
3884 @node History, , Screen Exchange, Copy and Paste
3889 @deffn Command history
3890 (@kbd{C-a @{}, @kbd{C-a @}})@*
3891 Usually users work with a shell that allows easy access to previous
3892 commands. For example, @code{csh} has the command @code{!!} to repeat
3893 the last command executed. @code{screen} provides a primitive way of
3894 recalling ``the command that started @dots{}'': You just type the first
3895 letter of that command, then hit @kbd{C-a @{} and @code{screen} tries to
3896 find a previous line that matches with the prompt character to the left
3897 of the cursor. This line is pasted into this window's input queue. Thus
3898 you have a crude command history (made up by the visible window and its
3902 @node Subprocess Execution, Key Binding, Copy and Paste, Top
3903 @chapter Subprocess Execution
3904 Control Input or Output of a window by another filter process.
3908 * Exec:: The @code{exec} command syntax.
3909 * Using Exec:: Weird things that filters can do.
3912 @node Exec, Using Exec, , Subprocess Execution
3914 @deffn Command exec [[@var{fdpat}] @var{newcommand} [@var{args} ... ]]
3916 Run a unix subprocess (specified by an executable path @var{newcommand} and
3917 its optional arguments) in the current window. The flow of data between
3918 newcommands stdin/stdout/stderr, the process originally started (let us call it
3919 "application-process") and
3920 screen itself (window) is controlled by the file descriptor pattern @var{fdpat}.
3921 This pattern is basically a three character sequence representing stdin, stdout
3922 and stderr of newcommand. A dot (@code{.}) connects the file descriptor
3923 to screen. An exclamation mark (@code{!}) causes the file descriptor to be
3924 connected to the application-process. A colon (@code{:}) combines both.
3926 User input will go to newcommand unless newcommand receives the
3927 application-process'
3928 output (@var{fdpat}s first character is @samp{!} or @samp{:}) or a pipe symbol
3929 (@samp{|}) is added to the end of @var{fdpat}.
3931 Invoking @code{exec} without arguments shows name and arguments of the currently
3932 running subprocess in this window. Only one subprocess can be running per
3935 When a subprocess is running the @code{kill} command will affect it instead of
3936 the windows process. Only one subprocess a time can be running in each window.
3938 Refer to the postscript file @file{doc/fdpat.ps} for a confusing
3939 illustration of all 21 possible combinations. Each drawing shows the digits
3940 2, 1, 0 representing the three file descriptors of newcommand. The box
3941 marked `W' is usual pty that has the application-process on its slave side.
3942 The box marked `P' is the secondary pty that now has screen at its master
3946 @node Using Exec, , Exec, Subprocess Execution
3953 Whitespace between the word @samp{exec} and @var{fdpat} and the command name
3957 Trailing dots and a @var{fdpat} consisting only of dots can be omitted.
3960 A simple @samp{|} is synonymous for the @samp{!..|} pattern.
3963 The word @samp{exec} can be omitted when the @samp{|} abbreviation is used.
3966 The word @samp{exec} can always be replaced by leading @samp{!}.
3975 @itemx exec ... /bin/sh
3976 All of the above are equivalent.
3977 Creates another shell in the same window, while the original shell is still
3978 running. Output of both shells is displayed and user input is sent to the new
3982 @itemx exec!stty 19200
3983 @itemx exec !.. stty 19200
3984 All of the above are equivalent.
3985 Set the speed of the window's tty. If your stty command operates on stdout,
3986 then add another @samp{!}. This is a useful command, when a screen window
3987 is directly connected to a serial line that needs to be configured.
3990 @itemx exec !..| less
3991 Both are equivalent.
3992 This adds a pager to the window output. The special character @samp{|} is
3993 needed to give the user control over the pager although it gets its input from
3994 the window's process. This works, because @samp{less} listens on stderr
3995 (a behavior that @code{screen} would not expect without the @samp{|})
3996 when its stdin is not a tty. @code{Less} versions newer than 177 fail miserably
3997 here; good old @code{pg} still works.
3999 @item !:sed -n s/.*Error.*/\007/p
4000 Sends window output to both, the user and the sed command. The sed inserts an
4001 additional bell character (oct. 007) to the window output seen by screen.
4002 This will cause 'Bell in window x' messages, whenever the string @samp{Error}
4003 appears in the window.
4006 @node Key Binding, Flow Control, Subprocess Execution, Top
4007 @chapter Key Binding
4011 You may disagree with some of the default bindings (I know I do). The
4012 @code{bind} command allows you to redefine them to suit your
4016 * Bind:: @code{bind} syntax.
4017 * Bind Examples:: Using @code{bind}.
4018 * Command Character:: The character used to start keyboard commands.
4019 * Help:: Show current key bindings.
4020 * Bindkey:: @code{bindkey} syntax.
4021 * Bindkey Examples:: Some easy examples.
4022 * Bindkey Control:: How to control the bindkey mechanism.
4025 @node Bind, Bind Examples, , Key Binding
4026 @section The @code{bind} command
4027 @deffn Command bind [-c class] key [command [args]]
4029 Bind a command to a key. The @var{key} argument is either a single
4030 character, a two-character sequence of the form @samp{^x} (meaning
4031 @kbd{C-x}), a backslash followed by an octal number (specifying the
4032 ASCII code of the character), or a backslash followed by a second
4033 character, such as @samp{\^} or @samp{\\}. The argument can also be
4034 quoted, if you like. If no further argument is given, any previously
4035 established binding for this key is removed. The @var{command}
4036 argument can be any command (@pxref{Command Index}).
4038 If a command class is specified via the @code{-c} option, the
4039 key is bound for the specified class. Use the @code{command}
4040 command to activate a class. Command classes can be used
4041 to create multiple command keys or multi-character bindings.
4043 By default, most suitable commands are bound to one or more keys
4044 (@pxref{Default Key Bindings}); for instance, the command to create a
4045 new window is bound to @kbd{C-c} and @kbd{c}. The @code{bind} command
4046 can be used to redefine the key bindings and to define new bindings.
4049 @deffn Command unbindall
4051 Unbind all the bindings. This can be useful when
4052 screen is used solely for its detaching abilities, such as when
4053 letting a console application run as a daemon. If, for some reason,
4054 it is necessary to bind commands after this, use 'screen -X'.
4057 @node Bind Examples, Command Character, Bind, Key Binding
4058 @section Examples of the @code{bind} command
4064 bind ^f screen telnet foobar
4065 bind \033 screen -ln -t root -h 1000 9 su
4069 would bind the space key to the command that displays a list of windows
4070 (so that the command usually invoked by @kbd{C-a C-w} would also be
4071 available as @kbd{C-a space}), bind @kbd{C-f} to the command
4072 ``create a window with a TELNET connection to foobar'', and bind
4073 @key{ESC} to the command that creates an non-login window with title
4074 @samp{root} in slot #9, with a superuser shell and a scrollback buffer
4078 bind -c demo1 0 select 10
4079 bind -c demo1 1 select 11
4080 bind -c demo1 2 select 12
4081 bindkey "^B" command -c demo1
4083 makes @kbd{C-b 0} select window 10, @kbd{C-b 1} window 11, etc.
4086 bind -c demo2 0 select 10
4087 bind -c demo2 1 select 11
4088 bind -c demo2 2 select 12
4089 bind - command -c demo2
4091 makes @kbd{C-a - 0} select window 10, @kbd{C-a - 1} window 11, etc.
4093 @node Command Character, Help, Bind Examples, Key Binding
4094 @cindex escape character
4095 @cindex command character
4096 @section Command Character
4098 @deffn Command escape xy
4100 Set the command character to @var{x} and the character generating a
4101 literal command character (by triggering the @code{meta} command)
4102 to @var{y} (similar to the @samp{-e} option).
4103 Each argument is either a single character, a two-character
4104 sequence of the form @samp{^x} (meaning @kbd{C-x}), a backslash followed
4105 by an octal number (specifying the ASCII code of the character), or a
4106 backslash followed by a second character, such as @samp{\^} or
4107 @samp{\\}. The default is @samp{^Aa}, but @samp{``} is recommended by
4111 @deffn Command defescape xy
4113 Set the default command characters. This is equivalent to the command
4114 @code{escape} except that it is useful for multiuser sessions only.
4115 In a multiuser session
4116 @code{escape} changes the command character of the calling user, where
4117 @code{defescape} changes the default command characters for users that
4118 will be added later.
4124 Send the command character (@kbd{C-a}) to the process in the current
4125 window. The keystroke for this command is the second parameter to the
4126 @samp{-e} command line switch (@pxref{Invoking Screen}), or the
4127 @code{escape} .screenrc directive.
4130 @deffn Command command [-c @var{class}]
4132 This command has the same effect as typing the screen escape character
4133 (@kbd{C-a}). It is probably only useful for key bindings.
4134 If the @samp{-c} option is given, select the specified command class.
4135 @xref{Bind}, @xref{Bindkey}.
4138 @node Help, Bindkey, Command Character, Key Binding
4143 Displays a help screen showing you all the key bindings. The first
4144 pages list all the internal commands followed by their bindings.
4145 Subsequent pages will display the custom commands, one command per key.
4146 Press space when you're done reading each page, or return to exit early.
4147 All other characters are ignored.
4148 If the @samp{-c} option is given, display all bound commands for the
4149 specified command class.
4150 @xref{Default Key Bindings}.
4153 @node Bindkey, Bindkey Examples, Help, Key Binding
4155 @deffn Command bindkey [@var{opts}] [@var{string} [@var{cmd} @var{args}]]
4157 This command manages screen's input translation tables. Every
4158 entry in one of the tables tells screen how to react if a certain
4159 sequence of characters is encountered. There are three tables:
4160 one that should contain actions programmed by the user, one for
4161 the default actions used for terminal emulation and one for
4162 screen's copy mode to do cursor movement. See @ref{Input Translation}
4163 for a list of default key bindings.
4166 option is given, bindkey modifies the default table, @samp{-m}
4167 changes the copy mode table and with neither option the user
4168 table is selected. The argument @samp{string} is the sequence of
4169 characters to which an action is bound. This can either be a fixed
4170 string or a termcap keyboard capability name (selectable with the
4173 Some keys on a VT100 terminal can send a different
4174 string if application mode is turned on (e.g. the cursor keys).
4175 Such keys have two entries in the translation table. You can
4176 select the application mode entry by specifying the @samp{-a}
4179 The @samp{-t} option tells screen not to do inter-character
4180 timing. One cannot turn off the timing if a termcap capability is
4183 @samp{cmd} can be any of screen's commands with an arbitrary
4184 number of @samp{args}. If @samp{cmd} is omitted the key-binding is
4185 removed from the table.
4188 @node Bindkey Examples, Bindkey Control,Bindkey, Key Binding
4189 @section Bindkey Examples
4191 Here are some examples of keyboard bindings:
4197 Show all of the default key bindings. The application mode entries
4198 are marked with [A].
4201 bindkey -k k1 select 1
4204 Make the "F1" key switch to window one.
4207 bindkey -t foo stuff barfoo
4210 Make @samp{foo} an abbreviation of the word @samp{barfoo}. Timeout is
4211 disabled so that users can type slowly.
4214 bindkey "\024" mapdefault
4217 This key-binding makes @samp{C-t} an escape character for key-bindings. If
4218 you did the above @samp{stuff barfoo} binding, you can enter the word
4219 @samp{foo} by typing @samp{C-t foo}. If you want to insert a
4220 @samp{C-t} you have to press the key twice (i.e., escape the escape
4224 bindkey -k F1 command
4227 Make the F11 (not F1!) key an alternative screen
4228 escape (besides @samp{C-a}).
4230 @node Bindkey Control, , Bindkey Examples, Key Binding
4231 @section Bindkey Control
4232 @deffn Command mapdefault
4234 Tell screen that the next input character should only be looked up
4235 in the default bindkey table.
4237 @deffn Command mapnotnext
4239 Like mapdefault, but don't even look in the default bindkey table.
4241 @deffn Command maptimeout n
4243 Set the inter-character timer for input sequence detection to a timeout
4244 of @var{n} ms. The default timeout is 300ms. Maptimeout with no
4245 arguments shows the current setting.
4248 @node Flow Control, Termcap, Key Binding, Top
4249 @chapter Flow Control
4250 @cindex flow control
4252 @code{screen} can trap flow control characters or pass them to the
4253 program, as you see fit. This is useful when your terminal wants to use
4254 XON/XOFF flow control and you are running a program which wants to use
4255 ^S/^Q for other purposes (i.e. @code{emacs}).
4258 * Flow Control Summary:: The effect of @code{screen} flow control
4259 * Flow:: Setting the flow control behavior
4260 * XON/XOFF:: Sending XON or XOFF to the window
4263 @node Flow Control Summary, Flow, , Flow Control
4264 @section About @code{screen} flow control settings
4265 Each window has a flow-control setting that determines how screen deals
4266 with the XON and XOFF characters (and perhaps the interrupt character).
4267 When flow-control is turned off, screen ignores the XON and XOFF
4268 characters, which allows the user to send them to the current program by
4269 simply typing them (useful for the @code{emacs} editor, for instance).
4270 The trade-off is that it will take longer for output from a
4271 ``normal'' program to pause in response to an XOFF. With
4272 flow-control turned on, XON and XOFF characters are used to immediately
4273 pause the output of the current window. You can still send these
4274 characters to the current program, but you must use the appropriate
4275 two-character screen commands (typically @kbd{C-a q} (xon) and @kbd{C-a
4276 s} (xoff)). The xon/xoff commands are also useful for typing C-s and
4277 C-q past a terminal that intercepts these characters.
4279 Each window has an initial flow-control value set with either the
4280 @samp{-f} option or the @code{defflow} command. By default the
4281 windows are set to automatic flow-switching. It can then be toggled
4282 between the three states 'fixed on', 'fixed off' and 'automatic'
4283 interactively with the @code{flow} command bound to @kbd{C-a f}.
4285 The automatic flow-switching mode deals with flow control using the
4286 TIOCPKT mode (like @code{rlogin} does). If the tty driver does not
4287 support TIOCPKT, screen tries to determine the right mode based on the
4288 current setting of the application keypad --- when it is enabled,
4289 flow-control is turned off and visa versa. Of course, you can still
4290 manipulate flow-control manually when needed.
4292 If you're running with flow-control enabled and find that pressing the
4293 interrupt key (usually C-c) does not interrupt the display until another
4294 6-8 lines have scrolled by, try running screen with the @samp{interrupt}
4295 option (add the @samp{interrupt} flag to the @code{flow} command in your
4296 .screenrc, or use the @samp{-i} command-line option). This causes the
4297 output that @code{screen} has accumulated from the interrupted program
4298 to be flushed. One disadvantage is that the virtual terminal's memory
4299 contains the non-flushed version of the output, which in rare cases can
4300 cause minor inaccuracies in the output. For example, if you switch
4301 screens and return, or update the screen with @kbd{C-a l} you would see
4302 the version of the output you would have gotten without @samp{interrupt}
4303 being on. Also, you might need to turn off flow-control (or use
4304 auto-flow mode to turn it off automatically) when running a program that
4305 expects you to type the interrupt character as input, as the
4306 @samp{interrupt} parameter only takes effect when flow-control is
4307 enabled. If your program's output is interrupted by mistake, a simple
4308 refresh of the screen with @kbd{C-a l} will restore it. Give each mode
4309 a try, and use whichever mode you find more comfortable.
4311 @node Flow, XON/XOFF, Flow Control Summary, Flow Control
4313 @deffn Command defflow fstate [interrupt]
4315 Same as the @code{flow} command except that the default setting for new
4316 windows is changed. Initial setting is `auto'.
4317 Specifying @code{flow auto interrupt} has the same effect as the
4318 command-line options @samp{-fa} and @samp{-i}.
4319 Note that if @samp{interrupt} is enabled, all existing displays are
4320 changed immediately to forward interrupt signals.
4325 @deffn Command flow [fstate]
4326 (@kbd{C-a f}, @kbd{C-a C-f})@*
4327 Sets the flow-control mode for this window to @var{fstate}, which can be
4328 @samp{on}, @samp{off} or @samp{auto}.
4329 Without parameters it cycles the current window's
4330 flow-control setting. Default is set by `defflow'.
4333 @node XON/XOFF, , Flow, Flow Control
4334 @section XON and XOFF
4338 (@kbd{C-a q}, @kbd{C-a C-q})@*
4339 Send a ^Q (ASCII XON) to the program in the current window. Redundant
4340 if flow control is set to @samp{off} or @samp{auto}.
4346 (@kbd{C-a s}, @kbd{C-a C-s})@*
4347 Send a ^S (ASCII XOFF) to the program in the current window.
4350 @node Termcap, Message Line, Flow Control, Top
4353 @code{Screen} demands the most out of your terminal so that it can
4354 perform its VT100 emulation most efficiently. These functions provide
4355 means for tweaking the termcap entries for both your physical terminal
4356 and the one simulated by @code{screen}.
4359 * Window Termcap:: Choosing a termcap entry for the window.
4360 * Dump Termcap:: Write out a termcap entry for the window.
4361 * Termcap Syntax:: The @code{termcap} and @code{terminfo} commands.
4362 * Termcap Examples:: Uses for @code{termcap}.
4363 * Special Capabilities:: Non-standard capabilities used by @code{screen}.
4364 * Autonuke:: Flush unseen output
4365 * Obuflimit:: Allow pending output when reading more
4366 * Character Translation:: Emulating fonts and charsets.
4369 @node Window Termcap, Dump Termcap, , Termcap
4370 @section Choosing the termcap entry for a window
4371 Usually @code{screen} tries to emulate as much of the VT100/ANSI
4372 standard as possible. But if your terminal lacks certain capabilities
4373 the emulation may not be complete. In these cases @code{screen} has to
4374 tell the applications that some of the features are missing. This is no
4375 problem on machines using termcap, because @code{screen} can use the
4376 @code{$TERMCAP} variable to customize the standard screen termcap.
4378 But if you do a rlogin on another machine or your machine supports only
4379 terminfo this method fails. Because of this @code{screen} offers a way
4380 to deal with these cases. Here is how it works:
4382 When @code{screen} tries to figure out a terminal name for itself, it
4383 first looks for an entry named @code{screen.@var{term}}, where
4384 @var{term} is the contents of your @code{$TERM} variable. If no such entry
4385 exists, @code{screen} tries @samp{screen} (or @samp{screen-w}, if the
4386 terminal is wide (132 cols or more)). If even this entry cannot be
4387 found, @samp{vt100} is used as a substitute.
4389 The idea is that if you have a terminal which doesn't support an
4390 important feature (e.g. delete char or clear to EOS) you can build a new
4391 termcap/terminfo entry for @code{screen} (named
4392 @samp{screen.@var{dumbterm}}) in which this capability has been
4393 disabled. If this entry is installed on your machines you are able to
4394 do a rlogin and still keep the correct termcap/terminfo entry. The
4395 terminal name is put in the @code{$TERM} variable of all new windows.
4396 @code{screen} also sets the @code{$TERMCAP} variable reflecting the
4397 capabilities of the virtual terminal emulated.
4398 Furthermore, the variable @code{$WINDOW} is set to the window number of each
4401 The actual set of capabilities supported by the virtual terminal depends
4402 on the capabilities supported by the physical terminal. If, for
4403 instance, the physical terminal does not support underscore mode,
4404 @code{screen} does not put the @samp{us} and @samp{ue} capabilities into
4405 the window's @code{$TERMCAP} variable, accordingly. However, a minimum number
4406 of capabilities must be supported by a terminal in order to run
4407 @code{screen}; namely scrolling, clear screen, and direct cursor
4408 addressing (in addition, @code{screen} does not run on hardcopy
4409 terminals or on terminals that over-strike).
4411 Also, you can customize the @code{$TERMCAP} value used by @code{screen} by
4412 using the @code{termcap} command, or by defining the variable
4413 @code{$SCREENCAP} prior to startup. When the latter defined, its value will be
4414 copied verbatim into each window's @code{$TERMCAP} variable. This can either
4415 be the full terminal definition, or a filename where the terminal
4416 @samp{screen} (and/or @samp{screen-w}) is defined.
4418 Note that @code{screen} honors the @code{terminfo} command if the system
4419 uses the terminfo database rather than termcap. On such machines the
4420 @code{$TERMCAP} variable has no effect and you must use the
4421 @code{dumptermcap} command (@pxref{Dump Termcap}) and the @code{tic}
4422 program to generate terminfo entries for @code{screen} windows.
4424 When the boolean @samp{G0} capability is present in the termcap entry
4425 for the terminal on which @code{screen} has been called, the terminal
4426 emulation of @code{screen} supports multiple character sets. This
4427 allows an application to make use of, for instance, the VT100 graphics
4428 character set or national character sets. The following control
4429 functions from ISO 2022 are supported: @samp{lock shift G0} (@samp{SI}),
4430 @samp{lock shift G1} (@samp{SO}), @samp{lock shift G2}, @samp{lock shift
4431 G3}, @samp{single shift G2}, and @samp{single shift G3}. When a virtual
4432 terminal is created or reset, the ASCII character set is designated as
4433 @samp{G0} through @samp{G3}. When the @samp{G0} capability is present,
4434 screen evaluates the capabilities @samp{S0}, @samp{E0}, and @samp{C0} if
4435 present. @samp{S0} is the sequence the terminal uses to enable and start
4436 the graphics character set rather than @samp{SI}. @samp{E0} is the
4437 corresponding replacement for @samp{SO}. @samp{C0} gives a character by
4438 character translation string that is used during semi-graphics mode.
4439 This string is built like the @samp{acsc} terminfo capability.
4441 When the @samp{po} and @samp{pf} capabilities are present in the
4442 terminal's termcap entry, applications running in a @code{screen} window
4443 can send output to the printer port of the terminal. This allows a user
4444 to have an application in one window sending output to a printer
4445 connected to the terminal, while all other windows are still active (the
4446 printer port is enabled and disabled again for each chunk of output).
4447 As a side-effect, programs running in different windows can send output
4448 to the printer simultaneously. Data sent to the printer is not
4449 displayed in the window. The @code{info} command displays a line starting
4450 with @samp{PRIN} while the printer is active.
4452 Some capabilities are only put into the @code{$TERMCAP} variable of the virtual
4453 terminal if they can be efficiently implemented by the physical
4454 terminal. For instance, @samp{dl} (delete line) is only put into the
4455 @code{$TERMCAP} variable if the terminal supports either delete line itself or
4456 scrolling regions. Note that this may provoke confusion, when the
4457 session is reattached on a different terminal, as the value of @code{$TERMCAP}
4458 cannot be modified by parent processes. You can force @code{screen} to
4459 include all capabilities in @code{$TERMCAP} with the @samp{-a}
4460 command-line option (@pxref{Invoking Screen}).
4462 The "alternate screen" capability is not enabled by default.
4463 Set the @code{altscreen} @file{.screenrc} command to enable it.
4465 @node Dump Termcap, Termcap Syntax, Window Termcap, Termcap
4466 @section Write out the window's termcap entry
4468 @deffn Command dumptermcap
4470 Write the termcap entry for the virtual terminal optimized for the
4471 currently active window to the file @file{.termcap} in the user's
4472 @file{$HOME/.screen} directory (or wherever @code{screen} stores its
4473 sockets. @pxref{Files}). This termcap entry is identical to
4474 the value of the environment variable @code{$TERMCAP} that is set up by
4475 @code{screen} for each window. For terminfo based systems you will need
4476 to run a converter like @code{captoinfo} and then compile the entry with
4480 @node Termcap Syntax, Termcap Examples, Dump Termcap, Termcap
4481 @section The @code{termcap} command
4482 @deffn Command termcap term terminal-tweaks [window-tweaks]
4483 @deffnx Command terminfo term terminal-tweaks [window-tweaks]
4484 @deffnx Command termcapinfo term terminal-tweaks [window-tweaks]
4486 Use this command to modify your terminal's termcap entry without going
4487 through all the hassles involved in creating a custom termcap entry.
4488 Plus, you can optionally customize the termcap generated for the
4490 You have to place these commands in one of the screenrc startup files, as they
4491 are meaningless once the terminal emulator is booted.
4493 If your system uses the terminfo database rather than termcap,
4494 @code{screen} will understand the @code{terminfo} command, which has the
4495 same effects as the @code{termcap} command. Two separate commands are
4496 provided, as there are subtle syntactic differences, e.g. when parameter
4497 interpolation (using @samp{%}) is required. Note that the termcap names of
4498 the capabilities should also be used with the @code{terminfo} command.
4500 In many cases, where the arguments are valid in both terminfo and termcap
4501 syntax, you can use the command @code{termcapinfo}, which is just a
4502 shorthand for a pair of @code{termcap} and @code{terminfo} commands with
4503 identical arguments.
4506 The first argument specifies which terminal(s) should be affected by
4507 this definition. You can specify multiple terminal names by separating
4508 them with @samp{|}s. Use @samp{*} to match all terminals and @samp{vt*}
4509 to match all terminals that begin with @samp{vt}.
4511 Each @var{tweak} argument contains one or more termcap defines
4512 (separated by @samp{:}s) to be inserted at the start of the appropriate
4513 termcap entry, enhancing it or overriding existing values. The first
4514 tweak modifies your terminal's termcap, and contains definitions that
4515 your terminal uses to perform certain functions. Specify a null string
4516 to leave this unchanged (e.g. ""). The second (optional) tweak modifies
4517 all the window termcaps, and should contain definitions that screen
4518 understands (@pxref{Virtual Terminal}).
4520 @node Termcap Examples, Special Capabilities, Termcap Syntax, Termcap
4521 @section Termcap Examples
4525 termcap xterm* xn:hs@@
4529 Informs @code{screen} that all terminals that begin with @samp{xterm}
4530 have firm auto-margins that allow the last position on the screen to be
4531 updated (xn), but they don't really have a status line (no 'hs' --
4532 append @samp{@@} to turn entries off). Note that we assume @samp{xn} for
4533 all terminal names that start with @samp{vt}, but only if you don't
4534 specify a termcap command for that terminal.
4538 termcap vt102|vt220 Z0=\E[?3h:Z1=\E[?3l
4542 Specifies the firm-margined @samp{xn} capability for all terminals that
4543 begin with @samp{vt}, and the second line will also add the
4544 escape-sequences to switch into (Z0) and back out of (Z1)
4545 132-character-per-line mode if this is a VT102 or VT220. (You must
4546 specify Z0 and Z1 in your termcap to use the width-changing commands.)
4549 termcap vt100 "" l0=PF1:l1=PF2:l2=PF3:l3=PF4
4553 This leaves your vt100 termcap alone and adds the function key labels to
4554 each window's termcap entry.
4557 termcap h19|z19 am@@:im=\E@@:ei=\EO dc=\E[P
4561 Takes a h19 or z19 termcap and turns off auto-margins (am@@) and enables
4562 the insert mode (im) and end-insert (ei) capabilities (the @samp{@@} in
4563 the @samp{im} string is after the @samp{=}, so it is part of the
4564 string). Having the @samp{im} and @samp{ei} definitions put into your
4565 terminal's termcap will cause screen to automatically advertise the
4566 character-insert capability in each window's termcap. Each window will
4567 also get the delete-character capability (dc) added to its termcap,
4568 which screen will translate into a line-update for the terminal (we're
4569 pretending it doesn't support character deletion).
4571 If you would like to fully specify each window's termcap entry, you
4572 should instead set the @code{$SCREENCAP} variable prior to running
4573 @code{screen}. @xref{Virtual Terminal}, for the details of the
4574 @code{screen} terminal emulation. @xref{Top, , Termcap, termcap, The
4575 Termcap Manual}, for more information on termcap definitions.
4577 @node Special Capabilities, Autonuke, Termcap Examples, Termcap
4578 @section Special Terminal Capabilities
4579 @cindex terminal capabilities
4580 @cindex capabilities
4581 The following table describes all terminal capabilities that are
4582 recognized by @code{screen} and are not in the termcap manual
4583 (@pxref{Top, , Termcap, termcap, The Termcap Manual}).
4584 You can place these capabilities in your termcap entries (in
4585 @file{/etc/termcap}) or use them with the commands @code{termcap},
4586 @code{terminfo} and @code{termcapinfo} in your @code{screenrc} files. It is
4587 often not possible to place these capabilities in the terminfo database.
4591 Terminal has VT100 style margins (`magic margins'). Note that
4592 this capability is obsolete --- @code{screen} now uses the standard
4597 Change width to 132 columns.
4601 Change width to 80 columns.
4605 Resize display. This capability has the desired width and height as
4606 arguments. SunView(tm) example: @samp{\E[8;%d;%dt}.
4610 Terminal doesn't need flow control. Send ^S and ^Q direct to
4611 the application. Same as @code{flow off}. The opposite of this
4612 capability is @samp{nx}.
4616 Terminal can deal with ISO 2022 font selection sequences.
4620 Switch charset @samp{G0} to the specified charset. Default
4625 Switch charset @samp{G0} back to standard charset. Default
4630 Use the string as a conversion table for font 0. See
4631 the @samp{ac} capability for more details.
4635 Switch cursor-keys to application mode.
4639 Switch cursor-keys to cursor mode.
4643 Enable autonuke for displays of this terminal type.
4648 Set the output buffer limit. See the @samp{obuflimit} command
4649 (@pxref{Obuflimit}) for more details.
4653 Set the encoding of the terminal. See the @samp{encoding} command
4654 (@pxref{Character Processing}) for valid encodings.
4658 Change character foreground color in an ANSI conform way. This
4659 capability will almost always be set to @samp{\E[3%dm}
4660 (@samp{\E[3%p1%dm} on terminfo machines).
4664 Same as @samp{AF}, but change background color.
4668 Does understand ANSI set default fg/bg color (@samp{\E[39m / \E[49m}).
4672 Describe a translation of characters to strings depending on the
4673 current font. (@pxref{Character Translation}).
4677 Terminal understands special xterm sequences (OSC, mouse tracking).
4681 Terminal needs bold to display high-intensity colors (e.g. Eterm).
4685 Add missing capabilities to the termcap/info entry. (Set by default).
4688 @node Autonuke, Obuflimit, Special Capabilities, Termcap
4690 @deffn Command autonuke @var{state}
4692 Sets whether a clear screen sequence should nuke all the output
4693 that has not been written to the terminal. @xref{Obuflimit}.
4694 This property is set per display, not per window.
4697 @deffn Command defautonuke @var{state}
4699 Same as the @code{autonuke} command except that the default setting for
4700 new displays is also changed. Initial setting is @code{off}.
4701 Note that you can use the special @code{AN} terminal capability if you
4702 want to have a terminal type dependent setting.
4705 @node Obuflimit, Character Translation, Autonuke, Termcap
4707 @deffn Command obuflimit [@var{limit}]
4709 If the output buffer contains more bytes than the specified limit, no
4710 more data will be read from the windows. The default value is 256. If
4711 you have a fast display (like @code{xterm}), you can set it to some
4712 higher value. If no argument is specified, the current setting is displayed.
4713 This property is set per display, not per window.
4716 @deffn Command defobuflimit @var{limit}
4718 Same as the @code{obuflimit} command except that the default setting for new
4719 displays is also changed. Initial setting is 256 bytes. Note that you can use
4720 the special @code{OL} terminal capability if you want to have a terminal
4721 type dependent limit.
4724 @node Character Translation, , Obuflimit, Termcap
4725 @section Character Translation
4726 @code{Screen} has a powerful mechanism to translate characters to
4727 arbitrary strings depending on the current font and terminal type.
4728 Use this feature if you want to work with a common standard character
4729 set (say ISO8851-latin1) even on terminals that scatter the more
4730 unusual characters over several national language font pages.
4735 XC=@var{<charset-mapping>}@{,,@var{<charset-mapping>}@}
4736 @var{<charset-mapping>} := @var{<designator>}@var{<template>}@{,@var{<mapping>}@}
4737 @var{<mapping>} := @var{<char-to-be-mapped>}@var{<template-arg>}
4740 The things in braces may be repeated any number of times.
4742 A @var{<charset-mapping>} tells screen how to map characters
4743 in font @var{<designator>} (@samp{B}: Ascii, @samp{A}: UK,
4744 @samp{K}: german, etc.)
4745 to strings. Every @var{<mapping>} describes to what string a single
4746 character will be translated. A template mechanism is used, as
4747 most of the time the codes have a lot in common (for example
4748 strings to switch to and from another charset). Each occurrence
4749 of @samp{%} in @var{<template>} gets substituted with the
4751 specified together with the character. If your strings are not
4752 similar at all, then use @samp{%} as a template and place the full
4753 string in @var{<template-arg>}. A quoting mechanism was added to make
4754 it possible to use a real @samp{%}. The @samp{\} character quotes the
4755 special characters @samp{\}, @samp{%}, and @samp{,}.
4760 termcap hp700 'XC=B\E(K%\E(B,\304[,\326\\\\,\334]'
4763 This tells @code{screen}, how to translate ISOlatin1 (charset @samp{B})
4764 upper case umlaut characters on a @code{hp700} terminal that has a
4765 German charset. @samp{\304} gets translated to
4766 @samp{\E(K[\E(B} and so on.
4767 Note that this line gets parsed *three* times before the internal
4768 lookup table is built, therefore a lot of quoting is needed to
4769 create a single @samp{\}.
4771 Another extension was added to allow more emulation: If a mapping
4772 translates the unquoted @samp{%} char, it will be sent to the terminal
4773 whenever screen switches to the corresponding @var{<designator>}.
4775 special case the template is assumed to be just @samp{%} because
4776 the charset switch sequence and the character mappings normally
4777 haven't much in common.
4779 This example shows one use of the extension:
4781 termcap xterm 'XC=K%,%\E(B,[\304,\\\\\326,]\334'
4784 Here, a part of the German (@samp{K}) charset is emulated on an xterm.
4785 If screen has to change to the @samp{K} charset, @samp{\E(B} will be
4787 to the terminal, i.e. the ASCII charset is used instead. The
4788 template is just @samp{%}, so the mapping is straightforward:
4789 @samp{[} to @samp{\304}, @samp{\} to @samp{\326}, and @samp{]} to
4792 @node Message Line, Logging, Termcap, Top
4793 @chapter The Message Line
4794 @cindex message line
4796 @code{Screen} displays informational messages and other diagnostics in a
4797 @dfn{message line} at the bottom of the screen. If your terminal has a
4798 status line defined in its termcap, screen will use this for displaying
4799 its messages, otherwise the last line of the screen will be temporarily
4800 overwritten and output will be momentarily interrupted. The message
4801 line is automatically removed after a few seconds delay, but it can also
4802 be removed early (on terminals without a status line) by beginning to
4806 * Privacy Message:: Using the message line from your program.
4807 * Hardware Status Line:: Use the terminal's hardware status line.
4808 * Last Message:: Redisplay the last message.
4809 * Message Wait:: Control how long messages are displayed.
4812 @node Privacy Message, Hardware Status Line, , Message Line
4813 @section Using the message line from your program
4814 The message line facility can be used by an application running in the
4815 current window by means of the ANSI @dfn{Privacy message} control
4816 sequence. For instance, from within the shell, try something like:
4819 echo "@value{esc}^Hello world from window $WINDOW@value{esc}\"
4822 where @samp{@value{esc}} is ASCII ESC and the @samp{^} that follows it
4823 is a literal caret or up-arrow.
4825 @node Hardware Status Line, Last Message, Privacy Message, Message Line
4826 @section Hardware Status Line
4827 @deffn Command hardstatus [state]
4828 @deffnx Command hardstatus [@code{always}]@code{lastline}|@code{message}|@code{ignore} [string]
4829 @deffnx Command hardstatus @code{string} [string]
4831 This command configures the use and emulation of the terminal's
4832 hardstatus line. The first form toggles whether @code{screen}
4833 will use the hardware status line to display messages. If the
4834 flag is set to @samp{off}, these messages
4835 are overlaid in reverse video mode at the display line. The default
4836 setting is @samp{on}.
4838 The second form tells screen what to do if the terminal doesn't
4839 have a hardstatus line (i.e. the termcap/terminfo capabilities
4840 "hs", "ts", "fs" and "ds" are not set). If the type
4841 @code{lastline} is used, screen will reserve the last line of the
4842 display for the hardstatus. @code{message} uses
4843 @code{screen}'s message mechanism and
4844 @code{ignore} tells @code{screen} never to display the hardstatus.
4845 If you prepend the word @code{always} to the type (e.g., @code{alwayslastline}), @code{screen} will use
4846 the type even if the terminal supports a hardstatus line.
4848 The third form specifies the contents of the hardstatus line.
4849 @code{%h} is used as default string, i.e., the stored hardstatus of the
4850 current window (settable via @samp{ESC]0;^G} or @samp{ESC_\\}) is
4852 You can customize this to any string you like including
4853 string escapes (@pxref{String Escapes}).
4855 out the argument @var{string}, the current string is displayed.
4857 You can mix the second and third form by providing the string as
4858 additional argument.
4861 @node Last Message, Message Wait, Hardware Status Line, Message Line
4862 @section Display Last Message
4865 @deffn Command lastmsg
4866 (@kbd{C-a m}, @kbd{C-a C-m})@*
4867 Repeat the last message displayed in the message line. Useful if you're
4868 typing when a message appears, because (unless your terminal has a
4869 hardware status line) the message goes away when you press a key.
4872 @node Message Wait, , Last Message, Message Line
4873 @section Message Wait
4874 @deffn Command msgminwait sec
4876 Defines the time @code{screen} delays a new message when another is
4877 currently displayed. Defaults to 1 second.
4880 @deffn Command msgwait sec
4882 Defines the time a message is displayed, if @code{screen} is not
4883 disturbed by other activity. Defaults to 5 seconds.
4886 @node Logging, Startup, Message Line, Top
4889 This section describes the commands for keeping a record of your session.
4892 * Hardcopy:: Dump the current screen to a file
4893 * Log:: Log the output of a window to a file
4896 @node Hardcopy, Log, , Logging
4899 @deffn Command hardcopy [-h] [@var{file}]
4901 Writes out the currently displayed image to the file @var{file}, or,
4902 if no filename is specified, to @file{hardcopy.@var{n}}
4903 in the default directory, where @var{n} is the number of the
4904 current window. This either appends or overwrites the file if it
4905 exists, as determined by the @code{hardcopy_append} command.
4906 If the option @code{-h} is specified, dump also the
4907 contents of the scrollback buffer.
4910 @deffn Command hardcopy_append state
4912 If set to @samp{on}, @code{screen} will append to the
4913 @file{hardcopy.@var{n}} files created by the command @code{hardcopy};
4914 otherwise, these files are overwritten each time.
4917 @deffn Command hardcopydir directory
4919 Defines a directory where hardcopy files will be placed.
4920 If unset, hardcopys are dumped in screen's current working
4924 @node Log, , Hardcopy, Logging
4927 @deffn Command deflog state
4929 Same as the @code{log} command except that the default setting for new
4930 windows is changed. Initial setting is `off'.
4934 @deffn Command log [state]
4936 Begins/ends logging of the current window to the file
4937 @file{screenlog.@var{n}} in the window's default directory, where
4938 @var{n} is the number of the current window.
4939 This filename can be changed with the @samp{logfile} command.
4940 If no parameter is given,
4941 the logging state is toggled. The session log is
4942 appended to the previous contents of the file if it already exists. The
4943 current contents and the contents of the scrollback history are not
4944 included in the session log. Default is @samp{off}.
4947 @deffn Command logfile filename
4948 @deffnx Command logfile flush secs
4950 Defines the name the log files will get. The default is @samp{screenlog.%n}.
4951 The second form changes the number of seconds @code{screen}
4952 will wait before flushing the logfile buffer to the file-system. The
4953 default value is 10 seconds.
4956 @deffn Command logtstamp [state]
4957 @deffnx Command logtstamp @code{after} secs
4958 @deffnx Command logtstamp @code{string} string
4960 This command controls logfile time-stamp mechanism of screen. If
4961 time-stamps are turned @samp{on}, screen adds a string containing
4962 the current time to the logfile after two minutes of inactivity.
4963 When output continues and more than another two minutes have passed,
4964 a second time-stamp is added to document the restart of the
4965 output. You can change this timeout with the second form
4966 of the command. The third form is used for customizing the time-stamp
4967 string (@samp{-- %n:%t -- time-stamp -- %M/%d/%y %c:%s --\n} by
4971 @node Startup, Miscellaneous, Logging, Top
4974 This section describes commands which are only useful in the
4975 @file{.screenrc} file, for use at startup.
4978 * echo:: Display a message.
4979 * sleep:: Pause execution of the @file{.screenrc}.
4980 * Startup Message:: Control display of the copyright notice.
4983 @node echo, sleep, , Startup
4985 @deffn Command echo [@samp{-n}] message
4987 The echo command may be used to annoy @code{screen} users with a
4988 'message of the day'. Typically installed in a global screenrc.
4989 The option @samp{-n} may be used to suppress the line feed.
4990 See also @code{sleep}.
4991 Echo is also useful for online checking of environment variables.
4994 @node sleep, Startup Message, echo, Startup
4996 @deffn Command sleep num
4998 This command will pause the execution of a .screenrc file for @var{num}
4999 seconds. Keyboard activity will end the sleep. It may be used to give
5000 users a chance to read the messages output by @code{echo}.
5003 @node Startup Message, , sleep, Startup
5004 @section Startup Message
5005 @deffn Command startup_message state
5007 Select whether you want to see the copyright notice during startup.
5008 Default is @samp{on}, as you probably noticed.
5011 @node Miscellaneous, String Escapes, Startup, Top
5012 @chapter Miscellaneous commands
5014 The commands described here do not fit well under any of the other
5018 * At:: Execute a command at other displays or windows.
5019 * Break:: Send a break signal to the window.
5020 * Debug:: Suppress/allow debugging output.
5021 * License:: Display the disclaimer page.
5022 * Nethack:: Use @code{nethack}-like error messages.
5023 * Nonblock:: Disable flow-control to a display.
5024 * Number:: Change the current window's number.
5025 * Time:: Display the time and load average.
5026 * Verbose:: Display window creation commands.
5027 * Version:: Display the version of @code{screen}.
5028 * Zombie:: Keep dead windows.
5029 * Printcmd:: Set command for VT100 printer port emulation.
5030 * Rendition:: Change text attributes in caption for flagged windows.
5031 * Sorendition:: Change the text highlighting method.
5032 * Attrcolor:: Map attributes to colors.
5033 * Setsid:: Change process group management.
5034 * Eval:: Parse and execute arguments.
5035 * Maxwin:: Set the maximum window number.
5036 * Backtick:: Program a command for a backtick string escape.
5037 * Screen Saver:: Define a screen safer.
5038 * Zmodem:: Define how screen treats zmodem requests.
5039 * Mousetrack:: Set whether screen should track mouse events.
5042 @node At, Break, , Miscellaneous
5044 @deffn Command at [identifier][#|*|%] command [args]
5046 Execute a command at other displays or windows as if it had been entered there.
5047 @code{At} changes the context (the `current window' or `current display'
5048 setting) of the command. If the first parameter describes a non-unique context,
5049 the command will be executed multiple times. If the first parameter is of the
5050 form @samp{@var{identifier}*} then identifier is matched against user names.
5051 The command is executed once for each display of the selected user(s).
5052 If the first parameter is of the form @samp{@var{identifier}%} identifier is
5053 matched against displays. Displays are named after the ttys they attach. The
5054 prefix @samp{/dev/} or @samp{/dev/tty} may be omitted from the identifier.
5055 If @var{identifier} has a @code{#} or nothing appended it is matched against
5056 window numbers and titles. Omitting an identifier in front of the @code{#},
5057 @code{*} or @code{%} character selects all users, displays or windows because
5058 a prefix-match is performed. Note that on the affected display(s) a short
5059 message will describe what happened.
5060 Note that the @code{#} character works as a comment introducer when it is
5061 preceded by whitespace. This can be escaped by prefixing @code{#} with a
5063 Permission is checked for the initiator of the @code{at} command, not for the
5064 owners of the affected display(s).
5066 When matching against windows, the command is executed at least
5067 once per window. Commands that change the internal arrangement of windows
5068 (like @code{other}) may be called again. In shared windows the command will
5069 be repeated for each attached display. Beware, when issuing toggle commands
5071 Some commands (e.g. @code{\*Qprocess}) require
5072 that a display is associated with the target windows. These commands may not
5073 work correctly under @code{at} looping over windows.
5076 @node Break, Debug, At, Miscellaneous
5080 @deffn Command break [duration]
5081 (@kbd{C-a b}, @kbd{C-a C-b})@*
5082 Send a break signal for @var{duration}*0.25 seconds to this window.
5083 For non-Posix systems the time interval is rounded up to full seconds.
5084 Most useful if a character device is attached to the window rather than
5085 a shell process (@pxref{Window Types}). The maximum duration of
5086 a break signal is limited to 15 seconds.
5090 @deffn Command pow_break
5092 Reopen the window's terminal line and send a break condition.
5095 @deffn Command breaktype [tcsendbreak|TIOCSBRK|TCSBRK]
5097 Choose one of the available methods of generating a break signal for
5098 terminal devices. This command should affect the current window only.
5099 But it still behaves identical to @code{defbreaktype}. This will be changed in
5101 Calling @code{breaktype} with no parameter displays the break setting for the
5105 @deffn Command defbreaktype [tcsendbreak|TIOCSBRK|TCSBRK]
5107 Choose one of the available methods of generating a break signal for
5108 terminal devices opened afterwards. The preferred methods are
5109 @code{tcsendbreak} and
5110 @code{TIOCSBRK}. The third, @code{TCSBRK}, blocks the complete @code{screen}
5111 session for the duration of the break, but it may be the only way to
5112 generate long breaks. @code{tcsendbreak} and @code{TIOCSBRK} may or may not
5113 produce long breaks with spikes (e.g. 4 per second). This is not only system
5114 dependent, this also differs between serial board drivers.
5115 Calling @code{defbreaktype} with no parameter displays the current setting.
5118 @node Debug, License, Break, Miscellaneous
5120 @deffn Command debug [on|off]
5122 Turns runtime debugging on or off. If @code{screen} has been compiled with
5123 option @code{-DDEBUG} debugging is available and is turned on per default.
5124 Note that this command only affects debugging output from the main
5125 @samp{SCREEN} process correctly. Debug output from attacher processes can only
5126 be turned off once and forever.
5129 @node License, Nethack, Debug, Miscellaneous
5132 @deffn Command license
5134 Display the disclaimer page. This is done whenever @code{screen} is
5135 started without options, which should be often enough.
5138 @node Nethack, Nonblock, License, Miscellaneous
5140 @deffn Command nethack state
5142 Changes the kind of error messages used by @code{screen}. When you are
5143 familiar with the game @code{nethack}, you may enjoy the nethack-style
5144 messages which will often blur the facts a little, but are much funnier
5145 to read. Anyway, standard messages often tend to be unclear as well.
5147 This option is only available if @code{screen} was compiled with the
5148 NETHACK flag defined (@pxref{Installation}). The default setting is then
5149 determined by the presence of the environment variable
5150 @code{$NETHACKOPTIONS} and the file @code{~/.nethackrc} - if either one is
5151 present, the default is @code{on}.
5154 @node Nonblock, Number, Nethack, Miscellaneous
5156 @deffn Command nonblock [@var{state}|@var{numsecs}]
5157 Tell screen how to deal with user interfaces (displays) that cease to
5158 accept output. This can happen if a user presses ^S or a TCP/modem
5159 connection gets cut but no hangup is received. If nonblock is
5160 @code{off} (this is the default) screen waits until the display
5161 restarts to accept the output. If nonblock is @code{on}, screen
5162 waits until the timeout is reached (@code{on} is treated as 1s). If the
5163 display still doesn't receive characters, screen will consider
5164 it ``blocked'' and stop sending characters to it. If at
5165 some time it restarts to accept characters, screen will unblock
5166 the display and redisplay the updated window contents.
5169 @deffn Command defnonblock @var{state}|@var{numsecs}
5170 Same as the @code{nonblock} command except that the default setting for
5171 displays is changed. Initial setting is @code{off}.
5174 @node Number, Time, Nonblock, Miscellaneous
5177 @deffn Command number [[+|-]@var{n}]
5179 Change the current window's number. If the given number @var{n} is already
5180 used by another window, both windows exchange their numbers. If no argument is
5181 specified, the current window number (and title) is shown. Using either a
5182 plus (`+') or minus (`-') will change the window's number by the relative
5186 @node Time, Verbose, Number, Miscellaneous
5190 @deffn Command time [@var{string}]
5191 (@kbd{C-a t}, @kbd{C-a C-t})@*
5192 Uses the message line to display the time of day, the host name, and the
5193 load averages over 1, 5, and 15 minutes (if this is available on your
5194 system). For window-specific information use @code{info} (@pxref{Info}).
5195 If a @var{string} is specified, it changes the format of the time report
5196 like it is described in the string escapes chapter (@pxref{String Escapes}). Screen uses a default of @samp{%c:%s %M %d %H%? %l%?}.
5199 @node Verbose, Version, Time, Miscellaneous
5201 @deffn Command verbose [on|off]
5202 If verbose is switched on, the command name is echoed, whenever a window
5203 is created (or resurrected from zombie state). Default is off.
5204 Without a parameter, the current setting is shown.
5207 @node Version, Zombie, Verbose, Miscellaneous
5210 @deffn Command version
5212 Display the version and modification date in the message line.
5215 @node Zombie, Printcmd, Version, Miscellaneous
5217 @deffn Command zombie [@var{keys} [onerror] ]
5218 @deffnx Command defzombie [@var{keys}]
5220 Per default windows are removed from the window list as soon as the
5221 windows process (e.g. shell) exits. When a string of two keys is
5222 specified to the zombie command, `dead' windows will remain in the list.
5223 The @code{kill} command may be used to remove the window. Pressing the first key
5224 in the dead window has the same effect. Pressing the second key, however,
5225 screen will attempt to resurrect the window. The process that was initially
5226 running in the window will be launched again. Calling @code{zombie} without
5227 parameters will clear the zombie setting, thus making windows disappear when
5228 the process terminates.
5230 As the zombie setting is affected globally for all windows, this command
5231 should only be called @code{defzombie}. Until we need this as a per window
5232 setting, the commands @code{zombie} and @code{defzombie} are synonymous.
5234 Optionally you can put the word @code{onerror} after the keys. This will
5235 cause screen to monitor exit status of the process running in the window.
5236 If it exits normally ('0'), the window disappears. Any other exit value
5237 causes the window to become a zombie.
5240 @node Printcmd, Rendition, Zombie, Miscellaneous
5242 @deffn Command printcmd [@var{cmd}]
5244 If @var{cmd} is not an empty string, screen will not use the terminal
5245 capabilities @code{po/pf} for printing if it detects an ansi print
5246 sequence @code{ESC [ 5 i}, but pipe the output into @var{cmd}.
5247 This should normally be a command like @samp{lpr} or
5248 @samp{cat > /tmp/scrprint}.
5249 @code{Printcmd} without an argument displays the current setting.
5250 The ansi sequence @code{ESC \} ends printing and closes the pipe.
5252 Warning: Be careful with this command! If other user have write
5253 access to your terminal, they will be able to fire off print commands.
5256 @node Rendition, Sorendition, Printcmd, Miscellaneous
5258 @deffn Command rendition bell | monitor | silence | so @var{attr} [@var{color}]
5260 Change the way screen renders the titles of windows that have monitor
5261 or bell flags set in caption or hardstatus or windowlist.
5263 about string escapes (@pxref{String Escapes}) for the syntax of
5264 the modifiers. The default for monitor is currently @samp{=b} (bold,
5265 active colors), for bell @samp{=ub} (underline, bold and active colors), and
5266 for silence @samp{=u}.
5269 @node Sorendition, Attrcolor, Rendition, Miscellaneous
5270 @section Sorendition
5271 @deffn Command sorendition [@var{attr} [@var{color}]]
5273 This command has been deprecated. Use @code{rendition so} instead.
5276 @node Attrcolor, Setsid, Sorendition, Miscellaneous
5278 @deffn Command attrcolor @var{attrib} [@var{attribute/color-modifier}]
5280 This command can be used to highlight attributes by changing the color of
5281 the text. If the attribute
5283 is in use, the specified attribute/color modifier is also applied. If no
5284 modifier is given, the current one is deleted. See the chapter
5285 about string escapes (@pxref{String Escapes}) for the syntax of
5286 the modifier. @code{Screen} understands two pseudo-attributes, @code{i}
5287 stands for high-intensity foreground color and @code{I} for
5288 high-intensity background color.
5293 @item attrcolor b "R"
5294 Change the color to bright red if bold text is to be printed.
5295 @item attrcolor u "-u b"
5296 Use blue text instead of underline.
5297 @item attrcolor b ".I"
5298 Use bright colors for bold text. Most terminal emulators do this
5300 @item attrcolor i "+b"
5301 Make bright colored text also bold.
5305 @node Setsid, Eval, Attrcolor, Miscellaneous
5307 @deffn Command setsid state
5309 Normally @code{screen} uses different sessions and process groups for
5310 the windows. If setsid is turned @code{off}, this is not done
5311 anymore and all windows will be in the same process group as the
5312 screen backend process. This also breaks job-control, so be careful.
5313 The default is @code{on}, of course. This command is probably useful
5314 only in rare circumstances.
5317 @node Eval, Maxwin, Setsid, Miscellaneous
5319 @deffn Command eval @var{command1} [@var{command2} ...]
5321 Parses and executes each argument as separate command.
5324 @node Maxwin, Backtick, Eval, Miscellaneous
5326 @deffn Command maxwin @var{n}
5328 Set the maximum window number screen will create. Doesn't affect
5329 already existing windows. The number can be increased only when there are no
5333 @node Backtick, Screen Saver, Maxwin, Miscellaneous
5335 @deffn Command backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}]
5336 @deffnx Command backtick @var{id}
5338 Program the backtick command with the numerical id @var{id}.
5339 The output of such a command is used for substitution of the
5340 @code{%`} string escape (@pxref{String Escapes}).
5341 The specified @var{lifespan} is the number
5342 of seconds the output is considered valid. After this time, the
5343 command is run again if a corresponding string escape is encountered.
5344 The @var{autorefresh} parameter triggers an
5345 automatic refresh for caption and hardstatus strings after the
5346 specified number of seconds. Only the last line of output is used
5349 If both the @var{lifespan} and the @var{autorefresh} parameters
5350 are zero, the backtick program is expected to stay in the
5351 background and generate output once in a while.
5352 In this case, the command is executed right away and screen stores
5353 the last line of output. If a new line gets printed screen will
5354 automatically refresh the hardstatus or the captions.
5356 The second form of the command deletes the backtick command
5357 with the numerical id @var{id}.
5360 @node Screen Saver, Zmodem, Backtick, Miscellaneous
5361 @section Screen Saver
5362 @deffn Command idle [@var{timeout} [@var{cmd} @var{args}]]
5364 Sets a command that is run after the specified number of
5365 seconds inactivity is reached. This command will normally
5366 be the @code{blanker} command to create a screen blanker, but
5367 it can be any screen command. If no command is specified,
5368 only the timeout is set. A timeout of zero (ot the special
5369 timeout @code{off}) disables the timer. If no arguments are
5370 given, the current settings are displayed.
5373 @deffn Command blanker
5375 Activate the screen blanker. First the screen is cleared.
5376 If no blanker program is defined, the cursor is turned
5377 off, otherwise, the program is started and it's output is
5378 written to the screen. The screen blanker is killed with
5379 the first keypress, the read key is discarded.
5381 This command is normally used together with the @code{idle}
5385 @deffn Command blankerprg [@var{program args}]
5386 Defines a blanker program. Disables the blanker program if an
5387 empty argument is given. Shows the currently set blanker program if no
5388 arguments are given.
5392 @node Zmodem, , Screen Saver, Miscellaneous
5394 @deffn Command zmodem [off|auto|catch|pass]
5395 @deffnx Command zmodem sendcmd [string]
5396 @deffnx Command zmodem recvcmd [string]
5398 Define zmodem support for @code{screen}. @code{Screen} understands two
5399 different modes when it detects a zmodem request: @code{pass}
5400 and @code{catch}. If the mode is set to @code{pass}, screen will
5401 relay all data to the attacher until the end of the
5402 transmission is reached. In @code{catch} mode screen acts as a
5403 zmodem endpoint and starts the corresponding rz/sz commands.
5404 If the mode is set to @code{auto}, screen will use @code{catch} if
5405 the window is a tty (e.g. a serial line), otherwise it
5406 will use @code{pass}.
5408 You can define the templates screen uses in @code{catch} mode
5409 via the second and the third form.
5411 Note also that this is an experimental feature.
5414 @node String Escapes, Environment, Miscellaneous, Top
5415 @chapter String Escapes
5416 @cindex string escapes
5417 Screen provides an escape mechanism to insert information like the
5418 current time into messages or file names. The escape character
5419 is @code{%} with one exception: inside of a window's hardstatus
5420 @code{^%} (@code{^E}) is used instead.
5422 Here is the full list of supported escapes:
5426 the escape character itself
5428 either @code{am} or @code{pm}
5430 either @code{AM} or @code{PM}
5432 current time @code{HH:MM} in 24h format
5434 current time @code{HH:MM} in 12h format
5440 flags of the window. @xref{Windows}, for meanings of the various flags.
5442 sets %? to true if the window has the focus
5444 hardstatus of the window
5446 hostname of the system
5448 current load of the system
5456 sets %? to true if the current region is in copy/paste mode
5464 all other users on this window
5466 all window numbers and names. With @code{-} qualifier: up to the current
5467 window; with @code{+} qualifier: starting with the window after the current
5470 all window numbers and names except the current one
5472 last two digits of the year number
5476 the part to the next @code{%?} is displayed only if a @code{%} escape
5477 inside the part expands to a non-empty string
5479 else part of @code{%?}
5481 pad the string to the display's width (like TeX's hfill). If a
5482 number is specified, pad to the percentage of the window's width.
5483 A @code{0} qualifier tells screen to treat the number as absolute position.
5484 You can specify to pad relative to the last absolute pad position
5485 by adding a @code{+} qualifier or to pad relative to the right margin
5486 by using @code{-}. The padding truncates the string if the specified
5487 position lies before the current position. Add the @code{L} qualifier
5490 same as @code{%=} but just do truncation, do not fill with spaces
5492 mark the current text position for the next truncation. When
5493 screen needs to do truncation, it tries to do it in a way that
5494 the marked position gets moved to the specified percentage of
5495 the output area. (The area starts from the last absolute pad
5496 position and ends with the position specified by the truncation
5497 operator.) The @code{L} qualifier tells screen to mark the truncated
5498 parts with @samp{...}.
5500 attribute/color modifier string terminated by the next @code{@}}
5502 Substitute with the output of a `backtick' command. The length
5503 qualifier is misused to identify one of the commands. @xref{Backtick}.
5505 The @code{c} and @code{C} escape may be qualified with a @code{0} to
5507 zero instead of space as fill character.
5509 @code{=} escapes understand
5510 a length qualifier (e.g. @code{%3n}), @code{D} and @code{M} can be
5511 prefixed with @code{L} to generate long names, @code{w} and
5512 @code{W} also show the window flags if @code{L} is given.
5514 An attribute/color modifier is is used to change the attributes or the
5515 color settings. Its format
5516 is @samp{[attribute modifier] [color description]}. The attribute modifier
5517 must be prefixed by a change type indicator if it can be confused with
5518 a color description. The following change types are known:
5521 add the specified set to the current attributes
5523 remove the set from the current attributes
5525 invert the set in the current attributes
5527 change the current attributes to the specified set
5529 The attribute set can either be specified as a hexadecimal number or
5530 a combination of the following letters:
5545 Colors are coded either as a hexadecimal number or two letters specifying
5546 the desired background and foreground color (in that order). The following
5568 leave color unchanged
5570 The capitalized versions of the letter specify bright colors. You can also
5571 use the pseudo-color @samp{i} to set just the brightness and leave the color
5574 A one digit/letter color description is treated as foreground or
5575 background color dependent on the current attributes: if reverse mode is
5576 set, the background color is changed instead of the foreground color.
5577 If you don't like this, prefix the color with a @samp{.}. If you want
5578 the same behavior for two-letter color descriptions, also prefix them
5581 As a special case, @samp{%@{-@}} restores the attributes and colors that
5582 were set before the last change was made (i.e. pops one level of the
5583 color-change stack).
5589 set color to bright green
5593 clear all attributes, write in default color on yellow background.
5594 @item %-Lw%@{= BW@}%50>%n%f* %t%@{-@}%+Lw%<
5595 The available windows centered at the current win dow and truncated to
5596 the available width. The current window is displayed white on blue.
5597 This can be used with @samp{hardstatus alwayslastline}.
5598 @item %?%F%@{.R.@}%?%3n %t%? [%h]%?
5599 The window number and title and the window's hardstatus, if one is set.
5600 Also use a red background if this is the active focus.
5601 Useful for @samp{caption string}.
5605 @node Environment, Files, String Escapes, Top
5606 @chapter Environment Variables
5611 Number of columns on the terminal (overrides termcap entry).
5614 Directory in which to look for .screenrc.
5617 Number of lines on the terminal (overrides termcap entry).
5620 Screen lock program.
5622 @item NETHACKOPTIONS
5623 Turns on @code{nethack} option.
5626 Used for locating programs to run.
5629 For customizing a terminal's @code{TERMCAP} value.
5632 Alternate socket directory.
5635 Alternate user screenrc file.
5638 Default shell program for opening windows (default @file{/bin/sh}).
5641 Alternate socket name. If @code{screen} is invoked, and the environment variable
5642 @code{STY} is set, then it creates only a window in the running @code{screen}
5643 session rather than starting a new session.
5646 Alternate system screenrc file.
5652 Terminal description.
5655 Window number of a window (at creation time).
5658 @node Files, Credits, Environment, Top
5659 @chapter Files Referenced
5663 @item .../screen-4.?.??/etc/screenrc
5664 @itemx .../screen-4.?.??/etc/etcscreenrc
5665 Examples in the @code{screen} distribution package for private and
5666 global initialization files.
5668 @item @code{$SYSSCREENRC}
5669 @itemx /local/etc/screenrc
5670 @code{screen} initialization commands
5672 @item @code{$SCREENRC}
5673 @itemx @code{$HOME}/.iscreenrc
5674 @itemx @code{$HOME}/.screenrc
5675 Read in after /local/etc/screenrc
5677 @item @code{$SCREENDIR}/S-@var{login}
5679 @item /local/screens/S-@var{login}
5680 Socket directories (default)
5682 @item /usr/tmp/screens/S-@var{login}
5683 Alternate socket directories.
5685 @item @var{socket directory}/.termcap
5686 Written by the @code{dumptermcap} command
5688 @item /usr/tmp/screens/screen-exchange or
5689 @itemx /tmp/screen-exchange
5690 @code{screen} interprocess communication buffer
5692 @item hardcopy.[0-9]
5693 Screen images created by the hardcopy command
5695 @item screenlog.[0-9]
5696 Output log files created by the log command
5698 @item /usr/lib/terminfo/?/* or
5700 Terminal capability databases
5705 @item @code{$LOCKPRG}
5706 Program for locking the terminal.
5709 @node Credits, Bugs, Files, Top
5716 Originally created by Oliver Laumann, this latest version was
5717 produced by Juergen Weigert, Michael Schroeder, Micah Cowan and
5718 Sadrul Habib Chowdhury.
5725 Ken Beal (kbeal@@amber.ssd.csd.harris.com),
5726 Rudolf Koenig (rfkoenig@@informatik.uni-erlangen.de),
5727 Toerless Eckert (eckert@@informatik.uni-erlangen.de),
5728 Wayne Davison (davison@@borland.com),
5729 Patrick Wolfe (pat@@kai.com, kailand!pat),
5730 Bart Schaefer (schaefer@@cse.ogi.edu),
5731 Nathan Glasser (nathan@@brokaw.lcs.mit.edu),
5732 Larry W. Virden (lvirden@@cas.org),
5733 Howard Chu (hyc@@hanauma.jpl.nasa.gov),
5734 Tim MacKenzie (tym@@dibbler.cs.monash.edu.au),
5735 Markku Jarvinen (mta@@@{cc,cs,ee@}.tut.fi),
5736 Marc Boucher (marc@@CAM.ORG),
5737 Doug Siebert (dsiebert@@isca.uiowa.edu),
5738 Ken Stillson (stillson@@tsfsrv.mitre.org),
5739 Ian Frechett (frechett@@spot.Colorado.EDU),
5740 Brian Koehmstedt (bpk@@gnu.ai.mit.edu),
5741 Don Smith (djs6015@@ultb.isc.rit.edu),
5742 Frank van der Linden (vdlinden@@fwi.uva.nl),
5743 Martin Schweikert (schweik@@cpp.ob.open.de),
5744 David Vrona (dave@@sashimi.lcu.com),
5745 E. Tye McQueen (tye%spillman.UUCP@@uunet.uu.net),
5746 Matthew Green (mrg@@eterna.com.au),
5747 Christopher Williams (cgw@@pobox.com),
5748 Matt Mosley (mattm@@access.digex.net),
5749 Gregory Neil Shapiro (gshapiro@@wpi.WPI.EDU),
5750 Jason Merrill (jason@@jarthur.Claremont.EDU),
5751 Johannes Zellner (johannes@@zellner.org),
5752 Pablo Averbuj (pablo@@averbuj.com).
5759 This manual describes version @value{version} of the @code{screen}
5760 program. Its roots are a merge of a custom version 2.3PR7 by Wayne
5761 Davison and several enhancements to Oliver Laumann's version 2.0.
5762 Note that all versions numbered 2.x are copyright by Oliver Laumann.
5764 See also @xref{Availability}.
5766 @node Bugs, Installation, Credits, Top
5770 Just like any other significant piece of software, @code{screen} has a
5771 few bugs and missing features. Please send in a bug report if you have
5772 found a bug not mentioned here.
5775 * Known Bugs:: Problems we know about.
5776 * Reporting Bugs:: How to contact the maintainers.
5777 * Availability:: Where to find the latest screen version.
5780 @node Known Bugs, Reporting Bugs, , Bugs
5785 @samp{dm} (delete mode) and @samp{xs} are not handled correctly (they
5786 are ignored). @samp{xn} is treated as a magic-margin indicator.
5789 @code{screen} has no clue about double-high or double-wide characters.
5790 But this is the only area where @code{vttest} is allowed to fail.
5793 It is not possible to change the environment variable @code{$TERMCAP}
5794 when reattaching under a different terminal type.
5797 The support of terminfo based systems is very limited. Adding extra
5798 capabilities to @code{$TERMCAP} may not have any effects.
5801 @code{screen} does not make use of hardware tabs.
5804 @code{screen} must be installed setuid root on most systems
5805 in order to be able to
5806 correctly change the owner of the tty device file for each window.
5807 Special permission may also be required to write the file
5811 Entries in @file{/etc/utmp} are not removed when @code{screen} is killed
5812 with SIGKILL. This will cause some programs (like "w" or "rwho") to
5813 advertise that a user is logged on who really isn't.
5816 @code{screen} may give a strange warning when your tty has no utmp
5820 When the modem line was hung up, @code{screen} may not automatically detach
5821 (or quit) unless the device driver sends a HANGUP signal. To detach such a
5822 @code{screen} session use the -D or -d command line option.
5825 If a password is set, the command line options -d and -D still detach a
5826 session without asking.
5829 Both @code{breaktype} and @code{defbreaktype} change the break generating
5830 method used by all terminal devices. The first should change a window
5831 specific setting, where the latter should change only the default for new
5835 When attaching to a multiuser session, the user's @file{.screenrc} file is not
5836 sourced. Each users personal settings have to be included in the
5837 @file{.screenrc} file from which the session is booted, or have to be
5841 A weird imagination is most useful to gain full advantage of all the
5845 @node Reporting Bugs, Availability, Known Bugs, Bugs
5846 @section Reporting Bugs
5849 If you find a bug in @code{Screen}, please send electronic mail to
5850 @w{@samp{screen@@uni-erlangen.de}}, and also to
5851 @w{@samp{bug-gnu-utils@@prep.ai.mit.edu}}. Include the version number
5852 of @code{Screen} which you are using. Also include in your message the
5853 hardware and operating system, the compiler used to compile, a
5854 description of the bug behavior, and the conditions that triggered the
5855 bug. Please recompile @code{screen} with the @samp{-DDEBUG} options
5856 enabled, reproduce the bug, and have a look at the debug output written to
5857 the directory @file{/tmp/debug}. If necessary quote suspect passages from the
5858 debug output and show the contents of your @file{config.h} if it matters.
5860 @node Availability, , Reporting Bugs, Bugs
5861 @section Availability
5862 @cindex availability
5864 @code{Screen} is available under the @code{GNU} copyleft.
5866 The latest official release of @code{screen} available via anonymous
5867 ftp from @samp{prep.ai.mit.edu}, @samp{nic.funet.fi} or any other
5868 @code{GNU} distribution site. The home site of
5869 @code{screen} is @samp{ftp.uni-erlangen.de
5870 (131.188.3.71)}, in the directory @file{pub/utilities/screen}.
5871 The subdirectory @samp{private} contains the latest beta testing release.
5872 If you want to help, send a note to screen@@uni-erlangen.de.
5874 @node Installation, Concept Index, Bugs, Top
5875 @chapter Installation
5876 @cindex installation
5878 Since @code{screen} uses pseudo-ttys, the select system call, and
5879 UNIX-domain sockets/named pipes, it will not run under a system that
5880 does not include these features of 4.2 and 4.3 BSD UNIX.
5883 * Socket Directory:: Where screen stores its handle.
5884 * Compiling Screen::
5887 @node Socket Directory,
5888 @section Socket Directory
5889 @cindex socket directory
5891 The socket directory defaults either to @file{$HOME/.screen} or simply to
5892 @file{/tmp/screens} or preferably to @file{/usr/local/screens} chosen at
5893 compile-time. If @code{screen} is installed
5894 setuid root, then the administrator should compile screen with an
5895 adequate (not NFS mounted) @code{SOCKDIR}. If @code{screen} is not
5896 running setuid-root, the user can specify any mode 700 directory in the
5897 environment variable @code{$SCREENDIR}.
5899 @node Compiling Screen, , Socket Directory, Installation
5900 @section Compiling Screen
5901 @cindex compiling screen
5903 To compile and install screen:
5905 The @code{screen} package comes with a @code{GNU Autoconf} configuration
5906 script. Before you compile the package run
5908 @center @code{sh ./configure}
5910 This will create a @file{config.h} and @file{Makefile} for your machine.
5911 If @code{configure} fails for some reason, then look at the examples and
5912 comments found in the @file{Makefile.in} and @file{config.h.in} templates.
5913 Rename @file{config.status} to @file{config.status.@var{machine}} when
5914 you want to keep configuration data for multiple architectures. Running
5915 @code{sh ./config.status.@var{machine}} recreates your configuration
5916 significantly faster than rerunning @code{configure}.
5918 Read through the "User Configuration" section of @file{config.h}, and verify
5919 that it suits your needs.
5920 A comment near the top of this section explains why it's best to
5921 install screen setuid to root.
5922 Check for the place for the global @file{screenrc}-file and for the socket
5925 Check the compiler used in @file{Makefile}, the prefix path where to install
5926 @code{screen}. Then run
5930 If @code{make} fails to produce one of the files @file{term.h}, @file{comm.h}
5931 or @file{tty.c}, then use @code{@var{filename.x}.dist} instead.
5932 For additional information about installation of @code{screen} refer to the
5933 file @file{INSTALLATION}, coming with this package.
5935 @node Concept Index, Command Index, Installation, Top
5936 @unnumbered Concept Index
5940 @node Command Index, Keystroke Index, Concept Index, Top
5941 @unnumbered Command Index
5943 This is a list of all the commands supported by @code{screen}.
5947 @node Keystroke Index, , Command Index, Top
5948 @unnumbered Keystroke Index
5950 This is a list of the default key bindings.
5952 The leading escape character (@pxref{Command Character}) has been omitted
5953 from the key sequences, since it is the same for all bindings.