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{Fit}.
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 horizontally 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 Split the current region vertically into two new ones. @xref{Regions}.
808 Show the copyright page. @xref{License}.
812 Show the listing of attached displays. @xref{Displays}.
815 @node Command Summary, , Default Key Bindings, Commands
816 @section Command Summary
817 @cindex command summary
820 @item acladd @var{usernames}
821 Allow other users in this session. @xref{Multiuser Session}.
822 @item aclchg @var{usernames permbits list}
823 Change a user's permissions. @xref{Multiuser Session}.
824 @item acldel @var{username}
825 Disallow other user in this session. @xref{Multiuser Session}.
826 @item aclgrp @var{usrname} [@var{groupname}]
827 Inherit permissions granted to a group leader. @xref{Multiuser Session}.
828 @item aclumask [@var{users}]+/-@var{bits} ...
829 Predefine access to new windows. @xref{Umask}.
830 @item activity @var{message}
831 Set the activity notification message. @xref{Monitor}.
832 @item addacl @var{usernames}
833 Synonym to @code{acladd}. @xref{Multiuser Session}.
834 @item allpartial @var{state}
835 Set all windows to partial refresh. @xref{Redisplay}.
836 @item altscreen @var{state}
837 Enables support for the "alternate screen" terminal capability. @xref{Redisplay}.
838 @item at [@var{ident}][@kbd{#}@var{|}@kbd{*}@var{|}@kbd{%}] @var{command} [@var{args}]
839 Execute a command at other displays or windows. @xref{At}.
840 @item attrcolor @var{attrib} [@var{attribute/color-modifier}]
841 Map attributes to colors. @xref{Attrcolor}.
842 @item autodetach @var{state}
843 Automatically detach the session on SIGHUP. @xref{Detach}.
844 @item autonuke @var{state}
845 Enable a clear screen to discard unwritten output. @xref{Autonuke}.
846 @item backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}]
847 Define a command for the backtick string escape. @xref{Backtick}.
848 @item bce [@var{state}]
849 Change background color erase. @xref{Character Processing}.
850 @item bell_msg [@var{message}]
851 Set the bell notification message. @xref{Bell}.
852 @item bind [-c @var{class}] @var{key} [@var{command} [@var{args}]]
853 Bind a command to a key. @xref{Bind}.
854 @item bindkey [@var{opts}] [@var{string} [@var{cmd args}]]
855 Bind a string to a series of keystrokes. @xref{Bindkey}.
857 Blank the screen. @xref{Screen Saver}.
859 Define a blanker program. @xref{Screen Saver}.
860 @item break [@var{duration}]
861 Send a break signal to the current window. @xref{Break}.
862 @item breaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}]
863 Specify how to generate breaks. @xref{Break}.
864 @item bufferfile [@var{exchange-file}]
865 Select a file for screen-exchange. @xref{Screen Exchange}.
866 @item c1 [@var{state}]
867 Change c1 code processing. @xref{Character Processing}.
868 @item caption @var{mode} [@var{string}]
869 Change caption mode and string. @xref{Regions}.
870 @item chacl @var{usernames permbits list}
871 Synonym to @code{aclchg}. @xref{Multiuser Session}.
872 @item charset @var{set}
873 Change character set slot designation. @xref{Character Processing}.
874 @item chdir [@var{directory}]
875 Change the current directory for future windows. @xref{Chdir}.
877 Clear the window screen. @xref{Clear}.
879 Enter a @code{screen} command. @xref{Colon}.
880 @item command [-c @var{class}]
881 Simulate the screen escape key. @xref{Command Character}.
882 @item compacthist [@var{state}]
883 Selects compaction of trailing empty lines. @xref{Scrollback}.
884 @item console [@var{state}]
885 Grab or ungrab console output. @xref{Console}.
887 Enter copy mode. @xref{Copy}.
888 @item copy_reg [@var{key}]
889 Removed. Use @code{paste} instead. @xref{Registers}.
890 @item crlf @var{state}
891 Select line break behavior for copying. @xref{Line Termination}.
892 @item debug @var{state}
893 Suppress/allow debugging output. @xref{Debug}.
894 @item defautonuke @var{state}
895 Select default autonuke behavior. @xref{Autonuke}.
896 @item defbce @var{state}
897 Select background color erase. @xref{Character Processing}.
898 @item defbreaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}]
899 Specify the default for generating breaks. @xref{Break}.
900 @item defc1 @var{state}
901 Select default c1 processing behavior. @xref{Character Processing}.
902 @item defcharset [@var{set}]
903 Change defaul character set slot designation. @xref{Character Processing}.
904 @item defencoding @var{enc}
905 Select default window encoding. @xref{Character Processing}.
906 @item defescape @var{xy}
907 Set the default command and @code{meta} characters. @xref{Command Character}.
908 @item defflow @var{fstate}
909 Select default flow control behavior. @xref{Flow}.
910 @item defgr @var{state}
911 Select default GR processing behavior. @xref{Character Processing}.
912 @item defhstatus [@var{status}]
913 Select default window hardstatus line. @xref{Hardstatus}.
914 @item deflog @var{state}
915 Select default window logging behavior. @xref{Log}.
916 @item deflogin @var{state}
917 Select default utmp logging behavior. @xref{Login}.
918 @item defmode @var{mode}
919 Select default file mode for ptys. @xref{Mode}.
920 @item defmonitor @var{state}
921 Select default activity monitoring behavior. @xref{Monitor}.
922 @item defmousetrack @var{on}|@var{off}
923 Select the default mouse tracking behavior. @xref{Mousetrack}.
924 @item defnonblock @var{state}|@var{numsecs}
925 Select default nonblock mode. @xref{Nonblock}.
926 @item defobuflimit @var{limit}
927 Select default output buffer limit. @xref{Obuflimit}.
928 @item defscrollback @var{num}
929 Set default lines of scrollback. @xref{Scrollback}.
930 @item defshell @var{command}
931 Set the default program for new windows. @xref{Shell}.
932 @item defsilence @var{state}
933 Select default idle monitoring behavior. @xref{Silence}.
934 @item defslowpaste @var{msec}
935 Select the default inter-character timeout when pasting. @xref{Paste}.
936 @item defutf8 @var{state}
937 Select default character encoding. @xref{Character Processing}.
938 @item defwrap @var{state}
939 Set default line-wrapping behavior. @xref{Wrap}.
940 @item defwritelock @var{on|off|auto}
941 Set default writelock behavior. @xref{Multiuser Session}.
942 @item defzombie [@var{keys}]
943 Keep dead windows. @xref{Zombie}.
945 Disconnect @code{screen} from the terminal. @xref{Detach}.
947 Enter digraph sequence. @xref{Digraph}.
949 Display terminal information. @xref{Info}.
951 List currently active user interfaces. @xref{Displays}.
953 Write the window's termcap entry to a file. @xref{Dump Termcap}.
954 @item echo [-n] @var{message}
955 Display a message on startup. @xref{Startup}.
956 @item encoding @var{enc} [@var{denc}]
957 Set the encoding of a window. @xref{Character Processing}.
958 @item escape @var{xy}
959 Set the command and @code{meta} characters. @xref{Command Character}.
960 @item eval @var{command1} [@var{command2} ...]
961 Parse and execute each argument. @xref{Eval}.
962 @item exec [[@var{fdpat}] @var{command} [@var{args} ...]]
963 Run a subprocess (filter). @xref{Exec}.
965 Change window size to current display size. @xref{Window Size}.
966 @item flow [@var{fstate}]
967 Set flow control behavior. @xref{Flow}.
969 Move focus to next region. @xref{Regions}.
970 @item gr [@var{state}]
971 Change GR charset processing. @xref{Character Processing}.
972 @item group [@var{grouptitle}]
973 Change or show the group the current window belongs to. @xref{Window Groups}.
974 @item hardcopy [-h] [@var{file}]
975 Write out the contents of the current window. @xref{Hardcopy}.
976 @item hardcopy_append @var{state}
977 Append to hardcopy files. @xref{Hardcopy}.
978 @item hardcopydir @var{directory}
979 Place, where to dump hardcopy files. @xref{Hardcopy}.
980 @item hardstatus [@var{state}]
981 Use the hardware status line. @xref{Hardware Status Line}.
982 @item height [@var{lines} [@var{cols}]]
983 Set display height. @xref{Window Size}.
984 @item help [-c @var{class}]
985 Display current key bindings. @xref{Help}.
987 Find previous command beginning @dots{}. @xref{History}.
988 @item hstatus @var{status}
989 Change the window's hardstatus line. @xref{Hardstatus}.
990 @item idle [@var{timeout} [@var{cmd} @var{args}]]
991 Define a screen saver command. @xref{Screen Saver}.
992 @item ignorecase [@var{state}]
993 Ignore character case in searches. @xref{Searching}.
995 Display window settings. @xref{Info}.
996 @item ins_reg [@var{key}]
997 Removed, use @code{paste} instead. @xref{Registers}.
999 Destroy the current window. @xref{Kill}.
1001 Redisplay the last message. @xref{Last Message}.
1003 Display licensing information. @xref{Startup}.
1005 Lock the controlling terminal. @xref{Lock}.
1006 @item log [@var{state}]
1007 Log all output in the current window. @xref{Log}.
1008 @item logfile @var{filename}
1009 Place where to collect logfiles. @xref{Log}.
1010 @item login [@var{state}]
1011 Log the window in @file{/etc/utmp}. @xref{Login}.
1012 @item logtstamp [@var{state}]
1013 Configure logfile time-stamps. @xref{Log}.
1015 Use only the default mapping table for the next keystroke. @xref{Bindkey Control}.
1017 Don't try to do keymapping on the next keystroke. @xref{Bindkey Control}.
1018 @item maptimeout @var{timo}
1019 Set the inter-character timeout used for keymapping. @xref{Bindkey Control}.
1020 @item markkeys @var{string}
1021 Rebind keys in copy mode. @xref{Copy Mode Keys}.
1022 @item maxwin @var{n}
1023 Set the maximum window number. @xref{Maxwin}.
1025 Insert the command character. @xref{Command Character}.
1026 @item monitor [@var{state}]
1027 Monitor activity in window. @xref{Monitor}.
1028 @item mousetrack [@var{on}|@var{off}]
1029 Enable selecting splitted regions with mouse clicks. @xref{Mousetrack}.
1030 @item msgminwait @var{sec}
1031 Set minimum message wait. @xref{Message Wait}.
1032 @item msgwait @var{sec}
1033 Set default message wait. @xref{Message Wait}.
1034 @item multiuser @var{state}
1035 Go into single or multi user mode. @xref{Multiuser Session}.
1036 @item nethack @var{state}
1037 Use @code{nethack}-like error messages. @xref{Nethack}.
1039 Switch to the next window. @xref{Selecting}.
1040 @item nonblock [@var{state}|@var{numsecs}]
1041 Disable flow control to the current display. @xref{Nonblock}.|@var{numsecs}]
1042 @item number [@var{n}]
1043 Change/display the current window's number. @xref{Number}.
1044 @item obuflimit [@var{limit}]
1045 Select output buffer limit. @xref{Obuflimit}.
1047 Kill all other regions. @xref{Regions}.
1049 Switch to the window you were in last. @xref{Selecting}.
1050 @item partial @var{state}
1051 Set window to partial refresh. @xref{Redisplay}.
1052 @item password [@var{crypted_pw}]
1053 Set reattach password. @xref{Detach}.
1054 @item paste [@var{src_regs} [@var{dest_reg}]]
1055 Paste contents of paste buffer or registers somewhere. @xref{Paste}.
1056 @item pastefont [@var{state}]
1057 Include font information in the paste buffer. @xref{Paste}.
1059 Close and Reopen the window's terminal. @xref{Break}.
1061 Detach and hang up. @xref{Power Detach}.
1062 @item pow_detach_msg [@var{message}]
1063 Set message displayed on @code{pow_detach}. @xref{Power Detach}.
1065 Switch to the previous window. @xref{Selecting}.
1066 @item printcmd [@var{cmd}]
1067 Set a command for VT100 printer port emulation. @xref{Printcmd}.
1068 @item process [@var{key}]
1069 Treat a register as input to @code{screen}. @xref{Registers}.
1071 Kill all windows and exit. @xref{Quit}.
1072 @item readbuf [-e @var{encoding}] [@var{filename}]
1073 Read the paste buffer from the screen-exchange file. @xref{Screen Exchange}.
1074 @item readreg [-e @var{encoding}] [@var{reg} [@var{file}]]
1075 Load a register from paste buffer or file. @xref{Registers}.
1077 Redisplay the current window. @xref{Redisplay}.
1078 @item register [-e @var{encoding}] @var{key} @var{string}
1079 Store a string to a register. @xref{Registers}.
1081 Kill current region. @xref{Regions}.
1083 Delete the screen-exchange file. @xref{Screen Exchange}.
1084 @item rendition bell | monitor | so @var{attr} [@var{color}]
1085 Change text attributes in caption for flagged windows. @xref{Rendition}.
1087 Reset the terminal settings for the window. @xref{Reset}.
1088 @item resize [(+/-)lines]
1089 Grow or shrink a region
1090 @item screen [@var{opts}] [@var{n}] [@var{cmd} [@var{args}] | //group]
1091 Create a new window. @xref{Screen Command}.
1092 @item scrollback @var{num}
1093 Set size of scrollback buffer. @xref{Scrollback}.
1094 @item select [@var{n}|-|.]
1095 Switch to a specified window. @xref{Selecting}.
1096 @item sessionname [@var{name}]
1097 Name this session. @xref{Session Name}.
1098 @item setenv [@var{var} [@var{string}]]
1099 Set an environment variable for new windows. @xref{Setenv}.
1100 @item setsid @var{state}
1101 Controll process group creation for windows. @xref{Setsid}.
1102 @item shell @var{command}
1103 Set the default program for new windows. @xref{Shell}.
1104 @item shelltitle @var{title}
1105 Set the default name for new windows. @xref{Shell}.
1106 @item silence [@var{state}|@var{seconds}]
1107 Monitor a window for inactivity. @xref{Silence}.
1108 @item silencewait @var{seconds}
1109 Default timeout to trigger an inactivity notify. @xref{Silence}.
1110 @item sleep @var{num}
1111 Pause during startup. @xref{Startup}.
1112 @item slowpaste @var{msec}
1113 Slow down pasting in windows. @xref{Paste}.
1114 @item source @var{file}
1115 Run commands from a file. @xref{Source}.
1116 @item sorendition [@var{attr} [@var{color}]]
1117 Deprecated. Use @code{rendition so} instead. @xref{Rendition}.
1119 Split region into two parts. @xref{Regions}.
1120 @item startup_message @var{state}
1121 Display copyright notice on startup. @xref{Startup}.
1122 @item stuff @var{string}
1123 Stuff a string in the input buffer of a window. @xref{Paste}.
1124 @item su [@var{username} [@var{password} [@var{password2}]]]
1125 Identify a user. @xref{Multiuser Session}.
1127 Put session in background. @xref{Suspend}.
1128 @item term @var{term}
1129 Set @code{$TERM} for new windows. @xref{Term}.
1130 @item termcap @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1131 Tweak termcap entries for best performance. @xref{Termcap Syntax}.
1132 @item terminfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1133 Ditto, for terminfo systems. @xref{Termcap Syntax}.
1134 @item termcapinfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}]
1135 Ditto, for both systems. @xref{Termcap Syntax}.
1136 @item time [@var{string}]
1137 Display time and load average. @xref{Time}.
1138 @item title [@var{windowtitle}]
1139 Set the name of the current window. @xref{Title Command}.
1140 @item umask [@var{users}]+/-@var{bits} ...
1141 Synonym to @code{aclumask}. @xref{Umask}.
1143 Unset all keybindings. @xref{Bind}.
1144 @item unsetenv @var{var}
1145 Unset environment variable for new windows. @xref{Setenv}.
1146 @item utf8 [@var{state} [@var{dstate}]]
1147 Select character encoding of the current window. @xref{Character Processing}.
1148 @item vbell [@var{state}]
1149 Use visual bell. @xref{Bell}.
1150 @item vbell_msg [@var{message}]
1151 Set vbell message. @xref{Bell}.
1152 @item vbellwait @var{sec}
1153 Set delay for vbell message. @xref{Bell}.
1155 Display @code{screen} version. @xref{Version}.
1156 @item wall @var{message}
1157 Write a message to all displays. @xref{Multiuser Session}.
1158 @item width [@var{cols} [@var{lines}]]
1159 Set the width of the window. @xref{Window Size}.
1160 @item windowlist [[-b] [-m] [-g]] | string [@var{string}] | title [@var{title}]
1161 Present a list of all windows for selection. @xref{Windowlist}.
1163 List active windows. @xref{Windows}.
1164 @item wrap [@var{state}]
1165 Control line-wrap behavior. @xref{Wrap}.
1166 @item writebuf [-e @var{encoding}] [@var{filename}]
1167 Write paste buffer to screen-exchange file. @xref{Screen Exchange}.
1168 @item writelock @var{on}|@var{off}|@var{auto}
1169 Grant exclusive write permission. @xref{Multiuser Session}.
1171 Send an XOFF character. @xref{XON/XOFF}.
1173 Send an XON character. @xref{XON/XOFF}.
1174 @item zmodem [off|auto|catch|pass]
1175 Define how screen treats zmodem requests. @xref{Zmodem}.
1176 @item zombie [@var{keys} [onerror] ]
1177 Keep dead windows. @xref{Zombie}.
1180 @node New Window, Selecting, Commands, Top
1183 This section describes the commands for creating a new window for
1184 running programs. When a new window is created, the first available
1185 number from the range 0@dots{}9 is assigned to it.
1186 The number of windows is limited at compile-time by the MAXWIN
1187 configuration parameter.
1190 * Chdir:: Change the working directory for new windows.
1191 * Screen Command:: Create a new window.
1192 * Setenv:: Set environment variables for new windows.
1193 * Shell:: Parameters for shell windows.
1194 * Term:: Set the terminal type for new windows.
1195 * Window Types:: Creating different types of windows.
1196 * Window Groups:: Grouping windows together
1199 @node Chdir, Screen Command, , New Window
1201 @deffn Command chdir [directory]
1203 Change the current directory of @code{screen} to the specified directory
1204 or, if called without an argument, to your home directory (the value of
1205 the environment variable @code{$HOME}). All windows that are created by means
1206 of the @code{screen} command from within @file{.screenrc} or by means of
1207 @kbd{C-a : screen @dots{}} or @kbd{C-a c} use this as their default
1208 directory. Without a @code{chdir} command, this would be the directory
1209 from which @code{screen} was invoked. Hardcopy and log files are always
1210 written to the @emph{window's} default directory, @emph{not} the current
1211 directory of the process running in the window. You can use this
1212 command multiple times in your @file{.screenrc} to start various windows
1213 in different default directories, but the last @code{chdir} value will
1214 affect all the windows you create interactively.
1217 @node Screen Command, Setenv, Chdir, New Window
1218 @section Screen Command
1221 @deffn Command screen [opts] [n] [cmd [args] @var{| //group}]
1222 (@kbd{C-a c}, @kbd{C-a C-c})@*
1223 Establish a new window. The flow-control options (@samp{-f}, @samp{-fn}
1224 and @samp{-fa}), title option (@samp{-t}), login options
1225 (@samp{-l} and @samp{-ln}) , terminal type option (@samp{-T @var{term}}),
1226 the all-capability-flag (@samp{-a}) and scrollback option
1227 (@samp{-h @var{num}}) may be specified with each command.
1228 The option (@samp{-M}) turns monitoring on for this window.
1229 The option (@samp{-L}) turns output logging on for this window.
1230 If an optional number @var{n} in the range 0@dots{}9 is given,
1231 the window number @var{n} is assigned to the newly created window (or,
1232 if this number is already in-use, the next available number). If a
1233 command is specified after @code{screen}, this command (with the given
1234 arguments) is started in the window; otherwise, a shell is created.
1235 If @samp{//group} is supplied, a container-type window is created in
1236 which other windows may be created inside it. @xref{Window Groups}.
1238 Screen has built in some functionality of @samp{cu} and @samp{telnet}.
1239 @xref{Window Types}.
1242 Thus, if your @file{.screenrc} contains the lines
1245 # example for .screenrc:
1247 screen -fn -t foobar 2 -L telnet foobar
1251 @code{screen} creates a shell window (in window #1) and a window with a
1252 TELNET connection to the machine foobar (with no flow-control using the
1253 title @samp{foobar} in window #2) and will write a logfile @samp{screenlog.2}
1254 of the telnet session. If you do not include any
1255 @code{screen} commands in your @file{.screenrc} file, then @code{screen}
1256 defaults to creating a single shell window, number zero. When the
1257 initialization is completed, @code{screen} switches to the last window
1258 specified in your .screenrc file or, if none, it opens default window
1261 @node Setenv, Shell, Screen Command, New Window
1263 @deffn Command setenv var string
1265 Set the environment variable @var{var} to value @var{string}.
1266 If only @var{var} is specified, the user will be prompted to enter a value.
1267 If no parameters are specified, the user will be prompted for both variable
1268 and value. The environment is inherited by all subsequently forked shells.
1271 @deffn Command unsetenv var
1273 Unset an environment variable.
1276 @node Shell, Term, Setenv, New Window
1278 @deffn Command shell command
1279 @deffnx Command defshell command
1281 Set the command to be used to create a new shell. This overrides the
1282 value of the environment variable @code{$SHELL}. This is useful if
1283 you'd like to run a tty-enhancer which is expecting to execute the
1284 program specified in @code{$SHELL}. If the command begins with
1285 a @samp{-} character, the shell will be started as a login-shell.
1287 @code{defshell} is currently a synonym to the @code{shell} command.
1290 @deffn Command shelltitle title
1292 Set the title for all shells created during startup or by the C-a C-c
1293 command. @xref{Naming Windows}, for details about what titles are.
1296 @node Term, Window Types , Shell, New Window
1298 @deffn Command term term
1300 In each window @code{screen} opens, it sets the @code{$TERM}
1301 variable to @code{screen} by default, unless no description for
1302 @code{screen} is installed in the local termcap or terminfo data base.
1303 In that case it pretends that the terminal emulator is @samp{vt100}.
1304 This won't do much harm, as @code{screen} is VT100/ANSI compatible. The
1305 use of the @code{term} command is discouraged for non-default purpose.
1306 That is, one may want to specify special @code{$TERM} settings (e.g. vt100) for
1307 the next @code{screen rlogin othermachine} command. Use the command
1308 @code{screen -T vt100 rlogin othermachine} rather than setting
1309 and resetting the default.
1312 @node Window Types, Window Groups, Term, New Window
1313 @section Window Types
1314 @cindex window types
1315 Screen provides three different window types. New windows are created
1316 with @code{screen}'s @samp{screen} command (@pxref{Screen Command}).
1317 The first parameter to the @samp{screen} command defines which
1318 type of window is created. The different window types are all
1319 special cases of the normal type. They have been added in order
1320 to allow @code{screen} to be used efficiently as a console
1321 with 100 or more windows.
1324 The normal window contains a shell (default, if no parameter is given)
1325 or any other system command that could be executed from a shell.
1326 (e.g. @samp{slogin}, etc...).
1329 If a tty (character special device) name (e.g. @samp{/dev/ttya})
1330 is specified as the first parameter, then the window is directly
1331 connected to this device.
1332 This window type is similar to @samp{screen cu -l /dev/ttya}.
1333 Read and write access is required on the device node,
1334 an exclusive open is attempted on the node to mark the connection line
1336 An optional parameter is allowed consisting of a comma separated
1337 list of flags in the notation used by @samp{stty(1)}:
1340 Usually 300, 1200, 9600 or 19200. This affects transmission as well as
1343 Specify the transmission of eight (or seven) bits per byte.
1345 Enables (or disables) software flow-control (CTRL-S/CTRL-Q) for sending
1347 @item ixoff or -ixoff
1348 Enables (or disables) software flow-control for receiving data.
1349 @item istrip or -istrip
1350 Clear (or keep) the eight bit in each received byte.
1353 You may want to specify as many of these options as applicable.
1354 Unspecified options cause the terminal driver to make up the parameter
1355 values of the connection. These values are system-dependent and may be
1356 in defaults or values saved from a previous connection.
1358 For tty windows, the @code{info} command shows some of the modem
1359 control lines in the status line.
1360 These may include @samp{RTS}, @samp{CTS}, @samp{DTR}, @samp{CD} and
1361 more. This depends rather on on the available @code{ioctl()}'s and system
1362 header files than on the physical capabilities of the serial board.
1363 The name of a logical low (inactive) signal is preceded by an
1364 exclamation mark (@samp{!}), otherwise the signal is logical high (active).
1365 Unsupported but shown signals are usually shown low.
1366 When the @code{CLOCAL} status bit is true, the whole set of modem signals is
1367 placed inside curly braces (@samp{@{} and @samp{@}}).
1368 When the @code{CRTSCTS} or @code{TIOCSOFTCAR} bit is true, the signals
1369 @samp{CTS} or @samp{CD} are shown in parenthesis, respectively.
1371 For tty windows, the command @code{break} causes the Data transmission
1372 line (TxD) to go low for a specified period of time. This is expected
1373 to be interpreted as break signal on the other side.
1374 No data is sent and no modem control line is changed when a
1375 @code{break} is issued.
1378 If the first parameter is @code{//telnet}, the second parameter is
1379 expected to be a host name, and an optional third parameter may specify
1380 a TCP port number (default decimal 23). Screen will connect to a
1381 server listening on the remote host and use the telnet protocol to
1382 communicate with that server.
1384 For telnet windows, the command @code{info} shows details about
1385 the connection in square brackets (@samp{[} and @samp{]}) at the end of
1389 BINARY. The connection is in binary mode.
1391 ECHO. Local echo is disabled.
1393 SGA. The connection is in `character mode' (default: `line mode').
1395 TTYPE. The terminal type has been requested by the remote host. Screen
1396 sends the name @code{screen} unless instructed otherwise (see also the
1397 command @samp{term}).
1399 NAWS. The remote site is notified about window size changes.
1401 LFLOW. The remote host will send flow control information.
1402 (Ignored at the moment.)
1404 Additional flags for debugging are @samp{x}, @samp{t} and @samp{n}
1405 (XDISPLOC, TSPEED and NEWENV).
1407 For telnet windows, the command @code{break} sends the telnet code
1408 @code{IAC BREAK} (decimal 243) to the remote host.
1412 @node Window Groups, , Window Types, New Window
1413 @section Window Groups
1414 @cindex window groups
1415 Screen provides a method for grouping windows together. Windows can be
1416 organized in a heirarchial fashion, resembling a tree structure. New
1417 screens are created using the @code{screen} command while new groups
1418 are created using @code{screen //group}. @xref{Screen Command}.
1420 Once a new group is created, it will act as a container for windows
1421 and even other groups. When a group is selected, you will see the
1422 output of the @code{windowlist} command, allowing you to select a
1423 window inside. If there are no windows inside a group, use the
1424 @code{screen} command to create one. Once inside a group, using the
1425 commands @code{next} and @code{prev} will switch between windows only
1426 in that group. Using the @code{windowlist} command will give you the
1427 opportunity to leave the group you are in. @xref{Windowlist}.
1429 @deffn Command group [grouptitle]
1430 Change or show the group the current window belongs to. Windows can
1431 be moved around between different groups by specifying the name of
1432 the destination group. Without specifying a group, the title of the
1433 current group is displayed.
1436 Using groups in combination with layouts will help create a
1437 multi-desktop experience. One group can be assigned for each
1438 layout made. Windows can be made, split, and organized within each
1439 group as desired. Afterwhich, switching between groups can be as easy
1440 as switching layouts.
1442 @node Selecting, Session Management, New Window, Top
1443 @chapter Selecting a Window
1445 This section describes the commands for switching between windows in an
1446 @code{screen} session. The windows are numbered from 0 to 9, and are created
1447 in that order by default (@pxref{New Window}).
1450 * Next and Previous:: Forward or back one window.
1451 * Other Window:: Switch back and forth between two windows.
1452 * Select:: Switch to a window (and to one after @code{kill}).
1453 * Windowlist:: Present a list of all windows for selection.
1456 @node Next and Previous, Other Window, , Selecting
1457 @section Moving Back and Forth
1462 (@kbd{C-a @key{SPC}}, @kbd{C-a n}, @kbd{C-a C-n})@*
1463 Switch to the next window. This command can be used repeatedly to
1464 cycle through the list of windows. (On some terminals, C-@key{SPC}
1465 generates a NUL character, so you must release the control key before
1474 (@kbd{C-a p}, @kbd{C-a C-p}, @kbd{C-a C-h}, @kbd{C-a @key{Backspace}})@*
1475 Switch to the previous window (the opposite of @kbd{C-a n}).
1478 @node Other Window, Select, Next and Previous, Selecting
1479 @section Other Window
1481 @deffn Command other
1483 Switch to the last window displayed. Note that this command
1484 defaults to the command character typed twice, unless overridden.
1485 For instance, if you use the option @samp{-e]x},
1486 this command becomes @kbd{]]} (@pxref{Command Character}).
1489 @node Select, Windowlist, Other Window, Selecting
1493 @deffn Command select [n @var{|-|.}]
1494 (@kbd{C-a @var{n}}, @kbd{C-a '})@*
1495 Switch to the window with the number @var{n}.
1496 If no window number is specified, you get prompted for an
1497 identifier. This can be a window name (title) or a number.
1498 When a new window is established, the lowest available number
1499 is assigned to this window.
1500 Thus, the first window can be activated by @code{select 0}; there
1501 can be no more than 10 windows present simultaneously (unless screen is
1502 compiled with a higher MAXWIN setting).
1503 There are two special arguments, @code{select -} switches to the
1504 internal blank window and @code{select .} switches to the
1505 current window. The latter is useful if used with screen's
1510 @node Windowlist, , Select, Selecting
1513 @deffn Command windowlist [-b] [-m] [-g]
1514 @deffnx Command windowlist string [@var{string}]
1515 @deffnx Command windowlist title [@var{title}]
1517 Display all windows in a table for visual window selection.
1518 The desired window can be selected via the standard
1519 movement keys (@pxref{Movement}) and activated via
1520 the return key. If screen was in a window group, screen will
1521 back out of the group and then display the windows in that
1522 group. If the @code{-b} option is given, screen will
1523 switch to the blank window before presenting the list, so
1524 that the current window is also selectable.
1525 The @code{-m} option changes the order of the windows, instead of
1526 sorting by window numbers screen uses its internal most-recently-used
1527 list. The @code{-g} option will show the windows inside any groups
1528 in that level and downwards.
1530 The table format can be changed with the string and title
1531 option, the title is displayed as table heading, while the
1532 lines are made by using the string setting. The default
1533 setting is @samp{Num Name%=Flags} for the title and
1534 @samp{%3n %t%=%f} for the lines. See the string escapes chapter
1535 (@pxref{String Escapes}) for more codes (e.g. color settings).
1539 @node Session Management, Regions, Selecting, Top
1540 @chapter Session Management Commands
1542 Perhaps the most useful feature of @code{screen} is the way it allows
1543 the user to move a session between terminals, by detaching and
1544 reattaching. This also makes life easier for modem users who have to
1545 deal with unexpected loss of carrier.
1548 * Detach:: Disconnect @code{screen} from your terminal.
1549 * Power Detach:: Detach and log out.
1550 * Lock:: Lock your terminal temporarily.
1551 * Multiuser Session:: Changing number of allowed users.
1552 * Session Name:: Rename your session for later reattachment.
1553 * Suspend:: Suspend your session.
1554 * Quit:: Terminate your session.
1557 @node Detach, Power Detach, , Session Management
1560 @deffn Command autodetach state
1562 Sets whether @code{screen} will automatically detach upon hangup, which
1563 saves all your running programs until they are resumed with a
1564 @code{screen -r} command. When turned off, a hangup signal will
1565 terminate @code{screen} and all the processes it contains. Autodetach is
1571 @deffn Command detach
1572 (@kbd{C-a d}, @kbd{C-a C-d})@*
1573 Detach the @code{screen} session (disconnect it from the terminal and
1574 put it into the background). A detached @code{screen} can be resumed by
1575 invoking @code{screen} with the @code{-r} option (@pxref{Invoking
1577 The @code{-h} option tells screen to immediately close the connection
1578 to the terminal (@samp{hangup}).
1581 @deffn Command password [crypted_pw]
1583 Present a crypted password in your @file{.screenrc} file and screen will
1584 ask for it, whenever someone attempts to resume a detached session. This
1585 is useful, if you have privileged programs running under @code{screen}
1586 and you want to protect your session from reattach attempts by users
1587 that managed to assume your uid. (I.e. any superuser.) If no crypted
1588 password is specified, screen prompts twice a password and places its
1589 encryption in the paste buffer. Default is `none', which disables
1593 @node Power Detach, Lock, Detach, Session Management
1594 @section Power Detach
1597 @deffn Command pow_detach
1599 Mainly the same as @code{detach}, but also sends a HANGUP signal
1600 to the parent process of @code{screen}.@*
1601 @emph{Caution}: This will result in a
1602 logout if @code{screen} was started from your login shell.
1605 @deffn Command pow_detach_msg [message]
1607 The @var{message} specified here is output whenever a power detach is
1608 performed. It may be used as a replacement for a logout message or to reset
1610 Without parameter, the current message is shown.
1613 @node Lock, Multiuser Session, Power Detach, Session Management
1617 @deffn Command lockscreen
1618 (@kbd{C-a x}, @kbd{C-a C-x})@*
1619 Call a screenlock program (@file{/local/bin/lck} or @file{/usr/bin/lock}
1620 or a builtin, if no other is available). Screen does not accept any
1621 command keys until this program terminates. Meanwhile processes in the
1622 windows may continue, as the windows are in the detached state.
1623 The screenlock program may be changed through the environment variable
1624 @code{$LOCKPRG} (which must be set in the shell from which @code{screen}
1625 is started) and is executed with the user's uid and gid.
1627 Warning: When you leave other shells unlocked and have no password set
1628 on @code{screen}, the lock is void: One could easily re-attach from an
1629 unlocked shell. This feature should rather be called
1630 @code{lockterminal}.
1633 @node Multiuser Session, Session Name, Lock, Session Management
1634 @section Multiuser Session
1635 @cindex multiuser session
1637 These commands allow other users to gain access to one single @code{screen}
1638 session. When attaching to a multiuser @code{screen} the sessionname is
1639 specified as @code{username/sessionname} to the @code{-S} command line option.
1640 @code{Screen} must be compiled with multiuser support to enable features
1644 * Multiuser:: Enable / Disable multiuser mode.
1645 * Acladd:: Enable a specific user.
1646 * Aclchg:: Change a users permissions.
1647 * Acldel:: Disable a specific user.
1648 * Aclgrp:: Grant a user permissions to other users.
1649 * Displays:: List all active users at their displays.
1650 * Umask:: Predefine access to new windows.
1651 * Wall:: Write a message to all users.
1652 * Writelock:: Grant exclusive window access.
1653 * Su:: Substitute user.
1656 @node Multiuser, Acladd, , Multiuser Session
1657 @subsection Multiuser
1658 @deffn Command multiuser @var{state}
1660 Switch between single-user and multi-user mode. Standard screen operation is
1661 single-user. In multi-user mode the commands @code{acladd}, @code{aclchg} and
1662 @code{acldel} can be used to enable (and disable) other users accessing this
1666 @node Acladd, Aclchg, Multiuser, Multiuser Session
1668 @deffn Command acladd @var{usernames}
1669 @deffnx Command addacl @var{usernames}
1671 Enable users to fully access this screen session. @var{Usernames} can be one
1672 user or a comma separated list of users. This command enables to attach to
1673 the @code{screen} session and performs the equivalent of
1674 @code{aclchg @var{usernames} +rwx "#?"}. To add a user with restricted access,
1675 use the @code{aclchg} command below.
1676 @code{Addacl} is a synonym to @code{acladd}.
1677 Multi-user mode only.
1680 @node Aclchg, Acldel, Acladd, Multiuser Session
1682 @deffn Command aclchg @var{usernames permbits list}
1683 @deffnx Command chacl @var{usernames permbits list}
1685 Change permissions for a comma separated list of users.
1686 Permission bits are represented as @samp{r}, @samp{w} and @samp{x}.
1687 Prefixing @samp{+} grants the permission, @samp{-} removes it. The third
1688 parameter is a comma separated list of commands or windows (specified either
1689 by number or title). The special list @samp{#} refers to all windows, @samp{?}
1690 to all commands. If @var{usernames} consists of a single @samp{*}, all
1691 known users are affected.
1692 A command can be executed when the user has the @samp{x} bit for it. The user
1693 can type input to a window when he has its @samp{w} bit set and no other
1694 user obtains a writelock for this window. Other bits are currently ignored.
1695 To withdraw the writelock from another user in e.g. window 2:
1696 @samp{aclchg @var{username} -w+w 2}. To allow read-only access
1697 to the session: @samp{aclchg @var{username} -w "#"}. As soon as a user's name
1698 is known to screen, he can attach to the session and (per default) has full
1699 permissions for all command and windows. Execution permission for the acl
1700 commands, @code{at} and others should also be removed or the user may be able
1701 to regain write permission.
1702 @code{Chacl} is a synonym to @code{aclchg}.
1703 Multi-user mode only.
1706 @node Acldel, Aclgrp, Aclchg, Multiuser Session
1708 @deffn Command acldel @var{username}
1710 Remove a user from screen's access control list. If currently attached, all the
1711 user's displays are detached from the session. He cannot attach again.
1712 Multi-user mode only.
1715 @node Aclgrp, Displays, Acldel, Multiuser Session
1717 @deffn Command aclgrp @var{username} [@var{groupname}]
1719 Creates groups of users that share common access rights. The
1720 name of the group is the username of the group leader. Each
1721 member of the group inherits the permissions that are
1722 granted to the group leader. That means, if a user fails an
1723 access check, another check is made for the group leader.
1724 A user is removed from all groups the special value @samp{none}
1725 is used for @var{groupname}. If the second parameter is omitted
1726 all groups the user is in are listed.
1729 @node Displays, Umask, Aclgrp, Multiuser Session
1730 @subsection Displays
1732 @deffn Command displays
1734 Shows a tabular listing of all currently connected user
1735 front-ends (displays). This is most useful for multiuser
1739 @node Umask, Wall, Displays, Multiuser Session
1740 @subsection aclumask
1741 @deffn Command aclumask [@var{users}]+/-@var{bits} ...
1742 @deffnx Command umask [@var{users}]+/-@var{bits} ...
1744 This specifies the access other users have to windows that
1745 will be created by the caller of the command. @var{Users} may be no,
1746 one or a comma separated list of known usernames. If no users are
1747 specified, a list of all currently known users is assumed.
1748 @var{Bits} is any combination of access control bits allowed
1749 defined with the @code{aclchg} command. The special username @samp{?}
1750 predefines the access that not yet known users will be
1751 granted to any window initially. The special username @samp{??}
1752 predefines the access that not yet known users are granted
1753 to any command. Rights of the special username nobody cannot
1754 be changed (see the @code{su} command).
1755 @code{Umask} is a synonym to @code{aclumask}.
1759 @node Wall, Writelock, Umask, Multiuser Session
1761 @deffn Command wall @var{message}
1763 Write a message to all displays. The message will appear in the terminal's
1767 @node Writelock, Su , Wall, Multiuser Session
1768 @subsection Writelock
1769 @deffn Command writelock @var{on|off|auto}
1771 In addition to access control lists, not all users may be able to write to
1772 the same window at once. Per default, writelock is in @samp{auto} mode and
1773 grants exclusive input permission to the user who is the first to switch
1774 to the particular window. When he leaves the window, other users may obtain
1775 the writelock (automatically). The writelock of the current window is disabled
1776 by the command @code{writelock off}. If the user issues the command
1777 @code{writelock on} he keeps the exclusive write permission while switching
1781 @deffn Command defwritelock @var{on|off|auto}
1783 Sets the default writelock behavior for new windows. Initially all windows
1784 will be created with no writelocks.
1787 @node Su, , Writelock, Multiuser Session
1789 @deffn Command su [@var{username} [@var{password} [@var{password2}]]]
1791 Substitute the user of a display. The command prompts for
1792 all parameters that are omitted. If passwords are specified
1793 as parameters, they have to be specified un-crypted. The
1794 first password is matched against the systems passwd database,
1795 the second password is matched against the @code{screen}
1796 password as set with the commands @code{acladd} or @code{password}.
1797 @code{Su} may be useful for the @code{screen} administrator to test
1799 When the identification fails, the user has
1800 access to the commands available for user @samp{nobody}. These are
1801 @code{detach}, @code{license}, @code{version}, @code{help} and
1805 @node Session Name, Suspend, Multiuser Session, Session Management
1806 @section Session Name
1807 @deffn Command sessionname [@var{name}]
1809 Rename the current session. Note that for @code{screen -list} the name
1810 shows up with the process-id prepended. If the argument @var{name} is
1811 omitted, the name of this session is displayed.@*
1812 @emph{Caution}: The @code{$STY}
1813 environment variable will still reflect the old name in pre-existing
1814 shells. This may result in
1815 confusion. The default is constructed from the tty and host names.
1818 @node Suspend, Quit, Session Name, Session Management
1822 @deffn Command suspend
1823 (@kbd{C-a z}, @kbd{C-a C-z})@*
1824 Suspend @code{screen}. The windows are in the detached state while
1825 @code{screen} is suspended. This feature relies on the parent shell
1826 being able to do job control.
1829 @node Quit, , Suspend, Session Management
1834 Kill all windows and terminate @code{screen}. Note that on VT100-style
1835 terminals the keys @kbd{C-4} and @kbd{C-\} are identical. So be careful
1836 not to type @kbd{C-a C-4} when selecting window no. 4. Use the empty
1837 bind command (as in @code{bind "^\"}) to remove a key binding
1838 (@pxref{Key Binding}).
1841 @node Regions, Window Settings, Session Management, Top
1844 Screen has the ability to display more than one window on the
1845 user's display. This is done by splitting the screen in regions,
1846 which can contain different windows.
1849 * Split:: Split a region into two
1850 * Focus:: Change to the next region
1851 * Only:: Delete all other regions
1852 * Remove:: Delete the current region
1853 * Resize:: Grow or shrink a region
1854 * Caption:: Control the window's caption
1855 * Fit:: Resize a window to fit the region
1858 @node Split, Focus, , Regions
1862 @deffn Command split [-v]
1863 (@kbd{C-a S}, @kbd{C-a |})@*
1864 Split the current region into two new ones. All regions on the
1865 display are resized to make room for the new region. The blank
1866 window is displayed on the new region. The default is to create
1867 a horizontal split, putting the new regions on the top and
1868 bottom of each other. Using -v will create a vertical split,
1869 causing the new regions to appear side by side of each other.
1871 With this current implementation of @code{screen}, scrolling data
1872 will appear much slower in a vertically splited region than one
1873 that is not. This should be taken into consideration if you need
1874 to use system commands such as @code{cat} or @code{tail -f}.
1877 @node Focus, Only, Split, Regions
1880 @deffn Command focus
1881 (@kbd{C-a @key{Tab}})@*
1882 Move the input focus to the next region. This is done in a cyclic
1883 way so that the top region is selected after the bottom one. If
1884 no subcommand is given it defaults to `down'. `up' cycles in the
1885 opposite order, `top' and `bottom' go to the top and bottom
1886 region respectively. Useful bindings are (j and k as in vi)
1895 @node Only, Remove, Focus, Regions
1900 Kill all regions but the current one.
1903 @node Remove, Resize, Only, Regions
1906 @deffn Command remove
1908 Kill the current region. This is a no-op if there is only one region.
1911 @node Resize, Caption, Remove, Regions
1913 @deffn Command resize [(+/-)@var{lines}]
1915 Resize the current region. The space will be removed from or added to
1916 the region below or if there's not enough space from the region above.
1918 resize +N increase current region height by N
1919 resize -N decrease current region height by N
1920 resize N set current region height to N
1921 resize = make all windows equally high
1922 resize max maximize current region height
1923 resize min minimize current region height
1927 @node Caption, Fit, Resize, Regions
1929 @deffn Command caption @code{always}|@code{splitonly} [string]
1930 @deffnx Command caption @code{string} [string]
1932 This command controls the display of the window captions. Normally
1933 a caption is only used if more than one window is shown on the
1934 display (split screen mode). But if the type is set to
1935 @code{always}, @code{screen} shows a caption
1936 even if only one window is displayed. The default
1937 is @samp{splitonly}.
1939 The second form changes the text used for the caption. You can use
1940 all string escapes (@pxref{String Escapes}). @code{Screen} uses
1941 a default of @samp{%3n %t}.
1943 You can mix both forms by providing the string as an additional
1947 @node Fit, , Caption, Regions
1952 Change the window size to the size of the current region. This
1953 command is needed because screen doesn't adapt the window size
1954 automatically if the window is displayed more than once.
1957 @node Window Settings, Virtual Terminal, Regions, Top
1958 @chapter Window Settings
1960 These commands control the way @code{screen} treats individual windows
1961 in a session. @xref{Virtual Terminal}, for commands to control the
1962 terminal emulation itself.
1965 * Naming Windows:: Control the name of the window
1966 * Console:: See the host's console messages
1967 * Kill:: Destroy an unwanted window
1968 * Login:: Control @file{/etc/utmp} logging
1969 * Mode:: Control the file mode of the pty
1970 * Monitor:: Watch for activity in a window
1971 * Windows:: List the active windows
1972 * Hardstatus:: Set a window's hardstatus line
1975 @node Naming Windows, Console, , Window Settings
1976 @section Naming Windows (Titles)
1979 You can customize each window's name in the window display (viewed with
1980 the @code{windows} command (@pxref{Windows}) by setting it with
1981 one of the title commands. Normally the name displayed is the actual
1982 command name of the program created in the window. However, it is
1983 sometimes useful to distinguish various programs of the same name or to
1984 change the name on-the-fly to reflect the current state of the window.
1986 The default name for all shell windows can be set with the
1987 @code{shelltitle} command (@pxref{Shell}). You can specify the name you
1988 want for a window with the @samp{-t} option to the @code{screen} command
1989 when the window is created (@pxref{Screen Command}). To change the name after
1990 the window has been created you can use the title-string escape-sequence
1991 (@kbd{@key{ESC} k @var{name} @key{ESC} \}) and the @code{title} command
1992 (C-a A). The former can be output from an application to control the
1993 window's name under software control, and the latter will prompt for a
1994 name when typed. You can also bind predefined names to keys with the
1995 @code{title} command to set things quickly without prompting.
1998 * Title Command:: The @code{title} command.
1999 * Dynamic Titles:: Make shell windows change titles dynamically.
2000 * Title Prompts:: Set up your shell prompt for dynamic Titles.
2001 * Title Screenrc:: Set up Titles in your @file{.screenrc}.
2004 @node Title Command, Dynamic Titles, , Naming Windows
2005 @subsection Title Command
2007 @deffn Command title [windowtitle]
2009 Set the name of the current window to @var{windowtitle}. If no name is
2010 specified, screen prompts for one.
2013 @node Dynamic Titles, Title Prompts, Title Command, Naming Windows
2014 @subsection Dynamic Titles
2015 @code{screen} has a shell-specific heuristic that is enabled by
2016 setting the window's name to @var{search|name} and arranging to have a
2017 null title escape-sequence output as a part of your prompt. The
2018 @var{search} portion specifies an end-of-prompt search string, while the
2019 @var{name} portion specifies the default shell name for the window. If
2020 the @var{name} ends in a @samp{:} @code{screen} will add what it
2021 believes to be the current command running in the window to the end of
2022 the specified name (e.g. @var{name:cmd}). Otherwise the current
2023 command name supersedes the shell name while it is running.
2025 Here's how it works: you must modify your shell prompt to output a null
2026 title-escape-sequence (@key{ESC} k @key{ESC} \) as a part of your prompt.
2027 The last part of your prompt must be the same as the string you
2028 specified for the @var{search} portion of the title. Once this is set
2029 up, @code{screen} will use the title-escape-sequence to clear the previous
2030 command name and get ready for the next command. Then, when a newline
2031 is received from the shell, a search is made for the end of the prompt.
2032 If found, it will grab the first word after the matched string and use
2033 it as the command name. If the command name begins with @samp{!},
2034 @samp{%}, or @samp{^}, @code{screen} will use the first word on the
2035 following line (if found) in preference to the just-found name. This
2036 helps csh users get more accurate titles when using job control or
2037 history recall commands.
2039 @node Title Prompts, Title Screenrc, Dynamic Titles, Naming Windows
2040 @subsection Setting up your prompt for shell titles
2041 One thing to keep in mind when adding a null title-escape-sequence to your
2042 prompt is that some shells (like the csh) count all the non-control
2043 characters as part of the prompt's length. If these invisible
2044 characters aren't a multiple of 8 then backspacing over a tab will
2045 result in an incorrect display. One way to get around this is to use a
2049 set prompt='@value{esc}[0000m@value{esc}k@value{esc}\% '
2052 The escape-sequence @samp{@value{esc}[0000m} not only normalizes the
2053 character attributes, but all the zeros round the length of the
2054 invisible characters up to 8.
2056 Tcsh handles escape codes in the prompt more intelligently, so you can
2057 specify your prompt like this:
2060 set prompt="%@{\ek\e\\%@}\% "
2063 Bash users will probably want to echo the escape sequence in the
2067 PROMPT_COMMAND='printf "\033k\033\134"'
2070 (I used @samp{\134} to output a @samp{\} because of a bug in v1.04).
2072 @node Title Screenrc, , Title Prompts, Naming Windows
2073 @subsection Setting up shell titles in your @file{.screenrc}
2074 Here are some .screenrc examples:
2077 screen -t top 2 nice top
2080 Adding this line to your .screenrc would start a niced version of the
2081 @code{top} command in window 2 named @samp{top} rather than @samp{nice}.
2088 This file would start a shell using the given shelltitle. The title
2089 specified is an auto-title that would expect the prompt and the typed
2090 command to look something like the following:
2093 /usr/joe/src/dir> trn
2096 (it looks after the '> ' for the command name).
2097 The window status would show the name @samp{trn} while the command was
2098 running, and revert to @samp{csh} upon completion.
2101 bind R screen -t '% |root:' su
2104 Having this command in your .screenrc would bind the key sequence
2105 @kbd{C-a R} to the @code{su} command and give it an auto-title name of
2106 @samp{root:}. For this auto-title to work, the screen could look
2107 something like this:
2114 Here the user typed the csh history command @code{!em} which ran the
2115 previously entered @code{emacs} command. The window status would show
2116 @samp{root:emacs} during the execution of the command, and revert to
2117 simply @samp{root:} at its completion.
2122 bind u title (unknown)
2125 The first binding doesn't have any arguments, so it would prompt you for
2126 a title when you type @kbd{C-a o}. The second binding would clear an
2127 auto-titles current setting (C-a E). The third binding would set the
2128 current window's title to @samp{(unknown)} (C-a u).
2130 @node Console, Kill, Naming Windows, Window Settings
2132 @deffn Command console [@var{state}]
2134 Grabs or un-grabs the machines console output to a window. When the argument
2135 is omitted the current state is displayed.
2136 @emph{Note}: Only the owner of @file{/dev/console} can grab the console
2137 output. This command is only available if the host supports the ioctl
2141 @node Kill, Login, Console, Window Settings
2147 (@kbd{C-a k}, @kbd{C-a C-k})@*
2148 Kill the current window.@*
2149 If there is an @code{exec} command running (@pxref{Exec}) then it is killed.
2150 Otherwise the process (e.g. shell) running in the window receives a
2151 @code{HANGUP} condition,
2152 the window structure is removed and screen (your display) switches to another
2153 window. When the last window is destroyed, @code{screen} exits.
2154 After a kill screen switches to the previously displayed window.
2156 @emph{Caution}: @code{emacs} users may find themselves killing their
2157 @code{emacs} session when trying to delete the current line. For this
2158 reason, it is probably wise to use a different command character
2159 (@pxref{Command Character}) or rebind @code{kill} to another key
2160 sequence, such as @kbd{C-a K} (@pxref{Key Binding}).
2163 @node Login, Mode, Kill, Window Settings
2166 @deffn Command deflogin state
2168 Same as the @code{login} command except that the default setting for new
2169 windows is changed. This defaults to `on' unless otherwise specified at
2170 compile time (@pxref{Installation}). Both commands are only present when
2171 @code{screen} has been compiled with utmp support.
2175 @deffn Command login [state]
2177 Adds or removes the entry in @file{/etc/utmp} for the current window.
2178 This controls whether or not the window is @dfn{logged in}. In addition
2179 to this toggle, it is convenient to have ``log in'' and ``log out''
2180 keys. For instance, @code{bind I login on} and @code{bind O
2181 login off} will map these keys to be @kbd{C-a I} and @kbd{C-a O}
2182 (@pxref{Key Binding}).
2185 @node Mode, Monitor, Login, Window Settings
2187 @deffn Command defmode mode
2189 The mode of each newly allocated pseudo-tty is set to @var{mode}.
2190 @var{mode} is an octal number as used by chmod(1). Defaults to 0622 for
2191 windows which are logged in, 0600 for others (e.g. when @code{-ln} was
2192 specified for creation, @pxref{Screen Command}).
2195 @node Monitor, Windows, Mode, Window Settings
2198 @deffn Command activity message
2200 When any activity occurs in a background window that is being monitored,
2201 @code{screen} displays a notification in the message line. The
2202 notification message can be redefined by means of the @code{activity}
2203 command. Each occurrence of @samp{%} in @var{message} is replaced by
2204 the number of the window in which activity has occurred, and each
2205 occurrence of @samp{^G} is replaced by the definition for bell in your
2206 termcap (usually an audible bell). The default message is
2209 'Activity in window %n'
2212 Note that monitoring is off for all windows by default, but can be altered
2213 by use of the @code{monitor} command (@kbd{C-a M}).
2216 @deffn Command defmonitor state
2218 Same as the @code{monitor} command except that the default setting for
2219 new windows is changed. Initial setting is `off'.
2223 @deffn Command monitor [state]
2225 Toggles monitoring of the current window. When monitoring is turned on
2226 and the affected window is switched into the background, the activity
2227 notification message will be displayed in the status line at the first
2228 sign of output, and the window will also be marked with an @samp{@@} in
2229 the window-status display (@pxref{Windows}). Monitoring defaults to
2230 @samp{off} for all windows.
2233 @node Windows, Hardstatus, Monitor, Window Settings
2237 @deffn Command windows
2238 (@kbd{C-a w}, @kbd{C-a C-w})@*
2239 Uses the message line to display a list of all the windows. Each
2240 window is listed by number with the name of the program running in the
2241 window (or its title).
2243 The current window is marked with a @samp{*};
2244 the previous window is marked with a @samp{-};
2245 all the windows that are logged in are marked with a @samp{$} (@pxref{Login});
2246 a background window that has received a bell is marked with a @samp{!};
2247 a background window that is being monitored and has had activity occur is
2248 marked with an @samp{@@} (@pxref{Monitor});
2249 a window which has output logging turned on is marked with @samp{(L)};
2250 windows occupied by other users are marked with @samp{&}
2251 or @samp{&&} if the window is shared by other users;
2252 windows in the zombie state are marked with @samp{Z}.
2254 If this list is too long to fit on the terminal's status line only the
2255 portion around the current window is displayed.
2258 @node Hardstatus, Mousetrack, Windows, Window Settings
2261 @code{Screen} maintains a hardstatus line for every window. If a window
2262 gets selected, the display's hardstatus will be updated to match
2263 the window's hardstatus line.
2264 The hardstatus line can be changed with the ANSI Application
2265 Program Command (APC): @samp{ESC_<string>ESC\}. As a convenience
2266 for xterm users the sequence @samp{ESC]0..2;<string>^G} is
2269 @deffn Command defhstatus [status]
2271 The hardstatus line that all new windows will get is set to
2273 This command is useful to make the hardstatus of every window
2274 display the window number or title or the like. @var{status}
2275 may contain the same directives as in the window messages, but
2276 the directive escape character is @samp{^E} (octal 005) instead
2277 of @samp{%}. This was done to make a misinterpretation of program
2278 generated hardstatus lines impossible.
2279 If the parameter @var{status}
2280 is omitted, the current default string is displayed.
2281 Per default the hardstatus line of new windows is empty.
2284 @deffn Command hstatus status
2286 Changes the current window's hardstatus line to @var{status}.
2289 @node Mousetrack, , Hardstatus, Miscellaneous
2292 @deffn Command mousetrack [ @code{on|off} ]
2294 This command determines whether @code{screen} will watch for
2295 mouse clicks. When this command is enabled, regions that have
2296 been split in various ways can be selected by pointing to them
2297 with a mouse and left-clicking them. Without specifying @var{on}
2298 or @var{off}, the current state is displayed. The default state
2299 is determined by the @code{defmousetrack} command.
2302 @deffn Command defmousetrack @code{on|off}
2304 This command determines the default state of the @code{mousetrack}
2305 command, currently defaulting of @var{off}.
2308 @node Virtual Terminal, Copy and Paste, Window Settings, Top
2309 @chapter Virtual Terminal
2311 Each window in a @code{screen} session emulates a VT100 terminal, with
2312 some extra functions added. The VT100 emulator is hard-coded, no other
2313 terminal types can be emulated.
2314 The commands described here modify the terminal emulation.
2317 * Control Sequences:: Details of the internal VT100 emulation.
2318 * Input Translation:: How keystrokes are remapped.
2319 * Digraph:: Entering digraph sequences.
2320 * Bell:: Getting your attention.
2321 * Clear:: Clear the window display.
2322 * Info:: Terminal emulation statistics.
2323 * Redisplay:: When the display gets confusing.
2324 * Wrap:: Automatic margins.
2325 * Reset:: Recovering from ill-behaved applications.
2326 * Window Size:: Changing the size of your terminal.
2327 * Character Processing:: Change the effect of special characters.
2330 @node Control Sequences, Input Translation, , Virtual Terminal
2331 @section Control Sequences
2332 @cindex control sequences
2333 The following is a list of control sequences recognized by
2334 @code{screen}. @samp{(V)} and @samp{(A)} indicate VT100-specific and
2335 ANSI- or ISO-specific functions, respectively.
2341 ESC H Horizontal Tab Set
2342 ESC Z Send VT100 Identification String
2343 ESC 7 (V) Save Cursor and Attributes
2344 ESC 8 (V) Restore Cursor and Attributes
2345 ESC [s (A) Save Cursor and Attributes
2346 ESC [u (A) Restore Cursor and Attributes
2347 ESC c Reset to Initial State
2349 ESC Pn p Cursor Visibility (97801)
2352 ESC = (V) Application Keypad Mode
2353 ESC > (V) Numeric Keypad Mode
2354 ESC # 8 (V) Fill Screen with E's
2355 ESC \ (A) String Terminator
2356 ESC ^ (A) Privacy Message String (Message Line)
2357 ESC ! Global Message String (Message Line)
2358 ESC k Title Definition String
2359 ESC P (A) Device Control String
2360 Outputs a string directly to the host
2361 terminal without interpretation.
2362 ESC _ (A) Application Program Command (Hardstatus)
2363 ESC ] 0 ; string ^G (A) Operating System Command (Hardstatus, xterm
2365 ESC ] 83 ; cmd ^G (A) Execute screen command. This only works if
2366 multi-user support is compiled into screen.
2367 The pseudo-user ":window:" is used to check
2368 the access control list. Use "addacl :window:
2369 -rwx #?" to create a user with no rights and
2370 allow only the needed commands.
2371 Control-N (A) Lock Shift G1 (SO)
2372 Control-O (A) Lock Shift G0 (SI)
2373 ESC n (A) Lock Shift G2
2374 ESC o (A) Lock Shift G3
2375 ESC N (A) Single Shift G2
2376 ESC O (A) Single Shift G3
2377 ESC ( Pcs (A) Designate character set as G0
2378 ESC ) Pcs (A) Designate character set as G1
2379 ESC * Pcs (A) Designate character set as G2
2380 ESC + Pcs (A) Designate character set as G3
2381 ESC [ Pn ; Pn H Direct Cursor Addressing
2382 ESC [ Pn ; Pn f same as above
2383 ESC [ Pn J Erase in Display
2384 Pn = None or 0 From Cursor to End of Screen
2385 1 From Beginning of Screen to Cursor
2387 ESC [ Pn K Erase in Line
2388 Pn = None or 0 From Cursor to End of Line
2389 1 From Beginning of Line to Cursor
2391 ESC [ Pn X Erase character
2392 ESC [ Pn A Cursor Up
2393 ESC [ Pn B Cursor Down
2394 ESC [ Pn C Cursor Right
2395 ESC [ Pn D Cursor Left
2396 ESC [ Pn E Cursor next line
2397 ESC [ Pn F Cursor previous line
2398 ESC [ Pn G Cursor horizontal position
2399 ESC [ Pn ` same as above
2400 ESC [ Pn d Cursor vertical position
2401 ESC [ Ps ;...; Ps m Select Graphic Rendition
2402 Ps = None or 0 Default Rendition
2405 3 (A) @i{Standout} Mode (ANSI: Italicized)
2409 22 (A) Normal Intensity
2410 23 (A) @i{Standout} Mode off (ANSI: Italicized off)
2411 24 (A) Not Underlined
2413 27 (A) Positive Image
2414 30 (A) Foreground Black
2415 31 (A) Foreground Red
2416 32 (A) Foreground Green
2417 33 (A) Foreground Yellow
2418 34 (A) Foreground Blue
2419 35 (A) Foreground Magenta
2420 36 (A) Foreground Cyan
2421 37 (A) Foreground White
2422 39 (A) Foreground Default
2423 40 (A) Background Black
2425 49 (A) Background Default
2426 ESC [ Pn g Tab Clear
2427 Pn = None or 0 Clear Tab at Current Position
2429 ESC [ Pn ; Pn r (V) Set Scrolling Region
2430 ESC [ Pn I (A) Horizontal Tab
2431 ESC [ Pn Z (A) Backward Tab
2432 ESC [ Pn L (A) Insert Line
2433 ESC [ Pn M (A) Delete Line
2434 ESC [ Pn @@ (A) Insert Character
2435 ESC [ Pn P (A) Delete Character
2436 ESC [ Pn S Scroll Scrolling Region Up
2437 ESC [ Pn T Scroll Scrolling Region Down
2438 ESC [ Pn ^ same as above
2439 ESC [ Ps ;...; Ps h Set Mode
2440 ESC [ Ps ;...; Ps l Reset Mode
2441 Ps = 4 (A) Insert Mode
2442 20 (A) @samp{Automatic Linefeed} Mode.
2443 34 Normal Cursor Visibility
2444 ?1 (V) Application Cursor Keys
2445 ?3 (V) Change Terminal Width to 132 columns
2446 ?5 (V) Reverse Video
2447 ?6 (V) @samp{Origin} Mode
2448 ?7 (V) @samp{Wrap} Mode
2449 ?9 X10 mouse tracking
2450 ?25 (V) Visible Cursor
2451 ?47 Alternate Screen (old xterm code)
2452 ?1000 (V) VT200 mouse tracking
2453 ?1047 Alternate Screen (new xterm code)
2454 ?1049 Alternate Screen (new xterm code)
2455 ESC [ 5 i (A) Start relay to printer (ANSI Media Copy)
2456 ESC [ 4 i (A) Stop relay to printer (ANSI Media Copy)
2457 ESC [ 8 ; Ph ; Pw t Resize the window to @samp{Ph} lines and
2458 @samp{Pw} columns (SunView special)
2459 ESC [ c Send VT100 Identification String
2460 ESC [ x (V) Send Terminal Parameter Report
2461 ESC [ > c Send Secondary Device Attributes String
2462 ESC [ 6 n Send Cursor Position Report
2467 @node Input Translation, Digraph, Control Sequences, Virtual Terminal
2468 @section Input Translation
2469 @cindex input translation
2470 In order to do a full VT100 emulation @code{screen} has to detect
2471 that a sequence of characters in the input stream was generated
2472 by a keypress on the user's keyboard and insert the VT100
2473 style escape sequence. @code{Screen} has a very flexible way of doing
2474 this by making it possible to map arbitrary commands on arbitrary
2475 sequences of characters. For standard VT100 emulation the command
2476 will always insert a string in the input buffer of the window
2477 (see also command @code{stuff}, @pxref{Paste}).
2478 Because the sequences generated by a keypress can
2479 change after a reattach from a different terminal type, it is
2480 possible to bind commands to the termcap name of the keys.
2481 @code{Screen} will insert the correct binding after each
2482 reattach. See @ref{Bindkey} for further details on the syntax and examples.
2484 Here is the table of the default key bindings. (A) means that the
2485 command is executed if the keyboard is switched into application
2489 Key name Termcap name Command
2490 -----------------------------------------------------
2491 Cursor up ku stuff \033[A
2493 Cursor down kd stuff \033[B
2495 Cursor right kr stuff \033[C
2497 Cursor left kl stuff \033[D
2499 Function key 0 k0 stuff \033[10~
2500 Function key 1 k1 stuff \033OP
2501 Function key 2 k2 stuff \033OQ
2502 Function key 3 k3 stuff \033OR
2503 Function key 4 k4 stuff \033OS
2504 Function key 5 k5 stuff \033[15~
2505 Function key 6 k6 stuff \033[17~
2506 Function key 7 k7 stuff \033[18~
2507 Function key 8 k8 stuff \033[19~
2508 Function key 9 k9 stuff \033[20~
2509 Function key 10 k; stuff \033[21~
2510 Function key 11 F1 stuff \033[23~
2511 Function key 12 F2 stuff \033[24~
2512 Home kh stuff \033[1~
2513 End kH stuff \033[4~
2514 Insert kI stuff \033[2~
2515 Delete kD stuff \033[3~
2516 Page up kP stuff \033[5~
2517 Page down kN stuff \033[6~
2552 Keypad enter fe stuff \015
2556 @node Digraph, Bell, Input Translation, Virtual Terminal
2560 @deffn Command digraph [preset]
2562 This command prompts the user for a digraph sequence. The next
2563 two characters typed are looked up in a builtin table and the
2564 resulting character is inserted in the input stream. For example,
2565 if the user enters @samp{a"}, an a-umlaut will be inserted. If the
2566 first character entered is a 0 (zero), @code{screen}
2567 will treat the following characters (up to three) as an octal
2568 number instead. The optional argument @var{preset}
2569 is treated as user input, thus one can create an "umlaut" key.
2570 For example the command @samp{bindkey ^K digraph '"'} enables the user
2571 to generate an a-umlaut by typing @samp{CTRL-K a}.
2574 @node Bell, Clear, Digraph, Virtual Terminal
2577 @deffn Command bell_msg [message]
2579 When a bell character is sent to a background window, @code{screen}
2580 displays a notification in the message line. The notification message
2581 can be re-defined by this command. Each occurrence
2582 of @samp{%} in @var{message} is replaced by the number of the window to
2583 which a bell has been sent, and each occurrence of @samp{^G} is replaced
2584 by the definition for bell in your termcap (usually an audible bell).
2585 The default message is
2591 An empty message can be supplied to the @code{bell_msg} command to suppress
2592 output of a message line (@code{bell_msg ""}).
2593 Without parameter, the current message is shown.
2597 @deffn Command vbell [state]
2599 Sets or toggles the visual bell setting for the current window. If
2600 @code{vbell} is switched to @samp{on}, but your
2601 terminal does not support a visual bell, the visual bell message is
2602 displayed in the status line when the bell character is received.
2603 Visual bell support of a terminal is
2604 defined by the termcap variable @code{vb}. @xref{Bell, , Visual Bell,
2605 termcap, The Termcap Manual}, for more information on visual bells.
2606 The equivalent terminfo capability is @code{flash}.
2608 Per default, @code{vbell} is @samp{off}, thus the audible bell is used.
2611 @deffn Command vbell_msg [message]
2613 Sets the visual bell message. @var{Message} is printed to the status
2614 line if the window receives a bell character (^G), @code{vbell} is
2615 set to @samp{on} and the terminal does not support a visual bell.
2616 The default message is @samp{Wuff, Wuff!!}.
2617 Without parameter, the current message is shown.
2620 @deffn Command vbellwait sec
2622 Define a delay in seconds after each display of @code{screen} 's visual
2623 bell message. The default is 1 second.
2626 @node Clear, Info, Bell, Virtual Terminal
2629 @deffn Command clear
2631 Clears the screen and saves its contents to the scrollback buffer.
2634 @node Info, Redisplay, Clear, Virtual Terminal
2639 (@kbd{C-a i}, @kbd{C-a C-i})@*
2640 Uses the message line to display some information about the current
2641 window: the cursor position in the form @samp{(@var{column},@var{row})}
2642 starting with @samp{(1,1)}, the terminal width and height plus the size
2643 of the scrollback buffer in lines, like in @samp{(80,24)+50},
2644 the current state of window XON/XOFF flow control is shown like this
2645 (@pxref{Flow Control}):
2647 +flow automatic flow control, currently on.
2648 -flow automatic flow control, currently off.
2649 +(+)flow flow control enabled. Agrees with automatic control.
2650 -(+)flow flow control disabled. Disagrees with automatic control.
2651 +(-)flow flow control enabled. Disagrees with automatic control.
2652 -(-)flow flow control disabled. Agrees with automatic control.
2655 The current line wrap setting (@samp{+wrap} indicates enabled, @samp{-wrap}
2656 not) is also shown. The flags @samp{ins}, @samp{org}, @samp{app}, @samp{log},
2657 @samp{mon} and @samp{nored} are displayed when the window is in insert mode,
2658 origin mode, application-keypad mode, has output logging,
2659 activity monitoring or partial redraw enabled.
2661 The currently active
2662 character set (@samp{G0}, @samp{G1}, @samp{G2}, or @samp{G3}), and in
2663 square brackets the terminal character sets that are currently
2664 designated as @samp{G0} through @samp{G3}.
2665 If the window is in UTF-8 mode, the string @samp{UTF-8} is shown instead.
2666 Additional modes depending on the type of the window are displayed at
2667 the end of the status line (@pxref{Window Types}).
2669 If the state machine of the terminal emulator is in a non-default state,
2670 the info line is started with a string identifying the current state.
2672 For system information use @code{time}.
2675 @deffn Command dinfo
2677 Show what screen thinks about your terminal. Useful if you want to know
2678 why features like color or the alternate charset don't work.
2681 @node Redisplay, Wrap, Info, Virtual Terminal
2684 @deffn Command allpartial state
2686 If set to on, only the current cursor line is refreshed on window change.
2687 This affects all windows and is useful for slow terminal lines. The
2688 previous setting of full/partial refresh for each window is restored
2689 with @code{allpartial off}. This is a global flag that immediately takes effect
2690 on all windows overriding the @code{partial} settings. It does not change the
2691 default redraw behavior of newly created windows.
2694 @deffn Command altscreen state
2696 If set to on, "alternate screen" support is enabled in virtual terminals,
2697 just like in xterm. Initial setting is @samp{off}.
2700 @deffn Command partial state
2702 Defines whether the display should be refreshed (as with
2703 @code{redisplay}) after switching to the current window. This command
2704 only affects the current window. To immediately affect all windows use the
2705 @code{allpartial} command. Default is @samp{off}, of course. This default is
2706 fixed, as there is currently no @code{defpartial} command.
2711 @deffn Command redisplay
2712 (@kbd{C-a l}, @kbd{C-a C-l})@*
2713 Redisplay the current window. Needed to get a full redisplay in
2714 partial redraw mode.
2717 @node Wrap, Reset, Redisplay, Virtual Terminal
2722 @deffn Command wrap state
2723 (@kbd{C-a r}, @kbd{C-a C-r}) @*
2724 Sets the line-wrap setting for the current window. When line-wrap is
2725 on, the second consecutive printable character output at the last column
2726 of a line will wrap to the start of the following line. As an added
2727 feature, backspace (^H) will also wrap through the left margin to the
2728 previous line. Default is @samp{on}.
2731 @deffn Command defwrap state
2733 Same as the @code{wrap} command except that the default setting for new
2734 windows is changed. Initially line-wrap is on and can be toggled with the
2735 @code{wrap} command (@kbd{C-a r}) or by means of "C-a : wrap on|off".
2738 @node Reset, Window Size, Wrap, Virtual Terminal
2741 @deffn Command reset
2743 Reset the virtual terminal to its ``power-on'' values. Useful when strange
2744 settings (like scroll regions or graphics character set) are left over from
2748 @node Window Size, Character Processing, Reset, Virtual Terminal
2749 @section Window Size
2751 @deffn Command width [@code{-w}|@code{-d}] [cols [lines]]
2753 Toggle the window width between 80 and 132 columns, or set it to
2754 @var{cols} columns if an argument is specified. This requires a
2755 capable terminal and the termcap entries @samp{Z0} and @samp{Z1}. See
2756 the @code{termcap} command (@pxref{Termcap}), for more information.
2757 You can also specify a height if you want to
2758 change both values. The @code{-w} option tells screen to leave
2759 the display size unchanged and just set the window size,
2760 @code{-d} vice versa.
2763 @deffn Command height [@code{-w}|@code{-d}] [lines [cols]]
2765 Set the display height to a specified number of lines. When no
2766 argument is given it toggles between 24 and 42 lines display.
2769 @node Character Processing, ,Window Size, Virtual Terminal
2770 @section Character Processing
2772 @deffn Command c1 [state]
2774 Change c1 code processing. @samp{c1 on} tells screen to treat
2775 the input characters between 128 and 159 as control functions.
2776 Such an 8-bit code is normally the same as ESC followed by the
2777 corresponding 7-bit code. The default setting is to process c1
2778 codes and can be changed with the @samp{defc1} command.
2779 Users with fonts that have usable characters in the
2780 c1 positions may want to turn this off.
2783 @deffn Command gr [state]
2785 Turn GR charset switching on/off. Whenever screen sees an input
2786 char with an 8th bit set, it will use the charset stored in the
2787 GR slot and print the character with the 8th bit stripped. The
2788 default (see also @samp{defgr}) is not to process GR switching because
2789 otherwise the ISO88591 charset would not work.
2792 @deffn Command bce [state]
2794 Change background-color-erase setting. If @samp{bce} is set to
2795 on, all characters cleared by an erase/insert/scroll/clear
2796 operation will be displayed in the current background color.
2797 Otherwise the default background color is used.
2800 @deffn Command encoding enc [denc]
2802 Tell screen how to interpret the input/output. The first argument
2803 sets the encoding of the current window.
2804 Each window can emulate a different encoding. The optional second
2805 parameter overwrites the encoding of the connected terminal.
2806 It should never be needed as screen uses the locale setting to detect
2808 There is also a way to select a terminal encoding depending on
2809 the terminal type by using the @samp{KJ} termcap entry. @xref{Special Capabilities}.
2811 Supported encodings are
2812 @code{eucJP}, @code{SJIS}, @code{eucKR},
2813 @code{eucCN}, @code{Big5}, @code{GBK}, @code{KOI8-R}, @code{CP1251},
2814 @code{UTF-8}, @code{ISO8859-2}, @code{ISO8859-3},
2815 @code{ISO8859-4}, @code{ISO8859-5}, @code{ISO8859-6},
2816 @code{ISO8859-7}, @code{ISO8859-8}, @code{ISO8859-9},
2817 @code{ISO8859-10}, @code{ISO8859-15}, @code{jis}.
2819 See also @samp{defencoding}, which changes the default setting of a new
2823 @deffn Command charset set
2825 Change the current character set slot designation and charset
2826 mapping. The first four character of @var{set}
2827 are treated as charset designators while the fifth and sixth
2828 character must be in range @samp{0} to @samp{3} and set the GL/GR
2829 charset mapping. On every position a @samp{.} may be used to indicate
2830 that the corresponding charset/mapping should not be changed
2831 (@var{set} is padded to six characters internally by appending
2832 @samp{.} chars). New windows have @samp{BBBB02} as default
2833 charset, unless a @samp{encoding} command is active.
2835 The current setting can be viewed with the @ref{Info} command.
2838 @deffn Command utf8 [state [dstate]]
2840 Change the encoding used in the current window. If utf8 is enabled, the
2841 strings sent to the window will be UTF-8 encoded and vice versa.
2843 parameter toggles the setting. If a second parameter is given, the
2845 encoding is also changed (this should rather be done with screen's
2847 See also @samp{defutf8}, which changes the default setting of a new
2851 @deffn Command defc1 state
2853 Same as the @samp{c1} command except that the default setting for
2854 new windows is changed. Initial setting is @samp{on}.
2857 @deffn Command defgr state
2859 Same as the @samp{gr} command except that the default setting for
2860 new windows is changed. Initial setting is @samp{off}.
2863 @deffn Command defbce state
2865 Same as the @samp{bce} command except that the default setting for
2866 new windows is changed. Initial setting is @samp{off}.
2869 @deffn Command defencoding enc
2871 Same as the @samp{encoding} command except that the default setting for
2872 new windows is changed. Initial setting is the encoding taken from the
2876 @deffn Command defcharset [set]
2877 Like the @samp{charset} command except that the default setting for
2878 new windows is changed. Shows current default if called without
2882 @deffn Command defutf8 state
2884 Same as the @samp{utf8} command except that the default setting for new
2885 windows is changed. Initial setting is @code{on} if screen was started
2886 with @samp{-U}, otherwise @code{off}.
2889 @node Copy and Paste, Subprocess Execution, Virtual Terminal, Top
2890 @chapter Copy and Paste
2891 @cindex copy and paste
2893 For those confined to a hardware terminal, these commands provide a cut
2894 and paste facility more powerful than those provided by most windowing
2898 * Copy:: Copy from scrollback to buffer
2899 * Paste:: Paste from buffer into window
2900 * Registers:: Longer-term storage
2901 * Screen Exchange:: Sharing data between screen users
2902 * History:: Recalling previous input
2905 @node Copy, Paste, , Copy and Paste
2913 (@kbd{C-a [}, @kbd{C-a C-[}, @kbd{C-a @key{ESC}})@*
2914 Enter copy/scrollback mode. This allows you to copy text from the
2915 current window and its history into the paste buffer. In this mode a
2916 @code{vi}-like full screen editor is active, with controls as
2921 * Line Termination:: End copied lines with CR/LF
2922 * Scrollback:: Set the size of the scrollback buffer
2923 * Copy Mode Keys:: Remap keys in copy mode
2924 * Movement:: Move around in the scrollback buffer
2925 * Marking:: Select the text you want
2926 * Repeat count:: Repeat a command
2927 * Searching:: Find the text you want
2928 * Specials:: Other random keys
2931 @node Line Termination, Scrollback, , Copy
2933 @deffn Command crlf [state]
2935 This affects the copying of text regions with the @kbd{C-a [} command.
2936 If it is set to @samp{on}, lines will be separated by the two character
2937 sequence @samp{CR}/@samp{LF}. Otherwise only @samp{LF} is used.
2938 @code{crlf} is off by default.
2939 When no parameter is given, the state is toggled.
2942 @node Scrollback, Copy Mode Keys, Line Termination, Copy
2943 @subsection Scrollback
2944 @deffn Command defscrollback num
2946 Same as the @code{scrollback} command except that the default setting
2947 for new windows is changed. Defaults to 100.
2950 @deffn Command scrollback num
2952 Set the size of the scrollback buffer for the current window to
2953 @var{num} lines. The default scrollback is 100 lines. Use @kbd{C-a i}
2954 to view the current setting.
2957 @deffn Command compacthist [state]
2959 This tells screen whether to suppress trailing blank lines when
2960 scrolling up text into the history buffer. Turn compacting @samp{on}
2961 to hold more useful lines in your scrollback buffer.
2964 @node Copy Mode Keys, Movement, Scrollback, Copy
2965 @subsection markkeys
2966 @deffn Command markkeys string
2968 This is a method of changing the keymap used for copy/history mode. The
2969 string is made up of @var{oldchar}=@var{newchar} pairs which are
2970 separated by @samp{:}. Example: The command @code{markkeys
2971 h=^B:l=^F:$=^E} would set some keys to be more familiar to @code{emacs}
2973 If your terminal sends characters, that cause you to abort copy mode,
2974 then this command may help by binding these characters to do nothing.
2975 The no-op character is `@@' and is used like this: @code{markkeys @@=L=H}
2976 if you do not want to use the `H' or `L' commands any longer.
2977 As shown in this example, multiple keys can be assigned to one function
2978 in a single statement.
2981 @node Movement, Marking, Copy Mode Keys, Copy
2982 @subsection Movement Keys
2985 @kbd{h}, @kbd{j}, @kbd{k}, @kbd{l} move the cursor line by line or
2989 @kbd{0}, @kbd{^} and @kbd{$} move to the leftmost column or to the first
2990 or last non-whitespace character on the line.
2993 @kbd{H}, @kbd{M} and @kbd{L} move the cursor to the leftmost column
2994 of the top, center or bottom line of the window.
2997 @kbd{+} and @kbd{-} move the cursor to the leftmost column of the next
3001 @kbd{G} moves to the specified absolute line (default: end of buffer).
3004 @kbd{|} moves to the specified absolute column.
3007 @kbd{w}, @kbd{b}, @kbd{e} move the cursor word by word.
3010 @kbd{B}, @kbd{E} move the cursor WORD by WORD (as in vi).
3013 @kbd{C-u} and @kbd{C-d} scroll the display up/down by the specified
3014 amount of lines while preserving the cursor position. (Default: half
3018 @kbd{C-b} and @kbd{C-f} move the cursor up/down a full screen.
3021 @kbd{g} moves to the beginning of the buffer.
3024 @kbd{%} jumps to the specified percentage of the buffer.
3026 Note that Emacs-style movement keys can be specified by a .screenrc
3027 command. (@code{markkeys "h=^B:l=^F:$=^E"}) There is no simple method for
3028 a full emacs-style keymap, however, as this involves multi-character codes.
3030 @node Marking, Repeat count, Movement, Copy
3033 The copy range is specified by setting two marks. The text between these
3034 marks will be highlighted. Press @kbd{space} to set the first or second
3038 @kbd{Y} and @kbd{y} can be used to mark one whole line or to mark from
3042 @kbd{W} marks exactly one word.
3044 @node Repeat count, Searching, Marking, Copy
3045 @subsection Repeat Count
3047 Any command in copy mode can be prefixed with a number (by pressing
3048 digits @kbd{0@dots{}9}) which is taken as a repeat count. Example:
3049 @kbd{C-a C-[ H 10 j 5 Y} will copy lines 11 to 15 into the paste buffer.
3051 @node Searching, Specials, Repeat count, Copy
3052 @subsection Searching
3055 @kbd{/} @code{vi}-like search forward.
3058 @kbd{?} @code{vi}-like search backward.
3061 @kbd{C-a s} @code{emacs} style incremental search forward.
3064 @kbd{C-r} @code{emacs} style reverse i-search.
3066 @deffn Command ignorecase [state]
3068 Tell screen to ignore the case of characters in searches. Default is
3072 @node Specials, , Searching, Copy
3073 @subsection Specials
3075 There are, however, some keys that act differently here from in
3076 @code{vi}. @code{Vi} does not allow to yank rectangular blocks of text,
3077 but @code{screen} does. Press
3080 @kbd{c} or @kbd{C} to set the left or right margin respectively. If no
3081 repeat count is given, both default to the current cursor position.@*
3082 Example: Try this on a rather full text screen:
3083 @kbd{C-a [ M 20 l SPACE c 10 l 5 j C SPACE}.
3086 This moves one to the middle line of the screen, moves in 20 columns left,
3087 marks the beginning of the paste buffer, sets the left column, moves 5 columns
3088 down, sets the right column, and then marks the end of
3089 the paste buffer. Now try:@*
3090 @kbd{C-a [ M 20 l SPACE 10 l 5 j SPACE}
3093 and notice the difference in the amount of text copied.
3096 @kbd{J} joins lines. It toggles between 4 modes: lines separated by a
3097 newline character (012), lines glued seamless, lines separated by a single
3098 space or comma separated lines. Note that you can prepend the newline
3099 character with a carriage return character, by issuing a @code{set crlf
3103 @kbd{v} is for all the @code{vi} users who use @code{:set numbers} - it
3104 toggles the left margin between column 9 and 1.
3107 @kbd{a} before the final space key turns on append mode. Thus
3108 the contents of the paste buffer will not be overwritten, but appended to.
3111 @kbd{A} turns on append mode and sets a (second) mark.
3114 @kbd{>} sets the (second) mark and writes the contents of the paste buffer
3115 to the screen-exchange file (@file{/tmp/screen-exchange} per default)
3116 once copy-mode is finished. @xref{Screen Exchange}.@*
3117 This example demonstrates how to dump the
3118 whole scrollback buffer to that file: @*@kbd{C-a [ g SPACE G $ >}.
3121 @kbd{C-g} gives information about the current line and column.
3124 @kbd{x} exchanges the first mark and the current cursor position. You
3125 can use this to adjust an already placed mark.
3128 @kbd{@@} does nothing. Absolutely nothing. Does not even exit copy
3132 All keys not described here exit copy mode.
3134 @node Paste, Registers, Copy, Copy and Paste
3139 @deffn Command paste [registers [destination]]
3140 (@kbd{C-a ]}, @kbd{C-a C-]})@*
3141 Write the (concatenated) contents of the specified registers to the stdin
3142 stream of the current window. The register @samp{.} is treated as the
3143 paste buffer. If no parameter is specified the user is prompted to enter a
3144 single register. The paste buffer can be filled with the
3145 @code{copy}, @code{history} and @code{readbuf} commands.
3146 Other registers can be filled with the @code{register}, @code{readreg} and
3147 @code{paste} commands.
3148 If @code{paste} is called with a second argument, the contents of the specified
3149 registers is pasted into the named destination register rather than
3150 the window. If @samp{.} is used as the second argument, the display's paste
3151 buffer is the destination.
3152 Note, that @code{paste} uses a wide variety of resources: Usually both, a
3153 current window and a current display are required. But whenever a second
3154 argument is specified no current window is needed. When the source specification
3155 only contains registers (not the paste buffer) then there need not be a current
3156 display (terminal attached), as the registers are a global resource. The
3157 paste buffer exists once for every user.
3160 @deffn Command stuff string
3162 Stuff the string @var{string} in the input buffer of the current window.
3163 This is like the @code{paste} command, but with much less overhead.
3164 You cannot paste large buffers with the @code{stuff} command. It is most
3165 useful for key bindings. @xref{Bindkey}.
3168 @deffn Command pastefont [state]
3169 Tell screen to include font information in the paste buffer. The
3170 default is not to do so. This command is especially useful for
3171 multi character fonts like kanji.
3174 @deffn Command slowpaste msec
3175 @deffnx Command defslowpaste msec
3177 Define the speed text is inserted in the current window by the @code{paste}
3178 command. If the slowpaste value is nonzero text is written character by
3180 @code{screen} will pause for @var{msec} milliseconds after each write
3181 to allow the application to process the input. only use @code{slowpaste} if
3182 your underlying system exposes flow control problems while pasting large
3184 @code{defslowpaste} specifies the default for new windows.
3187 @deffn Command readreg [-e encoding] [register [filename]]
3189 Does one of two things, dependent on number of arguments: with zero or one
3190 arguments it it duplicates the paste buffer contents into the register specified
3191 or entered at the prompt. With two arguments it reads the contents of the named
3192 file into the register, just as @code{readbuf} reads the screen-exchange file
3193 into the paste buffer.
3194 You can tell screen the encoding of the file via the @code{-e} option.
3195 The following example will paste the system's password file into
3196 the screen window (using register p, where a copy remains):
3199 C-a : readreg p /etc/passwd
3204 @node Registers, Screen Exchange, Paste, Copy and Paste
3207 @deffn Command copy_reg [key]
3209 Removed. Use @code{readreg} instead.
3212 @deffn Command ins_reg [key]
3214 Removed. Use @code{paste} instead.
3217 @deffn Command process [key]
3219 Stuff the contents of the specified register into the @code{screen}
3220 input queue. If no argument is given you are prompted for a
3221 register name. The text is parsed as if it had been typed in from the user's
3222 keyboard. This command can be used to bind multiple actions to a single key.
3225 @deffn Command register [-e encoding] key string
3227 Save the specified @var{string} to the register @var{key}.
3228 The encoding of the string can be specified via the @code{-e} option.
3231 @node Screen Exchange, History, Registers, Copy and Paste
3232 @section Screen Exchange
3234 @deffn Command bufferfile [@var{exchange-file}]
3236 Change the filename used for reading and writing with the paste buffer.
3237 If the @var{exchange-file} parameter is omitted, @code{screen} reverts
3238 to the default of @file{/tmp/screen-exchange}. The following example
3239 will paste the system's password file into the screen window (using the
3240 paste buffer, where a copy remains):
3243 C-a : bufferfile /etc/passwd
3250 @deffn Command readbuf [-e @var{encoding}] [@var{filename}]
3252 Reads the contents of the specified file into the paste buffer.
3253 You can tell screen the encoding of the file via the @code{-e} option.
3254 If no file is specified, the screen-exchange filename is used.
3258 @deffn Command removebuf
3260 Unlinks the screen-exchange file.
3264 @deffn Command writebuf [-e @var{encoding}] [@var{filename}]
3266 Writes the contents of the paste buffer to the specified file, or the
3267 public accessible screen-exchange file if no filename is given.
3268 This is thought of as a primitive means of
3269 communication between @code{screen} users on the same host.
3270 If an encoding is specified the paste buffer is recoded on the fly to
3273 @kbd{C-a @key{ESC}} (@pxref{Copy}).
3276 @node History, , Screen Exchange, Copy and Paste
3281 @deffn Command history
3282 (@kbd{C-a @{}, @kbd{C-a @}})@*
3283 Usually users work with a shell that allows easy access to previous
3284 commands. For example, @code{csh} has the command @code{!!} to repeat
3285 the last command executed. @code{screen} provides a primitive way of
3286 recalling ``the command that started @dots{}'': You just type the first
3287 letter of that command, then hit @kbd{C-a @{} and @code{screen} tries to
3288 find a previous line that matches with the prompt character to the left
3289 of the cursor. This line is pasted into this window's input queue. Thus
3290 you have a crude command history (made up by the visible window and its
3294 @node Subprocess Execution, Key Binding, Copy and Paste, Top
3295 @chapter Subprocess Execution
3296 Control Input or Output of a window by another filter process.
3300 * Exec:: The @code{exec} command syntax.
3301 * Using Exec:: Weird things that filters can do.
3304 @node Exec, Using Exec, , Subprocess Execution
3306 @deffn Command exec [[@var{fdpat}] @var{newcommand} [@var{args} ... ]]
3308 Run a unix subprocess (specified by an executable path @var{newcommand} and
3309 its optional arguments) in the current window. The flow of data between
3310 newcommands stdin/stdout/stderr, the process originally started (let us call it
3311 "application-process") and
3312 screen itself (window) is controlled by the file descriptor pattern @var{fdpat}.
3313 This pattern is basically a three character sequence representing stdin, stdout
3314 and stderr of newcommand. A dot (@code{.}) connects the file descriptor
3315 to screen. An exclamation mark (@code{!}) causes the file descriptor to be
3316 connected to the application-process. A colon (@code{:}) combines both.
3318 User input will go to newcommand unless newcommand receives the
3319 application-process'
3320 output (@var{fdpat}s first character is @samp{!} or @samp{:}) or a pipe symbol
3321 (@samp{|}) is added to the end of @var{fdpat}.
3323 Invoking @code{exec} without arguments shows name and arguments of the currently
3324 running subprocess in this window. Only one subprocess can be running per
3327 When a subprocess is running the @code{kill} command will affect it instead of
3328 the windows process. Only one subprocess a time can be running in each window.
3330 Refer to the postscript file @file{doc/fdpat.ps} for a confusing
3331 illustration of all 21 possible combinations. Each drawing shows the digits
3332 2, 1, 0 representing the three file descriptors of newcommand. The box
3333 marked `W' is usual pty that has the application-process on its slave side.
3334 The box marked `P' is the secondary pty that now has screen at its master
3338 @node Using Exec, , Exec, Subprocess Execution
3345 Whitespace between the word @samp{exec} and @var{fdpat} and the command name
3349 Trailing dots and a @var{fdpat} consisting only of dots can be omitted.
3352 A simple @samp{|} is synonymous for the @samp{!..|} pattern.
3355 The word @samp{exec} can be omitted when the @samp{|} abbreviation is used.
3358 The word @samp{exec} can always be replaced by leading @samp{!}.
3367 @itemx exec ... /bin/sh
3368 All of the above are equivalent.
3369 Creates another shell in the same window, while the original shell is still
3370 running. Output of both shells is displayed and user input is sent to the new
3374 @itemx exec!stty 19200
3375 @itemx exec !.. stty 19200
3376 All of the above are equivalent.
3377 Set the speed of the window's tty. If your stty command operates on stdout,
3378 then add another @samp{!}. This is a useful command, when a screen window
3379 is directly connected to a serial line that needs to be configured.
3382 @itemx exec !..| less
3383 Both are equivalent.
3384 This adds a pager to the window output. The special character @samp{|} is
3385 needed to give the user control over the pager although it gets its input from
3386 the window's process. This works, because @samp{less} listens on stderr
3387 (a behavior that @code{screen} would not expect without the @samp{|})
3388 when its stdin is not a tty. @code{Less} versions newer than 177 fail miserably
3389 here; good old @code{pg} still works.
3391 @item !:sed -n s/.*Error.*/\007/p
3392 Sends window output to both, the user and the sed command. The sed inserts an
3393 additional bell character (oct. 007) to the window output seen by screen.
3394 This will cause 'Bell in window x' messages, whenever the string @samp{Error}
3395 appears in the window.
3398 @node Key Binding, Flow Control, Subprocess Execution, Top
3399 @chapter Key Binding
3403 You may disagree with some of the default bindings (I know I do). The
3404 @code{bind} command allows you to redefine them to suit your
3408 * Bind:: @code{bind} syntax.
3409 * Bind Examples:: Using @code{bind}.
3410 * Command Character:: The character used to start keyboard commands.
3411 * Help:: Show current key bindings.
3412 * Bindkey:: @code{bindkey} syntax.
3413 * Bindkey Examples:: Some easy examples.
3414 * Bindkey Control:: How to control the bindkey mechanism.
3417 @node Bind, Bind Examples, , Key Binding
3418 @section The @code{bind} command
3419 @deffn Command bind [-c class] key [command [args]]
3421 Bind a command to a key. The @var{key} argument is either a single
3422 character, a two-character sequence of the form @samp{^x} (meaning
3423 @kbd{C-x}), a backslash followed by an octal number (specifying the
3424 ASCII code of the character), or a backslash followed by a second
3425 character, such as @samp{\^} or @samp{\\}. The argument can also be
3426 quoted, if you like. If no further argument is given, any previously
3427 established binding for this key is removed. The @var{command}
3428 argument can be any command (@pxref{Command Index}).
3430 If a command class is specified via the @code{-c} option, the
3431 key is bound for the specified class. Use the @code{command}
3432 command to activate a class. Command classes can be used
3433 to create multiple command keys or multi-character bindings.
3435 By default, most suitable commands are bound to one or more keys
3436 (@pxref{Default Key Bindings}; for instance, the command to create a
3437 new window is bound to @kbd{C-c} and @kbd{c}. The @code{bind} command
3438 can be used to redefine the key bindings and to define new bindings.
3441 @deffn Command unbindall
3443 Unbind all the bindings. This can be useful when
3444 screen is used solely for its detaching abilities, such as when
3445 letting a console application run as a daemon. If, for some reason,
3446 it is necessary to bind commands after this, use 'screen -X'.
3449 @node Bind Examples, Command Character, Bind, Key Binding
3450 @section Examples of the @code{bind} command
3456 bind ^f screen telnet foobar
3457 bind \033 screen -ln -t root -h 1000 9 su
3461 would bind the space key to the command that displays a list of windows
3462 (so that the command usually invoked by @kbd{C-a C-w} would also be
3463 available as @kbd{C-a space}), bind @kbd{C-f} to the command
3464 ``create a window with a TELNET connection to foobar'', and bind
3465 @key{ESC} to the command that creates an non-login window with title
3466 @samp{root} in slot #9, with a superuser shell and a scrollback buffer
3470 bind -c demo1 0 select 10
3471 bind -c demo1 1 select 11
3472 bind -c demo1 2 select 12
3473 bindkey "^B" command -c demo1
3475 makes @kbd{C-b 0} select window 10, @kbd{C-b 1} window 11, etc.
3478 bind -c demo2 0 select 10
3479 bind -c demo2 1 select 11
3480 bind -c demo2 2 select 12
3481 bind - command -c demo2
3483 makes @kbd{C-a - 0} select window 10, @kbd{C-a - 1} window 11, etc.
3485 @node Command Character, Help, Bind Examples, Key Binding
3486 @cindex escape character
3487 @cindex command character
3488 @section Command Character
3490 @deffn Command escape xy
3492 Set the command character to @var{x} and the character generating a
3493 literal command character (by triggering the @code{meta} command)
3494 to @var{y} (similar to the @samp{-e} option).
3495 Each argument is either a single character, a two-character
3496 sequence of the form @samp{^x} (meaning @kbd{C-x}), a backslash followed
3497 by an octal number (specifying the ASCII code of the character), or a
3498 backslash followed by a second character, such as @samp{\^} or
3499 @samp{\\}. The default is @samp{^Aa}, but @samp{``} is recommended by
3503 @deffn Command defescape xy
3505 Set the default command characters. This is equivalent to the command
3506 @code{escape} except that it is useful for multiuser sessions only.
3507 In a multiuser session
3508 @code{escape} changes the command character of the calling user, where
3509 @code{defescape} changes the default command characters for users that
3510 will be added later.
3516 Send the command character (@kbd{C-a}) to the process in the current
3517 window. The keystroke for this command is the second parameter to the
3518 @samp{-e} command line switch (@pxref{Invoking Screen}), or the
3519 @code{escape} .screenrc directive.
3522 @deffn Command command [-c @var{class}]
3524 This command has the same effect as typing the screen escape character
3525 (@kbd{C-a}). It is probably only useful for key bindings.
3526 If the @samp{-c} option is given, select the specified command class.
3527 @xref{Bind}, @xref{Bindkey}.
3530 @node Help, Bindkey, Command Character, Key Binding
3535 Displays a help screen showing you all the key bindings. The first
3536 pages list all the internal commands followed by their bindings.
3537 Subsequent pages will display the custom commands, one command per key.
3538 Press space when you're done reading each page, or return to exit early.
3539 All other characters are ignored.
3540 If the @samp{-c} option is given, display all bound commands for the
3541 specified command class.
3542 @xref{Default Key Bindings}.
3545 @node Bindkey, Bindkey Examples, Help, Key Binding
3547 @deffn Command bindkey [@var{opts}] [@var{string} [@var{cmd} @var{args}]]
3549 This command manages screen's input translation tables. Every
3550 entry in one of the tables tells screen how to react if a certain
3551 sequence of characters is encountered. There are three tables:
3552 one that should contain actions programmed by the user, one for
3553 the default actions used for terminal emulation and one for
3554 screen's copy mode to do cursor movement. See @ref{Input Translation}
3555 for a list of default key bindings.
3558 option is given, bindkey modifies the default table, @samp{-m}
3559 changes the copy mode table and with neither option the user
3560 table is selected. The argument @samp{string} is the sequence of
3561 characters to which an action is bound. This can either be a fixed
3562 string or a termcap keyboard capability name (selectable with the
3565 Some keys on a VT100 terminal can send a different
3566 string if application mode is turned on (e.g. the cursor keys).
3567 Such keys have two entries in the translation table. You can
3568 select the application mode entry by specifying the @samp{-a}
3571 The @samp{-t} option tells screen not to do inter-character
3572 timing. One cannot turn off the timing if a termcap capability is
3575 @samp{cmd} can be any of screen's commands with an arbitrary
3576 number of @samp{args}. If @samp{cmd} is omitted the key-binding is
3577 removed from the table.
3580 @node Bindkey Examples, Bindkey Control,Bindkey, Key Binding
3581 @section Bindkey Examples
3583 Here are some examples of keyboard bindings:
3589 Show all of the default key bindings. The application mode entries
3590 are marked with [A].
3593 bindkey -k k1 select 1
3596 Make the "F1" key switch to window one.
3599 bindkey -t foo stuff barfoo
3602 Make @samp{foo} an abbreviation of the word @samp{barfoo}. Timeout is
3603 disabled so that users can type slowly.
3606 bindkey "\024" mapdefault
3609 This key-binding makes @samp{C-t} an escape character for key-bindings. If
3610 you did the above @samp{stuff barfoo} binding, you can enter the word
3611 @samp{foo} by typing @samp{C-t foo}. If you want to insert a
3612 @samp{C-t} you have to press the key twice (i.e., escape the escape
3616 bindkey -k F1 command
3619 Make the F11 (not F1!) key an alternative screen
3620 escape (besides @samp{C-a}).
3622 @node Bindkey Control, , Bindkey Examples, Key Binding
3623 @section Bindkey Control
3624 @deffn Command mapdefault
3626 Tell screen that the next input character should only be looked up
3627 in the default bindkey table.
3629 @deffn Command mapnotnext
3631 Like mapdefault, but don't even look in the default bindkey table.
3633 @deffn Command maptimeout timo
3635 Set the inter-character timer for input sequence detection to a timeout
3636 of @var{timo} ms. The default timeout is 300ms. Maptimeout with no
3637 arguments shows the current setting.
3640 @node Flow Control, Termcap, Key Binding, Top
3641 @chapter Flow Control
3642 @cindex flow control
3644 @code{screen} can trap flow control characters or pass them to the
3645 program, as you see fit. This is useful when your terminal wants to use
3646 XON/XOFF flow control and you are running a program which wants to use
3647 ^S/^Q for other purposes (i.e. @code{emacs}).
3650 * Flow Control Summary:: The effect of @code{screen} flow control
3651 * Flow:: Setting the flow control behavior
3652 * XON/XOFF:: Sending XON or XOFF to the window
3655 @node Flow Control Summary, Flow, , Flow Control
3656 @section About @code{screen} flow control settings
3657 Each window has a flow-control setting that determines how screen deals
3658 with the XON and XOFF characters (and perhaps the interrupt character).
3659 When flow-control is turned off, screen ignores the XON and XOFF
3660 characters, which allows the user to send them to the current program by
3661 simply typing them (useful for the @code{emacs} editor, for instance).
3662 The trade-off is that it will take longer for output from a
3663 ``normal'' program to pause in response to an XOFF. With
3664 flow-control turned on, XON and XOFF characters are used to immediately
3665 pause the output of the current window. You can still send these
3666 characters to the current program, but you must use the appropriate
3667 two-character screen commands (typically @kbd{C-a q} (xon) and @kbd{C-a
3668 s} (xoff)). The xon/xoff commands are also useful for typing C-s and
3669 C-q past a terminal that intercepts these characters.
3671 Each window has an initial flow-control value set with either the
3672 @samp{-f} option or the @code{defflow} command. By default the
3673 windows are set to automatic flow-switching. It can then be toggled
3674 between the three states 'fixed on', 'fixed off' and 'automatic'
3675 interactively with the @code{flow} command bound to @kbd{C-a f}.
3677 The automatic flow-switching mode deals with flow control using the
3678 TIOCPKT mode (like @code{rlogin} does). If the tty driver does not
3679 support TIOCPKT, screen tries to determine the right mode based on the
3680 current setting of the application keypad --- when it is enabled,
3681 flow-control is turned off and visa versa. Of course, you can still
3682 manipulate flow-control manually when needed.
3684 If you're running with flow-control enabled and find that pressing the
3685 interrupt key (usually C-c) does not interrupt the display until another
3686 6-8 lines have scrolled by, try running screen with the @samp{interrupt}
3687 option (add the @samp{interrupt} flag to the @code{flow} command in your
3688 .screenrc, or use the @samp{-i} command-line option). This causes the
3689 output that @code{screen} has accumulated from the interrupted program
3690 to be flushed. One disadvantage is that the virtual terminal's memory
3691 contains the non-flushed version of the output, which in rare cases can
3692 cause minor inaccuracies in the output. For example, if you switch
3693 screens and return, or update the screen with @kbd{C-a l} you would see
3694 the version of the output you would have gotten without @samp{interrupt}
3695 being on. Also, you might need to turn off flow-control (or use
3696 auto-flow mode to turn it off automatically) when running a program that
3697 expects you to type the interrupt character as input, as the
3698 @samp{interrupt} parameter only takes effect when flow-control is
3699 enabled. If your program's output is interrupted by mistake, a simple
3700 refresh of the screen with @kbd{C-a l} will restore it. Give each mode
3701 a try, and use whichever mode you find more comfortable.
3703 @node Flow, XON/XOFF, Flow Control Summary, Flow Control
3705 @deffn Command defflow fstate [interrupt]
3707 Same as the @code{flow} command except that the default setting for new
3708 windows is changed. Initial setting is `auto'.
3709 Specifying @code{flow auto interrupt} has the same effect as the
3710 command-line options @samp{-fa} and @samp{-i}.
3711 Note that if @samp{interrupt} is enabled, all existing displays are
3712 changed immediately to forward interrupt signals.
3717 @deffn Command flow [fstate]
3718 (@kbd{C-a f}, @kbd{C-a C-f})@*
3719 Sets the flow-control mode for this window to @var{fstate}, which can be
3720 @samp{on}, @samp{off} or @samp{auto}.
3721 Without parameters it cycles the current window's
3722 flow-control setting. Default is set by `defflow'.
3725 @node XON/XOFF, , Flow, Flow Control
3726 @section XON and XOFF
3730 (@kbd{C-a q}, @kbd{C-a C-q})@*
3731 Send a ^Q (ASCII XON) to the program in the current window. Redundant
3732 if flow control is set to @samp{off} or @samp{auto}.
3738 (@kbd{C-a s}, @kbd{C-a C-s})@*
3739 Send a ^S (ASCII XOFF) to the program in the current window.
3742 @node Termcap, Message Line, Flow Control, Top
3745 @code{screen} demands the most out of your terminal so that it can
3746 perform its VT100 emulation most efficiently. These functions provide
3747 means for tweaking the termcap entries for both your physical terminal
3748 and the one simulated by @code{screen}.
3751 * Window Termcap:: Choosing a termcap entry for the window.
3752 * Dump Termcap:: Write out a termcap entry for the window.
3753 * Termcap Syntax:: The @code{termcap} and @code{terminfo} commands.
3754 * Termcap Examples:: Uses for @code{termcap}.
3755 * Special Capabilities:: Non-standard capabilities used by @code{screen}.
3756 * Autonuke:: Flush unseen output
3757 * Obuflimit:: Allow pending output when reading more
3758 * Character Translation:: Emulating fonts and charsets.
3761 @node Window Termcap, Dump Termcap, , Termcap
3762 @section Choosing the termcap entry for a window
3763 Usually @code{screen} tries to emulate as much of the VT100/ANSI
3764 standard as possible. But if your terminal lacks certain capabilities
3765 the emulation may not be complete. In these cases @code{screen} has to
3766 tell the applications that some of the features are missing. This is no
3767 problem on machines using termcap, because @code{screen} can use the
3768 @code{$TERMCAP} variable to customize the standard screen termcap.
3770 But if you do a rlogin on another machine or your machine supports only
3771 terminfo this method fails. Because of this @code{screen} offers a way
3772 to deal with these cases. Here is how it works:
3774 When @code{screen} tries to figure out a terminal name for itself, it
3775 first looks for an entry named @code{screen.@var{term}}, where
3776 @var{term} is the contents of your @code{$TERM} variable. If no such entry
3777 exists, @code{screen} tries @samp{screen} (or @samp{screen-w}, if the
3778 terminal is wide (132 cols or more)). If even this entry cannot be
3779 found, @samp{vt100} is used as a substitute.
3781 The idea is that if you have a terminal which doesn't support an
3782 important feature (e.g. delete char or clear to EOS) you can build a new
3783 termcap/terminfo entry for @code{screen} (named
3784 @samp{screen.@var{dumbterm}}) in which this capability has been
3785 disabled. If this entry is installed on your machines you are able to
3786 do a rlogin and still keep the correct termcap/terminfo entry. The
3787 terminal name is put in the @code{$TERM} variable of all new windows.
3788 @code{screen} also sets the @code{$TERMCAP} variable reflecting the
3789 capabilities of the virtual terminal emulated.
3790 Furthermore, the variable @code{$WINDOW} is set to the window number of each
3793 The actual set of capabilities supported by the virtual terminal depends
3794 on the capabilities supported by the physical terminal. If, for
3795 instance, the physical terminal does not support underscore mode,
3796 @code{screen} does not put the @samp{us} and @samp{ue} capabilities into
3797 the window's @code{$TERMCAP} variable, accordingly. However, a minimum number
3798 of capabilities must be supported by a terminal in order to run
3799 @code{screen}; namely scrolling, clear screen, and direct cursor
3800 addressing (in addition, @code{screen} does not run on hardcopy
3801 terminals or on terminals that over-strike).
3803 Also, you can customize the @code{$TERMCAP} value used by @code{screen} by
3804 using the @code{termcap} command, or by defining the variable
3805 @code{$SCREENCAP} prior to startup. When the latter defined, its value will be
3806 copied verbatim into each window's @code{$TERMCAP} variable. This can either
3807 be the full terminal definition, or a filename where the terminal
3808 @samp{screen} (and/or @samp{screen-w}) is defined.
3810 Note that @code{screen} honors the @code{terminfo} command if the system
3811 uses the terminfo database rather than termcap. On such machines the
3812 @code{$TERMCAP} variable has no effect and you must use the
3813 @code{dumptermcap} command (@pxref{Dump Termcap}) and the @code{tic}
3814 program to generate terminfo entries for @code{screen} windows.
3816 When the boolean @samp{G0} capability is present in the termcap entry
3817 for the terminal on which @code{screen} has been called, the terminal
3818 emulation of @code{screen} supports multiple character sets. This
3819 allows an application to make use of, for instance, the VT100 graphics
3820 character set or national character sets. The following control
3821 functions from ISO 2022 are supported: @samp{lock shift G0} (@samp{SI}),
3822 @samp{lock shift G1} (@samp{SO}), @samp{lock shift G2}, @samp{lock shift
3823 G3}, @samp{single shift G2}, and @samp{single shift G3}. When a virtual
3824 terminal is created or reset, the ASCII character set is designated as
3825 @samp{G0} through @samp{G3}. When the @samp{G0} capability is present,
3826 screen evaluates the capabilities @samp{S0}, @samp{E0}, and @samp{C0} if
3827 present. @samp{S0} is the sequence the terminal uses to enable and start
3828 the graphics character set rather than @samp{SI}. @samp{E0} is the
3829 corresponding replacement for @samp{SO}. @samp{C0} gives a character by
3830 character translation string that is used during semi-graphics mode.
3831 This string is built like the @samp{acsc} terminfo capability.
3833 When the @samp{po} and @samp{pf} capabilities are present in the
3834 terminal's termcap entry, applications running in a @code{screen} window
3835 can send output to the printer port of the terminal. This allows a user
3836 to have an application in one window sending output to a printer
3837 connected to the terminal, while all other windows are still active (the
3838 printer port is enabled and disabled again for each chunk of output).
3839 As a side-effect, programs running in different windows can send output
3840 to the printer simultaneously. Data sent to the printer is not
3841 displayed in the window. The @code{info} command displays a line starting
3842 with @samp{PRIN} while the printer is active.
3844 Some capabilities are only put into the @code{$TERMCAP} variable of the virtual
3845 terminal if they can be efficiently implemented by the physical
3846 terminal. For instance, @samp{dl} (delete line) is only put into the
3847 @code{$TERMCAP} variable if the terminal supports either delete line itself or
3848 scrolling regions. Note that this may provoke confusion, when the
3849 session is reattached on a different terminal, as the value of @code{$TERMCAP}
3850 cannot be modified by parent processes. You can force @code{screen} to
3851 include all capabilities in @code{$TERMCAP} with the @samp{-a}
3852 command-line option (@pxref{Invoking Screen}).
3854 The "alternate screen" capability is not enabled by default.
3855 Set the @code{altscreen} @file{.screenrc} command to enable it.
3857 @node Dump Termcap, Termcap Syntax, Window Termcap, Termcap
3858 @section Write out the window's termcap entry
3860 @deffn Command dumptermcap
3862 Write the termcap entry for the virtual terminal optimized for the
3863 currently active window to the file @file{.termcap} in the user's
3864 @file{$HOME/.screen} directory (or wherever @code{screen} stores its
3865 sockets. @pxref{Files}). This termcap entry is identical to
3866 the value of the environment variable @code{$TERMCAP} that is set up by
3867 @code{screen} for each window. For terminfo based systems you will need
3868 to run a converter like @code{captoinfo} and then compile the entry with
3872 @node Termcap Syntax, Termcap Examples, Dump Termcap, Termcap
3873 @section The @code{termcap} command
3874 @deffn Command termcap term terminal-tweaks [window-tweaks]
3875 @deffnx Command terminfo term terminal-tweaks [window-tweaks]
3876 @deffnx Command termcapinfo term terminal-tweaks [window-tweaks]
3878 Use this command to modify your terminal's termcap entry without going
3879 through all the hassles involved in creating a custom termcap entry.
3880 Plus, you can optionally customize the termcap generated for the
3882 You have to place these commands in one of the screenrc startup files, as they
3883 are meaningless once the terminal emulator is booted.
3885 If your system uses the terminfo database rather than termcap,
3886 @code{screen} will understand the @code{terminfo} command, which has the
3887 same effects as the @code{termcap} command. Two separate commands are
3888 provided, as there are subtle syntactic differences, e.g. when parameter
3889 interpolation (using @samp{%}) is required. Note that the termcap names of
3890 the capabilities should also be used with the @code{terminfo} command.
3892 In many cases, where the arguments are valid in both terminfo and termcap
3893 syntax, you can use the command @code{termcapinfo}, which is just a
3894 shorthand for a pair of @code{termcap} and @code{terminfo} commands with
3895 identical arguments.
3898 The first argument specifies which terminal(s) should be affected by
3899 this definition. You can specify multiple terminal names by separating
3900 them with @samp{|}s. Use @samp{*} to match all terminals and @samp{vt*}
3901 to match all terminals that begin with @samp{vt}.
3903 Each @var{tweak} argument contains one or more termcap defines
3904 (separated by @samp{:}s) to be inserted at the start of the appropriate
3905 termcap entry, enhancing it or overriding existing values. The first
3906 tweak modifies your terminal's termcap, and contains definitions that
3907 your terminal uses to perform certain functions. Specify a null string
3908 to leave this unchanged (e.g. ""). The second (optional) tweak modifies
3909 all the window termcaps, and should contain definitions that screen
3910 understands (@pxref{Virtual Terminal}).
3912 @node Termcap Examples, Special Capabilities, Termcap Syntax, Termcap
3913 @section Termcap Examples
3917 termcap xterm* xn:hs@@
3921 Informs @code{screen} that all terminals that begin with @samp{xterm}
3922 have firm auto-margins that allow the last position on the screen to be
3923 updated (xn), but they don't really have a status line (no 'hs' --
3924 append @samp{@@} to turn entries off). Note that we assume @samp{xn} for
3925 all terminal names that start with @samp{vt}, but only if you don't
3926 specify a termcap command for that terminal.
3930 termcap vt102|vt220 Z0=\E[?3h:Z1=\E[?3l
3934 Specifies the firm-margined @samp{xn} capability for all terminals that
3935 begin with @samp{vt}, and the second line will also add the
3936 escape-sequences to switch into (Z0) and back out of (Z1)
3937 132-character-per-line mode if this is a VT102 or VT220. (You must
3938 specify Z0 and Z1 in your termcap to use the width-changing commands.)
3941 termcap vt100 "" l0=PF1:l1=PF2:l2=PF3:l3=PF4
3945 This leaves your vt100 termcap alone and adds the function key labels to
3946 each window's termcap entry.
3949 termcap h19|z19 am@@:im=\E@@:ei=\EO dc=\E[P
3953 Takes a h19 or z19 termcap and turns off auto-margins (am@@) and enables
3954 the insert mode (im) and end-insert (ei) capabilities (the @samp{@@} in
3955 the @samp{im} string is after the @samp{=}, so it is part of the
3956 string). Having the @samp{im} and @samp{ei} definitions put into your
3957 terminal's termcap will cause screen to automatically advertise the
3958 character-insert capability in each window's termcap. Each window will
3959 also get the delete-character capability (dc) added to its termcap,
3960 which screen will translate into a line-update for the terminal (we're
3961 pretending it doesn't support character deletion).
3963 If you would like to fully specify each window's termcap entry, you
3964 should instead set the @code{$SCREENCAP} variable prior to running
3965 @code{screen}. @xref{Virtual Terminal}, for the details of the
3966 @code{screen} terminal emulation. @xref{Top, , Termcap, termcap, The
3967 Termcap Manual}, for more information on termcap definitions.
3969 @node Special Capabilities, Autonuke, Termcap Examples, Termcap
3970 @section Special Terminal Capabilities
3971 @cindex terminal capabilities
3972 @cindex capabilities
3973 The following table describes all terminal capabilities that are
3974 recognized by @code{screen} and are not in the termcap manual
3975 (@pxref{Top, , Termcap, termcap, The Termcap Manual}).
3976 You can place these capabilities in your termcap entries (in
3977 @file{/etc/termcap}) or use them with the commands @code{termcap},
3978 @code{terminfo} and @code{termcapinfo} in your @code{screenrc} files. It is
3979 often not possible to place these capabilities in the terminfo database.
3983 Terminal has VT100 style margins (`magic margins'). Note that
3984 this capability is obsolete --- @code{screen} now uses the standard
3989 Change width to 132 columns.
3993 Change width to 80 columns.
3997 Resize display. This capability has the desired width and height as
3998 arguments. SunView(tm) example: @samp{\E[8;%d;%dt}.
4002 Terminal doesn't need flow control. Send ^S and ^Q direct to
4003 the application. Same as @code{flow off}. The opposite of this
4004 capability is @samp{nx}.
4008 Terminal can deal with ISO 2022 font selection sequences.
4012 Switch charset @samp{G0} to the specified charset. Default
4017 Switch charset @samp{G0} back to standard charset. Default
4022 Use the string as a conversion table for font 0. See
4023 the @samp{ac} capability for more details.
4027 Switch cursor-keys to application mode.
4031 Switch cursor-keys to cursor mode.
4035 Enable autonuke for displays of this terminal type.
4040 Set the output buffer limit. See the @samp{obuflimit} command
4041 (@pxref{Obuflimit}) for more details.
4045 Set the encoding of the terminal. See the @samp{encoding} command
4046 (@pxref{Character Processing}) for valid encodings.
4050 Change character foreground color in an ANSI conform way. This
4051 capability will almost always be set to @samp{\E[3%dm}
4052 (@samp{\E[3%p1%dm} on terminfo machines).
4056 Same as @samp{AF}, but change background color.
4060 Does understand ANSI set default fg/bg color (@samp{\E[39m / \E[49m}).
4064 Describe a translation of characters to strings depending on the
4065 current font. (@pxref{Character Translation}).
4069 Terminal understands special xterm sequences (OSC, mouse tracking).
4073 Terminal needs bold to display high-intensity colors (e.g. Eterm).
4077 Add missing capabilities to the termcap/info entry. (Set by default).
4080 @node Autonuke, Obuflimit, Special Capabilities, Termcap
4082 @deffn Command autonuke @var{state}
4084 Sets whether a clear screen sequence should nuke all the output
4085 that has not been written to the terminal. @xref{Obuflimit}.
4086 This property is set per display, not per window.
4089 @deffn Command defautonuke @var{state}
4091 Same as the @code{autonuke} command except that the default setting for
4092 new displays is also changed. Initial setting is @code{off}.
4093 Note that you can use the special @code{AN} terminal capability if you
4094 want to have a terminal type dependent setting.
4097 @node Obuflimit, Character Translation, Autonuke, Termcap
4099 @deffn Command obuflimit [@var{limit}]
4101 If the output buffer contains more bytes than the specified limit, no
4102 more data will be read from the windows. The default value is 256. If
4103 you have a fast display (like @code{xterm}), you can set it to some
4104 higher value. If no argument is specified, the current setting is displayed.
4105 This property is set per display, not per window.
4108 @deffn Command defobuflimit @var{limit}
4110 Same as the @code{obuflimit} command except that the default setting for new
4111 displays is also changed. Initial setting is 256 bytes. Note that you can use
4112 the special @code{OL} terminal capability if you want to have a terminal
4113 type dependent limit.
4116 @node Character Translation, , Obuflimit, Termcap
4117 @section Character Translation
4118 @code{Screen} has a powerful mechanism to translate characters to
4119 arbitrary strings depending on the current font and terminal type.
4120 Use this feature if you want to work with a common standard character
4121 set (say ISO8851-latin1) even on terminals that scatter the more
4122 unusual characters over several national language font pages.
4127 XC=@var{<charset-mapping>}@{,,@var{<charset-mapping>}@}
4128 @var{<charset-mapping>} := @var{<designator>}@var{<template>}@{,@var{<mapping>}@}
4129 @var{<mapping>} := @var{<char-to-be-mapped>}@var{<template-arg>}
4132 The things in braces may be repeated any number of times.
4134 A @var{<charset-mapping>} tells screen how to map characters
4135 in font @var{<designator>} (@samp{B}: Ascii, @samp{A}: UK,
4136 @samp{K}: german, etc.)
4137 to strings. Every @var{<mapping>} describes to what string a single
4138 character will be translated. A template mechanism is used, as
4139 most of the time the codes have a lot in common (for example
4140 strings to switch to and from another charset). Each occurrence
4141 of @samp{%} in @var{<template>} gets substituted with the
4143 specified together with the character. If your strings are not
4144 similar at all, then use @samp{%} as a template and place the full
4145 string in @var{<template-arg>}. A quoting mechanism was added to make
4146 it possible to use a real @samp{%}. The @samp{\} character quotes the
4147 special characters @samp{\}, @samp{%}, and @samp{,}.
4152 termcap hp700 'XC=B\E(K%\E(B,\304[,\326\\\\,\334]'
4155 This tells @code{screen}, how to translate ISOlatin1 (charset @samp{B})
4156 upper case umlaut characters on a @code{hp700} terminal that has a
4157 German charset. @samp{\304} gets translated to
4158 @samp{\E(K[\E(B} and so on.
4159 Note that this line gets parsed *three* times before the internal
4160 lookup table is built, therefore a lot of quoting is needed to
4161 create a single @samp{\}.
4163 Another extension was added to allow more emulation: If a mapping
4164 translates the unquoted @samp{%} char, it will be sent to the terminal
4165 whenever screen switches to the corresponding @var{<designator>}.
4167 special case the template is assumed to be just @samp{%} because
4168 the charset switch sequence and the character mappings normally
4169 haven't much in common.
4171 This example shows one use of the extension:
4173 termcap xterm 'XC=K%,%\E(B,[\304,\\\\\326,]\334'
4176 Here, a part of the German (@samp{K}) charset is emulated on an xterm.
4177 If screen has to change to the @samp{K} charset, @samp{\E(B} will be
4179 to the terminal, i.e. the ASCII charset is used instead. The
4180 template is just @samp{%}, so the mapping is straightforward:
4181 @samp{[} to @samp{\304}, @samp{\} to @samp{\326}, and @samp{]} to
4184 @node Message Line, Logging, Termcap, Top
4185 @chapter The Message Line
4186 @cindex message line
4188 @code{screen} displays informational messages and other diagnostics in a
4189 @dfn{message line} at the bottom of the screen. If your terminal has a
4190 status line defined in its termcap, screen will use this for displaying
4191 its messages, otherwise the last line of the screen will be temporarily
4192 overwritten and output will be momentarily interrupted. The message
4193 line is automatically removed after a few seconds delay, but it can also
4194 be removed early (on terminals without a status line) by beginning to
4198 * Privacy Message:: Using the message line from your program.
4199 * Hardware Status Line:: Use the terminal's hardware status line.
4200 * Last Message:: Redisplay the last message.
4201 * Message Wait:: Control how long messages are displayed.
4204 @node Privacy Message, Hardware Status Line, , Message Line
4205 @section Using the message line from your program
4206 The message line facility can be used by an application running in the
4207 current window by means of the ANSI @dfn{Privacy message} control
4208 sequence. For instance, from within the shell, try something like:
4211 echo "@value{esc}^Hello world from window $WINDOW@value{esc}\"
4214 where @samp{@value{esc}} is ASCII ESC and the @samp{^} that follows it
4215 is a literal caret or up-arrow.
4217 @node Hardware Status Line, Last Message, Privacy Message, Message Line
4218 @section Hardware Status Line
4219 @deffn Command hardstatus [state]
4220 @deffnx Command hardstatus [@code{always}]@code{lastline}|@code{message}|@code{ignore} [string]
4221 @deffnx Command hardstatus @code{string} [string]
4223 This command configures the use and emulation of the terminal's
4224 hardstatus line. The first form toggles whether @code{screen}
4225 will use the hardware status line to display messages. If the
4226 flag is set to @samp{off}, these messages
4227 are overlaid in reverse video mode at the display line. The default
4228 setting is @samp{on}.
4230 The second form tells screen what to do if the terminal doesn't
4231 have a hardstatus line (i.e. the termcap/terminfo capabilities
4232 "hs", "ts", "fs" and "ds" are not set). If the type
4233 @code{lastline} is used, screen will reserve the last line of the
4234 display for the hardstatus. @code{message} uses
4235 @code{screen}'s message mechanism and
4236 @code{ignore} tells @code{screen} never to display the hardstatus.
4237 If you prepend the word @code{always} to the type (e.g., @code{alwayslastline}), @code{screen} will use
4238 the type even if the terminal supports a hardstatus line.
4240 The third form specifies the contents of the hardstatus line.
4241 @code{%h} is used as default string, i.e., the stored hardstatus of the
4242 current window (settable via @samp{ESC]0;^G} or @samp{ESC_\\}) is
4244 You can customize this to any string you like including
4245 string escapes (@pxref{String Escapes}).
4247 out the argument @var{string}, the current string is displayed.
4249 You can mix the second and third form by providing the string as
4250 additional argument.
4253 @node Last Message, Message Wait, Hardware Status Line, Message Line
4254 @section Display Last Message
4257 @deffn Command lastmsg
4258 (@kbd{C-a m}, @kbd{C-a C-m})@*
4259 Repeat the last message displayed in the message line. Useful if you're
4260 typing when a message appears, because (unless your terminal has a
4261 hardware status line) the message goes away when you press a key.
4264 @node Message Wait, , Last Message, Message Line
4265 @section Message Wait
4266 @deffn Command msgminwait sec
4268 Defines the time @code{screen} delays a new message when another is
4269 currently displayed. Defaults to 1 second.
4272 @deffn Command msgwait sec
4274 Defines the time a message is displayed, if @code{screen} is not
4275 disturbed by other activity. Defaults to 5 seconds.
4278 @node Logging, Startup, Message Line, Top
4281 This section describes the commands for keeping a record of your session.
4284 * Hardcopy:: Dump the current screen to a file
4285 * Log:: Log the output of a window to a file
4288 @node Hardcopy, Log, , Logging
4291 @deffn Command hardcopy [-h] [@var{file}]
4293 Writes out the currently displayed image to the file @var{file}, or,
4294 if no filename is specified, to @file{hardcopy.@var{n}}
4295 in the default directory, where @var{n} is the number of the
4296 current window. This either appends or overwrites the file if it
4297 exists, as determined by the @code{hardcopy_append} command.
4298 If the option @code{-h} is specified, dump also the
4299 contents of the scrollback buffer.
4302 @deffn Command hardcopy_append state
4304 If set to @samp{on}, @code{screen} will append to the
4305 @file{hardcopy.@var{n}} files created by the command @code{hardcopy};
4306 otherwise, these files are overwritten each time.
4309 @deffn Command hardcopydir directory
4311 Defines a directory where hardcopy files will be placed.
4312 If unset, hardcopys are dumped in screen's current working
4316 @node Log, , Hardcopy, Logging
4319 @deffn Command deflog state
4321 Same as the @code{log} command except that the default setting for new
4322 windows is changed. Initial setting is `off'.
4326 @deffn Command log [state]
4328 Begins/ends logging of the current window to the file
4329 @file{screenlog.@var{n}} in the window's default directory, where
4330 @var{n} is the number of the current window.
4331 This filename can be changed with the @samp{logfile} command.
4332 If no parameter is given,
4333 the logging state is toggled. The session log is
4334 appended to the previous contents of the file if it already exists. The
4335 current contents and the contents of the scrollback history are not
4336 included in the session log. Default is @samp{off}.
4339 @deffn Command logfile filename
4340 @deffnx Command logfile flush secs
4342 Defines the name the log files will get. The default is @samp{screenlog.%n}.
4343 The second form changes the number of seconds @code{screen}
4344 will wait before flushing the logfile buffer to the file-system. The
4345 default value is 10 seconds.
4348 @deffn Command logtstamp [state]
4349 @deffnx Command logtstamp @code{after} secs
4350 @deffnx Command logtstamp @code{string} string
4352 This command controls logfile time-stamp mechanism of screen. If
4353 time-stamps are turned @samp{on}, screen adds a string containing
4354 the current time to the logfile after two minutes of inactivity.
4355 When output continues and more than another two minutes have passed,
4356 a second time-stamp is added to document the restart of the
4357 output. You can change this timeout with the second form
4358 of the command. The third form is used for customizing the time-stamp
4359 string (@samp{-- %n:%t -- time-stamp -- %M/%d/%y %c:%s --\n} by
4363 @node Startup, Miscellaneous, Logging, Top
4366 This section describes commands which are only useful in the
4367 @file{.screenrc} file, for use at startup.
4370 * echo:: Display a message.
4371 * sleep:: Pause execution of the @file{.screenrc}.
4372 * Startup Message:: Control display of the copyright notice.
4375 @node echo, sleep, , Startup
4377 @deffn Command echo [@samp{-n}] message
4379 The echo command may be used to annoy @code{screen} users with a
4380 'message of the day'. Typically installed in a global screenrc.
4381 The option @samp{-n} may be used to suppress the line feed.
4382 See also @code{sleep}.
4383 Echo is also useful for online checking of environment variables.
4386 @node sleep, Startup Message, echo, Startup
4388 @deffn Command sleep num
4390 This command will pause the execution of a .screenrc file for @var{num}
4391 seconds. Keyboard activity will end the sleep. It may be used to give
4392 users a chance to read the messages output by @code{echo}.
4395 @node Startup Message, , sleep, Startup
4396 @section Startup Message
4397 @deffn Command startup_message state
4399 Select whether you want to see the copyright notice during startup.
4400 Default is @samp{on}, as you probably noticed.
4403 @node Miscellaneous, String Escapes, Startup, Top
4404 @chapter Miscellaneous commands
4406 The commands described here do not fit well under any of the other
4410 * At:: Execute a command at other displays or windows.
4411 * Break:: Send a break signal to the window.
4412 * Debug:: Suppress/allow debugging output.
4413 * License:: Display the disclaimer page.
4414 * Nethack:: Use @code{nethack}-like error messages.
4415 * Nonblock:: Disable flow-control to a display.
4416 * Number:: Change the current window's number.
4417 * Silence:: Notify on inactivity.
4418 * Time:: Display the time and load average.
4419 * Verbose:: Display window creation commands.
4420 * Version:: Display the version of @code{screen}.
4421 * Zombie:: Keep dead windows.
4422 * Printcmd:: Set command for VT100 printer port emulation.
4423 * Rendition:: Change text attributes in caption for flagged windows.
4424 * Sorendition:: Change the text highlighting method.
4425 * Attrcolor:: Map attributes to colors.
4426 * Setsid:: Change process group management.
4427 * Eval:: Parse and execute arguments.
4428 * Maxwin:: Set the maximum window number.
4429 * Backtick:: Program a command for a backtick string escape.
4430 * Screen Saver:: Define a screen safer.
4431 * Zmodem:: Define how screen treats zmodem requests.
4432 * Mousetrack:: Set whether screen should track mouse events.
4435 @node At, Break, , Miscellaneous
4437 @deffn Command at [identifier][#|*|%] command [args]
4439 Execute a command at other displays or windows as if it had been entered there.
4440 @code{At} changes the context (the `current window' or `current display'
4441 setting) of the command. If the first parameter describes a non-unique context,
4442 the command will be executed multiple times. If the first parameter is of the
4443 form @samp{@var{identifier}*} then identifier is matched against user names.
4444 The command is executed once for each display of the selected user(s).
4445 If the first parameter is of the form @samp{@var{identifier}%} identifier is
4446 matched against displays. Displays are named after the ttys they attach. The
4447 prefix @samp{/dev/} or @samp{/dev/tty} may be omitted from the identifier.
4448 If @var{identifier} has a @code{#} or nothing appended it is matched against
4449 window numbers and titles. Omitting an identifier in front of the @code{#},
4450 @code{*} or @code{%} character selects all users, displays or windows because
4451 a prefix-match is performed. Note that on the affected display(s) a short
4452 message will describe what happened.
4453 Note that the @code{#} character works as a comment introducer when it is
4454 preceded by whitespace. This can be escaped by prefixing @code{#} with a
4456 Permission is checked for the initiator of the @code{at} command, not for the
4457 owners of the affected display(s).
4459 When matching against windows, the command is executed at least
4460 once per window. Commands that change the internal arrangement of windows
4461 (like @code{other}) may be called again. In shared windows the command will
4462 be repeated for each attached display. Beware, when issuing toggle commands
4464 Some commands (e.g. @code{\*Qprocess}) require
4465 that a display is associated with the target windows. These commands may not
4466 work correctly under @code{at} looping over windows.
4469 @node Break, Debug, At, Miscellaneous
4473 @deffn Command break [duration]
4474 (@kbd{C-a b}, @kbd{C-a C-b})@*
4475 Send a break signal for @var{duration}*0.25 seconds to this window.
4476 For non-Posix systems the time interval is rounded up to full seconds.
4477 Most useful if a character device is attached to the window rather than
4478 a shell process (@pxref{Window Types}). The maximum duration of
4479 a break signal is limited to 15 seconds.
4483 @deffn Command pow_break
4485 Reopen the window's terminal line and send a break condition.
4488 @deffn Command breaktype [tcsendbreak|TIOCSBRK|TCSBRK]
4490 Choose one of the available methods of generating a break signal for
4491 terminal devices. This command should affect the current window only.
4492 But it still behaves identical to @code{defbreaktype}. This will be changed in
4494 Calling @code{breaktype} with no parameter displays the break setting for the
4498 @deffn Command defbreaktype [tcsendbreak|TIOCSBRK|TCSBRK]
4500 Choose one of the available methods of generating a break signal for
4501 terminal devices opened afterwards. The preferred methods are
4502 @code{tcsendbreak} and
4503 @code{TIOCSBRK}. The third, @code{TCSBRK}, blocks the complete @code{screen}
4504 session for the duration of the break, but it may be the only way to
4505 generate long breaks. @code{tcsendbreak} and @code{TIOCSBRK} may or may not
4506 produce long breaks with spikes (e.g. 4 per second). This is not only system
4507 dependent, this also differs between serial board drivers.
4508 Calling @code{defbreaktype} with no parameter displays the current setting.
4511 @node Debug, License, Break, Miscellaneous
4513 @deffn Command debug [on|off]
4515 Turns runtime debugging on or off. If @code{screen} has been compiled with
4516 option @code{-DDEBUG} debugging is available and is turned on per default.
4517 Note that this command only affects debugging output from the main
4518 @samp{SCREEN} process correctly. Debug output from attacher processes can only
4519 be turned off once and forever.
4522 @node License, Nethack, Debug, Miscellaneous
4525 @deffn Command license
4527 Display the disclaimer page. This is done whenever @code{screen} is
4528 started without options, which should be often enough.
4531 @node Nethack, Nonblock, License, Miscellaneous
4533 @deffn Command nethack state
4535 Changes the kind of error messages used by @code{screen}. When you are
4536 familiar with the game @code{nethack}, you may enjoy the nethack-style
4537 messages which will often blur the facts a little, but are much funnier
4538 to read. Anyway, standard messages often tend to be unclear as well.
4540 This option is only available if @code{screen} was compiled with the
4541 NETHACK flag defined (@pxref{Installation}). The default setting is then
4542 determined by the presence of the environment variable
4543 @code{$NETHACKOPTIONS}.
4546 @node Nonblock, Number, Nethack, Miscellaneous
4548 @deffn Command nonblock [@var{state}|@var{numsecs}]
4549 Tell screen how to deal with user interfaces (displays) that cease to
4550 accept output. This can happen if a user presses ^S or a TCP/modem
4551 connection gets cut but no hangup is received. If nonblock is
4552 @code{off} (this is the default) screen waits until the display
4553 restarts to accept the output. If nonblock is @code{on}, screen
4554 waits until the timeout is reached (@code{on} is treated as 1s). If the
4555 display still doesn't receive characters, screen will consider
4556 it ``blocked'' and stop sending characters to it. If at
4557 some time it restarts to accept characters, screen will unblock
4558 the display and redisplay the updated window contents.
4561 @deffn Command defnonblock @var{state}|@var{numsecs}
4562 Same as the @code{nonblock} command except that the default setting for
4563 displays is changed. Initial setting is @code{off}.
4566 @node Number, Silence, Nonblock, Miscellaneous
4569 @deffn Command number [[+|-]@var{n}]
4571 Change the current window's number. If the given number @var{n} is already
4572 used by another window, both windows exchange their numbers. If no argument is
4573 specified, the current window number (and title) is shown. Using either a
4574 plus (`+') or minus (`-') will change the window's number by the relative
4578 @node Silence, Time, Number, Miscellaneous
4581 @deffn Command silence [@var{state}|@var{sec}]
4583 Toggles silence monitoring of windows. When silence is turned on and an
4584 affected window is switched into the background, you will receive the
4585 silence notification message in the status line after a specified period
4586 of inactivity (silence). The default timeout can be changed with the
4587 @code{silencewait} command or by specifying a number of seconds instead of
4588 @code{on} or @code{off}. Silence is initially off for all windows.
4591 @deffn Command defsilence state
4593 Same as the @code{silence} command except that the default setting for
4594 new windows is changed. Initial setting is `off'.
4597 @deffn Command silencewait @var{seconds}
4599 Define the time that all windows monitored for silence should wait
4600 before displaying a message. Default is 30 seconds.
4603 @node Time, Verbose, Silence, Miscellaneous
4607 @deffn Command time [@var{string}]
4608 (@kbd{C-a t}, @kbd{C-a C-t})@*
4609 Uses the message line to display the time of day, the host name, and the
4610 load averages over 1, 5, and 15 minutes (if this is available on your
4611 system). For window-specific information use @code{info} (@pxref{Info}).
4612 If a @var{string} is specified, it changes the format of the time report
4613 like it is described in the string escapes chapter (@pxref{String Escapes}). Screen uses a default of @samp{%c:%s %M %d %H%? %l%?}.
4616 @node Verbose, Version, Time, Miscellaneous
4618 @deffn Command verbose [on|off]
4619 If verbose is switched on, the command name is echoed, whenever a window
4620 is created (or resurrected from zombie state). Default is off.
4621 Without parameter, the current setting is shown.
4624 @node Version, Zombie, Verbose, Miscellaneous
4627 @deffn Command version
4629 Display the version and modification date in the message line.
4632 @node Zombie, Printcmd, Version, Miscellaneous
4634 @deffn Command zombie [@var{keys} [onerror] ]
4635 @deffnx Command defzombie [@var{keys}]
4637 Per default windows are removed from the window list as soon as the
4638 windows process (e.g. shell) exits. When a string of two keys is
4639 specified to the zombie command, `dead' windows will remain in the list.
4640 The @code{kill} command may be used to remove the window. Pressing the first key
4641 in the dead window has the same effect. Pressing the second key, however,
4642 screen will attempt to resurrect the window. The process that was initially
4643 running in the window will be launched again. Calling @code{zombie} without
4644 parameters will clear the zombie setting, thus making windows disappear when
4645 the process terminates.
4647 As the zombie setting is affected globally for all windows, this command
4648 should only be called @code{defzombie}. Until we need this as a per window
4649 setting, the commands @code{zombie} and @code{defzombie} are synonymous.
4651 Optionally you can put the word @code{onerror} after the keys. This will
4652 cause screen to monitor exit status of the process running in the window.
4653 If it exits normally ('0'), the window disappears. Any other exit value
4654 causes the window to become a zombie.
4657 @node Printcmd, Rendition, Zombie, Miscellaneous
4659 @deffn Command printcmd [@var{cmd}]
4661 If @var{cmd} is not an empty string, screen will not use the terminal
4662 capabilities @code{po/pf} for printing if it detects an ansi print
4663 sequence @code{ESC [ 5 i}, but pipe the output into @var{cmd}.
4664 This should normally be a command like @samp{lpr} or
4665 @samp{cat > /tmp/scrprint}.
4666 @code{Printcmd} without an argument displays the current setting.
4667 The ansi sequence @code{ESC \} ends printing and closes the pipe.
4669 Warning: Be careful with this command! If other user have write
4670 access to your terminal, they will be able to fire off print commands.
4673 @node Rendition, Sorendition, Printcmd, Miscellaneous
4675 @deffn Command rendition bell | monitor | so @var{attr} [@var{color}]
4677 Change the way screen renders the titles of windows that have monitor
4678 or bell flags set in caption or hardstatus or windowlist.
4680 about string escapes (@pxref{String Escapes}) for the syntax of
4681 the modifiers. The default for monitor is currently @samp{=b} (bold,
4682 active colors), and for bell is @samp{=ub} (underline, bold and
4686 @node Sorendition, Attrcolor, Rendition, Miscellaneous
4687 @section Sorendition
4688 @deffn Command sorendition [@var{attr} [@var{color}]]
4690 This command has been deprecated. Use @code{rendition so} instead.
4693 @node Attrcolor, Setsid, Sorendition, Miscellaneous
4695 @deffn Command attrcolor @var{attrib} [@var{attribute/color-modifier}]
4697 This command can be used to highlight attributes by changing the color of
4698 the text. If the attribute
4700 is in use, the specified attribute/color modifier is also applied. If no
4701 modifier is given, the current one is deleted. See the chapter
4702 about string escapes (@pxref{String Escapes}) for the syntax of
4703 the modifier. Screen understands two pseudo-attributes, @code{i}
4704 stands for high-intensity foreground color and @code{I} for
4705 high-intensity background color.
4710 @item attrcolor b "R"
4711 Change the color to bright red if bold text is to be printed.
4712 @item attrcolor u "-u b"
4713 Use blue text instead of underline.
4714 @item attrcolor b ".I"
4715 Use bright colors for bold text. Most terminal emulators do this
4717 @item attrcolor i "+b"
4718 Make bright colored text also bold.
4722 @node Setsid, Eval, Attrcolor, Miscellaneous
4724 @deffn Command setsid state
4726 Normally screen uses different sessions and process groups for
4727 the windows. If setsid is turned @code{off}, this is not done
4728 anymore and all windows will be in the same process group as the
4729 screen backend process. This also breaks job-control, so be careful.
4730 The default is @code{on}, of course. This command is probably useful
4731 only in rare circumstances.
4734 @node Eval, Maxwin, Setsid, Miscellaneous
4736 @deffn Command eval @var{command1} [@var{command2} ...]
4738 Parses and executes each argument as separate command.
4741 @node Maxwin, Backtick, Eval, Miscellaneous
4743 @deffn Command maxwin @var{n}
4745 Set the maximum window number screen will create. Doesn't affect
4746 already existing windows. The number may only be decreased.
4749 @node Backtick, Screen Saver, Maxwin, Miscellaneous
4751 @deffn Command backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}]
4752 @deffnx Command backtick @var{id}
4754 Program the backtick command with the numerical id @var{id}.
4755 The output of such a command is used for substitution of the
4756 @code{%`} string escape (@pxref{String Escapes}).
4757 The specified @var{lifespan} is the number
4758 of seconds the output is considered valid. After this time, the
4759 command is run again if a corresponding string escape is encountered.
4760 The @var{autorefresh} parameter triggers an
4761 automatic refresh for caption and hardstatus strings after the
4762 specified number of seconds. Only the last line of output is used
4765 If both the @var{lifespan} and the @var{autorefresh} parameters
4766 are zero, the backtick program is expected to stay in the
4767 background and generate output once in a while.
4768 In this case, the command is executed right away and screen stores
4769 the last line of output. If a new line gets printed screen will
4770 automatically refresh the hardstatus or the captions.
4772 The second form of the command deletes the backtick command
4773 with the numerical id @var{id}.
4776 @node Screen Saver, Zmodem, Backtick, Miscellaneous
4777 @section Screen Saver
4778 @deffn Command idle [@var{timeout} [@var{cmd} @var{args}]]
4780 Sets a command that is run after the specified number of
4781 seconds inactivity is reached. This command will normally
4782 be the @code{blanker} command to create a screen blanker, but
4783 it can be any screen command. If no command is specified,
4784 only the timeout is set. A timeout of zero (ot the special
4785 timeout @code{off}) disables the timer. If no arguments are
4786 given, the current settings are displayed.
4789 @deffn Command blanker
4791 Activate the screen blanker. First the screen is cleared.
4792 If no blanker program is defined, the cursor is turned
4793 off, otherwise, the program is started and it's output is
4794 written to the screen. The screen blanker is killed with
4795 the first keypress, the read key is discarded.
4797 This command is normally used together with the @code{idle}
4801 @deffn Command blankerprg [@var{program args}]
4802 Defines a blanker program. Disables the blanker program if
4803 no arguments are given.
4806 @node Zmodem, , Screen Saver, Miscellaneous
4808 @deffn Command zmodem [off|auto|catch|pass]
4809 @deffnx Command zmodem sendcmd [string]
4810 @deffnx Command zmodem recvcmd [string]
4812 Define zmodem support for screen. Screen understands two
4813 different modes when it detects a zmodem request: @code{pass}
4814 and @code{catch}. If the mode is set to @code{pass}, screen will
4815 relay all data to the attacher until the end of the
4816 transmission is reached. In @code{catch} mode screen acts as a
4817 zmodem endpoint and starts the corresponding rz/sz commands.
4818 If the mode is set to @code{auto}, screen will use @code{catch} if
4819 the window is a tty (e.g. a serial line), otherwise it
4820 will use @code{pass}.
4822 You can define the templates screen uses in @code{catch} mode
4823 via the second and the third form.
4825 Note also that this is an experimental feature.
4828 @node String Escapes, Environment, Miscellaneous, Top
4829 @chapter String Escapes
4830 @cindex string escapes
4831 Screen provides an escape mechanism to insert information like the
4832 current time into messages or file names. The escape character
4833 is @code{%} with one exception: inside of a window's hardstatus
4834 @code{^%} (@code{^E}) is used instead.
4836 Here is the full list of supported escapes:
4840 the escape character itself
4842 either @code{am} or @code{pm}
4844 either @code{AM} or @code{PM}
4846 current time @code{HH:MM} in 24h format
4848 current time @code{HH:MM} in 12h format
4856 sets %? to true if the window has the focus
4858 hardstatus of the window
4860 hostname of the system
4862 current load of the system
4876 all other users on this window
4878 all window numbers and names. With @code{-} qualifier: up to the current
4879 window; with @code{+} qualifier: starting with the window after the current
4882 all window numbers and names except the current one
4884 last two digits of the year number
4888 the part to the next @code{%?} is displayed only if a @code{%} escape
4889 inside the part expands to a non-empty string
4891 else part of @code{%?}
4893 pad the string to the display's width (like TeX's hfill). If a
4894 number is specified, pad to the percentage of the window's width.
4895 A @code{0} qualifier tells screen to treat the number as absolute position.
4896 You can specify to pad relative to the last absolute pad position
4897 by adding a @code{+} qualifier or to pad relative to the right margin
4898 by using @code{-}. The padding truncates the string if the specified
4899 position lies before the current position. Add the @code{L} qualifier
4902 same as @code{%=} but just do truncation, do not fill with spaces
4904 mark the current text position for the next truncation. When
4905 screen needs to do truncation, it tries to do it in a way that
4906 the marked position gets moved to the specified percentage of
4907 the output area. (The area starts from the last absolute pad
4908 position and ends with the position specified by the truncation
4909 operator.) The @code{L} qualifier tells screen to mark the truncated
4910 parts with @samp{...}.
4912 attribute/color modifier string terminated by the next @code{@}}
4914 Substitute with the output of a `backtick' command. The length
4915 qualifier is misused to identify one of the commands. @xref{Backtick}.
4917 The @code{c} and @code{C} escape may be qualified with a @code{0} to
4919 zero instead of space as fill character.
4921 @code{=} escapes understand
4922 a length qualifier (e.g. @code{%3n}), @code{D} and @code{M} can be
4923 prefixed with @code{L} to generate long names, @code{w} and
4924 @code{W} also show the window flags if @code{L} is given.
4926 An attribute/color modifier is is used to change the attributes or the
4927 color settings. Its format
4928 is @samp{[attribute modifier] [color description]}. The attribute modifier
4929 must be prefixed by a change type indicator if it can be confused with
4930 a color description. The following change types are known:
4933 add the specified set to the current attributes
4935 remove the set from the current attributes
4937 invert the set in the current attributes
4939 change the current attributes to the specified set
4941 The attribute set can either be specified as a hexadecimal number or
4942 a combination of the following letters:
4957 Colors are coded either as a hexadecimal number or two letters specifying
4958 the desired background and foreground color (in that order). The following
4980 leave color unchanged
4982 The capitalized versions of the letter specify bright colors. You can also
4983 use the pseudo-color @samp{i} to set just the brightness and leave the color
4986 A one digit/letter color description is treated as foreground or
4987 background color dependent on the current attributes: if reverse mode is
4988 set, the background color is changed instead of the foreground color.
4989 If you don't like this, prefix the color with a @samp{.}. If you want
4990 the same behavior for two-letter color descriptions, also prefix them
4993 As a special case, @samp{%@{-@}} restores the attributes and colors that
4994 were set before the last change was made (i.e. pops one level of the
4995 color-change stack).
5001 set color to bright green
5005 clear all attributes, write in default color on yellow background.
5006 @item %-Lw%@{= BW@}%50>%n%f* %t%@{-@}%+Lw%<
5007 The available windows centered at the current win dow and truncated to
5008 the available width. The current window is displayed white on blue.
5009 This can be used with @samp{hardstatus alwayslastline}.
5010 @item %?%F%@{.R.@}%?%3n %t%? [%h]%?
5011 The window number and title and the window's hardstatus, if one is set.
5012 Also use a red background if this is the active focus.
5013 Useful for @samp{caption string}.
5017 @node Environment, Files, String Escapes, Top
5018 @chapter Environment Variables
5023 Number of columns on the terminal (overrides termcap entry).
5026 Directory in which to look for .screenrc.
5029 Number of lines on the terminal (overrides termcap entry).
5032 Screen lock program.
5034 @item NETHACKOPTIONS
5035 Turns on @code{nethack} option.
5038 Used for locating programs to run.
5041 For customizing a terminal's @code{TERMCAP} value.
5044 Alternate socket directory.
5047 Alternate user screenrc file.
5050 Default shell program for opening windows (default @file{/bin/sh}).
5053 Alternate socket name. If @code{screen} is invoked, and the environment variable
5054 @code{STY} is set, then it creates only a window in the running @code{screen}
5055 session rather than starting a new session.
5058 Alternate system screenrc file.
5064 Terminal description.
5067 Window number of a window (at creation time).
5070 @node Files, Credits, Environment, Top
5071 @chapter Files Referenced
5075 @item .../screen-4.?.??/etc/screenrc
5076 @itemx .../screen-4.?.??/etc/etcscreenrc
5077 Examples in the @code{screen} distribution package for private and
5078 global initialization files.
5080 @item @code{$SYSSCREENRC}
5081 @itemx /local/etc/screenrc
5082 @code{screen} initialization commands
5084 @item @code{$SCREENRC}
5085 @itemx @code{$HOME}/.iscreenrc
5086 @itemx @code{$HOME}/.screenrc
5087 Read in after /local/etc/screenrc
5089 @item @code{$SCREENDIR}/S-@var{login}
5091 @item /local/screens/S-@var{login}
5092 Socket directories (default)
5094 @item /usr/tmp/screens/S-@var{login}
5095 Alternate socket directories.
5097 @item @var{socket directory}/.termcap
5098 Written by the @code{dumptermcap} command
5100 @item /usr/tmp/screens/screen-exchange or
5101 @itemx /tmp/screen-exchange
5102 @code{screen} interprocess communication buffer
5104 @item hardcopy.[0-9]
5105 Screen images created by the hardcopy command
5107 @item screenlog.[0-9]
5108 Output log files created by the log command
5110 @item /usr/lib/terminfo/?/* or
5112 Terminal capability databases
5117 @item @code{$LOCKPRG}
5118 Program for locking the terminal.
5121 @node Credits, Bugs, Files, Top
5128 Originally created by Oliver Laumann, this latest version was
5129 produced by Wayne Davison, Juergen Weigert and Michael Schroeder.
5136 Ken Beal (kbeal@@amber.ssd.csd.harris.com),
5137 Rudolf Koenig (rfkoenig@@informatik.uni-erlangen.de),
5138 Toerless Eckert (eckert@@informatik.uni-erlangen.de),
5139 Wayne Davison (davison@@borland.com),
5140 Patrick Wolfe (pat@@kai.com, kailand!pat),
5141 Bart Schaefer (schaefer@@cse.ogi.edu),
5142 Nathan Glasser (nathan@@brokaw.lcs.mit.edu),
5143 Larry W. Virden (lvirden@@cas.org),
5144 Howard Chu (hyc@@hanauma.jpl.nasa.gov),
5145 Tim MacKenzie (tym@@dibbler.cs.monash.edu.au),
5146 Markku Jarvinen (mta@@@{cc,cs,ee@}.tut.fi),
5147 Marc Boucher (marc@@CAM.ORG),
5148 Doug Siebert (dsiebert@@isca.uiowa.edu),
5149 Ken Stillson (stillson@@tsfsrv.mitre.org),
5150 Ian Frechett (frechett@@spot.Colorado.EDU),
5151 Brian Koehmstedt (bpk@@gnu.ai.mit.edu),
5152 Don Smith (djs6015@@ultb.isc.rit.edu),
5153 Frank van der Linden (vdlinden@@fwi.uva.nl),
5154 Martin Schweikert (schweik@@cpp.ob.open.de),
5155 David Vrona (dave@@sashimi.lcu.com),
5156 E. Tye McQueen (tye%spillman.UUCP@@uunet.uu.net),
5157 Matthew Green (mrg@@eterna.com.au),
5158 Christopher Williams (cgw@@pobox.com),
5159 Matt Mosley (mattm@@access.digex.net),
5160 Gregory Neil Shapiro (gshapiro@@wpi.WPI.EDU),
5161 Jason Merrill (jason@@jarthur.Claremont.EDU),
5162 Johannes Zellner (johannes@@zellner.org),
5163 Pablo Averbuj (pablo@@averbuj.com).
5170 This manual describes version @value{version} of the @code{screen}
5171 program. Its roots are a merge of a custom version 2.3PR7 by Wayne
5172 Davison and several enhancements to Oliver Laumann's version 2.0.
5173 Note that all versions numbered 2.x are copyright by Oliver Laumann.
5175 See also @xref{Availability}.
5177 @node Bugs, Installation, Credits, Top
5181 Just like any other significant piece of software, @code{screen} has a
5182 few bugs and missing features. Please send in a bug report if you have
5183 found a bug not mentioned here.
5186 * Known Bugs:: Problems we know about.
5187 * Reporting Bugs:: How to contact the maintainers.
5188 * Availability:: Where to find the latest screen version.
5191 @node Known Bugs, Reporting Bugs, , Bugs
5196 @samp{dm} (delete mode) and @samp{xs} are not handled correctly (they
5197 are ignored). @samp{xn} is treated as a magic-margin indicator.
5200 @code{screen} has no clue about double-high or double-wide characters.
5201 But this is the only area where @code{vttest} is allowed to fail.
5204 It is not possible to change the environment variable @code{$TERMCAP}
5205 when reattaching under a different terminal type.
5208 The support of terminfo based systems is very limited. Adding extra
5209 capabilities to @code{$TERMCAP} may not have any effects.
5212 @code{screen} does not make use of hardware tabs.
5215 @code{screen} must be installed setuid root on most systems
5216 in order to be able to
5217 correctly change the owner of the tty device file for each window.
5218 Special permission may also be required to write the file
5222 Entries in @file{/etc/utmp} are not removed when @code{screen} is killed
5223 with SIGKILL. This will cause some programs (like "w" or "rwho") to
5224 advertise that a user is logged on who really isn't.
5227 @code{screen} may give a strange warning when your tty has no utmp
5231 When the modem line was hung up, @code{screen} may not automatically detach
5232 (or quit) unless the device driver sends a HANGUP signal. To detach such a
5233 @code{screen} session use the -D or -d command line option.
5236 If a password is set, the command line options -d and -D still detach a
5237 session without asking.
5240 Both @code{breaktype} and @code{defbreaktype} change the break generating
5241 method used by all terminal devices. The first should change a window
5242 specific setting, where the latter should change only the default for new
5246 When attaching to a multiuser session, the user's @file{.screenrc} file is not
5247 sourced. Each users personal settings have to be included in the
5248 @file{.screenrc} file from which the session is booted, or have to be
5252 A weird imagination is most useful to gain full advantage of all the
5256 @node Reporting Bugs, Availability, Known Bugs, Bugs
5257 @section Reporting Bugs
5260 If you find a bug in @code{Screen}, please send electronic mail to
5261 @w{@samp{screen@@uni-erlangen.de}}, and also to
5262 @w{@samp{bug-gnu-utils@@prep.ai.mit.edu}}. Include the version number
5263 of @code{Screen} which you are using. Also include in your message the
5264 hardware and operating system, the compiler used to compile, a
5265 description of the bug behavior, and the conditions that triggered the
5266 bug. Please recompile @code{screen} with the @samp{-DDEBUG} options
5267 enabled, reproduce the bug, and have a look at the debug output written to
5268 the directory @file{/tmp/debug}. If necessary quote suspect passages from the
5269 debug output and show the contents of your @file{config.h} if it matters.
5271 @node Availability, , Reporting Bugs, Bugs
5272 @section Availability
5273 @cindex availability
5275 @code{Screen} is available under the @code{GNU} copyleft.
5277 The latest official release of @code{screen} available via anonymous
5278 ftp from @samp{prep.ai.mit.edu}, @samp{nic.funet.fi} or any other
5279 @code{GNU} distribution site. The home site of
5280 @code{screen} is @samp{ftp.uni-erlangen.de
5281 (131.188.3.71)}, in the directory @file{pub/utilities/screen}.
5282 The subdirectory @samp{private} contains the latest beta testing release.
5283 If you want to help, send a note to screen@@uni-erlangen.de.
5285 @node Installation, Concept Index, Bugs, Top
5286 @chapter Installation
5287 @cindex installation
5289 Since @code{screen} uses pseudo-ttys, the select system call, and
5290 UNIX-domain sockets/named pipes, it will not run under a system that
5291 does not include these features of 4.2 and 4.3 BSD UNIX.
5294 * Socket Directory:: Where screen stores its handle.
5295 * Compiling Screen::
5298 @node Socket Directory,
5299 @section Socket Directory
5300 @cindex socket directory
5302 The socket directory defaults either to @file{$HOME/.screen} or simply to
5303 @file{/tmp/screens} or preferably to @file{/usr/local/screens} chosen at
5304 compile-time. If @code{screen} is installed
5305 setuid root, then the administrator should compile screen with an
5306 adequate (not NFS mounted) @code{SOCKDIR}. If @code{screen} is not
5307 running setuid-root, the user can specify any mode 700 directory in the
5308 environment variable @code{$SCREENDIR}.
5310 @node Compiling Screen, , Socket Directory, Installation
5311 @section Compiling Screen
5312 @cindex compiling screen
5314 To compile and install screen:
5316 The @code{screen} package comes with a @code{GNU Autoconf} configuration
5317 script. Before you compile the package run
5319 @center @code{sh ./configure}
5321 This will create a @file{config.h} and @file{Makefile} for your machine.
5322 If @code{configure} fails for some reason, then look at the examples and
5323 comments found in the @file{Makefile.in} and @file{config.h.in} templates.
5324 Rename @file{config.status} to @file{config.status.@var{machine}} when
5325 you want to keep configuration data for multiple architectures. Running
5326 @code{sh ./config.status.@var{machine}} recreates your configuration
5327 significantly faster than rerunning @code{configure}.
5329 Read through the "User Configuration" section of @file{config.h}, and verify
5330 that it suits your needs.
5331 A comment near the top of this section explains why it's best to
5332 install screen setuid to root.
5333 Check for the place for the global @file{screenrc}-file and for the socket
5336 Check the compiler used in @file{Makefile}, the prefix path where to install
5337 @code{screen}. Then run
5341 If @code{make} fails to produce one of the files @file{term.h}, @file{comm.h}
5342 or @file{tty.c}, then use @code{@var{filename.x}.dist} instead.
5343 For additional information about installation of @code{screen} refer to the
5344 file @file{INSTALLATION}, coming with this package.
5346 @node Concept Index, Command Index, Installation, Top
5347 @unnumbered Concept Index
5351 @node Command Index, Keystroke Index, Concept Index, Top
5352 @unnumbered Command Index
5354 This is a list of all the commands supported by @code{screen}.
5358 @node Keystroke Index, , Command Index, Top
5359 @unnumbered Keystroke Index
5361 This is a list of the default key bindings.
5363 The leading escape character (@pxref{Command Character}) has been omitted
5364 from the key sequences, since it is the same for all bindings.