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}.
1075 Reset the terminal settings for the window. @xref{Reset}.
1076 @item resize [(+/-)lines]
1077 Grow or shrink a region
1078 @item screen [@var{opts}] [@var{n}] [@var{cmd} [@var{args}]]
1079 Create a new window. @xref{Screen Command}.
1080 @item scrollback @var{num}
1081 Set size of scrollback buffer. @xref{Scrollback}.
1082 @item select [@var{n}]
1083 Switch to a specified window. @xref{Selecting}.
1084 @item sessionname [@var{name}]
1085 Name this session. @xref{Session Name}.
1086 @item setenv [@var{var} [@var{string}]]
1087 Set an environment variable for new windows. @xref{Setenv}.
1088 @item setsid @var{state}
1089 Controll process group creation for windows. @xref{Setsid}.
1090 @item shell @var{command}
1091 Set the default program for new windows. @xref{Shell}.
1092 @item shelltitle @var{title}
1093 Set the default name for new windows. @xref{Shell}.
1094 @item silence [@var{state}|@var{seconds}]
1095 Monitor a window for inactivity. @xref{Silence}.
1096 @item silencewait @var{seconds}
1097 Default timeout to trigger an inactivity notify. @xref{Silence}.
1098 @item sleep @var{num}
1099 Pause during startup. @xref{Startup}.
1100 @item slowpaste @var{msec}
1101 Slow down pasting in windows. @xref{Paste}.
1102 @item source @var{file}
1103 Run commands from a file. @xref{Source}.
1104 @item sorendition [@var{attr} [@var{color}]]
1105 Change text highlighting. @xref{Sorendition}.
1107 Split region into two parts. @xref{Regions}.
1108 @item startup_message @var{state}
1109 Display copyright notice on startup. @xref{Startup}.
1110 @item stuff @var{string}
1111 Stuff a string in the input buffer of a window. @xref{Paste}.
1112 @item su [@var{username} [@var{password} [@var{password2}]]]
1113 Identify a user. @xref{Multiuser Session}.
1115 Put session in background. @xref{Suspend}.
1116 @item term @var{term}
1117 Set @code{$TERM} for new windows. @xref{Term}.
1118 @item termcap @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1119 Tweak termcap entries for best performance. @xref{Termcap Syntax}.
1120 @item terminfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1121 Ditto, for terminfo systems. @xref{Termcap Syntax}.
1122 @item termcapinfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1123 Ditto, for both systems. @xref{Termcap Syntax}.
1124 @item time [@var{string}]
1125 Display time and load average. @xref{Time}.
1126 @item title [@var{windowtitle}]
1127 Set the name of the current window. @xref{Title Command}.
1128 @item umask [@var{users}]+/-@var{bits} ...
1129 Synonym to @code{aclumask}. @xref{Umask}.
1130 @item unsetenv @var{var}
1131 Unset environment variable for new windows. @xref{Setenv}.
1132 @item utf8 [@var{state} [@var{dstate}]]
1133 Select character encoding of the current window. @xref{Character Processing}.
1134 @item vbell [@var{state}]
1135 Use visual bell. @xref{Bell}.
1136 @item vbell_msg [@var{message}]
1137 Set vbell message. @xref{Bell}.
1138 @item vbellwait @var{sec}
1139 Set delay for vbell message. @xref{Bell}.
1141 Display @code{screen} version. @xref{Version}.
1142 @item wall @var{message}
1143 Write a message to all displays. @xref{Multiuser Session}.
1144 @item width [@var{cols} [@var{lines}]]
1145 Set the width of the window. @xref{Window Size}.
1146 @item windowlist [-b] | string [@var{string}] | title [@var{title}]
1147 Present a list of all windows for selection. @xref{Windowlist}.
1149 List active windows. @xref{Windows}.
1150 @item wrap [@var{state}]
1151 Control line-wrap behavior. @xref{Wrap}.
1152 @item writebuf [-e @var{encoding}] [@var{filename}]
1153 Write paste buffer to screen-exchange file. @xref{Screen Exchange}.
1154 @item writelock @var{on}|@var{off}|@var{auto}
1155 Grant exclusive write permission. @xref{Multiuser Session}.
1157 Send an XOFF character. @xref{XON/XOFF}.
1159 Send an XON character. @xref{XON/XOFF}.
1160 @item zmodem [off|auto|catch|pass]
1161 Define how screen treats zmodem requests. @xref{Zmodem}.
1162 @item zombie [@var{keys} [onerror] ]
1163 Keep dead windows. @xref{Zombie}.
1166 @node New Window, Selecting, Commands, Top
1169 This section describes the commands for creating a new window for
1170 running programs. When a new window is created, the first available
1171 number from the range 0@dots{}9 is assigned to it.
1172 The number of windows is limited at compile-time by the MAXWIN
1173 configuration parameter.
1176 * Chdir:: Change the working directory for new windows.
1177 * Screen Command:: Create a new window.
1178 * Setenv:: Set environment variables for new windows.
1179 * Shell:: Parameters for shell windows.
1180 * Term:: Set the terminal type for new windows.
1181 * Window Types:: Creating different types of windows.
1184 @node Chdir, Screen Command, , New Window
1186 @deffn Command chdir [directory]
1188 Change the current directory of @code{screen} to the specified directory
1189 or, if called without an argument, to your home directory (the value of
1190 the environment variable @code{$HOME}). All windows that are created by means
1191 of the @code{screen} command from within @file{.screenrc} or by means of
1192 @kbd{C-a : screen @dots{}} or @kbd{C-a c} use this as their default
1193 directory. Without a @code{chdir} command, this would be the directory
1194 from which @code{screen} was invoked. Hardcopy and log files are always
1195 written to the @emph{window's} default directory, @emph{not} the current
1196 directory of the process running in the window. You can use this
1197 command multiple times in your @file{.screenrc} to start various windows
1198 in different default directories, but the last @code{chdir} value will
1199 affect all the windows you create interactively.
1202 @node Screen Command, Setenv, Chdir, New Window
1203 @section Screen Command
1206 @deffn Command screen [opts] [n] [cmd [args]]
1207 (@kbd{C-a c}, @kbd{C-a C-c})@*
1208 Establish a new window. The flow-control options (@samp{-f}, @samp{-fn}
1209 and @samp{-fa}), title option (@samp{-t}), login options
1210 (@samp{-l} and @samp{-ln}) , terminal type option (@samp{-T @var{term}}),
1211 the all-capability-flag (@samp{-a}) and scrollback option
1212 (@samp{-h @var{num}}) may be specified with each command.
1213 The option (@samp{-M}) turns monitoring on for this window.
1214 The option (@samp{-L}) turns output logging on for this window.
1215 If an optional number @var{n} in the range 0@dots{}9 is given,
1216 the window number @var{n} is assigned to the newly created window (or,
1217 if this number is already in-use, the next available number). If a
1218 command is specified after @code{screen}, this command (with the given
1219 arguments) is started in the window; otherwise, a shell is created.
1221 Screen has built in some functionality of @samp{cu} and @samp{telnet}.
1222 @xref{Window Types}.
1225 Thus, if your @file{.screenrc} contains the lines
1228 # example for .screenrc:
1230 screen -fn -t foobar 2 -L telnet foobar
1234 @code{screen} creates a shell window (in window #1) and a window with a
1235 TELNET connection to the machine foobar (with no flow-control using the
1236 title @samp{foobar} in window #2) and will write a logfile @samp{screenlog.2}
1237 of the telnet session. If you do not include any
1238 @code{screen} commands in your @file{.screenrc} file, then @code{screen}
1239 defaults to creating a single shell window, number zero. When the
1240 initialization is completed, @code{screen} switches to the last window
1241 specified in your .screenrc file or, if none, it opens default window
1244 @node Setenv, Shell, Screen Command, New Window
1246 @deffn Command setenv var string
1248 Set the environment variable @var{var} to value @var{string}.
1249 If only @var{var} is specified, the user will be prompted to enter a value.
1250 If no parameters are specified, the user will be prompted for both variable
1251 and value. The environment is inherited by all subsequently forked shells.
1254 @deffn Command unsetenv var
1256 Unset an environment variable.
1259 @node Shell, Term, Setenv, New Window
1261 @deffn Command shell command
1262 @deffnx Command defshell command
1264 Set the command to be used to create a new shell. This overrides the
1265 value of the environment variable @code{$SHELL}. This is useful if
1266 you'd like to run a tty-enhancer which is expecting to execute the
1267 program specified in @code{$SHELL}. If the command begins with
1268 a @samp{-} character, the shell will be started as a login-shell.
1270 @code{defshell} is currently a synonym to the @code{shell} command.
1273 @deffn Command shelltitle title
1275 Set the title for all shells created during startup or by the C-a C-c
1276 command. @xref{Naming Windows}, for details about what titles are.
1279 @node Term, Window Types , Shell, New Window
1281 @deffn Command term term
1283 In each window @code{screen} opens, it sets the @code{$TERM}
1284 variable to @code{screen} by default, unless no description for
1285 @code{screen} is installed in the local termcap or terminfo data base.
1286 In that case it pretends that the terminal emulator is @samp{vt100}.
1287 This won't do much harm, as @code{screen} is VT100/ANSI compatible. The
1288 use of the @code{term} command is discouraged for non-default purpose.
1289 That is, one may want to specify special @code{$TERM} settings (e.g. vt100) for
1290 the next @code{screen rlogin othermachine} command. Use the command
1291 @code{screen -T vt100 rlogin othermachine} rather than setting
1292 and resetting the default.
1295 @node Window Types, , Term, New Window
1296 @section Window Types
1297 @cindex window types
1298 Screen provides three different window types. New windows are created
1299 with @code{screen}'s @samp{screen} command (@pxref{Screen Command}).
1300 The first parameter to the @samp{screen} command defines which
1301 type of window is created. The different window types are all
1302 special cases of the normal type. They have been added in order
1303 to allow @code{screen} to be used efficiently as a console
1304 with 100 or more windows.
1307 The normal window contains a shell (default, if no parameter is given)
1308 or any other system command that could be executed from a shell.
1309 (e.g. @samp{slogin}, etc...).
1312 If a tty (character special device) name (e.g. @samp{/dev/ttya})
1313 is specified as the first parameter, then the window is directly
1314 connected to this device.
1315 This window type is similar to @samp{screen cu -l /dev/ttya}.
1316 Read and write access is required on the device node,
1317 an exclusive open is attempted on the node to mark the connection line
1319 An optional parameter is allowed consisting of a comma separated
1320 list of flags in the notation used by @samp{stty(1)}:
1323 Usually 300, 1200, 9600 or 19200. This affects transmission as well as
1326 Specify the transmission of eight (or seven) bits per byte.
1328 Enables (or disables) software flow-control (CTRL-S/CTRL-Q) for sending
1330 @item ixoff or -ixoff
1331 Enables (or disables) software flow-control for receiving data.
1332 @item istrip or -istrip
1333 Clear (or keep) the eight bit in each received byte.
1336 You may want to specify as many of these options as applicable.
1337 Unspecified options cause the terminal driver to make up the parameter
1338 values of the connection. These values are system-dependent and may be
1339 in defaults or values saved from a previous connection.
1341 For tty windows, the @code{info} command shows some of the modem
1342 control lines in the status line.
1343 These may include @samp{RTS}, @samp{CTS}, @samp{DTR}, @samp{CD} and
1344 more. This depends rather on on the available @code{ioctl()}'s and system
1345 header files than on the physical capabilities of the serial board.
1346 The name of a logical low (inactive) signal is preceded by an
1347 exclamation mark (@samp{!}), otherwise the signal is logical high (active).
1348 Unsupported but shown signals are usually shown low.
1349 When the @code{CLOCAL} status bit is true, the whole set of modem signals is
1350 placed inside curly braces (@samp{@{} and @samp{@}}).
1351 When the @code{CRTSCTS} or @code{TIOCSOFTCAR} bit is true, the signals
1352 @samp{CTS} or @samp{CD} are shown in parenthesis, respectively.
1354 For tty windows, the command @code{break} causes the Data transmission
1355 line (TxD) to go low for a specified period of time. This is expected
1356 to be interpreted as break signal on the other side.
1357 No data is sent and no modem control line is changed when a
1358 @code{break} is issued.
1361 If the first parameter is @code{//telnet}, the second parameter is
1362 expected to be a host name, and an optional third parameter may specify
1363 a TCP port number (default decimal 23). Screen will connect to a
1364 server listening on the remote host and use the telnet protocol to
1365 communicate with that server.
1367 For telnet windows, the command @code{info} shows details about
1368 the connection in square brackets (@samp{[} and @samp{]}) at the end of
1372 BINARY. The connection is in binary mode.
1374 ECHO. Local echo is disabled.
1376 SGA. The connection is in `character mode' (default: `line mode').
1378 TTYPE. The terminal type has been requested by the remote host. Screen
1379 sends the name @code{screen} unless instructed otherwise (see also the
1380 command @samp{term}).
1382 NAWS. The remote site is notified about window size changes.
1384 LFLOW. The remote host will send flow control information.
1385 (Ignored at the moment.)
1387 Additional flags for debugging are @samp{x}, @samp{t} and @samp{n}
1388 (XDISPLOC, TSPEED and NEWENV).
1390 For telnet windows, the command @code{break} sends the telnet code
1391 @code{IAC BREAK} (decimal 243) to the remote host.
1395 @node Selecting, Session Management, New Window, Top
1396 @chapter Selecting a Window
1398 This section describes the commands for switching between windows in an
1399 @code{screen} session. The windows are numbered from 0 to 9, and are created
1400 in that order by default (@pxref{New Window}).
1403 * Next and Previous:: Forward or back one window.
1404 * Other Window:: Switch back and forth between two windows.
1405 * Select:: Switch to a window (and to one after @code{kill}).
1406 * Windowlist:: Present a list of all windows for selection.
1409 @node Next and Previous, Other Window, , Selecting
1410 @section Moving Back and Forth
1415 (@kbd{C-a @key{SPC}}, @kbd{C-a n}, @kbd{C-a C-n})@*
1416 Switch to the next window. This command can be used repeatedly to
1417 cycle through the list of windows. (On some terminals, C-@key{SPC}
1418 generates a NUL character, so you must release the control key before
1425 (@kbd{C-a p}, @kbd{C-a C-p})@*
1426 Switch to the previous window (the opposite of @kbd{C-a n}).
1429 @node Other Window, Select, Next and Previous, Selecting
1430 @section Other Window
1432 @deffn Command other
1434 Switch to the last window displayed. Note that this command
1435 defaults to the command character typed twice, unless overridden.
1436 For instance, if you use the option @samp{-e]x},
1437 this command becomes @kbd{]]} (@pxref{Command Character}).
1440 @node Select, Windowlist, Other Window, Selecting
1444 @deffn Command select [n]
1445 (@kbd{C-a @var{n}}, @kbd{C-a '})@*
1446 Switch to the window with the number @var{n}.
1447 If no window number is specified, you get prompted for an
1448 identifier. This can be a window name (title) or a number.
1449 When a new window is established, the lowest available number
1450 is assigned to this window.
1451 Thus, the first window can be activated by @code{select 0}; there
1452 can be no more than 10 windows present simultaneously (unless screen is
1453 compiled with a higher MAXWIN setting).
1454 There are two special arguments, @code{select -} switches to the
1455 internal blank window and @code{select .} switches to the
1456 current window. The latter is useful if used with screen's
1461 @node Windowlist, , Select, Selecting
1464 @deffn Command windowlist [-b] [-m]
1465 @deffnx Command windowlist string [@var{string}]
1466 @deffnx Command windowlist title [@var{title}]
1468 Display all windows in a table for visual window selection.
1469 The desired window can be selected via the standard
1470 movement keys (@pxref{Movement}) and activated via
1471 the return key. If the @code{-b} option is given, screen will
1472 switch to the blank window before presenting the list, so
1473 that the current window is also selectable.
1474 The @code{-m} option changes the order of the windows, instead of
1475 sorting by window numbers screen uses its internal most-recently-used
1478 The table format can be changed with the string and title
1479 option, the title is displayed as table heading, while the
1480 lines are made by using the string setting. The default
1481 setting is @samp{Num Name%=Flags} for the title and
1482 @samp{%3n %t%=%f} for the lines. See the string escapes chapter
1483 (@pxref{String Escapes}) for more codes (e.g. color settings).
1487 @node Session Management, Regions, Selecting, Top
1488 @chapter Session Management Commands
1490 Perhaps the most useful feature of @code{screen} is the way it allows
1491 the user to move a session between terminals, by detaching and
1492 reattaching. This also makes life easier for modem users who have to
1493 deal with unexpected loss of carrier.
1496 * Detach:: Disconnect @code{screen} from your terminal.
1497 * Power Detach:: Detach and log out.
1498 * Lock:: Lock your terminal temporarily.
1499 * Multiuser Session:: Changing number of allowed users.
1500 * Session Name:: Rename your session for later reattachment.
1501 * Suspend:: Suspend your session.
1502 * Quit:: Terminate your session.
1505 @node Detach, Power Detach, , Session Management
1508 @deffn Command autodetach state
1510 Sets whether @code{screen} will automatically detach upon hangup, which
1511 saves all your running programs until they are resumed with a
1512 @code{screen -r} command. When turned off, a hangup signal will
1513 terminate @code{screen} and all the processes it contains. Autodetach is
1519 @deffn Command detach
1520 (@kbd{C-a d}, @kbd{C-a C-d})@*
1521 Detach the @code{screen} session (disconnect it from the terminal and
1522 put it into the background). A detached @code{screen} can be resumed by
1523 invoking @code{screen} with the @code{-r} option (@pxref{Invoking
1525 The @code{-h} option tells screen to immediately close the connection
1526 to the terminal (@samp{hangup}).
1529 @deffn Command password [crypted_pw]
1531 Present a crypted password in your @file{.screenrc} file and screen will
1532 ask for it, whenever someone attempts to resume a detached session. This
1533 is useful, if you have privileged programs running under @code{screen}
1534 and you want to protect your session from reattach attempts by users
1535 that managed to assume your uid. (I.e. any superuser.) If no crypted
1536 password is specified, screen prompts twice a password and places its
1537 encryption in the paste buffer. Default is `none', which disables
1541 @node Power Detach, Lock, Detach, Session Management
1542 @section Power Detach
1545 @deffn Command pow_detach
1547 Mainly the same as @code{detach}, but also sends a HANGUP signal
1548 to the parent process of @code{screen}.@*
1549 @emph{Caution}: This will result in a
1550 logout if @code{screen} was started from your login shell.
1553 @deffn Command pow_detach_msg [message]
1555 The @var{message} specified here is output whenever a power detach is
1556 performed. It may be used as a replacement for a logout message or to reset
1558 Without parameter, the current message is shown.
1561 @node Lock, Multiuser Session, Power Detach, Session Management
1565 @deffn Command lockscreen
1566 (@kbd{C-a x}, @kbd{C-a C-x})@*
1567 Call a screenlock program (@file{/local/bin/lck} or @file{/usr/bin/lock}
1568 or a builtin, if no other is available). Screen does not accept any
1569 command keys until this program terminates. Meanwhile processes in the
1570 windows may continue, as the windows are in the detached state.
1571 The screenlock program may be changed through the environment variable
1572 @code{$LOCKPRG} (which must be set in the shell from which @code{screen}
1573 is started) and is executed with the user's uid and gid.
1575 Warning: When you leave other shells unlocked and have no password set
1576 on @code{screen}, the lock is void: One could easily re-attach from an
1577 unlocked shell. This feature should rather be called
1578 @code{lockterminal}.
1581 @node Multiuser Session, Session Name, Lock, Session Management
1582 @section Multiuser Session
1583 @cindex multiuser session
1585 These commands allow other users to gain access to one single @code{screen}
1586 session. When attaching to a multiuser @code{screen} the sessionname is
1587 specified as @code{username/sessionname} to the @code{-S} command line option.
1588 @code{Screen} must be compiled with multiuser support to enable features
1592 * Multiuser:: Enable / Disable multiuser mode.
1593 * Acladd:: Enable a specific user.
1594 * Aclchg:: Change a users permissions.
1595 * Acldel:: Disable a specific user.
1596 * Aclgrp:: Grant a user permissions to other users.
1597 * Displays:: List all active users at their displays.
1598 * Umask:: Predefine access to new windows.
1599 * Wall:: Write a message to all users.
1600 * Writelock:: Grant exclusive window access.
1601 * Su:: Substitute user.
1604 @node Multiuser, Acladd, , Multiuser Session
1605 @subsection Multiuser
1606 @deffn Command multiuser @var{state}
1608 Switch between single-user and multi-user mode. Standard screen operation is
1609 single-user. In multi-user mode the commands @code{acladd}, @code{aclchg} and
1610 @code{acldel} can be used to enable (and disable) other users accessing this
1614 @node Acladd, Aclchg, Multiuser, Multiuser Session
1616 @deffn Command acladd @var{usernames}
1617 @deffnx Command addacl @var{usernames}
1619 Enable users to fully access this screen session. @var{Usernames} can be one
1620 user or a comma separated list of users. This command enables to attach to
1621 the @code{screen} session and performs the equivalent of
1622 @code{aclchg @var{usernames} +rwx "#?"}. To add a user with restricted access,
1623 use the @code{aclchg} command below.
1624 @code{Addacl} is a synonym to @code{acladd}.
1625 Multi-user mode only.
1628 @node Aclchg, Acldel, Acladd, Multiuser Session
1630 @deffn Command aclchg @var{usernames permbits list}
1631 @deffnx Command chacl @var{usernames permbits list}
1633 Change permissions for a comma separated list of users.
1634 Permission bits are represented as @samp{r}, @samp{w} and @samp{x}.
1635 Prefixing @samp{+} grants the permission, @samp{-} removes it. The third
1636 parameter is a comma separated list of commands or windows (specified either
1637 by number or title). The special list @samp{#} refers to all windows, @samp{?}
1638 to all commands. If @var{usernames} consists of a single @samp{*}, all
1639 known users are affected.
1640 A command can be executed when the user has the @samp{x} bit for it. The user
1641 can type input to a window when he has its @samp{w} bit set and no other
1642 user obtains a writelock for this window. Other bits are currently ignored.
1643 To withdraw the writelock from another user in e.g. window 2:
1644 @samp{aclchg @var{username} -w+w 2}. To allow read-only access
1645 to the session: @samp{aclchg @var{username} -w "#"}. As soon as a user's name
1646 is known to screen, he can attach to the session and (per default) has full
1647 permissions for all command and windows. Execution permission for the acl
1648 commands, @code{at} and others should also be removed or the user may be able
1649 to regain write permission.
1650 @code{Chacl} is a synonym to @code{aclchg}.
1651 Multi-user mode only.
1654 @node Acldel, Aclgrp, Aclchg, Multiuser Session
1656 @deffn Command acldel @var{username}
1658 Remove a user from screen's access control list. If currently attached, all the
1659 user's displays are detached from the session. He cannot attach again.
1660 Multi-user mode only.
1663 @node Aclgrp, Displays, Acldel, Multiuser Session
1665 @deffn Command aclgrp @var{username} [@var{groupname}]
1667 Creates groups of users that share common access rights. The
1668 name of the group is the username of the group leader. Each
1669 member of the group inherits the permissions that are
1670 granted to the group leader. That means, if a user fails an
1671 access check, another check is made for the group leader.
1672 A user is removed from all groups the special value @samp{none}
1673 is used for @var{groupname}. If the second parameter is omitted
1674 all groups the user is in are listed.
1677 @node Displays, Umask, Aclgrp, Multiuser Session
1678 @subsection Displays
1680 @deffn Command displays
1682 Shows a tabular listing of all currently connected user
1683 front-ends (displays). This is most useful for multiuser
1687 @node Umask, Wall, Displays, Multiuser Session
1688 @subsection aclumask
1689 @deffn Command aclumask [@var{users}]+/-@var{bits} ...
1690 @deffnx Command umask [@var{users}]+/-@var{bits} ...
1692 This specifies the access other users have to windows that
1693 will be created by the caller of the command. @var{Users} may be no,
1694 one or a comma separated list of known usernames. If no users are
1695 specified, a list of all currently known users is assumed.
1696 @var{Bits} is any combination of access control bits allowed
1697 defined with the @code{aclchg} command. The special username @samp{?}
1698 predefines the access that not yet known users will be
1699 granted to any window initially. The special username @samp{??}
1700 predefines the access that not yet known users are granted
1701 to any command. Rights of the special username nobody cannot
1702 be changed (see the @code{su} command).
1703 @code{Umask} is a synonym to @code{aclumask}.
1707 @node Wall, Writelock, Umask, Multiuser Session
1709 @deffn Command wall @var{message}
1711 Write a message to all displays. The message will appear in the terminal's
1715 @node Writelock, Su , Wall, Multiuser Session
1716 @subsection Writelock
1717 @deffn Command writelock @var{on|off|auto}
1719 In addition to access control lists, not all users may be able to write to
1720 the same window at once. Per default, writelock is in @samp{auto} mode and
1721 grants exclusive input permission to the user who is the first to switch
1722 to the particular window. When he leaves the window, other users may obtain
1723 the writelock (automatically). The writelock of the current window is disabled
1724 by the command @code{writelock off}. If the user issues the command
1725 @code{writelock on} he keeps the exclusive write permission while switching
1729 @deffn Command defwritelock @var{on|off|auto}
1731 Sets the default writelock behavior for new windows. Initially all windows
1732 will be created with no writelocks.
1735 @node Su, , Writelock, Multiuser Session
1737 @deffn Command su [@var{username} [@var{password} [@var{password2}]]]
1739 Substitute the user of a display. The command prompts for
1740 all parameters that are omitted. If passwords are specified
1741 as parameters, they have to be specified un-crypted. The
1742 first password is matched against the systems passwd database,
1743 the second password is matched against the @code{screen}
1744 password as set with the commands @code{acladd} or @code{password}.
1745 @code{Su} may be useful for the @code{screen} administrator to test
1747 When the identification fails, the user has
1748 access to the commands available for user @samp{nobody}. These are
1749 @code{detach}, @code{license}, @code{version}, @code{help} and
1753 @node Session Name, Suspend, Multiuser Session, Session Management
1754 @section Session Name
1755 @deffn Command sessionname [@var{name}]
1757 Rename the current session. Note that for @code{screen -list} the name
1758 shows up with the process-id prepended. If the argument @var{name} is
1759 omitted, the name of this session is displayed.@*
1760 @emph{Caution}: The @code{$STY}
1761 environment variable still reflects the old name. This may result in
1762 confusion. The default is constructed from the tty and host names.
1765 @node Suspend, Quit, Session Name, Session Management
1769 @deffn Command suspend
1770 (@kbd{C-a z}, @kbd{C-a C-z})@*
1771 Suspend @code{screen}. The windows are in the detached state while
1772 @code{screen} is suspended. This feature relies on the parent shell
1773 being able to do job control.
1776 @node Quit, , Suspend, Session Management
1781 Kill all windows and terminate @code{screen}. Note that on VT100-style
1782 terminals the keys @kbd{C-4} and @kbd{C-\} are identical. So be careful
1783 not to type @kbd{C-a C-4} when selecting window no. 4. Use the empty
1784 bind command (as in @code{bind "^\"}) to remove a key binding
1785 (@pxref{Key Binding}).
1788 @node Regions, Window Settings, Session Management, Top
1791 Screen has the ability to display more than one window on the
1792 user's display. This is done by splitting the screen in regions,
1793 which can contain different windows.
1796 * Split:: Split a region into two
1797 * Focus:: Change to the next region
1798 * Only:: Delete all other regions
1799 * Remove:: Delete the current region
1800 * Resize:: Grow or shrink a region
1801 * Caption:: Control the window's caption
1802 * Fit:: Resize a window to fit the region
1805 @node Split, Focus, , Regions
1808 @deffn Command split
1810 Split the current region into two new ones. All regions on the
1811 display are resized to make room for the new region. The blank
1812 window is displayed on the new region.
1815 @node Focus, Only, Split, Regions
1818 @deffn Command focus
1819 (@kbd{C-a @key{Tab}})@*
1820 Move the input focus to the next region. This is done in a cyclic
1821 way so that the top region is selected after the bottom one. If
1822 no subcommand is given it defaults to `down'. `up' cycles in the
1823 opposite order, `top' and `bottom' go to the top and bottom
1824 region respectively. Useful bindings are (j and k as in vi)
1833 @node Only, Remove, Focus, Regions
1838 Kill all regions but the current one.
1841 @node Remove, Resize, Only, Regions
1844 @deffn Command remove
1846 Kill the current region. This is a no-op if there is only one region.
1849 @node Resize, Caption, Remove, Regions
1851 @deffn Command resize [(+/-)@var{lines}]
1853 Resize the current region. The space will be removed from or added to
1854 the region below or if there's not enough space from the region above.
1856 resize +N increase current region height by N
1857 resize -N decrease current region height by N
1858 resize N set current region height to N
1859 resize = make all windows equally high
1860 resize max maximize current region height
1861 resize min minimize current region height
1865 @node Caption, Fit, Resize, Regions
1867 @deffn Command caption @code{always}|@code{splitonly} [string]
1868 @deffnx Command caption @code{string} [string]
1870 This command controls the display of the window captions. Normally
1871 a caption is only used if more than one window is shown on the
1872 display (split screen mode). But if the type is set to
1873 @code{always}, @code{screen} shows a caption
1874 even if only one window is displayed. The default
1875 is @samp{splitonly}.
1877 The second form changes the text used for the caption. You can use
1878 all string escapes (@pxref{String Escapes}). @code{Screen} uses
1879 a default of @samp{%3n %t}.
1881 You can mix both forms by providing the string as an additional
1885 @node Fit, , Caption, Regions
1890 Change the window size to the size of the current region. This
1891 command is needed because screen doesn't adapt the window size
1892 automatically if the window is displayed more than once.
1895 @node Window Settings, Virtual Terminal, Regions, Top
1896 @chapter Window Settings
1898 These commands control the way @code{screen} treats individual windows
1899 in a session. @xref{Virtual Terminal}, for commands to control the
1900 terminal emulation itself.
1903 * Naming Windows:: Control the name of the window
1904 * Console:: See the host's console messages
1905 * Kill:: Destroy an unwanted window
1906 * Login:: Control @file{/etc/utmp} logging
1907 * Mode:: Control the file mode of the pty
1908 * Monitor:: Watch for activity in a window
1909 * Windows:: List the active windows
1910 * Hardstatus:: Set a window's hardstatus line
1913 @node Naming Windows, Console, , Window Settings
1914 @section Naming Windows (Titles)
1917 You can customize each window's name in the window display (viewed with
1918 the @code{windows} command (@pxref{Windows}) by setting it with
1919 one of the title commands. Normally the name displayed is the actual
1920 command name of the program created in the window. However, it is
1921 sometimes useful to distinguish various programs of the same name or to
1922 change the name on-the-fly to reflect the current state of the window.
1924 The default name for all shell windows can be set with the
1925 @code{shelltitle} command (@pxref{Shell}). You can specify the name you
1926 want for a window with the @samp{-t} option to the @code{screen} command
1927 when the window is created (@pxref{Screen Command}). To change the name after
1928 the window has been created you can use the title-string escape-sequence
1929 (@kbd{@key{ESC} k @var{name} @key{ESC} \}) and the @code{title} command
1930 (C-a A). The former can be output from an application to control the
1931 window's name under software control, and the latter will prompt for a
1932 name when typed. You can also bind predefined names to keys with the
1933 @code{title} command to set things quickly without prompting.
1936 * Title Command:: The @code{title} command.
1937 * Dynamic Titles:: Make shell windows change titles dynamically.
1938 * Title Prompts:: Set up your shell prompt for dynamic Titles.
1939 * Title Screenrc:: Set up Titles in your @file{.screenrc}.
1942 @node Title Command, Dynamic Titles, , Naming Windows
1943 @subsection Title Command
1945 @deffn Command title [windowtitle]
1947 Set the name of the current window to @var{windowtitle}. If no name is
1948 specified, screen prompts for one.
1951 @node Dynamic Titles, Title Prompts, Title Command, Naming Windows
1952 @subsection Dynamic Titles
1953 @code{screen} has a shell-specific heuristic that is enabled by
1954 setting the window's name to @var{search|name} and arranging to have a
1955 null title escape-sequence output as a part of your prompt. The
1956 @var{search} portion specifies an end-of-prompt search string, while the
1957 @var{name} portion specifies the default shell name for the window. If
1958 the @var{name} ends in a @samp{:} @code{screen} will add what it
1959 believes to be the current command running in the window to the end of
1960 the specified name (e.g. @var{name:cmd}). Otherwise the current
1961 command name supersedes the shell name while it is running.
1963 Here's how it works: you must modify your shell prompt to output a null
1964 title-escape-sequence (@key{ESC} k @key{ESC} \) as a part of your prompt.
1965 The last part of your prompt must be the same as the string you
1966 specified for the @var{search} portion of the title. Once this is set
1967 up, @code{screen} will use the title-escape-sequence to clear the previous
1968 command name and get ready for the next command. Then, when a newline
1969 is received from the shell, a search is made for the end of the prompt.
1970 If found, it will grab the first word after the matched string and use
1971 it as the command name. If the command name begins with @samp{!},
1972 @samp{%}, or @samp{^}, @code{screen} will use the first word on the
1973 following line (if found) in preference to the just-found name. This
1974 helps csh users get more accurate titles when using job control or
1975 history recall commands.
1977 @node Title Prompts, Title Screenrc, Dynamic Titles, Naming Windows
1978 @subsection Setting up your prompt for shell titles
1979 One thing to keep in mind when adding a null title-escape-sequence to your
1980 prompt is that some shells (like the csh) count all the non-control
1981 characters as part of the prompt's length. If these invisible
1982 characters aren't a multiple of 8 then backspacing over a tab will
1983 result in an incorrect display. One way to get around this is to use a
1987 set prompt='@value{esc}[0000m@value{esc}k@value{esc}\% '
1990 The escape-sequence @samp{@value{esc}[0000m} not only normalizes the
1991 character attributes, but all the zeros round the length of the
1992 invisible characters up to 8.
1994 Tcsh handles escape codes in the prompt more intelligently, so you can
1995 specify your prompt like this:
1998 set prompt="%@{\ek\e\\%@}\% "
2001 Bash users will probably want to echo the escape sequence in the
2005 PROMPT_COMMAND='echo -n -e "\033k\033\134"'
2008 (I used @samp{\134} to output a @samp{\} because of a bug in v1.04).
2010 @node Title Screenrc, , Title Prompts, Naming Windows
2011 @subsection Setting up shell titles in your @file{.screenrc}
2012 Here are some .screenrc examples:
2015 screen -t top 2 nice top
2018 Adding this line to your .screenrc would start a niced version of the
2019 @code{top} command in window 2 named @samp{top} rather than @samp{nice}.
2026 This file would start a shell using the given shelltitle. The title
2027 specified is an auto-title that would expect the prompt and the typed
2028 command to look something like the following:
2031 /usr/joe/src/dir> trn
2034 (it looks after the '> ' for the command name).
2035 The window status would show the name @samp{trn} while the command was
2036 running, and revert to @samp{csh} upon completion.
2039 bind R screen -t '% |root:' su
2042 Having this command in your .screenrc would bind the key sequence
2043 @kbd{C-a R} to the @code{su} command and give it an auto-title name of
2044 @samp{root:}. For this auto-title to work, the screen could look
2045 something like this:
2052 Here the user typed the csh history command @code{!em} which ran the
2053 previously entered @code{emacs} command. The window status would show
2054 @samp{root:emacs} during the execution of the command, and revert to
2055 simply @samp{root:} at its completion.
2060 bind u title (unknown)
2063 The first binding doesn't have any arguments, so it would prompt you for
2064 a title when you type @kbd{C-a o}. The second binding would clear an
2065 auto-titles current setting (C-a E). The third binding would set the
2066 current window's title to @samp{(unknown)} (C-a u).
2068 @node Console, Kill, Naming Windows, Window Settings
2070 @deffn Command console [@var{state}]
2072 Grabs or un-grabs the machines console output to a window. When the argument
2073 is omitted the current state is displayed.
2074 @emph{Note}: Only the owner of @file{/dev/console} can grab the console
2075 output. This command is only available if the host supports the ioctl
2079 @node Kill, Login, Console, Window Settings
2085 (@kbd{C-a k}, @kbd{C-a C-k})@*
2086 Kill the current window.@*
2087 If there is an @code{exec} command running (@pxref{Exec}) then it is killed.
2088 Otherwise the process (e.g. shell) running in the window receives a
2089 @code{HANGUP} condition,
2090 the window structure is removed and screen (your display) switches to another
2091 window. When the last window is destroyed, @code{screen} exits.
2092 After a kill screen switches to the previously displayed window.
2094 @emph{Caution}: @code{emacs} users may find themselves killing their
2095 @code{emacs} session when trying to delete the current line. For this
2096 reason, it is probably wise to use a different command character
2097 (@pxref{Command Character}) or rebind @code{kill} to another key
2098 sequence, such as @kbd{C-a K} (@pxref{Key Binding}).
2101 @node Login, Mode, Kill, Window Settings
2104 @deffn Command deflogin state
2106 Same as the @code{login} command except that the default setting for new
2107 windows is changed. This defaults to `on' unless otherwise specified at
2108 compile time (@pxref{Installation}). Both commands are only present when
2109 @code{screen} has been compiled with utmp support.
2113 @deffn Command login [state]
2115 Adds or removes the entry in @file{/etc/utmp} for the current window.
2116 This controls whether or not the window is @dfn{logged in}. In addition
2117 to this toggle, it is convenient to have ``log in'' and ``log out''
2118 keys. For instance, @code{bind I login on} and @code{bind O
2119 login off} will map these keys to be @kbd{C-a I} and @kbd{C-a O}
2120 (@pxref{Key Binding}).
2123 @node Mode, Monitor, Login, Window Settings
2125 @deffn Command defmode mode
2127 The mode of each newly allocated pseudo-tty is set to @var{mode}.
2128 @var{mode} is an octal number as used by chmod(1). Defaults to 0622 for
2129 windows which are logged in, 0600 for others (e.g. when @code{-ln} was
2130 specified for creation, @pxref{Screen Command}).
2133 @node Monitor, Windows, Mode, Window Settings
2136 @deffn Command activity message
2138 When any activity occurs in a background window that is being monitored,
2139 @code{screen} displays a notification in the message line. The
2140 notification message can be redefined by means of the @code{activity}
2141 command. Each occurrence of @samp{%} in @var{message} is replaced by
2142 the number of the window in which activity has occurred, and each
2143 occurrence of @samp{^G} is replaced by the definition for bell in your
2144 termcap (usually an audible bell). The default message is
2147 'Activity in window %n'
2150 Note that monitoring is off for all windows by default, but can be altered
2151 by use of the @code{monitor} command (@kbd{C-a M}).
2154 @deffn Command defmonitor state
2156 Same as the @code{monitor} command except that the default setting for
2157 new windows is changed. Initial setting is `off'.
2161 @deffn Command monitor [state]
2163 Toggles monitoring of the current window. When monitoring is turned on
2164 and the affected window is switched into the background, the activity
2165 notification message will be displayed in the status line at the first
2166 sign of output, and the window will also be marked with an @samp{@@} in
2167 the window-status display (@pxref{Windows}). Monitoring defaults to
2168 @samp{off} for all windows.
2171 @node Windows, Hardstatus, Monitor, Window Settings
2175 @deffn Command windows
2176 (@kbd{C-a w}, @kbd{C-a C-w})@*
2177 Uses the message line to display a list of all the windows. Each
2178 window is listed by number with the name of the program running in the
2179 window (or its title).
2181 The current window is marked with a @samp{*};
2182 the previous window is marked with a @samp{-};
2183 all the windows that are logged in are marked with a @samp{$} (@pxref{Login});
2184 a background window that has received a bell is marked with a @samp{!};
2185 a background window that is being monitored and has had activity occur is
2186 marked with an @samp{@@} (@pxref{Monitor});
2187 a window which has output logging turned on is marked with @samp{(L)};
2188 windows occupied by other users are marked with @samp{&}
2189 or @samp{&&} if the window is shared by other users;
2190 windows in the zombie state are marked with @samp{Z}.
2192 If this list is too long to fit on the terminal's status line only the
2193 portion around the current window is displayed.
2196 @node Hardstatus, , Windows, Window Settings
2199 @code{Screen} maintains a hardstatus line for every window. If a window
2200 gets selected, the display's hardstatus will be updated to match
2201 the window's hardstatus line.
2202 The hardstatus line can be changed with the ANSI Application
2203 Program Command (APC): @samp{ESC_<string>ESC\}. As a convenience
2204 for xterm users the sequence @samp{ESC]0..2;<string>^G} is
2207 @deffn Command defhstatus [status]
2209 The hardstatus line that all new windows will get is set to
2211 This command is useful to make the hardstatus of every window
2212 display the window number or title or the like. @var{status}
2213 may contain the same directives as in the window messages, but
2214 the directive escape character is @samp{^E} (octal 005) instead
2215 of @samp{%}. This was done to make a misinterpretation of program
2216 generated hardstatus lines impossible.
2217 If the parameter @var{status}
2218 is omitted, the current default string is displayed.
2219 Per default the hardstatus line of new windows is empty.
2222 @deffn Command hstatus status
2224 Changes the current window's hardstatus line to @var{status}.
2227 @node Virtual Terminal, Copy and Paste, Window Settings, Top
2228 @chapter Virtual Terminal
2230 Each window in a @code{screen} session emulates a VT100 terminal, with
2231 some extra functions added. The VT100 emulator is hard-coded, no other
2232 terminal types can be emulated.
2233 The commands described here modify the terminal emulation.
2236 * Control Sequences:: Details of the internal VT100 emulation.
2237 * Input Translation:: How keystrokes are remapped.
2238 * Digraph:: Entering digraph sequences.
2239 * Bell:: Getting your attention.
2240 * Clear:: Clear the window display.
2241 * Info:: Terminal emulation statistics.
2242 * Redisplay:: When the display gets confusing.
2243 * Wrap:: Automatic margins.
2244 * Reset:: Recovering from ill-behaved applications.
2245 * Window Size:: Changing the size of your terminal.
2246 * Character Processing:: Change the effect of special characters.
2249 @node Control Sequences, Input Translation, , Virtual Terminal
2250 @section Control Sequences
2251 @cindex control sequences
2252 The following is a list of control sequences recognized by
2253 @code{screen}. @samp{(V)} and @samp{(A)} indicate VT100-specific and
2254 ANSI- or ISO-specific functions, respectively.
2260 ESC H Horizontal Tab Set
2261 ESC Z Send VT100 Identification String
2262 ESC 7 (V) Save Cursor and Attributes
2263 ESC 8 (V) Restore Cursor and Attributes
2264 ESC [s (A) Save Cursor and Attributes
2265 ESC [u (A) Restore Cursor and Attributes
2266 ESC c Reset to Initial State
2268 ESC Pn p Cursor Visibility (97801)
2271 ESC = (V) Application Keypad Mode
2272 ESC > (V) Numeric Keypad Mode
2273 ESC # 8 (V) Fill Screen with E's
2274 ESC \ (A) String Terminator
2275 ESC ^ (A) Privacy Message String (Message Line)
2276 ESC ! Global Message String (Message Line)
2277 ESC k Title Definition String
2278 ESC P (A) Device Control String
2279 Outputs a string directly to the host
2280 terminal without interpretation.
2281 ESC _ (A) Application Program Command (Hardstatus)
2282 ESC ] 0 ; string ^G (A) Operating System Command (Hardstatus, xterm
2284 ESC ] 83 ; cmd ^G (A) Execute screen command. This only works if
2285 multi-user support is compiled into screen.
2286 The pseudo-user ":window:" is used to check
2287 the access control list. Use "addacl :window:
2288 -rwx #?" to create a user with no rights and
2289 allow only the needed commands.
2290 Control-N (A) Lock Shift G1 (SO)
2291 Control-O (A) Lock Shift G0 (SI)
2292 ESC n (A) Lock Shift G2
2293 ESC o (A) Lock Shift G3
2294 ESC N (A) Single Shift G2
2295 ESC O (A) Single Shift G3
2296 ESC ( Pcs (A) Designate character set as G0
2297 ESC ) Pcs (A) Designate character set as G1
2298 ESC * Pcs (A) Designate character set as G2
2299 ESC + Pcs (A) Designate character set as G3
2300 ESC [ Pn ; Pn H Direct Cursor Addressing
2301 ESC [ Pn ; Pn f same as above
2302 ESC [ Pn J Erase in Display
2303 Pn = None or 0 From Cursor to End of Screen
2304 1 From Beginning of Screen to Cursor
2306 ESC [ Pn K Erase in Line
2307 Pn = None or 0 From Cursor to End of Line
2308 1 From Beginning of Line to Cursor
2310 ESC [ Pn X Erase character
2311 ESC [ Pn A Cursor Up
2312 ESC [ Pn B Cursor Down
2313 ESC [ Pn C Cursor Right
2314 ESC [ Pn D Cursor Left
2315 ESC [ Pn E Cursor next line
2316 ESC [ Pn F Cursor previous line
2317 ESC [ Pn G Cursor horizontal position
2318 ESC [ Pn ` same as above
2319 ESC [ Pn d Cursor vertical position
2320 ESC [ Ps ;...; Ps m Select Graphic Rendition
2321 Ps = None or 0 Default Rendition
2324 3 (A) @i{Standout} Mode (ANSI: Italicized)
2328 22 (A) Normal Intensity
2329 23 (A) @i{Standout} Mode off (ANSI: Italicized off)
2330 24 (A) Not Underlined
2332 27 (A) Positive Image
2333 30 (A) Foreground Black
2334 31 (A) Foreground Red
2335 32 (A) Foreground Green
2336 33 (A) Foreground Yellow
2337 34 (A) Foreground Blue
2338 35 (A) Foreground Magenta
2339 36 (A) Foreground Cyan
2340 37 (A) Foreground White
2341 39 (A) Foreground Default
2342 40 (A) Background Black
2344 49 (A) Background Default
2345 ESC [ Pn g Tab Clear
2346 Pn = None or 0 Clear Tab at Current Position
2348 ESC [ Pn ; Pn r (V) Set Scrolling Region
2349 ESC [ Pn I (A) Horizontal Tab
2350 ESC [ Pn Z (A) Backward Tab
2351 ESC [ Pn L (A) Insert Line
2352 ESC [ Pn M (A) Delete Line
2353 ESC [ Pn @@ (A) Insert Character
2354 ESC [ Pn P (A) Delete Character
2355 ESC [ Pn S Scroll Scrolling Region Up
2356 ESC [ Pn T Scroll Scrolling Region Down
2357 ESC [ Pn ^ same as above
2358 ESC [ Ps ;...; Ps h Set Mode
2359 ESC [ Ps ;...; Ps l Reset Mode
2360 Ps = 4 (A) Insert Mode
2361 20 (A) @samp{Automatic Linefeed} Mode.
2362 34 Normal Cursor Visibility
2363 ?1 (V) Application Cursor Keys
2364 ?3 (V) Change Terminal Width to 132 columns
2365 ?5 (V) Reverse Video
2366 ?6 (V) @samp{Origin} Mode
2367 ?7 (V) @samp{Wrap} Mode
2368 ?9 X10 mouse tracking
2369 ?25 (V) Visible Cursor
2370 ?47 Alternate Screen (old xterm code)
2371 ?1000 (V) VT200 mouse tracking
2372 ?1047 Alternate Screen (new xterm code)
2373 ?1049 Alternate Screen (new xterm code)
2374 ESC [ 5 i (A) Start relay to printer (ANSI Media Copy)
2375 ESC [ 4 i (A) Stop relay to printer (ANSI Media Copy)
2376 ESC [ 8 ; Ph ; Pw t Resize the window to @samp{Ph} lines and
2377 @samp{Pw} columns (SunView special)
2378 ESC [ c Send VT100 Identification String
2379 ESC [ x (V) Send Terminal Parameter Report
2380 ESC [ > c Send Secondary Device Attributes String
2381 ESC [ 6 n Send Cursor Position Report
2386 @node Input Translation, Digraph, Control Sequences, Virtual Terminal
2387 @section Input Translation
2388 @cindex input translation
2389 In order to do a full VT100 emulation @code{screen} has to detect
2390 that a sequence of characters in the input stream was generated
2391 by a keypress on the user's keyboard and insert the VT100
2392 style escape sequence. @code{Screen} has a very flexible way of doing
2393 this by making it possible to map arbitrary commands on arbitrary
2394 sequences of characters. For standard VT100 emulation the command
2395 will always insert a string in the input buffer of the window
2396 (see also command @code{stuff}, @pxref{Paste}).
2397 Because the sequences generated by a keypress can
2398 change after a reattach from a different terminal type, it is
2399 possible to bind commands to the termcap name of the keys.
2400 @code{Screen} will insert the correct binding after each
2401 reattach. See @ref{Bindkey} for further details on the syntax and examples.
2403 Here is the table of the default key bindings. (A) means that the
2404 command is executed if the keyboard is switched into application
2408 Key name Termcap name Command
2409 -----------------------------------------------------
2410 Cursor up ku stuff \033[A
2412 Cursor down kd stuff \033[B
2414 Cursor right kr stuff \033[C
2416 Cursor left kl stuff \033[D
2418 Function key 0 k0 stuff \033[10~
2419 Function key 1 k1 stuff \033OP
2420 Function key 2 k2 stuff \033OQ
2421 Function key 3 k3 stuff \033OR
2422 Function key 4 k4 stuff \033OS
2423 Function key 5 k5 stuff \033[15~
2424 Function key 6 k6 stuff \033[17~
2425 Function key 7 k7 stuff \033[18~
2426 Function key 8 k8 stuff \033[19~
2427 Function key 9 k9 stuff \033[20~
2428 Function key 10 k; stuff \033[21~
2429 Function key 11 F1 stuff \033[23~
2430 Function key 12 F2 stuff \033[24~
2431 Home kh stuff \033[1~
2432 End kH stuff \033[4~
2433 Insert kI stuff \033[2~
2434 Delete kD stuff \033[3~
2435 Page up kP stuff \033[5~
2436 Page down kN stuff \033[6~
2471 Keypad enter fe stuff \015
2475 @node Digraph, Bell, Input Translation, Virtual Terminal
2479 @deffn Command digraph [preset]
2481 This command prompts the user for a digraph sequence. The next
2482 two characters typed are looked up in a builtin table and the
2483 resulting character is inserted in the input stream. For example,
2484 if the user enters @samp{a"}, an a-umlaut will be inserted. If the
2485 first character entered is a 0 (zero), @code{screen}
2486 will treat the following characters (up to three) as an octal
2487 number instead. The optional argument @var{preset}
2488 is treated as user input, thus one can create an "umlaut" key.
2489 For example the command @samp{bindkey ^K digraph '"'} enables the user
2490 to generate an a-umlaut by typing @samp{CTRL-K a}.
2493 @node Bell, Clear, Digraph, Virtual Terminal
2496 @deffn Command bell_msg [message]
2498 When a bell character is sent to a background window, @code{screen}
2499 displays a notification in the message line. The notification message
2500 can be re-defined by this command. Each occurrence
2501 of @samp{%} in @var{message} is replaced by the number of the window to
2502 which a bell has been sent, and each occurrence of @samp{^G} is replaced
2503 by the definition for bell in your termcap (usually an audible bell).
2504 The default message is
2510 An empty message can be supplied to the @code{bell_msg} command to suppress
2511 output of a message line (@code{bell_msg ""}).
2512 Without parameter, the current message is shown.
2516 @deffn Command vbell [state]
2518 Sets or toggles the visual bell setting for the current window. If
2519 @code{vbell} is switched to @samp{on}, but your
2520 terminal does not support a visual bell, the visual bell message is
2521 displayed in the status line when the bell character is received.
2522 Visual bell support of a terminal is
2523 defined by the termcap variable @code{vb}. @xref{Bell, , Visual Bell,
2524 termcap, The Termcap Manual}, for more information on visual bells.
2525 The equivalent terminfo capability is @code{flash}.
2527 Per default, @code{vbell} is @samp{off}, thus the audible bell is used.
2530 @deffn Command vbell_msg [message]
2532 Sets the visual bell message. @var{Message} is printed to the status
2533 line if the window receives a bell character (^G), @code{vbell} is
2534 set to @samp{on} and the terminal does not support a visual bell.
2535 The default message is @samp{Wuff, Wuff!!}.
2536 Without parameter, the current message is shown.
2539 @deffn Command vbellwait sec
2541 Define a delay in seconds after each display of @code{screen} 's visual
2542 bell message. The default is 1 second.
2545 @node Clear, Info, Bell, Virtual Terminal
2548 @deffn Command clear
2550 Clears the screen and saves its contents to the scrollback buffer.
2553 @node Info, Redisplay, Clear, Virtual Terminal
2558 (@kbd{C-a i}, @kbd{C-a C-i})@*
2559 Uses the message line to display some information about the current
2560 window: the cursor position in the form @samp{(@var{column},@var{row})}
2561 starting with @samp{(1,1)}, the terminal width and height plus the size
2562 of the scrollback buffer in lines, like in @samp{(80,24)+50},
2563 the current state of window XON/XOFF flow control is shown like this
2564 (@pxref{Flow Control}):
2566 +flow automatic flow control, currently on.
2567 -flow automatic flow control, currently off.
2568 +(+)flow flow control enabled. Agrees with automatic control.
2569 -(+)flow flow control disabled. Disagrees with automatic control.
2570 +(-)flow flow control enabled. Disagrees with automatic control.
2571 -(-)flow flow control disabled. Agrees with automatic control.
2574 The current line wrap setting (@samp{+wrap} indicates enabled, @samp{-wrap}
2575 not) is also shown. The flags @samp{ins}, @samp{org}, @samp{app}, @samp{log},
2576 @samp{mon} and @samp{nored} are displayed when the window is in insert mode,
2577 origin mode, application-keypad mode, has output logging,
2578 activity monitoring or partial redraw enabled.
2580 The currently active
2581 character set (@samp{G0}, @samp{G1}, @samp{G2}, or @samp{G3}), and in
2582 square brackets the terminal character sets that are currently
2583 designated as @samp{G0} through @samp{G3}.
2584 If the window is in UTF-8 mode, the string @samp{UTF-8} is shown instead.
2585 Additional modes depending on the type of the window are displayed at
2586 the end of the status line (@pxref{Window Types}).
2588 If the state machine of the terminal emulator is in a non-default state,
2589 the info line is started with a string identifying the current state.
2591 For system information use @code{time}.
2594 @deffn Command dinfo
2596 Show what screen thinks about your terminal. Useful if you want to know
2597 why features like color or the alternate charset don't work.
2600 @node Redisplay, Wrap, Info, Virtual Terminal
2603 @deffn Command allpartial state
2605 If set to on, only the current cursor line is refreshed on window change.
2606 This affects all windows and is useful for slow terminal lines. The
2607 previous setting of full/partial refresh for each window is restored
2608 with @code{allpartial off}. This is a global flag that immediately takes effect
2609 on all windows overriding the @code{partial} settings. It does not change the
2610 default redraw behavior of newly created windows.
2613 @deffn Command altscreen state
2615 If set to on, "alternate screen" support is enabled in virtual terminals,
2616 just like in xterm. Initial setting is @samp{off}.
2619 @deffn Command partial state
2621 Defines whether the display should be refreshed (as with
2622 @code{redisplay}) after switching to the current window. This command
2623 only affects the current window. To immediately affect all windows use the
2624 @code{allpartial} command. Default is @samp{off}, of course. This default is
2625 fixed, as there is currently no @code{defpartial} command.
2630 @deffn Command redisplay
2631 (@kbd{C-a l}, @kbd{C-a C-l})@*
2632 Redisplay the current window. Needed to get a full redisplay in
2633 partial redraw mode.
2636 @node Wrap, Reset, Redisplay, Virtual Terminal
2641 @deffn Command wrap state
2642 (@kbd{C-a r}, @kbd{C-a C-r}) @*
2643 Sets the line-wrap setting for the current window. When line-wrap is
2644 on, the second consecutive printable character output at the last column
2645 of a line will wrap to the start of the following line. As an added
2646 feature, backspace (^H) will also wrap through the left margin to the
2647 previous line. Default is @samp{on}.
2650 @deffn Command defwrap state
2652 Same as the @code{wrap} command except that the default setting for new
2653 windows is changed. Initially line-wrap is on and can be toggled with the
2654 @code{wrap} command (@kbd{C-a r}) or by means of "C-a : wrap on|off".
2657 @node Reset, Window Size, Wrap, Virtual Terminal
2660 @deffn Command reset
2662 Reset the virtual terminal to its ``power-on'' values. Useful when strange
2663 settings (like scroll regions or graphics character set) are left over from
2667 @node Window Size, Character Processing, Reset, Virtual Terminal
2668 @section Window Size
2670 @deffn Command width [@code{-w}|@code{-d}] [cols [lines]]
2672 Toggle the window width between 80 and 132 columns, or set it to
2673 @var{cols} columns if an argument is specified. This requires a
2674 capable terminal and the termcap entries @samp{Z0} and @samp{Z1}. See
2675 the @code{termcap} command (@pxref{Termcap}), for more information.
2676 You can also specify a height if you want to
2677 change both values. The @code{-w} option tells screen to leave
2678 the display size unchanged and just set the window size,
2679 @code{-d} vice versa.
2682 @deffn Command height [@code{-w}|@code{-d}] [lines [cols]]
2684 Set the display height to a specified number of lines. When no
2685 argument is given it toggles between 24 and 42 lines display.
2688 @node Character Processing, ,Window Size, Virtual Terminal
2689 @section Character Processing
2691 @deffn Command c1 [state]
2693 Change c1 code processing. @samp{c1 on} tells screen to treat
2694 the input characters between 128 and 159 as control functions.
2695 Such an 8-bit code is normally the same as ESC followed by the
2696 corresponding 7-bit code. The default setting is to process c1
2697 codes and can be changed with the @samp{defc1} command.
2698 Users with fonts that have usable characters in the
2699 c1 positions may want to turn this off.
2702 @deffn Command gr [state]
2704 Turn GR charset switching on/off. Whenever screen sees an input
2705 char with an 8th bit set, it will use the charset stored in the
2706 GR slot and print the character with the 8th bit stripped. The
2707 default (see also @samp{defgr}) is not to process GR switching because
2708 otherwise the ISO88591 charset would not work.
2711 @deffn Command bce [state]
2713 Change background-color-erase setting. If @samp{bce} is set to
2714 on, all characters cleared by an erase/insert/scroll/clear
2715 operation will be displayed in the current background color.
2716 Otherwise the default background color is used.
2719 @deffn Command encoding enc [denc]
2721 Tell screen how to interpret the input/output. The first argument
2722 sets the encoding of the current window.
2723 Each window can emulate a different encoding. The optional second
2724 parameter overwrites the encoding of the connected terminal.
2725 It should never be needed as screen uses the locale setting to detect
2727 There is also a way to select a terminal encoding depending on
2728 the terminal type by using the @samp{KJ} termcap entry. @xref{Special Capabilities}.
2730 Supported encodings are
2731 @code{eucJP}, @code{SJIS}, @code{eucKR},
2732 @code{eucCN}, @code{Big5}, @code{GBK}, @code{KOI8-R}, @code{CP1251},
2733 @code{UTF-8}, @code{ISO8859-2}, @code{ISO8859-3},
2734 @code{ISO8859-4}, @code{ISO8859-5}, @code{ISO8859-6},
2735 @code{ISO8859-7}, @code{ISO8859-8}, @code{ISO8859-9},
2736 @code{ISO8859-10}, @code{ISO8859-15}, @code{jis}.
2738 See also @samp{defencoding}, which changes the default setting of a new
2742 @deffn Command charset set
2744 Change the current character set slot designation and charset
2745 mapping. The first four character of @var{set}
2746 are treated as charset designators while the fifth and sixth
2747 character must be in range @samp{0} to @samp{3} and set the GL/GR
2748 charset mapping. On every position a @samp{.} may be used to indicate
2749 that the corresponding charset/mapping should not be changed
2750 (@var{set} is padded to six characters internally by appending
2751 @samp{.} chars). New windows have @samp{BBBB02} as default
2752 charset, unless a @samp{encoding} command is active.
2754 The current setting can be viewed with the @ref{Info} command.
2757 @deffn Command utf8 [state [dstate]]
2759 Change the encoding used in the current window. If utf8 is enabled, the
2760 strings sent to the window will be UTF-8 encoded and vice versa.
2762 parameter toggles the setting. If a second parameter is given, the
2764 encoding is also changed (this should rather be done with screen's
2766 See also @samp{defutf8}, which changes the default setting of a new
2770 @deffn Command defc1 state
2772 Same as the @samp{c1} command except that the default setting for
2773 new windows is changed. Initial setting is @samp{on}.
2776 @deffn Command defgr state
2778 Same as the @samp{gr} command except that the default setting for
2779 new windows is changed. Initial setting is @samp{off}.
2782 @deffn Command defbce state
2784 Same as the @samp{bce} command except that the default setting for
2785 new windows is changed. Initial setting is @samp{off}.
2788 @deffn Command defencoding enc
2790 Same as the @samp{encoding} command except that the default setting for
2791 new windows is changed. Initial setting is the encoding taken from the
2795 @deffn Command defcharset [set]
2796 Like the @samp{charset} command except that the default setting for
2797 new windows is changed. Shows current default if called without
2801 @deffn Command defutf8 state
2803 Same as the @samp{utf8} command except that the default setting for new
2804 windows is changed. Initial setting is @code{on} if screen was started
2805 with @samp{-U}, otherwise @code{off}.
2808 @node Copy and Paste, Subprocess Execution, Virtual Terminal, Top
2809 @chapter Copy and Paste
2810 @cindex copy and paste
2812 For those confined to a hardware terminal, these commands provide a cut
2813 and paste facility more powerful than those provided by most windowing
2817 * Copy:: Copy from scrollback to buffer
2818 * Paste:: Paste from buffer into window
2819 * Registers:: Longer-term storage
2820 * Screen Exchange:: Sharing data between screen users
2821 * History:: Recalling previous input
2824 @node Copy, Paste, , Copy and Paste
2832 (@kbd{C-a [}, @kbd{C-a C-[}, @kbd{C-a @key{ESC}})@*
2833 Enter copy/scrollback mode. This allows you to copy text from the
2834 current window and its history into the paste buffer. In this mode a
2835 @code{vi}-like full screen editor is active, with controls as
2840 * Line Termination:: End copied lines with CR/LF
2841 * Scrollback:: Set the size of the scrollback buffer
2842 * Copy Mode Keys:: Remap keys in copy mode
2843 * Movement:: Move around in the scrollback buffer
2844 * Marking:: Select the text you want
2845 * Repeat count:: Repeat a command
2846 * Searching:: Find the text you want
2847 * Specials:: Other random keys
2850 @node Line Termination, Scrollback, , Copy
2852 @deffn Command crlf [state]
2854 This affects the copying of text regions with the @kbd{C-a [} command.
2855 If it is set to @samp{on}, lines will be separated by the two character
2856 sequence @samp{CR}/@samp{LF}. Otherwise only @samp{LF} is used.
2857 @code{crlf} is off by default.
2858 When no parameter is given, the state is toggled.
2861 @node Scrollback, Copy Mode Keys, Line Termination, Copy
2862 @subsection Scrollback
2863 @deffn Command defscrollback num
2865 Same as the @code{scrollback} command except that the default setting
2866 for new windows is changed. Defaults to 100.
2869 @deffn Command scrollback num
2871 Set the size of the scrollback buffer for the current window to
2872 @var{num} lines. The default scrollback is 100 lines. Use @kbd{C-a i}
2873 to view the current setting.
2876 @deffn Command compacthist [state]
2878 This tells screen whether to suppress trailing blank lines when
2879 scrolling up text into the history buffer. Turn compacting @samp{on}
2880 to hold more useful lines in your scrollback buffer.
2883 @node Copy Mode Keys, Movement, Scrollback, Copy
2884 @subsection markkeys
2885 @deffn Command markkeys string
2887 This is a method of changing the keymap used for copy/history mode. The
2888 string is made up of @var{oldchar}=@var{newchar} pairs which are
2889 separated by @samp{:}. Example: The command @code{markkeys
2890 h=^B:l=^F:$=^E} would set some keys to be more familiar to @code{emacs}
2892 If your terminal sends characters, that cause you to abort copy mode,
2893 then this command may help by binding these characters to do nothing.
2894 The no-op character is `@@' and is used like this: @code{markkeys @@=L=H}
2895 if you do not want to use the `H' or `L' commands any longer.
2896 As shown in this example, multiple keys can be assigned to one function
2897 in a single statement.
2900 @node Movement, Marking, Copy Mode Keys, Copy
2901 @subsection Movement Keys
2904 @kbd{h}, @kbd{j}, @kbd{k}, @kbd{l} move the cursor line by line or
2908 @kbd{0}, @kbd{^} and @kbd{$} move to the leftmost column or to the first
2909 or last non-whitespace character on the line.
2912 @kbd{H}, @kbd{M} and @kbd{L} move the cursor to the leftmost column
2913 of the top, center or bottom line of the window.
2916 @kbd{+} and @kbd{-} move the cursor to the leftmost column of the next
2920 @kbd{G} moves to the specified absolute line (default: end of buffer).
2923 @kbd{|} moves to the specified absolute column.
2926 @kbd{w}, @kbd{b}, @kbd{e} move the cursor word by word.
2929 @kbd{B}, @kbd{E} move the cursor WORD by WORD (as in vi).
2932 @kbd{C-u} and @kbd{C-d} scroll the display up/down by the specified
2933 amount of lines while preserving the cursor position. (Default: half
2937 @kbd{C-b} and @kbd{C-f} move the cursor up/down a full screen.
2940 @kbd{g} moves to the beginning of the buffer.
2943 @kbd{%} jumps to the specified percentage of the buffer.
2945 Note that Emacs-style movement keys can be specified by a .screenrc
2946 command. (@code{markkeys "h=^B:l=^F:$=^E"}) There is no simple method for
2947 a full emacs-style keymap, however, as this involves multi-character codes.
2949 @node Marking, Repeat count, Movement, Copy
2952 The copy range is specified by setting two marks. The text between these
2953 marks will be highlighted. Press @kbd{space} to set the first or second
2957 @kbd{Y} and @kbd{y} can be used to mark one whole line or to mark from
2961 @kbd{W} marks exactly one word.
2963 @node Repeat count, Searching, Marking, Copy
2964 @subsection Repeat Count
2966 Any command in copy mode can be prefixed with a number (by pressing
2967 digits @kbd{0@dots{}9}) which is taken as a repeat count. Example:
2968 @kbd{C-a C-[ H 10 j 5 Y} will copy lines 11 to 15 into the paste buffer.
2970 @node Searching, Specials, Repeat count, Copy
2971 @subsection Searching
2974 @kbd{/} @code{vi}-like search forward.
2977 @kbd{?} @code{vi}-like search backward.
2980 @kbd{C-a s} @code{emacs} style incremental search forward.
2983 @kbd{C-r} @code{emacs} style reverse i-search.
2985 @deffn Command ignorecase [state]
2987 Tell screen to ignore the case of characters in searches. Default is
2991 @node Specials, , Searching, Copy
2992 @subsection Specials
2994 There are, however, some keys that act differently here from in
2995 @code{vi}. @code{Vi} does not allow to yank rectangular blocks of text,
2996 but @code{screen} does. Press
2999 @kbd{c} or @kbd{C} to set the left or right margin respectively. If no
3000 repeat count is given, both default to the current cursor position.@*
3001 Example: Try this on a rather full text screen:
3002 @kbd{C-a [ M 20 l SPACE c 10 l 5 j C SPACE}.
3005 This moves one to the middle line of the screen, moves in 20 columns left,
3006 marks the beginning of the paste buffer, sets the left column, moves 5 columns
3007 down, sets the right column, and then marks the end of
3008 the paste buffer. Now try:@*
3009 @kbd{C-a [ M 20 l SPACE 10 l 5 j SPACE}
3012 and notice the difference in the amount of text copied.
3015 @kbd{J} joins lines. It toggles between 4 modes: lines separated by a
3016 newline character (012), lines glued seamless, lines separated by a single
3017 space or comma separated lines. Note that you can prepend the newline
3018 character with a carriage return character, by issuing a @code{set crlf
3022 @kbd{v} is for all the @code{vi} users who use @code{:set numbers} - it
3023 toggles the left margin between column 9 and 1.
3026 @kbd{a} before the final space key turns on append mode. Thus
3027 the contents of the paste buffer will not be overwritten, but appended to.
3030 @kbd{A} turns on append mode and sets a (second) mark.
3033 @kbd{>} sets the (second) mark and writes the contents of the paste buffer
3034 to the screen-exchange file (@file{/tmp/screen-exchange} per default)
3035 once copy-mode is finished. @xref{Screen Exchange}.@*
3036 This example demonstrates how to dump the
3037 whole scrollback buffer to that file: @*@kbd{C-a [ g SPACE G $ >}.
3040 @kbd{C-g} gives information about the current line and column.
3043 @kbd{x} exchanges the first mark and the current cursor position. You
3044 can use this to adjust an already placed mark.
3047 @kbd{@@} does nothing. Absolutely nothing. Does not even exit copy
3051 All keys not described here exit copy mode.
3053 @node Paste, Registers, Copy, Copy and Paste
3058 @deffn Command paste [registers [destination]]
3059 (@kbd{C-a ]}, @kbd{C-a C-]})@*
3060 Write the (concatenated) contents of the specified registers to the stdin
3061 stream of the current window. The register @samp{.} is treated as the
3062 paste buffer. If no parameter is specified the user is prompted to enter a
3063 single register. The paste buffer can be filled with the
3064 @code{copy}, @code{history} and @code{readbuf} commands.
3065 Other registers can be filled with the @code{register}, @code{readreg} and
3066 @code{paste} commands.
3067 If @code{paste} is called with a second argument, the contents of the specified
3068 registers is pasted into the named destination register rather than
3069 the window. If @samp{.} is used as the second argument, the display's paste
3070 buffer is the destination.
3071 Note, that @code{paste} uses a wide variety of resources: Usually both, a
3072 current window and a current display are required. But whenever a second
3073 argument is specified no current window is needed. When the source specification
3074 only contains registers (not the paste buffer) then there need not be a current
3075 display (terminal attached), as the registers are a global resource. The
3076 paste buffer exists once for every user.
3079 @deffn Command stuff string
3081 Stuff the string @var{string} in the input buffer of the current window.
3082 This is like the @code{paste} command, but with much less overhead.
3083 You cannot paste large buffers with the @code{stuff} command. It is most
3084 useful for key bindings. @xref{Bindkey}.
3087 @deffn Command pastefont [state]
3088 Tell screen to include font information in the paste buffer. The
3089 default is not to do so. This command is especially useful for
3090 multi character fonts like kanji.
3093 @deffn Command slowpaste msec
3094 @deffnx Command defslowpaste msec
3096 Define the speed text is inserted in the current window by the @code{paste}
3097 command. If the slowpaste value is nonzero text is written character by
3099 @code{screen} will pause for @var{msec} milliseconds after each write
3100 to allow the application to process the input. only use @code{slowpaste} if
3101 your underlying system exposes flow control problems while pasting large
3103 @code{defslowpaste} specifies the default for new windows.
3106 @deffn Command readreg [-e encoding] [register [filename]]
3108 Does one of two things, dependent on number of arguments: with zero or one
3109 arguments it it duplicates the paste buffer contents into the register specified
3110 or entered at the prompt. With two arguments it reads the contents of the named
3111 file into the register, just as @code{readbuf} reads the screen-exchange file
3112 into the paste buffer.
3113 You can tell screen the encoding of the file via the @code{-e} option.
3114 The following example will paste the system's password file into
3115 the screen window (using register p, where a copy remains):
3118 C-a : readreg p /etc/passwd
3123 @node Registers, Screen Exchange, Paste, Copy and Paste
3126 @deffn Command copy_reg [key]
3128 Removed. Use @code{readreg} instead.
3131 @deffn Command ins_reg [key]
3133 Removed. Use @code{paste} instead.
3136 @deffn Command process [key]
3138 Stuff the contents of the specified register into the @code{screen}
3139 input queue. If no argument is given you are prompted for a
3140 register name. The text is parsed as if it had been typed in from the user's
3141 keyboard. This command can be used to bind multiple actions to a single key.
3144 @deffn Command register [-e encoding] key string
3146 Save the specified @var{string} to the register @var{key}.
3147 The encoding of the string can be specified via the @code{-e} option.
3150 @node Screen Exchange, History, Registers, Copy and Paste
3151 @section Screen Exchange
3153 @deffn Command bufferfile [@var{exchange-file}]
3155 Change the filename used for reading and writing with the paste buffer.
3156 If the @var{exchange-file} parameter is omitted, @code{screen} reverts
3157 to the default of @file{/tmp/screen-exchange}. The following example
3158 will paste the system's password file into the screen window (using the
3159 paste buffer, where a copy remains):
3162 C-a : bufferfile /etc/passwd
3169 @deffn Command readbuf [-e @var{encoding}] [@var{filename}]
3171 Reads the contents of the specified file into the paste buffer.
3172 You can tell screen the encoding of the file via the @code{-e} option.
3173 If no file is specified, the screen-exchange filename is used.
3177 @deffn Command removebuf
3179 Unlinks the screen-exchange file.
3183 @deffn Command writebuf [-e @var{encoding}] [@var{filename}]
3185 Writes the contents of the paste buffer to the specified file, or the
3186 public accessible screen-exchange file if no filename is given.
3187 This is thought of as a primitive means of
3188 communication between @code{screen} users on the same host.
3189 If an encoding is specified the paste buffer is recoded on the fly to
3192 @kbd{C-a @key{ESC}} (@pxref{Copy}).
3195 @node History, , Screen Exchange, Copy and Paste
3199 @deffn Command history
3201 Usually users work with a shell that allows easy access to previous
3202 commands. For example, @code{csh} has the command @code{!!} to repeat
3203 the last command executed. @code{screen} provides a primitive way of
3204 recalling ``the command that started @dots{}'': You just type the first
3205 letter of that command, then hit @kbd{C-a @{} and @code{screen} tries to
3206 find a previous line that matches with the prompt character to the left
3207 of the cursor. This line is pasted into this window's input queue. Thus
3208 you have a crude command history (made up by the visible window and its
3212 @node Subprocess Execution, Key Binding, Copy and Paste, Top
3213 @chapter Subprocess Execution
3214 Control Input or Output of a window by another filter process.
3218 * Exec:: The @code{exec} command syntax.
3219 * Using Exec:: Weird things that filters can do.
3222 @node Exec, Using Exec, , Subprocess Execution
3224 @deffn Command exec [[@var{fdpat}] @var{newcommand} [@var{args} ... ]]
3226 Run a unix subprocess (specified by an executable path @var{newcommand} and
3227 its optional arguments) in the current window. The flow of data between
3228 newcommands stdin/stdout/stderr, the process originally started (let us call it
3229 "application-process") and
3230 screen itself (window) is controlled by the file descriptor pattern @var{fdpat}.
3231 This pattern is basically a three character sequence representing stdin, stdout
3232 and stderr of newcommand. A dot (@code{.}) connects the file descriptor
3233 to screen. An exclamation mark (@code{!}) causes the file descriptor to be
3234 connected to the application-process. A colon (@code{:}) combines both.
3236 User input will go to newcommand unless newcommand receives the
3237 application-process'
3238 output (@var{fdpat}s first character is @samp{!} or @samp{:}) or a pipe symbol
3239 (@samp{|}) is added to the end of @var{fdpat}.
3241 Invoking @code{exec} without arguments shows name and arguments of the currently
3242 running subprocess in this window. Only one subprocess can be running per
3245 When a subprocess is running the @code{kill} command will affect it instead of
3246 the windows process. Only one subprocess a time can be running in each window.
3248 Refer to the postscript file @file{doc/fdpat.ps} for a confusing
3249 illustration of all 21 possible combinations. Each drawing shows the digits
3250 2, 1, 0 representing the three file descriptors of newcommand. The box
3251 marked `W' is usual pty that has the application-process on its slave side.
3252 The box marked `P' is the secondary pty that now has screen at its master
3256 @node Using Exec, , Exec, Subprocess Execution
3263 Whitespace between the word @samp{exec} and @var{fdpat} and the command name
3267 Trailing dots and a @var{fdpat} consisting only of dots can be omitted.
3270 A simple @samp{|} is synonymous for the @samp{!..|} pattern.
3273 The word @samp{exec} can be omitted when the @samp{|} abbreviation is used.
3276 The word @samp{exec} can always be replaced by leading @samp{!}.
3285 @itemx exec ... /bin/sh
3286 All of the above are equivalent.
3287 Creates another shell in the same window, while the original shell is still
3288 running. Output of both shells is displayed and user input is sent to the new
3292 @itemx exec!stty 19200
3293 @itemx exec !.. stty 19200
3294 All of the above are equivalent.
3295 Set the speed of the window's tty. If your stty command operates on stdout,
3296 then add another @samp{!}. This is a useful command, when a screen window
3297 is directly connected to a serial line that needs to be configured.
3300 @itemx exec !..| less
3301 Both are equivalent.
3302 This adds a pager to the window output. The special character @samp{|} is
3303 needed to give the user control over the pager although it gets its input from
3304 the window's process. This works, because @samp{less} listens on stderr
3305 (a behavior that @code{screen} would not expect without the @samp{|})
3306 when its stdin is not a tty. @code{Less} versions newer than 177 fail miserably
3307 here; good old @code{pg} still works.
3309 @item !:sed -n s/.*Error.*/\007/p
3310 Sends window output to both, the user and the sed command. The sed inserts an
3311 additional bell character (oct. 007) to the window output seen by screen.
3312 This will cause 'Bell in window x' messages, whenever the string @samp{Error}
3313 appears in the window.
3316 @node Key Binding, Flow Control, Subprocess Execution, Top
3317 @chapter Key Binding
3321 You may disagree with some of the default bindings (I know I do). The
3322 @code{bind} command allows you to redefine them to suit your
3326 * Bind:: @code{bind} syntax.
3327 * Bind Examples:: Using @code{bind}.
3328 * Command Character:: The character used to start keyboard commands.
3329 * Help:: Show current key bindings.
3330 * Bindkey:: @code{bindkey} syntax.
3331 * Bindkey Examples:: Some easy examples.
3332 * Bindkey Control:: How to control the bindkey mechanism.
3335 @node Bind, Bind Examples, , Key Binding
3336 @section The @code{bind} command
3337 @deffn Command bind [-c class] key [command [args]]
3339 Bind a command to a key. The @var{key} argument is either a single
3340 character, a two-character sequence of the form @samp{^x} (meaning
3341 @kbd{C-x}), a backslash followed by an octal number (specifying the
3342 ASCII code of the character), or a backslash followed by a second
3343 character, such as @samp{\^} or @samp{\\}. The argument can also be
3344 quoted, if you like. If no further argument is given, any previously
3345 established binding for this key is removed. The @var{command}
3346 argument can be any command (@pxref{Command Index}).
3348 If a command class is specified via the @code{-c} option, the
3349 key is bound for the specified class. Use the @code{command}
3350 command to activate a class. Command classes can be used
3351 to create multiple command keys or multi-character bindings.
3353 By default, most suitable commands are bound to one or more keys
3354 (@pxref{Default Key Bindings}; for instance, the command to create a
3355 new window is bound to @kbd{C-c} and @kbd{c}. The @code{bind} command
3356 can be used to redefine the key bindings and to define new bindings.
3359 @node Bind Examples, Command Character, Bind, Key Binding
3360 @section Examples of the @code{bind} command
3366 bind ^f screen telnet foobar
3367 bind \033 screen -ln -t root -h 1000 9 su
3371 would bind the space key to the command that displays a list of windows
3372 (so that the command usually invoked by @kbd{C-a C-w} would also be
3373 available as @kbd{C-a space}), bind @kbd{C-f} to the command
3374 ``create a window with a TELNET connection to foobar'', and bind
3375 @key{ESC} to the command that creates an non-login window with title
3376 @samp{root} in slot #9, with a superuser shell and a scrollback buffer
3380 bind -c demo1 0 select 10
3381 bind -c demo1 1 select 11
3382 bind -c demo1 2 select 12
3383 bindkey "^B" command -c demo1
3385 makes @kbd{C-b 0} select window 10, @kbd{C-b 1} window 11, etc.
3388 bind -c demo2 0 select 10
3389 bind -c demo2 1 select 11
3390 bind -c demo2 2 select 12
3391 bind - command -c demo2
3393 makes @kbd{C-a - 0} select window 10, @kbd{C-a - 1} window 11, etc.
3395 @node Command Character, Help, Bind Examples, Key Binding
3396 @cindex escape character
3397 @cindex command character
3398 @section Command Character
3400 @deffn Command escape xy
3402 Set the command character to @var{x} and the character generating a
3403 literal command character (by triggering the @code{meta} command)
3404 to @var{y} (similar to the @samp{-e} option).
3405 Each argument is either a single character, a two-character
3406 sequence of the form @samp{^x} (meaning @kbd{C-x}), a backslash followed
3407 by an octal number (specifying the ASCII code of the character), or a
3408 backslash followed by a second character, such as @samp{\^} or
3409 @samp{\\}. The default is @samp{^Aa}, but @samp{``} is recommended by
3413 @deffn Command defescape xy
3415 Set the default command characters. This is equivalent to the command
3416 @code{escape} except that it is useful for multiuser sessions only.
3417 In a multiuser session
3418 @code{escape} changes the command character of the calling user, where
3419 @code{defescape} changes the default command characters for users that
3420 will be added later.
3426 Send the command character (@kbd{C-a}) to the process in the current
3427 window. The keystroke for this command is the second parameter to the
3428 @samp{-e} command line switch (@pxref{Invoking Screen}), or the
3429 @code{escape} .screenrc directive.
3432 @deffn Command command [-c @var{class}]
3434 This command has the same effect as typing the screen escape character
3435 (@kbd{C-a}). It is probably only useful for key bindings.
3436 If the @samp{-c} option is given, select the specified command class.
3437 @xref{Bind}, @xref{Bindkey}.
3440 @node Help, Bindkey, Command Character, Key Binding
3445 Displays a help screen showing you all the key bindings. The first
3446 pages list all the internal commands followed by their bindings.
3447 Subsequent pages will display the custom commands, one command per key.
3448 Press space when you're done reading each page, or return to exit early.
3449 All other characters are ignored.
3450 If the @samp{-c} option is given, display all bound commands for the
3451 specified command class.
3452 @xref{Default Key Bindings}.
3455 @node Bindkey, Bindkey Examples, Help, Key Binding
3457 @deffn Command bindkey [@var{opts}] [@var{string} [@var{cmd} @var{args}]]
3459 This command manages screen's input translation tables. Every
3460 entry in one of the tables tells screen how to react if a certain
3461 sequence of characters is encountered. There are three tables:
3462 one that should contain actions programmed by the user, one for
3463 the default actions used for terminal emulation and one for
3464 screen's copy mode to do cursor movement. See @ref{Input Translation}
3465 for a list of default key bindings.
3468 option is given, bindkey modifies the default table, @samp{-m}
3469 changes the copy mode table and with neither option the user
3470 table is selected. The argument @samp{string} is the sequence of
3471 characters to which an action is bound. This can either be a fixed
3472 string or a termcap keyboard capability name (selectable with the
3475 Some keys on a VT100 terminal can send a different
3476 string if application mode is turned on (e.g. the cursor keys).
3477 Such keys have two entries in the translation table. You can
3478 select the application mode entry by specifying the @samp{-a}
3481 The @samp{-t} option tells screen not to do inter-character
3482 timing. One cannot turn off the timing if a termcap capability is
3485 @samp{cmd} can be any of screen's commands with an arbitrary
3486 number of @samp{args}. If @samp{cmd} is omitted the key-binding is
3487 removed from the table.
3490 @node Bindkey Examples, Bindkey Control,Bindkey, Key Binding
3491 @section Bindkey Examples
3493 Here are some examples of keyboard bindings:
3499 Show all of the default key bindings. The application mode entries
3500 are marked with [A].
3503 bindkey -k k1 select 1
3506 Make the "F1" key switch to window one.
3509 bindkey -t foo stuff barfoo
3512 Make @samp{foo} an abbreviation of the word @samp{barfoo}. Timeout is
3513 disabled so that users can type slowly.
3516 bindkey "\024" mapdefault
3519 This key-binding makes @samp{C-t} an escape character for key-bindings. If
3520 you did the above @samp{stuff barfoo} binding, you can enter the word
3521 @samp{foo} by typing @samp{C-t foo}. If you want to insert a
3522 @samp{C-t} you have to press the key twice (i.e., escape the escape
3526 bindkey -k F1 command
3529 Make the F11 (not F1!) key an alternative screen
3530 escape (besides @samp{C-a}).
3532 @node Bindkey Control, , Bindkey Examples, Key Binding
3533 @section Bindkey Control
3534 @deffn Command mapdefault
3536 Tell screen that the next input character should only be looked up
3537 in the default bindkey table.
3539 @deffn Command mapnotnext
3541 Like mapdefault, but don't even look in the default bindkey table.
3543 @deffn Command maptimeout timo
3545 Set the inter-character timer for input sequence detection to a timeout
3546 of @var{timo} ms. The default timeout is 300ms. Maptimeout with no
3547 arguments shows the current setting.
3550 @node Flow Control, Termcap, Key Binding, Top
3551 @chapter Flow Control
3552 @cindex flow control
3554 @code{screen} can trap flow control characters or pass them to the
3555 program, as you see fit. This is useful when your terminal wants to use
3556 XON/XOFF flow control and you are running a program which wants to use
3557 ^S/^Q for other purposes (i.e. @code{emacs}).
3560 * Flow Control Summary:: The effect of @code{screen} flow control
3561 * Flow:: Setting the flow control behavior
3562 * XON/XOFF:: Sending XON or XOFF to the window
3565 @node Flow Control Summary, Flow, , Flow Control
3566 @section About @code{screen} flow control settings
3567 Each window has a flow-control setting that determines how screen deals
3568 with the XON and XOFF characters (and perhaps the interrupt character).
3569 When flow-control is turned off, screen ignores the XON and XOFF
3570 characters, which allows the user to send them to the current program by
3571 simply typing them (useful for the @code{emacs} editor, for instance).
3572 The trade-off is that it will take longer for output from a
3573 ``normal'' program to pause in response to an XOFF. With
3574 flow-control turned on, XON and XOFF characters are used to immediately
3575 pause the output of the current window. You can still send these
3576 characters to the current program, but you must use the appropriate
3577 two-character screen commands (typically @kbd{C-a q} (xon) and @kbd{C-a
3578 s} (xoff)). The xon/xoff commands are also useful for typing C-s and
3579 C-q past a terminal that intercepts these characters.
3581 Each window has an initial flow-control value set with either the
3582 @samp{-f} option or the @code{defflow} command. By default the
3583 windows are set to automatic flow-switching. It can then be toggled
3584 between the three states 'fixed on', 'fixed off' and 'automatic'
3585 interactively with the @code{flow} command bound to @kbd{C-a f}.
3587 The automatic flow-switching mode deals with flow control using the
3588 TIOCPKT mode (like @code{rlogin} does). If the tty driver does not
3589 support TIOCPKT, screen tries to determine the right mode based on the
3590 current setting of the application keypad --- when it is enabled,
3591 flow-control is turned off and visa versa. Of course, you can still
3592 manipulate flow-control manually when needed.
3594 If you're running with flow-control enabled and find that pressing the
3595 interrupt key (usually C-c) does not interrupt the display until another
3596 6-8 lines have scrolled by, try running screen with the @samp{interrupt}
3597 option (add the @samp{interrupt} flag to the @code{flow} command in your
3598 .screenrc, or use the @samp{-i} command-line option). This causes the
3599 output that @code{screen} has accumulated from the interrupted program
3600 to be flushed. One disadvantage is that the virtual terminal's memory
3601 contains the non-flushed version of the output, which in rare cases can
3602 cause minor inaccuracies in the output. For example, if you switch
3603 screens and return, or update the screen with @kbd{C-a l} you would see
3604 the version of the output you would have gotten without @samp{interrupt}
3605 being on. Also, you might need to turn off flow-control (or use
3606 auto-flow mode to turn it off automatically) when running a program that
3607 expects you to type the interrupt character as input, as the
3608 @samp{interrupt} parameter only takes effect when flow-control is
3609 enabled. If your program's output is interrupted by mistake, a simple
3610 refresh of the screen with @kbd{C-a l} will restore it. Give each mode
3611 a try, and use whichever mode you find more comfortable.
3613 @node Flow, XON/XOFF, Flow Control Summary, Flow Control
3615 @deffn Command defflow fstate [interrupt]
3617 Same as the @code{flow} command except that the default setting for new
3618 windows is changed. Initial setting is `auto'.
3619 Specifying @code{flow auto interrupt} has the same effect as the
3620 command-line options @samp{-fa} and @samp{-i}.
3621 Note that if @samp{interrupt} is enabled, all existing displays are
3622 changed immediately to forward interrupt signals.
3627 @deffn Command flow [fstate]
3628 (@kbd{C-a f}, @kbd{C-a C-f})@*
3629 Sets the flow-control mode for this window to @var{fstate}, which can be
3630 @samp{on}, @samp{off} or @samp{auto}.
3631 Without parameters it cycles the current window's
3632 flow-control setting. Default is set by `defflow'.
3635 @node XON/XOFF, , Flow, Flow Control
3636 @section XON and XOFF
3640 (@kbd{C-a q}, @kbd{C-a C-q})@*
3641 Send a ^Q (ASCII XON) to the program in the current window. Redundant
3642 if flow control is set to @samp{off} or @samp{auto}.
3648 (@kbd{C-a s}, @kbd{C-a C-s})@*
3649 Send a ^S (ASCII XOFF) to the program in the current window.
3652 @node Termcap, Message Line, Flow Control, Top
3655 @code{screen} demands the most out of your terminal so that it can
3656 perform its VT100 emulation most efficiently. These functions provide
3657 means for tweaking the termcap entries for both your physical terminal
3658 and the one simulated by @code{screen}.
3661 * Window Termcap:: Choosing a termcap entry for the window.
3662 * Dump Termcap:: Write out a termcap entry for the window.
3663 * Termcap Syntax:: The @code{termcap} and @code{terminfo} commands.
3664 * Termcap Examples:: Uses for @code{termcap}.
3665 * Special Capabilities:: Non-standard capabilities used by @code{screen}.
3666 * Autonuke:: Flush unseen output
3667 * Obuflimit:: Allow pending output when reading more
3668 * Character Translation:: Emulating fonts and charsets.
3671 @node Window Termcap, Dump Termcap, , Termcap
3672 @section Choosing the termcap entry for a window
3673 Usually @code{screen} tries to emulate as much of the VT100/ANSI
3674 standard as possible. But if your terminal lacks certain capabilities
3675 the emulation may not be complete. In these cases @code{screen} has to
3676 tell the applications that some of the features are missing. This is no
3677 problem on machines using termcap, because @code{screen} can use the
3678 @code{$TERMCAP} variable to customize the standard screen termcap.
3680 But if you do a rlogin on another machine or your machine supports only
3681 terminfo this method fails. Because of this @code{screen} offers a way
3682 to deal with these cases. Here is how it works:
3684 When @code{screen} tries to figure out a terminal name for itself, it
3685 first looks for an entry named @code{screen.@var{term}}, where
3686 @var{term} is the contents of your @code{$TERM} variable. If no such entry
3687 exists, @code{screen} tries @samp{screen} (or @samp{screen-w}, if the
3688 terminal is wide (132 cols or more)). If even this entry cannot be
3689 found, @samp{vt100} is used as a substitute.
3691 The idea is that if you have a terminal which doesn't support an
3692 important feature (e.g. delete char or clear to EOS) you can build a new
3693 termcap/terminfo entry for @code{screen} (named
3694 @samp{screen.@var{dumbterm}}) in which this capability has been
3695 disabled. If this entry is installed on your machines you are able to
3696 do a rlogin and still keep the correct termcap/terminfo entry. The
3697 terminal name is put in the @code{$TERM} variable of all new windows.
3698 @code{screen} also sets the @code{$TERMCAP} variable reflecting the
3699 capabilities of the virtual terminal emulated.
3700 Furthermore, the variable @code{$WINDOW} is set to the window number of each
3703 The actual set of capabilities supported by the virtual terminal depends
3704 on the capabilities supported by the physical terminal. If, for
3705 instance, the physical terminal does not support underscore mode,
3706 @code{screen} does not put the @samp{us} and @samp{ue} capabilities into
3707 the window's @code{$TERMCAP} variable, accordingly. However, a minimum number
3708 of capabilities must be supported by a terminal in order to run
3709 @code{screen}; namely scrolling, clear screen, and direct cursor
3710 addressing (in addition, @code{screen} does not run on hardcopy
3711 terminals or on terminals that over-strike).
3713 Also, you can customize the @code{$TERMCAP} value used by @code{screen} by
3714 using the @code{termcap} command, or by defining the variable
3715 @code{$SCREENCAP} prior to startup. When the latter defined, its value will be
3716 copied verbatim into each window's @code{$TERMCAP} variable. This can either
3717 be the full terminal definition, or a filename where the terminal
3718 @samp{screen} (and/or @samp{screen-w}) is defined.
3720 Note that @code{screen} honors the @code{terminfo} command if the system
3721 uses the terminfo database rather than termcap. On such machines the
3722 @code{$TERMCAP} variable has no effect and you must use the
3723 @code{dumptermcap} command (@pxref{Dump Termcap}) and the @code{tic}
3724 program to generate terminfo entries for @code{screen} windows.
3726 When the boolean @samp{G0} capability is present in the termcap entry
3727 for the terminal on which @code{screen} has been called, the terminal
3728 emulation of @code{screen} supports multiple character sets. This
3729 allows an application to make use of, for instance, the VT100 graphics
3730 character set or national character sets. The following control
3731 functions from ISO 2022 are supported: @samp{lock shift G0} (@samp{SI}),
3732 @samp{lock shift G1} (@samp{SO}), @samp{lock shift G2}, @samp{lock shift
3733 G3}, @samp{single shift G2}, and @samp{single shift G3}. When a virtual
3734 terminal is created or reset, the ASCII character set is designated as
3735 @samp{G0} through @samp{G3}. When the @samp{G0} capability is present,
3736 screen evaluates the capabilities @samp{S0}, @samp{E0}, and @samp{C0} if
3737 present. @samp{S0} is the sequence the terminal uses to enable and start
3738 the graphics character set rather than @samp{SI}. @samp{E0} is the
3739 corresponding replacement for @samp{SO}. @samp{C0} gives a character by
3740 character translation string that is used during semi-graphics mode.
3741 This string is built like the @samp{acsc} terminfo capability.
3743 When the @samp{po} and @samp{pf} capabilities are present in the
3744 terminal's termcap entry, applications running in a @code{screen} window
3745 can send output to the printer port of the terminal. This allows a user
3746 to have an application in one window sending output to a printer
3747 connected to the terminal, while all other windows are still active (the
3748 printer port is enabled and disabled again for each chunk of output).
3749 As a side-effect, programs running in different windows can send output
3750 to the printer simultaneously. Data sent to the printer is not
3751 displayed in the window. The @code{info} command displays a line starting
3752 with @samp{PRIN} while the printer is active.
3754 Some capabilities are only put into the @code{$TERMCAP} variable of the virtual
3755 terminal if they can be efficiently implemented by the physical
3756 terminal. For instance, @samp{dl} (delete line) is only put into the
3757 @code{$TERMCAP} variable if the terminal supports either delete line itself or
3758 scrolling regions. Note that this may provoke confusion, when the
3759 session is reattached on a different terminal, as the value of @code{$TERMCAP}
3760 cannot be modified by parent processes. You can force @code{screen} to
3761 include all capabilities in @code{$TERMCAP} with the @samp{-a}
3762 command-line option (@pxref{Invoking Screen}).
3764 The "alternate screen" capability is not enabled by default.
3765 Set the @code{altscreen} @file{.screenrc} command to enable it.
3767 @node Dump Termcap, Termcap Syntax, Window Termcap, Termcap
3768 @section Write out the window's termcap entry
3770 @deffn Command dumptermcap
3772 Write the termcap entry for the virtual terminal optimized for the
3773 currently active window to the file @file{.termcap} in the user's
3774 @file{$HOME/.screen} directory (or wherever @code{screen} stores its
3775 sockets. @pxref{Files}). This termcap entry is identical to
3776 the value of the environment variable @code{$TERMCAP} that is set up by
3777 @code{screen} for each window. For terminfo based systems you will need
3778 to run a converter like @code{captoinfo} and then compile the entry with
3782 @node Termcap Syntax, Termcap Examples, Dump Termcap, Termcap
3783 @section The @code{termcap} command
3784 @deffn Command termcap term terminal-tweaks [window-tweaks]
3785 @deffnx Command terminfo term terminal-tweaks [window-tweaks]
3786 @deffnx Command termcapinfo term terminal-tweaks [window-tweaks]
3788 Use this command to modify your terminal's termcap entry without going
3789 through all the hassles involved in creating a custom termcap entry.
3790 Plus, you can optionally customize the termcap generated for the
3792 You have to place these commands in one of the screenrc startup files, as they
3793 are meaningless once the terminal emulator is booted.
3795 If your system uses the terminfo database rather than termcap,
3796 @code{screen} will understand the @code{terminfo} command, which has the
3797 same effects as the @code{termcap} command. Two separate commands are
3798 provided, as there are subtle syntactic differences, e.g. when parameter
3799 interpolation (using @samp{%}) is required. Note that the termcap names of
3800 the capabilities should also be used with the @code{terminfo} command.
3802 In many cases, where the arguments are valid in both terminfo and termcap
3803 syntax, you can use the command @code{termcapinfo}, which is just a
3804 shorthand for a pair of @code{termcap} and @code{terminfo} commands with
3805 identical arguments.
3808 The first argument specifies which terminal(s) should be affected by
3809 this definition. You can specify multiple terminal names by separating
3810 them with @samp{|}s. Use @samp{*} to match all terminals and @samp{vt*}
3811 to match all terminals that begin with @samp{vt}.
3813 Each @var{tweak} argument contains one or more termcap defines
3814 (separated by @samp{:}s) to be inserted at the start of the appropriate
3815 termcap entry, enhancing it or overriding existing values. The first
3816 tweak modifies your terminal's termcap, and contains definitions that
3817 your terminal uses to perform certain functions. Specify a null string
3818 to leave this unchanged (e.g. ""). The second (optional) tweak modifies
3819 all the window termcaps, and should contain definitions that screen
3820 understands (@pxref{Virtual Terminal}).
3822 @node Termcap Examples, Special Capabilities, Termcap Syntax, Termcap
3823 @section Termcap Examples
3827 termcap xterm* xn:hs@@
3831 Informs @code{screen} that all terminals that begin with @samp{xterm}
3832 have firm auto-margins that allow the last position on the screen to be
3833 updated (xn), but they don't really have a status line (no 'hs' --
3834 append @samp{@@} to turn entries off). Note that we assume @samp{xn} for
3835 all terminal names that start with @samp{vt}, but only if you don't
3836 specify a termcap command for that terminal.
3840 termcap vt102|vt220 Z0=\E[?3h:Z1=\E[?3l
3844 Specifies the firm-margined @samp{xn} capability for all terminals that
3845 begin with @samp{vt}, and the second line will also add the
3846 escape-sequences to switch into (Z0) and back out of (Z1)
3847 132-character-per-line mode if this is a VT102 or VT220. (You must
3848 specify Z0 and Z1 in your termcap to use the width-changing commands.)
3851 termcap vt100 "" l0=PF1:l1=PF2:l2=PF3:l3=PF4
3855 This leaves your vt100 termcap alone and adds the function key labels to
3856 each window's termcap entry.
3859 termcap h19|z19 am@@:im=\E@@:ei=\EO dc=\E[P
3863 Takes a h19 or z19 termcap and turns off auto-margins (am@@) and enables
3864 the insert mode (im) and end-insert (ei) capabilities (the @samp{@@} in
3865 the @samp{im} string is after the @samp{=}, so it is part of the
3866 string). Having the @samp{im} and @samp{ei} definitions put into your
3867 terminal's termcap will cause screen to automatically advertise the
3868 character-insert capability in each window's termcap. Each window will
3869 also get the delete-character capability (dc) added to its termcap,
3870 which screen will translate into a line-update for the terminal (we're
3871 pretending it doesn't support character deletion).
3873 If you would like to fully specify each window's termcap entry, you
3874 should instead set the @code{$SCREENCAP} variable prior to running
3875 @code{screen}. @xref{Virtual Terminal}, for the details of the
3876 @code{screen} terminal emulation. @xref{Top, , Termcap, termcap, The
3877 Termcap Manual}, for more information on termcap definitions.
3879 @node Special Capabilities, Autonuke, Termcap Examples, Termcap
3880 @section Special Terminal Capabilities
3881 @cindex terminal capabilities
3882 @cindex capabilities
3883 The following table describes all terminal capabilities that are
3884 recognized by @code{screen} and are not in the termcap manual
3885 (@pxref{Top, , Termcap, termcap, The Termcap Manual}).
3886 You can place these capabilities in your termcap entries (in
3887 @file{/etc/termcap}) or use them with the commands @code{termcap},
3888 @code{terminfo} and @code{termcapinfo} in your @code{screenrc} files. It is
3889 often not possible to place these capabilities in the terminfo database.
3893 Terminal has VT100 style margins (`magic margins'). Note that
3894 this capability is obsolete --- @code{screen} now uses the standard
3899 Change width to 132 columns.
3903 Change width to 80 columns.
3907 Resize display. This capability has the desired width and height as
3908 arguments. SunView(tm) example: @samp{\E[8;%d;%dt}.
3912 Terminal doesn't need flow control. Send ^S and ^Q direct to
3913 the application. Same as @code{flow off}. The opposite of this
3914 capability is @samp{nx}.
3918 Terminal can deal with ISO 2022 font selection sequences.
3922 Switch charset @samp{G0} to the specified charset. Default
3927 Switch charset @samp{G0} back to standard charset. Default
3932 Use the string as a conversion table for font 0. See
3933 the @samp{ac} capability for more details.
3937 Switch cursor-keys to application mode.
3941 Switch cursor-keys to cursor mode.
3945 Enable autonuke for displays of this terminal type.
3950 Set the output buffer limit. See the @samp{obuflimit} command
3951 (@pxref{Obuflimit}) for more details.
3955 Set the encoding of the terminal. See the @samp{encoding} command
3956 (@pxref{Character Processing}) for valid encodings.
3960 Change character foreground color in an ANSI conform way. This
3961 capability will almost always be set to @samp{\E[3%dm}
3962 (@samp{\E[3%p1%dm} on terminfo machines).
3966 Same as @samp{AF}, but change background color.
3970 Does understand ANSI set default fg/bg color (@samp{\E[39m / \E[49m}).
3974 Describe a translation of characters to strings depending on the
3975 current font. (@pxref{Character Translation}).
3979 Terminal understands special xterm sequences (OSC, mouse tracking).
3983 Terminal needs bold to display high-intensity colors (e.g. Eterm).
3987 Add missing capabilities to the termcap/info entry. (Set by default).
3990 @node Autonuke, Obuflimit, Special Capabilities, Termcap
3992 @deffn Command autonuke @var{state}
3994 Sets whether a clear screen sequence should nuke all the output
3995 that has not been written to the terminal. @xref{Obuflimit}.
3996 This property is set per display, not per window.
3999 @deffn Command defautonuke @var{state}
4001 Same as the @code{autonuke} command except that the default setting for
4002 new displays is also changed. Initial setting is @code{off}.
4003 Note that you can use the special @code{AN} terminal capability if you
4004 want to have a terminal type dependent setting.
4007 @node Obuflimit, Character Translation, Autonuke, Termcap
4009 @deffn Command obuflimit [@var{limit}]
4011 If the output buffer contains more bytes than the specified limit, no
4012 more data will be read from the windows. The default value is 256. If
4013 you have a fast display (like @code{xterm}), you can set it to some
4014 higher value. If no argument is specified, the current setting is displayed.
4015 This property is set per display, not per window.
4018 @deffn Command defobuflimit @var{limit}
4020 Same as the @code{obuflimit} command except that the default setting for new
4021 displays is also changed. Initial setting is 256 bytes. Note that you can use
4022 the special @code{OL} terminal capability if you want to have a terminal
4023 type dependent limit.
4026 @node Character Translation, , Obuflimit, Termcap
4027 @section Character Translation
4028 @code{Screen} has a powerful mechanism to translate characters to
4029 arbitrary strings depending on the current font and terminal type.
4030 Use this feature if you want to work with a common standard character
4031 set (say ISO8851-latin1) even on terminals that scatter the more
4032 unusual characters over several national language font pages.
4037 XC=@var{<charset-mapping>}@{,,@var{<charset-mapping>}@}
4038 @var{<charset-mapping>} := @var{<designator>}@var{<template>}@{,@var{<mapping>}@}
4039 @var{<mapping>} := @var{<char-to-be-mapped>}@var{<template-arg>}
4042 The things in braces may be repeated any number of times.
4044 A @var{<charset-mapping>} tells screen how to map characters
4045 in font @var{<designator>} (@samp{B}: Ascii, @samp{A}: UK,
4046 @samp{K}: german, etc.)
4047 to strings. Every @var{<mapping>} describes to what string a single
4048 character will be translated. A template mechanism is used, as
4049 most of the time the codes have a lot in common (for example
4050 strings to switch to and from another charset). Each occurrence
4051 of @samp{%} in @var{<template>} gets substituted with the
4053 specified together with the character. If your strings are not
4054 similar at all, then use @samp{%} as a template and place the full
4055 string in @var{<template-arg>}. A quoting mechanism was added to make
4056 it possible to use a real @samp{%}. The @samp{\} character quotes the
4057 special characters @samp{\}, @samp{%}, and @samp{,}.
4062 termcap hp700 'XC=B\E(K%\E(B,\304[,\326\\\\,\334]'
4065 This tells @code{screen}, how to translate ISOlatin1 (charset @samp{B})
4066 upper case umlaut characters on a @code{hp700} terminal that has a
4067 German charset. @samp{\304} gets translated to
4068 @samp{\E(K[\E(B} and so on.
4069 Note that this line gets parsed *three* times before the internal
4070 lookup table is built, therefore a lot of quoting is needed to
4071 create a single @samp{\}.
4073 Another extension was added to allow more emulation: If a mapping
4074 translates the unquoted @samp{%} char, it will be sent to the terminal
4075 whenever screen switches to the corresponding @var{<designator>}.
4077 special case the template is assumed to be just @samp{%} because
4078 the charset switch sequence and the character mappings normally
4079 haven't much in common.
4081 This example shows one use of the extension:
4083 termcap xterm 'XC=K%,%\E(B,[\304,\\\\\326,]\334'
4086 Here, a part of the German (@samp{K}) charset is emulated on an xterm.
4087 If screen has to change to the @samp{K} charset, @samp{\E(B} will be
4089 to the terminal, i.e. the ASCII charset is used instead. The
4090 template is just @samp{%}, so the mapping is straightforward:
4091 @samp{[} to @samp{\304}, @samp{\} to @samp{\326}, and @samp{]} to
4094 @node Message Line, Logging, Termcap, Top
4095 @chapter The Message Line
4096 @cindex message line
4098 @code{screen} displays informational messages and other diagnostics in a
4099 @dfn{message line} at the bottom of the screen. If your terminal has a
4100 status line defined in its termcap, screen will use this for displaying
4101 its messages, otherwise the last line of the screen will be temporarily
4102 overwritten and output will be momentarily interrupted. The message
4103 line is automatically removed after a few seconds delay, but it can also
4104 be removed early (on terminals without a status line) by beginning to
4108 * Privacy Message:: Using the message line from your program.
4109 * Hardware Status Line:: Use the terminal's hardware status line.
4110 * Last Message:: Redisplay the last message.
4111 * Message Wait:: Control how long messages are displayed.
4114 @node Privacy Message, Hardware Status Line, , Message Line
4115 @section Using the message line from your program
4116 The message line facility can be used by an application running in the
4117 current window by means of the ANSI @dfn{Privacy message} control
4118 sequence. For instance, from within the shell, try something like:
4121 echo "@value{esc}^Hello world from window $WINDOW@value{esc}\"
4124 where @samp{@value{esc}} is ASCII ESC and the @samp{^} that follows it
4125 is a literal caret or up-arrow.
4127 @node Hardware Status Line, Last Message, Privacy Message, Message Line
4128 @section Hardware Status Line
4129 @deffn Command hardstatus [state]
4130 @deffnx Command hardstatus [@code{always}]@code{lastline}|@code{message}|@code{ignore} [string]
4131 @deffnx Command hardstatus @code{string} [string]
4133 This command configures the use and emulation of the terminal's
4134 hardstatus line. The first form toggles whether @code{screen}
4135 will use the hardware status line to display messages. If the
4136 flag is set to @samp{off}, these messages
4137 are overlaid in reverse video mode at the display line. The default
4138 setting is @samp{on}.
4140 The second form tells screen what to do if the terminal doesn't
4141 have a hardstatus line (i.e. the termcap/terminfo capabilities
4142 "hs", "ts", "fs" and "ds" are not set). If the type
4143 @code{lastline} is used, screen will reserve the last line of the
4144 display for the hardstatus. @code{message} uses
4145 @code{screen}'s message mechanism and
4146 @code{ignore} tells @code{screen} never to display the hardstatus.
4147 If you prepend the word @code{always} to the type (e.g., @code{alwayslastline}), @code{screen} will use
4148 the type even if the terminal supports a hardstatus line.
4150 The third form specifies the contents of the hardstatus line.
4151 @code{%h} is used as default string, i.e., the stored hardstatus of the
4152 current window (settable via @samp{ESC]0;^G} or @samp{ESC_\\}) is
4154 You can customize this to any string you like including
4155 string escapes (@pxref{String Escapes}).
4157 out the argument @var{string}, the current string is displayed.
4159 You can mix the second and third form by providing the string as
4160 additional argument.
4163 @node Last Message, Message Wait, Hardware Status Line, Message Line
4164 @section Display Last Message
4167 @deffn Command lastmsg
4168 (@kbd{C-a m}, @kbd{C-a C-m})@*
4169 Repeat the last message displayed in the message line. Useful if you're
4170 typing when a message appears, because (unless your terminal has a
4171 hardware status line) the message goes away when you press a key.
4174 @node Message Wait, , Last Message, Message Line
4175 @section Message Wait
4176 @deffn Command msgminwait sec
4178 Defines the time @code{screen} delays a new message when another is
4179 currently displayed. Defaults to 1 second.
4182 @deffn Command msgwait sec
4184 Defines the time a message is displayed, if @code{screen} is not
4185 disturbed by other activity. Defaults to 5 seconds.
4188 @node Logging, Startup, Message Line, Top
4191 This section describes the commands for keeping a record of your session.
4194 * Hardcopy:: Dump the current screen to a file
4195 * Log:: Log the output of a window to a file
4198 @node Hardcopy, Log, , Logging
4202 @deffn Command hardcopy [-h] [@var{file}]
4203 (@kbd{C-a h}, @kbd{C-a C-h})@*
4204 Writes out the currently displayed image to the file @var{file}, or,
4205 if no filename is specified, to @file{hardcopy.@var{n}}
4206 in the default directory, where @var{n} is the number of the
4207 current window. This either appends or overwrites the file if it
4208 exists, as determined by the @code{hardcopy_append} command.
4209 If the option @code{-h} is specified, dump also the
4210 contents of the scrollback buffer.
4213 @deffn Command hardcopy_append state
4215 If set to @samp{on}, @code{screen} will append to the
4216 @file{hardcopy.@var{n}} files created by the command @code{hardcopy};
4217 otherwise, these files are overwritten each time.
4220 @deffn Command hardcopydir directory
4222 Defines a directory where hardcopy files will be placed.
4223 If unset, hardcopys are dumped in screen's current working
4227 @node Log, , Hardcopy, Logging
4230 @deffn Command deflog state
4232 Same as the @code{log} command except that the default setting for new
4233 windows is changed. Initial setting is `off'.
4237 @deffn Command log [state]
4239 Begins/ends logging of the current window to the file
4240 @file{screenlog.@var{n}} in the window's default directory, where
4241 @var{n} is the number of the current window.
4242 This filename can be changed with the @samp{logfile} command.
4243 If no parameter is given,
4244 the logging state is toggled. The session log is
4245 appended to the previous contents of the file if it already exists. The
4246 current contents and the contents of the scrollback history are not
4247 included in the session log. Default is @samp{off}.
4250 @deffn Command logfile filename
4251 @deffnx Command logfile flush secs
4253 Defines the name the log files will get. The default is @samp{screenlog.%n}.
4254 The second form changes the number of seconds @code{screen}
4255 will wait before flushing the logfile buffer to the file-system. The
4256 default value is 10 seconds.
4259 @deffn Command logtstamp [state]
4260 @deffnx Command logtstamp @code{after} secs
4261 @deffnx Command logtstamp @code{string} string
4263 This command controls logfile time-stamp mechanism of screen. If
4264 time-stamps are turned @samp{on}, screen adds a string containing
4265 the current time to the logfile after two minutes of inactivity.
4266 When output continues and more than another two minutes have passed,
4267 a second time-stamp is added to document the restart of the
4268 output. You can change this timeout with the second form
4269 of the command. The third form is used for customizing the time-stamp
4270 string (@samp{-- %n:%t -- time-stamp -- %M/%d/%y %c:%s --\n} by
4274 @node Startup, Miscellaneous, Logging, Top
4277 This section describes commands which are only useful in the
4278 @file{.screenrc} file, for use at startup.
4281 * echo:: Display a message.
4282 * sleep:: Pause execution of the @file{.screenrc}.
4283 * Startup Message:: Control display of the copyright notice.
4286 @node echo, sleep, , Startup
4288 @deffn Command echo [@samp{-n}] message
4290 The echo command may be used to annoy @code{screen} users with a
4291 'message of the day'. Typically installed in a global screenrc.
4292 The option @samp{-n} may be used to suppress the line feed.
4293 See also @code{sleep}.
4294 Echo is also useful for online checking of environment variables.
4297 @node sleep, Startup Message, echo, Startup
4299 @deffn Command sleep num
4301 This command will pause the execution of a .screenrc file for @var{num}
4302 seconds. Keyboard activity will end the sleep. It may be used to give
4303 users a chance to read the messages output by @code{echo}.
4306 @node Startup Message, , sleep, Startup
4307 @section Startup Message
4308 @deffn Command startup_message state
4310 Select whether you want to see the copyright notice during startup.
4311 Default is @samp{on}, as you probably noticed.
4314 @node Miscellaneous, String Escapes, Startup, Top
4315 @chapter Miscellaneous commands
4317 The commands described here do not fit well under any of the other
4321 * At:: Execute a command at other displays or windows.
4322 * Break:: Send a break signal to the window.
4323 * Debug:: Suppress/allow debugging output.
4324 * License:: Display the disclaimer page.
4325 * Nethack:: Use @code{nethack}-like error messages.
4326 * Nonblock:: Disable flow-control to a display.
4327 * Number:: Change the current window's number.
4328 * Silence:: Notify on inactivity.
4329 * Time:: Display the time and load average.
4330 * Verbose:: Display window creation commands.
4331 * Version:: Display the version of @code{screen}.
4332 * Zombie:: Keep dead windows.
4333 * Printcmd:: Set command for VT100 printer port emulation.
4334 * Sorendition:: Change the text highlighting method.
4335 * Attrcolor:: Map attributes to colors.
4336 * Setsid:: Change process group management.
4337 * Eval:: Parse and execute arguments.
4338 * Maxwin:: Set the maximum window number.
4339 * Backtick:: Program a command for a backtick string escape.
4340 * Screen Saver:: Define a screen safer.
4341 * Zmodem:: Define how screen treats zmodem requests.
4344 @node At, Break, , Miscellaneous
4346 @deffn Command at [identifier][#|*|%] command [args]
4348 Execute a command at other displays or windows as if it had been entered there.
4349 @code{At} changes the context (the `current window' or `current display'
4350 setting) of the command. If the first parameter describes a non-unique context,
4351 the command will be executed multiple times. If the first parameter is of the
4352 form @samp{@var{identifier}*} then identifier is matched against user names.
4353 The command is executed once for each display of the selected user(s).
4354 If the first parameter is of the form @samp{@var{identifier}%} identifier is
4355 matched against displays. Displays are named after the ttys they attach. The
4356 prefix @samp{/dev/} or @samp{/dev/tty} may be omitted from the identifier.
4357 If @var{identifier} has a @code{#} or nothing appended it is matched against
4358 window numbers and titles. Omitting an identifier in front of the @code{#},
4359 @code{*} or @code{%} character selects all users, displays or windows because
4360 a prefix-match is performed. Note that on the affected display(s) a short
4361 message will describe what happened.
4362 Note that the @code{#} character works as a comment introducer when it is
4363 preceded by whitespace. This can be escaped by prefixing @code{#} with a
4365 Permission is checked for the initiator of the @code{at} command, not for the
4366 owners of the affected display(s).
4368 When matching against windows, the command is executed at least
4369 once per window. Commands that change the internal arrangement of windows
4370 (like @code{other}) may be called again. In shared windows the command will
4371 be repeated for each attached display. Beware, when issuing toggle commands
4373 Some commands (e.g. @code{\*Qprocess}) require
4374 that a display is associated with the target windows. These commands may not
4375 work correctly under @code{at} looping over windows.
4378 @node Break, Debug, At, Miscellaneous
4380 @deffn Command break [duration]
4382 Send a break signal for @var{duration}*0.25 seconds to this window.
4383 For non-Posix systems the time interval is rounded up to full seconds.
4384 Most useful if a character device is attached to the window rather than
4385 a shell process (@pxref{Window Types}). The maximum duration of
4386 a break signal is limited to 15 seconds.
4389 @deffn Command pow_break
4391 Reopen the window's terminal line and send a break condition.
4394 @deffn Command breaktype [tcsendbreak|TIOCSBRK|TCSBRK]
4396 Choose one of the available methods of generating a break signal for
4397 terminal devices. This command should affect the current window only.
4398 But it still behaves identical to @code{defbreaktype}. This will be changed in
4400 Calling @code{breaktype} with no parameter displays the break setting for the
4404 @deffn Command defbreaktype [tcsendbreak|TIOCSBRK|TCSBRK]
4406 Choose one of the available methods of generating a break signal for
4407 terminal devices opened afterwards. The preferred methods are
4408 @code{tcsendbreak} and
4409 @code{TIOCSBRK}. The third, @code{TCSBRK}, blocks the complete @code{screen}
4410 session for the duration of the break, but it may be the only way to
4411 generate long breaks. @code{tcsendbreak} and @code{TIOCSBRK} may or may not
4412 produce long breaks with spikes (e.g. 4 per second). This is not only system
4413 dependent, this also differs between serial board drivers.
4414 Calling @code{defbreaktype} with no parameter displays the current setting.
4417 @node Debug, License, Break, Miscellaneous
4419 @deffn Command debug [on|off]
4421 Turns runtime debugging on or off. If @code{screen} has been compiled with
4422 option @code{-DDEBUG} debugging is available and is turned on per default.
4423 Note that this command only affects debugging output from the main
4424 @samp{SCREEN} process correctly. Debug output from attacher processes can only
4425 be turned off once and forever.
4428 @node License, Nethack, Debug, Miscellaneous
4430 @deffn Command license
4432 Display the disclaimer page. This is done whenever @code{screen} is
4433 started without options, which should be often enough.
4436 @node Nethack, Nonblock, License, Miscellaneous
4438 @deffn Command nethack state
4440 Changes the kind of error messages used by @code{screen}. When you are
4441 familiar with the game @code{nethack}, you may enjoy the nethack-style
4442 messages which will often blur the facts a little, but are much funnier
4443 to read. Anyway, standard messages often tend to be unclear as well.
4445 This option is only available if @code{screen} was compiled with the
4446 NETHACK flag defined (@pxref{Installation}). The default setting is then
4447 determined by the presence of the environment variable
4448 @code{$NETHACKOPTIONS}.
4451 @node Nonblock, Number, Nethack, Miscellaneous
4453 @deffn Command nonblock [@var{state}|@var{numsecs}]
4454 Tell screen how to deal with user interfaces (displays) that cease to
4455 accept output. This can happen if a user presses ^S or a TCP/modem
4456 connection gets cut but no hangup is received. If nonblock is
4457 @code{off} (this is the default) screen waits until the display
4458 restarts to accept the output. If nonblock is @code{on}, screen
4459 waits until the timeout is reached (@code{on} is treated as 1s). If the
4460 display still doesn't receive characters, screen will consider
4461 it ``blocked'' and stop sending characters to it. If at
4462 some time it restarts to accept characters, screen will unblock
4463 the display and redisplay the updated window contents.
4466 @deffn Command defnonblock @var{state}|@var{numsecs}
4467 Same as the @code{nonblock} command except that the default setting for
4468 displays is changed. Initial setting is @code{off}.
4471 @node Number, Silence, Nonblock, Miscellaneous
4474 @deffn Command number [@var{n}]
4476 Change the current window's number. If the given number @var{n} is already
4477 used by another window, both windows exchange their numbers. If no argument is
4478 specified, the current window number (and title) is shown.
4481 @node Silence, Time, Number, Miscellaneous
4483 @deffn Command silence [@var{state}|@var{sec}]
4485 Toggles silence monitoring of windows. When silence is turned on and an
4486 affected window is switched into the background, you will receive the
4487 silence notification message in the status line after a specified period
4488 of inactivity (silence). The default timeout can be changed with the
4489 @code{silencewait} command or by specifying a number of seconds instead of
4490 @code{on} or @code{off}. Silence is initially off for all windows.
4493 @deffn Command defsilence state
4495 Same as the @code{silence} command except that the default setting for
4496 new windows is changed. Initial setting is `off'.
4499 @deffn Command silencewait @var{seconds}
4501 Define the time that all windows monitored for silence should wait
4502 before displaying a message. Default is 30 seconds.
4505 @node Time, Verbose, Silence, Miscellaneous
4509 @deffn Command time [@var{string}]
4510 (@kbd{C-a t}, @kbd{C-a C-t})@*
4511 Uses the message line to display the time of day, the host name, and the
4512 load averages over 1, 5, and 15 minutes (if this is available on your
4513 system). For window-specific information use @code{info} (@pxref{Info}).
4514 If a @var{string} is specified, it changes the format of the time report
4515 like it is described in the string escapes chapter (@pxref{String Escapes}). Screen uses a default of @samp{%c:%s %M %d %H%? %l%?}.
4518 @node Verbose, Version, Time, Miscellaneous
4520 @deffn Command verbose [on|off]
4521 If verbose is switched on, the command name is echoed, whenever a window
4522 is created (or resurrected from zombie state). Default is off.
4523 Without parameter, the current setting is shown.
4526 @node Version, Zombie, Verbose, Miscellaneous
4529 @deffn Command version
4531 Display the version and modification date in the message line.
4534 @node Zombie, Printcmd, Version, Miscellaneous
4536 @deffn Command zombie [@var{keys} [onerror] ]
4537 @deffnx Command defzombie [@var{keys}]
4539 Per default windows are removed from the window list as soon as the
4540 windows process (e.g. shell) exits. When a string of two keys is
4541 specified to the zombie command, `dead' windows will remain in the list.
4542 The @code{kill} command may be used to remove the window. Pressing the first key
4543 in the dead window has the same effect. Pressing the second key, however,
4544 screen will attempt to resurrect the window. The process that was initially
4545 running in the window will be launched again. Calling @code{zombie} without
4546 parameters will clear the zombie setting, thus making windows disappear when
4547 the process terminates.
4549 As the zombie setting is affected globally for all windows, this command
4550 should only be called @code{defzombie}. Until we need this as a per window
4551 setting, the commands @code{zombie} and @code{defzombie} are synonymous.
4553 Optionally you can put the word @code{onerror} after the keys. This will
4554 cause screen to monitor exit status of the process running in the window.
4555 If it exits normally ('0'), the window disappears. Any other exit value
4556 causes the window to become a zombie.
4559 @node Printcmd, Sorendition, Zombie, Miscellaneous
4561 @deffn Command printcmd [@var{cmd}]
4563 If @var{cmd} is not an empty string, screen will not use the terminal
4564 capabilities @code{po/pf} for printing if it detects an ansi print
4565 sequence @code{ESC [ 5 i}, but pipe the output into @var{cmd}.
4566 This should normally be a command like @samp{lpr} or
4567 @samp{cat > /tmp/scrprint}.
4568 @code{Printcmd} without an argument displays the current setting.
4569 The ansi sequence @code{ESC \} ends printing and closes the pipe.
4571 Warning: Be careful with this command! If other user have write
4572 access to your terminal, they will be able to fire off print commands.
4575 @node Sorendition, Attrcolor, Printcmd, Miscellaneous
4576 @section Sorendition
4577 @deffn Command sorendition [@var{attr} [@var{color}]]
4579 Change the way screen does highlighting for text marking and printing
4582 about string escapes (@pxref{String Escapes}) for the syntax of
4583 the modifiers. The default is currently @samp{=s dd} (standout,
4587 @node Attrcolor, Setsid, Sorendition, Miscellaneous
4589 @deffn Command attrcolor @var{attrib} [@var{attribute/color-modifier}]
4591 This command can be used to highlight attributes by changing the color of
4592 the text. If the attribute
4594 is in use, the specified attribute/color modifier is also applied. If no
4595 modifier is given, the current one is deleted. See the chapter
4596 about string escapes (@pxref{String Escapes}) for the syntax of
4597 the modifier. Screen understands two pseudo-attributes, @code{i}
4598 stands for high-intensity foreground color and @code{I} for
4599 high-intensity background color.
4604 @item attrcolor b "R"
4605 Change the color to bright red if bold text is to be printed.
4606 @item attrcolor u "-u b"
4607 Use blue text instead of underline.
4608 @item attrcolor b ".I"
4609 Use bright colors for bold text. Most terminal emulators do this
4611 @item attrcolor i "+b"
4612 Make bright colored text also bold.
4616 @node Setsid, Eval, Attrcolor, Miscellaneous
4618 @deffn Command setsid state
4620 Normally screen uses different sessions and process groups for
4621 the windows. If setsid is turned @code{off}, this is not done
4622 anymore and all windows will be in the same process group as the
4623 screen backend process. This also breaks job-control, so be careful.
4624 The default is @code{on}, of course. This command is probably useful
4625 only in rare circumstances.
4628 @node Eval, Maxwin, Setsid, Miscellaneous
4630 @deffn Command eval @var{command1} [@var{command2} ...]
4632 Parses and executes each argument as separate command.
4635 @node Maxwin, Backtick, Eval, Miscellaneous
4637 @deffn Command maxwin @var{n}
4639 Set the maximum window number screen will create. Doesn't affect
4640 already existing windows. The number may only be decreased.
4643 @node Backtick, Screen Saver, Maxwin, Miscellaneous
4645 @deffn Command backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}]
4646 @deffnx Command backtick @var{id}
4648 Program the backtick command with the numerical id @var{id}.
4649 The output of such a command is used for substitution of the
4650 @code{%`} string escape (@pxref{String Escapes}).
4651 The specified @var{lifespan} is the number
4652 of seconds the output is considered valid. After this time, the
4653 command is run again if a corresponding string escape is encountered.
4654 The @var{autorefresh} parameter triggers an
4655 automatic refresh for caption and hardstatus strings after the
4656 specified number of seconds. Only the last line of output is used
4659 If both the @var{lifespan} and the @var{autorefresh} parameters
4660 are zero, the backtick program is expected to stay in the
4661 background and generate output once in a while.
4662 In this case, the command is executed right away and screen stores
4663 the last line of output. If a new line gets printed screen will
4664 automatically refresh the hardstatus or the captions.
4666 The second form of the command deletes the backtick command
4667 with the numerical id @var{id}.
4670 @node Screen Saver, Zmodem, Backtick, Miscellaneous
4671 @section Screen Saver
4672 @deffn Command idle [@var{timeout} [@var{cmd} @var{args}]]
4674 Sets a command that is run after the specified number of
4675 seconds inactivity is reached. This command will normally
4676 be the @code{blanker} command to create a screen blanker, but
4677 it can be any screen command. If no command is specified,
4678 only the timeout is set. A timeout of zero (ot the special
4679 timeout @code{off}) disables the timer. If no arguments are
4680 given, the current settings are displayed.
4683 @deffn Command blanker
4685 Activate the screen blanker. First the screen is cleared.
4686 If no blanker program is defined, the cursor is turned
4687 off, otherwise, the program is started and it's output is
4688 written to the screen. The screen blanker is killed with
4689 the first keypress, the read key is discarded.
4691 This command is normally used together with the @code{idle}
4695 @deffn Command blankerprg [@var{program args}]
4696 Defines a blanker program. Disables the blanker program if
4697 no arguments are given.
4700 @node Zmodem, , Screen Saver, Miscellaneous
4702 @deffn Command zmodem [off|auto|catch|pass]
4703 @deffnx Command zmodem sendcmd [string]
4704 @deffnx Command zmodem recvcmd [string]
4706 Define zmodem support for screen. Screen understands two
4707 different modes when it detects a zmodem request: @code{pass}
4708 and @code{catch}. If the mode is set to @code{pass}, screen will
4709 relay all data to the attacher until the end of the
4710 transmission is reached. In @code{catch} mode screen acts as a
4711 zmodem endpoint and starts the corresponding rz/sz commands.
4712 If the mode is set to @code{auto}, screen will use @code{catch} if
4713 the window is a tty (e.g. a serial line), otherwise it
4714 will use @code{pass}.
4716 You can define the templates screen uses in @code{catch} mode
4717 via the second and the third form.
4719 Note also that this is an experimental feature.
4722 @node String Escapes, Environment, Miscellaneous, Top
4723 @chapter String Escapes
4724 @cindex string escapes
4725 Screen provides an escape mechanism to insert information like the
4726 current time into messages or file names. The escape character
4727 is @code{%} with one exception: inside of a window's hardstatus
4728 @code{^%} (@code{^E}) is used instead.
4730 Here is the full list of supported escapes:
4734 the escape character itself
4736 either @code{am} or @code{pm}
4738 either @code{AM} or @code{PM}
4740 current time @code{HH:MM} in 24h format
4742 current time @code{HH:MM} in 12h format
4750 sets %? to true if the window has the focus
4752 hardstatus of the window
4754 hostname of the system
4756 current load of the system
4770 all other users on this window
4772 all window numbers and names. With @code{-} qualifier: up to the current
4773 window; with @code{+} qualifier: starting with the window after the current
4776 all window numbers and names except the current one
4778 last two digits of the year number
4782 the part to the next @code{%?} is displayed only if a @code{%} escape
4783 inside the part expands to a non-empty string
4785 else part of @code{%?}
4787 pad the string to the display's width (like TeX's hfill). If a
4788 number is specified, pad to the percentage of the window's width.
4789 A @code{0} qualifier tells screen to treat the number as absolute position.
4790 You can specify to pad relative to the last absolute pad position
4791 by adding a @code{+} qualifier or to pad relative to the right margin
4792 by using @code{-}. The padding truncates the string if the specified
4793 position lies before the current position. Add the @code{L} qualifier
4796 same as @code{%=} but just do truncation, do not fill with spaces
4798 mark the current text position for the next truncation. When
4799 screen needs to do truncation, it tries to do it in a way that
4800 the marked position gets moved to the specified percentage of
4801 the output area. (The area starts from the last absolute pad
4802 position and ends with the position specified by the truncation
4803 operator.) The @code{L} qualifier tells screen to mark the truncated
4804 parts with @samp{...}.
4806 attribute/color modifier string terminated by the next @code{@}}
4808 Substitute with the output of a `backtick' command. The length
4809 qualifier is misused to identify one of the commands. @xref{Backtick}.
4811 The @code{c} and @code{C} escape may be qualified with a @code{0} to
4813 zero instead of space as fill character.
4815 @code{=} escapes understand
4816 a length qualifier (e.g. @code{%3n}), @code{D} and @code{M} can be
4817 prefixed with @code{L} to generate long names, @code{w} and
4818 @code{W} also show the window flags if @code{L} is given.
4820 An attribute/color modifier is is used to change the attributes or the
4821 color settings. Its format
4822 is @samp{[attribute modifier] [color description]}. The attribute modifier
4823 must be prefixed by a change type indicator if it can be confused with
4824 a color description. The following change types are known:
4827 add the specified set to the current attributes
4829 remove the set from the current attributes
4831 invert the set in the current attributes
4833 change the current attributes to the specified set
4835 The attribute set can either be specified as a hexadecimal number or
4836 a combination of the following letters:
4851 Colors are coded either as a hexadecimal number or two letters specifying
4852 the desired background and foreground color (in that order). The following
4874 leave color unchanged
4876 The capitalized versions of the letter specify bright colors. You can also
4877 use the pseudo-color @samp{i} to set just the brightness and leave the color
4880 A one digit/letter color description is treated as foreground or
4881 background color dependent on the current attributes: if reverse mode is
4882 set, the background color is changed instead of the foreground color.
4883 If you don't like this, prefix the color with a @samp{.}. If you want
4884 the same behavior for two-letter color descriptions, also prefix them
4887 As a special case, @samp{%@{-@}} restores the attributes and colors that
4888 were set before the last change was made (i.e. pops one level of the
4889 color-change stack).
4895 set color to bright green
4899 clear all attributes, write in default color on yellow background.
4900 @item %-Lw%@{= BW@}%50>%n%f* %t%@{-@}%+Lw%<
4901 The available windows centered at the current win dow and truncated to
4902 the available width. The current window is displayed white on blue.
4903 This can be used with @samp{hardstatus alwayslastline}.
4904 @item %?%F%@{.R.@}%?%3n %t%? [%h]%?
4905 The window number and title and the window's hardstatus, if one is set.
4906 Also use a red background if this is the active focus.
4907 Useful for @samp{caption string}.
4911 @node Environment, Files, String Escapes, Top
4912 @chapter Environment Variables
4917 Number of columns on the terminal (overrides termcap entry).
4920 Directory in which to look for .screenrc.
4923 Number of lines on the terminal (overrides termcap entry).
4926 Screen lock program.
4928 @item NETHACKOPTIONS
4929 Turns on @code{nethack} option.
4932 Used for locating programs to run.
4935 For customizing a terminal's @code{TERMCAP} value.
4938 Alternate socket directory.
4941 Alternate user screenrc file.
4944 Default shell program for opening windows (default @file{/bin/sh}).
4947 Alternate socket name. If @code{screen} is invoked, and the environment variable
4948 @code{STY} is set, then it creates only a window in the running @code{screen}
4949 session rather than starting a new session.
4952 Alternate system screenrc file.
4958 Terminal description.
4961 Window number of a window (at creation time).
4964 @node Files, Credits, Environment, Top
4965 @chapter Files Referenced
4969 @item .../screen-4.?.??/etc/screenrc
4970 @itemx .../screen-4.?.??/etc/etcscreenrc
4971 Examples in the @code{screen} distribution package for private and
4972 global initialization files.
4974 @item @code{$SYSSCREENRC}
4975 @itemx /local/etc/screenrc
4976 @code{screen} initialization commands
4978 @item @code{$SCREENRC}
4979 @itemx @code{$HOME}/.iscreenrc
4980 @itemx @code{$HOME}/.screenrc
4981 Read in after /local/etc/screenrc
4983 @item @code{$SCREENDIR}/S-@var{login}
4985 @item /local/screens/S-@var{login}
4986 Socket directories (default)
4988 @item /usr/tmp/screens/S-@var{login}
4989 Alternate socket directories.
4991 @item @var{socket directory}/.termcap
4992 Written by the @code{dumptermcap} command
4994 @item /usr/tmp/screens/screen-exchange or
4995 @itemx /tmp/screen-exchange
4996 @code{screen} interprocess communication buffer
4998 @item hardcopy.[0-9]
4999 Screen images created by the hardcopy command
5001 @item screenlog.[0-9]
5002 Output log files created by the log command
5004 @item /usr/lib/terminfo/?/* or
5006 Terminal capability databases
5011 @item @code{$LOCKPRG}
5012 Program for locking the terminal.
5015 @node Credits, Bugs, Files, Top
5022 Originally created by Oliver Laumann, this latest version was
5023 produced by Wayne Davison, Juergen Weigert and Michael Schroeder.
5030 Ken Beal (kbeal@@amber.ssd.csd.harris.com),
5031 Rudolf Koenig (rfkoenig@@informatik.uni-erlangen.de),
5032 Toerless Eckert (eckert@@informatik.uni-erlangen.de),
5033 Wayne Davison (davison@@borland.com),
5034 Patrick Wolfe (pat@@kai.com, kailand!pat),
5035 Bart Schaefer (schaefer@@cse.ogi.edu),
5036 Nathan Glasser (nathan@@brokaw.lcs.mit.edu),
5037 Larry W. Virden (lvirden@@cas.org),
5038 Howard Chu (hyc@@hanauma.jpl.nasa.gov),
5039 Tim MacKenzie (tym@@dibbler.cs.monash.edu.au),
5040 Markku Jarvinen (mta@@@{cc,cs,ee@}.tut.fi),
5041 Marc Boucher (marc@@CAM.ORG),
5042 Doug Siebert (dsiebert@@isca.uiowa.edu),
5043 Ken Stillson (stillson@@tsfsrv.mitre.org),
5044 Ian Frechett (frechett@@spot.Colorado.EDU),
5045 Brian Koehmstedt (bpk@@gnu.ai.mit.edu),
5046 Don Smith (djs6015@@ultb.isc.rit.edu),
5047 Frank van der Linden (vdlinden@@fwi.uva.nl),
5048 Martin Schweikert (schweik@@cpp.ob.open.de),
5049 David Vrona (dave@@sashimi.lcu.com),
5050 E. Tye McQueen (tye%spillman.UUCP@@uunet.uu.net),
5051 Matthew Green (mrg@@eterna.com.au),
5052 Christopher Williams (cgw@@pobox.com),
5053 Matt Mosley (mattm@@access.digex.net),
5054 Gregory Neil Shapiro (gshapiro@@wpi.WPI.EDU),
5055 Jason Merrill (jason@@jarthur.Claremont.EDU),
5056 Johannes Zellner (johannes@@zellner.org),
5057 Pablo Averbuj (pablo@@averbuj.com).
5064 This manual describes version @value{version} of the @code{screen}
5065 program. Its roots are a merge of a custom version 2.3PR7 by Wayne
5066 Davison and several enhancements to Oliver Laumann's version 2.0.
5067 Note that all versions numbered 2.x are copyright by Oliver Laumann.
5069 See also @xref{Availability}.
5071 @node Bugs, Installation, Credits, Top
5075 Just like any other significant piece of software, @code{screen} has a
5076 few bugs and missing features. Please send in a bug report if you have
5077 found a bug not mentioned here.
5080 * Known Bugs:: Problems we know about.
5081 * Reporting Bugs:: How to contact the maintainers.
5082 * Availability:: Where to find the latest screen version.
5085 @node Known Bugs, Reporting Bugs, , Bugs
5090 @samp{dm} (delete mode) and @samp{xs} are not handled correctly (they
5091 are ignored). @samp{xn} is treated as a magic-margin indicator.
5094 @code{screen} has no clue about double-high or double-wide characters.
5095 But this is the only area where @code{vttest} is allowed to fail.
5098 It is not possible to change the environment variable @code{$TERMCAP}
5099 when reattaching under a different terminal type.
5102 The support of terminfo based systems is very limited. Adding extra
5103 capabilities to @code{$TERMCAP} may not have any effects.
5106 @code{screen} does not make use of hardware tabs.
5109 @code{screen} must be installed setuid root on most systems
5110 in order to be able to
5111 correctly change the owner of the tty device file for each window.
5112 Special permission may also be required to write the file
5116 Entries in @file{/etc/utmp} are not removed when @code{screen} is killed
5117 with SIGKILL. This will cause some programs (like "w" or "rwho") to
5118 advertise that a user is logged on who really isn't.
5121 @code{screen} may give a strange warning when your tty has no utmp
5125 When the modem line was hung up, @code{screen} may not automatically detach
5126 (or quit) unless the device driver sends a HANGUP signal. To detach such a
5127 @code{screen} session use the -D or -d command line option.
5130 If a password is set, the command line options -d and -D still detach a
5131 session without asking.
5134 Both @code{breaktype} and @code{defbreaktype} change the break generating
5135 method used by all terminal devices. The first should change a window
5136 specific setting, where the latter should change only the default for new
5140 When attaching to a multiuser session, the user's @file{.screenrc} file is not
5141 sourced. Each users personal settings have to be included in the
5142 @file{.screenrc} file from which the session is booted, or have to be
5146 A weird imagination is most useful to gain full advantage of all the
5150 @node Reporting Bugs, Availability, Known Bugs, Bugs
5151 @section Reporting Bugs
5154 If you find a bug in @code{Screen}, please send electronic mail to
5155 @w{@samp{screen@@uni-erlangen.de}}, and also to
5156 @w{@samp{bug-gnu-utils@@prep.ai.mit.edu}}. Include the version number
5157 of @code{Screen} which you are using. Also include in your message the
5158 hardware and operating system, the compiler used to compile, a
5159 description of the bug behavior, and the conditions that triggered the
5160 bug. Please recompile @code{screen} with the @samp{-DDEBUG} options
5161 enabled, reproduce the bug, and have a look at the debug output written to
5162 the directory @file{/tmp/debug}. If necessary quote suspect passages from the
5163 debug output and show the contents of your @file{config.h} if it matters.
5165 @node Availability, , Reporting Bugs, Bugs
5166 @section Availability
5167 @cindex availability
5169 @code{Screen} is available under the @code{GNU} copyleft.
5171 The latest official release of @code{screen} available via anonymous
5172 ftp from @samp{prep.ai.mit.edu}, @samp{nic.funet.fi} or any other
5173 @code{GNU} distribution site. The home site of
5174 @code{screen} is @samp{ftp.uni-erlangen.de
5175 (131.188.3.71)}, in the directory @file{pub/utilities/screen}.
5176 The subdirectory @samp{private} contains the latest beta testing release.
5177 If you want to help, send a note to screen@@uni-erlangen.de.
5179 @node Installation, Concept Index, Bugs, Top
5180 @chapter Installation
5181 @cindex installation
5183 Since @code{screen} uses pseudo-ttys, the select system call, and
5184 UNIX-domain sockets/named pipes, it will not run under a system that
5185 does not include these features of 4.2 and 4.3 BSD UNIX.
5188 * Socket Directory:: Where screen stores its handle.
5189 * Compiling Screen::
5192 @node Socket Directory,
5193 @section Socket Directory
5194 @cindex socket directory
5196 The socket directory defaults either to @file{$HOME/.screen} or simply to
5197 @file{/tmp/screens} or preferably to @file{/usr/local/screens} chosen at
5198 compile-time. If @code{screen} is installed
5199 setuid root, then the administrator should compile screen with an
5200 adequate (not NFS mounted) @code{SOCKDIR}. If @code{screen} is not
5201 running setuid-root, the user can specify any mode 700 directory in the
5202 environment variable @code{$SCREENDIR}.
5204 @node Compiling Screen, , Socket Directory, Installation
5205 @section Compiling Screen
5206 @cindex compiling screen
5208 To compile and install screen:
5210 The @code{screen} package comes with a @code{GNU Autoconf} configuration
5211 script. Before you compile the package run
5213 @center @code{sh ./configure}
5215 This will create a @file{config.h} and @file{Makefile} for your machine.
5216 If @code{configure} fails for some reason, then look at the examples and
5217 comments found in the @file{Makefile.in} and @file{config.h.in} templates.
5218 Rename @file{config.status} to @file{config.status.@var{machine}} when
5219 you want to keep configuration data for multiple architectures. Running
5220 @code{sh ./config.status.@var{machine}} recreates your configuration
5221 significantly faster than rerunning @code{configure}.
5223 Read through the "User Configuration" section of @file{config.h}, and verify
5224 that it suits your needs.
5225 A comment near the top of this section explains why it's best to
5226 install screen setuid to root.
5227 Check for the place for the global @file{screenrc}-file and for the socket
5230 Check the compiler used in @file{Makefile}, the prefix path where to install
5231 @code{screen}. Then run
5235 If @code{make} fails to produce one of the files @file{term.h}, @file{comm.h}
5236 or @file{tty.c}, then use @code{@var{filename.x}.dist} instead.
5237 For additional information about installation of @code{screen} refer to the
5238 file @file{INSTALLATION}, coming with this package.
5240 @node Concept Index, Command Index, Installation, Top
5241 @unnumbered Concept Index
5245 @node Command Index, Keystroke Index, Concept Index, Top
5246 @unnumbered Command Index
5248 This is a list of all the commands supported by @code{screen}.
5252 @node Keystroke Index, , Command Index, Top
5253 @unnumbered Keystroke Index
5255 This is a list of the default key bindings.
5257 The leading escape character (@pxref{Command Character}) has been omitted
5258 from the key sequences, since it is the same for all bindings.