1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@c vi:set wm=5 4@setfilename screen.info 5@settitle Screen User's Manual 6@dircategory General Commands 7@finalout 8@setchapternewpage odd 9@c %**end of header 10@set version 4.0.2 11 12@direntry 13* Screen: (screen). Full-screen window manager. 14@end direntry 15 16@c For examples, use a literal escape in info. 17@ifinfo 18@set esc 19@end ifinfo 20@iftex 21@set esc <ESC> 22@end iftex 23 24@ifinfo 25This file documents the @code{Screen} virtual terminal manager. 26 27Copyright (c) 1993-2003 Free Software Foundation, Inc. 28 29Permission is granted to make and distribute verbatim copies of 30this manual provided the copyright notice and this permission notice 31are preserved on all copies. 32 33@ignore 34Permission is granted to process this file through TeX and print the 35results, provided the printed document carries copying permission 36notice identical to this one except for the removal of this paragraph 37(this paragraph not being relevant to the printed manual). 38 39@end ignore 40Permission is granted to copy and distribute modified versions of this 41manual under the conditions for verbatim copying, provided that the entire 42resulting derived work is distributed under the terms of a permission 43notice identical to this one. 44 45Permission is granted to copy and distribute translations of this manual 46into another language, under the above conditions for modified versions, 47except that this permission notice may be stated in a translation approved 48by the Foundation. 49@end ifinfo 50 51@titlepage 52@title Screen 53@subtitle The virtual terminal manager 54@subtitle for Version @value{version} 55@subtitle Aug 2003 56 57@page 58@vskip 0pt plus 1filll 59Copyright @copyright{} 1993-2003 Free Software Foundation, Inc. 60 61Permission is granted to make and distribute verbatim copies of 62this manual provided the copyright notice and this permission notice 63are preserved on all copies. 64 65Permission is granted to copy and distribute modified versions of this 66manual under the conditions for verbatim copying, provided that the entire 67resulting derived work is distributed under the terms of a permission 68notice identical to this one. 69 70Permission is granted to copy and distribute translations of this manual 71into another language, under the above conditions for modified versions, 72except that this permission notice may be stated in a translation approved 73by the Foundation. 74@end titlepage 75 76@node Top, Overview, (dir), (dir) 77 78@ifinfo 79@top Screen 80This file documents the @code{Screen} virtual terminal manager, version 81@value{version}. 82@end ifinfo 83 84@menu 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. 114@end menu 115 116@node Overview, Getting Started, Top, Top 117@chapter Overview 118@cindex overview 119 120Screen is a full-screen window manager that multiplexes a physical 121terminal between several processes, typically interactive shells. Each 122virtual terminal provides the functions of the DEC VT100 terminal and, 123in addition, several control functions from the ISO 6429 (ECMA 48, ANSI X3.64) 124and ISO 2022 standards (e.g. insert/delete line and support for multiple 125character sets). There is a scrollback history buffer for each virtual 126terminal and a copy-and-paste mechanism that allows the user to move 127text regions between windows. 128 129When @code{screen} is called, it creates a single window with a shell in 130it (or the specified command) and then gets out of your way so that you 131can use the program as you normally would. Then, at any time, you can 132create new (full-screen) windows with other programs in them (including 133more shells), kill the current window, view a list of the active 134windows, turn output logging on and off, copy text between windows, view 135the scrollback history, switch between windows, etc. All windows run 136their programs completely independent of each other. Programs continue 137to run when their window is currently not visible and even when the 138whole screen session is detached from the user's terminal. 139 140When a program terminates, @code{screen} (per default) kills the window 141that contained it. If this window was in the foreground, the display 142switches to the previously displayed window; if none are left, 143@code{screen} exits. 144 145Everything you type is sent to the program running in the current 146window. The only exception to this is the one keystroke that is used to 147initiate a command to the window manager. By default, each command 148begins with a control-a (abbreviated @kbd{C-a} from now on), and is 149followed by one other keystroke. The command character (@pxref{Command 150Character}) and all the key bindings (@pxref{Key Binding}) can be fully 151customized to be anything you like, though they are always two 152characters in length. 153 154@code{Screen} does not understand the prefix @kbd{C-} to mean control. 155Please use the caret notation (@kbd{^A} instead of @kbd{C-a}) as arguments 156to e.g. the @code{escape} command or the @code{-e} option. @code{Screen} 157will also print out control characters in caret notation. 158 159The standard way to create a new window is to type @kbd{C-a c}. This 160creates a new window running a shell and switches to that window 161immediately, regardless of the state of the process running in the 162current window. Similarly, you can create a new window with a custom 163command 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 165just like the @kbd{C-a c} command. In addition, new windows can be created by 166running a command like: 167 168@example 169screen emacs prog.c 170@end example 171 172@noindent 173from a shell prompt within a previously created window. This will not 174run another copy of @code{screen}, but will instead supply the command 175name and its arguments to the window manager (specified in the $STY environment 176variable) who will use it to create the new window. The above example would 177start the @code{emacs} editor (editing @file{prog.c}) and switch to its window. 178 179If @file{/etc/utmp} is writable by @code{screen}, an appropriate record 180will be written to this file for each window, and removed when the 181window is closed. This is useful for working with @code{talk}, 182@code{script}, @code{shutdown}, @code{rsend}, @code{sccs} and other 183similar programs that use the utmp file to determine who you are. As 184long as @code{screen} is active on your terminal, the terminal's own 185record is removed from the utmp file. @xref{Login}. 186 187@node Getting Started, Invoking Screen, Overview, Top 188@chapter Getting Started 189@cindex introduction 190 191Before you begin to use @code{screen} you'll need to make sure you have 192correctly selected your terminal type, just as you would for any other 193termcap/terminfo program. (You can do this by using @code{tset}, 194@code{qterm}, or just @code{set term=mytermtype}, for example.) 195 196If you're impatient and want to get started without doing a lot more 197reading, you should remember this one command: @kbd{C-a ?} (@pxref{Key 198Binding}). Typing these two characters will display a list of the 199available @code{screen} commands and their bindings. Each keystroke is 200discussed in the section on keystrokes (@pxref{Default Key Bindings}). 201Another section (@pxref{Customization}) deals with the contents of your 202@file{.screenrc}. 203 204If your terminal is a ``true'' auto-margin terminal (it doesn't allow 205the last position on the screen to be updated without scrolling the 206screen) consider using a version of your terminal's termcap that has 207automatic margins turned @emph{off}. This will ensure an accurate 208and optimal update of the screen in all circumstances. Most terminals 209nowadays have ``magic'' margins (automatic margins plus usable last 210column). This is the VT100 style type and perfectly suited for 211@code{screen}. 212If all you've got is a ``true'' auto-margin terminal @code{screen} 213will be content to use it, but updating a character put into the last 214position on the screen may not be possible until the screen scrolls or 215the character is moved into a safe position in some other way. This 216delay can be shortened by using a terminal with insert-character 217capability. 218 219@xref{Special Capabilities}, for more information about telling 220@code{screen} what kind of terminal you have. 221 222@node Invoking Screen, Customization, Getting Started, Top 223@chapter Invoking @code{Screen} 224@cindex invoking 225@cindex options 226@cindex command line options 227 228Screen has the following command-line options: 229 230@table @samp 231@item -a 232Include @emph{all} capabilities (with some minor exceptions) in each 233window's termcap, even if @code{screen} must redraw parts of the display 234in order to implement a function. 235 236@item -A 237Adapt 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 239resizable terminals (those with @samp{WS} in their descriptions, e.g. 240@code{suncmd} or some varieties of @code{xterm}). 241 242@item -c @var{file} 243Use @var{file} as the user's configuration file instead of the default 244of @file{$HOME/.screenrc}. 245 246@item -d [@var{pid.sessionname}] 247@itemx -D [@var{pid.sessionname}] 248Do not start @code{screen}, but instead detach a @code{screen} session 249running elsewhere (@pxref{Detach}). @samp{-d} has the same effect as 250typing @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 252be detached, this option is ignored. In combination with the 253@code{-r}/@code{-R} option more powerful effects can be achieved: 254 255@table @code 256@item -d -r 257Reattach a session and if necessary detach it first. 258@item -d -R 259Reattach a session and if necessary detach or even create it first. 260@item -d -RR 261Reattach a session and if necessary detach or create it. 262Use the first session if more than one session is available. 263@item -D -r 264Reattach a session. If necessary detach and logout remotely first. 265@item -D -R 266Attach here and now. In detail this means: If a session is running, 267then reattach. If necessary detach and logout remotely first. If it 268was not running create it and notify the user. 269This is the author's favorite. 270@item -D -RR 271Attach here and now. Whatever that means, just do it. 272@end table 273 274@emph{Note}: It is a good idea to check the status of your sessions 275with @code{screen -list} before using this option. 276 277@item -e @var{xy} 278Set the command character to @var{x}, and the character generating a 279literal 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 281as @samp{-e^Aa}. When creating a @code{screen} session, this option 282sets the default command character. In a multiuser session all users 283added will start off with this command character. But when attaching 284to an already running session, this option only changes the command 285character of the attaching user. 286This option is equivalent to the commands @code{defescape} or 287@code{escape} respectively. (@pxref{Command Character}). 288 289@item -f 290@itemx -fn 291@itemx -fa 292Set flow-control to on, off, or automatic switching mode, respectively. 293This option is equivalent to the @code{defflow} command (@pxref{Flow 294Control}). 295 296@item -h @var{num} 297Set the history scrollback buffer to be @var{num} lines high. 298Equivalent to the @code{defscrollback} command (@pxref{Copy}). 299 300@item -i 301Cause the interrupt key (usually @kbd{C-c}) to interrupt the display 302immediately when flow control is on. This option is equivalent to the 303@code{interrupt} argument to the @code{defflow} command (@pxref{Flow 304Control}). Its use is discouraged. 305 306@item -l 307@itemx -ln 308Turn login mode on or off (for @file{/etc/utmp} updating). This option 309is equivalent to the @code{deflogin} command (@pxref{Login}). 310 311@item -ls [@var{match}] 312@itemx -list [@var{match}] 313Do not start @code{screen}, but instead print a list of session 314identification strings (usually of the form @var{pid.tty.host}; 315@pxref{Session Name}). Sessions marked @samp{detached} can be resumed 316with @code{screen -r}. Those marked @samp{attached} are running and 317have a controlling terminal. If the session runs in multiuser mode, 318it is marked @samp{multi}. Sessions marked as @samp{unreachable} either 319live on a different host or are dead. 320An unreachable session is considered dead, when its name matches either the 321name of the local host, or the specified parameter, if any. 322See the @code{-r} flag for a description how to construct matches. 323Sessions marked as @samp{dead} should be thoroughly checked and removed. 324Ask your system administrator if you are not sure. 325Remove sessions with the @samp{-wipe} option. 326 327@item -L 328Tell @code{screen} to turn on automatic output logging for the 329windows. 330 331@item -m 332Tell @code{screen} to ignore the @code{$STY} environment variable. When 333this option is used, a new session will always be created, regardless of 334whether @code{screen} is being called from within another @code{screen} 335session or not. This flag has a special meaning in connection 336with the @samp{-d} option: 337@table @code 338@item -d -m 339Start @code{screen} in @emph{detached} mode. This creates a new 340session but doesn't attach to it. This is useful for system startup 341scripts. 342@item -D -m 343This also starts @code{screen} in @emph{detached} mode, but doesn't fork 344a new process. The command exits if the session terminates. 345@end table 346 347@item -p @var{name_or_number} 348Preselect a window. This is usefull when you want to reattach to a 349specific windor or you want to send a command via the @samp{-X} 350option to a specific window. As with screen's select commant, @samp{-} 351selects the blank window. As a special case for reattach, @samp{=} 352brings up the windowlist on the blank window. 353 354@item -q 355Suppress printing of error messages. In combination with @samp{-ls} the exit 356value is set as follows: 9 indicates a directory without sessions. 10 357indicates a directory with running but not attachable sessions. 11 (or more) 358indicates 1 (or more) usable sessions. 359In combination with @samp{-r} the exit value is as follows: 10 indicates that 360there is no session to resume. 12 (or more) indicates that there are 2 (or 361more) sessions to resume and you should specify which one to choose. 362In all other cases @samp{-q} has no effect. 363 364@item -r [@var{pid.sessionname}] 365@itemx -r @var{sessionowner}/[@var{pid.sessionname}] 366Resume a detached @code{screen} session. No other options (except 367combinations with @samp{-d} or @samp{-D}) may be specified, though 368the session name 369(@pxref{Session Name}) may be needed to distinguish between multiple 370detached @code{screen} sessions. 371The second form is used to connect to another user's screen session which 372runs in multiuser mode. This indicates that screen should look for 373sessions in another user's directory. This requires setuid-root. 374 375@item -R 376Resume the first appropriate detached @code{screen} session. If 377successful, all other command-line options are ignored. If no detached 378session exists, start a new session using the specified options, just as 379if @samp{-R} had not been specified. This option is set by default if 380screen is run as a login-shell (actually screen uses @samp{-xRR} in 381that case). 382For combinations with the 383@samp{-D}/@samp{-d} option see there. 384 385@item -s @var{program} 386Set the default shell to be @var{program}. By default, @code{screen} 387uses 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}). 390 391@item -S @var{sessionname} 392Set the name of the new session to @var{sessionname}. This option can 393be used to specify a meaningful name for the session in place of the 394default @var{tty.host} suffix. This name identifies the session for the 395@code{screen -list} and @code{screen -r} commands. This option is 396equivalent to the @code{sessionname} command (@pxref{Session Name}). 397 398@item -t @var{name} 399Set the title (name) for the default shell or specified program. 400This option is equivalent to the @code{shelltitle} command 401(@pxref{Shell}). 402 403@item -U 404Run screen in UTF-8 mode. This option tells screen that your terminal 405sends and understands UTF-8 encoded characters. It also sets the default 406encoding for new windows to @samp{utf8}. 407 408@item -v 409Print the version number. 410 411@item -wipe [@var{match}] 412List available screens like @code{screen -ls}, but remove destroyed 413sessions instead of marking them as @samp{dead}. 414An unreachable session is considered dead, when its name matches either 415the name of the local host, or the explicitly given parameter, if any. 416See the @code{-r} flag for a description how to construct matches. 417 418@item -x 419Attach to a session which is already attached elsewhere (multi-display 420mode). 421 422@item -X 423Send the specified command to a running screen session. You can use 424the @code{-d} or @code{-r} option to tell screen to look only for 425attached or detached screen sessions. Note that this command doesn't 426work if the session is password protected. 427 428@end table 429 430@node Customization, Commands, Invoking Screen, Top 431@chapter Customizing @code{Screen} 432@cindex customization 433 434You can modify the default settings for @code{screen} to fit your tastes 435either through a personal @file{.screenrc} file which contains commands 436to be executed at startup, or on the fly using the @code{colon} command. 437 438@menu 439* Startup Files:: The @file{.screenrc} file. 440* Source:: Read commands from a file. 441* Colon:: Entering customization commands interactively. 442@end menu 443 444@node Startup Files, Source, , Customization 445@section The @file{.screenrc} file 446@cindex .screenrc 447@cindex screenrc 448When @code{screen} is invoked, it executes initialization commands from 449the files @file{.screenrc} in the user's home directory and 450@file{/usr/local/etc/screenrc}. These defaults can be overridden in the 451following ways: 452For the global screenrc file @code{screen} searches for the environment 453variable @code{$SYSSCREENRC} (this override feature may be disabled at 454compile-time). The user specific screenrc file is 455searched for in @code{$SCREENRC}, then 456@file{@code{$HOME}/.screenrc}. The command line option @samp{-c} 457specifies which file to use (@pxref{Invoking Screen}. Commands in these 458files are used to set options, bind commands to keys, and to 459automatically establish one or more windows at the beginning of 460your @code{screen} session. Commands are listed one per line, with 461empty lines being ignored. A command's arguments are separated by tabs 462or spaces, and may be surrounded by single or double quotes. A @samp{#} 463turns the rest of the line into a comment, except in quotes. 464Unintelligible lines are warned about and ignored. Commands may contain 465references to environment variables. The syntax is the shell-like 466@code{$VAR} or @code{$@{VAR@}}. Note that this causes incompatibility 467with previous @code{screen} versions, as now the '$'-character has to be 468protected with '\' if no variable substitution is intended. A string in 469single-quotes is also protected from variable substitution. 470 471Two configuration files are shipped as examples with your screen 472distribution: @file{etc/screenrc} and @file{etc/etcscreenrc}. They 473contain a number of useful examples for various commands. 474 475@node Source, Colon, Startup Files, Customization 476@section Source 477@deffn Command source file 478(none)@* 479Read and execute commands from file @var{file}. Source commands 480may be nested to a maximum recursion level of ten. If @var{file} 481is not an absolute path and screen is already processing a 482source command, the parent directory of the running source 483command file is used to search for the new command file before 484screen's current directory. 485 486Note that termcap/terminfo/termcapinfo commands only work 487at startup and reattach time, so they must be reached via 488the default screenrc files to have an effect. 489@end deffn 490 491@node Colon, , Source, Customization 492@section Colon 493Customization can also be done online, with this command: 494 495@kindex : 496@deffn Command colon 497(@kbd{C-a :})@* 498Allows you to enter @file{.screenrc} command lines. Useful for 499on-the-fly modification of key bindings, specific window creation and 500changing settings. Note that the @code{set} keyword no longer exists, 501as of version 3.3. Change default settings with commands starting with 502@samp{def}. You might think of this as the @code{ex} command mode of 503@code{screen}, with @code{copy} as its @code{vi} command mode 504(@pxref{Copy and Paste}). 505@end deffn 506 507@node Commands, New Window, Customization, Top 508@chapter Commands 509 510A command in @code{screen} can either be bound to a key, invoked from a 511screenrc file, or called from the @code{colon} prompt 512(@pxref{Customization}). As of version 3.3, all commands can be bound 513to keys, although some may be less useful than others. 514For a number of real life working examples of the most important 515commands see the files @file{etc/screenrc} and @file{etc/etcscreenrc} 516of your screen distribution. 517 518In this manual, a command definition looks like this: 519 520@table @asis 521@item -- Command: command [-n] ARG1 [ARG2] @dots{} 522(@var{keybindings})@* 523This command does something, but I can't remember what. 524@end table 525 526An argument in square brackets (@samp{[]}) is optional. Many commands 527take an argument of @samp{on} or @samp{off}, which is indicated as 528@var{state} in the definition. 529 530@menu 531* Default Key Bindings:: @code{screen} keyboard commands. 532* Command Summary:: List of all commands. 533@end menu 534 535@node Default Key Bindings, Command Summary, , Commands 536@section Default Key Bindings 537 538As mentioned previously, each keyboard command consists of a 539@kbd{C-a} followed by one other character. For your convenience, all 540commands that are bound to lower-case letters are also bound to their 541control character counterparts (with the exception of @kbd{C-a a}; see 542below). Thus, both @kbd{C-a c} and @kbd{C-a C-c} can be used to create 543a window. 544 545The following table shows the default key bindings: 546 547@table @asis 548@item @kbd{C-a '} 549(select)@* 550Prompt for a window identifier and switch. 551@xref{Selecting}. 552 553@item @kbd{C-a "} 554(windowlist -b)@* 555Present a list of all windows for selection. 556@xref{Selecting}. 557 558@item @kbd{C-a 0@dots{}9, -} 559(select 0@dots{}select 9, select -)@* 560Switch to window number 0@dots{}9, or the blank window. 561@xref{Selecting}. 562 563@item @kbd{C-a @key{Tab}} 564(focus)@* 565Switch the input focus to the next region. @xref{Regions}. 566 567@item @kbd{C-a C-a} 568(other)@* 569Toggle to the window displayed previously. If this window does no 570longer exist, @code{other} has the same effect as @code{next}. 571@xref{Selecting}. 572 573@item @kbd{C-a a} 574(meta)@* 575Send the command character (C-a) to window. See @code{escape} command. 576@xref{Command Character}. 577 578@item @kbd{C-a A} 579(title)@* 580Allow the user to enter a title for the current window. 581@xref{Naming Windows}. 582 583@item @kbd{C-a b} 584@itemx @kbd{C-a C-b} 585(break)@* 586Send a break to the tty. 587@xref{Break}. 588 589@item @kbd{C-a B} 590(pow_break)@* 591Close and reopen the tty-line. 592@xref{Break}. 593 594@item @kbd{C-a c} 595@itemx @kbd{C-a C-c} 596(screen)@* 597Create a new window with a shell and switch to that window. 598@xref{Screen Command}. 599 600@item @kbd{C-a C} 601(clear)@* 602Clear the screen. @xref{Clear}. 603 604@item @kbd{C-a d} 605@itemx @kbd{C-a C-d} 606(detach)@* 607Detach @code{screen} from this terminal. @xref{Detach}. 608 609@item @kbd{C-a D D} 610(pow_detach)@* 611Detach and logout. @xref{Power Detach}. 612 613@item @kbd{C-a f} 614@itemx @kbd{C-a C-f} 615(flow)@* 616Cycle flow among @samp{on}, @samp{off} or @samp{auto}. @xref{Flow}. 617 618@item @kbd{C-a F} 619(fit)@* 620Resize the window to the current region size. @xref{Window Size}. 621 622@item @kbd{C-a C-g} 623(vbell)@* 624Toggle visual bell mode. @xref{Bell}. 625 626@item @kbd{C-a h} 627(hardcopy)@* 628Write a hardcopy of the current window to the file ``hardcopy.@var{n}''. 629@xref{Hardcopy}. 630 631@item @kbd{C-a H} 632(log)@* 633Toggle logging of the current window to the file ``screenlog.@var{n}''. 634@xref{Log}. 635 636@item @kbd{C-a i} 637@itemx @kbd{C-a C-i} 638(info)@* 639Show info about the current window. @xref{Info}. 640 641@item @kbd{C-a k} 642@itemx @kbd{C-a C-k} 643(kill)@* 644Destroy the current window. @xref{Kill}. 645 646@item @kbd{C-a l} 647@itemx @kbd{C-a C-l} 648(redisplay)@* 649Fully refresh the current window. @xref{Redisplay}. 650 651@item @kbd{C-a L} 652(login)@* 653Toggle the current window's login state. @xref{Login}. 654 655@item @kbd{C-a m} 656@itemx @kbd{C-a C-m} 657(lastmsg)@* 658Repeat the last message displayed in the message line. 659@xref{Last Message}. 660 661@item @kbd{C-a M} 662(monitor) 663Toggle monitoring of the current window. @xref{Monitor}. 664 665@item @kbd{C-a @key{SPC}} 666@itemx @kbd{C-a n} 667@itemx @kbd{C-a C-n} 668(next)@* 669Switch to the next window. @xref{Selecting}. 670 671@item @kbd{C-a N} 672(number)@* 673Show the number (and title) of the current window. @xref{Number}. 674 675@item @kbd{C-a p} 676@itemx @kbd{C-a C-p} 677@itemx @kbd{C-a C-h} 678@itemx @kbd{C-a @key{BackSpace}} 679(prev)@* 680Switch to the previous window (opposite of @kbd{C-a n}). 681@xref{Selecting}. 682 683@item @kbd{C-a q} 684@itemx @kbd{C-a C-q} 685(xon)@* 686Send a ^Q (ASCII XON) to the current window. @xref{XON/XOFF}. 687 688@item @kbd{C-a Q} 689(only)@* 690Delete all regions but the current one. @xref{Regions}. 691 692@item @kbd{C-a r} 693@itemx @kbd{C-a C-r} 694(wrap)@* 695Toggle the current window's line-wrap setting (turn the current window's 696automatic margins on or off). @xref{Wrap}. 697 698@item @kbd{C-a s} 699@itemx @kbd{C-a C-s} 700(xoff)@* 701Send a ^S (ASCII XOFF) to the current window. @xref{XON/XOFF}. 702 703@item @kbd{C-a S} 704(split)@* 705Split the current region into two new ones. @xref{Regions}. 706 707@item @kbd{C-a t} 708@itemx @kbd{C-a C-t} 709(time)@* 710Show the load average and xref. @xref{Time}. 711 712@item @kbd{C-a v} 713(version)@* 714Display the version and compilation date. @xref{Version}. 715 716@item @kbd{C-a C-v} 717(digraph)@* 718Enter digraph. @xref{Digraph}. 719 720@item @kbd{C-a w} 721@itemx @kbd{C-a C-w} 722(windows)@* 723Show a list of active windows. @xref{Windows}. 724 725@item @kbd{C-a W} 726(width)@* 727Toggle between 80 and 132 columns. @xref{Window Size}. 728 729@item @kbd{C-a x} 730@itemx @kbd{C-a C-x} 731(lockscreen)@* 732Lock your terminal. @xref{Lock}. 733 734@item @kbd{C-a X} 735(remove)@* 736Kill the current region. @xref{Regions}. 737 738@item @kbd{C-a z} 739@itemx @kbd{C-a C-z} 740(suspend)@* 741Suspend @code{screen}. @xref{Suspend}. 742 743@item @kbd{C-a Z} 744(reset)@* 745Reset the virtual terminal to its ``power-on'' values. 746@xref{Reset}. 747 748@item @kbd{C-a .} 749(dumptermcap)@* 750Write out a @file{.termcap} file. @xref{Dump Termcap}. 751 752@item @kbd{C-a ?} 753(help)@* 754Show key bindings. @xref{Help}. 755 756@item @kbd{C-a C-\} 757(quit)@* 758Kill all windows and terminate @code{screen}. @xref{Quit}. 759 760@item @kbd{C-a :} 761(colon)@* 762Enter a command line. @xref{Colon}. 763 764@item @kbd{C-a [} 765@itemx @kbd{C-a C-[} 766@itemx @kbd{C-a @key{ESC}} 767(copy)@* 768Enter copy/scrollback mode. @xref{Copy}. 769 770@item @kbd{C-a ]} 771@itemx @kbd{C-a C-]} 772(paste .)@* 773Write the contents of the paste buffer to the stdin queue of the 774current window. @xref{Paste}. 775 776@item @kbd{C-a @{} 777@itemx @kbd{C-a @}} 778(history)@* 779Copy and paste a previous (command) line. @xref{History}. 780 781@item @kbd{C-a >} 782(writebuf)@* 783Write the paste buffer out to the screen-exchange file. 784@xref{Screen Exchange}. 785 786@item @kbd{C-a <} 787(readbuf)@* 788Read the screen-exchange file into the paste buffer. 789@xref{Screen Exchange}. 790 791@item @kbd{C-a =} 792(removebuf)@* 793Delete the screen-exchange file. @xref{Screen Exchange}. 794 795@item @kbd{C-a _} 796(silence)@* 797Start/stop monitoring the current window for inactivity. @xref{Silence}, 798 799@item @kbd{C-a ,} 800(license)@* 801Show the copyright page. 802 803@item @kbd{C-a *} 804(displays)@* 805Show the listing of attached displays. 806@end table 807 808@node Command Summary, , Default Key Bindings, Commands 809@section Command Summary 810@cindex command summary 811 812@table @code 813@item acladd @var{usernames} 814Allow other users in this session. @xref{Multiuser Session}. 815@item aclchg @var{usernames permbits list} 816Change a user's permissions. @xref{Multiuser Session}. 817@item acldel @var{username} 818Disallow other user in this session. @xref{Multiuser Session}. 819@item aclgrp @var{usrname} [@var{groupname}] 820Inherit permissions granted to a group leader. @xref{Multiuser Session}. 821@item aclumask [@var{users}]+/-@var{bits} ... 822Predefine access to new windows. @xref{Umask}. 823@item activity @var{message} 824Set the activity notification message. @xref{Monitor}. 825@item addacl @var{usernames} 826Synonym to @code{acladd}. @xref{Multiuser Session}. 827@item allpartial @var{state} 828Set all windows to partial refresh. @xref{Redisplay}. 829@item altscreen @var{state} 830Enables support for the "alternate screen" terminal capability. @xref{Redisplay}. 831@item at [@var{ident}][@kbd{#}@var{|}@kbd{*}@var{|}@kbd{%}] @var{command} [@var{args}] 832Execute a command at other displays or windows. @xref{At}. 833@item attrcolor @var{attrib} [@var{attribute/color-modifier}] 834Map attributes to colors. @xref{Attrcolor}. 835@item autodetach @var{state} 836Automatically detach the session on SIGHUP. @xref{Detach}. 837@item autonuke @var{state} 838Enable a clear screen to discard unwritten output. @xref{Autonuke}. 839@item backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}] 840Define a command for the backtick string escape. @xref{Backtick}. 841@item bce [@var{state}] 842Change background color erase. @xref{Character Processing}. 843@item bell_msg [@var{message}] 844Set the bell notification message. @xref{Bell}. 845@item bind [-c @var{class}] @var{key} [@var{command} [@var{args}]] 846Bind a command to a key. @xref{Bind}. 847@item bindkey [@var{opts}] [@var{string} [@var{cmd args}]] 848Bind a string to a series of keystrokes. @xref{Bindkey}. 849@item blanker 850Blank the screen. @xref{Screen Saver}. 851@item blankerprg 852Define a blanker program. @xref{Screen Saver}. 853@item break [@var{duration}] 854Send a break signal to the current window. @xref{Break}. 855@item breaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}] 856Specify how to generate breaks. @xref{Break}. 857@item bufferfile [@var{exchange-file}] 858Select a file for screen-exchange. @xref{Screen Exchange}. 859@item c1 [@var{state}] 860Change c1 code processing. @xref{Character Processing}. 861@item caption @var{mode} [@var{string}] 862Change caption mode and string. @xref{Regions}. 863@item chacl @var{usernames permbits list} 864Synonym to @code{aclchg}. @xref{Multiuser Session}. 865@item charset @var{set} 866Change character set slot designation. @xref{Character Processing}. 867@item chdir [@var{directory}] 868Change the current directory for future windows. @xref{Chdir}. 869@item clear 870Clear the window screen. @xref{Clear}. 871@item colon 872Enter a @code{screen} command. @xref{Colon}. 873@item command [-c @var{class}] 874Simulate the screen escape key. @xref{Command Character}. 875@item compacthist [@var{state}] 876Selects compaction of trailing empty lines. @xref{Scrollback}. 877@item console [@var{state}] 878Grab or ungrab console output. @xref{Console}. 879@item copy 880Enter copy mode. @xref{Copy}. 881@item copy_reg [@var{key}] 882Removed. Use @code{paste} instead. @xref{Registers}. 883@item crlf @var{state} 884Select line break behavior for copying. @xref{Line Termination}. 885@item debug @var{state} 886Suppress/allow debugging output. @xref{Debug}. 887@item defautonuke @var{state} 888Select default autonuke behavior. @xref{Autonuke}. 889@item defbce @var{state} 890Select background color erase. @xref{Character Processing}. 891@item defbreaktype [@var{tcsendbreak} | @var{TCSBRK} | @var{TIOCSBRK}] 892Specify the default for generating breaks. @xref{Break}. 893@item defc1 @var{state} 894Select default c1 processing behavior. @xref{Character Processing}. 895@item defcharset [@var{set}] 896Change defaul character set slot designation. @xref{Character Processing}. 897@item defencoding @var{enc} 898Select default window encoding. @xref{Character Processing}. 899@item defescape @var{xy} 900Set the default command and @code{meta} characters. @xref{Command Character}. 901@item defflow @var{fstate} 902Select default flow control behavior. @xref{Flow}. 903@item defgr @var{state} 904Select default GR processing behavior. @xref{Character Processing}. 905@item defhstatus [@var{status}] 906Select default window hardstatus line. @xref{Hardstatus}. 907@item deflog @var{state} 908Select default window logging behavior. @xref{Log}. 909@item deflogin @var{state} 910Select default utmp logging behavior. @xref{Login}. 911@item defmode @var{mode} 912Select default file mode for ptys. @xref{Mode}. 913@item defmonitor @var{state} 914Select default activity monitoring behavior. @xref{Monitor}. 915@item defnonblock @var{state}|@var{numsecs} 916Select default nonblock mode. @xref{Nonblock}. 917@item defobuflimit @var{limit} 918Select default output buffer limit. @xref{Obuflimit}. 919@item defscrollback @var{num} 920Set default lines of scrollback. @xref{Scrollback}. 921@item defshell @var{command} 922Set the default program for new windows. @xref{Shell}. 923@item defsilence @var{state} 924Select default idle monitoring behavior. @xref{Silence}. 925@item defslowpaste @var{msec} 926Select the default inter-character timeout when pasting. @xref{Paste}. 927@item defutf8 @var{state} 928Select default character encoding. @xref{Character Processing}. 929@item defwrap @var{state} 930Set default line-wrapping behavior. @xref{Wrap}. 931@item defwritelock @var{on|off|auto} 932Set default writelock behavior. @xref{Multiuser Session}. 933@item defzombie [@var{keys}] 934Keep dead windows. @xref{Zombie}. 935@item detach [-h] 936Disconnect @code{screen} from the terminal. @xref{Detach}. 937@item digraph 938Enter digraph sequence. @xref{Digraph}. 939@item dinfo 940Display terminal information. @xref{Info}. 941@item displays 942List currently active user interfaces. @xref{Displays}. 943@item dumptermcap 944Write the window's termcap entry to a file. @xref{Dump Termcap}. 945@item echo [-n] @var{message} 946Display a message on startup. @xref{Startup}. 947@item encoding @var{enc} [@var{denc}] 948Set the encoding of a window. @xref{Character Processing}. 949@item escape @var{xy} 950Set the command and @code{meta} characters. @xref{Command Character}. 951@item eval @var{command1} [@var{command2} ...] 952Parse and execute each argument. @xref{Eval}. 953@item exec [[@var{fdpat}] @var{command} [@var{args} ...]] 954Run a subprocess (filter). @xref{Exec}. 955@item fit 956Change window size to current display size. @xref{Window Size}. 957@item flow [@var{fstate}] 958Set flow control behavior. @xref{Flow}. 959@item focus 960Move focus to next region. @xref{Regions}. 961@item gr [@var{state}] 962Change GR charset processing. @xref{Character Processing}. 963@item hardcopy [-h] [@var{file}] 964Write out the contents of the current window. @xref{Hardcopy}. 965@item hardcopy_append @var{state} 966Append to hardcopy files. @xref{Hardcopy}. 967@item hardcopydir @var{directory} 968Place, where to dump hardcopy files. @xref{Hardcopy}. 969@item hardstatus [@var{state}] 970Use the hardware status line. @xref{Hardware Status Line}. 971@item height [@var{lines} [@var{cols}]] 972Set display height. @xref{Window Size}. 973@item help [-c @var{class}] 974Display current key bindings. @xref{Help}. 975@item history 976Find previous command beginning @dots{}. @xref{History}. 977@item hstatus @var{status} 978Change the window's hardstatus line. @xref{Hardstatus}. 979@item idle [@var{timeout} [@var{cmd} @var{args}]] 980Define a screen saver command. @xref{Screen Saver}. 981@item ignorecase [@var{state}] 982Ignore character case in searches. @xref{Searching}. 983@item info 984Display window settings. @xref{Info}. 985@item ins_reg [@var{key}] 986Removed, use @code{paste} instead. @xref{Registers}. 987@item kill 988Destroy the current window. @xref{Kill}. 989@item lastmsg 990Redisplay the last message. @xref{Last Message}. 991@item license 992Display licensing information. @xref{Startup}. 993@item lockscreen 994Lock the controlling terminal. @xref{Lock}. 995@item log [@var{state}] 996Log all output in the current window. @xref{Log}. 997@item logfile @var{filename} 998Place where to collect logfiles. @xref{Log}. 999@item login [@var{state}] 1000Log the window in @file{/etc/utmp}. @xref{Login}. 1001@item logtstamp [@var{state}] 1002Configure logfile time-stamps. @xref{Log}. 1003@item mapdefault 1004Use only the default mapping table for the next keystroke. @xref{Bindkey Control}. 1005@item mapnotnext 1006Don't try to do keymapping on the next keystroke. @xref{Bindkey Control}. 1007@item maptimeout @var{timo} 1008Set the inter-character timeout used for keymapping. @xref{Bindkey Control}. 1009@item markkeys @var{string} 1010Rebind keys in copy mode. @xref{Copy Mode Keys}. 1011@item maxwin @var{n} 1012Set the maximum window number. @xref{Maxwin}. 1013@item meta 1014Insert the command character. @xref{Command Character}. 1015@item monitor [@var{state}] 1016Monitor activity in window. @xref{Monitor}. 1017@item msgminwait @var{sec} 1018Set minimum message wait. @xref{Message Wait}. 1019@item msgwait @var{sec} 1020Set default message wait. @xref{Message Wait}. 1021@item multiuser @var{state} 1022Go into single or multi user mode. @xref{Multiuser Session}. 1023@item nethack @var{state} 1024Use @code{nethack}-like error messages. @xref{Nethack}. 1025@item next 1026Switch to the next window. @xref{Selecting}. 1027@item nonblock [@var{state}|@var{numsecs}] 1028Disable flow control to the current display. @xref{Nonblock}.|@var{numsecs}] 1029@item number [@var{n}] 1030Change/display the current window's number. @xref{Number}. 1031@item obuflimit [@var{limit}] 1032Select output buffer limit. @xref{Obuflimit}. 1033@item only 1034Kill all other regions. @xref{Regions}. 1035@item other 1036Switch to the window you were in last. @xref{Selecting}. 1037@item partial @var{state} 1038Set window to partial refresh. @xref{Redisplay}. 1039@item password [@var{crypted_pw}] 1040Set reattach password. @xref{Detach}. 1041@item paste [@var{src_regs} [@var{dest_reg}]] 1042Paste contents of paste buffer or registers somewhere. @xref{Paste}. 1043@item pastefont [@var{state}] 1044Include font information in the paste buffer. @xref{Paste}. 1045@item pow_break 1046Close and Reopen the window's terminal. @xref{Break}. 1047@item pow_detach 1048Detach and hang up. @xref{Power Detach}. 1049@item pow_detach_msg [@var{message}] 1050Set message displayed on @code{pow_detach}. @xref{Power Detach}. 1051@item prev 1052Switch to the previous window. @xref{Selecting}. 1053@item printcmd [@var{cmd}] 1054Set a command for VT100 printer port emulation. @xref{Printcmd}. 1055@item process [@var{key}] 1056Treat a register as input to @code{screen}. @xref{Registers}. 1057@item quit 1058Kill all windows and exit. @xref{Quit}. 1059@item readbuf [-e @var{encoding}] [@var{filename}] 1060Read the paste buffer from the screen-exchange file. @xref{Screen Exchange}. 1061@item readreg [-e @var{encoding}] [@var{reg} [@var{file}]] 1062Load a register from paste buffer or file. @xref{Registers}. 1063@item redisplay 1064Redisplay the current window. @xref{Redisplay}. 1065@item register [-e @var{encoding}] @var{key} @var{string} 1066Store a string to a register. @xref{Registers}. 1067@item remove 1068Kill current region. @xref{Regions}. 1069@item removebuf 1070Delete the screen-exchange file. @xref{Screen Exchange}. 1071@item reset 1072Reset the terminal settings for the window. @xref{Reset}. 1073@item resize [(+/-)lines] 1074Grow or shrink a region 1075@item screen [@var{opts}] [@var{n}] [@var{cmd} [@var{args}]] 1076Create a new window. @xref{Screen Command}. 1077@item scrollback @var{num} 1078Set size of scrollback buffer. @xref{Scrollback}. 1079@item select [@var{n}] 1080Switch to a specified window. @xref{Selecting}. 1081@item sessionname [@var{name}] 1082Name this session. @xref{Session Name}. 1083@item setenv [@var{var} [@var{string}]] 1084Set an environment variable for new windows. @xref{Setenv}. 1085@item setsid @var{state} 1086Controll process group creation for windows. @xref{Setsid}. 1087@item shell @var{command} 1088Set the default program for new windows. @xref{Shell}. 1089@item shelltitle @var{title} 1090Set the default name for new windows. @xref{Shell}. 1091@item silence [@var{state}|@var{seconds}] 1092Monitor a window for inactivity. @xref{Silence}. 1093@item silencewait @var{seconds} 1094Default timeout to trigger an inactivity notify. @xref{Silence}. 1095@item sleep @var{num} 1096Pause during startup. @xref{Startup}. 1097@item slowpaste @var{msec} 1098Slow down pasting in windows. @xref{Paste}. 1099@item source @var{file} 1100Run commands from a file. @xref{Source}. 1101@item sorendition [@var{attr} [@var{color}]] 1102Change text highlighting. @xref{Sorendition}. 1103@item split 1104Split region into two parts. @xref{Regions}. 1105@item startup_message @var{state} 1106Display copyright notice on startup. @xref{Startup}. 1107@item stuff @var{string} 1108Stuff a string in the input buffer of a window. @xref{Paste}. 1109@item su [@var{username} [@var{password} [@var{password2}]]] 1110Identify a user. @xref{Multiuser Session}. 1111@item suspend 1112Put session in background. @xref{Suspend}. 1113@item term @var{term} 1114Set @code{$TERM} for new windows. @xref{Term}. 1115@item termcap @var{term} @var{terminal-tweaks} [@var{window-tweaks}] 1116Tweak termcap entries for best performance. @xref{Termcap Syntax}. 1117@item terminfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}] 1118Ditto, for terminfo systems. @xref{Termcap Syntax}. 1119@item termcapinfo @var{term} @var{terminal-tweaks} [@var{window-tweaks}] 1120Ditto, for both systems. @xref{Termcap Syntax}. 1121@item time [@var{string}] 1122Display time and load average. @xref{Time}. 1123@item title [@var{windowtitle}] 1124Set the name of the current window. @xref{Title Command}. 1125@item umask [@var{users}]+/-@var{bits} ... 1126Synonym to @code{aclumask}. @xref{Umask}. 1127@item unsetenv @var{var} 1128Unset environment variable for new windows. @xref{Setenv}. 1129@item utf8 [@var{state} [@var{dstate}]] 1130Select character encoding of the current window. @xref{Character Processing}. 1131@item vbell [@var{state}] 1132Use visual bell. @xref{Bell}. 1133@item vbell_msg [@var{message}] 1134Set vbell message. @xref{Bell}. 1135@item vbellwait @var{sec} 1136Set delay for vbell message. @xref{Bell}. 1137@item version 1138Display @code{screen} version. @xref{Version}. 1139@item wall @var{message} 1140Write a message to all displays. @xref{Multiuser Session}. 1141@item width [@var{cols} [@var{lines}]] 1142Set the width of the window. @xref{Window Size}. 1143@item windowlist [-b] | string [@var{string}] | title [@var{title}] 1144Present a list of all windows for selection. @xref{Windowlist}. 1145@item windows 1146List active windows. @xref{Windows}. 1147@item wrap [@var{state}] 1148Control line-wrap behavior. @xref{Wrap}. 1149@item writebuf [-e @var{encoding}] [@var{filename}] 1150Write paste buffer to screen-exchange file. @xref{Screen Exchange}. 1151@item writelock @var{on}|@var{off}|@var{auto} 1152Grant exclusive write permission. @xref{Multiuser Session}. 1153@item xoff 1154Send an XOFF character. @xref{XON/XOFF}. 1155@item xon 1156Send an XON character. @xref{XON/XOFF}. 1157@item zmodem [off|auto|catch|pass] 1158Define how screen treats zmodem requests. @xref{Zmodem}. 1159@item zombie [@var{keys}] 1160Keep dead windows. @xref{Zombie}. 1161@end table 1162 1163@node New Window, Selecting, Commands, Top 1164@chapter New Window 1165 1166This section describes the commands for creating a new window for 1167running programs. When a new window is created, the first available 1168number from the range 0@dots{}9 is assigned to it. 1169The number of windows is limited at compile-time by the MAXWIN 1170configuration parameter. 1171 1172@menu 1173* Chdir:: Change the working directory for new windows. 1174* Screen Command:: Create a new window. 1175* Setenv:: Set environment variables for new windows. 1176* Shell:: Parameters for shell windows. 1177* Term:: Set the terminal type for new windows. 1178* Window Types:: Creating different types of windows. 1179@end menu 1180 1181@node Chdir, Screen Command, , New Window 1182@section Chdir 1183@deffn Command chdir [directory] 1184(none)@* 1185Change the current directory of @code{screen} to the specified directory 1186or, if called without an argument, to your home directory (the value of 1187the environment variable @code{$HOME}). All windows that are created by means 1188of the @code{screen} command from within @file{.screenrc} or by means of 1189@kbd{C-a : screen @dots{}} or @kbd{C-a c} use this as their default 1190directory. Without a @code{chdir} command, this would be the directory 1191from which @code{screen} was invoked. Hardcopy and log files are always 1192written to the @emph{window's} default directory, @emph{not} the current 1193directory of the process running in the window. You can use this 1194command multiple times in your @file{.screenrc} to start various windows 1195in different default directories, but the last @code{chdir} value will 1196affect all the windows you create interactively. 1197@end deffn 1198 1199@node Screen Command, Setenv, Chdir, New Window 1200@section Screen Command 1201@kindex c 1202@kindex C-c 1203@deffn Command screen [opts] [n] [cmd [args]] 1204(@kbd{C-a c}, @kbd{C-a C-c})@* 1205Establish a new window. The flow-control options (@samp{-f}, @samp{-fn} 1206and @samp{-fa}), title option (@samp{-t}), login options 1207(@samp{-l} and @samp{-ln}) , terminal type option (@samp{-T @var{term}}), 1208the all-capability-flag (@samp{-a}) and scrollback option 1209(@samp{-h @var{num}}) may be specified with each command. 1210The option (@samp{-M}) turns monitoring on for this window. 1211The option (@samp{-L}) turns output logging on for this window. 1212If an optional number @var{n} in the range 0@dots{}9 is given, 1213the window number @var{n} is assigned to the newly created window (or, 1214if this number is already in-use, the next available number). If a 1215command is specified after @code{screen}, this command (with the given 1216arguments) is started in the window; otherwise, a shell is created. 1217 1218Screen has built in some functionality of @samp{cu} and @samp{telnet}. 1219@xref{Window Types}. 1220@end deffn 1221 1222Thus, if your @file{.screenrc} contains the lines 1223 1224@example 1225# example for .screenrc: 1226screen 1 1227screen -fn -t foobar 2 -L telnet foobar 1228@end example 1229 1230@noindent 1231@code{screen} creates a shell window (in window #1) and a window with a 1232TELNET connection to the machine foobar (with no flow-control using the 1233title @samp{foobar} in window #2) and will write a logfile @samp{screenlog.2} 1234of the telnet session. If you do not include any 1235@code{screen} commands in your @file{.screenrc} file, then @code{screen} 1236defaults to creating a single shell window, number zero. When the 1237initialization is completed, @code{screen} switches to the last window 1238specified in your .screenrc file or, if none, it opens default window 1239#0. 1240 1241@node Setenv, Shell, Screen Command, New Window 1242@section Setenv 1243@deffn Command setenv var string 1244(none)@* 1245Set the environment variable @var{var} to value @var{string}. 1246If only @var{var} is specified, the user will be prompted to enter a value. 1247If no parameters are specified, the user will be prompted for both variable 1248and value. The environment is inherited by all subsequently forked shells. 1249@end deffn 1250 1251@deffn Command unsetenv var 1252(none)@* 1253Unset an environment variable. 1254@end deffn 1255 1256@node Shell, Term, Setenv, New Window 1257@section Shell 1258@deffn Command shell command 1259@deffnx Command defshell command 1260(none)@* 1261Set the command to be used to create a new shell. This overrides the 1262value of the environment variable @code{$SHELL}. This is useful if 1263you'd like to run a tty-enhancer which is expecting to execute the 1264program specified in @code{$SHELL}. If the command begins with 1265a @samp{-} character, the shell will be started as a login-shell. 1266 1267@code{defshell} is currently a synonym to the @code{shell} command. 1268@end deffn 1269 1270@deffn Command shelltitle title 1271(none)@* 1272Set the title for all shells created during startup or by the C-a C-c 1273command. @xref{Naming Windows}, for details about what titles are. 1274@end deffn 1275 1276@node Term, Window Types , Shell, New Window 1277@section Term 1278@deffn Command term term 1279(none)@* 1280In each window @code{screen} opens, it sets the @code{$TERM} 1281variable to @code{screen} by default, unless no description for 1282@code{screen} is installed in the local termcap or terminfo data base. 1283In that case it pretends that the terminal emulator is @samp{vt100}. 1284This won't do much harm, as @code{screen} is VT100/ANSI compatible. The 1285use of the @code{term} command is discouraged for non-default purpose. 1286That is, one may want to specify special @code{$TERM} settings (e.g. vt100) for 1287the next @code{screen rlogin othermachine} command. Use the command 1288@code{screen -T vt100 rlogin othermachine} rather than setting 1289and resetting the default. 1290@end deffn 1291 1292@node Window Types, , Term, New Window 1293@section Window Types 1294@cindex window types 1295Screen provides three different window types. New windows are created 1296with @code{screen}'s @samp{screen} command (@pxref{Screen Command}). 1297The first parameter to the @samp{screen} command defines which 1298type of window is created. The different window types are all 1299special cases of the normal type. They have been added in order 1300to allow @code{screen} to be used efficiently as a console 1301with 100 or more windows. 1302@itemize @bullet 1303@item 1304The normal window contains a shell (default, if no parameter is given) 1305or any other system command that could be executed from a shell. 1306(e.g. @samp{slogin}, etc...). 1307 1308@item 1309If a tty (character special device) name (e.g. @samp{/dev/ttya}) 1310is specified as the first parameter, then the window is directly 1311connected to this device. 1312This window type is similar to @samp{screen cu -l /dev/ttya}. 1313Read and write access is required on the device node, 1314an exclusive open is attempted on the node to mark the connection line 1315as busy. 1316An optional parameter is allowed consisting of a comma separated 1317list of flags in the notation used by @samp{stty(1)}: 1318@table @code 1319@item <baud_rate> 1320Usually 300, 1200, 9600 or 19200. This affects transmission as well as 1321receive speed. 1322@item cs8 or cs7 1323Specify the transmission of eight (or seven) bits per byte. 1324@item ixon or -ixon 1325Enables (or disables) software flow-control (CTRL-S/CTRL-Q) for sending 1326data. 1327@item ixoff or -ixoff 1328Enables (or disables) software flow-control for receiving data. 1329@item istrip or -istrip 1330Clear (or keep) the eight bit in each received byte. 1331@end table 1332 1333You may want to specify as many of these options as applicable. 1334Unspecified options cause the terminal driver to make up the parameter 1335values of the connection. These values are system dependant and may be 1336in defaults or values saved from a previous connection. 1337 1338For tty windows, the @code{info} command shows some of the modem 1339control lines in the status line. 1340These may include @samp{RTS}, @samp{CTS}, @samp{DTR}, @samp{CD} and 1341more. This depends rather on on the available @code{ioctl()}'s and system 1342header files than on the physical capabilities of the serial board. 1343The name of a logical low (inactive) signal is preceded by an 1344exclamation mark (@samp{!}), otherwise the signal is logical high (active). 1345Unsupported but shown signals are usually shown low. 1346When the @code{CLOCAL} status bit is true, the whole set of modem signals is 1347placed inside curly braces (@samp{@{} and @samp{@}}). 1348When the @code{CRTSCTS} or @code{TIOCSOFTCAR} bit is true, the signals 1349@samp{CTS} or @samp{CD} are shown in parenthesis, respectively. 1350 1351For tty windows, the command @code{break} causes the Data transmission 1352line (TxD) to go low for a specified period of time. This is expected 1353to be interpreted as break signal on the other side. 1354No data is sent and no modem control line is changed when a 1355@code{break} is issued. 1356 1357@item 1358If the first parameter is @code{//telnet}, the second parameter is 1359expected to be a host name, and an optional third parameter may specify 1360a TCP port number (default decimal 23). Screen will connect to a 1361server listening on the remote host and use the telnet protocol to 1362communicate with that server. 1363 1364For telnet windows, the command @code{info} shows details about 1365the connection in square brackets (@samp{[} and @samp{]}) at the end of 1366the status line. 1367@table @code 1368@item b 1369BINARY. The connection is in binary mode. 1370@item e 1371ECHO. Local echo is disabled. 1372@item c 1373SGA. The connection is in `character mode' (default: `line mode'). 1374@item t 1375TTYPE. The terminal type has been requested by the remote host. Screen 1376sends the name @code{screen} unless instructed otherwise (see also the 1377command @samp{term}). 1378@item w 1379NAWS. The remote site is notified about window size changes. 1380@item f 1381LFLOW. The remote host will send flow control information. 1382(Ignored at the moment.) 1383@end table 1384Additional flags for debugging are @samp{x}, @samp{t} and @samp{n} 1385(XDISPLOC, TSPEED and NEWENV). 1386 1387For telnet windows, the command @code{break} sends the telnet code 1388@code{IAC BREAK} (decimal 243) to the remote host. 1389 1390@end itemize 1391 1392@node Selecting, Session Management, New Window, Top 1393@chapter Selecting a Window 1394 1395This section describes the commands for switching between windows in an 1396@code{screen} session. The windows are numbered from 0 to 9, and are created 1397in that order by default (@pxref{New Window}). 1398 1399@menu 1400* Next and Previous:: Forward or back one window. 1401* Other Window:: Switch back and forth between two windows. 1402* Select:: Switch to a window (and to one after @code{kill}). 1403* Windowlist:: Present a list of all windows for selection. 1404@end menu 1405 1406@node Next and Previous, Other Window, , Selecting 1407@section Moving Back and Forth 1408@kindex SPC 1409@kindex n 1410@kindex C-n 1411@deffn Command next 1412(@kbd{C-a @key{SPC}}, @kbd{C-a n}, @kbd{C-a C-n})@* 1413Switch to the next window. This command can be used repeatedly to 1414cycle through the list of windows. (On some terminals, C-@key{SPC} 1415generates a NUL character, so you must release the control key before 1416pressing space.) 1417@end deffn 1418 1419@kindex p 1420@kindex C-p 1421@deffn Command prev 1422(@kbd{C-a p}, @kbd{C-a C-p})@* 1423Switch to the previous window (the opposite of @kbd{C-a n}). 1424@end deffn 1425 1426@node Other Window, Select, Next and Previous, Selecting 1427@section Other Window 1428@kindex C-a 1429@deffn Command other 1430(@kbd{C-a C-a})@* 1431Switch to the last window displayed. Note that this command 1432defaults to the command character typed twice, unless overridden. 1433For instance, if you use the option @samp{-e]x}, 1434this command becomes @kbd{]]} (@pxref{Command Character}). 1435@end deffn 1436 1437@node Select, Windowlist, Other Window, Selecting 1438@section Select 1439@kindex 0@dots{}9 1440@kindex ' 1441@deffn Command select [n] 1442(@kbd{C-a @var{n}}, @kbd{C-a '})@* 1443Switch to the window with the number @var{n}. 1444If no window number is specified, you get prompted for an 1445identifier. This can be a window name (title) or a number. 1446When a new window is established, the lowest available number 1447is assigned to this window. 1448Thus, the first window can be activated by @code{select 0}; there 1449can be no more than 10 windows present simultaneously (unless screen is 1450compiled with a higher MAXWIN setting). 1451There are two special arguments, @code{select -} switches to the 1452internal blank window and @code{select .} switches to the 1453current window. The latter is useful if used with screen's 1454@code{-X} option. 1455 1456@end deffn 1457 1458@node Windowlist, , Select, Selecting 1459@section Windowlist 1460@kindex " 1461@deffn Command windowlist [-b] [-m] 1462@deffnx Command windowlist string [@var{string}] 1463@deffnx Command windowlist title [@var{title}] 1464(@kbd{C-a "})@* 1465Display all windows in a table for visual window selection. 1466The desired window can be selected via the standard 1467movement keys (@pxref{Movement}) and activated via 1468the return key. If the @code{-b} option is given, screen will 1469switch to the blank window before presenting the list, so 1470that the current window is also selectable. 1471The @code{-m} option changes the order of the windows, instead of 1472sorting by window numbers screen uses its internal most-recently-used 1473list. 1474 1475The table format can be changed with the string and title 1476option, the title is displayed as table heading, while the 1477lines are made by using the string setting. The default 1478setting is @samp{Num Name%=Flags} for the title and 1479@samp{%3n %t%=%f} for the lines. See the string escapes chapter 1480(@pxref{String Escapes}) for more codes (e.g. color settings). 1481 1482@end deffn 1483 1484@node Session Management, Regions, Selecting, Top 1485@chapter Session Management Commands 1486 1487Perhaps the most useful feature of @code{screen} is the way it allows 1488the user to move a session between terminals, by detaching and 1489reattaching. This also makes life easier for modem users who have to 1490deal with unexpected loss of carrier. 1491 1492@menu 1493* Detach:: Disconnect @code{screen} from your terminal. 1494* Power Detach:: Detach and log out. 1495* Lock:: Lock your terminal temporarily. 1496* Multiuser Session:: Changing number of allowed users. 1497* Session Name:: Rename your session for later reattachment. 1498* Suspend:: Suspend your session. 1499* Quit:: Terminate your session. 1500@end menu 1501 1502@node Detach, Power Detach, , Session Management 1503@section Detach 1504 1505@deffn Command autodetach state 1506(none)@* 1507Sets whether @code{screen} will automatically detach upon hangup, which 1508saves all your running programs until they are resumed with a 1509@code{screen -r} command. When turned off, a hangup signal will 1510terminate @code{screen} and all the processes it contains. Autodetach is 1511on by default. 1512@end deffn 1513 1514@kindex d 1515@kindex C-d 1516@deffn Command detach 1517(@kbd{C-a d}, @kbd{C-a C-d})@* 1518Detach the @code{screen} session (disconnect it from the terminal and 1519put it into the background). A detached @code{screen} can be resumed by 1520invoking @code{screen} with the @code{-r} option (@pxref{Invoking 1521Screen}). 1522The @code{-h} option tells screen to immediately close the connection 1523to the terminal (@samp{hangup}). 1524@end deffn 1525 1526@deffn Command password [crypted_pw] 1527(none)@* 1528Present a crypted password in your @file{.screenrc} file and screen will 1529ask for it, whenever someone attempts to resume a detached session. This 1530is useful, if you have privileged programs running under @code{screen} 1531and you want to protect your session from reattach attempts by users 1532that managed to assume your uid. (I.e. any superuser.) If no crypted 1533password is specified, screen prompts twice a password and places its 1534encryption in the paste buffer. Default is `none', which disables 1535password checking. 1536@end deffn 1537 1538@node Power Detach, Lock, Detach, Session Management 1539@section Power Detach 1540 1541@kindex D 1542@deffn Command pow_detach 1543(@kbd{C-a D D})@* 1544Mainly the same as @code{detach}, but also sends a HANGUP signal 1545to the parent process of @code{screen}.@* 1546@emph{Caution}: This will result in a 1547logout if @code{screen} was started from your login shell. 1548@end deffn 1549 1550@deffn Command pow_detach_msg [message] 1551(none)@* 1552The @var{message} specified here is output whenever a power detach is 1553performed. It may be used as a replacement for a logout message or to reset 1554baud rate, etc. 1555Without parameter, the current message is shown. 1556@end deffn 1557 1558@node Lock, Multiuser Session, Power Detach, Session Management 1559@section Lock 1560@kindex x 1561@kindex C-x 1562@deffn Command lockscreen 1563(@kbd{C-a x}, @kbd{C-a C-x})@* 1564Call a screenlock program (@file{/local/bin/lck} or @file{/usr/bin/lock} 1565or a builtin, if no other is available). Screen does not accept any 1566command keys until this program terminates. Meanwhile processes in the 1567windows may continue, as the windows are in the detached state. 1568The screenlock program may be changed through the environment variable 1569@code{$LOCKPRG} (which must be set in the shell from which @code{screen} 1570is started) and is executed with the user's uid and gid. 1571 1572Warning: When you leave other shells unlocked and have no password set 1573on @code{screen}, the lock is void: One could easily re-attach from an 1574unlocked shell. This feature should rather be called 1575@code{lockterminal}. 1576@end deffn 1577 1578@node Multiuser Session, Session Name, Lock, Session Management 1579@section Multiuser Session 1580@cindex multiuser session 1581 1582These commands allow other users to gain access to one single @code{screen} 1583session. When attaching to a multiuser @code{screen} the sessionname is 1584specified as @code{username/sessionname} to the @code{-S} command line option. 1585@code{Screen} must be compiled with multiuser support to enable features 1586described here. 1587 1588@menu 1589* Multiuser:: Enable / Disable multiuser mode. 1590* Acladd:: Enable a specific user. 1591* Aclchg:: Change a users permissions. 1592* Acldel:: Disable a specific user. 1593* Aclgrp:: Grant a user permissions to other users. 1594* Displays:: List all active users at their displays. 1595* Umask:: Predefine access to new windows. 1596* Wall:: Write a message to all users. 1597* Writelock:: Grant exclusive window access. 1598* Su:: Substitute user. 1599@end menu 1600 1601@node Multiuser, Acladd, , Multiuser Session 1602@subsection Multiuser 1603@deffn Command multiuser @var{state} 1604(none)@* 1605Switch between single-user and multi-user mode. Standard screen operation is 1606single-user. In multi-user mode the commands @code{acladd}, @code{aclchg} and 1607@code{acldel} can be used to enable (and disable) other users accessing this 1608@code{screen}. 1609@end deffn 1610 1611@node Acladd, Aclchg, Multiuser, Multiuser Session 1612@subsection Acladd 1613@deffn Command acladd @var{usernames} 1614@deffnx Command addacl @var{usernames} 1615(none)@* 1616Enable users to fully access this screen session. @var{Usernames} can be one 1617user or a comma separated list of users. This command enables to attach to 1618the @code{screen} session and performs the equivalent of 1619@code{aclchg @var{usernames} +rwx "#?"}. To add a user with restricted access, 1620use the @code{aclchg} command below. 1621@code{Addacl} is a synonym to @code{acladd}. 1622Multi-user mode only. 1623@end deffn 1624 1625@node Aclchg, Acldel, Acladd, Multiuser Session 1626@subsection Aclchg 1627@deffn Command aclchg @var{usernames permbits list} 1628@deffnx Command chacl @var{usernames permbits list} 1629(none)@* 1630Change permissions for a comma separated list of users. 1631Permission bits are represented as @samp{r}, @samp{w} and @samp{x}. 1632Prefixing @samp{+} grants the permission, @samp{-} removes it. The third 1633parameter is a comma separated list of commands or windows (specified either 1634by number or title). The special list @samp{#} refers to all windows, @samp{?} 1635to all commands. If @var{usernames} consists of a single @samp{*}, all 1636known users are affected. 1637A command can be executed when the user has the @samp{x} bit for it. The user 1638can type input to a window when he has its @samp{w} bit set and no other 1639user obtains a writelock for this window. Other bits are currently ignored. 1640To withdraw the writelock from another user in e.g. window 2: 1641@samp{aclchg @var{username} -w+w 2}. To allow read-only access 1642to the session: @samp{aclchg @var{username} -w "#"}. As soon as a user's name 1643is known to screen, he can attach to the session and (per default) has full 1644permissions for all command and windows. Execution permission for the acl 1645commands, @code{at} and others should also be removed or the user may be able 1646to regain write permission. 1647@code{Chacl} is a synonym to @code{aclchg}. 1648Multi-user mode only. 1649@end deffn 1650 1651@node Acldel, Aclgrp, Aclchg, Multiuser Session 1652@subsection Acldel 1653@deffn Command acldel @var{username} 1654(none)@* 1655Remove a user from screen's access control list. If currently attached, all the 1656user's displays are detached from the session. He cannot attach again. 1657Multi-user mode only. 1658@end deffn 1659 1660@node Aclgrp, Displays, Acldel, Multiuser Session 1661@subsection Aclgrp 1662@deffn Command aclgrp @var{username} [@var{groupname}] 1663(none)@* 1664Creates groups of users that share common access rights. The 1665name of the group is the username of the group leader. Each 1666member of the group inherits the permissions that are 1667granted to the group leader. That means, if a user fails an 1668access check, another check is made for the group leader. 1669A user is removed from all groups the special value @samp{none} 1670is used for @var{groupname}. If the second parameter is omitted 1671all groups the user is in are listed. 1672@end deffn 1673 1674@node Displays, Umask, Aclgrp, Multiuser Session 1675@subsection Displays 1676@kindex * 1677@deffn Command displays 1678(@kbd{C-a *})@* 1679Shows a tabular listing of all currently connected user 1680front-ends (displays). This is most useful for multiuser 1681sessions. 1682@end deffn 1683 1684@node Umask, Wall, Displays, Multiuser Session 1685@subsection aclumask 1686@deffn Command aclumask [@var{users}]+/-@var{bits} ... 1687@deffnx Command umask [@var{users}]+/-@var{bits} ... 1688(none)@* 1689This specifies the access other users have to windows that 1690will be created by the caller of the command. @var{Users} may be no, 1691one or a comma separated list of known usernames. If no users are 1692specified, a list of all currently known users is assumed. 1693@var{Bits} is any combination of access control bits allowed 1694defined with the @code{aclchg} command. The special username @samp{?} 1695predefines the access that not yet known users will be 1696granted to any window initially. The special username @samp{??} 1697predefines the access that not yet known users are granted 1698to any command. Rights of the special username nobody cannot 1699be changed (see the @code{su} command). 1700@code{Umask} is a synonym to @code{aclumask}. 1701@end deffn 1702 1703 1704@node Wall, Writelock, Umask, Multiuser Session 1705@subsection Wall 1706@deffn Command wall @var{message} 1707(none)@* 1708Write a message to all displays. The message will appear in the terminal's 1709status line. 1710@end deffn 1711 1712@node Writelock, Su , Wall, Multiuser Session 1713@subsection Writelock 1714@deffn Command writelock @var{on|off|auto} 1715(none)@* 1716In addition to access control lists, not all users may be able to write to 1717the same window at once. Per default, writelock is in @samp{auto} mode and 1718grants exclusive input permission to the user who is the first to switch 1719to the particular window. When he leaves the window, other users may obtain 1720the writelock (automatically). The writelock of the current window is disabled 1721by the command @code{writelock off}. If the user issues the command 1722@code{writelock on} he keeps the exclusive write permission while switching 1723to other windows. 1724@end deffn 1725 1726@deffn Command defwritelock @var{on|off|auto} 1727(none)@* 1728Sets the default writelock behavior for new windows. Initially all windows 1729will be created with no writelocks. 1730@end deffn 1731 1732@node Su, , Writelock, Multiuser Session 1733@subsection Su 1734@deffn Command su [@var{username} [@var{password} [@var{password2}]]] 1735(none)@* 1736Substitute the user of a display. The command prompts for 1737all parameters that are omitted. If passwords are specified 1738as parameters, they have to be specified un-crypted. The 1739first password is matched against the systems passwd database, 1740the second password is matched against the @code{screen} 1741password as set with the commands @code{acladd} or @code{password}. 1742@code{Su} may be useful for the @code{screen} administrator to test 1743multiuser setups. 1744When the identification fails, the user has 1745access to the commands available for user @samp{nobody}. These are 1746@code{detach}, @code{license}, @code{version}, @code{help} and 1747@code{displays}. 1748@end deffn 1749 1750@node Session Name, Suspend, Multiuser Session, Session Management 1751@section Session Name 1752@deffn Command sessionname [@var{name}] 1753(none)@* 1754Rename the current session. Note that for @code{screen -list} the name 1755shows up with the process-id prepended. If the argument @var{name} is 1756omitted, the name of this session is displayed.@* 1757@emph{Caution}: The @code{$STY} 1758environment variable still reflects the old name. This may result in 1759confusion. The default is constructed from the tty and host names. 1760@end deffn 1761 1762@node Suspend, Quit, Session Name, Session Management 1763@section Suspend 1764@kindex z 1765@kindex C-z 1766@deffn Command suspend 1767(@kbd{C-a z}, @kbd{C-a C-z})@* 1768Suspend @code{screen}. The windows are in the detached state while 1769@code{screen} is suspended. This feature relies on the parent shell 1770being able to do job control. 1771@end deffn 1772 1773@node Quit, , Suspend, Session Management 1774@section Quit 1775@kindex C-\ 1776@deffn Command quit 1777(@kbd{C-a C-\})@* 1778Kill all windows and terminate @code{screen}. Note that on VT100-style 1779terminals the keys @kbd{C-4} and @kbd{C-\} are identical. So be careful 1780not to type @kbd{C-a C-4} when selecting window no. 4. Use the empty 1781bind command (as in @code{bind "^\"}) to remove a key binding 1782(@pxref{Key Binding}). 1783@end deffn 1784 1785@node Regions, Window Settings, Session Management, Top 1786@chapter Regions 1787@cindex regions 1788Screen has the ability to display more than one window on the 1789user's display. This is done by splitting the screen in regions, 1790which can contain different windows. 1791 1792@menu 1793* Split:: Split a region into two 1794* Focus:: Change to the next region 1795* Only:: Delete all other regions 1796* Remove:: Delete the current region 1797* Resize:: Grow or shrink a region 1798* Caption:: Control the window's caption 1799* Fit:: Resize a window to fit the region 1800@end menu 1801 1802@node Split, Focus, , Regions 1803@section Split 1804@kindex S 1805@deffn Command split 1806(@kbd{C-a S})@* 1807Split the current region into two new ones. All regions on the 1808display are resized to make room for the new region. The blank 1809window is displayed on the new region. 1810@end deffn 1811 1812@node Focus, Only, Split, Regions 1813@section Focus 1814@kindex TAB 1815@deffn Command focus 1816(@kbd{C-a @key{Tab}})@* 1817Move the input focus to the next region. This is done in a cyclic 1818way so that the top region is selected after the bottom one. If 1819no subcommand is given it defaults to `down'. `up' cycles in the 1820opposite order, `top' and `bottom' go to the top and bottom 1821region respectively. Useful bindings are (j and k as in vi) 1822@example 1823bind j focus down 1824bind k focus up 1825bind t focus top 1826bind b focus bottom 1827@end example 1828@end deffn 1829 1830@node Only, Remove, Focus, Regions 1831@section Only 1832@kindex Q 1833@deffn Command only 1834(@kbd{C-a Q})@* 1835Kill all regions but the current one. 1836@end deffn 1837 1838@node Remove, Resize, Only, Regions 1839@section Remove 1840@kindex X 1841@deffn Command remove 1842(@kbd{C-a X})@* 1843Kill the current region. This is a no-op if there is only one region. 1844@end deffn 1845 1846@node Resize, Caption, Remove, Regions 1847@section Resize 1848@deffn Command resize [(+/-)@var{lines}] 1849(none)@* 1850Resize the current region. The space will be removed from or added to 1851the region below or if there's not enough space from the region above. 1852@example 1853resize +N increase current region height by N 1854resize -N decrease current region height by N 1855resize N set current region height to N 1856resize = make all windows equally high 1857resize max maximize current region height 1858resize min minimize current region height 1859@end example 1860@end deffn 1861 1862@node Caption, Fit, Resize, Regions 1863@section Caption 1864@deffn Command caption @code{always}|@code{splitonly} [string] 1865@deffnx Command caption @code{string} [string] 1866(none)@* 1867This command controls the display of the window captions. Normally 1868a caption is only used if more than one window is shown on the 1869display (split screen mode). But if the type is set to 1870@code{always}, @code{screen} shows a caption 1871even if only one window is displayed. The default 1872is @samp{splitonly}. 1873 1874The second form changes the text used for the caption. You can use 1875all string escapes (@pxref{String Escapes}). @code{Screen} uses 1876a default of @samp{%3n %t}. 1877 1878You can mix both forms by providing the string as an additional 1879argument. 1880@end deffn 1881 1882@node Fit, , Caption, Regions 1883@section Fit 1884@kindex F 1885@deffn Command fit 1886(@kbd{C-a F})@* 1887Change the window size to the size of the current region. This 1888command is needed because screen doesn't adapt the window size 1889automatically if the window is displayed more than once. 1890@end deffn 1891 1892@node Window Settings, Virtual Terminal, Regions, Top 1893@chapter Window Settings 1894 1895These commands control the way @code{screen} treats individual windows 1896in a session. @xref{Virtual Terminal}, for commands to control the 1897terminal emulation itself. 1898 1899@menu 1900* Naming Windows:: Control the name of the window 1901* Console:: See the host's console messages 1902* Kill:: Destroy an unwanted window 1903* Login:: Control @file{/etc/utmp} logging 1904* Mode:: Control the file mode of the pty 1905* Monitor:: Watch for activity in a window 1906* Windows:: List the active windows 1907* Hardstatus:: Set a window's hardstatus line 1908@end menu 1909 1910@node Naming Windows, Console, , Window Settings 1911@section Naming Windows (Titles) 1912@cindex title 1913 1914You can customize each window's name in the window display (viewed with 1915the @code{windows} command (@pxref{Windows}) by setting it with 1916one of the title commands. Normally the name displayed is the actual 1917command name of the program created in the window. However, it is 1918sometimes useful to distinguish various programs of the same name or to 1919change the name on-the-fly to reflect the current state of the window. 1920 1921The default name for all shell windows can be set with the 1922@code{shelltitle} command (@pxref{Shell}). You can specify the name you 1923want for a window with the @samp{-t} option to the @code{screen} command 1924when the window is created (@pxref{Screen Command}). To change the name after 1925the window has been created you can use the title-string escape-sequence 1926(@kbd{@key{ESC} k @var{name} @key{ESC} \}) and the @code{title} command 1927(C-a A). The former can be output from an application to control the 1928window's name under software control, and the latter will prompt for a 1929name when typed. You can also bind predefined names to keys with the 1930@code{title} command to set things quickly without prompting. 1931 1932@menu 1933* Title Command:: The @code{title} command. 1934* Dynamic Titles:: Make shell windows change titles dynamically. 1935* Title Prompts:: Set up your shell prompt for dynamic Titles. 1936* Title Screenrc:: Set up Titles in your @file{.screenrc}. 1937@end menu 1938 1939@node Title Command, Dynamic Titles, , Naming Windows 1940@subsection Title Command 1941@kindex A 1942@deffn Command title [windowtitle] 1943(@kbd{C-a A})@* 1944Set the name of the current window to @var{windowtitle}. If no name is 1945specified, screen prompts for one. 1946@end deffn 1947 1948@node Dynamic Titles, Title Prompts, Title Command, Naming Windows 1949@subsection Dynamic Titles 1950@code{screen} has a shell-specific heuristic that is enabled by 1951setting the window's name to @var{search|name} and arranging to have a 1952null title escape-sequence output as a part of your prompt. The 1953@var{search} portion specifies an end-of-prompt search string, while the 1954@var{name} portion specifies the default shell name for the window. If 1955the @var{name} ends in a @samp{:} @code{screen} will add what it 1956believes to be the current command running in the window to the end of 1957the specified name (e.g. @var{name:cmd}). Otherwise the current 1958command name supersedes the shell name while it is running. 1959 1960Here's how it works: you must modify your shell prompt to output a null 1961title-escape-sequence (@key{ESC} k @key{ESC} \) as a part of your prompt. 1962The last part of your prompt must be the same as the string you 1963specified for the @var{search} portion of the title. Once this is set 1964up, @code{screen} will use the title-escape-sequence to clear the previous 1965command name and get ready for the next command. Then, when a newline 1966is received from the shell, a search is made for the end of the prompt. 1967If found, it will grab the first word after the matched string and use 1968it as the command name. If the command name begins with @samp{!}, 1969@samp{%}, or @samp{^}, @code{screen} will use the first word on the 1970following line (if found) in preference to the just-found name. This 1971helps csh users get more accurate titles when using job control or 1972history recall commands. 1973 1974@node Title Prompts, Title Screenrc, Dynamic Titles, Naming Windows 1975@subsection Setting up your prompt for shell titles 1976One thing to keep in mind when adding a null title-escape-sequence to your 1977prompt is that some shells (like the csh) count all the non-control 1978characters as part of the prompt's length. If these invisible 1979characters aren't a multiple of 8 then backspacing over a tab will 1980result in an incorrect display. One way to get around this is to use a 1981prompt like this: 1982 1983@example 1984set prompt='@value{esc}[0000m@value{esc}k@value{esc}\% ' 1985@end example 1986 1987The escape-sequence @samp{@value{esc}[0000m} not only normalizes the 1988character attributes, but all the zeros round the length of the 1989invisible characters up to 8. 1990 1991Tcsh handles escape codes in the prompt more intelligently, so you can 1992specify your prompt like this: 1993 1994@example 1995set prompt="%@{\ek\e\\%@}\% " 1996@end example 1997 1998Bash users will probably want to echo the escape sequence in the 1999PROMPT_COMMAND: 2000 2001@example 2002PROMPT_COMMAND='echo -n -e "\033k\033\134"' 2003@end example 2004 2005(I used @samp{\134} to output a @samp{\} because of a bug in v1.04). 2006 2007@node Title Screenrc, , Title Prompts, Naming Windows 2008@subsection Setting up shell titles in your @file{.screenrc} 2009Here are some .screenrc examples: 2010 2011@example 2012screen -t top 2 nice top 2013@end example 2014 2015Adding this line to your .screenrc would start a niced version of the 2016@code{top} command in window 2 named @samp{top} rather than @samp{nice}. 2017 2018@example 2019shelltitle '> |csh' 2020screen 1 2021@end example 2022 2023This file would start a shell using the given shelltitle. The title 2024specified is an auto-title that would expect the prompt and the typed 2025command to look something like the following: 2026 2027@example 2028/usr/joe/src/dir> trn 2029@end example 2030 2031(it looks after the '> ' for the command name). 2032The window status would show the name @samp{trn} while the command was 2033running, and revert to @samp{csh} upon completion. 2034 2035@example 2036bind R screen -t '% |root:' su 2037@end example 2038 2039Having this command in your .screenrc would bind the key sequence 2040@kbd{C-a R} to the @code{su} command and give it an auto-title name of 2041@samp{root:}. For this auto-title to work, the screen could look 2042something like this: 2043 2044@example 2045% !em 2046emacs file.c 2047@end example 2048 2049Here the user typed the csh history command @code{!em} which ran the 2050previously entered @code{emacs} command. The window status would show 2051@samp{root:emacs} during the execution of the command, and revert to 2052simply @samp{root:} at its completion. 2053 2054@example 2055bind o title 2056bind E title "" 2057bind u title (unknown) 2058@end example 2059 2060The first binding doesn't have any arguments, so it would prompt you for 2061a title when you type @kbd{C-a o}. The second binding would clear an 2062auto-titles current setting (C-a E). The third binding would set the 2063current window's title to @samp{(unknown)} (C-a u). 2064 2065@node Console, Kill, Naming Windows, Window Settings 2066@section Console 2067@deffn Command console [@var{state}] 2068(none)@* 2069Grabs or un-grabs the machines console output to a window. When the argument 2070is omitted the current state is displayed. 2071@emph{Note}: Only the owner of @file{/dev/console} can grab the console 2072output. This command is only available if the host supports the ioctl 2073@code{TIOCCONS}. 2074@end deffn 2075 2076@node Kill, Login, Console, Window Settings 2077@section Kill 2078 2079@kindex k 2080@kindex C-k 2081@deffn Command kill 2082(@kbd{C-a k}, @kbd{C-a C-k})@* 2083Kill the current window.@* 2084If there is an @code{exec} command running (@pxref{Exec}) then it is killed. 2085Otherwise the process (e.g. shell) running in the window receives a 2086@code{HANGUP} condition, 2087the window structure is removed and screen (your display) switches to another 2088window. When the last window is destroyed, @code{screen} exits. 2089After a kill screen switches to the previously displayed window. 2090@* 2091@emph{Caution}: @code{emacs} users may find themselves killing their 2092@code{emacs} session when trying to delete the current line. For this 2093reason, it is probably wise to use a different command character 2094(@pxref{Command Character}) or rebind @code{kill} to another key 2095sequence, such as @kbd{C-a K} (@pxref{Key Binding}). 2096@end deffn 2097 2098@node Login, Mode, Kill, Window Settings 2099@section Login 2100 2101@deffn Command deflogin state 2102(none)@* 2103Same as the @code{login} command except that the default setting for new 2104windows is changed. This defaults to `on' unless otherwise specified at 2105compile time (@pxref{Installation}). Both commands are only present when 2106@code{screen} has been compiled with utmp support. 2107@end deffn 2108 2109@kindex L 2110@deffn Command login [state] 2111(@kbd{C-a L})@* 2112Adds or removes the entry in @file{/etc/utmp} for the current window. 2113This controls whether or not the window is @dfn{logged in}. In addition 2114to this toggle, it is convenient to have ``log in'' and ``log out'' 2115keys. For instance, @code{bind I login on} and @code{bind O 2116login off} will map these keys to be @kbd{C-a I} and @kbd{C-a O} 2117(@pxref{Key Binding}). 2118@end deffn 2119 2120@node Mode, Monitor, Login, Window Settings 2121@section Mode 2122@deffn Command defmode mode 2123(none)@* 2124The mode of each newly allocated pseudo-tty is set to @var{mode}. 2125@var{mode} is an octal number as used by chmod(1). Defaults to 0622 for 2126windows which are logged in, 0600 for others (e.g. when @code{-ln} was 2127specified for creation, @pxref{Screen Command}). 2128@end deffn 2129 2130@node Monitor, Windows, Mode, Window Settings 2131@section Monitoring 2132 2133@deffn Command activity message 2134(none)@* 2135When any activity occurs in a background window that is being monitored, 2136@code{screen} displays a notification in the message line. The 2137notification message can be redefined by means of the @code{activity} 2138command. Each occurrence of @samp{%} in @var{message} is replaced by 2139the number of the window in which activity has occurred, and each 2140occurrence of @samp{^G} is replaced by the definition for bell in your 2141termcap (usually an audible bell). The default message is 2142 2143@example 2144'Activity in window %n' 2145@end example 2146 2147Note that monitoring is off for all windows by default, but can be altered 2148by use of the @code{monitor} command (@kbd{C-a M}). 2149@end deffn 2150 2151@deffn Command defmonitor state 2152(none)@* 2153Same as the @code{monitor} command except that the default setting for 2154new windows is changed. Initial setting is `off'. 2155@end deffn 2156 2157@kindex M 2158@deffn Command monitor [state] 2159(@kbd{C-a M})@* 2160Toggles monitoring of the current window. When monitoring is turned on 2161and the affected window is switched into the background, the activity 2162notification message will be displayed in the status line at the first 2163sign of output, and the window will also be marked with an @samp{@@} in 2164the window-status display (@pxref{Windows}). Monitoring defaults to 2165@samp{off} for all windows. 2166@end deffn 2167 2168@node Windows, Hardstatus, Monitor, Window Settings 2169@section Windows 2170@kindex w 2171@kindex C-w 2172@deffn Command windows 2173(@kbd{C-a w}, @kbd{C-a C-w})@* 2174Uses the message line to display a list of all the windows. Each 2175window is listed by number with the name of the program running in the 2176window (or its title). 2177 2178The current window is marked with a @samp{*}; 2179the previous window is marked with a @samp{-}; 2180all the windows that are logged in are marked with a @samp{$} (@pxref{Login}); 2181a background window that has received a bell is marked with a @samp{!}; 2182a background window that is being monitored and has had activity occur is 2183marked with an @samp{@@} (@pxref{Monitor}); 2184a window which has output logging turned on is marked with @samp{(L)}; 2185windows occupied by other users are marked with @samp{&} 2186or @samp{&&} if the window is shared by other users; 2187windows in the zombie state are marked with @samp{Z}. 2188 2189If this list is too long to fit on the terminal's status line only the 2190portion around the current window is displayed. 2191@end deffn 2192 2193@node Hardstatus, , Windows, Window Settings 2194@section Hardstatus 2195 2196@code{Screen} maintains a hardstatus line for every window. If a window 2197gets selected, the display's hardstatus will be updated to match 2198the window's hardstatus line. 2199The hardstatus line can be changed with the ANSI Application 2200Program Command (APC): @samp{ESC_<string>ESC\}. As a convenience 2201for xterm users the sequence @samp{ESC]0..2;<string>^G} is 2202also accepted. 2203 2204@deffn Command defhstatus [status] 2205(none)@* 2206The hardstatus line that all new windows will get is set to 2207@var{status}. 2208This command is useful to make the hardstatus of every window 2209display the window number or title or the like. @var{status} 2210may contain the same directives as in the window messages, but 2211the directive escape character is @samp{^E} (octal 005) instead 2212of @samp{%}. This was done to make a misinterpretation of program 2213generated hardstatus lines impossible. 2214If the parameter @var{status} 2215is omitted, the current default string is displayed. 2216Per default the hardstatus line of new windows is empty. 2217@end deffn 2218 2219@deffn Command hstatus status 2220(none)@* 2221Changes the current window's hardstatus line to @var{status}. 2222@end deffn 2223 2224@node Virtual Terminal, Copy and Paste, Window Settings, Top 2225@chapter Virtual Terminal 2226 2227Each window in a @code{screen} session emulates a VT100 terminal, with 2228some extra functions added. The VT100 emulator is hard-coded, no other 2229terminal types can be emulated. 2230The commands described here modify the terminal emulation. 2231 2232@menu 2233* Control Sequences:: Details of the internal VT100 emulation. 2234* Input Translation:: How keystrokes are remapped. 2235* Digraph:: Entering digraph sequences. 2236* Bell:: Getting your attention. 2237* Clear:: Clear the window display. 2238* Info:: Terminal emulation statistics. 2239* Redisplay:: When the display gets confusing. 2240* Wrap:: Automatic margins. 2241* Reset:: Recovering from ill-behaved applications. 2242* Window Size:: Changing the size of your terminal. 2243* Character Processing:: Change the effect of special characters. 2244@end menu 2245 2246@node Control Sequences, Input Translation, , Virtual Terminal 2247@section Control Sequences 2248@cindex control sequences 2249The following is a list of control sequences recognized by 2250@code{screen}. @samp{(V)} and @samp{(A)} indicate VT100-specific and 2251ANSI- or ISO-specific functions, respectively. 2252 2253@example 2254ESC E Next Line 2255ESC D Index 2256ESC M Reverse Index 2257ESC H Horizontal Tab Set 2258ESC Z Send VT100 Identification String 2259ESC 7 (V) Save Cursor and Attributes 2260ESC 8 (V) Restore Cursor and Attributes 2261ESC [s (A) Save Cursor and Attributes 2262ESC [u (A) Restore Cursor and Attributes 2263ESC c Reset to Initial State 2264ESC g Visual Bell 2265ESC Pn p Cursor Visibility (97801) 2266 Pn = 6 Invisible 2267 7 Visible 2268ESC = (V) Application Keypad Mode 2269ESC > (V) Numeric Keypad Mode 2270ESC # 8 (V) Fill Screen with E's 2271ESC \ (A) String Terminator 2272ESC ^ (A) Privacy Message String (Message Line) 2273ESC ! Global Message String (Message Line) 2274ESC k Title Definition String 2275ESC P (A) Device Control String 2276 Outputs a string directly to the host 2277 terminal without interpretation. 2278ESC _ (A) Application Program Command (Hardstatus) 2279ESC ] 0 ; string ^G (A) Operating System Command (Hardstatus, xterm 2280 title hack) 2281ESC ] 83 ; cmd ^G (A) Execute screen command. This only works if 2282 multi-user support is compiled into screen. 2283 The pseudo-user ":window:" is used to check 2284 the access control list. Use "addacl :window: 2285 -rwx #?" to create a user with no rights and 2286 allow only the needed commands. 2287Control-N (A) Lock Shift G1 (SO) 2288Control-O (A) Lock Shift G0 (SI) 2289ESC n (A) Lock Shift G2 2290ESC o (A) Lock Shift G3 2291ESC N (A) Single Shift G2 2292ESC O (A) Single Shift G3 2293ESC ( Pcs (A) Designate character set as G0 2294ESC ) Pcs (A) Designate character set as G1 2295ESC * Pcs (A) Designate character set as G2 2296ESC + Pcs (A) Designate character set as G3 2297ESC [ Pn ; Pn H Direct Cursor Addressing 2298ESC [ Pn ; Pn f same as above 2299ESC [ Pn J Erase in Display 2300 Pn = None or 0 From Cursor to End of Screen 2301 1 From Beginning of Screen to Cursor 2302 2 Entire Screen 2303ESC [ Pn K Erase in Line 2304 Pn = None or 0 From Cursor to End of Line 2305 1 From Beginning of Line to Cursor 2306 2 Entire Line 2307ESC [ Pn X Erase character 2308ESC [ Pn A Cursor Up 2309ESC [ Pn B Cursor Down 2310ESC [ Pn C Cursor Right 2311ESC [ Pn D Cursor Left 2312ESC [ Pn E Cursor next line 2313ESC [ Pn F Cursor previous line 2314ESC [ Pn G Cursor horizontal position 2315ESC [ Pn ` same as above 2316ESC [ Pn d Cursor vertical position 2317ESC [ Ps ;...; Ps m Select Graphic Rendition 2318 Ps = None or 0 Default Rendition 2319 1 Bold 2320 2 (A) Faint 2321 3 (A) @i{Standout} Mode (ANSI: Italicized) 2322 4 Underlined 2323 5 Blinking 2324 7 Negative Image 2325 22 (A) Normal Intensity 2326 23 (A) @i{Standout} Mode off (ANSI: Italicized off) 2327 24 (A) Not Underlined 2328 25 (A) Not Blinking 2329 27 (A) Positive Image 2330 30 (A) Foreground Black 2331 31 (A) Foreground Red 2332 32 (A) Foreground Green 2333 33 (A) Foreground Yellow 2334 34 (A) Foreground Blue 2335 35 (A) Foreground Magenta 2336 36 (A) Foreground Cyan 2337 37 (A) Foreground White 2338 39 (A) Foreground Default 2339 40 (A) Background Black 2340 ... ... 2341 49 (A) Background Default 2342ESC [ Pn g Tab Clear 2343 Pn = None or 0 Clear Tab at Current Position 2344 3 Clear All Tabs 2345ESC [ Pn ; Pn r (V) Set Scrolling Region 2346ESC [ Pn I (A) Horizontal Tab 2347ESC [ Pn Z (A) Backward Tab 2348ESC [ Pn L (A) Insert Line 2349ESC [ Pn M (A) Delete Line 2350ESC [ Pn @@ (A) Insert Character 2351ESC [ Pn P (A) Delete Character 2352ESC [ Pn S Scroll Scrolling Region Up 2353ESC [ Pn T Scroll Scrolling Region Down 2354ESC [ Pn ^ same as above 2355ESC [ Ps ;...; Ps h Set Mode 2356ESC [ Ps ;...; Ps l Reset Mode 2357 Ps = 4 (A) Insert Mode 2358 20 (A) @samp{Automatic Linefeed} Mode. 2359 34 Normal Cursor Visibility 2360 ?1 (V) Application Cursor Keys 2361 ?3 (V) Change Terminal Width to 132 columns 2362 ?5 (V) Reverse Video 2363 ?6 (V) @samp{Origin} Mode 2364 ?7 (V) @samp{Wrap} Mode 2365 ?9 X10 mouse tracking 2366 ?25 (V) Visible Cursor 2367 ?47 Alternate Screen (old xterm code) 2368 ?1000 (V) VT200 mouse tracking 2369 ?1047 Alternate Screen (new xterm code) 2370 ?1049 Alternate Screen (new xterm code) 2371ESC [ 5 i (A) Start relay to printer (ANSI Media Copy) 2372ESC [ 4 i (A) Stop relay to printer (ANSI Media Copy) 2373ESC [ 8 ; Ph ; Pw t Resize the window to @samp{Ph} lines and 2374 @samp{Pw} columns (SunView special) 2375ESC [ c Send VT100 Identification String 2376ESC [ x (V) Send Terminal Parameter Report 2377ESC [ > c Send Secondary Device Attributes String 2378ESC [ 6 n Send Cursor Position Report 2379 2380@end example 2381 2382 2383@node Input Translation, Digraph, Control Sequences, Virtual Terminal 2384@section Input Translation 2385@cindex input translation 2386In order to do a full VT100 emulation @code{screen} has to detect 2387that a sequence of characters in the input stream was generated 2388by a keypress on the user's keyboard and insert the VT100 2389style escape sequence. @code{Screen} has a very flexible way of doing 2390this by making it possible to map arbitrary commands on arbitrary 2391sequences of characters. For standard VT100 emulation the command 2392will always insert a string in the input buffer of the window 2393(see also command @code{stuff}, @pxref{Paste}). 2394Because the sequences generated by a keypress can 2395change after a reattach from a different terminal type, it is 2396possible to bind commands to the termcap name of the keys. 2397@code{Screen} will insert the correct binding after each 2398reattach. See @ref{Bindkey} for further details on the syntax and examples. 2399 2400Here is the table of the default key bindings. (A) means that the 2401command is executed if the keyboard is switched into application 2402mode. 2403@example 2404 2405Key name Termcap name Command 2406----------------------------------------------------- 2407Cursor up ku stuff \033[A 2408 stuff \033OA (A) 2409Cursor down kd stuff \033[B 2410 stuff \033OB (A) 2411Cursor right kr stuff \033[C 2412 stuff \033OC (A) 2413Cursor left kl stuff \033[D 2414 stuff \033OD (A) 2415Function key 0 k0 stuff \033[10~ 2416Function key 1 k1 stuff \033OP 2417Function key 2 k2 stuff \033OQ 2418Function key 3 k3 stuff \033OR 2419Function key 4 k4 stuff \033OS 2420Function key 5 k5 stuff \033[15~ 2421Function key 6 k6 stuff \033[17~ 2422Function key 7 k7 stuff \033[18~ 2423Function key 8 k8 stuff \033[19~ 2424Function key 9 k9 stuff \033[20~ 2425Function key 10 k; stuff \033[21~ 2426Function key 11 F1 stuff \033[23~ 2427Function key 12 F2 stuff \033[24~ 2428Home kh stuff \033[1~ 2429End kH stuff \033[4~ 2430Insert kI stuff \033[2~ 2431Delete kD stuff \033[3~ 2432Page up kP stuff \033[5~ 2433Page down kN stuff \033[6~ 2434Keypad 0 f0 stuff 0 2435 stuff \033Op (A) 2436Keypad 1 f1 stuff 1 2437 stuff \033Oq (A) 2438Keypad 2 f2 stuff 2 2439 stuff \033Or (A) 2440Keypad 3 f3 stuff 3 2441 stuff \033Os (A) 2442Keypad 4 f4 stuff 4 2443 stuff \033Ot (A) 2444Keypad 5 f5 stuff 5 2445 stuff \033Ou (A) 2446Keypad 6 f6 stuff 6 2447 stuff \033Ov (A) 2448Keypad 7 f7 stuff 7 2449 stuff \033Ow (A) 2450Keypad 8 f8 stuff 8 2451 stuff \033Ox (A) 2452Keypad 9 f9 stuff 9 2453 stuff \033Oy (A) 2454Keypad + f+ stuff + 2455 stuff \033Ok (A) 2456Keypad - f- stuff - 2457 stuff \033Om (A) 2458Keypad * f* stuff * 2459 stuff \033Oj (A) 2460Keypad / f/ stuff / 2461 stuff \033Oo (A) 2462Keypad = fq stuff = 2463 stuff \033OX (A) 2464Keypad . f. stuff . 2465 stuff \033On (A) 2466Keypad , f, stuff , 2467 stuff \033Ol (A) 2468Keypad enter fe stuff \015 2469 stuff \033OM (A) 2470@end example 2471 2472@node Digraph, Bell, Input Translation, Virtual Terminal 2473@section Digraph 2474 2475@kindex C-v 2476@deffn Command digraph [preset] 2477(none)@* 2478This command prompts the user for a digraph sequence. The next 2479two characters typed are looked up in a builtin table and the 2480resulting character is inserted in the input stream. For example, 2481if the user enters @samp{a"}, an a-umlaut will be inserted. If the 2482first character entered is a 0 (zero), @code{screen} 2483will treat the following characters (up to three) as an octal 2484number instead. The optional argument @var{preset} 2485is treated as user input, thus one can create an "umlaut" key. 2486For example the command @samp{bindkey ^K digraph '"'} enables the user 2487to generate an a-umlaut by typing @samp{CTRL-K a}. 2488@end deffn 2489 2490@node Bell, Clear, Digraph, Virtual Terminal 2491@section Bell 2492 2493@deffn Command bell_msg [message] 2494(none)@* 2495When a bell character is sent to a background window, @code{screen} 2496displays a notification in the message line. The notification message 2497can be re-defined by this command. Each occurrence 2498of @samp{%} in @var{message} is replaced by the number of the window to 2499which a bell has been sent, and each occurrence of @samp{^G} is replaced 2500by the definition for bell in your termcap (usually an audible bell). 2501The default message is 2502 2503@example 2504'Bell in window %n' 2505@end example 2506 2507An empty message can be supplied to the @code{bell_msg} command to suppress 2508output of a message line (@code{bell_msg ""}). 2509Without parameter, the current message is shown. 2510@end deffn 2511 2512@kindex C-g 2513@deffn Command vbell [state] 2514(@kbd{C-a C-g})@* 2515Sets or toggles the visual bell setting for the current window. If 2516@code{vbell} is switched to @samp{on}, but your 2517terminal does not support a visual bell, the visual bell message is 2518displayed in the status line when the bell character is received. 2519Visual bell support of a terminal is 2520defined by the termcap variable @code{vb}. @xref{Bell, , Visual Bell, 2521termcap, The Termcap Manual}, for more information on visual bells. 2522The equivalent terminfo capability is @code{flash}. 2523 2524Per default, @code{vbell} is @samp{off}, thus the audible bell is used. 2525@end deffn 2526 2527@deffn Command vbell_msg [message] 2528(none)@* 2529Sets the visual bell message. @var{Message} is printed to the status 2530line if the window receives a bell character (^G), @code{vbell} is 2531set to @samp{on} and the terminal does not support a visual bell. 2532The default message is @samp{Wuff, Wuff!!}. 2533Without parameter, the current message is shown. 2534@end deffn 2535 2536@deffn Command vbellwait sec 2537(none)@* 2538Define a delay in seconds after each display of @code{screen} 's visual 2539bell message. The default is 1 second. 2540@end deffn 2541 2542@node Clear, Info, Bell, Virtual Terminal 2543@section Clear 2544@kindex C 2545@deffn Command clear 2546(@kbd{C-a C})@* 2547Clears the screen and saves its contents to the scrollback buffer. 2548@end deffn 2549 2550@node Info, Redisplay, Clear, Virtual Terminal 2551@section Info 2552@kindex i 2553@kindex C-i 2554@deffn Command info 2555(@kbd{C-a i}, @kbd{C-a C-i})@* 2556Uses the message line to display some information about the current 2557window: the cursor position in the form @samp{(@var{column},@var{row})} 2558starting with @samp{(1,1)}, the terminal width and height plus the size 2559of the scrollback buffer in lines, like in @samp{(80,24)+50}, 2560the current state of window XON/XOFF flow control is shown like this 2561(@pxref{Flow Control}): 2562@example 2563 +flow automatic flow control, currently on. 2564 -flow automatic flow control, currently off. 2565 +(+)flow flow control enabled. Agrees with automatic control. 2566 -(+)flow flow control disabled. Disagrees with automatic control. 2567 +(-)flow flow control enabled. Disagrees with automatic control. 2568 -(-)flow flow control disabled. Agrees with automatic control. 2569@end example 2570 2571The current line wrap setting (@samp{+wrap} indicates enabled, @samp{-wrap} 2572not) is also shown. The flags @samp{ins}, @samp{org}, @samp{app}, @samp{log}, 2573@samp{mon} and @samp{nored} are displayed when the window is in insert mode, 2574origin mode, application-keypad mode, has output logging, 2575activity monitoring or partial redraw enabled. 2576 2577The currently active 2578character set (@samp{G0}, @samp{G1}, @samp{G2}, or @samp{G3}), and in 2579square brackets the terminal character sets that are currently 2580designated as @samp{G0} through @samp{G3}. 2581If the window is in UTF-8 mode, the string @samp{UTF-8} is shown instead. 2582Additional modes depending on the type of the window are displayed at 2583the end of the status line (@pxref{Window Types}). 2584 2585If the state machine of the terminal emulator is in a non-default state, 2586the info line is started with a string identifying the current state. 2587 2588For system information use @code{time}. 2589@end deffn 2590 2591@deffn Command dinfo 2592(none)@* 2593Show what screen thinks about your terminal. Useful if you want to know 2594why features like color or the alternate charset don't work. 2595@end deffn 2596 2597@node Redisplay, Wrap, Info, Virtual Terminal 2598@section Redisplay 2599 2600@deffn Command allpartial state 2601(none)@* 2602If set to on, only the current cursor line is refreshed on window change. 2603This affects all windows and is useful for slow terminal lines. The 2604previous setting of full/partial refresh for each window is restored 2605with @code{allpartial off}. This is a global flag that immediately takes effect 2606on all windows overriding the @code{partial} settings. It does not change the 2607default redraw behavior of newly created windows. 2608@end deffn 2609 2610@deffn Command altscreen state 2611(none)@* 2612If set to on, "alternate screen" support is enabled in virtual terminals, 2613just like in xterm. Initial setting is @samp{off}. 2614@end deffn 2615 2616@deffn Command partial state 2617(none)@* 2618Defines whether the display should be refreshed (as with 2619@code{redisplay}) after switching to the current window. This command 2620only affects the current window. To immediately affect all windows use the 2621@code{allpartial} command. Default is @samp{off}, of course. This default is 2622fixed, as there is currently no @code{defpartial} command. 2623@end deffn 2624 2625@kindex l 2626@kindex C-l 2627@deffn Command redisplay 2628(@kbd{C-a l}, @kbd{C-a C-l})@* 2629Redisplay the current window. Needed to get a full redisplay in 2630partial redraw mode. 2631@end deffn 2632 2633@node Wrap, Reset, Redisplay, Virtual Terminal 2634@section Wrap 2635 2636@kindex r 2637@kindex C-r 2638@deffn Command wrap state 2639(@kbd{C-a r}, @kbd{C-a C-r}) @* 2640Sets the line-wrap setting for the current window. When line-wrap is 2641on, the second consecutive printable character output at the last column 2642of a line will wrap to the start of the following line. As an added 2643feature, backspace (^H) will also wrap through the left margin to the 2644previous line. Default is @samp{on}. 2645@end deffn 2646 2647@deffn Command defwrap state 2648(none) @* 2649Same as the @code{wrap} command except that the default setting for new 2650windows is changed. Initially line-wrap is on and can be toggled with the 2651@code{wrap} command (@kbd{C-a r}) or by means of "C-a : wrap on|off". 2652@end deffn 2653 2654@node Reset, Window Size, Wrap, Virtual Terminal 2655@section Reset 2656@kindex Z 2657@deffn Command reset 2658(@kbd{C-a Z})@* 2659Reset the virtual terminal to its ``power-on'' values. Useful when strange 2660settings (like scroll regions or graphics character set) are left over from 2661an application. 2662@end deffn 2663 2664@node Window Size, Character Processing, Reset, Virtual Terminal 2665@section Window Size 2666@kindex W 2667@deffn Command width [@code{-w}|@code{-d}] [cols [lines]] 2668(@kbd{C-a W})@* 2669Toggle the window width between 80 and 132 columns, or set it to 2670@var{cols} columns if an argument is specified. This requires a 2671capable terminal and the termcap entries @samp{Z0} and @samp{Z1}. See 2672the @code{termcap} command (@pxref{Termcap}), for more information. 2673You can also specify a height if you want to 2674change both values. The @code{-w} option tells screen to leave 2675the display size unchanged and just set the window size, 2676@code{-d} vice versa. 2677@end deffn 2678 2679@deffn Command height [@code{-w}|@code{-d}] [lines [cols]] 2680(none)@* 2681Set the display height to a specified number of lines. When no 2682argument is given it toggles between 24 and 42 lines display. 2683@end deffn 2684 2685@node Character Processing, ,Window Size, Virtual Terminal 2686@section Character Processing 2687 2688@deffn Command c1 [state] 2689(none)@* 2690Change c1 code processing. @samp{c1 on} tells screen to treat 2691the input characters between 128 and 159 as control functions. 2692Such an 8-bit code is normally the same as ESC followed by the 2693corresponding 7-bit code. The default setting is to process c1 2694codes and can be changed with the @samp{defc1} command. 2695Users with fonts that have usable characters in the 2696c1 positions may want to turn this off. 2697 2698@end deffn 2699@deffn Command gr [state] 2700(none)@* 2701Turn GR charset switching on/off. Whenever screen sees an input 2702char with an 8th bit set, it will use the charset stored in the 2703GR slot and print the character with the 8th bit stripped. The 2704default (see also @samp{defgr}) is not to process GR switching because 2705otherwise the ISO88591 charset would not work. 2706@end deffn 2707 2708@deffn Command bce [state] 2709(none)@* 2710Change background-color-erase setting. If @samp{bce} is set to 2711on, all characters cleared by an erase/insert/scroll/clear 2712operation will be displayed in the current background color. 2713Otherwise the default background color is used. 2714@end deffn 2715 2716@deffn Command encoding enc [denc] 2717(none)@* 2718Tell screen how to interpret the input/output. The first argument 2719sets the encoding of the current window. 2720Each window can emulate a different encoding. The optional second 2721parameter overwrites the encoding of the connected terminal. 2722It should never be needed as screen uses the locale setting to detect 2723the encoding. 2724There is also a way to select a terminal encoding depending on 2725the terminal type by using the @samp{KJ} termcap entry. @xref{Special Capabilities}. 2726 2727Supported encodings are 2728@code{eucJP}, @code{SJIS}, @code{eucKR}, 2729@code{eucCN}, @code{Big5}, @code{GBK}, @code{KOI8-R}, @code{CP1251}, 2730@code{UTF-8}, @code{ISO8859-2}, @code{ISO8859-3}, 2731@code{ISO8859-4}, @code{ISO8859-5}, @code{ISO8859-6}, 2732@code{ISO8859-7}, @code{ISO8859-8}, @code{ISO8859-9}, 2733@code{ISO8859-10}, @code{ISO8859-15}, @code{jis}. 2734 2735See also @samp{defencoding}, which changes the default setting of a new 2736window. 2737@end deffn 2738 2739@deffn Command charset set 2740(none)@* 2741Change the current character set slot designation and charset 2742mapping. The first four character of @var{set} 2743are treated as charset designators while the fifth and sixth 2744character must be in range @samp{0} to @samp{3} and set the GL/GR 2745charset mapping. On every position a @samp{.} may be used to indicate 2746that the corresponding charset/mapping should not be changed 2747(@var{set} is padded to six characters internally by appending 2748@samp{.} chars). New windows have @samp{BBBB02} as default 2749charset, unless a @samp{encoding} command is active. 2750 2751The current setting can be viewed with the @ref{Info} command. 2752@end deffn 2753 2754@deffn Command utf8 [state [dstate]] 2755(none)@* 2756Change the encoding used in the current window. If utf8 is enabled, the 2757strings sent to the window will be UTF-8 encoded and vice versa. 2758Omitting the 2759parameter toggles the setting. If a second parameter is given, the 2760display's 2761encoding is also changed (this should rather be done with screen's 2762@samp{-U} option). 2763See also @samp{defutf8}, which changes the default setting of a new 2764window. 2765@end deffn 2766 2767@deffn Command defc1 state 2768(none)@* 2769Same as the @samp{c1} command except that the default setting for 2770new windows is changed. Initial setting is @samp{on}. 2771@end deffn 2772 2773@deffn Command defgr state 2774(none)@* 2775Same as the @samp{gr} command except that the default setting for 2776new windows is changed. Initial setting is @samp{off}. 2777@end deffn 2778 2779@deffn Command defbce state 2780(none)@* 2781Same as the @samp{bce} command except that the default setting for 2782new windows is changed. Initial setting is @samp{off}. 2783@end deffn 2784 2785@deffn Command defencoding enc 2786(none)@* 2787Same as the @samp{encoding} command except that the default setting for 2788new windows is changed. Initial setting is the encoding taken from the 2789terminal. 2790@end deffn 2791 2792@deffn Command defcharset [set] 2793Like the @samp{charset} command except that the default setting for 2794new windows is changed. Shows current default if called without 2795argument. 2796@end deffn 2797 2798@deffn Command defutf8 state 2799(none)@* 2800Same as the @samp{utf8} command except that the default setting for new 2801windows is changed. Initial setting is @code{on} if screen was started 2802with @samp{-U}, otherwise @code{off}. 2803@end deffn 2804 2805@node Copy and Paste, Subprocess Execution, Virtual Terminal, Top 2806@chapter Copy and Paste 2807@cindex copy and paste 2808 2809For those confined to a hardware terminal, these commands provide a cut 2810and paste facility more powerful than those provided by most windowing 2811systems. 2812 2813@menu 2814* Copy:: Copy from scrollback to buffer 2815* Paste:: Paste from buffer into window 2816* Registers:: Longer-term storage 2817* Screen Exchange:: Sharing data between screen users 2818* History:: Recalling previous input 2819@end menu 2820 2821@node Copy, Paste, , Copy and Paste 2822@section Copying 2823@cindex marking 2824@cindex scrollback 2825@kindex [ 2826@kindex C-[ 2827@kindex ESC 2828@deffn Command copy 2829(@kbd{C-a [}, @kbd{C-a C-[}, @kbd{C-a @key{ESC}})@* 2830Enter copy/scrollback mode. This allows you to copy text from the 2831current window and its history into the paste buffer. In this mode a 2832@code{vi}-like full screen editor is active, with controls as 2833outlined below. 2834@end deffn 2835 2836@menu 2837* Line Termination:: End copied lines with CR/LF 2838* Scrollback:: Set the size of the scrollback buffer 2839* Copy Mode Keys:: Remap keys in copy mode 2840* Movement:: Move around in the scrollback buffer 2841* Marking:: Select the text you want 2842* Repeat count:: Repeat a command 2843* Searching:: Find the text you want 2844* Specials:: Other random keys 2845@end menu 2846 2847@node Line Termination, Scrollback, , Copy 2848@subsection CR/LF 2849@deffn Command crlf [state] 2850(none)@* 2851This affects the copying of text regions with the @kbd{C-a [} command. 2852If it is set to @samp{on}, lines will be separated by the two character 2853sequence @samp{CR}/@samp{LF}. Otherwise only @samp{LF} is used. 2854@code{crlf} is off by default. 2855When no parameter is given, the state is toggled. 2856@end deffn 2857 2858@node Scrollback, Copy Mode Keys, Line Termination, Copy 2859@subsection Scrollback 2860@deffn Command defscrollback num 2861(none)@* 2862Same as the @code{scrollback} command except that the default setting 2863for new windows is changed. Defaults to 100. 2864@end deffn 2865 2866@deffn Command scrollback num 2867(none)@* 2868Set the size of the scrollback buffer for the current window to 2869@var{num} lines. The default scrollback is 100 lines. Use @kbd{C-a i} 2870to view the current setting. 2871@end deffn 2872 2873@deffn Command compacthist [state] 2874(none)@* 2875This tells screen whether to suppress trailing blank lines when 2876scrolling up text into the history buffer. Turn compacting @samp{on} 2877to hold more useful lines in your scrollback buffer. 2878@end deffn 2879 2880@node Copy Mode Keys, Movement, Scrollback, Copy 2881@subsection markkeys 2882@deffn Command markkeys string 2883(none)@* 2884This is a method of changing the keymap used for copy/history mode. The 2885string is made up of @var{oldchar}=@var{newchar} pairs which are 2886separated by @samp{:}. Example: The command @code{markkeys 2887h=^B:l=^F:$=^E} would set some keys to be more familiar to @code{emacs} 2888users. 2889If your terminal sends characters, that cause you to abort copy mode, 2890then this command may help by binding these characters to do nothing. 2891The no-op character is `@' and is used like this: @code{markkeys @@=L=H} 2892if you do not want to use the `H' or `L' commands any longer. 2893As shown in this example, multiple keys can be assigned to one function 2894in a single statement. 2895@end deffn 2896 2897@node Movement, Marking, Copy Mode Keys, Copy 2898@subsection Movement Keys 2899 2900@noindent 2901@kbd{h}, @kbd{j}, @kbd{k}, @kbd{l} move the cursor line by line or 2902column by column. 2903 2904@noindent 2905@kbd{0}, @kbd{^} and @kbd{$} move to the leftmost column or to the first 2906or last non-whitespace character on the line. 2907 2908@noindent 2909@kbd{H}, @kbd{M} and @kbd{L} move the cursor to the leftmost column 2910of the top, center or bottom line of the window. 2911 2912@noindent 2913@kbd{+} and @kbd{-} move the cursor to the leftmost column of the next 2914or previous line. 2915 2916@noindent 2917@kbd{G} moves to the specified absolute line (default: end of buffer). 2918 2919@noindent 2920@kbd{|} moves to the specified absolute column. 2921 2922@noindent 2923@kbd{w}, @kbd{b}, @kbd{e} move the cursor word by word. 2924 2925@noindent 2926@kbd{B}, @kbd{E} move the cursor WORD by WORD (as in vi). 2927 2928@noindent 2929@kbd{C-u} and @kbd{C-d} scroll the display up/down by the specified 2930amount of lines while preserving the cursor position. (Default: half 2931screenfull). 2932 2933@noindent 2934@kbd{C-b} and @kbd{C-f} move the cursor up/down a full screen. 2935 2936@noindent 2937@kbd{g} moves to the beginning of the buffer. 2938 2939@noindent 2940@kbd{%} jumps to the specified percentage of the buffer. 2941 2942Note that Emacs-style movement keys can be specified by a .screenrc 2943command. (@code{markkeys "h=^B:l=^F:$=^E"}) There is no simple method for 2944a full emacs-style keymap, however, as this involves multi-character codes. 2945 2946@node Marking, Repeat count, Movement, Copy 2947@subsection Marking 2948 2949The copy range is specified by setting two marks. The text between these 2950marks will be highlighted. Press @kbd{space} to set the first or second 2951mark respectively. 2952 2953@noindent 2954@kbd{Y} and @kbd{y} can be used to mark one whole line or to mark from 2955start of line. 2956 2957@noindent 2958@kbd{W} marks exactly one word. 2959 2960@node Repeat count, Searching, Marking, Copy 2961@subsection Repeat Count 2962 2963Any command in copy mode can be prefixed with a number (by pressing 2964digits @kbd{0@dots{}9}) which is taken as a repeat count. Example: 2965@kbd{C-a C-[ H 10 j 5 Y} will copy lines 11 to 15 into the paste buffer. 2966 2967@node Searching, Specials, Repeat count, Copy 2968@subsection Searching 2969 2970@noindent 2971@kbd{/} @code{vi}-like search forward. 2972 2973@noindent 2974@kbd{?} @code{vi}-like search backward. 2975 2976@noindent 2977@kbd{C-a s} @code{emacs} style incremental search forward. 2978 2979@noindent 2980@kbd{C-r} @code{emacs} style reverse i-search. 2981 2982@deffn Command ignorecase [state] 2983(none)@* 2984Tell screen to ignore the case of characters in searches. Default is 2985@code{off}. 2986@end deffn 2987 2988@node Specials, , Searching, Copy 2989@subsection Specials 2990 2991There are, however, some keys that act differently here from in 2992@code{vi}. @code{Vi} does not allow to yank rectangular blocks of text, 2993but @code{screen} does. Press 2994 2995@noindent 2996@kbd{c} or @kbd{C} to set the left or right margin respectively. If no 2997repeat count is given, both default to the current cursor position.@* 2998Example: Try this on a rather full text screen: 2999@kbd{C-a [ M 20 l SPACE c 10 l 5 j C SPACE}. 3000 3001@noindent 3002This moves one to the middle line of the screen, moves in 20 columns left, 3003marks the beginning of the paste buffer, sets the left column, moves 5 columns 3004down, sets the right column, and then marks the end of 3005the paste buffer. Now try:@* 3006@kbd{C-a [ M 20 l SPACE 10 l 5 j SPACE} 3007 3008@noindent 3009and notice the difference in the amount of text copied. 3010 3011@noindent 3012@kbd{J} joins lines. It toggles between 4 modes: lines separated by a 3013newline character (012), lines glued seamless, lines separated by a single 3014space or comma separated lines. Note that you can prepend the newline 3015character with a carriage return character, by issuing a @code{set crlf 3016on}. 3017 3018@noindent 3019@kbd{v} is for all the @code{vi} users who use @code{:set numbers} - it 3020toggles the left margin between column 9 and 1. 3021 3022@noindent 3023@kbd{a} before the final space key turns on append mode. Thus 3024the contents of the paste buffer will not be overwritten, but appended to. 3025 3026@noindent 3027@kbd{A} turns on append mode and sets a (second) mark. 3028 3029@noindent 3030@kbd{>} sets the (second) mark and writes the contents of the paste buffer 3031to the screen-exchange file (@file{/tmp/screen-exchange} per default) 3032once copy-mode is finished. @xref{Screen Exchange}.@* 3033This example demonstrates how to dump the 3034whole scrollback buffer to that file: @*@kbd{C-a [ g SPACE G $ >}. 3035 3036@noindent 3037@kbd{C-g} gives information about the current line and column. 3038 3039@noindent 3040@kbd{x} exchanges the first mark and the current cursor position. You 3041can use this to adjust an already placed mark. 3042 3043@noindent 3044@kbd{@@} does nothing. Absolutely nothing. Does not even exit copy 3045mode. 3046 3047@noindent 3048All keys not described here exit copy mode. 3049 3050@node Paste, Registers, Copy, Copy and Paste 3051@section Paste 3052 3053@kindex ] 3054@kindex C-] 3055@deffn Command paste [registers [destination]] 3056(@kbd{C-a ]}, @kbd{C-a C-]})@* 3057Write the (concatenated) contents of the specified registers to the stdin 3058stream of the current window. The register @samp{.} is treated as the 3059paste buffer. If no parameter is specified the user is prompted to enter a 3060single register. The paste buffer can be filled with the 3061@code{copy}, @code{history} and @code{readbuf} commands. 3062Other registers can be filled with the @code{register}, @code{readreg} and 3063@code{paste} commands. 3064If @code{paste} is called with a second argument, the contents of the specified 3065registers is pasted into the named destination register rather than 3066the window. If @samp{.} is used as the second argument, the display's paste 3067buffer is the destination. 3068Note, that @code{paste} uses a wide variety of resources: Usually both, a 3069current window and a current display are required. But whenever a second 3070argument is specified no current window is needed. When the source specification 3071only contains registers (not the paste buffer) then there need not be a current 3072display (terminal attached), as the registers are a global resource. The 3073paste buffer exists once for every user. 3074@end deffn 3075 3076@deffn Command stuff string 3077(none)@* 3078Stuff the string @var{string} in the input buffer of the current window. 3079This is like the @code{paste} command, but with much less overhead. 3080You cannot paste large buffers with the @code{stuff} command. It is most 3081useful for key bindings. @xref{Bindkey}. 3082@end deffn 3083 3084@deffn Command pastefont [state] 3085Tell screen to include font information in the paste buffer. The 3086default is not to do so. This command is especially useful for 3087multi character fonts like kanji. 3088@end deffn 3089 3090@deffn Command slowpaste msec 3091@deffnx Command defslowpaste msec 3092(none)@* 3093Define the speed text is inserted in the current window by the @code{paste} 3094command. If the slowpaste value is nonzero text is written character by 3095character. 3096@code{screen} will pause for @var{msec} milliseconds after each write 3097to allow the application to process the input. only use @code{slowpaste} if 3098your underlying system exposes flow control problems while pasting large 3099amounts of text. 3100@code{defslowpaste} specifies the default for new windows. 3101@end deffn 3102 3103@deffn Command readreg [-e encoding] [register [filename]] 3104(none)@* 3105Does one of two things, dependent on number of arguments: with zero or one 3106arguments it it duplicates the paste buffer contents into the register specified 3107or entered at the prompt. With two arguments it reads the contents of the named 3108file into the register, just as @code{readbuf} reads the screen-exchange file 3109into the paste buffer. 3110You can tell screen the encoding of the file via the @code{-e} option. 3111The following example will paste the system's password file into 3112the screen window (using register p, where a copy remains): 3113 3114@example 3115C-a : readreg p /etc/passwd 3116C-a : paste p 3117@end example 3118@end deffn 3119 3120@node Registers, Screen Exchange, Paste, Copy and Paste 3121@section Registers 3122 3123@deffn Command copy_reg [key] 3124(none)@* 3125Removed. Use @code{readreg} instead. 3126@end deffn 3127 3128@deffn Command ins_reg [key] 3129(none)@* 3130Removed. Use @code{paste} instead. 3131@end deffn 3132 3133@deffn Command process [key] 3134(none)@* 3135Stuff the contents of the specified register into the @code{screen} 3136input queue. If no argument is given you are prompted for a 3137register name. The text is parsed as if it had been typed in from the user's 3138keyboard. This command can be used to bind multiple actions to a single key. 3139@end deffn 3140 3141@deffn Command register [-e encoding] key string 3142(none)@* 3143Save the specified @var{string} to the register @var{key}. 3144The encoding of the string can be specified via the @code{-e} option. 3145@end deffn 3146 3147@node Screen Exchange, History, Registers, Copy and Paste 3148@section Screen Exchange 3149 3150@deffn Command bufferfile [@var{exchange-file}] 3151(none)@* 3152Change the filename used for reading and writing with the paste buffer. 3153If the @var{exchange-file} parameter is omitted, @code{screen} reverts 3154to the default of @file{/tmp/screen-exchange}. The following example 3155will paste the system's password file into the screen window (using the 3156paste buffer, where a copy remains): 3157 3158@example 3159C-a : bufferfile /etc/passwd 3160C-a < C-a ] 3161C-a : bufferfile 3162@end example 3163@end deffn 3164 3165@kindex < 3166@deffn Command readbuf [-e @var{encoding}] [@var{filename}] 3167(@kbd{C-a <})@* 3168Reads the contents of the specified file into the paste buffer. 3169You can tell screen the encoding of the file via the @code{-e} option. 3170If no file is specified, the screen-exchange filename is used. 3171@end deffn 3172 3173@kindex = 3174@deffn Command removebuf 3175(@kbd{C-a =})@* 3176Unlinks the screen-exchange file. 3177@end deffn 3178 3179@kindex > 3180@deffn Command writebuf [-e @var{encoding}] [@var{filename}] 3181(@kbd{C-a >})@* 3182Writes the contents of the paste buffer to the specified file, or the 3183public accessible screen-exchange file if no filename is given. 3184This is thought of as a primitive means of 3185communication between @code{screen} users on the same host. 3186If an encoding is specified the paste buffer is recoded on the fly to 3187match the encoding. 3188See also 3189@kbd{C-a @key{ESC}} (@pxref{Copy}). 3190@end deffn 3191 3192@node History, , Screen Exchange, Copy and Paste 3193@section History 3194 3195@kindex @{ 3196@deffn Command history 3197(@kbd{C-a @{})@* 3198Usually users work with a shell that allows easy access to previous 3199commands. For example, @code{csh} has the command @code{!!} to repeat 3200the last command executed. @code{screen} provides a primitive way of 3201recalling ``the command that started @dots{}'': You just type the first 3202letter of that command, then hit @kbd{C-a @{} and @code{screen} tries to 3203find a previous line that matches with the prompt character to the left 3204of the cursor. This line is pasted into this window's input queue. Thus 3205you have a crude command history (made up by the visible window and its 3206scrollback buffer). 3207@end deffn 3208 3209@node Subprocess Execution, Key Binding, Copy and Paste, Top 3210@chapter Subprocess Execution 3211Control Input or Output of a window by another filter process. 3212Use with care! 3213 3214@menu 3215* Exec:: The @code{exec} command syntax. 3216* Using Exec:: Weird things that filters can do. 3217@end menu 3218 3219@node Exec, Using Exec, , Subprocess Execution 3220@section Exec 3221@deffn Command exec [[@var{fdpat}] @var{newcommand} [@var{args} ... ]] 3222(none)@* 3223Run a unix subprocess (specified by an executable path @var{newcommand} and 3224its optional arguments) in the current window. The flow of data between 3225newcommands stdin/stdout/stderr, the process originally started (let us call it 3226"application-process") and 3227screen itself (window) is controlled by the filedescriptor pattern @var{fdpat}. 3228This pattern is basically a three character sequence representing stdin, stdout 3229and stderr of newcommand. A dot (@code{.}) connects the file descriptor 3230to screen. An exclamation mark (@code{!}) causes the file descriptor to be 3231connected to the application-process. A colon (@code{:}) combines both. 3232@* 3233User input will go to newcommand unless newcommand receives the 3234application-process' 3235output (@var{fdpat}s first character is @samp{!} or @samp{:}) or a pipe symbol 3236(@samp{|}) is added to the end of @var{fdpat}. 3237@* 3238Invoking @code{exec} without arguments shows name and arguments of the currently 3239running subprocess in this window. Only one subprocess can be running per 3240window. 3241@* 3242When a subprocess is running the @code{kill} command will affect it instead of 3243the windows process. Only one subprocess a time can be running in each window. 3244@* 3245Refer to the postscript file @file{doc/fdpat.ps} for a confusing 3246illustration of all 21 possible combinations. Each drawing shows the digits 32472, 1, 0 representing the three file descriptors of newcommand. The box 3248marked `W' is usual pty that has the application-process on its slave side. 3249The box marked `P' is the secondary pty that now has screen at its master 3250side. 3251@end deffn 3252 3253@node Using Exec, , Exec, Subprocess Execution 3254@section Using Exec 3255@noindent 3256Abbreviations: 3257 3258@itemize @bullet 3259@item 3260Whitespace between the word @samp{exec} and @var{fdpat} and the command name 3261can be omitted. 3262 3263@item 3264Trailing dots and a @var{fdpat} consisting only of dots can be omitted. 3265 3266@item 3267A simple @samp{|} is synonymous for the @samp{!..|} pattern. 3268 3269@item 3270The word @samp{exec} can be omitted when the @samp{|} abbreviation is used. 3271 3272@item 3273The word @samp{exec} can always be replaced by leading @samp{!}. 3274@end itemize 3275 3276@noindent 3277Examples: 3278 3279@table @code 3280@item !/bin/sh 3281@itemx exec /bin/sh 3282@itemx exec ... /bin/sh 3283All of the above are equivalent. 3284Creates another shell in the same window, while the original shell is still 3285running. Output of both shells is displayed and user input is sent to the new 3286@file{/bin/sh}. 3287 3288@item !!stty 19200 3289@itemx exec!stty 19200 3290@itemx exec !.. stty 19200 3291All of the above are equivalent. 3292Set the speed of the window's tty. If your stty command operates on stdout, 3293then add another @samp{!}. This is a useful command, when a screen window 3294is directly connected to a serial line that needs to be configured. 3295 3296@item |less 3297@itemx exec !..| less 3298Both are equivalent. 3299This adds a pager to the window output. The special character @samp{|} is 3300needed to give the user control over the pager although it gets its input from 3301the window's process. This works, because @samp{less} listens on stderr 3302(a behavior that @code{screen} would not expect without the @samp{|}) 3303when its stdin is not a tty. @code{Less} versions newer than 177 fail miserably 3304here; good old @code{pg} still works. 3305 3306@item !:sed -n s/.*Error.*/\007/p 3307Sends window output to both, the user and the sed command. The sed inserts an 3308additional bell character (oct. 007) to the window output seen by screen. 3309This will cause 'Bell in window x' messages, whenever the string @samp{Error} 3310appears in the window. 3311@end table 3312 3313@node Key Binding, Flow Control, Subprocess Execution, Top 3314@chapter Key Binding 3315@cindex key binding 3316@cindex binding 3317 3318You may disagree with some of the default bindings (I know I do). The 3319@code{bind} command allows you to redefine them to suit your 3320preferences. 3321 3322@menu 3323* Bind:: @code{bind} syntax. 3324* Bind Examples:: Using @code{bind}. 3325* Command Character:: The character used to start keyboard commands. 3326* Help:: Show current key bindings. 3327* Bindkey:: @code{bindkey} syntax. 3328* Bindkey Examples:: Some easy examples. 3329* Bindkey Control:: How to control the bindkey mechanism. 3330@end menu 3331 3332@node Bind, Bind Examples, , Key Binding 3333@section The @code{bind} command 3334@deffn Command bind [-c class] key [command [args]] 3335(none)@* 3336Bind a command to a key. The @var{key} argument is either a single 3337character, a two-character sequence of the form @samp{^x} (meaning 3338@kbd{C-x}), a backslash followed by an octal number (specifying the 3339ASCII code of the character), or a backslash followed by a second 3340character, such as @samp{\^} or @samp{\\}. The argument can also be 3341quoted, if you like. If no further argument is given, any previously 3342established binding for this key is removed. The @var{command} 3343argument can be any command (@pxref{Command Index}). 3344 3345If a command class is specified via the @code{-c} option, the 3346key is bound for the specified class. Use the @code{command} 3347command to activate a class. Command classes can be used 3348to create multiple command keys or multi-character bindings. 3349 3350By default, most suitable commands are bound to one or more keys 3351(@pxref{Default Key Bindings}; for instance, the command to create a 3352new window is bound to @kbd{C-c} and @kbd{c}. The @code{bind} command 3353can be used to redefine the key bindings and to define new bindings. 3354@end deffn 3355 3356@node Bind Examples, Command Character, Bind, Key Binding 3357@section Examples of the @code{bind} command 3358@noindent 3359Some examples: 3360 3361@example 3362bind ' ' windows 3363bind ^f screen telnet foobar 3364bind \033 screen -ln -t root -h 1000 9 su 3365@end example 3366 3367@noindent 3368would bind the space key to the command that displays a list of windows 3369(so that the command usually invoked by @kbd{C-a C-w} would also be 3370available as @kbd{C-a space}), bind @kbd{C-f} to the command 3371``create a window with a TELNET connection to foobar'', and bind 3372@key{ESC} to the command that creates an non-login window with title 3373@samp{root} in slot #9, with a superuser shell and a scrollback buffer 3374of 1000 lines. 3375 3376@example 3377bind -c demo1 0 select 10 3378bind -c demo1 1 select 11 3379bind -c demo1 2 select 12 3380bindkey "^B" command -c demo1 3381@end example 3382makes @kbd{C-b 0} select window 10, @kbd{C-b 1} window 11, etc. 3383 3384@example 3385bind -c demo2 0 select 10 3386bind -c demo2 1 select 11 3387bind -c demo2 2 select 12 3388bind - command -c demo2 3389@end example 3390makes @kbd{C-a - 0} select window 10, @kbd{C-a - 1} window 11, etc. 3391 3392@node Command Character, Help, Bind Examples, Key Binding 3393@cindex escape character 3394@cindex command character 3395@section Command Character 3396 3397@deffn Command escape xy 3398(none)@* 3399Set the command character to @var{x} and the character generating a 3400literal command character (by triggering the @code{meta} command) 3401to @var{y} (similar to the @samp{-e} option). 3402Each argument is either a single character, a two-character 3403sequence of the form @samp{^x} (meaning @kbd{C-x}), a backslash followed 3404by an octal number (specifying the ASCII code of the character), or a 3405backslash followed by a second character, such as @samp{\^} or 3406@samp{\\}. The default is @samp{^Aa}, but @samp{``} is recommended by 3407one of the authors. 3408@end deffn 3409 3410@deffn Command defescape xy 3411(none)@* 3412Set the default command characters. This is equivalent to the command 3413@code{escape} except that it is useful for multiuser sessions only. 3414In a multiuser session 3415@code{escape} changes the command character of the calling user, where 3416@code{defescape} changes the default command characters for users that 3417will be added later. 3418@end deffn 3419 3420@kindex a 3421@deffn Command meta 3422(@kbd{C-a a})@* 3423Send the command character (@kbd{C-a}) to the process in the current 3424window. The keystroke for this command is the second parameter to the 3425@samp{-e} command line switch (@pxref{Invoking Screen}), or the 3426@code{escape} .screenrc directive. 3427@end deffn 3428 3429@deffn Command command [-c @var{class}] 3430(none)@* 3431This command has the same effect as typing the screen escape character 3432(@kbd{C-a}). It is probably only useful for key bindings. 3433If the @samp{-c} option is given, select the specified command class. 3434@xref{Bind}, @xref{Bindkey}. 3435@end deffn 3436 3437@node Help, Bindkey, Command Character, Key Binding 3438@section Help 3439@kindex ? 3440@deffn Command help 3441(@kbd{C-a ?})@* 3442Displays a help screen showing you all the key bindings. The first 3443pages list all the internal commands followed by their bindings. 3444Subsequent pages will display the custom commands, one command per key. 3445Press space when you're done reading each page, or return to exit early. 3446All other characters are ignored. 3447If the @samp{-c} option is given, display all bound commands for the 3448specified command class. 3449@xref{Default Key Bindings}. 3450@end deffn 3451 3452@node Bindkey, Bindkey Examples, Help, Key Binding 3453@section Bindkey 3454@deffn Command bindkey [@var{opts}] [@var{string} [@var{cmd} @var{args}]] 3455(none)@* 3456This command manages screen's input translation tables. Every 3457entry in one of the tables tells screen how to react if a certain 3458sequence of characters is encountered. There are three tables: 3459one that should contain actions programmed by the user, one for 3460the default actions used for terminal emulation and one for 3461screen's copy mode to do cursor movement. See @ref{Input Translation} 3462for a list of default key bindings. 3463 3464If the @samp{-d} 3465option is given, bindkey modifies the default table, @samp{-m} 3466changes the copy mode table and with neither option the user 3467table is selected. The argument @samp{string} is the sequence of 3468characters to which an action is bound. This can either be a fixed 3469tring or a termcap keyboard capability name (selectable with the 3470@samp{-k} option). 3471 3472Some keys on a VT100 terminal can send a different 3473string if application mode is turned on (e.g. the cursor keys). 3474Such keys have two entries in the translation table. You can 3475select the application mode entry by specifying the @samp{-a} 3476option. 3477 3478The @samp{-t} option tells screen not to do inter-character 3479timing. One cannot turn off the timing if a termcap capability is 3480used. 3481 3482@samp{cmd} can be any of screen's commands with an arbitrary 3483number of @samp{args}. If @samp{cmd} is omitted the key-binding is 3484removed from the table. 3485@end deffn 3486 3487@node Bindkey Examples, Bindkey Control,Bindkey, Key Binding 3488@section Bindkey Examples 3489@noindent 3490Here are some examples of keyboard bindings: 3491 3492@example 3493bindkey -d 3494@end example 3495@noindent 3496Show all of the default key bindings. The application mode entries 3497are marked with [A]. 3498 3499@example 3500bindkey -k k1 select 1 3501@end example 3502@noindent 3503Make the "F1" key switch to window one. 3504 3505@example 3506bindkey -t foo stuff barfoo 3507@end example 3508@noindent 3509Make @samp{foo} an abbreviation of the word @samp{barfoo}. Timeout is 3510disabled so that users can type slowly. 3511 3512@example 3513bindkey "\024" mapdefault 3514@end example 3515@noindent 3516This key-binding makes @samp{C-t} an escape character for key-bindings. If 3517you did the above @samp{stuff barfoo} binding, you can enter the word 3518@samp{foo} by typing @samp{C-t foo}. If you want to insert a 3519@samp{C-t} you have to press the key twice (i.e. escape the escape 3520binding). 3521 3522@example 3523bindkey -k F1 command 3524@end example 3525@noindent 3526Make the F11 (not F1!) key an alternative screen 3527escape (besides @samp{C-a}). 3528 3529@node Bindkey Control, , Bindkey Examples, Key Binding 3530@section Bindkey Control 3531@deffn Command mapdefault 3532(none)@* 3533Tell screen that the next input character should only be looked up 3534in the default bindkey table. 3535@end deffn 3536@deffn Command mapnotnext 3537(none)@* 3538Like mapdefault, but don't even look in the default bindkey table. 3539@end deffn 3540@deffn Command maptimeout timo 3541(none)@* 3542Set the intercharacter timer for input sequence detection to a timeout 3543of @var{timo} ms. The default timeout is 300ms. Maptimeout with no 3544arguments shows the current setting. 3545@end deffn 3546 3547@node Flow Control, Termcap, Key Binding, Top 3548@chapter Flow Control 3549@cindex flow control 3550 3551@code{screen} can trap flow control characters or pass them to the 3552program, as you see fit. This is useful when your terminal wants to use 3553XON/XOFF flow control and you are running a program which wants to use 3554^S/^Q for other purposes (i.e. @code{emacs}). 3555 3556@menu 3557* Flow Control Summary:: The effect of @code{screen} flow control 3558* Flow:: Setting the flow control behavior 3559* XON/XOFF:: Sending XON or XOFF to the window 3560@end menu 3561 3562@node Flow Control Summary, Flow, , Flow Control 3563@section About @code{screen} flow control settings 3564Each window has a flow-control setting that determines how screen deals 3565with the XON and XOFF characters (and perhaps the interrupt character). 3566When flow-control is turned off, screen ignores the XON and XOFF 3567characters, which allows the user to send them to the current program by 3568simply typing them (useful for the @code{emacs} editor, for instance). 3569The trade-off is that it will take longer for output from a 3570``normal'' program to pause in response to an XOFF. With 3571flow-control turned on, XON and XOFF characters are used to immediately 3572pause the output of the current window. You can still send these 3573characters to the current program, but you must use the appropriate 3574two-character screen commands (typically @kbd{C-a q} (xon) and @kbd{C-a 3575s} (xoff)). The xon/xoff commands are also useful for typing C-s and 3576C-q past a terminal that intercepts these characters. 3577 3578Each window has an initial flow-control value set with either the 3579@samp{-f} option or the @code{defflow} command. By default the 3580windows are set to automatic flow-switching. It can then be toggled 3581between the three states 'fixed on', 'fixed off' and 'automatic' 3582interactively with the @code{flow} command bound to @kbd{C-a f}. 3583 3584The automatic flow-switching mode deals with flow control using the 3585TIOCPKT mode (like @code{rlogin} does). If the tty driver does not 3586support TIOCPKT, screen tries to determine the right mode based on the 3587current setting of the application keypad --- when it is enabled, 3588flow-control is turned off and visa versa. Of course, you can still 3589manipulate flow-control manually when needed. 3590 3591If you're running with flow-control enabled and find that pressing the 3592interrupt key (usually C-c) does not interrupt the display until another 35936-8 lines have scrolled by, try running screen with the @samp{interrupt} 3594option (add the @samp{interrupt} flag to the @code{flow} command in your 3595.screenrc, or use the @samp{-i} command-line option). This causes the 3596output that @code{screen} has accumulated from the interrupted program 3597to be flushed. One disadvantage is that the virtual terminal's memory 3598contains the non-flushed version of the output, which in rare cases can 3599cause minor inaccuracies in the output. For example, if you switch 3600screens and return, or update the screen with @kbd{C-a l} you would see 3601the version of the output you would have gotten without @samp{interrupt} 3602being on. Also, you might need to turn off flow-control (or use 3603auto-flow mode to turn it off automatically) when running a program that 3604expects you to type the interrupt character as input, as the 3605@samp{interrupt} parameter only takes effect when flow-control is 3606enabled. If your program's output is interrupted by mistake, a simple 3607refresh of the screen with @kbd{C-a l} will restore it. Give each mode 3608a try, and use whichever mode you find more comfortable. 3609 3610@node Flow, XON/XOFF, Flow Control Summary, Flow Control 3611@section Flow 3612@deffn Command defflow fstate [interrupt] 3613(none)@* 3614Same as the @code{flow} command except that the default setting for new 3615windows is changed. Initial setting is `auto'. 3616Specifying @code{flow auto interrupt} has the same effect as the 3617command-line options @samp{-fa} and @samp{-i}. 3618Note that if @samp{interrupt} is enabled, all existing displays are 3619changed immediately to forward interrupt signals. 3620@end deffn 3621 3622@kindex f 3623@kindex C-f 3624@deffn Command flow [fstate] 3625(@kbd{C-a f}, @kbd{C-a C-f})@* 3626Sets the flow-control mode for this window to @var{fstate}, which can be 3627@samp{on}, @samp{off} or @samp{auto}. 3628Without parameters it cycles the current window's 3629flow-control setting. Default is set by `defflow'. 3630@end deffn 3631 3632@node XON/XOFF, , Flow, Flow Control 3633@section XON and XOFF 3634@kindex q 3635@kindex C-q 3636@deffn Command xon 3637(@kbd{C-a q}, @kbd{C-a C-q})@* 3638Send a ^Q (ASCII XON) to the program in the current window. Redundant 3639if flow control is set to @samp{off} or @samp{auto}. 3640@end deffn 3641 3642@kindex s 3643@kindex C-s 3644@deffn Command xoff 3645(@kbd{C-a s}, @kbd{C-a C-s})@* 3646Send a ^S (ASCII XOFF) to the program in the current window. 3647@end deffn 3648 3649@node Termcap, Message Line, Flow Control, Top 3650@chapter Termcap 3651 3652@code{screen} demands the most out of your terminal so that it can 3653perform its VT100 emulation most efficiently. These functions provide 3654means for tweaking the termcap entries for both your physical terminal 3655and the one simulated by @code{screen}. 3656 3657@menu 3658* Window Termcap:: Choosing a termcap entry for the window. 3659* Dump Termcap:: Write out a termcap entry for the window. 3660* Termcap Syntax:: The @code{termcap} and @code{terminfo} commands. 3661* Termcap Examples:: Uses for @code{termcap}. 3662* Special Capabilities:: Non-standard capabilities used by @code{screen}. 3663* Autonuke:: Flush unseen output 3664* Obuflimit:: Allow pending output when reading more 3665* Character Translation:: Emulating fonts and charsets. 3666@end menu 3667 3668@node Window Termcap, Dump Termcap, , Termcap 3669@section Choosing the termcap entry for a window 3670Usually @code{screen} tries to emulate as much of the VT100/ANSI 3671standard as possible. But if your terminal lacks certain capabilities 3672the emulation may not be complete. In these cases @code{screen} has to 3673tell the applications that some of the features are missing. This is no 3674problem on machines using termcap, because @code{screen} can use the 3675@code{$TERMCAP} variable to customize the standard screen termcap. 3676 3677But if you do a rlogin on another machine or your machine supports only 3678terminfo this method fails. Because of this @code{screen} offers a way 3679to deal with these cases. Here is how it works: 3680 3681When @code{screen} tries to figure out a terminal name for itself, it 3682first looks for an entry named @code{screen.@var{term}}, where 3683@var{term} is the contents of your @code{$TERM} variable. If no such entry 3684exists, @code{screen} tries @samp{screen} (or @samp{screen-w}, if the 3685terminal is wide (132 cols or more)). If even this entry cannot be 3686found, @samp{vt100} is used as a substitute. 3687 3688The idea is that if you have a terminal which doesn't support an 3689important feature (e.g. delete char or clear to EOS) you can build a new 3690termcap/terminfo entry for @code{screen} (named 3691@samp{screen.@var{dumbterm}}) in which this capability has been 3692disabled. If this entry is installed on your machines you are able to 3693do a rlogin and still keep the correct termcap/terminfo entry. The 3694terminal name is put in the @code{$TERM} variable of all new windows. 3695@code{screen} also sets the @code{$TERMCAP} variable reflecting the 3696capabilities of the virtual terminal emulated. 3697Furthermore, the variable @code{$WINDOW} is set to the window number of each 3698window. 3699 3700The actual set of capabilities supported by the virtual terminal depends 3701on the capabilities supported by the physical terminal. If, for 3702instance, the physical terminal does not support underscore mode, 3703@code{screen} does not put the @samp{us} and @samp{ue} capabilities into 3704the window's @code{$TERMCAP} variable, accordingly. However, a minimum number 3705of capabilities must be supported by a terminal in order to run 3706@code{screen}; namely scrolling, clear screen, and direct cursor 3707addressing (in addition, @code{screen} does not run on hardcopy 3708terminals or on terminals that over-strike). 3709 3710Also, you can customize the @code{$TERMCAP} value used by @code{screen} by 3711using the @code{termcap} command, or by defining the variable 3712@code{$SCREENCAP} prior to startup. When the latter defined, its value will be 3713copied verbatim into each window's @code{$TERMCAP} variable. This can either 3714be the full terminal definition, or a filename where the terminal 3715@samp{screen} (and/or @samp{screen-w}) is defined. 3716 3717Note that @code{screen} honors the @code{terminfo} command if the system 3718uses the terminfo database rather than termcap. On such machines the 3719@code{$TERMCAP} variable has no effect and you must use the 3720@code{dumptermcap} command (@pxref{Dump Termcap}) and the @code{tic} 3721program to generate terminfo entries for @code{screen} windows. 3722 3723When the boolean @samp{G0} capability is present in the termcap entry 3724for the terminal on which @code{screen} has been called, the terminal 3725emulation of @code{screen} supports multiple character sets. This 3726allows an application to make use of, for instance, the VT100 graphics 3727character set or national character sets. The following control 3728functions from ISO 2022 are supported: @samp{lock shift G0} (@samp{SI}), 3729@samp{lock shift G1} (@samp{SO}), @samp{lock shift G2}, @samp{lock shift 3730G3}, @samp{single shift G2}, and @samp{single shift G3}. When a virtual 3731terminal is created or reset, the ASCII character set is designated as 3732@samp{G0} through @samp{G3}. When the @samp{G0} capability is present, 3733screen evaluates the capabilities @samp{S0}, @samp{E0}, and @samp{C0} if 3734present. @samp{S0} is the sequence the terminal uses to enable and start 3735the graphics character set rather than @samp{SI}. @samp{E0} is the 3736corresponding replacement for @samp{SO}. @samp{C0} gives a character by 3737character translation string that is used during semi-graphics mode. 3738This string is built like the @samp{acsc} terminfo capability. 3739 3740When the @samp{po} and @samp{pf} capabilities are present in the 3741terminal's termcap entry, applications running in a @code{screen} window 3742can send output to the printer port of the terminal. This allows a user 3743to have an application in one window sending output to a printer 3744connected to the terminal, while all other windows are still active (the 3745printer port is enabled and disabled again for each chunk of output). 3746As a side-effect, programs running in different windows can send output 3747to the printer simultaneously. Data sent to the printer is not 3748displayed in the window. The @code{info} command displays a line starting 3749with @samp{PRIN} while the printer is active. 3750 3751Some capabilities are only put into the @code{$TERMCAP} variable of the virtual 3752terminal if they can be efficiently implemented by the physical 3753terminal. For instance, @samp{dl} (delete line) is only put into the 3754@code{$TERMCAP} variable if the terminal supports either delete line itself or 3755scrolling regions. Note that this may provoke confusion, when the 3756session is reattached on a different terminal, as the value of @code{$TERMCAP} 3757cannot be modified by parent processes. You can force @code{screen} to 3758include all capabilities in @code{$TERMCAP} with the @samp{-a} 3759command-line option (@pxref{Invoking Screen}). 3760 3761The "alternate screen" capability is not enabled by default. 3762Set the @code{altscreen} @file{.screenrc} command to enable it. 3763 3764@node Dump Termcap, Termcap Syntax, Window Termcap, Termcap 3765@section Write out the window's termcap entry 3766@kindex . 3767@deffn Command dumptermcap 3768(@kbd{C-a .})@* 3769Write the termcap entry for the virtual terminal optimized for the 3770currently active window to the file @file{.termcap} in the user's 3771@file{$HOME/.screen} directory (or wherever @code{screen} stores its 3772sockets. @pxref{Files}). This termcap entry is identical to 3773the value of the environment variable @code{$TERMCAP} that is set up by 3774@code{screen} for each window. For terminfo based systems you will need 3775to run a converter like @code{captoinfo} and then compile the entry with 3776@code{tic}. 3777@end deffn 3778 3779@node Termcap Syntax, Termcap Examples, Dump Termcap, Termcap 3780@section The @code{termcap} command 3781@deffn Command termcap term terminal-tweaks [window-tweaks] 3782@deffnx Command terminfo term terminal-tweaks [window-tweaks] 3783@deffnx Command termcapinfo term terminal-tweaks [window-tweaks] 3784(none)@* 3785Use this command to modify your terminal's termcap entry without going 3786through all the hassles involved in creating a custom termcap entry. 3787Plus, you can optionally customize the termcap generated for the 3788windows. 3789You have to place these commands in one of the screenrc startup files, as they 3790are meaningless once the terminal emulator is booted. 3791 3792If your system uses the terminfo database rather than termcap, 3793@code{screen} will understand the @code{terminfo} command, which has the 3794same effects as the @code{termcap} command. Two separate commands are 3795provided, as there are subtle syntactic differences, e.g. when parameter 3796interpolation (using @samp{%}) is required. Note that the termcap names of 3797the capabilities should also be used with the @code{terminfo} command. 3798 3799In many cases, where the arguments are valid in both terminfo and termcap 3800syntax, you can use the command @code{termcapinfo}, which is just a 3801shorthand for a pair of @code{termcap} and @code{terminfo} commands with 3802identical arguments. 3803@end deffn 3804 3805The first argument specifies which terminal(s) should be affected by 3806this definition. You can specify multiple terminal names by separating 3807them with @samp{|}s. Use @samp{*} to match all terminals and @samp{vt*} 3808to match all terminals that begin with @samp{vt}. 3809 3810Each @var{tweak} argument contains one or more termcap defines 3811(separated by @samp{:}s) to be inserted at the start of the appropriate 3812termcap entry, enhancing it or overriding existing values. The first 3813tweak modifies your terminal's termcap, and contains definitions that 3814your terminal uses to perform certain functions. Specify a null string 3815to leave this unchanged (e.g. ""). The second (optional) tweak modifies 3816all the window termcaps, and should contain definitions that screen 3817understands (@pxref{Virtual Terminal}). 3818 3819@node Termcap Examples, Special Capabilities, Termcap Syntax, Termcap 3820@section Termcap Examples 3821Some examples: 3822 3823@example 3824termcap xterm* xn:hs@@ 3825@end example 3826 3827@noindent 3828Informs @code{screen} that all terminals that begin with @samp{xterm} 3829have firm auto-margins that allow the last position on the screen to be 3830updated (xn), but they don't really have a status line (no 'hs' -- 3831append @samp{@@} to turn entries off). Note that we assume @samp{xn} for 3832all terminal names that start with @samp{vt}, but only if you don't 3833specify a termcap command for that terminal. 3834 3835@example 3836termcap vt* xn 3837termcap vt102|vt220 Z0=\E[?3h:Z1=\E[?3l 3838@end example 3839 3840@noindent 3841Specifies the firm-margined @samp{xn} capability for all terminals that 3842begin with @samp{vt}, and the second line will also add the 3843escape-sequences to switch into (Z0) and back out of (Z1) 3844132-character-per-line mode if this is a VT102 or VT220. (You must 3845specify Z0 and Z1 in your termcap to use the width-changing commands.) 3846 3847@example 3848termcap vt100 "" l0=PF1:l1=PF2:l2=PF3:l3=PF4 3849@end example 3850 3851@noindent 3852This leaves your vt100 termcap alone and adds the function key labels to 3853each window's termcap entry. 3854 3855@example 3856termcap h19|z19 am@@:im=\E@@:ei=\EO dc=\E[P 3857@end example 3858 3859@noindent 3860Takes a h19 or z19 termcap and turns off auto-margins (am@@) and enables 3861the insert mode (im) and end-insert (ei) capabilities (the @samp{@@} in 3862the @samp{im} string is after the @samp{=}, so it is part of the 3863string). Having the @samp{im} and @samp{ei} definitions put into your 3864terminal's termcap will cause screen to automatically advertise the 3865character-insert capability in each window's termcap. Each window will 3866also get the delete-character capability (dc) added to its termcap, 3867which screen will translate into a line-update for the terminal (we're 3868pretending it doesn't support character deletion). 3869 3870If you would like to fully specify each window's termcap entry, you 3871should instead set the @code{$SCREENCAP} variable prior to running 3872@code{screen}. @xref{Virtual Terminal}, for the details of the 3873@code{screen} terminal emulation. @xref{Top, , Termcap, termcap, The 3874Termcap Manual}, for more information on termcap definitions. 3875 3876@node Special Capabilities, Autonuke, Termcap Examples, Termcap 3877@section Special Terminal Capabilities 3878@cindex terminal capabilities 3879@cindex capabilities 3880The following table describes all terminal capabilities that are 3881recognized by @code{screen} and are not in the termcap manual 3882(@pxref{Top, , Termcap, termcap, The Termcap Manual}). 3883You can place these capabilities in your termcap entries (in 3884@file{/etc/termcap}) or use them with the commands @code{termcap}, 3885@code{terminfo} and @code{termcapinfo} in your @code{screenrc} files. It is 3886often not possible to place these capabilities in the terminfo database. 3887@table @samp 3888@item LP 3889(bool)@* 3890Terminal has VT100 style margins (`magic margins'). Note that 3891this capability is obsolete --- @code{screen} now uses the standard 3892@samp{xn} instead. 3893 3894@item Z0 3895(str)@* 3896Change width to 132 columns. 3897 3898@item Z1 3899(str)@* 3900Change width to 80 columns. 3901 3902@item WS 3903(str)@* 3904Resize display. This capability has the desired width and height as 3905arguments. SunView(tm) example: @samp{\E[8;%d;%dt}. 3906 3907@item NF 3908(bool)@* 3909Terminal doesn't need flow control. Send ^S and ^Q direct to 3910the application. Same as @code{flow off}. The opposite of this 3911capability is @samp{nx}. 3912 3913@item G0 3914(bool)@* 3915Terminal can deal with ISO 2022 font selection sequences. 3916 3917@item S0 3918(str)@* 3919Switch charset @samp{G0} to the specified charset. Default 3920is @samp{\E(%.}. 3921 3922@item E0 3923(str)@* 3924Switch charset @samp{G0} back to standard charset. Default 3925is @samp{\E(B}. 3926 3927@item C0 3928(str)@* 3929Use the string as a conversion table for font 0. See 3930the @samp{ac} capability for more details. 3931 3932@item CS 3933(str)@* 3934Switch cursor-keys to application mode. 3935 3936@item CE 3937(str)@* 3938Switch cursor-keys to cursor mode. 3939 3940@item AN 3941(bool)@* 3942Enable autonuke for displays of this terminal type. 3943(@pxref{Autonuke}). 3944 3945@item OL 3946(num)@* 3947Set the output buffer limit. See the @samp{obuflimit} command 3948(@pxref{Obuflimit}) for more details. 3949 3950@item KJ 3951(str)@* 3952Set the encoding of the terminal. See the @samp{encoding} command 3953(@pxref{Character Processing}) for valid encodings. 3954 3955@item AF 3956(str)@* 3957Change character foreground color in an ANSI conform way. This 3958capability will almost always be set to @samp{\E[3%dm} 3959(@samp{\E[3%p1%dm} on terminfo machines). 3960 3961@item AB 3962(str)@* 3963Same as @samp{AF}, but change background color. 3964 3965@item AX 3966(bool)@* 3967Does understand ANSI set default fg/bg color (@samp{\E[39m / \E[49m}). 3968 3969@item XC 3970(str)@* 3971Describe a translation of characters to strings depending on the 3972current font. (@pxref{Character Translation}). 3973 3974@item XT 3975(bool)@* 3976Terminal understands special xterm sequences (OSC, mouse tracking). 3977 3978@item C8 3979(bool)@* 3980Terminal needs bold to display high-intensity colors (e.g. Eterm). 3981 3982@item TF 3983(bool)@* 3984Add missing capabilities to the termcap/info entry. (Set by default). 3985@end table 3986 3987@node Autonuke, Obuflimit, Special Capabilities, Termcap 3988@section Autonuke 3989@deffn Command autonuke @var{state} 3990(none)@* 3991Sets whether a clear screen sequence should nuke all the output 3992that has not been written to the terminal. @xref{Obuflimit}. 3993This property is set per display, not per window. 3994@end deffn 3995 3996@deffn Command defautonuke @var{state} 3997(none)@* 3998Same as the @code{autonuke} command except that the default setting for 3999new displays is also changed. Initial setting is @code{off}. 4000Note that you can use the special @code{AN} terminal capability if you 4001want to have a terminal type dependent setting. 4002@end deffn 4003 4004@node Obuflimit, Character Translation, Autonuke, Termcap 4005@section Obuflimit 4006@deffn Command obuflimit [@var{limit}] 4007(none)@* 4008If the output buffer contains more bytes than the specified limit, no 4009more data will be read from the windows. The default value is 256. If 4010you have a fast display (like @code{xterm}), you can set it to some 4011higher value. If no argument is specified, the current setting is displayed. 4012This property is set per display, not per window. 4013@end deffn 4014 4015@deffn Command defobuflimit @var{limit} 4016(none)@* 4017Same as the @code{obuflimit} command except that the default setting for new 4018displays is also changed. Initial setting is 256 bytes. Note that you can use 4019the special @code{OL} terminal capability if you want to have a terminal 4020type dependent limit. 4021@end deffn 4022 4023@node Character Translation, , Obuflimit, Termcap 4024@section Character Translation 4025@code{Screen} has a powerful mechanism to translate characters to 4026arbitrary strings depending on the current font and terminal type. 4027Use this feature if you want to work with a common standard character 4028set (say ISO8851-latin1) even on terminals that scatter the more 4029unusual characters over several national language font pages. 4030 4031Syntax: 4032 4033@example 4034 XC=@var{<charset-mapping>}@{,,@var{<charset-mapping>}@} 4035 @var{<charset-mapping>} := @var{<designator>}@var{<template>}@{,@var{<mapping>}@} 4036 @var{<mapping>} := @var{<char-to-be-mapped>}@var{<template-arg>} 4037@end example 4038 4039The things in braces may be repeated any number of times. 4040 4041A @var{<charset-mapping>} tells screen how to map characters 4042in font @var{<designator>} (@samp{B}: Ascii, @samp{A}: UK, 4043@samp{K}: german, etc.) 4044to strings. Every @var{<mapping>} describes to what string a single 4045character will be translated. A template mechanism is used, as 4046most of the time the codes have a lot in common (for example 4047strings to switch to and from another charset). Each occurrence 4048of @samp{%} in @var{<template>} gets substituted with the 4049@var{template-arg} 4050specified together with the character. If your strings are not 4051similar at all, then use @samp{%} as a template and place the full 4052string in @var{<template-arg>}. A quoting mechanism was added to make 4053it possible to use a real @samp{%}. The @samp{\} character quotes the 4054special characters @samp{\}, @samp{%}, and @samp{,}. 4055 4056Here is an example: 4057 4058@example 4059 termcap hp700 'XC=B\E(K%\E(B,\304[,\326\\\\,\334]' 4060@end example 4061 4062This tells @code{screen}, how to translate ISOlatin1 (charset @samp{B}) 4063upper case umlaut characters on a @code{hp700} terminal that has a 4064german charset. @samp{\304} gets translated to 4065@samp{\E(K[\E(B} and so on. 4066Note that this line gets parsed *three* times before the internal 4067lookup table is built, therefore a lot of quoting is needed to 4068create a single @samp{\}. 4069 4070Another extension was added to allow more emulation: If a mapping 4071translates the unquoted @samp{%} char, it will be sent to the terminal 4072whenever screen switches to the corresponding @var{<designator>}. 4073In this 4074special case the template is assumed to be just @samp{%} because 4075the charset switch sequence and the character mappings normally 4076haven't much in common. 4077 4078This example shows one use of the extension: 4079@example 4080 termcap xterm 'XC=K%,%\E(B,[\304,\\\\\326,]\334' 4081@end example 4082 4083Here, a part of the german (@samp{K}) charset is emulated on an xterm. 4084If screen has to change to the @samp{K} charset, @samp{\E(B} will be 4085sent 4086to the terminal, i.e. the ASCII charset is used instead. The 4087template is just @samp{%}, so the mapping is straightforward: 4088@samp{[} to @samp{\304}, @samp{\} to @samp{\326}, and @samp{]} to 4089@samp{\334}. 4090 4091@node Message Line, Logging, Termcap, Top 4092@chapter The Message Line 4093@cindex message line 4094 4095@code{screen} displays informational messages and other diagnostics in a 4096@dfn{message line} at the bottom of the screen. If your terminal has a 4097status line defined in its termcap, screen will use this for displaying 4098its messages, otherwise the last line of the screen will be temporarily 4099overwritten and output will be momentarily interrupted. The message 4100line is automatically removed after a few seconds delay, but it can also 4101be removed early (on terminals without a status line) by beginning to 4102type. 4103 4104@menu 4105* Privacy Message:: Using the message line from your program. 4106* Hardware Status Line:: Use the terminal's hardware status line. 4107* Last Message:: Redisplay the last message. 4108* Message Wait:: Control how long messages are displayed. 4109@end menu 4110 4111@node Privacy Message, Hardware Status Line, , Message Line 4112@section Using the message line from your program 4113The message line facility can be used by an application running in the 4114current window by means of the ANSI @dfn{Privacy message} control 4115sequence. For instance, from within the shell, try something like: 4116 4117@example 4118echo "@value{esc}^Hello world from window $WINDOW@value{esc}\" 4119@end example 4120 4121where @samp{@value{esc}} is ASCII ESC and @samp{^} is a literal caret or 4122up-arrow. 4123 4124@node Hardware Status Line, Last Message, Privacy Message, Message Line 4125@section Hardware Status Line 4126@deffn Command hardstatus [state] 4127@deffnx Command hardstatus [@code{always}]@code{lastline}|@code{message}|@code{ignore} [string] 4128@deffnx Command hardstatus @code{string} [string] 4129(none)@* 4130This command configures the use and emulation of the terminal's 4131hardstatus line. The first form toggles whether @code{screen} 4132will use the hardware status line to display messages. If the 4133flag is set to @samp{off}, these messages 4134are overlaid in reverse video mode at the display line. The default 4135setting is @samp{on}. 4136 4137The second form tells screen what to do if the terminal doesn't 4138have a hardstatus line (i.e. the termcap/terminfo capabilities 4139"hs", "ts", "fs" and "ds" are not set). If the type 4140@code{lastline} is used, screen will reserve the last line of the 4141display for the hardstatus. @code{message} uses 4142@code{screen}'s message mechanism and 4143@code{ignore} tells @code{screen} never to display the hardstatus. 4144If you prepend the word @code{always} to the type (e.g., @code{alwayslastline}), @code{screen} will use 4145the type even if the terminal supports a hardstatus line. 4146 4147The third form specifies the contents of the hardstatus line. 4148@code{%h} is used as default string, i.e. the stored hardstatus of the 4149current window (settable via @samp{ESC]0;^G} or @samp{ESC_\\}) is 4150displayed. 4151You can customize this to any string you like including 4152string escapes (@pxref{String Escapes}). 4153If you leave 4154out the argument @var{string}, the current string is displayed. 4155 4156You can mix the second and third form by providing the string as 4157additional argument. 4158@end deffn 4159 4160@node Last Message, Message Wait, Hardware Status Line, Message Line 4161@section Display Last Message 4162@kindex m 4163@kindex C-m 4164@deffn Command lastmsg 4165(@kbd{C-a m}, @kbd{C-a C-m})@* 4166Repeat the last message displayed in the message line. Useful if you're 4167typing when a message appears, because (unless your terminal has a 4168hardware status line) the message goes away when you press a key. 4169@end deffn 4170 4171@node Message Wait, , Last Message, Message Line 4172@section Message Wait 4173@deffn Command msgminwait sec 4174(none)@* 4175Defines the time @code{screen} delays a new message when another is 4176currently displayed. Defaults to 1 second. 4177@end deffn 4178 4179@deffn Command msgwait sec 4180(none)@* 4181Defines the time a message is displayed, if @code{screen} is not 4182disturbed by other activity. Defaults to 5 seconds. 4183@end deffn 4184 4185@node Logging, Startup, Message Line, Top 4186@chapter Logging 4187 4188This section describes the commands for keeping a record of your session. 4189 4190@menu 4191* Hardcopy:: Dump the current screen to a file 4192* Log:: Log the output of a window to a file 4193@end menu 4194 4195@node Hardcopy, Log, , Logging 4196@section hardcopy 4197@kindex h 4198@kindex C-h 4199@deffn Command hardcopy [-h] [@var{file}] 4200(@kbd{C-a h}, @kbd{C-a C-h})@* 4201Writes out the currently displayed image to the file @var{file}, or, 4202if no filename is specified, to @file{hardcopy.@var{n}} 4203in the default directory, where @var{n} is the number of the 4204current window. This either appends or overwrites the file if it 4205exists, as determined by the @code{hardcopy_append} command. 4206If the option @code{-h} is specified, dump also the 4207contents of the scrollback buffer. 4208@end deffn 4209 4210@deffn Command hardcopy_append state 4211(none)@* 4212If set to @samp{on}, @code{screen} will append to the 4213@file{hardcopy.@var{n}} files created by the command @code{hardcopy}; 4214otherwise, these files are overwritten each time. 4215@end deffn 4216 4217@deffn Command hardcopydir directory 4218(none)@* 4219Defines a directory where hardcopy files will be placed. 4220If unset hardcopys are dumped in screen's current working 4221directory. 4222@end deffn 4223 4224@node Log, , Hardcopy, Logging 4225@section log 4226 4227@deffn Command deflog state 4228(none)@* 4229Same as the @code{log} command except that the default setting for new 4230windows is changed. Initial setting is `off'. 4231@end deffn 4232 4233@kindex H 4234@deffn Command log [state] 4235(@kbd{C-a H})@* 4236Begins/ends logging of the current window to the file 4237@file{screenlog.@var{n}} in the window's default directory, where 4238@var{n} is the number of the current window. 4239This filename can be changed with the @samp{logfile} command. 4240If no parameter is given, 4241the logging state is toggled. The session log is 4242appended to the previous contents of the file if it already exists. The 4243current contents and the contents of the scrollback history are not 4244included in the session log. Default is @samp{off}. 4245@end deffn 4246 4247@deffn Command logfile filename 4248@deffnx Command logfile flush secs 4249(none)@* 4250Defines the name the logfiles will get. The default is @samp{screenlog.%n}. 4251The second form changes the number of seconds @code{screen} 4252will wait before flushing the logfile buffer to the file-system. The 4253default value is 10 seconds. 4254@end deffn 4255 4256@deffn Command logtstamp [state] 4257@deffnx Command logtstamp @code{after} secs 4258@deffnx Command logtstamp @code{string} string 4259(none)@* 4260This command controls logfile time-stamp mechanism of screen. If 4261time-stamps are turned @samp{on}, screen adds a string containing 4262the current time to the logfile after two minutes of inactivity. 4263When output continues and more than another two minutes have passed, 4264a second time-stamp is added to document the restart of the 4265output. You can change this timeout with the second form 4266of the command. The third form is used for customizing the time-stamp 4267string (@samp{-- %n:%t -- time-stamp -- %M/%d/%y %c:%s --\n} by 4268default). 4269@end deffn 4270 4271@node Startup, Miscellaneous, Logging, Top 4272@chapter Startup 4273 4274This section describes commands which are only useful in the 4275@file{.screenrc} file, for use at startup. 4276 4277@menu 4278* echo:: Display a message. 4279* sleep:: Pause execution of the @file{.screenrc}. 4280* Startup Message:: Control display of the copyright notice. 4281@end menu 4282 4283@node echo, sleep, , Startup 4284@section echo 4285@deffn Command echo [@samp{-n}] message 4286(none)@* 4287The echo command may be used to annoy @code{screen} users with a 4288'message of the day'. Typically installed in a global screenrc. 4289The option @samp{-n} may be used to suppress the line feed. 4290See also @code{sleep}. 4291Echo is also useful for online checking of environment variables. 4292@end deffn 4293 4294@node sleep, Startup Message, echo, Startup 4295@section sleep 4296@deffn Command sleep num 4297(none)@* 4298This command will pause the execution of a .screenrc file for @var{num} 4299seconds. Keyboard activity will end the sleep. It may be used to give 4300users a chance to read the messages output by @code{echo}. 4301@end deffn 4302 4303@node Startup Message, , sleep, Startup 4304@section Startup Message 4305@deffn Command startup_message state 4306(none)@* 4307Select whether you want to see the copyright notice during startup. 4308Default is @samp{on}, as you probably noticed. 4309@end deffn 4310 4311@node Miscellaneous, String Escapes, Startup, Top 4312@chapter Miscellaneous commands 4313 4314The commands described here do not fit well under any of the other 4315categories. 4316 4317@menu 4318* At:: Execute a command at other displays or windows. 4319* Break:: Send a break signal to the window. 4320* Debug:: Suppress/allow debugging output. 4321* License:: Display the disclaimer page. 4322* Nethack:: Use @code{nethack}-like error messages. 4323* Nonblock:: Disable flow-control to a display. 4324* Number:: Change the current window's number. 4325* Silence:: Notify on inactivity. 4326* Time:: Display the time and load average. 4327* Verbose:: Display window creation commands. 4328* Version:: Display the version of @code{screen}. 4329* Zombie:: Keep dead windows. 4330* Printcmd:: Set command for VT100 printer port emulation. 4331* Sorendition:: Change the text highlighting method. 4332* Attrcolor:: Map attributes to colors. 4333* Setsid:: Change process group management. 4334* Eval:: Parse and execute arguments. 4335* Maxwin:: Set the maximum window number. 4336* Backtick:: Program a command for a backtick string escape. 4337* Screen Saver:: Define a screen safer. 4338* Zmodem:: Define how screen treats zmodem requests. 4339@end menu 4340 4341@node At, Break, , Miscellaneous 4342@section At 4343@deffn Command at [identifier][#|*|%] command [args] 4344(none)@* 4345Execute a command at other displays or windows as if it had been entered there. 4346@code{At} changes the context (the `current window' or `current display' 4347setting) of the command. If the first parameter describes a non-unique context, 4348the command will be executed multiple times. If the first parameter is of the 4349form @samp{@var{identifier}*} then identifier is matched against user names. 4350The command is executed once for each display of the selected user(s). 4351If the first parameter is of the form @samp{@var{identifier}%} identifier is 4352matched against displays. Displays are named after the ttys they attach. The 4353prefix @samp{/dev/} or @samp{/dev/tty} may be omitted from the identifier. 4354If @var{identifier} has a @code{#} or nothing appended it is matched against 4355window numbers and titles. Omitting an identifier in front of the @code{#}, 4356@code{*} or @code{%} character selects all users, displays or windows because 4357a prefix-match is performed. Note that on the affected display(s) a short 4358message will describe what happened. 4359Note that the @code{#} character works as a comment introducer when it is 4360preceded by whitespace. This can be escaped by prefixing @code{#} with a 4361@code{\}. 4362Permission is checked for the initiator of the @code{at} command, not for the 4363owners of the affected display(s). 4364Caveat: 4365When matching against windows, the command is executed at least 4366once per window. Commands that change the internal arrangement of windows 4367(like @code{other}) may be called again. In shared windows the command will 4368be repeated for each attached display. Beware, when issuing toggle commands 4369like @code{login}! 4370Some commands (e.g. @code{\*Qprocess}) require 4371that a display is associated with the target windows. These commands may not 4372work correctly under @code{at} looping over windows. 4373@end deffn 4374 4375@node Break, Debug, At, Miscellaneous 4376@section Break 4377@deffn Command break [duration] 4378(none)@* 4379Send a break signal for @var{duration}*0.25 seconds to this window. 4380For non-Posix systems the time interval is rounded up to full seconds. 4381Most useful if a character device is attached to the window rather than 4382a shell process (@pxref{Window Types}). The maximum duration of 4383a break signal is limited to 15 seconds. 4384@end deffn 4385 4386@deffn Command pow_break 4387(none)@* 4388Reopen the window's terminal line and send a break condition. 4389@end deffn 4390 4391@deffn Command breaktype [tcsendbreak|TIOCSBRK|TCSBRK] 4392(none)@* 4393Choose one of the available methods of generating a break signal for 4394terminal devices. This command should affect the current window only. 4395But it still behaves identical to @code{defbreaktype}. This will be changed in 4396the future. 4397Calling @code{breaktype} with no parameter displays the break setting for the 4398current window. 4399@end deffn 4400 4401@deffn Command defbreaktype [tcsendbreak|TIOCSBRK|TCSBRK] 4402(none)@* 4403Choose one of the available methods of generating a break signal for 4404terminal devices opened afterwards. The preferred methods are 4405@code{tcsendbreak} and 4406@code{TIOCSBRK}. The third, @code{TCSBRK}, blocks the complete @code{screen} 4407session for the duration of the break, but it may be the only way to 4408generate long breaks. @code{tcsendbreak} and @code{TIOCSBRK} may or may not 4409produce long breaks with spikes (e.g. 4 per second). This is not only system 4410dependant, this also differs between serial board drivers. 4411Calling @code{defbreaktype} with no parameter displays the current setting. 4412@end deffn 4413 4414@node Debug, License, Break, Miscellaneous 4415@section Debug 4416@deffn Command debug [on|off] 4417(none)@* 4418Turns runtime debugging on or off. If @code{screen} has been compiled with 4419option @code{-DDEBUG} debugging is available and is turned on per default. 4420Note that this command only affects debugging output from the main 4421@samp{SCREEN} process correctly. Debug output from attacher processes can only 4422be turned off once and forever. 4423@end deffn 4424 4425@node License, Nethack, Debug, Miscellaneous 4426@section License 4427@deffn Command license 4428(none)@* 4429Display the disclaimer page. This is done whenever @code{screen} is 4430started without options, which should be often enough. 4431@end deffn 4432 4433@node Nethack, Nonblock, License, Miscellaneous 4434@section Nethack 4435@deffn Command nethack state 4436(none)@* 4437Changes the kind of error messages used by @code{screen}. When you are 4438familiar with the game @code{nethack}, you may enjoy the nethack-style 4439messages which will often blur the facts a little, but are much funnier 4440to read. Anyway, standard messages often tend to be unclear as well. 4441 4442This option is only available if @code{screen} was compiled with the 4443NETHACK flag defined (@pxref{Installation}). The default setting is then 4444determined by the presence of the environment variable 4445@code{$NETHACKOPTIONS}. 4446@end deffn 4447 4448@node Nonblock, Number, Nethack, Miscellaneous 4449@section Nonblock 4450@deffn Command nonblock [@var{state}|@var{numsecs}] 4451Tell screen how to deal with user interfaces (displays) that cease to 4452accept output. This can happen if a user presses ^S or a TCP/modem 4453connection gets cut but no hangup is received. If nonblock is 4454@code{off} (this is the default) screen waits until the display 4455restarts to accept the output. If nonblock is @code{on}, screen 4456waits until the timeout is reached (@code{on} is treated as 1s). If the 4457display still doesn't receive characters, screen will consider 4458it ``blocked'' and stop sending characters to it. If at 4459some time it restarts to accept characters, screen will unblock 4460the display and redisplay the updated window contents. 4461@end deffn 4462 4463@deffn Command defnonblock @var{state}|@var{numsecs} 4464Same as the @code{nonblock} command except that the default setting for 4465displays is changed. Initial setting is @code{off}. 4466@end deffn 4467 4468@node Number, Silence, Nonblock, Miscellaneous 4469@section Number 4470@kindex N 4471@deffn Command number [@var{n}] 4472(@kbd{C-a N})@* 4473Change the current window's number. If the given number @var{n} is already 4474used by another window, both windows exchange their numbers. If no argument is 4475specified, the current window number (and title) is shown. 4476@end deffn 4477 4478@node Silence, Time, Number, Miscellaneous 4479@section Silence 4480@deffn Command silence [@var{state}|@var{sec}] 4481(none)@* 4482Toggles silence monitoring of windows. When silence is turned on and an 4483affected window is switched into the background, you will receive the 4484silence notification message in the status line after a specified period 4485of inactivity (silence). The default timeout can be changed with the 4486@code{silencewait} command or by specifying a number of seconds instead of 4487@code{on} or @code{off}. Silence is initially off for all windows. 4488@end deffn 4489 4490@deffn Command defsilence state 4491(none)@* 4492Same as the @code{silence} command except that the default setting for 4493new windows is changed. Initial setting is `off'. 4494@end deffn 4495 4496@deffn Command silencewait @var{seconds} 4497(none)@* 4498Define the time that all windows monitored for silence should wait 4499before displaying a message. Default is 30 seconds. 4500@end deffn 4501 4502@node Time, Verbose, Silence, Miscellaneous 4503@section Time 4504@kindex t 4505@kindex C-t 4506@deffn Command time [@var{string}] 4507(@kbd{C-a t}, @kbd{C-a C-t})@* 4508Uses the message line to display the time of day, the host name, and the 4509load averages over 1, 5, and 15 minutes (if this is available on your 4510system). For window-specific information use @code{info} (@pxref{Info}). 4511If a @var{string} is specified, it changes the format of the time report 4512like it is described in the string escapes chapter (@pxref{String Escapes}). Screen uses a default of @samp{%c:%s %M %d %H%? %l%?}. 4513@end deffn 4514 4515@node Verbose, Version, Time, Miscellaneous 4516@section Verbose 4517@deffn Command verbose [on|off] 4518If verbose is switched on, the command name is echoed, whenever a window 4519is created (or resurrected from zombie state). Default is off. 4520Without parameter, the current setting is shown. 4521@end deffn 4522 4523@node Version, Zombie, Verbose, Miscellaneous 4524@section Version 4525@kindex v 4526@deffn Command version 4527(@kbd{C-a v})@* 4528Display the version and modification date in the message line. 4529@end deffn 4530 4531@node Zombie, Printcmd, Version, Miscellaneous 4532@section Zombie 4533@deffn Command zombie [@var{keys}] 4534@deffnx Command defzombie [@var{keys}] 4535(none)@* 4536Per default windows are removed from the window list as soon as the 4537windows process (e.g. shell) exits. When a string of two keys is 4538specified to the zombie command, `dead' windows will remain in the list. 4539The @code{kill} command may be used to remove the window. Pressing the first key 4540in the dead window has the same effect. Pressing the second key, however, 4541screen will attempt to resurrect the window. The process that was initially 4542running in the window will be launched again. Calling @code{zombie} without 4543parameters will clear the zombie setting, thus making windows disappear when 4544the process terminates. 4545 4546As the zombie setting is affected globally for all windows, this command 4547should only be called @code{defzombie}. Until we need this as a per window 4548setting, the commands @code{zombie} and @code{defzombie} are synonymous. 4549@end deffn 4550 4551@node Printcmd, Sorendition, Zombie, Miscellaneous 4552@section Printcmd 4553@deffn Command printcmd [@var{cmd}] 4554(none)@* 4555If @var{cmd} is not an empty string, screen will not use the terminal 4556capabilities @code{po/pf} for printing if it detects an ansi print 4557sequence @code{ESC [ 5 i}, but pipe the output into @var{cmd}. 4558This should normally be a command like @samp{lpr} or 4559@samp{cat > /tmp/scrprint}. 4560@code{Printcmd} without an argument displays the current setting. 4561The ansi sequence @code{ESC \} ends printing and closes the pipe. 4562 4563Warning: Be careful with this command! If other user have write 4564access to your terminal, they will be able to fire off print commands. 4565@end deffn 4566 4567@node Sorendition, Attrcolor, Printcmd, Miscellaneous 4568@section Sorendition 4569@deffn Command sorendition [@var{attr} [@var{color}]] 4570(none)@* 4571Change the way screen does highlighting for text marking and printing 4572messages. 4573See the chapter 4574about string escapes (@pxref{String Escapes}) for the syntax of 4575the modifiers. The default is currently @samp{=s dd} (standout, 4576default colors). 4577@end deffn 4578 4579@node Attrcolor, Setsid, Sorendition, Miscellaneous 4580@section Attrcolor 4581@deffn Command attrcolor @var{attrib} [@var{attribute/color-modifier}] 4582(none)@* 4583This command can be used to highlight attributes by changing the color of 4584the text. If the attribute 4585@var{attrib} 4586is in use, the specified attribute/color modifier is also applied. If no 4587modifier is given, the current one is deleted. See the chapter 4588about string escapes (@pxref{String Escapes}) for the syntax of 4589the modifier. Screen understands two pseudo-attributes, @code{i} 4590stands for high-intensity foreground color and @code{I} for 4591high-intensity background color. 4592 4593@noindent 4594Examples: 4595@table @code 4596@item attrcolor b "R" 4597Change the color to bright red if bold text is to be printed. 4598@item attrcolor u "-u b" 4599Use blue text instead of underline. 4600@item attrcolor b ".I" 4601Use bright colors for bold text. Most terminal emulators do this 4602already. 4603@item attrcolor i "+b" 4604Make bright colored text also bold. 4605@end table 4606@end deffn 4607 4608@node Setsid, Eval, Attrcolor, Miscellaneous 4609@section Setsid 4610@deffn Command setsid state 4611(none)@* 4612Normally screen uses different sessions and process groups for 4613the windows. If setsid is turned @code{off}, this is not done 4614anymore and all windows will be in the same process group as the 4615screen backend process. This also breaks job-control, so be careful. 4616The default is @code{on}, of course. This command is probably useful 4617only in rare circumstances. 4618@end deffn 4619 4620@node Eval, Maxwin, Setsid, Miscellaneous 4621@section Eval 4622@deffn Command eval @var{command1} [@var{command2} ...] 4623(none)@* 4624Parses and executes each argument as separate command. 4625@end deffn 4626 4627@node Maxwin, Backtick, Eval, Miscellaneous 4628@section Maxwin 4629@deffn Command maxwin @var{n} 4630(none)@* 4631Set the maximum window number screen will create. Doesn't affect 4632already existing windows. The number may only be decreased. 4633@end deffn 4634 4635@node Backtick, Screen Saver, Maxwin, Miscellaneous 4636@section Backtick 4637@deffn Command backtick @var{id} @var{lifespan} @var{autorefresh} @var{command} [@var{args}] 4638@deffnx Command backtick @var{id} 4639(none)@* 4640Program the backtick command with the numerical id @var{id}. 4641The output of such a command is used for substitution of the 4642@code{%`} string escape (@pxref{String Escapes}). 4643The specified @var{lifespan} is the number 4644of seconds the output is considered valid. After this time, the 4645command is run again if a corresponding string escape is encountered. 4646The @var{autorefresh} parameter triggers an 4647automatic refresh for caption and hardstatus strings after the 4648specified number of seconds. Only the last line of output is used 4649for substitution. 4650 4651If both the @var{lifespan} and the @var{autorefresh} parameters 4652are zero, the backtick program is expected to stay in the 4653background and generate output once in a while. 4654In this case, the command is executed right away and screen stores 4655the last line of output. If a new line gets printed screen will 4656automatically refresh the hardstatus or the captions. 4657 4658The second form of the command deletes the backtick command 4659with the numerical id @var{id}. 4660@end deffn 4661 4662@node Screen Saver, Zmodem, Backtick, Miscellaneous 4663@section Screen Saver 4664@deffn Command idle [@var{timeout} [@var{cmd} @var{args}]] 4665(none)@* 4666Sets a command that is run after the specified number of 4667seconds inactivity is reached. This command will normally 4668be the @code{blanker} command to create a screen blanker, but 4669it can be any screen command. If no command is specified, 4670only the timeout is set. A timeout of zero (ot the special 4671timeout @code{off}) disables the timer. If no arguments are 4672given, the current settings are displayed. 4673@end deffn 4674 4675@deffn Command blanker 4676(none)@* 4677Activate the screen blanker. First the screen is cleared. 4678If no blanker program is defined, the cursor is turned 4679off, otherwise, the program is started and it's output is 4680written to the screen. The screen blanker is killed with 4681the first keypress, the read key is discarded. 4682 4683This command is normally used together with the @code{idle} 4684command. 4685@end deffn 4686 4687@deffn Command blankerprg [@var{program args}] 4688Defines a blanker program. Disables the blanker program if 4689no arguments are given. 4690@end deffn 4691 4692@node Zmodem, , Screen Saver, Miscellaneous 4693@section Zmodem 4694@deffn Command zmodem [off|auto|catch|pass] 4695@deffnx Command zmodem sendcmd [string] 4696@deffnx Command zmodem recvcmd [string] 4697(none)@* 4698Define zmodem support for screen. Screen understands two 4699different modes when it detects a zmodem request: @code{pass} 4700and @code{catch}. If the mode is set to @code{pass}, screen will 4701relay all data to the attacher until the end of the 4702transmission is reached. In @code{catch} mode screen acts as a 4703zmodem endpoint and starts the corresponding rz/sz commands. 4704If the mode is set to @code{auto}, screen will use @code{catch} if 4705the window is a tty (e.g. a serial line), otherwise it 4706will use @code{pass}. 4707 4708You can define the templates screen uses in @code{catch} mode 4709via the second and the third form. 4710 4711Note also that this is an experimental feature. 4712@end deffn 4713 4714@node String Escapes, Environment, Miscellaneous, Top 4715@chapter String Escapes 4716@cindex string escapes 4717Screen provides an escape mechanism to insert information like the 4718current time into messages or file names. The escape character 4719is @code{%} with one exception: inside of a window's hardstatus 4720@code{^%} (@code{^E}) is used instead. 4721 4722Here is the full list of supported escapes: 4723 4724@table @code 4725@item % 4726the escape character itself 4727@item a 4728either @code{am} or @code{pm} 4729@item A 4730either @code{AM} or @code{PM} 4731@item c 4732current time @code{HH:MM} in 24h format 4733@item C 4734current time @code{HH:MM} in 12h format 4735@item d 4736day number 4737@item D 4738weekday name 4739@item f 4740flags of the window 4741@item F 4742sets %? to true if the window has the focus 4743@item h 4744hardstatus of the window 4745@item H 4746hostname of the system 4747@item l 4748current load of the system 4749@item m 4750month number 4751@item M 4752month name 4753@item n 4754window number 4755@item s 4756seconds 4757@item t 4758window title 4759@item u 4760all other users on this window 4761@item w 4762all window numbers and names. With @code{-} quailifier: up to the current 4763window; with @code{+} qualifier: starting with the window after the current 4764one. 4765@item W 4766all window numbers and names except the current one 4767@item y 4768last two digits of the year number 4769@item Y 4770full year number 4771@item ? 4772the part to the next @code{%?} is displayed only if a @code{%} escape 4773inside the part expands to a non-empty string 4774@item : 4775else part of @code{%?} 4776@item = 4777pad the string to the display's width (like TeX's hfill). If a 4778number is specified, pad to the percentage of the window's width. 4779A @code{0} qualifier tells screen to treat the number as absolute position. 4780You can specify to pad relative to the last absolute pad position 4781by adding a @code{+} qualifier or to pad relative to the right margin 4782by using @code{-}. The padding truncates the string if the specified 4783position lies before the current position. Add the @code{L} qualifier 4784to change this. 4785@item < 4786same as @code{%=} but just do truncation, do not fill with spaces 4787@item > 4788mark the current text position for the next truncation. When 4789screen needs to do truncation, it tries to do it in a way that 4790the marked position gets moved to the specified percentage of 4791the output area. (The area starts from the last absolute pad 4792position and ends with the position specified by the truncation 4793operator.) The @code{L} qualifier tells screen to mark the truncated 4794parts with @samp{...}. 4795@item @{ 4796attribute/color modifier string terminated by the next @code{@}} 4797@item ` 4798Substitute with the output of a `backtick' command. The length 4799qualifier is misused to identify one of the commands. @xref{Backtick}. 4800@end table 4801The @code{c} and @code{C} escape may be qualified with a @code{0} to 4802make screen use 4803zero instead of space as fill character. 4804The @code{n} and 4805@code{=} escapes understand 4806a length qualifier (e.g. @code{%3n}), @code{D} and @code{M} can be 4807prefixed with @code{L} to generate long names, @code{w} and 4808@code{W} also show the window flags if @code{L} is given. 4809 4810An attribute/color modifier is is used to change the attributes or the 4811color settings. Its format 4812is @samp{[attribute modifier] [color description]}. The attribute modifier 4813must be prefixed by a change type indicator if it can be confused with 4814a color desciption. The following change types are known: 4815@table @code 4816@item + 4817add the specified set to the current attributes 4818@item - 4819remove the set from the current attributes 4820@item ! 4821invert the set in the current attributes 4822@item = 4823change the current attributes to the specified set 4824@end table 4825The attribute set can either be specified as a hexadecimal number or 4826a combination of the following letters: 4827@table @code 4828@item d 4829dim 4830@item u 4831underline 4832@item b 4833bold 4834@item r 4835reverse 4836@item s 4837standout 4838@item B 4839blinking 4840@end table 4841Colors are coded either as a hexadecimal number or two letters specifying 4842the desired background and foreground color (in that order). The following 4843colors are known: 4844@table @code 4845@item k 4846black 4847@item r 4848red 4849@item g 4850green 4851@item y 4852yellow 4853@item b 4854blue 4855@item m 4856magenta 4857@item c 4858cyan 4859@item w 4860white 4861@item d 4862default color 4863@item . 4864leave color unchanged 4865@end table 4866The capitalized versions of the letter specify bright colors. You can also 4867use the pseudo-color @samp{i} to set just the brightness and leave the color 4868unchanged. 4869 4870A one digit/letter color description is treated as foreground or 4871background color dependant on the current attributes: if reverse mode is 4872set, the background color is changed instead of the foreground color. 4873If you don't like this, prefix the color with a @samp{.}. If you want 4874the same behaviour for two-letter color descriptions, also prefix them 4875with a @samp{.}. 4876 4877As a special case, @samp{%@{-@}} restores the attributes and colors that 4878were set before the last change was made (i.e. pops one level of the 4879color-change stack). 4880 4881@noindent 4882Examples: 4883@table @samp 4884@item G 4885set color to bright green 4886@item +b r 4887use bold red 4888@item = yd 4889clear all attributes, write in default color on yellow background. 4890@item %-Lw%@{= BW@}%50>%n%f* %t%@{-@}%+Lw%< 4891The available windows centered at the current win dow and truncated to 4892the available width. The current window is displayed white on blue. 4893This can be used with @samp{hardstatus alwayslastline}. 4894@item %?%F%@{.R.@}%?%3n %t%? [%h]%? 4895The window number and title and the window's hardstatus, if one is set. 4896Also use a red background if this is the active focus. 4897Useful for @samp{caption string}. 4898@end table 4899 4900 4901@node Environment, Files, String Escapes, Top 4902@chapter Environment Variables 4903@cindex environment 4904 4905@table @code 4906@item COLUMNS 4907Number of columns on the terminal (overrides termcap entry). 4908 4909@item HOME 4910Directory in which to look for .screenrc. 4911 4912@item LINES 4913Number of lines on the terminal (overrides termcap entry). 4914 4915@item LOCKPRG 4916Screen lock program. 4917 4918@item NETHACKOPTIONS 4919Turns on @code{nethack} option. 4920 4921@item PATH 4922Used for locating programs to run. 4923 4924@item SCREENCAP 4925For customizing a terminal's @code{TERMCAP} value. 4926 4927@item SCREENDIR 4928Alternate socket directory. 4929 4930@item SCREENRC 4931Alternate user screenrc file. 4932 4933@item SHELL 4934Default shell program for opening windows (default @file{/bin/sh}). 4935 4936@item STY 4937Alternate socket name. If @code{screen} is invoked, and the environment variable 4938@code{STY} is set, then it creates only a window in the running @code{screen} 4939session rather than starting a new session. 4940 4941@item SYSSCREENRC 4942Alternate system screenrc file. 4943 4944@item TERM 4945Terminal name. 4946 4947@item TERMCAP 4948Terminal description. 4949 4950@item WINDOW 4951Window number of a window (at creation time). 4952@end table 4953 4954@node Files, Credits, Environment, Top 4955@chapter Files Referenced 4956@cindex files 4957 4958@table @file 4959@item .../screen-4.?.??/etc/screenrc 4960@itemx .../screen-4.?.??/etc/etcscreenrc 4961Examples in the @code{screen} distribution package for private and 4962global initialization files. 4963 4964@item @code{$SYSSCREENRC} 4965@itemx /local/etc/screenrc 4966@code{screen} initialization commands 4967 4968@item @code{$SCREENRC} 4969@itemx @code{$HOME}/.iscreenrc 4970@itemx @code{$HOME}/.screenrc 4971Read in after /local/etc/screenrc 4972 4973@item @code{$SCREENDIR}/S-@var{login} 4974 4975@item /local/screens/S-@var{login} 4976Socket directories (default) 4977 4978@item /usr/tmp/screens/S-@var{login} 4979Alternate socket directories. 4980 4981@item @var{socket directory}/.termcap 4982Written by the @code{dumptermcap} command 4983 4984@item /usr/tmp/screens/screen-exchange or 4985@itemx /tmp/screen-exchange 4986@code{screen} interprocess communication buffer 4987 4988@item hardcopy.[0-9] 4989Screen images created by the hardcopy command 4990 4991@item screenlog.[0-9] 4992Output log files created by the log command 4993 4994@item /usr/lib/terminfo/?/* or 4995@itemx /etc/termcap 4996Terminal capability databases 4997 4998@item /etc/utmp 4999Login records 5000 5001@item @code{$LOCKPRG} 5002Program for locking the terminal. 5003@end table 5004 5005@node Credits, Bugs, Files, Top 5006@chapter Credits 5007 5008@noindent 5009Authors @* 5010======= 5011 5012Originally created by Oliver Laumann, this latest version was 5013produced by Wayne Davison, Juergen Weigert and Michael Schroeder. 5014 5015@noindent 5016Contributors @* 5017============ 5018 5019@example 5020 Ken Beal (kbeal@@amber.ssd.csd.harris.com), 5021 Rudolf Koenig (rfkoenig@@informatik.uni-erlangen.de), 5022 Toerless Eckert (eckert@@informatik.uni-erlangen.de), 5023 Wayne Davison (davison@@borland.com), 5024 Patrick Wolfe (pat@@kai.com, kailand!pat), 5025 Bart Schaefer (schaefer@@cse.ogi.edu), 5026 Nathan Glasser (nathan@@brokaw.lcs.mit.edu), 5027 Larry W. Virden (lvirden@@cas.org), 5028 Howard Chu (hyc@@hanauma.jpl.nasa.gov), 5029 Tim MacKenzie (tym@@dibbler.cs.monash.edu.au), 5030 Markku Jarvinen (mta@@@{cc,cs,ee@}.tut.fi), 5031 Marc Boucher (marc@@CAM.ORG), 5032 Doug Siebert (dsiebert@@isca.uiowa.edu), 5033 Ken Stillson (stillson@@tsfsrv.mitre.org), 5034 Ian Frechett (frechett@@spot.Colorado.EDU), 5035 Brian Koehmstedt (bpk@@gnu.ai.mit.edu), 5036 Don Smith (djs6015@@ultb.isc.rit.edu), 5037 Frank van der Linden (vdlinden@@fwi.uva.nl), 5038 Martin Schweikert (schweik@@cpp.ob.open.de), 5039 David Vrona (dave@@sashimi.lcu.com), 5040 E. Tye McQueen (tye%spillman.UUCP@@uunet.uu.net), 5041 Matthew Green (mrg@@eterna.com.au), 5042 Christopher Williams (cgw@@pobox.com), 5043 Matt Mosley (mattm@@access.digex.net), 5044 Gregory Neil Shapiro (gshapiro@@wpi.WPI.EDU), 5045 Jason Merrill (jason@@jarthur.Claremont.EDU), 5046 Johannes Zellner (johannes@@zellner.org), 5047 Pablo Averbuj (pablo@@averbuj.com). 5048@end example 5049 5050@noindent 5051Version @* 5052======= 5053 5054This manual describes version @value{version} of the @code{screen} 5055program. Its roots are a merge of a custom version 2.3PR7 by Wayne 5056Davison and several enhancements to Oliver Laumann's version 2.0. 5057Note that all versions numbered 2.x are copyright by Oliver Laumann. 5058 5059See also @xref{Availability}. 5060 5061@node Bugs, Installation, Credits, Top 5062@chapter Bugs 5063@cindex bugs 5064 5065Just like any other significant piece of software, @code{screen} has a 5066few bugs and missing features. Please send in a bug report if you have 5067found a bug not mentioned here. 5068 5069@menu 5070* Known Bugs:: Problems we know about. 5071* Reporting Bugs:: How to contact the maintainers. 5072* Availability:: Where to find the lastest screen version. 5073@end menu 5074 5075@node Known Bugs, Reporting Bugs, , Bugs 5076@section Known Bugs 5077 5078@itemize @bullet 5079@item 5080@samp{dm} (delete mode) and @samp{xs} are not handled correctly (they 5081are ignored). @samp{xn} is treated as a magic-margin indicator. 5082 5083@item 5084@code{screen} has no clue about double-high or double-wide characters. 5085But this is the only area where @code{vttest} is allowed to fail. 5086 5087@item 5088It is not possible to change the environment variable @code{$TERMCAP} 5089when reattaching under a different terminal type. 5090 5091@item 5092The support of terminfo based systems is very limited. Adding extra 5093capabilities to @code{$TERMCAP} may not have any effects. 5094 5095@item 5096@code{screen} does not make use of hardware tabs. 5097 5098@item 5099@code{screen} must be installed setuid root on most systems 5100in order to be able to 5101correctly change the owner of the tty device file for each window. 5102Special permission may also be required to write the file 5103@file{/etc/utmp}. 5104 5105@item 5106Entries in @file{/etc/utmp} are not removed when @code{screen} is killed 5107with SIGKILL. This will cause some programs (like "w" or "rwho") to 5108advertise that a user is logged on who really isn't. 5109 5110@item 5111@code{screen} may give a strange warning when your tty has no utmp 5112entry. 5113 5114@item 5115When the modem line was hung up, @code{screen} may not automatically detach 5116(or quit) unless the device driver sends a HANGUP signal. To detach such a 5117@code{screen} session use the -D or -d command line option. 5118 5119@item 5120If a password is set, the command line options -d and -D still detach a 5121session without asking. 5122 5123@item 5124Both @code{breaktype} and @code{defbreaktype} change the break generating 5125method used by all terminal devices. The first should change a window 5126specific setting, where the latter should change only the default for new 5127windows. 5128 5129@item 5130When attaching to a multiuser session, the user's @file{.screenrc} file is not 5131sourced. Each users personal settings have to be included in the 5132@file{.screenrc} file from which the session is booted, or have to be 5133changed manually. 5134 5135@item 5136A weird imagination is most useful to gain full advantage of all the 5137features. 5138@end itemize 5139 5140@node Reporting Bugs, Availability, Known Bugs, Bugs 5141@section Reporting Bugs 5142@cindex bug report 5143 5144If you find a bug in @code{Screen}, please send electronic mail to 5145@w{@samp{screen@@uni-erlangen.de}}, and also to 5146@w{@samp{bug-gnu-utils@@prep.ai.mit.edu}}. Include the version number 5147of @code{Screen} which you are using. Also include in your message the 5148hardware and operating system, the compiler used to compile, a 5149description of the bug behavior, and the conditions that triggered the 5150bug. Please recompile @code{screen} with the @samp{-DDEBUG} options 5151enabled, reproduce the bug, and have a look at the debug output written to 5152the directory @file{/tmp/debug}. If necessary quote suspect passages from the 5153debug output and show the contents of your @file{config.h} if it matters. 5154 5155@node Availability, , Reporting Bugs, Bugs 5156@section Availability 5157@cindex availability 5158 5159@code{Screen} is available under the @code{GNU} copyleft. 5160 5161The latest official release of @code{screen} available via anonymous 5162ftp from @samp{prep.ai.mit.edu}, @samp{nic.funet.fi} or any other 5163@code{GNU} distribution site. The home site of 5164@code{screen} is @samp{ftp.uni-erlangen.de 5165(131.188.3.71)}, in the directory @file{pub/utilities/screen}. 5166The subdirectory @samp{private} contains the latest beta testing release. 5167If you want to help, send a note to screen@@uni-erlangen.de. 5168 5169@node Installation, Concept Index, Bugs, Top 5170@chapter Installation 5171@cindex installation 5172 5173Since @code{screen} uses pseudo-ttys, the select system call, and 5174UNIX-domain sockets/named pipes, it will not run under a system that 5175does not include these features of 4.2 and 4.3 BSD UNIX. 5176 5177@menu 5178* Socket Directory:: Where screen stores its handle. 5179* Compiling Screen:: 5180@end menu 5181 5182@node Socket Directory, 5183@section Socket Directory 5184@cindex socket directory 5185 5186The socket directory defaults either to @file{$HOME/.screen} or simply to 5187@file{/tmp/screens} or preferably to @file{/usr/local/screens} chosen at 5188compile-time. If @code{screen} is installed 5189setuid root, then the administrator should compile screen with an 5190adequate (not NFS mounted) @code{SOCKDIR}. If @code{screen} is not 5191running setuid-root, the user can specify any mode 700 directory in the 5192environment variable @code{$SCREENDIR}. 5193 5194@node Compiling Screen, , Socket Directory, Installation 5195@section Compiling Screen 5196@cindex compiling screen 5197 5198To compile and install screen: 5199 5200The @code{screen} package comes with a @code{GNU Autoconf} configuration 5201script. Before you compile the package run 5202 5203@center @code{sh ./configure} 5204 5205This will create a @file{config.h} and @file{Makefile} for your machine. 5206If @code{configure} fails for some reason, then look at the examples and 5207comments found in the @file{Makefile.in} and @file{config.h.in} templates. 5208Rename @file{config.status} to @file{config.status.@var{machine}} when 5209you want to keep configuration data for multiple architectures. Running 5210@code{sh ./config.status.@var{machine}} recreates your configuration 5211significantly faster than rerunning @code{configure}. 5212@* 5213Read through the "User Configuration" section of @file{config.h}, and verify 5214that it suits your needs. 5215A comment near the top of this section explains why it's best to 5216install screen setuid to root. 5217Check for the place for the global @file{screenrc}-file and for the socket 5218directory. 5219@* 5220Check the compiler used in @file{Makefile}, the prefix path where to install 5221@code{screen}. Then run 5222 5223@center @code{make} 5224 5225If @code{make} fails to produce one of the files @file{term.h}, @file{comm.h} 5226or @file{tty.c}, then use @code{@var{filename.x}.dist} instead. 5227For additional information about installation of @code{screen} refer to the 5228file @file{INSTALLATION}, coming with this package. 5229 5230@node Concept Index, Command Index, Installation, Top 5231@unnumbered Concept Index 5232 5233@printindex cp 5234 5235@node Command Index, Keystroke Index, Concept Index, Top 5236@unnumbered Command Index 5237 5238This is a list of all the commands supported by @code{screen}. 5239 5240@printindex fn 5241 5242@node Keystroke Index, , Command Index, Top 5243@unnumbered Keystroke Index 5244 5245This is a list of the default key bindings. 5246 5247The leading escape character (@pxref{Command Character}) has been omitted 5248from the key sequences, since it is the same for all bindings. 5249 5250@printindex ky 5251 5252@shortcontents 5253@contents 5254@bye 5255 5256