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
76 @node Top, Overview, (dir), (dir)
80 This file documents the @code{Screen} virtual terminal manager, version
85 * Overview:: Preliminary information.
86 * Getting Started:: An introduction to @code{screen}.
87 * Invoking Screen:: Command line options for @code{screen}.
88 * Customization:: The @file{.screenrc} file.
89 * Commands:: List all of the commands.
90 * New Window:: Running a program in a new window.
91 * Selecting:: Selecting a window to display.
92 * Session Management:: Suspend/detach, grant access, connect sessions.
93 * Regions:: Split-screen commands.
94 * Window Settings:: Titles, logging, etc.
95 * Virtual Terminal:: Controlling the @code{screen} VT100 emulation.
96 * Copy and Paste:: Exchanging text between windows and sessions.
97 * Subprocess Execution:: I/O filtering with @code{exec}.
98 * Key Binding:: Binding commands to keys.
99 * Flow Control:: Trap or pass flow control characters.
100 * Termcap:: Tweaking your terminal's termcap entry.
101 * Message Line:: The @code{screen} message line.
102 * Logging:: Keeping a record of your session.
103 * Startup:: Functions only useful at @code{screen} startup.
104 * Miscellaneous:: Various other commands.
105 * String Escapes:: Inserting current information into strings
106 * Environment:: Environment variables used by @code{screen}.
107 * Files:: Files used by @code{screen}.
108 * Credits:: Who's who of @code{screen}.
109 * Bugs:: What to do if you find a bug.
110 * Installation:: Getting @code{screen} running on your system.
111 * Concept Index:: Index of concepts.
112 * Command Index:: Index of all @code{screen} commands.
113 * Keystroke Index:: Index of default key bindings.
116 @node Overview, Getting Started, Top, Top
120 Screen is a full-screen window manager that multiplexes a physical
121 terminal between several processes, typically interactive shells. Each
122 virtual terminal provides the functions of the DEC VT100 terminal and,
123 in addition, several control functions from the ISO 6429 (ECMA 48, ANSI X3.64)
124 and ISO 2022 standards (e.g. insert/delete line and support for multiple
125 character sets). There is a scrollback history buffer for each virtual
126 terminal and a copy-and-paste mechanism that allows the user to move
127 text regions between windows.
129 When @code{screen} is called, it creates a single window with a shell in
130 it (or the specified command) and then gets out of your way so that you
131 can use the program as you normally would. Then, at any time, you can
132 create new (full-screen) windows with other programs in them (including
133 more shells), kill the current window, view a list of the active
134 windows, turn output logging on and off, copy text between windows, view
135 the scrollback history, switch between windows, etc. All windows run
136 their programs completely independent of each other. Programs continue
137 to run when their window is currently not visible and even when the
138 whole screen session is detached from the user's terminal.
140 When a program terminates, @code{screen} (per default) kills the window
141 that contained it. If this window was in the foreground, the display
142 switches to the previously displayed window; if none are left,
145 Everything you type is sent to the program running in the current
146 window. The only exception to this is the one keystroke that is used to
147 initiate a command to the window manager. By default, each command
148 begins with a control-a (abbreviated @kbd{C-a} from now on), and is
149 followed by one other keystroke. The command character (@pxref{Command
150 Character}) and all the key bindings (@pxref{Key Binding}) can be fully
151 customized to be anything you like, though they are always two
152 characters in length.
154 @code{Screen} does not understand the prefix @kbd{C-} to mean control.
155 Please use the caret notation (@kbd{^A} instead of @kbd{C-a}) as arguments
156 to e.g. the @code{escape} command or the @code{-e} option. @code{Screen}
157 will also print out control characters in caret notation.
159 The standard way to create a new window is to type @kbd{C-a c}. This
160 creates a new window running a shell and switches to that window
161 immediately, regardless of the state of the process running in the
162 current window. Similarly, you can create a new window with a custom
163 command in it by first binding the command to a keystroke (in your
164 @file{.screenrc} file or at the @kbd{C-a :} command line) and then using it
165 just like the @kbd{C-a c} command. In addition, new windows can be created by
166 running a command like:
173 from a shell prompt within a previously created window. This will not
174 run another copy of @code{screen}, but will instead supply the command
175 name and its arguments to the window manager (specified in the $STY environment
176 variable) who will use it to create the new window. The above example would
177 start the @code{emacs} editor (editing @file{prog.c}) and switch to its window.
179 If @file{/etc/utmp} is writable by @code{screen}, an appropriate record
180 will be written to this file for each window, and removed when the
181 window is closed. This is useful for working with @code{talk},
182 @code{script}, @code{shutdown}, @code{rsend}, @code{sccs} and other
183 similar programs that use the utmp file to determine who you are. As
184 long as @code{screen} is active on your terminal, the terminal's own
185 record is removed from the utmp file. @xref{Login}.
187 @node Getting Started, Invoking Screen, Overview, Top
188 @chapter Getting Started
191 Before you begin to use @code{screen} you'll need to make sure you have
192 correctly selected your terminal type, just as you would for any other
193 termcap/terminfo program. (You can do this by using @code{tset},
194 @code{qterm}, or just @code{set term=mytermtype}, for example.)
196 If you're impatient and want to get started without doing a lot more
197 reading, you should remember this one command: @kbd{C-a ?} (@pxref{Key
198 Binding}). Typing these two characters will display a list of the
199 available @code{screen} commands and their bindings. Each keystroke is
200 discussed in the section on keystrokes (@pxref{Default Key Bindings}).
201 Another section (@pxref{Customization}) deals with the contents of your
204 If your terminal is a ``true'' auto-margin terminal (it doesn't allow
205 the last position on the screen to be updated without scrolling the
206 screen) consider using a version of your terminal's termcap that has
207 automatic margins turned @emph{off}. This will ensure an accurate
208 and optimal update of the screen in all circumstances. Most terminals
209 nowadays have ``magic'' margins (automatic margins plus usable last
210 column). This is the VT100 style type and perfectly suited for
212 If all you've got is a ``true'' auto-margin terminal @code{screen}
213 will be content to use it, but updating a character put into the last
214 position on the screen may not be possible until the screen scrolls or
215 the character is moved into a safe position in some other way. This
216 delay can be shortened by using a terminal with insert-character
219 @xref{Special Capabilities}, for more information about telling
220 @code{screen} what kind of terminal you have.
222 @node Invoking Screen, Customization, Getting Started, Top
223 @chapter Invoking @code{Screen}
226 @cindex command line options
228 Screen has the following command-line options:
232 Include @emph{all} capabilities (with some minor exceptions) in each
233 window's termcap, even if @code{screen} must redraw parts of the display
234 in order to implement a function.
237 Adapt the sizes of all windows to the size of the display. By default,
238 @code{screen} may try to restore its old window sizes when attaching to
239 resizable terminals (those with @samp{WS} in their descriptions, e.g.
240 @code{suncmd} or some varieties of @code{xterm}).
243 Use @var{file} as the user's configuration file instead of the default
244 of @file{$HOME/.screenrc}.
246 @item -d [@var{pid.sessionname}]
247 @itemx -D [@var{pid.sessionname}]
248 Do not start @code{screen}, but instead detach a @code{screen} session
249 running elsewhere (@pxref{Detach}). @samp{-d} has the same effect as
250 typing @kbd{C-a d} from the controlling terminal for the session.
251 @samp{-D} is the equivalent to the power detach key. If no session can
252 be detached, this option is ignored. In combination with the
253 @code{-r}/@code{-R} option more powerful effects can be achieved:
257 Reattach a session and if necessary detach it first.
259 Reattach a session and if necessary detach or even create it first.
261 Reattach a session and if necessary detach or create it.
262 Use the first session if more than one session is available.
264 Reattach a session. If necessary detach and logout remotely first.
266 Attach here and now. In detail this means: If a session is running,
267 then reattach. If necessary detach and logout remotely first. If it
268 was not running create it and notify the user.
269 This is the author's favorite.
271 Attach here and now. Whatever that means, just do it.
274 @emph{Note}: It is a good idea to check the status of your sessions
275 with @code{screen -list} before using this option.
278 Set the command character to @var{x}, and the character generating a
279 literal command character (when typed after the command character) to
280 @var{y}. The defaults are @kbd{C-a} and @kbd{a}, which can be specified
281 as @samp{-e^Aa}. When creating a @code{screen} session, this option
282 sets the default command character. In a multiuser session all users
283 added will start off with this command character. But when attaching
284 to an already running session, this option only changes the command
285 character of the attaching user.
286 This option is equivalent to the commands @code{defescape} or
287 @code{escape} respectively. (@pxref{Command Character}).
292 Set flow-control to on, off, or automatic switching mode, respectively.
293 This option is equivalent to the @code{defflow} command (@pxref{Flow
297 Set the history scrollback buffer to be @var{num} lines high.
298 Equivalent to the @code{defscrollback} command (@pxref{Copy}).
301 Cause the interrupt key (usually @kbd{C-c}) to interrupt the display
302 immediately when flow control is on. This option is equivalent to the
303 @code{interrupt} argument to the @code{defflow} command (@pxref{Flow
304 Control}). Its use is discouraged.
308 Turn login mode on or off (for @file{/etc/utmp} updating). This option
309 is equivalent to the @code{deflogin} command (@pxref{Login}).
311 @item -ls [@var{match}]
312 @itemx -list [@var{match}]
313 Do not start @code{screen}, but instead print a list of session
314 identification strings (usually of the form @var{pid.tty.host};
315 @pxref{Session Name}). Sessions marked @samp{detached} can be resumed
316 with @code{screen -r}. Those marked @samp{attached} are running and
317 have a controlling terminal. If the session runs in multiuser mode,
318 it is marked @samp{multi}. Sessions marked as @samp{unreachable} either
319 live on a different host or are dead.
320 An unreachable session is considered dead, when its name matches either the
321 name of the local host, or the specified parameter, if any.
322 See the @code{-r} flag for a description how to construct matches.
323 Sessions marked as @samp{dead} should be thoroughly checked and removed.
324 Ask your system administrator if you are not sure.
325 Remove sessions with the @samp{-wipe} option.
328 Tell @code{screen} to turn on automatic output logging for the
332 Tell @code{screen} to ignore the @code{$STY} environment variable. When
333 this option is used, a new session will always be created, regardless of
334 whether @code{screen} is being called from within another @code{screen}
335 session or not. This flag has a special meaning in connection
336 with the @samp{-d} option:
339 Start @code{screen} in @emph{detached} mode. This creates a new
340 session but doesn't attach to it. This is useful for system startup
343 This also starts @code{screen} in @emph{detached} mode, but doesn't fork
344 a new process. The command exits if the session terminates.
347 @item -p @var{name_or_number}
348 Preselect a window. This is useful when you want to reattach to a
349 specific window or you want to send a command via the @samp{-X}
350 option to a specific window. As with screen's select command, @samp{-}
351 selects the blank window. As a special case for reattach, @samp{=}
352 brings up the windowlist on the blank window.
355 Suppress printing of error messages. In combination with @samp{-ls} the exit
356 value is set as follows: 9 indicates a directory without sessions. 10
357 indicates a directory with running but not attachable sessions. 11 (or more)
358 indicates 1 (or more) usable sessions.
359 In combination with @samp{-r} the exit value is as follows: 10 indicates that
360 there is no session to resume. 12 (or more) indicates that there are 2 (or
361 more) sessions to resume and you should specify which one to choose.
362 In all other cases @samp{-q} has no effect.
364 @item -r [@var{pid.sessionname}]
365 @itemx -r @var{sessionowner}/[@var{pid.sessionname}]
366 Resume a detached @code{screen} session. No other options (except
367 combinations with @samp{-d} or @samp{-D}) may be specified, though
369 (@pxref{Session Name}) may be needed to distinguish between multiple
370 detached @code{screen} sessions.
371 The second form is used to connect to another user's screen session which
372 runs in multiuser mode. This indicates that screen should look for
373 sessions in another user's directory. This requires setuid-root.
376 Resume the first appropriate detached @code{screen} session. If
377 successful, all other command-line options are ignored. If no detached
378 session exists, start a new session using the specified options, just as
379 if @samp{-R} had not been specified. This option is set by default if
380 screen is run as a login-shell (actually screen uses @samp{-xRR} in
382 For combinations with the
383 @samp{-D}/@samp{-d} option see there.
385 @item -s @var{program}
386 Set the default shell to be @var{program}. By default, @code{screen}
387 uses the value of the environment variable @code{$SHELL}, or
388 @file{/bin/sh} if it is not defined. This option is equivalent to the
389 @code{shell} command (@pxref{Shell}).
391 @item -S @var{sessionname}
392 Set the name of the new session to @var{sessionname}. This option can
393 be used to specify a meaningful name for the session in place of the
394 default @var{tty.host} suffix. This name identifies the session for the
395 @code{screen -list} and @code{screen -r} commands. This option is
396 equivalent to the @code{sessionname} command (@pxref{Session Name}).
399 Set the title (name) for the default shell or specified program.
400 This option is equivalent to the @code{shelltitle} command
404 Run screen in UTF-8 mode. This option tells screen that your terminal
405 sends and understands UTF-8 encoded characters. It also sets the default
406 encoding for new windows to @samp{utf8}.
409 Print the version number.
411 @item -wipe [@var{match}]
412 List available screens like @code{screen -ls}, but remove destroyed
413 sessions instead of marking them as @samp{dead}.
414 An unreachable session is considered dead, when its name matches either
415 the name of the local host, or the explicitly given parameter, if any.
416 See the @code{-r} flag for a description how to construct matches.
419 Attach to a session which is already attached elsewhere (multi-display
421 @code{Screen} refuses to attach from within itself.
422 But when cascading multiple screens, loops are not detected; take care.
426 Send the specified command to a running screen session. You can use
427 the @code{-d} or @code{-r} option to tell screen to look only for
428 attached or detached screen sessions. Note that this command doesn't
429 work if the session is password protected.
433 @node Customization, Commands, Invoking Screen, Top
434 @chapter Customizing @code{Screen}
435 @cindex customization
437 You can modify the default settings for @code{screen} to fit your tastes
438 either through a personal @file{.screenrc} file which contains commands
439 to be executed at startup, or on the fly using the @code{colon} command.
442 * Startup Files:: The @file{.screenrc} file.
443 * Source:: Read commands from a file.
444 * Colon:: Entering customization commands interactively.
447 @node Startup Files, Source, , Customization
448 @section The @file{.screenrc} file
451 When @code{screen} is invoked, it executes initialization commands from
452 the files @file{.screenrc} in the user's home directory and
453 @file{/usr/local/etc/screenrc}. These defaults can be overridden in the
455 For the global screenrc file @code{screen} searches for the environment
456 variable @code{$SYSSCREENRC} (this override feature may be disabled at
457 compile-time). The user specific screenrc file is
458 searched for in @code{$SCREENRC}, then
459 @file{@code{$HOME}/.screenrc}. The command line option @samp{-c}
460 specifies which file to use (@pxref{Invoking Screen}. Commands in these
461 files are used to set options, bind commands to keys, and to
462 automatically establish one or more windows at the beginning of
463 your @code{screen} session. Commands are listed one per line, with
464 empty lines being ignored. A command's arguments are separated by tabs
465 or spaces, and may be surrounded by single or double quotes. A @samp{#}
466 turns the rest of the line into a comment, except in quotes.
467 Unintelligible lines are warned about and ignored. Commands may contain
468 references to environment variables. The syntax is the shell-like
469 @code{$VAR} or @code{$@{VAR@}}. Note that this causes incompatibility
470 with previous @code{screen} versions, as now the '$'-character has to be
471 protected with '\' if no variable substitution is intended. A string in
472 single-quotes is also protected from variable substitution.
474 Two configuration files are shipped as examples with your screen
475 distribution: @file{etc/screenrc} and @file{etc/etcscreenrc}. They
476 contain a number of useful examples for various commands.
478 @node Source, Colon, Startup Files, Customization
480 @deffn Command source file
482 Read and execute commands from file @var{file}. Source commands
483 may be nested to a maximum recursion level of ten. If @var{file}
484 is not an absolute path and screen is already processing a
485 source command, the parent directory of the running source
486 command file is used to search for the new command file before
487 screen's current directory.
489 Note that termcap/terminfo/termcapinfo commands only work
490 at startup and reattach time, so they must be reached via
491 the default screenrc files to have an effect.
494 @node Colon, , Source, Customization
496 Customization can also be done online, with this command:
501 Allows you to enter @file{.screenrc} command lines. Useful for
502 on-the-fly modification of key bindings, specific window creation and
503 changing settings. Note that the @code{set} keyword no longer exists,
504 as of version 3.3. Change default settings with commands starting with
505 @samp{def}. You might think of this as the @code{ex} command mode of
506 @code{screen}, with @code{copy} as its @code{vi} command mode
507 (@pxref{Copy and Paste}).
510 @node Commands, New Window, Customization, Top
513 A command in @code{screen} can either be bound to a key, invoked from a
514 screenrc file, or called from the @code{colon} prompt
515 (@pxref{Customization}). As of version 3.3, all commands can be bound
516 to keys, although some may be less useful than others.
517 For a number of real life working examples of the most important
518 commands see the files @file{etc/screenrc} and @file{etc/etcscreenrc}
519 of your screen distribution.
521 In this manual, a command definition looks like this:
524 @item -- Command: command [-n] ARG1 [ARG2] @dots{}
525 (@var{keybindings})@*
526 This command does something, but I can't remember what.
529 An argument in square brackets (@samp{[]}) is optional. Many commands
530 take an argument of @samp{on} or @samp{off}, which is indicated as
531 @var{state} in the definition.
534 * Default Key Bindings:: @code{screen} keyboard commands.
535 * Command Summary:: List of all commands.
538 @node Default Key Bindings, Command Summary, , Commands
539 @section Default Key Bindings
541 As mentioned previously, each keyboard command consists of a
542 @kbd{C-a} followed by one other character. For your convenience, all
543 commands that are bound to lower-case letters are also bound to their
544 control character counterparts (with the exception of @kbd{C-a a}; see
545 below). Thus, both @kbd{C-a c} and @kbd{C-a C-c} can be used to create
548 The following table shows the default key bindings:
553 Prompt for a window identifier and switch.
558 Present a list of all windows for selection.
561 @item @kbd{C-a 0@dots{}9, -}
562 (select 0@dots{}select 9, select -)@*
563 Switch to window number 0@dots{}9, or the blank window.
566 @item @kbd{C-a @key{Tab}}
568 Switch the input focus to the next region. @xref{Regions}.
572 Toggle to the window displayed previously. If this window does no
573 longer exist, @code{other} has the same effect as @code{next}.
578 Send the command character (C-a) to window. See @code{escape} command.
579 @xref{Command Character}.
583 Allow the user to enter a title for the current window.
584 @xref{Naming Windows}.
589 Send a break to the tty.
594 Close and reopen the tty-line.
600 Create a new window with a shell and switch to that window.
601 @xref{Screen Command}.
605 Clear the screen. @xref{Clear}.
610 Detach @code{screen} from this terminal. @xref{Detach}.
614 Detach and logout. @xref{Power Detach}.
619 Cycle flow among @samp{on}, @samp{off} or @samp{auto}. @xref{Flow}.
623 Resize the window to the current region size. @xref{Window Size}.
627 Toggle visual bell mode. @xref{Bell}.
631 Write a hardcopy of the current window to the file ``hardcopy.@var{n}''.
636 Toggle logging of the current window to the file ``screenlog.@var{n}''.
642 Show info about the current window. @xref{Info}.
647 Destroy the current window. @xref{Kill}.
652 Fully refresh the current window. @xref{Redisplay}.
656 Toggle the current window's login state. @xref{Login}.
661 Repeat the last message displayed in the message line.
666 Toggle monitoring of the current window. @xref{Monitor}.
668 @item @kbd{C-a @key{SPC}}
672 Switch to the next window. @xref{Selecting}.
676 Show the number (and title) of the current window. @xref{Number}.
681 @itemx @kbd{C-a @key{BackSpace}}
683 Switch to the previous window (opposite of @kbd{C-a n}).
689 Send a ^Q (ASCII XON) to the current window. @xref{XON/XOFF}.
693 Delete all regions but the current one. @xref{Regions}.
698 Toggle the current window's line-wrap setting (turn the current window's
699 automatic margins on or off). @xref{Wrap}.
704 Send a ^S (ASCII XOFF) to the current window. @xref{XON/XOFF}.
708 Split the current region into two new ones. @xref{Regions}.
713 Show the load average and xref. @xref{Time}.
717 Display the version and compilation date. @xref{Version}.
721 Enter digraph. @xref{Digraph}.
726 Show a list of active windows. @xref{Windows}.
730 Toggle between 80 and 132 columns. @xref{Window Size}.
735 Lock your terminal. @xref{Lock}.
739 Kill the current region. @xref{Regions}.
744 Suspend @code{screen}. @xref{Suspend}.
748 Reset the virtual terminal to its ``power-on'' values.
753 Write out a @file{.termcap} file. @xref{Dump Termcap}.
757 Show key bindings. @xref{Help}.
761 Kill all windows and terminate @code{screen}. @xref{Quit}.
765 Enter a command line. @xref{Colon}.
769 @itemx @kbd{C-a @key{ESC}}
771 Enter copy/scrollback mode. @xref{Copy}.
776 Write the contents of the paste buffer to the stdin queue of the
777 current window. @xref{Paste}.
782 Copy and paste a previous (command) line. @xref{History}.
786 Write the paste buffer out to the screen-exchange file.
787 @xref{Screen Exchange}.
791 Read the screen-exchange file into the paste buffer.
792 @xref{Screen Exchange}.
796 Delete the screen-exchange file. @xref{Screen Exchange}.
800 Start/stop monitoring the current window for inactivity. @xref{Silence},
804 Show the copyright page.
808 Show the listing of attached displays.
811 @node Command Summary, , Default Key Bindings, Commands
812 @section Command Summary
813 @cindex command summary
816 @item acladd @var{usernames}
817 Allow other users in this session. @xref{Multiuser Session}.
818 @item aclchg @var{usernames permbits list}
819 Change a user's permissions. @xref{Multiuser Session}.
820 @item acldel @var{username}
821 Disallow other user in this session. @xref{Multiuser Session}.
822 @item aclgrp @var{usrname} [@var{groupname}]
823 Inherit permissions granted to a group leader. @xref{Multiuser Session}.
824 @item aclumask [@var{users}]+/-@var{bits} ...
825 Predefine access to new windows. @xref{Umask}.
826 @item activity @var{message}
827 Set the activity notification message. @xref{Monitor}.
828 @item addacl @var{usernames}
829 Synonym to @code{acladd}. @xref{Multiuser Session}.
830 @item allpartial @var{state}
831 Set all windows to partial refresh. @xref{Redisplay}.
832 @item altscreen @var{state}
833 Enables support for the "alternate screen" terminal capability. @xref{Redisplay}.
834 @item at [@var{ident}][@kbd{#}@var{|}@kbd{*}@var{|}@kbd{%}] @var{command} [@var{args}]
835 Execute a command at other displays or windows. @xref{At}.
836 @item attrcolor @var{attrib} [@var{attribute/color-modifier}]
837 Map attributes to colors. @xref{Attrcolor}.
838 @item autodetach @var{state}
839 Automatically detach the session on SIGHUP. @xref{Detach}.
840 @item autonuke @var{state}
841 Enable a clear screen to discard unwritten output. @xref{Autonuke}.
842 @item backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}]
843 Define a command for the backtick string escape. @xref{Backtick}.
844 @item bce [@var{state}]
845 Change background color erase. @xref{Character Processing}.
846 @item bell_msg [@var{message}]
847 Set the bell notification message. @xref{Bell}.
848 @item bind [-c @var{class}] @var{key} [@var{command} [@var{args}]]
849 Bind a command to a key. @xref{Bind}.
850 @item bindkey [@var{opts}] [@var{string} [@var{cmd args}]]
851 Bind a string to a series of keystrokes. @xref{Bindkey}.
853 Blank the screen. @xref{Screen Saver}.
855 Define a blanker program. @xref{Screen Saver}.
856 @item break [@var{duration}]
857 Send a break signal to the current window. @xref{Break}.
858 @item breaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}]
859 Specify how to generate breaks. @xref{Break}.
860 @item bufferfile [@var{exchange-file}]
861 Select a file for screen-exchange. @xref{Screen Exchange}.
862 @item c1 [@var{state}]
863 Change c1 code processing. @xref{Character Processing}.
864 @item caption @var{mode} [@var{string}]
865 Change caption mode and string. @xref{Regions}.
866 @item chacl @var{usernames permbits list}
867 Synonym to @code{aclchg}. @xref{Multiuser Session}.
868 @item charset @var{set}
869 Change character set slot designation. @xref{Character Processing}.
870 @item chdir [@var{directory}]
871 Change the current directory for future windows. @xref{Chdir}.
873 Clear the window screen. @xref{Clear}.
875 Enter a @code{screen} command. @xref{Colon}.
876 @item command [-c @var{class}]
877 Simulate the screen escape key. @xref{Command Character}.
878 @item compacthist [@var{state}]
879 Selects compaction of trailing empty lines. @xref{Scrollback}.
880 @item console [@var{state}]
881 Grab or ungrab console output. @xref{Console}.
883 Enter copy mode. @xref{Copy}.
884 @item copy_reg [@var{key}]
885 Removed. Use @code{paste} instead. @xref{Registers}.
886 @item crlf @var{state}
887 Select line break behavior for copying. @xref{Line Termination}.
888 @item debug @var{state}
889 Suppress/allow debugging output. @xref{Debug}.
890 @item defautonuke @var{state}
891 Select default autonuke behavior. @xref{Autonuke}.
892 @item defbce @var{state}
893 Select background color erase. @xref{Character Processing}.
894 @item defbreaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}]
895 Specify the default for generating breaks. @xref{Break}.
896 @item defc1 @var{state}
897 Select default c1 processing behavior. @xref{Character Processing}.
898 @item defcharset [@var{set}]
899 Change defaul character set slot designation. @xref{Character Processing}.
900 @item defencoding @var{enc}
901 Select default window encoding. @xref{Character Processing}.
902 @item defescape @var{xy}
903 Set the default command and @code{meta} characters. @xref{Command Character}.
904 @item defflow @var{fstate}
905 Select default flow control behavior. @xref{Flow}.
906 @item defgr @var{state}
907 Select default GR processing behavior. @xref{Character Processing}.
908 @item defhstatus [@var{status}]
909 Select default window hardstatus line. @xref{Hardstatus}.
910 @item deflog @var{state}
911 Select default window logging behavior. @xref{Log}.
912 @item deflogin @var{state}
913 Select default utmp logging behavior. @xref{Login}.
914 @item defmode @var{mode}
915 Select default file mode for ptys. @xref{Mode}.
916 @item defmonitor @var{state}
917 Select default activity monitoring behavior. @xref{Monitor}.
918 @item defnonblock @var{state}|@var{numsecs}
919 Select default nonblock mode. @xref{Nonblock}.
920 @item defobuflimit @var{limit}
921 Select default output buffer limit. @xref{Obuflimit}.
922 @item defscrollback @var{num}
923 Set default lines of scrollback. @xref{Scrollback}.
924 @item defshell @var{command}
925 Set the default program for new windows. @xref{Shell}.
926 @item defsilence @var{state}
927 Select default idle monitoring behavior. @xref{Silence}.
928 @item defslowpaste @var{msec}
929 Select the default inter-character timeout when pasting. @xref{Paste}.
930 @item defutf8 @var{state}
931 Select default character encoding. @xref{Character Processing}.
932 @item defwrap @var{state}
933 Set default line-wrapping behavior. @xref{Wrap}.
934 @item defwritelock @var{on|off|auto}
935 Set default writelock behavior. @xref{Multiuser Session}.
936 @item defzombie [@var{keys}]
937 Keep dead windows. @xref{Zombie}.
939 Disconnect @code{screen} from the terminal. @xref{Detach}.
941 Enter digraph sequence. @xref{Digraph}.
943 Display terminal information. @xref{Info}.
945 List currently active user interfaces. @xref{Displays}.
947 Write the window's termcap entry to a file. @xref{Dump Termcap}.
948 @item echo [-n] @var{message}
949 Display a message on startup. @xref{Startup}.
950 @item encoding @var{enc} [@var{denc}]
951 Set the encoding of a window. @xref{Character Processing}.
952 @item escape @var{xy}
953 Set the command and @code{meta} characters. @xref{Command Character}.
954 @item eval @var{command1} [@var{command2} ...]
955 Parse and execute each argument. @xref{Eval}.
956 @item exec [[@var{fdpat}] @var{command} [@var{args} ...]]
957 Run a subprocess (filter). @xref{Exec}.
959 Change window size to current display size. @xref{Window Size}.
960 @item flow [@var{fstate}]
961 Set flow control behavior. @xref{Flow}.
963 Move focus to next region. @xref{Regions}.
964 @item gr [@var{state}]
965 Change GR charset processing. @xref{Character Processing}.
966 @item hardcopy [-h] [@var{file}]
967 Write out the contents of the current window. @xref{Hardcopy}.
968 @item hardcopy_append @var{state}
969 Append to hardcopy files. @xref{Hardcopy}.
970 @item hardcopydir @var{directory}
971 Place, where to dump hardcopy files. @xref{Hardcopy}.
972 @item hardstatus [@var{state}]
973 Use the hardware status line. @xref{Hardware Status Line}.
974 @item height [@var{lines} [@var{cols}]]
975 Set display height. @xref{Window Size}.
976 @item help [-c @var{class}]
977 Display current key bindings. @xref{Help}.
979 Find previous command beginning @dots{}. @xref{History}.
980 @item hstatus @var{status}
981 Change the window's hardstatus line. @xref{Hardstatus}.
982 @item idle [@var{timeout} [@var{cmd} @var{args}]]
983 Define a screen saver command. @xref{Screen Saver}.
984 @item ignorecase [@var{state}]
985 Ignore character case in searches. @xref{Searching}.
987 Display window settings. @xref{Info}.
988 @item ins_reg [@var{key}]
989 Removed, use @code{paste} instead. @xref{Registers}.
991 Destroy the current window. @xref{Kill}.
993 Redisplay the last message. @xref{Last Message}.
995 Display licensing information. @xref{Startup}.
997 Lock the controlling terminal. @xref{Lock}.
998 @item log [@var{state}]
999 Log all output in the current window. @xref{Log}.
1000 @item logfile @var{filename}
1001 Place where to collect logfiles. @xref{Log}.
1002 @item login [@var{state}]
1003 Log the window in @file{/etc/utmp}. @xref{Login}.
1004 @item logtstamp [@var{state}]
1005 Configure logfile time-stamps. @xref{Log}.
1007 Use only the default mapping table for the next keystroke. @xref{Bindkey Control}.
1009 Don't try to do keymapping on the next keystroke. @xref{Bindkey Control}.
1010 @item maptimeout @var{timo}
1011 Set the inter-character timeout used for keymapping. @xref{Bindkey Control}.
1012 @item markkeys @var{string}
1013 Rebind keys in copy mode. @xref{Copy Mode Keys}.
1014 @item maxwin @var{n}
1015 Set the maximum window number. @xref{Maxwin}.
1017 Insert the command character. @xref{Command Character}.
1018 @item monitor [@var{state}]
1019 Monitor activity in window. @xref{Monitor}.
1020 @item msgminwait @var{sec}
1021 Set minimum message wait. @xref{Message Wait}.
1022 @item msgwait @var{sec}
1023 Set default message wait. @xref{Message Wait}.
1024 @item multiuser @var{state}
1025 Go into single or multi user mode. @xref{Multiuser Session}.
1026 @item nethack @var{state}
1027 Use @code{nethack}-like error messages. @xref{Nethack}.
1029 Switch to the next window. @xref{Selecting}.
1030 @item nonblock [@var{state}|@var{numsecs}]
1031 Disable flow control to the current display. @xref{Nonblock}.|@var{numsecs}]
1032 @item number [@var{n}]
1033 Change/display the current window's number. @xref{Number}.
1034 @item obuflimit [@var{limit}]
1035 Select output buffer limit. @xref{Obuflimit}.
1037 Kill all other regions. @xref{Regions}.
1039 Switch to the window you were in last. @xref{Selecting}.
1040 @item partial @var{state}
1041 Set window to partial refresh. @xref{Redisplay}.
1042 @item password [@var{crypted_pw}]
1043 Set reattach password. @xref{Detach}.
1044 @item paste [@var{src_regs} [@var{dest_reg}]]
1045 Paste contents of paste buffer or registers somewhere. @xref{Paste}.
1046 @item pastefont [@var{state}]
1047 Include font information in the paste buffer. @xref{Paste}.
1049 Close and Reopen the window's terminal. @xref{Break}.
1051 Detach and hang up. @xref{Power Detach}.
1052 @item pow_detach_msg [@var{message}]
1053 Set message displayed on @code{pow_detach}. @xref{Power Detach}.
1055 Switch to the previous window. @xref{Selecting}.
1056 @item printcmd [@var{cmd}]
1057 Set a command for VT100 printer port emulation. @xref{Printcmd}.
1058 @item process [@var{key}]
1059 Treat a register as input to @code{screen}. @xref{Registers}.
1061 Kill all windows and exit. @xref{Quit}.
1062 @item readbuf [-e @var{encoding}] [@var{filename}]
1063 Read the paste buffer from the screen-exchange file. @xref{Screen Exchange}.
1064 @item readreg [-e @var{encoding}] [@var{reg} [@var{file}]]
1065 Load a register from paste buffer or file. @xref{Registers}.
1067 Redisplay the current window. @xref{Redisplay}.
1068 @item register [-e @var{encoding}] @var{key} @var{string}
1069 Store a string to a register. @xref{Registers}.
1071 Kill current region. @xref{Regions}.
1073 Delete the screen-exchange file. @xref{Screen Exchange}.
1074 @item rendition bell | monitor | so @var{attr} [@var{color}]
1075 Change text attributes in caption for flagged windows. @xref{Rendition}.
1077 Reset the terminal settings for the window. @xref{Reset}.
1078 @item resize [(+/-)lines]
1079 Grow or shrink a region
1080 @item screen [@var{opts}] [@var{n}] [@var{cmd} [@var{args}]]
1081 Create a new window. @xref{Screen Command}.
1082 @item scrollback @var{num}
1083 Set size of scrollback buffer. @xref{Scrollback}.
1084 @item select [@var{n}]
1085 Switch to a specified window. @xref{Selecting}.
1086 @item sessionname [@var{name}]
1087 Name this session. @xref{Session Name}.
1088 @item setenv [@var{var} [@var{string}]]
1089 Set an environment variable for new windows. @xref{Setenv}.
1090 @item setsid @var{state}
1091 Controll process group creation for windows. @xref{Setsid}.
1092 @item shell @var{command}
1093 Set the default program for new windows. @xref{Shell}.
1094 @item shelltitle @var{title}
1095 Set the default name for new windows. @xref{Shell}.
1096 @item silence [@var{state}|@var{seconds}]
1097 Monitor a window for inactivity. @xref{Silence}.
1098 @item silencewait @var{seconds}
1099 Default timeout to trigger an inactivity notify. @xref{Silence}.
1100 @item sleep @var{num}
1101 Pause during startup. @xref{Startup}.
1102 @item slowpaste @var{msec}
1103 Slow down pasting in windows. @xref{Paste}.
1104 @item source @var{file}
1105 Run commands from a file. @xref{Source}.
1106 @item sorendition [@var{attr} [@var{color}]]
1107 Change text highlighting. @xref{Sorendition}.
1109 Split region into two parts. @xref{Regions}.
1110 @item startup_message @var{state}
1111 Display copyright notice on startup. @xref{Startup}.
1112 @item stuff @var{string}
1113 Stuff a string in the input buffer of a window. @xref{Paste}.
1114 @item su [@var{username} [@var{password} [@var{password2}]]]
1115 Identify a user. @xref{Multiuser Session}.
1117 Put session in background. @xref{Suspend}.
1118 @item term @var{term}
1119 Set @code{$TERM} for new windows. @xref{Term}.
1120 @item termcap @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1121 Tweak termcap entries for best performance. @xref{Termcap Syntax}.
1122 @item terminfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1123 Ditto, for terminfo systems. @xref{Termcap Syntax}.
1124 @item termcapinfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1125 Ditto, for both systems. @xref{Termcap Syntax}.
1126 @item time [@var{string}]
1127 Display time and load average. @xref{Time}.
1128 @item title [@var{windowtitle}]
1129 Set the name of the current window. @xref{Title Command}.
1130 @item umask [@var{users}]+/-@var{bits} ...
1131 Synonym to @code{aclumask}. @xref{Umask}.
1132 @item unsetenv @var{var}
1133 Unset environment variable for new windows. @xref{Setenv}.
1134 @item utf8 [@var{state} [@var{dstate}]]
1135 Select character encoding of the current window. @xref{Character Processing}.
1136 @item vbell [@var{state}]
1137 Use visual bell. @xref{Bell}.
1138 @item vbell_msg [@var{message}]
1139 Set vbell message. @xref{Bell}.
1140 @item vbellwait @var{sec}
1141 Set delay for vbell message. @xref{Bell}.
1143 Display @code{screen} version. @xref{Version}.
1144 @item wall @var{message}
1145 Write a message to all displays. @xref{Multiuser Session}.
1146 @item width [@var{cols} [@var{lines}]]
1147 Set the width of the window. @xref{Window Size}.
1148 @item windowlist [-b] | string [@var{string}] | title [@var{title}]
1149 Present a list of all windows for selection. @xref{Windowlist}.
1151 List active windows. @xref{Windows}.
1152 @item wrap [@var{state}]
1153 Control line-wrap behavior. @xref{Wrap}.
1154 @item writebuf [-e @var{encoding}] [@var{filename}]
1155 Write paste buffer to screen-exchange file. @xref{Screen Exchange}.
1156 @item writelock @var{on}|@var{off}|@var{auto}
1157 Grant exclusive write permission. @xref{Multiuser Session}.
1159 Send an XOFF character. @xref{XON/XOFF}.
1161 Send an XON character. @xref{XON/XOFF}.
1162 @item zmodem [off|auto|catch|pass]
1163 Define how screen treats zmodem requests. @xref{Zmodem}.
1164 @item zombie [@var{keys} [onerror] ]
1165 Keep dead windows. @xref{Zombie}.
1168 @node New Window, Selecting, Commands, Top
1171 This section describes the commands for creating a new window for
1172 running programs. When a new window is created, the first available
1173 number from the range 0@dots{}9 is assigned to it.
1174 The number of windows is limited at compile-time by the MAXWIN
1175 configuration parameter.
1178 * Chdir:: Change the working directory for new windows.
1179 * Screen Command:: Create a new window.
1180 * Setenv:: Set environment variables for new windows.
1181 * Shell:: Parameters for shell windows.
1182 * Term:: Set the terminal type for new windows.
1183 * Window Types:: Creating different types of windows.
1186 @node Chdir, Screen Command, , New Window
1188 @deffn Command chdir [directory]
1190 Change the current directory of @code{screen} to the specified directory
1191 or, if called without an argument, to your home directory (the value of
1192 the environment variable @code{$HOME}). All windows that are created by means
1193 of the @code{screen} command from within @file{.screenrc} or by means of
1194 @kbd{C-a : screen @dots{}} or @kbd{C-a c} use this as their default
1195 directory. Without a @code{chdir} command, this would be the directory
1196 from which @code{screen} was invoked. Hardcopy and log files are always
1197 written to the @emph{window's} default directory, @emph{not} the current
1198 directory of the process running in the window. You can use this
1199 command multiple times in your @file{.screenrc} to start various windows
1200 in different default directories, but the last @code{chdir} value will
1201 affect all the windows you create interactively.
1204 @node Screen Command, Setenv, Chdir, New Window
1205 @section Screen Command
1208 @deffn Command screen [opts] [n] [cmd [args]]
1209 (@kbd{C-a c}, @kbd{C-a C-c})@*
1210 Establish a new window. The flow-control options (@samp{-f}, @samp{-fn}
1211 and @samp{-fa}), title option (@samp{-t}), login options
1212 (@samp{-l} and @samp{-ln}) , terminal type option (@samp{-T @var{term}}),
1213 the all-capability-flag (@samp{-a}) and scrollback option
1214 (@samp{-h @var{num}}) may be specified with each command.
1215 The option (@samp{-M}) turns monitoring on for this window.
1216 The option (@samp{-L}) turns output logging on for this window.
1217 If an optional number @var{n} in the range 0@dots{}9 is given,
1218 the window number @var{n} is assigned to the newly created window (or,
1219 if this number is already in-use, the next available number). If a
1220 command is specified after @code{screen}, this command (with the given
1221 arguments) is started in the window; otherwise, a shell is created.
1223 Screen has built in some functionality of @samp{cu} and @samp{telnet}.
1224 @xref{Window Types}.
1227 Thus, if your @file{.screenrc} contains the lines
1230 # example for .screenrc:
1232 screen -fn -t foobar 2 -L telnet foobar
1236 @code{screen} creates a shell window (in window #1) and a window with a
1237 TELNET connection to the machine foobar (with no flow-control using the
1238 title @samp{foobar} in window #2) and will write a logfile @samp{screenlog.2}
1239 of the telnet session. If you do not include any
1240 @code{screen} commands in your @file{.screenrc} file, then @code{screen}
1241 defaults to creating a single shell window, number zero. When the
1242 initialization is completed, @code{screen} switches to the last window
1243 specified in your .screenrc file or, if none, it opens default window
1246 @node Setenv, Shell, Screen Command, New Window
1248 @deffn Command setenv var string
1250 Set the environment variable @var{var} to value @var{string}.
1251 If only @var{var} is specified, the user will be prompted to enter a value.
1252 If no parameters are specified, the user will be prompted for both variable
1253 and value. The environment is inherited by all subsequently forked shells.
1256 @deffn Command unsetenv var
1258 Unset an environment variable.
1261 @node Shell, Term, Setenv, New Window
1263 @deffn Command shell command
1264 @deffnx Command defshell command
1266 Set the command to be used to create a new shell. This overrides the
1267 value of the environment variable @code{$SHELL}. This is useful if
1268 you'd like to run a tty-enhancer which is expecting to execute the
1269 program specified in @code{$SHELL}. If the command begins with
1270 a @samp{-} character, the shell will be started as a login-shell.
1272 @code{defshell} is currently a synonym to the @code{shell} command.
1275 @deffn Command shelltitle title
1277 Set the title for all shells created during startup or by the C-a C-c
1278 command. @xref{Naming Windows}, for details about what titles are.
1281 @node Term, Window Types , Shell, New Window
1283 @deffn Command term term
1285 In each window @code{screen} opens, it sets the @code{$TERM}
1286 variable to @code{screen} by default, unless no description for
1287 @code{screen} is installed in the local termcap or terminfo data base.
1288 In that case it pretends that the terminal emulator is @samp{vt100}.
1289 This won't do much harm, as @code{screen} is VT100/ANSI compatible. The
1290 use of the @code{term} command is discouraged for non-default purpose.
1291 That is, one may want to specify special @code{$TERM} settings (e.g. vt100) for
1292 the next @code{screen rlogin othermachine} command. Use the command
1293 @code{screen -T vt100 rlogin othermachine} rather than setting
1294 and resetting the default.
1297 @node Window Types, , Term, New Window
1298 @section Window Types
1299 @cindex window types
1300 Screen provides three different window types. New windows are created
1301 with @code{screen}'s @samp{screen} command (@pxref{Screen Command}).
1302 The first parameter to the @samp{screen} command defines which
1303 type of window is created. The different window types are all
1304 special cases of the normal type. They have been added in order
1305 to allow @code{screen} to be used efficiently as a console
1306 with 100 or more windows.
1309 The normal window contains a shell (default, if no parameter is given)
1310 or any other system command that could be executed from a shell.
1311 (e.g. @samp{slogin}, etc...).
1314 If a tty (character special device) name (e.g. @samp{/dev/ttya})
1315 is specified as the first parameter, then the window is directly
1316 connected to this device.
1317 This window type is similar to @samp{screen cu -l /dev/ttya}.
1318 Read and write access is required on the device node,
1319 an exclusive open is attempted on the node to mark the connection line
1321 An optional parameter is allowed consisting of a comma separated
1322 list of flags in the notation used by @samp{stty(1)}:
1325 Usually 300, 1200, 9600 or 19200. This affects transmission as well as
1328 Specify the transmission of eight (or seven) bits per byte.
1330 Enables (or disables) software flow-control (CTRL-S/CTRL-Q) for sending
1332 @item ixoff or -ixoff
1333 Enables (or disables) software flow-control for receiving data.
1334 @item istrip or -istrip
1335 Clear (or keep) the eight bit in each received byte.
1338 You may want to specify as many of these options as applicable.
1339 Unspecified options cause the terminal driver to make up the parameter
1340 values of the connection. These values are system-dependent and may be
1341 in defaults or values saved from a previous connection.
1343 For tty windows, the @code{info} command shows some of the modem
1344 control lines in the status line.
1345 These may include @samp{RTS}, @samp{CTS}, @samp{DTR}, @samp{CD} and
1346 more. This depends rather on on the available @code{ioctl()}'s and system
1347 header files than on the physical capabilities of the serial board.
1348 The name of a logical low (inactive) signal is preceded by an
1349 exclamation mark (@samp{!}), otherwise the signal is logical high (active).
1350 Unsupported but shown signals are usually shown low.
1351 When the @code{CLOCAL} status bit is true, the whole set of modem signals is
1352 placed inside curly braces (@samp{@{} and @samp{@}}).
1353 When the @code{CRTSCTS} or @code{TIOCSOFTCAR} bit is true, the signals
1354 @samp{CTS} or @samp{CD} are shown in parenthesis, respectively.
1356 For tty windows, the command @code{break} causes the Data transmission
1357 line (TxD) to go low for a specified period of time. This is expected
1358 to be interpreted as break signal on the other side.
1359 No data is sent and no modem control line is changed when a
1360 @code{break} is issued.
1363 If the first parameter is @code{//telnet}, the second parameter is
1364 expected to be a host name, and an optional third parameter may specify
1365 a TCP port number (default decimal 23). Screen will connect to a
1366 server listening on the remote host and use the telnet protocol to
1367 communicate with that server.
1369 For telnet windows, the command @code{info} shows details about
1370 the connection in square brackets (@samp{[} and @samp{]}) at the end of
1374 BINARY. The connection is in binary mode.
1376 ECHO. Local echo is disabled.
1378 SGA. The connection is in `character mode' (default: `line mode').
1380 TTYPE. The terminal type has been requested by the remote host. Screen
1381 sends the name @code{screen} unless instructed otherwise (see also the
1382 command @samp{term}).
1384 NAWS. The remote site is notified about window size changes.
1386 LFLOW. The remote host will send flow control information.
1387 (Ignored at the moment.)
1389 Additional flags for debugging are @samp{x}, @samp{t} and @samp{n}
1390 (XDISPLOC, TSPEED and NEWENV).
1392 For telnet windows, the command @code{break} sends the telnet code
1393 @code{IAC BREAK} (decimal 243) to the remote host.
1397 @node Selecting, Session Management, New Window, Top
1398 @chapter Selecting a Window
1400 This section describes the commands for switching between windows in an
1401 @code{screen} session. The windows are numbered from 0 to 9, and are created
1402 in that order by default (@pxref{New Window}).
1405 * Next and Previous:: Forward or back one window.
1406 * Other Window:: Switch back and forth between two windows.
1407 * Select:: Switch to a window (and to one after @code{kill}).
1408 * Windowlist:: Present a list of all windows for selection.
1411 @node Next and Previous, Other Window, , Selecting
1412 @section Moving Back and Forth
1417 (@kbd{C-a @key{SPC}}, @kbd{C-a n}, @kbd{C-a C-n})@*
1418 Switch to the next window. This command can be used repeatedly to
1419 cycle through the list of windows. (On some terminals, C-@key{SPC}
1420 generates a NUL character, so you must release the control key before
1427 (@kbd{C-a p}, @kbd{C-a C-p})@*
1428 Switch to the previous window (the opposite of @kbd{C-a n}).
1431 @node Other Window, Select, Next and Previous, Selecting
1432 @section Other Window
1434 @deffn Command other
1436 Switch to the last window displayed. Note that this command
1437 defaults to the command character typed twice, unless overridden.
1438 For instance, if you use the option @samp{-e]x},
1439 this command becomes @kbd{]]} (@pxref{Command Character}).
1442 @node Select, Windowlist, Other Window, Selecting
1446 @deffn Command select [n]
1447 (@kbd{C-a @var{n}}, @kbd{C-a '})@*
1448 Switch to the window with the number @var{n}.
1449 If no window number is specified, you get prompted for an
1450 identifier. This can be a window name (title) or a number.
1451 When a new window is established, the lowest available number
1452 is assigned to this window.
1453 Thus, the first window can be activated by @code{select 0}; there
1454 can be no more than 10 windows present simultaneously (unless screen is
1455 compiled with a higher MAXWIN setting).
1456 There are two special arguments, @code{select -} switches to the
1457 internal blank window and @code{select .} switches to the
1458 current window. The latter is useful if used with screen's
1463 @node Windowlist, , Select, Selecting
1466 @deffn Command windowlist [-b] [-m]
1467 @deffnx Command windowlist string [@var{string}]
1468 @deffnx Command windowlist title [@var{title}]
1470 Display all windows in a table for visual window selection.
1471 The desired window can be selected via the standard
1472 movement keys (@pxref{Movement}) and activated via
1473 the return key. If the @code{-b} option is given, screen will
1474 switch to the blank window before presenting the list, so
1475 that the current window is also selectable.
1476 The @code{-m} option changes the order of the windows, instead of
1477 sorting by window numbers screen uses its internal most-recently-used
1480 The table format can be changed with the string and title
1481 option, the title is displayed as table heading, while the
1482 lines are made by using the string setting. The default
1483 setting is @samp{Num Name%=Flags} for the title and
1484 @samp{%3n %t%=%f} for the lines. See the string escapes chapter
1485 (@pxref{String Escapes}) for more codes (e.g. color settings).
1489 @node Session Management, Regions, Selecting, Top
1490 @chapter Session Management Commands
1492 Perhaps the most useful feature of @code{screen} is the way it allows
1493 the user to move a session between terminals, by detaching and
1494 reattaching. This also makes life easier for modem users who have to
1495 deal with unexpected loss of carrier.
1498 * Detach:: Disconnect @code{screen} from your terminal.
1499 * Power Detach:: Detach and log out.
1500 * Lock:: Lock your terminal temporarily.
1501 * Multiuser Session:: Changing number of allowed users.
1502 * Session Name:: Rename your session for later reattachment.
1503 * Suspend:: Suspend your session.
1504 * Quit:: Terminate your session.
1507 @node Detach, Power Detach, , Session Management
1510 @deffn Command autodetach state
1512 Sets whether @code{screen} will automatically detach upon hangup, which
1513 saves all your running programs until they are resumed with a
1514 @code{screen -r} command. When turned off, a hangup signal will
1515 terminate @code{screen} and all the processes it contains. Autodetach is
1521 @deffn Command detach
1522 (@kbd{C-a d}, @kbd{C-a C-d})@*
1523 Detach the @code{screen} session (disconnect it from the terminal and
1524 put it into the background). A detached @code{screen} can be resumed by
1525 invoking @code{screen} with the @code{-r} option (@pxref{Invoking
1527 The @code{-h} option tells screen to immediately close the connection
1528 to the terminal (@samp{hangup}).
1531 @deffn Command password [crypted_pw]
1533 Present a crypted password in your @file{.screenrc} file and screen will
1534 ask for it, whenever someone attempts to resume a detached session. This
1535 is useful, if you have privileged programs running under @code{screen}
1536 and you want to protect your session from reattach attempts by users
1537 that managed to assume your uid. (I.e. any superuser.) If no crypted
1538 password is specified, screen prompts twice a password and places its
1539 encryption in the paste buffer. Default is `none', which disables
1543 @node Power Detach, Lock, Detach, Session Management
1544 @section Power Detach
1547 @deffn Command pow_detach
1549 Mainly the same as @code{detach}, but also sends a HANGUP signal
1550 to the parent process of @code{screen}.@*
1551 @emph{Caution}: This will result in a
1552 logout if @code{screen} was started from your login shell.
1555 @deffn Command pow_detach_msg [message]
1557 The @var{message} specified here is output whenever a power detach is
1558 performed. It may be used as a replacement for a logout message or to reset
1560 Without parameter, the current message is shown.
1563 @node Lock, Multiuser Session, Power Detach, Session Management
1567 @deffn Command lockscreen
1568 (@kbd{C-a x}, @kbd{C-a C-x})@*
1569 Call a screenlock program (@file{/local/bin/lck} or @file{/usr/bin/lock}
1570 or a builtin, if no other is available). Screen does not accept any
1571 command keys until this program terminates. Meanwhile processes in the
1572 windows may continue, as the windows are in the detached state.
1573 The screenlock program may be changed through the environment variable
1574 @code{$LOCKPRG} (which must be set in the shell from which @code{screen}
1575 is started) and is executed with the user's uid and gid.
1577 Warning: When you leave other shells unlocked and have no password set
1578 on @code{screen}, the lock is void: One could easily re-attach from an
1579 unlocked shell. This feature should rather be called
1580 @code{lockterminal}.
1583 @node Multiuser Session, Session Name, Lock, Session Management
1584 @section Multiuser Session
1585 @cindex multiuser session
1587 These commands allow other users to gain access to one single @code{screen}
1588 session. When attaching to a multiuser @code{screen} the sessionname is
1589 specified as @code{username/sessionname} to the @code{-S} command line option.
1590 @code{Screen} must be compiled with multiuser support to enable features
1594 * Multiuser:: Enable / Disable multiuser mode.
1595 * Acladd:: Enable a specific user.
1596 * Aclchg:: Change a users permissions.
1597 * Acldel:: Disable a specific user.
1598 * Aclgrp:: Grant a user permissions to other users.
1599 * Displays:: List all active users at their displays.
1600 * Umask:: Predefine access to new windows.
1601 * Wall:: Write a message to all users.
1602 * Writelock:: Grant exclusive window access.
1603 * Su:: Substitute user.
1606 @node Multiuser, Acladd, , Multiuser Session
1607 @subsection Multiuser
1608 @deffn Command multiuser @var{state}
1610 Switch between single-user and multi-user mode. Standard screen operation is
1611 single-user. In multi-user mode the commands @code{acladd}, @code{aclchg} and
1612 @code{acldel} can be used to enable (and disable) other users accessing this
1616 @node Acladd, Aclchg, Multiuser, Multiuser Session
1618 @deffn Command acladd @var{usernames}
1619 @deffnx Command addacl @var{usernames}
1621 Enable users to fully access this screen session. @var{Usernames} can be one
1622 user or a comma separated list of users. This command enables to attach to
1623 the @code{screen} session and performs the equivalent of
1624 @code{aclchg @var{usernames} +rwx "#?"}. To add a user with restricted access,
1625 use the @code{aclchg} command below.
1626 @code{Addacl} is a synonym to @code{acladd}.
1627 Multi-user mode only.
1630 @node Aclchg, Acldel, Acladd, Multiuser Session
1632 @deffn Command aclchg @var{usernames permbits list}
1633 @deffnx Command chacl @var{usernames permbits list}
1635 Change permissions for a comma separated list of users.
1636 Permission bits are represented as @samp{r}, @samp{w} and @samp{x}.
1637 Prefixing @samp{+} grants the permission, @samp{-} removes it. The third
1638 parameter is a comma separated list of commands or windows (specified either
1639 by number or title). The special list @samp{#} refers to all windows, @samp{?}
1640 to all commands. If @var{usernames} consists of a single @samp{*}, all
1641 known users are affected.
1642 A command can be executed when the user has the @samp{x} bit for it. The user
1643 can type input to a window when he has its @samp{w} bit set and no other
1644 user obtains a writelock for this window. Other bits are currently ignored.
1645 To withdraw the writelock from another user in e.g. window 2:
1646 @samp{aclchg @var{username} -w+w 2}. To allow read-only access
1647 to the session: @samp{aclchg @var{username} -w "#"}. As soon as a user's name
1648 is known to screen, he can attach to the session and (per default) has full
1649 permissions for all command and windows. Execution permission for the acl
1650 commands, @code{at} and others should also be removed or the user may be able
1651 to regain write permission.
1652 @code{Chacl} is a synonym to @code{aclchg}.
1653 Multi-user mode only.
1656 @node Acldel, Aclgrp, Aclchg, Multiuser Session
1658 @deffn Command acldel @var{username}
1660 Remove a user from screen's access control list. If currently attached, all the
1661 user's displays are detached from the session. He cannot attach again.
1662 Multi-user mode only.
1665 @node Aclgrp, Displays, Acldel, Multiuser Session
1667 @deffn Command aclgrp @var{username} [@var{groupname}]
1669 Creates groups of users that share common access rights. The
1670 name of the group is the username of the group leader. Each
1671 member of the group inherits the permissions that are
1672 granted to the group leader. That means, if a user fails an
1673 access check, another check is made for the group leader.
1674 A user is removed from all groups the special value @samp{none}
1675 is used for @var{groupname}. If the second parameter is omitted
1676 all groups the user is in are listed.
1679 @node Displays, Umask, Aclgrp, Multiuser Session
1680 @subsection Displays
1682 @deffn Command displays
1684 Shows a tabular listing of all currently connected user
1685 front-ends (displays). This is most useful for multiuser
1689 @node Umask, Wall, Displays, Multiuser Session
1690 @subsection aclumask
1691 @deffn Command aclumask [@var{users}]+/-@var{bits} ...
1692 @deffnx Command umask [@var{users}]+/-@var{bits} ...
1694 This specifies the access other users have to windows that
1695 will be created by the caller of the command. @var{Users} may be no,
1696 one or a comma separated list of known usernames. If no users are
1697 specified, a list of all currently known users is assumed.
1698 @var{Bits} is any combination of access control bits allowed
1699 defined with the @code{aclchg} command. The special username @samp{?}
1700 predefines the access that not yet known users will be
1701 granted to any window initially. The special username @samp{??}
1702 predefines the access that not yet known users are granted
1703 to any command. Rights of the special username nobody cannot
1704 be changed (see the @code{su} command).
1705 @code{Umask} is a synonym to @code{aclumask}.
1709 @node Wall, Writelock, Umask, Multiuser Session
1711 @deffn Command wall @var{message}
1713 Write a message to all displays. The message will appear in the terminal's
1717 @node Writelock, Su , Wall, Multiuser Session
1718 @subsection Writelock
1719 @deffn Command writelock @var{on|off|auto}
1721 In addition to access control lists, not all users may be able to write to
1722 the same window at once. Per default, writelock is in @samp{auto} mode and
1723 grants exclusive input permission to the user who is the first to switch
1724 to the particular window. When he leaves the window, other users may obtain
1725 the writelock (automatically). The writelock of the current window is disabled
1726 by the command @code{writelock off}. If the user issues the command
1727 @code{writelock on} he keeps the exclusive write permission while switching
1731 @deffn Command defwritelock @var{on|off|auto}
1733 Sets the default writelock behavior for new windows. Initially all windows
1734 will be created with no writelocks.
1737 @node Su, , Writelock, Multiuser Session
1739 @deffn Command su [@var{username} [@var{password} [@var{password2}]]]
1741 Substitute the user of a display. The command prompts for
1742 all parameters that are omitted. If passwords are specified
1743 as parameters, they have to be specified un-crypted. The
1744 first password is matched against the systems passwd database,
1745 the second password is matched against the @code{screen}
1746 password as set with the commands @code{acladd} or @code{password}.
1747 @code{Su} may be useful for the @code{screen} administrator to test
1749 When the identification fails, the user has
1750 access to the commands available for user @samp{nobody}. These are
1751 @code{detach}, @code{license}, @code{version}, @code{help} and
1755 @node Session Name, Suspend, Multiuser Session, Session Management
1756 @section Session Name
1757 @deffn Command sessionname [@var{name}]
1759 Rename the current session. Note that for @code{screen -list} the name
1760 shows up with the process-id prepended. If the argument @var{name} is
1761 omitted, the name of this session is displayed.@*
1762 @emph{Caution}: The @code{$STY}
1763 environment variable will still reflect the old name in pre-existing
1764 shells. This may result in
1765 confusion. The default is constructed from the tty and host names.
1768 @node Suspend, Quit, Session Name, Session Management
1772 @deffn Command suspend
1773 (@kbd{C-a z}, @kbd{C-a C-z})@*
1774 Suspend @code{screen}. The windows are in the detached state while
1775 @code{screen} is suspended. This feature relies on the parent shell
1776 being able to do job control.
1779 @node Quit, , Suspend, Session Management
1784 Kill all windows and terminate @code{screen}. Note that on VT100-style
1785 terminals the keys @kbd{C-4} and @kbd{C-\} are identical. So be careful
1786 not to type @kbd{C-a C-4} when selecting window no. 4. Use the empty
1787 bind command (as in @code{bind "^\"}) to remove a key binding
1788 (@pxref{Key Binding}).
1791 @node Regions, Window Settings, Session Management, Top
1794 Screen has the ability to display more than one window on the
1795 user's display. This is done by splitting the screen in regions,
1796 which can contain different windows.
1799 * Split:: Split a region into two
1800 * Focus:: Change to the next region
1801 * Only:: Delete all other regions
1802 * Remove:: Delete the current region
1803 * Resize:: Grow or shrink a region
1804 * Caption:: Control the window's caption
1805 * Fit:: Resize a window to fit the region
1808 @node Split, Focus, , Regions
1811 @deffn Command split
1813 Split the current region into two new ones. All regions on the
1814 display are resized to make room for the new region. The blank
1815 window is displayed on the new region.
1818 @node Focus, Only, Split, Regions
1821 @deffn Command focus
1822 (@kbd{C-a @key{Tab}})@*
1823 Move the input focus to the next region. This is done in a cyclic
1824 way so that the top region is selected after the bottom one. If
1825 no subcommand is given it defaults to `down'. `up' cycles in the
1826 opposite order, `top' and `bottom' go to the top and bottom
1827 region respectively. Useful bindings are (j and k as in vi)
1836 @node Only, Remove, Focus, Regions
1841 Kill all regions but the current one.
1844 @node Remove, Resize, Only, Regions
1847 @deffn Command remove
1849 Kill the current region. This is a no-op if there is only one region.
1852 @node Resize, Caption, Remove, Regions
1854 @deffn Command resize [(+/-)@var{lines}]
1856 Resize the current region. The space will be removed from or added to
1857 the region below or if there's not enough space from the region above.
1859 resize +N increase current region height by N
1860 resize -N decrease current region height by N
1861 resize N set current region height to N
1862 resize = make all windows equally high
1863 resize max maximize current region height
1864 resize min minimize current region height
1868 @node Caption, Fit, Resize, Regions
1870 @deffn Command caption @code{always}|@code{splitonly} [string]
1871 @deffnx Command caption @code{string} [string]
1873 This command controls the display of the window captions. Normally
1874 a caption is only used if more than one window is shown on the
1875 display (split screen mode). But if the type is set to
1876 @code{always}, @code{screen} shows a caption
1877 even if only one window is displayed. The default
1878 is @samp{splitonly}.
1880 The second form changes the text used for the caption. You can use
1881 all string escapes (@pxref{String Escapes}). @code{Screen} uses
1882 a default of @samp{%3n %t}.
1884 You can mix both forms by providing the string as an additional
1888 @node Fit, , Caption, Regions
1893 Change the window size to the size of the current region. This
1894 command is needed because screen doesn't adapt the window size
1895 automatically if the window is displayed more than once.
1898 @node Window Settings, Virtual Terminal, Regions, Top
1899 @chapter Window Settings
1901 These commands control the way @code{screen} treats individual windows
1902 in a session. @xref{Virtual Terminal}, for commands to control the
1903 terminal emulation itself.
1906 * Naming Windows:: Control the name of the window
1907 * Console:: See the host's console messages
1908 * Kill:: Destroy an unwanted window
1909 * Login:: Control @file{/etc/utmp} logging
1910 * Mode:: Control the file mode of the pty
1911 * Monitor:: Watch for activity in a window
1912 * Windows:: List the active windows
1913 * Hardstatus:: Set a window's hardstatus line
1916 @node Naming Windows, Console, , Window Settings
1917 @section Naming Windows (Titles)
1920 You can customize each window's name in the window display (viewed with
1921 the @code{windows} command (@pxref{Windows}) by setting it with
1922 one of the title commands. Normally the name displayed is the actual
1923 command name of the program created in the window. However, it is
1924 sometimes useful to distinguish various programs of the same name or to
1925 change the name on-the-fly to reflect the current state of the window.
1927 The default name for all shell windows can be set with the
1928 @code{shelltitle} command (@pxref{Shell}). You can specify the name you
1929 want for a window with the @samp{-t} option to the @code{screen} command
1930 when the window is created (@pxref{Screen Command}). To change the name after
1931 the window has been created you can use the title-string escape-sequence
1932 (@kbd{@key{ESC} k @var{name} @key{ESC} \}) and the @code{title} command
1933 (C-a A). The former can be output from an application to control the
1934 window's name under software control, and the latter will prompt for a
1935 name when typed. You can also bind predefined names to keys with the
1936 @code{title} command to set things quickly without prompting.
1939 * Title Command:: The @code{title} command.
1940 * Dynamic Titles:: Make shell windows change titles dynamically.
1941 * Title Prompts:: Set up your shell prompt for dynamic Titles.
1942 * Title Screenrc:: Set up Titles in your @file{.screenrc}.
1945 @node Title Command, Dynamic Titles, , Naming Windows
1946 @subsection Title Command
1948 @deffn Command title [windowtitle]
1950 Set the name of the current window to @var{windowtitle}. If no name is
1951 specified, screen prompts for one.
1954 @node Dynamic Titles, Title Prompts, Title Command, Naming Windows
1955 @subsection Dynamic Titles
1956 @code{screen} has a shell-specific heuristic that is enabled by
1957 setting the window's name to @var{search|name} and arranging to have a
1958 null title escape-sequence output as a part of your prompt. The
1959 @var{search} portion specifies an end-of-prompt search string, while the
1960 @var{name} portion specifies the default shell name for the window. If
1961 the @var{name} ends in a @samp{:} @code{screen} will add what it
1962 believes to be the current command running in the window to the end of
1963 the specified name (e.g. @var{name:cmd}). Otherwise the current
1964 command name supersedes the shell name while it is running.
1966 Here's how it works: you must modify your shell prompt to output a null
1967 title-escape-sequence (@key{ESC} k @key{ESC} \) as a part of your prompt.
1968 The last part of your prompt must be the same as the string you
1969 specified for the @var{search} portion of the title. Once this is set
1970 up, @code{screen} will use the title-escape-sequence to clear the previous
1971 command name and get ready for the next command. Then, when a newline
1972 is received from the shell, a search is made for the end of the prompt.
1973 If found, it will grab the first word after the matched string and use
1974 it as the command name. If the command name begins with @samp{!},
1975 @samp{%}, or @samp{^}, @code{screen} will use the first word on the
1976 following line (if found) in preference to the just-found name. This
1977 helps csh users get more accurate titles when using job control or
1978 history recall commands.
1980 @node Title Prompts, Title Screenrc, Dynamic Titles, Naming Windows
1981 @subsection Setting up your prompt for shell titles
1982 One thing to keep in mind when adding a null title-escape-sequence to your
1983 prompt is that some shells (like the csh) count all the non-control
1984 characters as part of the prompt's length. If these invisible
1985 characters aren't a multiple of 8 then backspacing over a tab will
1986 result in an incorrect display. One way to get around this is to use a
1990 set prompt='@value{esc}[0000m@value{esc}k@value{esc}\% '
1993 The escape-sequence @samp{@value{esc}[0000m} not only normalizes the
1994 character attributes, but all the zeros round the length of the
1995 invisible characters up to 8.
1997 Tcsh handles escape codes in the prompt more intelligently, so you can
1998 specify your prompt like this:
2001 set prompt="%@{\ek\e\\%@}\% "
2004 Bash users will probably want to echo the escape sequence in the
2008 PROMPT_COMMAND='printf "\033k\033\134"'
2011 (I used @samp{\134} to output a @samp{\} because of a bug in v1.04).
2013 @node Title Screenrc, , Title Prompts, Naming Windows
2014 @subsection Setting up shell titles in your @file{.screenrc}
2015 Here are some .screenrc examples:
2018 screen -t top 2 nice top
2021 Adding this line to your .screenrc would start a niced version of the
2022 @code{top} command in window 2 named @samp{top} rather than @samp{nice}.
2029 This file would start a shell using the given shelltitle. The title
2030 specified is an auto-title that would expect the prompt and the typed
2031 command to look something like the following:
2034 /usr/joe/src/dir> trn
2037 (it looks after the '> ' for the command name).
2038 The window status would show the name @samp{trn} while the command was
2039 running, and revert to @samp{csh} upon completion.
2042 bind R screen -t '% |root:' su
2045 Having this command in your .screenrc would bind the key sequence
2046 @kbd{C-a R} to the @code{su} command and give it an auto-title name of
2047 @samp{root:}. For this auto-title to work, the screen could look
2048 something like this:
2055 Here the user typed the csh history command @code{!em} which ran the
2056 previously entered @code{emacs} command. The window status would show
2057 @samp{root:emacs} during the execution of the command, and revert to
2058 simply @samp{root:} at its completion.
2063 bind u title (unknown)
2066 The first binding doesn't have any arguments, so it would prompt you for
2067 a title when you type @kbd{C-a o}. The second binding would clear an
2068 auto-titles current setting (C-a E). The third binding would set the
2069 current window's title to @samp{(unknown)} (C-a u).
2071 @node Console, Kill, Naming Windows, Window Settings
2073 @deffn Command console [@var{state}]
2075 Grabs or un-grabs the machines console output to a window. When the argument
2076 is omitted the current state is displayed.
2077 @emph{Note}: Only the owner of @file{/dev/console} can grab the console
2078 output. This command is only available if the host supports the ioctl
2082 @node Kill, Login, Console, Window Settings
2088 (@kbd{C-a k}, @kbd{C-a C-k})@*
2089 Kill the current window.@*
2090 If there is an @code{exec} command running (@pxref{Exec}) then it is killed.
2091 Otherwise the process (e.g. shell) running in the window receives a
2092 @code{HANGUP} condition,
2093 the window structure is removed and screen (your display) switches to another
2094 window. When the last window is destroyed, @code{screen} exits.
2095 After a kill screen switches to the previously displayed window.
2097 @emph{Caution}: @code{emacs} users may find themselves killing their
2098 @code{emacs} session when trying to delete the current line. For this
2099 reason, it is probably wise to use a different command character
2100 (@pxref{Command Character}) or rebind @code{kill} to another key
2101 sequence, such as @kbd{C-a K} (@pxref{Key Binding}).
2104 @node Login, Mode, Kill, Window Settings
2107 @deffn Command deflogin state
2109 Same as the @code{login} command except that the default setting for new
2110 windows is changed. This defaults to `on' unless otherwise specified at
2111 compile time (@pxref{Installation}). Both commands are only present when
2112 @code{screen} has been compiled with utmp support.
2116 @deffn Command login [state]
2118 Adds or removes the entry in @file{/etc/utmp} for the current window.
2119 This controls whether or not the window is @dfn{logged in}. In addition
2120 to this toggle, it is convenient to have ``log in'' and ``log out''
2121 keys. For instance, @code{bind I login on} and @code{bind O
2122 login off} will map these keys to be @kbd{C-a I} and @kbd{C-a O}
2123 (@pxref{Key Binding}).
2126 @node Mode, Monitor, Login, Window Settings
2128 @deffn Command defmode mode
2130 The mode of each newly allocated pseudo-tty is set to @var{mode}.
2131 @var{mode} is an octal number as used by chmod(1). Defaults to 0622 for
2132 windows which are logged in, 0600 for others (e.g. when @code{-ln} was
2133 specified for creation, @pxref{Screen Command}).
2136 @node Monitor, Windows, Mode, Window Settings
2139 @deffn Command activity message
2141 When any activity occurs in a background window that is being monitored,
2142 @code{screen} displays a notification in the message line. The
2143 notification message can be redefined by means of the @code{activity}
2144 command. Each occurrence of @samp{%} in @var{message} is replaced by
2145 the number of the window in which activity has occurred, and each
2146 occurrence of @samp{^G} is replaced by the definition for bell in your
2147 termcap (usually an audible bell). The default message is
2150 'Activity in window %n'
2153 Note that monitoring is off for all windows by default, but can be altered
2154 by use of the @code{monitor} command (@kbd{C-a M}).
2157 @deffn Command defmonitor state
2159 Same as the @code{monitor} command except that the default setting for
2160 new windows is changed. Initial setting is `off'.
2164 @deffn Command monitor [state]
2166 Toggles monitoring of the current window. When monitoring is turned on
2167 and the affected window is switched into the background, the activity
2168 notification message will be displayed in the status line at the first
2169 sign of output, and the window will also be marked with an @samp{@@} in
2170 the window-status display (@pxref{Windows}). Monitoring defaults to
2171 @samp{off} for all windows.
2174 @node Windows, Hardstatus, Monitor, Window Settings
2178 @deffn Command windows
2179 (@kbd{C-a w}, @kbd{C-a C-w})@*
2180 Uses the message line to display a list of all the windows. Each
2181 window is listed by number with the name of the program running in the
2182 window (or its title).
2184 The current window is marked with a @samp{*};
2185 the previous window is marked with a @samp{-};
2186 all the windows that are logged in are marked with a @samp{$} (@pxref{Login});
2187 a background window that has received a bell is marked with a @samp{!};
2188 a background window that is being monitored and has had activity occur is
2189 marked with an @samp{@@} (@pxref{Monitor});
2190 a window which has output logging turned on is marked with @samp{(L)};
2191 windows occupied by other users are marked with @samp{&}
2192 or @samp{&&} if the window is shared by other users;
2193 windows in the zombie state are marked with @samp{Z}.
2195 If this list is too long to fit on the terminal's status line only the
2196 portion around the current window is displayed.
2199 @node Hardstatus, , Windows, Window Settings
2202 @code{Screen} maintains a hardstatus line for every window. If a window
2203 gets selected, the display's hardstatus will be updated to match
2204 the window's hardstatus line.
2205 The hardstatus line can be changed with the ANSI Application
2206 Program Command (APC): @samp{ESC_<string>ESC\}. As a convenience
2207 for xterm users the sequence @samp{ESC]0..2;<string>^G} is
2210 @deffn Command defhstatus [status]
2212 The hardstatus line that all new windows will get is set to
2214 This command is useful to make the hardstatus of every window
2215 display the window number or title or the like. @var{status}
2216 may contain the same directives as in the window messages, but
2217 the directive escape character is @samp{^E} (octal 005) instead
2218 of @samp{%}. This was done to make a misinterpretation of program
2219 generated hardstatus lines impossible.
2220 If the parameter @var{status}
2221 is omitted, the current default string is displayed.
2222 Per default the hardstatus line of new windows is empty.
2225 @deffn Command hstatus status
2227 Changes the current window's hardstatus line to @var{status}.
2230 @node Virtual Terminal, Copy and Paste, Window Settings, Top
2231 @chapter Virtual Terminal
2233 Each window in a @code{screen} session emulates a VT100 terminal, with
2234 some extra functions added. The VT100 emulator is hard-coded, no other
2235 terminal types can be emulated.
2236 The commands described here modify the terminal emulation.
2239 * Control Sequences:: Details of the internal VT100 emulation.
2240 * Input Translation:: How keystrokes are remapped.
2241 * Digraph:: Entering digraph sequences.
2242 * Bell:: Getting your attention.
2243 * Clear:: Clear the window display.
2244 * Info:: Terminal emulation statistics.
2245 * Redisplay:: When the display gets confusing.
2246 * Wrap:: Automatic margins.
2247 * Reset:: Recovering from ill-behaved applications.
2248 * Window Size:: Changing the size of your terminal.
2249 * Character Processing:: Change the effect of special characters.
2252 @node Control Sequences, Input Translation, , Virtual Terminal
2253 @section Control Sequences
2254 @cindex control sequences
2255 The following is a list of control sequences recognized by
2256 @code{screen}. @samp{(V)} and @samp{(A)} indicate VT100-specific and
2257 ANSI- or ISO-specific functions, respectively.
2263 ESC H Horizontal Tab Set
2264 ESC Z Send VT100 Identification String
2265 ESC 7 (V) Save Cursor and Attributes
2266 ESC 8 (V) Restore Cursor and Attributes
2267 ESC [s (A) Save Cursor and Attributes
2268 ESC [u (A) Restore Cursor and Attributes
2269 ESC c Reset to Initial State
2271 ESC Pn p Cursor Visibility (97801)
2274 ESC = (V) Application Keypad Mode
2275 ESC > (V) Numeric Keypad Mode
2276 ESC # 8 (V) Fill Screen with E's
2277 ESC \ (A) String Terminator
2278 ESC ^ (A) Privacy Message String (Message Line)
2279 ESC ! Global Message String (Message Line)
2280 ESC k Title Definition String
2281 ESC P (A) Device Control String
2282 Outputs a string directly to the host
2283 terminal without interpretation.
2284 ESC _ (A) Application Program Command (Hardstatus)
2285 ESC ] 0 ; string ^G (A) Operating System Command (Hardstatus, xterm
2287 ESC ] 83 ; cmd ^G (A) Execute screen command. This only works if
2288 multi-user support is compiled into screen.
2289 The pseudo-user ":window:" is used to check
2290 the access control list. Use "addacl :window:
2291 -rwx #?" to create a user with no rights and
2292 allow only the needed commands.
2293 Control-N (A) Lock Shift G1 (SO)
2294 Control-O (A) Lock Shift G0 (SI)
2295 ESC n (A) Lock Shift G2
2296 ESC o (A) Lock Shift G3
2297 ESC N (A) Single Shift G2
2298 ESC O (A) Single Shift G3
2299 ESC ( Pcs (A) Designate character set as G0
2300 ESC ) Pcs (A) Designate character set as G1
2301 ESC * Pcs (A) Designate character set as G2
2302 ESC + Pcs (A) Designate character set as G3
2303 ESC [ Pn ; Pn H Direct Cursor Addressing
2304 ESC [ Pn ; Pn f same as above
2305 ESC [ Pn J Erase in Display
2306 Pn = None or 0 From Cursor to End of Screen
2307 1 From Beginning of Screen to Cursor
2309 ESC [ Pn K Erase in Line
2310 Pn = None or 0 From Cursor to End of Line
2311 1 From Beginning of Line to Cursor
2313 ESC [ Pn X Erase character
2314 ESC [ Pn A Cursor Up
2315 ESC [ Pn B Cursor Down
2316 ESC [ Pn C Cursor Right
2317 ESC [ Pn D Cursor Left
2318 ESC [ Pn E Cursor next line
2319 ESC [ Pn F Cursor previous line
2320 ESC [ Pn G Cursor horizontal position
2321 ESC [ Pn ` same as above
2322 ESC [ Pn d Cursor vertical position
2323 ESC [ Ps ;...; Ps m Select Graphic Rendition
2324 Ps = None or 0 Default Rendition
2327 3 (A) @i{Standout} Mode (ANSI: Italicized)
2331 22 (A) Normal Intensity
2332 23 (A) @i{Standout} Mode off (ANSI: Italicized off)
2333 24 (A) Not Underlined
2335 27 (A) Positive Image
2336 30 (A) Foreground Black
2337 31 (A) Foreground Red
2338 32 (A) Foreground Green
2339 33 (A) Foreground Yellow
2340 34 (A) Foreground Blue
2341 35 (A) Foreground Magenta
2342 36 (A) Foreground Cyan
2343 37 (A) Foreground White
2344 39 (A) Foreground Default
2345 40 (A) Background Black
2347 49 (A) Background Default
2348 ESC [ Pn g Tab Clear
2349 Pn = None or 0 Clear Tab at Current Position
2351 ESC [ Pn ; Pn r (V) Set Scrolling Region
2352 ESC [ Pn I (A) Horizontal Tab
2353 ESC [ Pn Z (A) Backward Tab
2354 ESC [ Pn L (A) Insert Line
2355 ESC [ Pn M (A) Delete Line
2356 ESC [ Pn @@ (A) Insert Character
2357 ESC [ Pn P (A) Delete Character
2358 ESC [ Pn S Scroll Scrolling Region Up
2359 ESC [ Pn T Scroll Scrolling Region Down
2360 ESC [ Pn ^ same as above
2361 ESC [ Ps ;...; Ps h Set Mode
2362 ESC [ Ps ;...; Ps l Reset Mode
2363 Ps = 4 (A) Insert Mode
2364 20 (A) @samp{Automatic Linefeed} Mode.
2365 34 Normal Cursor Visibility
2366 ?1 (V) Application Cursor Keys
2367 ?3 (V) Change Terminal Width to 132 columns
2368 ?5 (V) Reverse Video
2369 ?6 (V) @samp{Origin} Mode
2370 ?7 (V) @samp{Wrap} Mode
2371 ?9 X10 mouse tracking
2372 ?25 (V) Visible Cursor
2373 ?47 Alternate Screen (old xterm code)
2374 ?1000 (V) VT200 mouse tracking
2375 ?1047 Alternate Screen (new xterm code)
2376 ?1049 Alternate Screen (new xterm code)
2377 ESC [ 5 i (A) Start relay to printer (ANSI Media Copy)
2378 ESC [ 4 i (A) Stop relay to printer (ANSI Media Copy)
2379 ESC [ 8 ; Ph ; Pw t Resize the window to @samp{Ph} lines and
2380 @samp{Pw} columns (SunView special)
2381 ESC [ c Send VT100 Identification String
2382 ESC [ x (V) Send Terminal Parameter Report
2383 ESC [ > c Send Secondary Device Attributes String
2384 ESC [ 6 n Send Cursor Position Report
2389 @node Input Translation, Digraph, Control Sequences, Virtual Terminal
2390 @section Input Translation
2391 @cindex input translation
2392 In order to do a full VT100 emulation @code{screen} has to detect
2393 that a sequence of characters in the input stream was generated
2394 by a keypress on the user's keyboard and insert the VT100
2395 style escape sequence. @code{Screen} has a very flexible way of doing
2396 this by making it possible to map arbitrary commands on arbitrary
2397 sequences of characters. For standard VT100 emulation the command
2398 will always insert a string in the input buffer of the window
2399 (see also command @code{stuff}, @pxref{Paste}).
2400 Because the sequences generated by a keypress can
2401 change after a reattach from a different terminal type, it is
2402 possible to bind commands to the termcap name of the keys.
2403 @code{Screen} will insert the correct binding after each
2404 reattach. See @ref{Bindkey} for further details on the syntax and examples.
2406 Here is the table of the default key bindings. (A) means that the
2407 command is executed if the keyboard is switched into application
2411 Key name Termcap name Command
2412 -----------------------------------------------------
2413 Cursor up ku stuff \033[A
2415 Cursor down kd stuff \033[B
2417 Cursor right kr stuff \033[C
2419 Cursor left kl stuff \033[D
2421 Function key 0 k0 stuff \033[10~
2422 Function key 1 k1 stuff \033OP
2423 Function key 2 k2 stuff \033OQ
2424 Function key 3 k3 stuff \033OR
2425 Function key 4 k4 stuff \033OS
2426 Function key 5 k5 stuff \033[15~
2427 Function key 6 k6 stuff \033[17~
2428 Function key 7 k7 stuff \033[18~
2429 Function key 8 k8 stuff \033[19~
2430 Function key 9 k9 stuff \033[20~
2431 Function key 10 k; stuff \033[21~
2432 Function key 11 F1 stuff \033[23~
2433 Function key 12 F2 stuff \033[24~
2434 Home kh stuff \033[1~
2435 End kH stuff \033[4~
2436 Insert kI stuff \033[2~
2437 Delete kD stuff \033[3~
2438 Page up kP stuff \033[5~
2439 Page down kN stuff \033[6~
2474 Keypad enter fe stuff \015
2478 @node Digraph, Bell, Input Translation, Virtual Terminal
2482 @deffn Command digraph [preset]
2484 This command prompts the user for a digraph sequence. The next
2485 two characters typed are looked up in a builtin table and the
2486 resulting character is inserted in the input stream. For example,
2487 if the user enters @samp{a"}, an a-umlaut will be inserted. If the
2488 first character entered is a 0 (zero), @code{screen}
2489 will treat the following characters (up to three) as an octal
2490 number instead. The optional argument @var{preset}
2491 is treated as user input, thus one can create an "umlaut" key.
2492 For example the command @samp{bindkey ^K digraph '"'} enables the user
2493 to generate an a-umlaut by typing @samp{CTRL-K a}.
2496 @node Bell, Clear, Digraph, Virtual Terminal
2499 @deffn Command bell_msg [message]
2501 When a bell character is sent to a background window, @code{screen}
2502 displays a notification in the message line. The notification message
2503 can be re-defined by this command. Each occurrence
2504 of @samp{%} in @var{message} is replaced by the number of the window to
2505 which a bell has been sent, and each occurrence of @samp{^G} is replaced
2506 by the definition for bell in your termcap (usually an audible bell).
2507 The default message is
2513 An empty message can be supplied to the @code{bell_msg} command to suppress
2514 output of a message line (@code{bell_msg ""}).
2515 Without parameter, the current message is shown.
2519 @deffn Command vbell [state]
2521 Sets or toggles the visual bell setting for the current window. If
2522 @code{vbell} is switched to @samp{on}, but your
2523 terminal does not support a visual bell, the visual bell message is
2524 displayed in the status line when the bell character is received.
2525 Visual bell support of a terminal is
2526 defined by the termcap variable @code{vb}. @xref{Bell, , Visual Bell,
2527 termcap, The Termcap Manual}, for more information on visual bells.
2528 The equivalent terminfo capability is @code{flash}.
2530 Per default, @code{vbell} is @samp{off}, thus the audible bell is used.
2533 @deffn Command vbell_msg [message]
2535 Sets the visual bell message. @var{Message} is printed to the status
2536 line if the window receives a bell character (^G), @code{vbell} is
2537 set to @samp{on} and the terminal does not support a visual bell.
2538 The default message is @samp{Wuff, Wuff!!}.
2539 Without parameter, the current message is shown.
2542 @deffn Command vbellwait sec
2544 Define a delay in seconds after each display of @code{screen} 's visual
2545 bell message. The default is 1 second.
2548 @node Clear, Info, Bell, Virtual Terminal
2551 @deffn Command clear
2553 Clears the screen and saves its contents to the scrollback buffer.
2556 @node Info, Redisplay, Clear, Virtual Terminal
2561 (@kbd{C-a i}, @kbd{C-a C-i})@*
2562 Uses the message line to display some information about the current
2563 window: the cursor position in the form @samp{(@var{column},@var{row})}
2564 starting with @samp{(1,1)}, the terminal width and height plus the size
2565 of the scrollback buffer in lines, like in @samp{(80,24)+50},
2566 the current state of window XON/XOFF flow control is shown like this
2567 (@pxref{Flow Control}):
2569 +flow automatic flow control, currently on.
2570 -flow automatic flow control, currently off.
2571 +(+)flow flow control enabled. Agrees with automatic control.
2572 -(+)flow flow control disabled. Disagrees with automatic control.
2573 +(-)flow flow control enabled. Disagrees with automatic control.
2574 -(-)flow flow control disabled. Agrees with automatic control.
2577 The current line wrap setting (@samp{+wrap} indicates enabled, @samp{-wrap}
2578 not) is also shown. The flags @samp{ins}, @samp{org}, @samp{app}, @samp{log},
2579 @samp{mon} and @samp{nored} are displayed when the window is in insert mode,
2580 origin mode, application-keypad mode, has output logging,
2581 activity monitoring or partial redraw enabled.
2583 The currently active
2584 character set (@samp{G0}, @samp{G1}, @samp{G2}, or @samp{G3}), and in
2585 square brackets the terminal character sets that are currently
2586 designated as @samp{G0} through @samp{G3}.
2587 If the window is in UTF-8 mode, the string @samp{UTF-8} is shown instead.
2588 Additional modes depending on the type of the window are displayed at
2589 the end of the status line (@pxref{Window Types}).
2591 If the state machine of the terminal emulator is in a non-default state,
2592 the info line is started with a string identifying the current state.
2594 For system information use @code{time}.
2597 @deffn Command dinfo
2599 Show what screen thinks about your terminal. Useful if you want to know
2600 why features like color or the alternate charset don't work.
2603 @node Redisplay, Wrap, Info, Virtual Terminal
2606 @deffn Command allpartial state
2608 If set to on, only the current cursor line is refreshed on window change.
2609 This affects all windows and is useful for slow terminal lines. The
2610 previous setting of full/partial refresh for each window is restored
2611 with @code{allpartial off}. This is a global flag that immediately takes effect
2612 on all windows overriding the @code{partial} settings. It does not change the
2613 default redraw behavior of newly created windows.
2616 @deffn Command altscreen state
2618 If set to on, "alternate screen" support is enabled in virtual terminals,
2619 just like in xterm. Initial setting is @samp{off}.
2622 @deffn Command partial state
2624 Defines whether the display should be refreshed (as with
2625 @code{redisplay}) after switching to the current window. This command
2626 only affects the current window. To immediately affect all windows use the
2627 @code{allpartial} command. Default is @samp{off}, of course. This default is
2628 fixed, as there is currently no @code{defpartial} command.
2633 @deffn Command redisplay
2634 (@kbd{C-a l}, @kbd{C-a C-l})@*
2635 Redisplay the current window. Needed to get a full redisplay in
2636 partial redraw mode.
2639 @node Wrap, Reset, Redisplay, Virtual Terminal
2644 @deffn Command wrap state
2645 (@kbd{C-a r}, @kbd{C-a C-r}) @*
2646 Sets the line-wrap setting for the current window. When line-wrap is
2647 on, the second consecutive printable character output at the last column
2648 of a line will wrap to the start of the following line. As an added
2649 feature, backspace (^H) will also wrap through the left margin to the
2650 previous line. Default is @samp{on}.
2653 @deffn Command defwrap state
2655 Same as the @code{wrap} command except that the default setting for new
2656 windows is changed. Initially line-wrap is on and can be toggled with the
2657 @code{wrap} command (@kbd{C-a r}) or by means of "C-a : wrap on|off".
2660 @node Reset, Window Size, Wrap, Virtual Terminal
2663 @deffn Command reset
2665 Reset the virtual terminal to its ``power-on'' values. Useful when strange
2666 settings (like scroll regions or graphics character set) are left over from
2670 @node Window Size, Character Processing, Reset, Virtual Terminal
2671 @section Window Size
2673 @deffn Command width [@code{-w}|@code{-d}] [cols [lines]]
2675 Toggle the window width between 80 and 132 columns, or set it to
2676 @var{cols} columns if an argument is specified. This requires a
2677 capable terminal and the termcap entries @samp{Z0} and @samp{Z1}. See
2678 the @code{termcap} command (@pxref{Termcap}), for more information.
2679 You can also specify a height if you want to
2680 change both values. The @code{-w} option tells screen to leave
2681 the display size unchanged and just set the window size,
2682 @code{-d} vice versa.
2685 @deffn Command height [@code{-w}|@code{-d}] [lines [cols]]
2687 Set the display height to a specified number of lines. When no
2688 argument is given it toggles between 24 and 42 lines display.
2691 @node Character Processing, ,Window Size, Virtual Terminal
2692 @section Character Processing
2694 @deffn Command c1 [state]
2696 Change c1 code processing. @samp{c1 on} tells screen to treat
2697 the input characters between 128 and 159 as control functions.
2698 Such an 8-bit code is normally the same as ESC followed by the
2699 corresponding 7-bit code. The default setting is to process c1
2700 codes and can be changed with the @samp{defc1} command.
2701 Users with fonts that have usable characters in the
2702 c1 positions may want to turn this off.
2705 @deffn Command gr [state]
2707 Turn GR charset switching on/off. Whenever screen sees an input
2708 char with an 8th bit set, it will use the charset stored in the
2709 GR slot and print the character with the 8th bit stripped. The
2710 default (see also @samp{defgr}) is not to process GR switching because
2711 otherwise the ISO88591 charset would not work.
2714 @deffn Command bce [state]
2716 Change background-color-erase setting. If @samp{bce} is set to
2717 on, all characters cleared by an erase/insert/scroll/clear
2718 operation will be displayed in the current background color.
2719 Otherwise the default background color is used.
2722 @deffn Command encoding enc [denc]
2724 Tell screen how to interpret the input/output. The first argument
2725 sets the encoding of the current window.
2726 Each window can emulate a different encoding. The optional second
2727 parameter overwrites the encoding of the connected terminal.
2728 It should never be needed as screen uses the locale setting to detect
2730 There is also a way to select a terminal encoding depending on
2731 the terminal type by using the @samp{KJ} termcap entry. @xref{Special Capabilities}.
2733 Supported encodings are
2734 @code{eucJP}, @code{SJIS}, @code{eucKR},
2735 @code{eucCN}, @code{Big5}, @code{GBK}, @code{KOI8-R}, @code{CP1251},
2736 @code{UTF-8}, @code{ISO8859-2}, @code{ISO8859-3},
2737 @code{ISO8859-4}, @code{ISO8859-5}, @code{ISO8859-6},
2738 @code{ISO8859-7}, @code{ISO8859-8}, @code{ISO8859-9},
2739 @code{ISO8859-10}, @code{ISO8859-15}, @code{jis}.
2741 See also @samp{defencoding}, which changes the default setting of a new
2745 @deffn Command charset set
2747 Change the current character set slot designation and charset
2748 mapping. The first four character of @var{set}
2749 are treated as charset designators while the fifth and sixth
2750 character must be in range @samp{0} to @samp{3} and set the GL/GR
2751 charset mapping. On every position a @samp{.} may be used to indicate
2752 that the corresponding charset/mapping should not be changed
2753 (@var{set} is padded to six characters internally by appending
2754 @samp{.} chars). New windows have @samp{BBBB02} as default
2755 charset, unless a @samp{encoding} command is active.
2757 The current setting can be viewed with the @ref{Info} command.
2760 @deffn Command utf8 [state [dstate]]
2762 Change the encoding used in the current window. If utf8 is enabled, the
2763 strings sent to the window will be UTF-8 encoded and vice versa.
2765 parameter toggles the setting. If a second parameter is given, the
2767 encoding is also changed (this should rather be done with screen's
2769 See also @samp{defutf8}, which changes the default setting of a new
2773 @deffn Command defc1 state
2775 Same as the @samp{c1} command except that the default setting for
2776 new windows is changed. Initial setting is @samp{on}.
2779 @deffn Command defgr state
2781 Same as the @samp{gr} command except that the default setting for
2782 new windows is changed. Initial setting is @samp{off}.
2785 @deffn Command defbce state
2787 Same as the @samp{bce} command except that the default setting for
2788 new windows is changed. Initial setting is @samp{off}.
2791 @deffn Command defencoding enc
2793 Same as the @samp{encoding} command except that the default setting for
2794 new windows is changed. Initial setting is the encoding taken from the
2798 @deffn Command defcharset [set]
2799 Like the @samp{charset} command except that the default setting for
2800 new windows is changed. Shows current default if called without
2804 @deffn Command defutf8 state
2806 Same as the @samp{utf8} command except that the default setting for new
2807 windows is changed. Initial setting is @code{on} if screen was started
2808 with @samp{-U}, otherwise @code{off}.
2811 @node Copy and Paste, Subprocess Execution, Virtual Terminal, Top
2812 @chapter Copy and Paste
2813 @cindex copy and paste
2815 For those confined to a hardware terminal, these commands provide a cut
2816 and paste facility more powerful than those provided by most windowing
2820 * Copy:: Copy from scrollback to buffer
2821 * Paste:: Paste from buffer into window
2822 * Registers:: Longer-term storage
2823 * Screen Exchange:: Sharing data between screen users
2824 * History:: Recalling previous input
2827 @node Copy, Paste, , Copy and Paste
2835 (@kbd{C-a [}, @kbd{C-a C-[}, @kbd{C-a @key{ESC}})@*
2836 Enter copy/scrollback mode. This allows you to copy text from the
2837 current window and its history into the paste buffer. In this mode a
2838 @code{vi}-like full screen editor is active, with controls as
2843 * Line Termination:: End copied lines with CR/LF
2844 * Scrollback:: Set the size of the scrollback buffer
2845 * Copy Mode Keys:: Remap keys in copy mode
2846 * Movement:: Move around in the scrollback buffer
2847 * Marking:: Select the text you want
2848 * Repeat count:: Repeat a command
2849 * Searching:: Find the text you want
2850 * Specials:: Other random keys
2853 @node Line Termination, Scrollback, , Copy
2855 @deffn Command crlf [state]
2857 This affects the copying of text regions with the @kbd{C-a [} command.
2858 If it is set to @samp{on}, lines will be separated by the two character
2859 sequence @samp{CR}/@samp{LF}. Otherwise only @samp{LF} is used.
2860 @code{crlf} is off by default.
2861 When no parameter is given, the state is toggled.
2864 @node Scrollback, Copy Mode Keys, Line Termination, Copy
2865 @subsection Scrollback
2866 @deffn Command defscrollback num
2868 Same as the @code{scrollback} command except that the default setting
2869 for new windows is changed. Defaults to 100.
2872 @deffn Command scrollback num
2874 Set the size of the scrollback buffer for the current window to
2875 @var{num} lines. The default scrollback is 100 lines. Use @kbd{C-a i}
2876 to view the current setting.
2879 @deffn Command compacthist [state]
2881 This tells screen whether to suppress trailing blank lines when
2882 scrolling up text into the history buffer. Turn compacting @samp{on}
2883 to hold more useful lines in your scrollback buffer.
2886 @node Copy Mode Keys, Movement, Scrollback, Copy
2887 @subsection markkeys
2888 @deffn Command markkeys string
2890 This is a method of changing the keymap used for copy/history mode. The
2891 string is made up of @var{oldchar}=@var{newchar} pairs which are
2892 separated by @samp{:}. Example: The command @code{markkeys
2893 h=^B:l=^F:$=^E} would set some keys to be more familiar to @code{emacs}
2895 If your terminal sends characters, that cause you to abort copy mode,
2896 then this command may help by binding these characters to do nothing.
2897 The no-op character is `@@' and is used like this: @code{markkeys @@=L=H}
2898 if you do not want to use the `H' or `L' commands any longer.
2899 As shown in this example, multiple keys can be assigned to one function
2900 in a single statement.
2903 @node Movement, Marking, Copy Mode Keys, Copy
2904 @subsection Movement Keys
2907 @kbd{h}, @kbd{j}, @kbd{k}, @kbd{l} move the cursor line by line or
2911 @kbd{0}, @kbd{^} and @kbd{$} move to the leftmost column or to the first
2912 or last non-whitespace character on the line.
2915 @kbd{H}, @kbd{M} and @kbd{L} move the cursor to the leftmost column
2916 of the top, center or bottom line of the window.
2919 @kbd{+} and @kbd{-} move the cursor to the leftmost column of the next
2923 @kbd{G} moves to the specified absolute line (default: end of buffer).
2926 @kbd{|} moves to the specified absolute column.
2929 @kbd{w}, @kbd{b}, @kbd{e} move the cursor word by word.
2932 @kbd{B}, @kbd{E} move the cursor WORD by WORD (as in vi).
2935 @kbd{C-u} and @kbd{C-d} scroll the display up/down by the specified
2936 amount of lines while preserving the cursor position. (Default: half
2940 @kbd{C-b} and @kbd{C-f} move the cursor up/down a full screen.
2943 @kbd{g} moves to the beginning of the buffer.
2946 @kbd{%} jumps to the specified percentage of the buffer.
2948 Note that Emacs-style movement keys can be specified by a .screenrc
2949 command. (@code{markkeys "h=^B:l=^F:$=^E"}) There is no simple method for
2950 a full emacs-style keymap, however, as this involves multi-character codes.
2952 @node Marking, Repeat count, Movement, Copy
2955 The copy range is specified by setting two marks. The text between these
2956 marks will be highlighted. Press @kbd{space} to set the first or second
2960 @kbd{Y} and @kbd{y} can be used to mark one whole line or to mark from
2964 @kbd{W} marks exactly one word.
2966 @node Repeat count, Searching, Marking, Copy
2967 @subsection Repeat Count
2969 Any command in copy mode can be prefixed with a number (by pressing
2970 digits @kbd{0@dots{}9}) which is taken as a repeat count. Example:
2971 @kbd{C-a C-[ H 10 j 5 Y} will copy lines 11 to 15 into the paste buffer.
2973 @node Searching, Specials, Repeat count, Copy
2974 @subsection Searching
2977 @kbd{/} @code{vi}-like search forward.
2980 @kbd{?} @code{vi}-like search backward.
2983 @kbd{C-a s} @code{emacs} style incremental search forward.
2986 @kbd{C-r} @code{emacs} style reverse i-search.
2988 @deffn Command ignorecase [state]
2990 Tell screen to ignore the case of characters in searches. Default is
2994 @node Specials, , Searching, Copy
2995 @subsection Specials
2997 There are, however, some keys that act differently here from in
2998 @code{vi}. @code{Vi} does not allow to yank rectangular blocks of text,
2999 but @code{screen} does. Press
3002 @kbd{c} or @kbd{C} to set the left or right margin respectively. If no
3003 repeat count is given, both default to the current cursor position.@*
3004 Example: Try this on a rather full text screen:
3005 @kbd{C-a [ M 20 l SPACE c 10 l 5 j C SPACE}.
3008 This moves one to the middle line of the screen, moves in 20 columns left,
3009 marks the beginning of the paste buffer, sets the left column, moves 5 columns
3010 down, sets the right column, and then marks the end of
3011 the paste buffer. Now try:@*
3012 @kbd{C-a [ M 20 l SPACE 10 l 5 j SPACE}
3015 and notice the difference in the amount of text copied.
3018 @kbd{J} joins lines. It toggles between 4 modes: lines separated by a
3019 newline character (012), lines glued seamless, lines separated by a single
3020 space or comma separated lines. Note that you can prepend the newline
3021 character with a carriage return character, by issuing a @code{set crlf
3025 @kbd{v} is for all the @code{vi} users who use @code{:set numbers} - it
3026 toggles the left margin between column 9 and 1.
3029 @kbd{a} before the final space key turns on append mode. Thus
3030 the contents of the paste buffer will not be overwritten, but appended to.
3033 @kbd{A} turns on append mode and sets a (second) mark.
3036 @kbd{>} sets the (second) mark and writes the contents of the paste buffer
3037 to the screen-exchange file (@file{/tmp/screen-exchange} per default)
3038 once copy-mode is finished. @xref{Screen Exchange}.@*
3039 This example demonstrates how to dump the
3040 whole scrollback buffer to that file: @*@kbd{C-a [ g SPACE G $ >}.
3043 @kbd{C-g} gives information about the current line and column.
3046 @kbd{x} exchanges the first mark and the current cursor position. You
3047 can use this to adjust an already placed mark.
3050 @kbd{@@} does nothing. Absolutely nothing. Does not even exit copy
3054 All keys not described here exit copy mode.
3056 @node Paste, Registers, Copy, Copy and Paste
3061 @deffn Command paste [registers [destination]]
3062 (@kbd{C-a ]}, @kbd{C-a C-]})@*
3063 Write the (concatenated) contents of the specified registers to the stdin
3064 stream of the current window. The register @samp{.} is treated as the
3065 paste buffer. If no parameter is specified the user is prompted to enter a
3066 single register. The paste buffer can be filled with the
3067 @code{copy}, @code{history} and @code{readbuf} commands.
3068 Other registers can be filled with the @code{register}, @code{readreg} and
3069 @code{paste} commands.
3070 If @code{paste} is called with a second argument, the contents of the specified
3071 registers is pasted into the named destination register rather than
3072 the window. If @samp{.} is used as the second argument, the display's paste
3073 buffer is the destination.
3074 Note, that @code{paste} uses a wide variety of resources: Usually both, a
3075 current window and a current display are required. But whenever a second
3076 argument is specified no current window is needed. When the source specification
3077 only contains registers (not the paste buffer) then there need not be a current
3078 display (terminal attached), as the registers are a global resource. The
3079 paste buffer exists once for every user.
3082 @deffn Command stuff string
3084 Stuff the string @var{string} in the input buffer of the current window.
3085 This is like the @code{paste} command, but with much less overhead.
3086 You cannot paste large buffers with the @code{stuff} command. It is most
3087 useful for key bindings. @xref{Bindkey}.
3090 @deffn Command pastefont [state]
3091 Tell screen to include font information in the paste buffer. The
3092 default is not to do so. This command is especially useful for
3093 multi character fonts like kanji.
3096 @deffn Command slowpaste msec
3097 @deffnx Command defslowpaste msec
3099 Define the speed text is inserted in the current window by the @code{paste}
3100 command. If the slowpaste value is nonzero text is written character by
3102 @code{screen} will pause for @var{msec} milliseconds after each write
3103 to allow the application to process the input. only use @code{slowpaste} if
3104 your underlying system exposes flow control problems while pasting large
3106 @code{defslowpaste} specifies the default for new windows.
3109 @deffn Command readreg [-e encoding] [register [filename]]
3111 Does one of two things, dependent on number of arguments: with zero or one
3112 arguments it it duplicates the paste buffer contents into the register specified
3113 or entered at the prompt. With two arguments it reads the contents of the named
3114 file into the register, just as @code{readbuf} reads the screen-exchange file
3115 into the paste buffer.
3116 You can tell screen the encoding of the file via the @code{-e} option.
3117 The following example will paste the system's password file into
3118 the screen window (using register p, where a copy remains):
3121 C-a : readreg p /etc/passwd
3126 @node Registers, Screen Exchange, Paste, Copy and Paste
3129 @deffn Command copy_reg [key]
3131 Removed. Use @code{readreg} instead.
3134 @deffn Command ins_reg [key]
3136 Removed. Use @code{paste} instead.
3139 @deffn Command process [key]
3141 Stuff the contents of the specified register into the @code{screen}
3142 input queue. If no argument is given you are prompted for a
3143 register name. The text is parsed as if it had been typed in from the user's
3144 keyboard. This command can be used to bind multiple actions to a single key.
3147 @deffn Command register [-e encoding] key string
3149 Save the specified @var{string} to the register @var{key}.
3150 The encoding of the string can be specified via the @code{-e} option.
3153 @node Screen Exchange, History, Registers, Copy and Paste
3154 @section Screen Exchange
3156 @deffn Command bufferfile [@var{exchange-file}]
3158 Change the filename used for reading and writing with the paste buffer.
3159 If the @var{exchange-file} parameter is omitted, @code{screen} reverts
3160 to the default of @file{/tmp/screen-exchange}. The following example
3161 will paste the system's password file into the screen window (using the
3162 paste buffer, where a copy remains):
3165 C-a : bufferfile /etc/passwd
3172 @deffn Command readbuf [-e @var{encoding}] [@var{filename}]
3174 Reads the contents of the specified file into the paste buffer.
3175 You can tell screen the encoding of the file via the @code{-e} option.
3176 If no file is specified, the screen-exchange filename is used.
3180 @deffn Command removebuf
3182 Unlinks the screen-exchange file.
3186 @deffn Command writebuf [-e @var{encoding}] [@var{filename}]
3188 Writes the contents of the paste buffer to the specified file, or the
3189 public accessible screen-exchange file if no filename is given.
3190 This is thought of as a primitive means of
3191 communication between @code{screen} users on the same host.
3192 If an encoding is specified the paste buffer is recoded on the fly to
3195 @kbd{C-a @key{ESC}} (@pxref{Copy}).
3198 @node History, , Screen Exchange, Copy and Paste
3202 @deffn Command history
3204 Usually users work with a shell that allows easy access to previous
3205 commands. For example, @code{csh} has the command @code{!!} to repeat
3206 the last command executed. @code{screen} provides a primitive way of
3207 recalling ``the command that started @dots{}'': You just type the first
3208 letter of that command, then hit @kbd{C-a @{} and @code{screen} tries to
3209 find a previous line that matches with the prompt character to the left
3210 of the cursor. This line is pasted into this window's input queue. Thus
3211 you have a crude command history (made up by the visible window and its
3215 @node Subprocess Execution, Key Binding, Copy and Paste, Top
3216 @chapter Subprocess Execution
3217 Control Input or Output of a window by another filter process.
3221 * Exec:: The @code{exec} command syntax.
3222 * Using Exec:: Weird things that filters can do.
3225 @node Exec, Using Exec, , Subprocess Execution
3227 @deffn Command exec [[@var{fdpat}] @var{newcommand} [@var{args} ... ]]
3229 Run a unix subprocess (specified by an executable path @var{newcommand} and
3230 its optional arguments) in the current window. The flow of data between
3231 newcommands stdin/stdout/stderr, the process originally started (let us call it
3232 "application-process") and
3233 screen itself (window) is controlled by the file descriptor pattern @var{fdpat}.
3234 This pattern is basically a three character sequence representing stdin, stdout
3235 and stderr of newcommand. A dot (@code{.}) connects the file descriptor
3236 to screen. An exclamation mark (@code{!}) causes the file descriptor to be
3237 connected to the application-process. A colon (@code{:}) combines both.
3239 User input will go to newcommand unless newcommand receives the
3240 application-process'
3241 output (@var{fdpat}s first character is @samp{!} or @samp{:}) or a pipe symbol
3242 (@samp{|}) is added to the end of @var{fdpat}.
3244 Invoking @code{exec} without arguments shows name and arguments of the currently
3245 running subprocess in this window. Only one subprocess can be running per
3248 When a subprocess is running the @code{kill} command will affect it instead of
3249 the windows process. Only one subprocess a time can be running in each window.
3251 Refer to the postscript file @file{doc/fdpat.ps} for a confusing
3252 illustration of all 21 possible combinations. Each drawing shows the digits
3253 2, 1, 0 representing the three file descriptors of newcommand. The box
3254 marked `W' is usual pty that has the application-process on its slave side.
3255 The box marked `P' is the secondary pty that now has screen at its master
3259 @node Using Exec, , Exec, Subprocess Execution
3266 Whitespace between the word @samp{exec} and @var{fdpat} and the command name
3270 Trailing dots and a @var{fdpat} consisting only of dots can be omitted.
3273 A simple @samp{|} is synonymous for the @samp{!..|} pattern.
3276 The word @samp{exec} can be omitted when the @samp{|} abbreviation is used.
3279 The word @samp{exec} can always be replaced by leading @samp{!}.
3288 @itemx exec ... /bin/sh
3289 All of the above are equivalent.
3290 Creates another shell in the same window, while the original shell is still
3291 running. Output of both shells is displayed and user input is sent to the new
3295 @itemx exec!stty 19200
3296 @itemx exec !.. stty 19200
3297 All of the above are equivalent.
3298 Set the speed of the window's tty. If your stty command operates on stdout,
3299 then add another @samp{!}. This is a useful command, when a screen window
3300 is directly connected to a serial line that needs to be configured.
3303 @itemx exec !..| less
3304 Both are equivalent.
3305 This adds a pager to the window output. The special character @samp{|} is
3306 needed to give the user control over the pager although it gets its input from
3307 the window's process. This works, because @samp{less} listens on stderr
3308 (a behavior that @code{screen} would not expect without the @samp{|})
3309 when its stdin is not a tty. @code{Less} versions newer than 177 fail miserably
3310 here; good old @code{pg} still works.
3312 @item !:sed -n s/.*Error.*/\007/p
3313 Sends window output to both, the user and the sed command. The sed inserts an
3314 additional bell character (oct. 007) to the window output seen by screen.
3315 This will cause 'Bell in window x' messages, whenever the string @samp{Error}
3316 appears in the window.
3319 @node Key Binding, Flow Control, Subprocess Execution, Top
3320 @chapter Key Binding
3324 You may disagree with some of the default bindings (I know I do). The
3325 @code{bind} command allows you to redefine them to suit your
3329 * Bind:: @code{bind} syntax.
3330 * Bind Examples:: Using @code{bind}.
3331 * Command Character:: The character used to start keyboard commands.
3332 * Help:: Show current key bindings.
3333 * Bindkey:: @code{bindkey} syntax.
3334 * Bindkey Examples:: Some easy examples.
3335 * Bindkey Control:: How to control the bindkey mechanism.
3338 @node Bind, Bind Examples, , Key Binding
3339 @section The @code{bind} command
3340 @deffn Command bind [-c class] key [command [args]]
3342 Bind a command to a key. The @var{key} argument is either a single
3343 character, a two-character sequence of the form @samp{^x} (meaning
3344 @kbd{C-x}), a backslash followed by an octal number (specifying the
3345 ASCII code of the character), or a backslash followed by a second
3346 character, such as @samp{\^} or @samp{\\}. The argument can also be
3347 quoted, if you like. If no further argument is given, any previously
3348 established binding for this key is removed. The @var{command}
3349 argument can be any command (@pxref{Command Index}).
3351 If a command class is specified via the @code{-c} option, the
3352 key is bound for the specified class. Use the @code{command}
3353 command to activate a class. Command classes can be used
3354 to create multiple command keys or multi-character bindings.
3356 By default, most suitable commands are bound to one or more keys
3357 (@pxref{Default Key Bindings}; for instance, the command to create a
3358 new window is bound to @kbd{C-c} and @kbd{c}. The @code{bind} command
3359 can be used to redefine the key bindings and to define new bindings.
3362 @node Bind Examples, Command Character, Bind, Key Binding
3363 @section Examples of the @code{bind} command
3369 bind ^f screen telnet foobar
3370 bind \033 screen -ln -t root -h 1000 9 su
3374 would bind the space key to the command that displays a list of windows
3375 (so that the command usually invoked by @kbd{C-a C-w} would also be
3376 available as @kbd{C-a space}), bind @kbd{C-f} to the command
3377 ``create a window with a TELNET connection to foobar'', and bind
3378 @key{ESC} to the command that creates an non-login window with title
3379 @samp{root} in slot #9, with a superuser shell and a scrollback buffer
3383 bind -c demo1 0 select 10
3384 bind -c demo1 1 select 11
3385 bind -c demo1 2 select 12
3386 bindkey "^B" command -c demo1
3388 makes @kbd{C-b 0} select window 10, @kbd{C-b 1} window 11, etc.
3391 bind -c demo2 0 select 10
3392 bind -c demo2 1 select 11
3393 bind -c demo2 2 select 12
3394 bind - command -c demo2
3396 makes @kbd{C-a - 0} select window 10, @kbd{C-a - 1} window 11, etc.
3398 @node Command Character, Help, Bind Examples, Key Binding
3399 @cindex escape character
3400 @cindex command character
3401 @section Command Character
3403 @deffn Command escape xy
3405 Set the command character to @var{x} and the character generating a
3406 literal command character (by triggering the @code{meta} command)
3407 to @var{y} (similar to the @samp{-e} option).
3408 Each argument is either a single character, a two-character
3409 sequence of the form @samp{^x} (meaning @kbd{C-x}), a backslash followed
3410 by an octal number (specifying the ASCII code of the character), or a
3411 backslash followed by a second character, such as @samp{\^} or
3412 @samp{\\}. The default is @samp{^Aa}, but @samp{``} is recommended by
3416 @deffn Command defescape xy
3418 Set the default command characters. This is equivalent to the command
3419 @code{escape} except that it is useful for multiuser sessions only.
3420 In a multiuser session
3421 @code{escape} changes the command character of the calling user, where
3422 @code{defescape} changes the default command characters for users that
3423 will be added later.
3429 Send the command character (@kbd{C-a}) to the process in the current
3430 window. The keystroke for this command is the second parameter to the
3431 @samp{-e} command line switch (@pxref{Invoking Screen}), or the
3432 @code{escape} .screenrc directive.
3435 @deffn Command command [-c @var{class}]
3437 This command has the same effect as typing the screen escape character
3438 (@kbd{C-a}). It is probably only useful for key bindings.
3439 If the @samp{-c} option is given, select the specified command class.
3440 @xref{Bind}, @xref{Bindkey}.
3443 @node Help, Bindkey, Command Character, Key Binding
3448 Displays a help screen showing you all the key bindings. The first
3449 pages list all the internal commands followed by their bindings.
3450 Subsequent pages will display the custom commands, one command per key.
3451 Press space when you're done reading each page, or return to exit early.
3452 All other characters are ignored.
3453 If the @samp{-c} option is given, display all bound commands for the
3454 specified command class.
3455 @xref{Default Key Bindings}.
3458 @node Bindkey, Bindkey Examples, Help, Key Binding
3460 @deffn Command bindkey [@var{opts}] [@var{string} [@var{cmd} @var{args}]]
3462 This command manages screen's input translation tables. Every
3463 entry in one of the tables tells screen how to react if a certain
3464 sequence of characters is encountered. There are three tables:
3465 one that should contain actions programmed by the user, one for
3466 the default actions used for terminal emulation and one for
3467 screen's copy mode to do cursor movement. See @ref{Input Translation}
3468 for a list of default key bindings.
3471 option is given, bindkey modifies the default table, @samp{-m}
3472 changes the copy mode table and with neither option the user
3473 table is selected. The argument @samp{string} is the sequence of
3474 characters to which an action is bound. This can either be a fixed
3475 string or a termcap keyboard capability name (selectable with the
3478 Some keys on a VT100 terminal can send a different
3479 string if application mode is turned on (e.g. the cursor keys).
3480 Such keys have two entries in the translation table. You can
3481 select the application mode entry by specifying the @samp{-a}
3484 The @samp{-t} option tells screen not to do inter-character
3485 timing. One cannot turn off the timing if a termcap capability is
3488 @samp{cmd} can be any of screen's commands with an arbitrary
3489 number of @samp{args}. If @samp{cmd} is omitted the key-binding is
3490 removed from the table.
3493 @node Bindkey Examples, Bindkey Control,Bindkey, Key Binding
3494 @section Bindkey Examples
3496 Here are some examples of keyboard bindings:
3502 Show all of the default key bindings. The application mode entries
3503 are marked with [A].
3506 bindkey -k k1 select 1
3509 Make the "F1" key switch to window one.
3512 bindkey -t foo stuff barfoo
3515 Make @samp{foo} an abbreviation of the word @samp{barfoo}. Timeout is
3516 disabled so that users can type slowly.
3519 bindkey "\024" mapdefault
3522 This key-binding makes @samp{C-t} an escape character for key-bindings. If
3523 you did the above @samp{stuff barfoo} binding, you can enter the word
3524 @samp{foo} by typing @samp{C-t foo}. If you want to insert a
3525 @samp{C-t} you have to press the key twice (i.e., escape the escape
3529 bindkey -k F1 command
3532 Make the F11 (not F1!) key an alternative screen
3533 escape (besides @samp{C-a}).
3535 @node Bindkey Control, , Bindkey Examples, Key Binding
3536 @section Bindkey Control
3537 @deffn Command mapdefault
3539 Tell screen that the next input character should only be looked up
3540 in the default bindkey table.
3542 @deffn Command mapnotnext
3544 Like mapdefault, but don't even look in the default bindkey table.
3546 @deffn Command maptimeout timo
3548 Set the inter-character timer for input sequence detection to a timeout
3549 of @var{timo} ms. The default timeout is 300ms. Maptimeout with no
3550 arguments shows the current setting.
3553 @node Flow Control, Termcap, Key Binding, Top
3554 @chapter Flow Control
3555 @cindex flow control
3557 @code{screen} can trap flow control characters or pass them to the
3558 program, as you see fit. This is useful when your terminal wants to use
3559 XON/XOFF flow control and you are running a program which wants to use
3560 ^S/^Q for other purposes (i.e. @code{emacs}).
3563 * Flow Control Summary:: The effect of @code{screen} flow control
3564 * Flow:: Setting the flow control behavior
3565 * XON/XOFF:: Sending XON or XOFF to the window
3568 @node Flow Control Summary, Flow, , Flow Control
3569 @section About @code{screen} flow control settings
3570 Each window has a flow-control setting that determines how screen deals
3571 with the XON and XOFF characters (and perhaps the interrupt character).
3572 When flow-control is turned off, screen ignores the XON and XOFF
3573 characters, which allows the user to send them to the current program by
3574 simply typing them (useful for the @code{emacs} editor, for instance).
3575 The trade-off is that it will take longer for output from a
3576 ``normal'' program to pause in response to an XOFF. With
3577 flow-control turned on, XON and XOFF characters are used to immediately
3578 pause the output of the current window. You can still send these
3579 characters to the current program, but you must use the appropriate
3580 two-character screen commands (typically @kbd{C-a q} (xon) and @kbd{C-a
3581 s} (xoff)). The xon/xoff commands are also useful for typing C-s and
3582 C-q past a terminal that intercepts these characters.
3584 Each window has an initial flow-control value set with either the
3585 @samp{-f} option or the @code{defflow} command. By default the
3586 windows are set to automatic flow-switching. It can then be toggled
3587 between the three states 'fixed on', 'fixed off' and 'automatic'
3588 interactively with the @code{flow} command bound to @kbd{C-a f}.
3590 The automatic flow-switching mode deals with flow control using the
3591 TIOCPKT mode (like @code{rlogin} does). If the tty driver does not
3592 support TIOCPKT, screen tries to determine the right mode based on the
3593 current setting of the application keypad --- when it is enabled,
3594 flow-control is turned off and visa versa. Of course, you can still
3595 manipulate flow-control manually when needed.
3597 If you're running with flow-control enabled and find that pressing the
3598 interrupt key (usually C-c) does not interrupt the display until another
3599 6-8 lines have scrolled by, try running screen with the @samp{interrupt}
3600 option (add the @samp{interrupt} flag to the @code{flow} command in your
3601 .screenrc, or use the @samp{-i} command-line option). This causes the
3602 output that @code{screen} has accumulated from the interrupted program
3603 to be flushed. One disadvantage is that the virtual terminal's memory
3604 contains the non-flushed version of the output, which in rare cases can
3605 cause minor inaccuracies in the output. For example, if you switch
3606 screens and return, or update the screen with @kbd{C-a l} you would see
3607 the version of the output you would have gotten without @samp{interrupt}
3608 being on. Also, you might need to turn off flow-control (or use
3609 auto-flow mode to turn it off automatically) when running a program that
3610 expects you to type the interrupt character as input, as the
3611 @samp{interrupt} parameter only takes effect when flow-control is
3612 enabled. If your program's output is interrupted by mistake, a simple
3613 refresh of the screen with @kbd{C-a l} will restore it. Give each mode
3614 a try, and use whichever mode you find more comfortable.
3616 @node Flow, XON/XOFF, Flow Control Summary, Flow Control
3618 @deffn Command defflow fstate [interrupt]
3620 Same as the @code{flow} command except that the default setting for new
3621 windows is changed. Initial setting is `auto'.
3622 Specifying @code{flow auto interrupt} has the same effect as the
3623 command-line options @samp{-fa} and @samp{-i}.
3624 Note that if @samp{interrupt} is enabled, all existing displays are
3625 changed immediately to forward interrupt signals.
3630 @deffn Command flow [fstate]
3631 (@kbd{C-a f}, @kbd{C-a C-f})@*
3632 Sets the flow-control mode for this window to @var{fstate}, which can be
3633 @samp{on}, @samp{off} or @samp{auto}.
3634 Without parameters it cycles the current window's
3635 flow-control setting. Default is set by `defflow'.
3638 @node XON/XOFF, , Flow, Flow Control
3639 @section XON and XOFF
3643 (@kbd{C-a q}, @kbd{C-a C-q})@*
3644 Send a ^Q (ASCII XON) to the program in the current window. Redundant
3645 if flow control is set to @samp{off} or @samp{auto}.
3651 (@kbd{C-a s}, @kbd{C-a C-s})@*
3652 Send a ^S (ASCII XOFF) to the program in the current window.
3655 @node Termcap, Message Line, Flow Control, Top
3658 @code{screen} demands the most out of your terminal so that it can
3659 perform its VT100 emulation most efficiently. These functions provide
3660 means for tweaking the termcap entries for both your physical terminal
3661 and the one simulated by @code{screen}.
3664 * Window Termcap:: Choosing a termcap entry for the window.
3665 * Dump Termcap:: Write out a termcap entry for the window.
3666 * Termcap Syntax:: The @code{termcap} and @code{terminfo} commands.
3667 * Termcap Examples:: Uses for @code{termcap}.
3668 * Special Capabilities:: Non-standard capabilities used by @code{screen}.
3669 * Autonuke:: Flush unseen output
3670 * Obuflimit:: Allow pending output when reading more
3671 * Character Translation:: Emulating fonts and charsets.
3674 @node Window Termcap, Dump Termcap, , Termcap
3675 @section Choosing the termcap entry for a window
3676 Usually @code{screen} tries to emulate as much of the VT100/ANSI
3677 standard as possible. But if your terminal lacks certain capabilities
3678 the emulation may not be complete. In these cases @code{screen} has to
3679 tell the applications that some of the features are missing. This is no
3680 problem on machines using termcap, because @code{screen} can use the
3681 @code{$TERMCAP} variable to customize the standard screen termcap.
3683 But if you do a rlogin on another machine or your machine supports only
3684 terminfo this method fails. Because of this @code{screen} offers a way
3685 to deal with these cases. Here is how it works:
3687 When @code{screen} tries to figure out a terminal name for itself, it
3688 first looks for an entry named @code{screen.@var{term}}, where
3689 @var{term} is the contents of your @code{$TERM} variable. If no such entry
3690 exists, @code{screen} tries @samp{screen} (or @samp{screen-w}, if the
3691 terminal is wide (132 cols or more)). If even this entry cannot be
3692 found, @samp{vt100} is used as a substitute.
3694 The idea is that if you have a terminal which doesn't support an
3695 important feature (e.g. delete char or clear to EOS) you can build a new
3696 termcap/terminfo entry for @code{screen} (named
3697 @samp{screen.@var{dumbterm}}) in which this capability has been
3698 disabled. If this entry is installed on your machines you are able to
3699 do a rlogin and still keep the correct termcap/terminfo entry. The
3700 terminal name is put in the @code{$TERM} variable of all new windows.
3701 @code{screen} also sets the @code{$TERMCAP} variable reflecting the
3702 capabilities of the virtual terminal emulated.
3703 Furthermore, the variable @code{$WINDOW} is set to the window number of each
3706 The actual set of capabilities supported by the virtual terminal depends
3707 on the capabilities supported by the physical terminal. If, for
3708 instance, the physical terminal does not support underscore mode,
3709 @code{screen} does not put the @samp{us} and @samp{ue} capabilities into
3710 the window's @code{$TERMCAP} variable, accordingly. However, a minimum number
3711 of capabilities must be supported by a terminal in order to run
3712 @code{screen}; namely scrolling, clear screen, and direct cursor
3713 addressing (in addition, @code{screen} does not run on hardcopy
3714 terminals or on terminals that over-strike).
3716 Also, you can customize the @code{$TERMCAP} value used by @code{screen} by
3717 using the @code{termcap} command, or by defining the variable
3718 @code{$SCREENCAP} prior to startup. When the latter defined, its value will be
3719 copied verbatim into each window's @code{$TERMCAP} variable. This can either
3720 be the full terminal definition, or a filename where the terminal
3721 @samp{screen} (and/or @samp{screen-w}) is defined.
3723 Note that @code{screen} honors the @code{terminfo} command if the system
3724 uses the terminfo database rather than termcap. On such machines the
3725 @code{$TERMCAP} variable has no effect and you must use the
3726 @code{dumptermcap} command (@pxref{Dump Termcap}) and the @code{tic}
3727 program to generate terminfo entries for @code{screen} windows.
3729 When the boolean @samp{G0} capability is present in the termcap entry
3730 for the terminal on which @code{screen} has been called, the terminal
3731 emulation of @code{screen} supports multiple character sets. This
3732 allows an application to make use of, for instance, the VT100 graphics
3733 character set or national character sets. The following control
3734 functions from ISO 2022 are supported: @samp{lock shift G0} (@samp{SI}),
3735 @samp{lock shift G1} (@samp{SO}), @samp{lock shift G2}, @samp{lock shift
3736 G3}, @samp{single shift G2}, and @samp{single shift G3}. When a virtual
3737 terminal is created or reset, the ASCII character set is designated as
3738 @samp{G0} through @samp{G3}. When the @samp{G0} capability is present,
3739 screen evaluates the capabilities @samp{S0}, @samp{E0}, and @samp{C0} if
3740 present. @samp{S0} is the sequence the terminal uses to enable and start
3741 the graphics character set rather than @samp{SI}. @samp{E0} is the
3742 corresponding replacement for @samp{SO}. @samp{C0} gives a character by
3743 character translation string that is used during semi-graphics mode.
3744 This string is built like the @samp{acsc} terminfo capability.
3746 When the @samp{po} and @samp{pf} capabilities are present in the
3747 terminal's termcap entry, applications running in a @code{screen} window
3748 can send output to the printer port of the terminal. This allows a user
3749 to have an application in one window sending output to a printer
3750 connected to the terminal, while all other windows are still active (the
3751 printer port is enabled and disabled again for each chunk of output).
3752 As a side-effect, programs running in different windows can send output
3753 to the printer simultaneously. Data sent to the printer is not
3754 displayed in the window. The @code{info} command displays a line starting
3755 with @samp{PRIN} while the printer is active.
3757 Some capabilities are only put into the @code{$TERMCAP} variable of the virtual
3758 terminal if they can be efficiently implemented by the physical
3759 terminal. For instance, @samp{dl} (delete line) is only put into the
3760 @code{$TERMCAP} variable if the terminal supports either delete line itself or
3761 scrolling regions. Note that this may provoke confusion, when the
3762 session is reattached on a different terminal, as the value of @code{$TERMCAP}
3763 cannot be modified by parent processes. You can force @code{screen} to
3764 include all capabilities in @code{$TERMCAP} with the @samp{-a}
3765 command-line option (@pxref{Invoking Screen}).
3767 The "alternate screen" capability is not enabled by default.
3768 Set the @code{altscreen} @file{.screenrc} command to enable it.
3770 @node Dump Termcap, Termcap Syntax, Window Termcap, Termcap
3771 @section Write out the window's termcap entry
3773 @deffn Command dumptermcap
3775 Write the termcap entry for the virtual terminal optimized for the
3776 currently active window to the file @file{.termcap} in the user's
3777 @file{$HOME/.screen} directory (or wherever @code{screen} stores its
3778 sockets. @pxref{Files}). This termcap entry is identical to
3779 the value of the environment variable @code{$TERMCAP} that is set up by
3780 @code{screen} for each window. For terminfo based systems you will need
3781 to run a converter like @code{captoinfo} and then compile the entry with
3785 @node Termcap Syntax, Termcap Examples, Dump Termcap, Termcap
3786 @section The @code{termcap} command
3787 @deffn Command termcap term terminal-tweaks [window-tweaks]
3788 @deffnx Command terminfo term terminal-tweaks [window-tweaks]
3789 @deffnx Command termcapinfo term terminal-tweaks [window-tweaks]
3791 Use this command to modify your terminal's termcap entry without going
3792 through all the hassles involved in creating a custom termcap entry.
3793 Plus, you can optionally customize the termcap generated for the
3795 You have to place these commands in one of the screenrc startup files, as they
3796 are meaningless once the terminal emulator is booted.
3798 If your system uses the terminfo database rather than termcap,
3799 @code{screen} will understand the @code{terminfo} command, which has the
3800 same effects as the @code{termcap} command. Two separate commands are
3801 provided, as there are subtle syntactic differences, e.g. when parameter
3802 interpolation (using @samp{%}) is required. Note that the termcap names of
3803 the capabilities should also be used with the @code{terminfo} command.
3805 In many cases, where the arguments are valid in both terminfo and termcap
3806 syntax, you can use the command @code{termcapinfo}, which is just a
3807 shorthand for a pair of @code{termcap} and @code{terminfo} commands with
3808 identical arguments.
3811 The first argument specifies which terminal(s) should be affected by
3812 this definition. You can specify multiple terminal names by separating
3813 them with @samp{|}s. Use @samp{*} to match all terminals and @samp{vt*}
3814 to match all terminals that begin with @samp{vt}.
3816 Each @var{tweak} argument contains one or more termcap defines
3817 (separated by @samp{:}s) to be inserted at the start of the appropriate
3818 termcap entry, enhancing it or overriding existing values. The first
3819 tweak modifies your terminal's termcap, and contains definitions that
3820 your terminal uses to perform certain functions. Specify a null string
3821 to leave this unchanged (e.g. ""). The second (optional) tweak modifies
3822 all the window termcaps, and should contain definitions that screen
3823 understands (@pxref{Virtual Terminal}).
3825 @node Termcap Examples, Special Capabilities, Termcap Syntax, Termcap
3826 @section Termcap Examples
3830 termcap xterm* xn:hs@@
3834 Informs @code{screen} that all terminals that begin with @samp{xterm}
3835 have firm auto-margins that allow the last position on the screen to be
3836 updated (xn), but they don't really have a status line (no 'hs' --
3837 append @samp{@@} to turn entries off). Note that we assume @samp{xn} for
3838 all terminal names that start with @samp{vt}, but only if you don't
3839 specify a termcap command for that terminal.
3843 termcap vt102|vt220 Z0=\E[?3h:Z1=\E[?3l
3847 Specifies the firm-margined @samp{xn} capability for all terminals that
3848 begin with @samp{vt}, and the second line will also add the
3849 escape-sequences to switch into (Z0) and back out of (Z1)
3850 132-character-per-line mode if this is a VT102 or VT220. (You must
3851 specify Z0 and Z1 in your termcap to use the width-changing commands.)
3854 termcap vt100 "" l0=PF1:l1=PF2:l2=PF3:l3=PF4
3858 This leaves your vt100 termcap alone and adds the function key labels to
3859 each window's termcap entry.
3862 termcap h19|z19 am@@:im=\E@@:ei=\EO dc=\E[P
3866 Takes a h19 or z19 termcap and turns off auto-margins (am@@) and enables
3867 the insert mode (im) and end-insert (ei) capabilities (the @samp{@@} in
3868 the @samp{im} string is after the @samp{=}, so it is part of the
3869 string). Having the @samp{im} and @samp{ei} definitions put into your
3870 terminal's termcap will cause screen to automatically advertise the
3871 character-insert capability in each window's termcap. Each window will
3872 also get the delete-character capability (dc) added to its termcap,
3873 which screen will translate into a line-update for the terminal (we're
3874 pretending it doesn't support character deletion).
3876 If you would like to fully specify each window's termcap entry, you
3877 should instead set the @code{$SCREENCAP} variable prior to running
3878 @code{screen}. @xref{Virtual Terminal}, for the details of the
3879 @code{screen} terminal emulation. @xref{Top, , Termcap, termcap, The
3880 Termcap Manual}, for more information on termcap definitions.
3882 @node Special Capabilities, Autonuke, Termcap Examples, Termcap
3883 @section Special Terminal Capabilities
3884 @cindex terminal capabilities
3885 @cindex capabilities
3886 The following table describes all terminal capabilities that are
3887 recognized by @code{screen} and are not in the termcap manual
3888 (@pxref{Top, , Termcap, termcap, The Termcap Manual}).
3889 You can place these capabilities in your termcap entries (in
3890 @file{/etc/termcap}) or use them with the commands @code{termcap},
3891 @code{terminfo} and @code{termcapinfo} in your @code{screenrc} files. It is
3892 often not possible to place these capabilities in the terminfo database.
3896 Terminal has VT100 style margins (`magic margins'). Note that
3897 this capability is obsolete --- @code{screen} now uses the standard
3902 Change width to 132 columns.
3906 Change width to 80 columns.
3910 Resize display. This capability has the desired width and height as
3911 arguments. SunView(tm) example: @samp{\E[8;%d;%dt}.
3915 Terminal doesn't need flow control. Send ^S and ^Q direct to
3916 the application. Same as @code{flow off}. The opposite of this
3917 capability is @samp{nx}.
3921 Terminal can deal with ISO 2022 font selection sequences.
3925 Switch charset @samp{G0} to the specified charset. Default
3930 Switch charset @samp{G0} back to standard charset. Default
3935 Use the string as a conversion table for font 0. See
3936 the @samp{ac} capability for more details.
3940 Switch cursor-keys to application mode.
3944 Switch cursor-keys to cursor mode.
3948 Enable autonuke for displays of this terminal type.
3953 Set the output buffer limit. See the @samp{obuflimit} command
3954 (@pxref{Obuflimit}) for more details.
3958 Set the encoding of the terminal. See the @samp{encoding} command
3959 (@pxref{Character Processing}) for valid encodings.
3963 Change character foreground color in an ANSI conform way. This
3964 capability will almost always be set to @samp{\E[3%dm}
3965 (@samp{\E[3%p1%dm} on terminfo machines).
3969 Same as @samp{AF}, but change background color.
3973 Does understand ANSI set default fg/bg color (@samp{\E[39m / \E[49m}).
3977 Describe a translation of characters to strings depending on the
3978 current font. (@pxref{Character Translation}).
3982 Terminal understands special xterm sequences (OSC, mouse tracking).
3986 Terminal needs bold to display high-intensity colors (e.g. Eterm).
3990 Add missing capabilities to the termcap/info entry. (Set by default).
3993 @node Autonuke, Obuflimit, Special Capabilities, Termcap
3995 @deffn Command autonuke @var{state}
3997 Sets whether a clear screen sequence should nuke all the output
3998 that has not been written to the terminal. @xref{Obuflimit}.
3999 This property is set per display, not per window.
4002 @deffn Command defautonuke @var{state}
4004 Same as the @code{autonuke} command except that the default setting for
4005 new displays is also changed. Initial setting is @code{off}.
4006 Note that you can use the special @code{AN} terminal capability if you
4007 want to have a terminal type dependent setting.
4010 @node Obuflimit, Character Translation, Autonuke, Termcap
4012 @deffn Command obuflimit [@var{limit}]
4014 If the output buffer contains more bytes than the specified limit, no
4015 more data will be read from the windows. The default value is 256. If
4016 you have a fast display (like @code{xterm}), you can set it to some
4017 higher value. If no argument is specified, the current setting is displayed.
4018 This property is set per display, not per window.
4021 @deffn Command defobuflimit @var{limit}
4023 Same as the @code{obuflimit} command except that the default setting for new
4024 displays is also changed. Initial setting is 256 bytes. Note that you can use
4025 the special @code{OL} terminal capability if you want to have a terminal
4026 type dependent limit.
4029 @node Character Translation, , Obuflimit, Termcap
4030 @section Character Translation
4031 @code{Screen} has a powerful mechanism to translate characters to
4032 arbitrary strings depending on the current font and terminal type.
4033 Use this feature if you want to work with a common standard character
4034 set (say ISO8851-latin1) even on terminals that scatter the more
4035 unusual characters over several national language font pages.
4040 XC=@var{<charset-mapping>}@{,,@var{<charset-mapping>}@}
4041 @var{<charset-mapping>} := @var{<designator>}@var{<template>}@{,@var{<mapping>}@}
4042 @var{<mapping>} := @var{<char-to-be-mapped>}@var{<template-arg>}
4045 The things in braces may be repeated any number of times.
4047 A @var{<charset-mapping>} tells screen how to map characters
4048 in font @var{<designator>} (@samp{B}: Ascii, @samp{A}: UK,
4049 @samp{K}: german, etc.)
4050 to strings. Every @var{<mapping>} describes to what string a single
4051 character will be translated. A template mechanism is used, as
4052 most of the time the codes have a lot in common (for example
4053 strings to switch to and from another charset). Each occurrence
4054 of @samp{%} in @var{<template>} gets substituted with the
4056 specified together with the character. If your strings are not
4057 similar at all, then use @samp{%} as a template and place the full
4058 string in @var{<template-arg>}. A quoting mechanism was added to make
4059 it possible to use a real @samp{%}. The @samp{\} character quotes the
4060 special characters @samp{\}, @samp{%}, and @samp{,}.
4065 termcap hp700 'XC=B\E(K%\E(B,\304[,\326\\\\,\334]'
4068 This tells @code{screen}, how to translate ISOlatin1 (charset @samp{B})
4069 upper case umlaut characters on a @code{hp700} terminal that has a
4070 German charset. @samp{\304} gets translated to
4071 @samp{\E(K[\E(B} and so on.
4072 Note that this line gets parsed *three* times before the internal
4073 lookup table is built, therefore a lot of quoting is needed to
4074 create a single @samp{\}.
4076 Another extension was added to allow more emulation: If a mapping
4077 translates the unquoted @samp{%} char, it will be sent to the terminal
4078 whenever screen switches to the corresponding @var{<designator>}.
4080 special case the template is assumed to be just @samp{%} because
4081 the charset switch sequence and the character mappings normally
4082 haven't much in common.
4084 This example shows one use of the extension:
4086 termcap xterm 'XC=K%,%\E(B,[\304,\\\\\326,]\334'
4089 Here, a part of the German (@samp{K}) charset is emulated on an xterm.
4090 If screen has to change to the @samp{K} charset, @samp{\E(B} will be
4092 to the terminal, i.e. the ASCII charset is used instead. The
4093 template is just @samp{%}, so the mapping is straightforward:
4094 @samp{[} to @samp{\304}, @samp{\} to @samp{\326}, and @samp{]} to
4097 @node Message Line, Logging, Termcap, Top
4098 @chapter The Message Line
4099 @cindex message line
4101 @code{screen} displays informational messages and other diagnostics in a
4102 @dfn{message line} at the bottom of the screen. If your terminal has a
4103 status line defined in its termcap, screen will use this for displaying
4104 its messages, otherwise the last line of the screen will be temporarily
4105 overwritten and output will be momentarily interrupted. The message
4106 line is automatically removed after a few seconds delay, but it can also
4107 be removed early (on terminals without a status line) by beginning to
4111 * Privacy Message:: Using the message line from your program.
4112 * Hardware Status Line:: Use the terminal's hardware status line.
4113 * Last Message:: Redisplay the last message.
4114 * Message Wait:: Control how long messages are displayed.
4117 @node Privacy Message, Hardware Status Line, , Message Line
4118 @section Using the message line from your program
4119 The message line facility can be used by an application running in the
4120 current window by means of the ANSI @dfn{Privacy message} control
4121 sequence. For instance, from within the shell, try something like:
4124 echo "@value{esc}^Hello world from window $WINDOW@value{esc}\"
4127 where @samp{@value{esc}} is ASCII ESC and the @samp{^} that follows it
4128 is a literal caret or up-arrow.
4130 @node Hardware Status Line, Last Message, Privacy Message, Message Line
4131 @section Hardware Status Line
4132 @deffn Command hardstatus [state]
4133 @deffnx Command hardstatus [@code{always}]@code{lastline}|@code{message}|@code{ignore} [string]
4134 @deffnx Command hardstatus @code{string} [string]
4136 This command configures the use and emulation of the terminal's
4137 hardstatus line. The first form toggles whether @code{screen}
4138 will use the hardware status line to display messages. If the
4139 flag is set to @samp{off}, these messages
4140 are overlaid in reverse video mode at the display line. The default
4141 setting is @samp{on}.
4143 The second form tells screen what to do if the terminal doesn't
4144 have a hardstatus line (i.e. the termcap/terminfo capabilities
4145 "hs", "ts", "fs" and "ds" are not set). If the type
4146 @code{lastline} is used, screen will reserve the last line of the
4147 display for the hardstatus. @code{message} uses
4148 @code{screen}'s message mechanism and
4149 @code{ignore} tells @code{screen} never to display the hardstatus.
4150 If you prepend the word @code{always} to the type (e.g., @code{alwayslastline}), @code{screen} will use
4151 the type even if the terminal supports a hardstatus line.
4153 The third form specifies the contents of the hardstatus line.
4154 @code{%h} is used as default string, i.e., the stored hardstatus of the
4155 current window (settable via @samp{ESC]0;^G} or @samp{ESC_\\}) is
4157 You can customize this to any string you like including
4158 string escapes (@pxref{String Escapes}).
4160 out the argument @var{string}, the current string is displayed.
4162 You can mix the second and third form by providing the string as
4163 additional argument.
4166 @node Last Message, Message Wait, Hardware Status Line, Message Line
4167 @section Display Last Message
4170 @deffn Command lastmsg
4171 (@kbd{C-a m}, @kbd{C-a C-m})@*
4172 Repeat the last message displayed in the message line. Useful if you're
4173 typing when a message appears, because (unless your terminal has a
4174 hardware status line) the message goes away when you press a key.
4177 @node Message Wait, , Last Message, Message Line
4178 @section Message Wait
4179 @deffn Command msgminwait sec
4181 Defines the time @code{screen} delays a new message when another is
4182 currently displayed. Defaults to 1 second.
4185 @deffn Command msgwait sec
4187 Defines the time a message is displayed, if @code{screen} is not
4188 disturbed by other activity. Defaults to 5 seconds.
4191 @node Logging, Startup, Message Line, Top
4194 This section describes the commands for keeping a record of your session.
4197 * Hardcopy:: Dump the current screen to a file
4198 * Log:: Log the output of a window to a file
4201 @node Hardcopy, Log, , Logging
4205 @deffn Command hardcopy [-h] [@var{file}]
4206 (@kbd{C-a h}, @kbd{C-a C-h})@*
4207 Writes out the currently displayed image to the file @var{file}, or,
4208 if no filename is specified, to @file{hardcopy.@var{n}}
4209 in the default directory, where @var{n} is the number of the
4210 current window. This either appends or overwrites the file if it
4211 exists, as determined by the @code{hardcopy_append} command.
4212 If the option @code{-h} is specified, dump also the
4213 contents of the scrollback buffer.
4216 @deffn Command hardcopy_append state
4218 If set to @samp{on}, @code{screen} will append to the
4219 @file{hardcopy.@var{n}} files created by the command @code{hardcopy};
4220 otherwise, these files are overwritten each time.
4223 @deffn Command hardcopydir directory
4225 Defines a directory where hardcopy files will be placed.
4226 If unset, hardcopys are dumped in screen's current working
4230 @node Log, , Hardcopy, Logging
4233 @deffn Command deflog state
4235 Same as the @code{log} command except that the default setting for new
4236 windows is changed. Initial setting is `off'.
4240 @deffn Command log [state]
4242 Begins/ends logging of the current window to the file
4243 @file{screenlog.@var{n}} in the window's default directory, where
4244 @var{n} is the number of the current window.
4245 This filename can be changed with the @samp{logfile} command.
4246 If no parameter is given,
4247 the logging state is toggled. The session log is
4248 appended to the previous contents of the file if it already exists. The
4249 current contents and the contents of the scrollback history are not
4250 included in the session log. Default is @samp{off}.
4253 @deffn Command logfile filename
4254 @deffnx Command logfile flush secs
4256 Defines the name the log files will get. The default is @samp{screenlog.%n}.
4257 The second form changes the number of seconds @code{screen}
4258 will wait before flushing the logfile buffer to the file-system. The
4259 default value is 10 seconds.
4262 @deffn Command logtstamp [state]
4263 @deffnx Command logtstamp @code{after} secs
4264 @deffnx Command logtstamp @code{string} string
4266 This command controls logfile time-stamp mechanism of screen. If
4267 time-stamps are turned @samp{on}, screen adds a string containing
4268 the current time to the logfile after two minutes of inactivity.
4269 When output continues and more than another two minutes have passed,
4270 a second time-stamp is added to document the restart of the
4271 output. You can change this timeout with the second form
4272 of the command. The third form is used for customizing the time-stamp
4273 string (@samp{-- %n:%t -- time-stamp -- %M/%d/%y %c:%s --\n} by
4277 @node Startup, Miscellaneous, Logging, Top
4280 This section describes commands which are only useful in the
4281 @file{.screenrc} file, for use at startup.
4284 * echo:: Display a message.
4285 * sleep:: Pause execution of the @file{.screenrc}.
4286 * Startup Message:: Control display of the copyright notice.
4289 @node echo, sleep, , Startup
4291 @deffn Command echo [@samp{-n}] message
4293 The echo command may be used to annoy @code{screen} users with a
4294 'message of the day'. Typically installed in a global screenrc.
4295 The option @samp{-n} may be used to suppress the line feed.
4296 See also @code{sleep}.
4297 Echo is also useful for online checking of environment variables.
4300 @node sleep, Startup Message, echo, Startup
4302 @deffn Command sleep num
4304 This command will pause the execution of a .screenrc file for @var{num}
4305 seconds. Keyboard activity will end the sleep. It may be used to give
4306 users a chance to read the messages output by @code{echo}.
4309 @node Startup Message, , sleep, Startup
4310 @section Startup Message
4311 @deffn Command startup_message state
4313 Select whether you want to see the copyright notice during startup.
4314 Default is @samp{on}, as you probably noticed.
4317 @node Miscellaneous, String Escapes, Startup, Top
4318 @chapter Miscellaneous commands
4320 The commands described here do not fit well under any of the other
4324 * At:: Execute a command at other displays or windows.
4325 * Break:: Send a break signal to the window.
4326 * Debug:: Suppress/allow debugging output.
4327 * License:: Display the disclaimer page.
4328 * Nethack:: Use @code{nethack}-like error messages.
4329 * Nonblock:: Disable flow-control to a display.
4330 * Number:: Change the current window's number.
4331 * Silence:: Notify on inactivity.
4332 * Time:: Display the time and load average.
4333 * Verbose:: Display window creation commands.
4334 * Version:: Display the version of @code{screen}.
4335 * Zombie:: Keep dead windows.
4336 * Printcmd:: Set command for VT100 printer port emulation.
4337 * Rendition:: Change text attributes in caption for flagged windows.
4338 * Sorendition:: Change the text highlighting method.
4339 * Attrcolor:: Map attributes to colors.
4340 * Setsid:: Change process group management.
4341 * Eval:: Parse and execute arguments.
4342 * Maxwin:: Set the maximum window number.
4343 * Backtick:: Program a command for a backtick string escape.
4344 * Screen Saver:: Define a screen safer.
4345 * Zmodem:: Define how screen treats zmodem requests.
4348 @node At, Break, , Miscellaneous
4350 @deffn Command at [identifier][#|*|%] command [args]
4352 Execute a command at other displays or windows as if it had been entered there.
4353 @code{At} changes the context (the `current window' or `current display'
4354 setting) of the command. If the first parameter describes a non-unique context,
4355 the command will be executed multiple times. If the first parameter is of the
4356 form @samp{@var{identifier}*} then identifier is matched against user names.
4357 The command is executed once for each display of the selected user(s).
4358 If the first parameter is of the form @samp{@var{identifier}%} identifier is
4359 matched against displays. Displays are named after the ttys they attach. The
4360 prefix @samp{/dev/} or @samp{/dev/tty} may be omitted from the identifier.
4361 If @var{identifier} has a @code{#} or nothing appended it is matched against
4362 window numbers and titles. Omitting an identifier in front of the @code{#},
4363 @code{*} or @code{%} character selects all users, displays or windows because
4364 a prefix-match is performed. Note that on the affected display(s) a short
4365 message will describe what happened.
4366 Note that the @code{#} character works as a comment introducer when it is
4367 preceded by whitespace. This can be escaped by prefixing @code{#} with a
4369 Permission is checked for the initiator of the @code{at} command, not for the
4370 owners of the affected display(s).
4372 When matching against windows, the command is executed at least
4373 once per window. Commands that change the internal arrangement of windows
4374 (like @code{other}) may be called again. In shared windows the command will
4375 be repeated for each attached display. Beware, when issuing toggle commands
4377 Some commands (e.g. @code{\*Qprocess}) require
4378 that a display is associated with the target windows. These commands may not
4379 work correctly under @code{at} looping over windows.
4382 @node Break, Debug, At, Miscellaneous
4384 @deffn Command break [duration]
4386 Send a break signal for @var{duration}*0.25 seconds to this window.
4387 For non-Posix systems the time interval is rounded up to full seconds.
4388 Most useful if a character device is attached to the window rather than
4389 a shell process (@pxref{Window Types}). The maximum duration of
4390 a break signal is limited to 15 seconds.
4393 @deffn Command pow_break
4395 Reopen the window's terminal line and send a break condition.
4398 @deffn Command breaktype [tcsendbreak|TIOCSBRK|TCSBRK]
4400 Choose one of the available methods of generating a break signal for
4401 terminal devices. This command should affect the current window only.
4402 But it still behaves identical to @code{defbreaktype}. This will be changed in
4404 Calling @code{breaktype} with no parameter displays the break setting for the
4408 @deffn Command defbreaktype [tcsendbreak|TIOCSBRK|TCSBRK]
4410 Choose one of the available methods of generating a break signal for
4411 terminal devices opened afterwards. The preferred methods are
4412 @code{tcsendbreak} and
4413 @code{TIOCSBRK}. The third, @code{TCSBRK}, blocks the complete @code{screen}
4414 session for the duration of the break, but it may be the only way to
4415 generate long breaks. @code{tcsendbreak} and @code{TIOCSBRK} may or may not
4416 produce long breaks with spikes (e.g. 4 per second). This is not only system
4417 dependent, this also differs between serial board drivers.
4418 Calling @code{defbreaktype} with no parameter displays the current setting.
4421 @node Debug, License, Break, Miscellaneous
4423 @deffn Command debug [on|off]
4425 Turns runtime debugging on or off. If @code{screen} has been compiled with
4426 option @code{-DDEBUG} debugging is available and is turned on per default.
4427 Note that this command only affects debugging output from the main
4428 @samp{SCREEN} process correctly. Debug output from attacher processes can only
4429 be turned off once and forever.
4432 @node License, Nethack, Debug, Miscellaneous
4434 @deffn Command license
4436 Display the disclaimer page. This is done whenever @code{screen} is
4437 started without options, which should be often enough.
4440 @node Nethack, Nonblock, License, Miscellaneous
4442 @deffn Command nethack state
4444 Changes the kind of error messages used by @code{screen}. When you are
4445 familiar with the game @code{nethack}, you may enjoy the nethack-style
4446 messages which will often blur the facts a little, but are much funnier
4447 to read. Anyway, standard messages often tend to be unclear as well.
4449 This option is only available if @code{screen} was compiled with the
4450 NETHACK flag defined (@pxref{Installation}). The default setting is then
4451 determined by the presence of the environment variable
4452 @code{$NETHACKOPTIONS}.
4455 @node Nonblock, Number, Nethack, Miscellaneous
4457 @deffn Command nonblock [@var{state}|@var{numsecs}]
4458 Tell screen how to deal with user interfaces (displays) that cease to
4459 accept output. This can happen if a user presses ^S or a TCP/modem
4460 connection gets cut but no hangup is received. If nonblock is
4461 @code{off} (this is the default) screen waits until the display
4462 restarts to accept the output. If nonblock is @code{on}, screen
4463 waits until the timeout is reached (@code{on} is treated as 1s). If the
4464 display still doesn't receive characters, screen will consider
4465 it ``blocked'' and stop sending characters to it. If at
4466 some time it restarts to accept characters, screen will unblock
4467 the display and redisplay the updated window contents.
4470 @deffn Command defnonblock @var{state}|@var{numsecs}
4471 Same as the @code{nonblock} command except that the default setting for
4472 displays is changed. Initial setting is @code{off}.
4475 @node Number, Silence, Nonblock, Miscellaneous
4478 @deffn Command number [@var{n}]
4480 Change the current window's number. If the given number @var{n} is already
4481 used by another window, both windows exchange their numbers. If no argument is
4482 specified, the current window number (and title) is shown.
4485 @node Silence, Time, Number, Miscellaneous
4487 @deffn Command silence [@var{state}|@var{sec}]
4489 Toggles silence monitoring of windows. When silence is turned on and an
4490 affected window is switched into the background, you will receive the
4491 silence notification message in the status line after a specified period
4492 of inactivity (silence). The default timeout can be changed with the
4493 @code{silencewait} command or by specifying a number of seconds instead of
4494 @code{on} or @code{off}. Silence is initially off for all windows.
4497 @deffn Command defsilence state
4499 Same as the @code{silence} command except that the default setting for
4500 new windows is changed. Initial setting is `off'.
4503 @deffn Command silencewait @var{seconds}
4505 Define the time that all windows monitored for silence should wait
4506 before displaying a message. Default is 30 seconds.
4509 @node Time, Verbose, Silence, Miscellaneous
4513 @deffn Command time [@var{string}]
4514 (@kbd{C-a t}, @kbd{C-a C-t})@*
4515 Uses the message line to display the time of day, the host name, and the
4516 load averages over 1, 5, and 15 minutes (if this is available on your
4517 system). For window-specific information use @code{info} (@pxref{Info}).
4518 If a @var{string} is specified, it changes the format of the time report
4519 like it is described in the string escapes chapter (@pxref{String Escapes}). Screen uses a default of @samp{%c:%s %M %d %H%? %l%?}.
4522 @node Verbose, Version, Time, Miscellaneous
4524 @deffn Command verbose [on|off]
4525 If verbose is switched on, the command name is echoed, whenever a window
4526 is created (or resurrected from zombie state). Default is off.
4527 Without parameter, the current setting is shown.
4530 @node Version, Zombie, Verbose, Miscellaneous
4533 @deffn Command version
4535 Display the version and modification date in the message line.
4538 @node Zombie, Printcmd, Version, Miscellaneous
4540 @deffn Command zombie [@var{keys} [onerror] ]
4541 @deffnx Command defzombie [@var{keys}]
4543 Per default windows are removed from the window list as soon as the
4544 windows process (e.g. shell) exits. When a string of two keys is
4545 specified to the zombie command, `dead' windows will remain in the list.
4546 The @code{kill} command may be used to remove the window. Pressing the first key
4547 in the dead window has the same effect. Pressing the second key, however,
4548 screen will attempt to resurrect the window. The process that was initially
4549 running in the window will be launched again. Calling @code{zombie} without
4550 parameters will clear the zombie setting, thus making windows disappear when
4551 the process terminates.
4553 As the zombie setting is affected globally for all windows, this command
4554 should only be called @code{defzombie}. Until we need this as a per window
4555 setting, the commands @code{zombie} and @code{defzombie} are synonymous.
4557 Optionally you can put the word @code{onerror} after the keys. This will
4558 cause screen to monitor exit status of the process running in the window.
4559 If it exits normally ('0'), the window disappears. Any other exit value
4560 causes the window to become a zombie.
4563 @node Printcmd, Rendition, Zombie, Miscellaneous
4565 @deffn Command printcmd [@var{cmd}]
4567 If @var{cmd} is not an empty string, screen will not use the terminal
4568 capabilities @code{po/pf} for printing if it detects an ansi print
4569 sequence @code{ESC [ 5 i}, but pipe the output into @var{cmd}.
4570 This should normally be a command like @samp{lpr} or
4571 @samp{cat > /tmp/scrprint}.
4572 @code{Printcmd} without an argument displays the current setting.
4573 The ansi sequence @code{ESC \} ends printing and closes the pipe.
4575 Warning: Be careful with this command! If other user have write
4576 access to your terminal, they will be able to fire off print commands.
4579 @node Rendition, Sorendition, Printcmd, Miscellaneous
4581 @deffn Command rendition bell | monitor | so @var{attr} [@var{color}]
4583 Change the way screen renders the titles of windows that have monitor
4584 or bell flags set in caption or hardstatus or windowlist.
4586 about string escapes (@pxref{String Escapes}) for the syntax of
4587 the modifiers. The default for monitor is currently @samp{=b} (bold,
4588 active colors), and for bell is @samp{=ub} (underline, bold and
4592 @node Sorendition, Attrcolor, Rendition, Miscellaneous
4593 @section Sorendition
4594 @deffn Command sorendition [@var{attr} [@var{color}]]
4596 Change the way screen does highlighting for text marking and printing
4599 about string escapes (@pxref{String Escapes}) for the syntax of
4600 the modifiers. The default is currently @samp{=s dd} (standout,
4604 @node Attrcolor, Setsid, Sorendition, Miscellaneous
4606 @deffn Command attrcolor @var{attrib} [@var{attribute/color-modifier}]
4608 This command can be used to highlight attributes by changing the color of
4609 the text. If the attribute
4611 is in use, the specified attribute/color modifier is also applied. If no
4612 modifier is given, the current one is deleted. See the chapter
4613 about string escapes (@pxref{String Escapes}) for the syntax of
4614 the modifier. Screen understands two pseudo-attributes, @code{i}
4615 stands for high-intensity foreground color and @code{I} for
4616 high-intensity background color.
4621 @item attrcolor b "R"
4622 Change the color to bright red if bold text is to be printed.
4623 @item attrcolor u "-u b"
4624 Use blue text instead of underline.
4625 @item attrcolor b ".I"
4626 Use bright colors for bold text. Most terminal emulators do this
4628 @item attrcolor i "+b"
4629 Make bright colored text also bold.
4633 @node Setsid, Eval, Attrcolor, Miscellaneous
4635 @deffn Command setsid state
4637 Normally screen uses different sessions and process groups for
4638 the windows. If setsid is turned @code{off}, this is not done
4639 anymore and all windows will be in the same process group as the
4640 screen backend process. This also breaks job-control, so be careful.
4641 The default is @code{on}, of course. This command is probably useful
4642 only in rare circumstances.
4645 @node Eval, Maxwin, Setsid, Miscellaneous
4647 @deffn Command eval @var{command1} [@var{command2} ...]
4649 Parses and executes each argument as separate command.
4652 @node Maxwin, Backtick, Eval, Miscellaneous
4654 @deffn Command maxwin @var{n}
4656 Set the maximum window number screen will create. Doesn't affect
4657 already existing windows. The number may only be decreased.
4660 @node Backtick, Screen Saver, Maxwin, Miscellaneous
4662 @deffn Command backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}]
4663 @deffnx Command backtick @var{id}
4665 Program the backtick command with the numerical id @var{id}.
4666 The output of such a command is used for substitution of the
4667 @code{%`} string escape (@pxref{String Escapes}).
4668 The specified @var{lifespan} is the number
4669 of seconds the output is considered valid. After this time, the
4670 command is run again if a corresponding string escape is encountered.
4671 The @var{autorefresh} parameter triggers an
4672 automatic refresh for caption and hardstatus strings after the
4673 specified number of seconds. Only the last line of output is used
4676 If both the @var{lifespan} and the @var{autorefresh} parameters
4677 are zero, the backtick program is expected to stay in the
4678 background and generate output once in a while.
4679 In this case, the command is executed right away and screen stores
4680 the last line of output. If a new line gets printed screen will
4681 automatically refresh the hardstatus or the captions.
4683 The second form of the command deletes the backtick command
4684 with the numerical id @var{id}.
4687 @node Screen Saver, Zmodem, Backtick, Miscellaneous
4688 @section Screen Saver
4689 @deffn Command idle [@var{timeout} [@var{cmd} @var{args}]]
4691 Sets a command that is run after the specified number of
4692 seconds inactivity is reached. This command will normally
4693 be the @code{blanker} command to create a screen blanker, but
4694 it can be any screen command. If no command is specified,
4695 only the timeout is set. A timeout of zero (ot the special
4696 timeout @code{off}) disables the timer. If no arguments are
4697 given, the current settings are displayed.
4700 @deffn Command blanker
4702 Activate the screen blanker. First the screen is cleared.
4703 If no blanker program is defined, the cursor is turned
4704 off, otherwise, the program is started and it's output is
4705 written to the screen. The screen blanker is killed with
4706 the first keypress, the read key is discarded.
4708 This command is normally used together with the @code{idle}
4712 @deffn Command blankerprg [@var{program args}]
4713 Defines a blanker program. Disables the blanker program if
4714 no arguments are given.
4717 @node Zmodem, , Screen Saver, Miscellaneous
4719 @deffn Command zmodem [off|auto|catch|pass]
4720 @deffnx Command zmodem sendcmd [string]
4721 @deffnx Command zmodem recvcmd [string]
4723 Define zmodem support for screen. Screen understands two
4724 different modes when it detects a zmodem request: @code{pass}
4725 and @code{catch}. If the mode is set to @code{pass}, screen will
4726 relay all data to the attacher until the end of the
4727 transmission is reached. In @code{catch} mode screen acts as a
4728 zmodem endpoint and starts the corresponding rz/sz commands.
4729 If the mode is set to @code{auto}, screen will use @code{catch} if
4730 the window is a tty (e.g. a serial line), otherwise it
4731 will use @code{pass}.
4733 You can define the templates screen uses in @code{catch} mode
4734 via the second and the third form.
4736 Note also that this is an experimental feature.
4739 @node String Escapes, Environment, Miscellaneous, Top
4740 @chapter String Escapes
4741 @cindex string escapes
4742 Screen provides an escape mechanism to insert information like the
4743 current time into messages or file names. The escape character
4744 is @code{%} with one exception: inside of a window's hardstatus
4745 @code{^%} (@code{^E}) is used instead.
4747 Here is the full list of supported escapes:
4751 the escape character itself
4753 either @code{am} or @code{pm}
4755 either @code{AM} or @code{PM}
4757 current time @code{HH:MM} in 24h format
4759 current time @code{HH:MM} in 12h format
4767 sets %? to true if the window has the focus
4769 hardstatus of the window
4771 hostname of the system
4773 current load of the system
4787 all other users on this window
4789 all window numbers and names. With @code{-} qualifier: up to the current
4790 window; with @code{+} qualifier: starting with the window after the current
4793 all window numbers and names except the current one
4795 last two digits of the year number
4799 the part to the next @code{%?} is displayed only if a @code{%} escape
4800 inside the part expands to a non-empty string
4802 else part of @code{%?}
4804 pad the string to the display's width (like TeX's hfill). If a
4805 number is specified, pad to the percentage of the window's width.
4806 A @code{0} qualifier tells screen to treat the number as absolute position.
4807 You can specify to pad relative to the last absolute pad position
4808 by adding a @code{+} qualifier or to pad relative to the right margin
4809 by using @code{-}. The padding truncates the string if the specified
4810 position lies before the current position. Add the @code{L} qualifier
4813 same as @code{%=} but just do truncation, do not fill with spaces
4815 mark the current text position for the next truncation. When
4816 screen needs to do truncation, it tries to do it in a way that
4817 the marked position gets moved to the specified percentage of
4818 the output area. (The area starts from the last absolute pad
4819 position and ends with the position specified by the truncation
4820 operator.) The @code{L} qualifier tells screen to mark the truncated
4821 parts with @samp{...}.
4823 attribute/color modifier string terminated by the next @code{@}}
4825 Substitute with the output of a `backtick' command. The length
4826 qualifier is misused to identify one of the commands. @xref{Backtick}.
4828 The @code{c} and @code{C} escape may be qualified with a @code{0} to
4830 zero instead of space as fill character.
4832 @code{=} escapes understand
4833 a length qualifier (e.g. @code{%3n}), @code{D} and @code{M} can be
4834 prefixed with @code{L} to generate long names, @code{w} and
4835 @code{W} also show the window flags if @code{L} is given.
4837 An attribute/color modifier is is used to change the attributes or the
4838 color settings. Its format
4839 is @samp{[attribute modifier] [color description]}. The attribute modifier
4840 must be prefixed by a change type indicator if it can be confused with
4841 a color description. The following change types are known:
4844 add the specified set to the current attributes
4846 remove the set from the current attributes
4848 invert the set in the current attributes
4850 change the current attributes to the specified set
4852 The attribute set can either be specified as a hexadecimal number or
4853 a combination of the following letters:
4868 Colors are coded either as a hexadecimal number or two letters specifying
4869 the desired background and foreground color (in that order). The following
4891 leave color unchanged
4893 The capitalized versions of the letter specify bright colors. You can also
4894 use the pseudo-color @samp{i} to set just the brightness and leave the color
4897 A one digit/letter color description is treated as foreground or
4898 background color dependent on the current attributes: if reverse mode is
4899 set, the background color is changed instead of the foreground color.
4900 If you don't like this, prefix the color with a @samp{.}. If you want
4901 the same behavior for two-letter color descriptions, also prefix them
4904 As a special case, @samp{%@{-@}} restores the attributes and colors that
4905 were set before the last change was made (i.e. pops one level of the
4906 color-change stack).
4912 set color to bright green
4916 clear all attributes, write in default color on yellow background.
4917 @item %-Lw%@{= BW@}%50>%n%f* %t%@{-@}%+Lw%<
4918 The available windows centered at the current win dow and truncated to
4919 the available width. The current window is displayed white on blue.
4920 This can be used with @samp{hardstatus alwayslastline}.
4921 @item %?%F%@{.R.@}%?%3n %t%? [%h]%?
4922 The window number and title and the window's hardstatus, if one is set.
4923 Also use a red background if this is the active focus.
4924 Useful for @samp{caption string}.
4928 @node Environment, Files, String Escapes, Top
4929 @chapter Environment Variables
4934 Number of columns on the terminal (overrides termcap entry).
4937 Directory in which to look for .screenrc.
4940 Number of lines on the terminal (overrides termcap entry).
4943 Screen lock program.
4945 @item NETHACKOPTIONS
4946 Turns on @code{nethack} option.
4949 Used for locating programs to run.
4952 For customizing a terminal's @code{TERMCAP} value.
4955 Alternate socket directory.
4958 Alternate user screenrc file.
4961 Default shell program for opening windows (default @file{/bin/sh}).
4964 Alternate socket name. If @code{screen} is invoked, and the environment variable
4965 @code{STY} is set, then it creates only a window in the running @code{screen}
4966 session rather than starting a new session.
4969 Alternate system screenrc file.
4975 Terminal description.
4978 Window number of a window (at creation time).
4981 @node Files, Credits, Environment, Top
4982 @chapter Files Referenced
4986 @item .../screen-4.?.??/etc/screenrc
4987 @itemx .../screen-4.?.??/etc/etcscreenrc
4988 Examples in the @code{screen} distribution package for private and
4989 global initialization files.
4991 @item @code{$SYSSCREENRC}
4992 @itemx /local/etc/screenrc
4993 @code{screen} initialization commands
4995 @item @code{$SCREENRC}
4996 @itemx @code{$HOME}/.iscreenrc
4997 @itemx @code{$HOME}/.screenrc
4998 Read in after /local/etc/screenrc
5000 @item @code{$SCREENDIR}/S-@var{login}
5002 @item /local/screens/S-@var{login}
5003 Socket directories (default)
5005 @item /usr/tmp/screens/S-@var{login}
5006 Alternate socket directories.
5008 @item @var{socket directory}/.termcap
5009 Written by the @code{dumptermcap} command
5011 @item /usr/tmp/screens/screen-exchange or
5012 @itemx /tmp/screen-exchange
5013 @code{screen} interprocess communication buffer
5015 @item hardcopy.[0-9]
5016 Screen images created by the hardcopy command
5018 @item screenlog.[0-9]
5019 Output log files created by the log command
5021 @item /usr/lib/terminfo/?/* or
5023 Terminal capability databases
5028 @item @code{$LOCKPRG}
5029 Program for locking the terminal.
5032 @node Credits, Bugs, Files, Top
5039 Originally created by Oliver Laumann, this latest version was
5040 produced by Wayne Davison, Juergen Weigert and Michael Schroeder.
5047 Ken Beal (kbeal@@amber.ssd.csd.harris.com),
5048 Rudolf Koenig (rfkoenig@@informatik.uni-erlangen.de),
5049 Toerless Eckert (eckert@@informatik.uni-erlangen.de),
5050 Wayne Davison (davison@@borland.com),
5051 Patrick Wolfe (pat@@kai.com, kailand!pat),
5052 Bart Schaefer (schaefer@@cse.ogi.edu),
5053 Nathan Glasser (nathan@@brokaw.lcs.mit.edu),
5054 Larry W. Virden (lvirden@@cas.org),
5055 Howard Chu (hyc@@hanauma.jpl.nasa.gov),
5056 Tim MacKenzie (tym@@dibbler.cs.monash.edu.au),
5057 Markku Jarvinen (mta@@@{cc,cs,ee@}.tut.fi),
5058 Marc Boucher (marc@@CAM.ORG),
5059 Doug Siebert (dsiebert@@isca.uiowa.edu),
5060 Ken Stillson (stillson@@tsfsrv.mitre.org),
5061 Ian Frechett (frechett@@spot.Colorado.EDU),
5062 Brian Koehmstedt (bpk@@gnu.ai.mit.edu),
5063 Don Smith (djs6015@@ultb.isc.rit.edu),
5064 Frank van der Linden (vdlinden@@fwi.uva.nl),
5065 Martin Schweikert (schweik@@cpp.ob.open.de),
5066 David Vrona (dave@@sashimi.lcu.com),
5067 E. Tye McQueen (tye%spillman.UUCP@@uunet.uu.net),
5068 Matthew Green (mrg@@eterna.com.au),
5069 Christopher Williams (cgw@@pobox.com),
5070 Matt Mosley (mattm@@access.digex.net),
5071 Gregory Neil Shapiro (gshapiro@@wpi.WPI.EDU),
5072 Jason Merrill (jason@@jarthur.Claremont.EDU),
5073 Johannes Zellner (johannes@@zellner.org),
5074 Pablo Averbuj (pablo@@averbuj.com).
5081 This manual describes version @value{version} of the @code{screen}
5082 program. Its roots are a merge of a custom version 2.3PR7 by Wayne
5083 Davison and several enhancements to Oliver Laumann's version 2.0.
5084 Note that all versions numbered 2.x are copyright by Oliver Laumann.
5086 See also @xref{Availability}.
5088 @node Bugs, Installation, Credits, Top
5092 Just like any other significant piece of software, @code{screen} has a
5093 few bugs and missing features. Please send in a bug report if you have
5094 found a bug not mentioned here.
5097 * Known Bugs:: Problems we know about.
5098 * Reporting Bugs:: How to contact the maintainers.
5099 * Availability:: Where to find the latest screen version.
5102 @node Known Bugs, Reporting Bugs, , Bugs
5107 @samp{dm} (delete mode) and @samp{xs} are not handled correctly (they
5108 are ignored). @samp{xn} is treated as a magic-margin indicator.
5111 @code{screen} has no clue about double-high or double-wide characters.
5112 But this is the only area where @code{vttest} is allowed to fail.
5115 It is not possible to change the environment variable @code{$TERMCAP}
5116 when reattaching under a different terminal type.
5119 The support of terminfo based systems is very limited. Adding extra
5120 capabilities to @code{$TERMCAP} may not have any effects.
5123 @code{screen} does not make use of hardware tabs.
5126 @code{screen} must be installed setuid root on most systems
5127 in order to be able to
5128 correctly change the owner of the tty device file for each window.
5129 Special permission may also be required to write the file
5133 Entries in @file{/etc/utmp} are not removed when @code{screen} is killed
5134 with SIGKILL. This will cause some programs (like "w" or "rwho") to
5135 advertise that a user is logged on who really isn't.
5138 @code{screen} may give a strange warning when your tty has no utmp
5142 When the modem line was hung up, @code{screen} may not automatically detach
5143 (or quit) unless the device driver sends a HANGUP signal. To detach such a
5144 @code{screen} session use the -D or -d command line option.
5147 If a password is set, the command line options -d and -D still detach a
5148 session without asking.
5151 Both @code{breaktype} and @code{defbreaktype} change the break generating
5152 method used by all terminal devices. The first should change a window
5153 specific setting, where the latter should change only the default for new
5157 When attaching to a multiuser session, the user's @file{.screenrc} file is not
5158 sourced. Each users personal settings have to be included in the
5159 @file{.screenrc} file from which the session is booted, or have to be
5163 A weird imagination is most useful to gain full advantage of all the
5167 @node Reporting Bugs, Availability, Known Bugs, Bugs
5168 @section Reporting Bugs
5171 If you find a bug in @code{Screen}, please send electronic mail to
5172 @w{@samp{screen@@uni-erlangen.de}}, and also to
5173 @w{@samp{bug-gnu-utils@@prep.ai.mit.edu}}. Include the version number
5174 of @code{Screen} which you are using. Also include in your message the
5175 hardware and operating system, the compiler used to compile, a
5176 description of the bug behavior, and the conditions that triggered the
5177 bug. Please recompile @code{screen} with the @samp{-DDEBUG} options
5178 enabled, reproduce the bug, and have a look at the debug output written to
5179 the directory @file{/tmp/debug}. If necessary quote suspect passages from the
5180 debug output and show the contents of your @file{config.h} if it matters.
5182 @node Availability, , Reporting Bugs, Bugs
5183 @section Availability
5184 @cindex availability
5186 @code{Screen} is available under the @code{GNU} copyleft.
5188 The latest official release of @code{screen} available via anonymous
5189 ftp from @samp{prep.ai.mit.edu}, @samp{nic.funet.fi} or any other
5190 @code{GNU} distribution site. The home site of
5191 @code{screen} is @samp{ftp.uni-erlangen.de
5192 (131.188.3.71)}, in the directory @file{pub/utilities/screen}.
5193 The subdirectory @samp{private} contains the latest beta testing release.
5194 If you want to help, send a note to screen@@uni-erlangen.de.
5196 @node Installation, Concept Index, Bugs, Top
5197 @chapter Installation
5198 @cindex installation
5200 Since @code{screen} uses pseudo-ttys, the select system call, and
5201 UNIX-domain sockets/named pipes, it will not run under a system that
5202 does not include these features of 4.2 and 4.3 BSD UNIX.
5205 * Socket Directory:: Where screen stores its handle.
5206 * Compiling Screen::
5209 @node Socket Directory,
5210 @section Socket Directory
5211 @cindex socket directory
5213 The socket directory defaults either to @file{$HOME/.screen} or simply to
5214 @file{/tmp/screens} or preferably to @file{/usr/local/screens} chosen at
5215 compile-time. If @code{screen} is installed
5216 setuid root, then the administrator should compile screen with an
5217 adequate (not NFS mounted) @code{SOCKDIR}. If @code{screen} is not
5218 running setuid-root, the user can specify any mode 700 directory in the
5219 environment variable @code{$SCREENDIR}.
5221 @node Compiling Screen, , Socket Directory, Installation
5222 @section Compiling Screen
5223 @cindex compiling screen
5225 To compile and install screen:
5227 The @code{screen} package comes with a @code{GNU Autoconf} configuration
5228 script. Before you compile the package run
5230 @center @code{sh ./configure}
5232 This will create a @file{config.h} and @file{Makefile} for your machine.
5233 If @code{configure} fails for some reason, then look at the examples and
5234 comments found in the @file{Makefile.in} and @file{config.h.in} templates.
5235 Rename @file{config.status} to @file{config.status.@var{machine}} when
5236 you want to keep configuration data for multiple architectures. Running
5237 @code{sh ./config.status.@var{machine}} recreates your configuration
5238 significantly faster than rerunning @code{configure}.
5240 Read through the "User Configuration" section of @file{config.h}, and verify
5241 that it suits your needs.
5242 A comment near the top of this section explains why it's best to
5243 install screen setuid to root.
5244 Check for the place for the global @file{screenrc}-file and for the socket
5247 Check the compiler used in @file{Makefile}, the prefix path where to install
5248 @code{screen}. Then run
5252 If @code{make} fails to produce one of the files @file{term.h}, @file{comm.h}
5253 or @file{tty.c}, then use @code{@var{filename.x}.dist} instead.
5254 For additional information about installation of @code{screen} refer to the
5255 file @file{INSTALLATION}, coming with this package.
5257 @node Concept Index, Command Index, Installation, Top
5258 @unnumbered Concept Index
5262 @node Command Index, Keystroke Index, Concept Index, Top
5263 @unnumbered Command Index
5265 This is a list of all the commands supported by @code{screen}.
5269 @node Keystroke Index, , Command Index, Top
5270 @unnumbered Keystroke Index
5272 This is a list of the default key bindings.
5274 The leading escape character (@pxref{Command Character}) has been omitted
5275 from the key sequences, since it is the same for all bindings.