elks-enhanced - XT-Emporium

File editor

.TH SCREEN 1 "2 March 1987"
.SH NAME
screen \- screen manager with VT100/ANSI terminal emulation
.SH SYNOPSIS
.B screen
[
.B \-a
] [
.B \-f
] [
.B \-n
] [
.B \-e\fIxy\fP
] [
.BR \fIcmd args\fP ]
.br
.B screen \-r
[
.BR \fIhost.tty\fP ]
.ta .5i 1.8i
.SH DESCRIPTION
.I screen
is a full-screen window manager that
multiplexes a physical terminal between several processes (typically
interactive shells).  Each virtual terminal provides the functions
of the DEC VT100 terminal and, in addition, several control functions
from the ANSI X3.64 (ISO 6429) and ISO 2022 standards
(e.\|g. insert/delete line and support for multiple character sets).
.PP
When
.I screen
is called, it creates a single window with a shell; the pathname of the
shell is taken from the environment symbol $SHELL; if this is not
defined, \*Q/bin/sh\*U is used.
New windows can be created at any time by calling
.I screen
from within a previously created window.
The program to be started in a newly created
window and optional arguments to the program can be supplied when
.I screen
is invoked.
For instance,
.IP
screen csh
.PP
will create a window with a C-Shell and switch to that window.
When the process associated with the currently displayed window
terminates (e.\|g. ^D has been typed to a shell),
.I screen
switches to the previously displayed window;
when no more windows are left,
.I screen
exits.
.PP
When \*Q/etc/utmp\*U is writable by
.IR screen ,
an appropriate record is written to this file for each window and
removed when the window is terminated.
.PP
The
.B \-r
option is used to resume a
.I screen
session that has been \fIdetached\fP from the terminal by means
of the \*Qdetach\*U command key (see below).
This mechanism allows a user to disconnect
.I screen
together with all currently active windows from the terminal
and resume it at a later point in time, e.\|g. at a later
login session, and possibly on a different terminal.
The type of terminal on which a detached
.I screen
is resumed must of course be compatible to the type of terminal
on which
.I screen
has originally been invoked.
When more than one detached
.I screen
exist, the
.B \-r
option displays a list of
.I host.tty
pairs identifying the detached
.IR screens .
In this case an additional
.I host.tty
argument can be given to resume a specific
.I screen
session.
.SH "COMMAND KEYS"
The standard way to create a new window is to type \*QC-a c\*U (the notation
\*QC-x\*U will be used as a shorthand for Control-x in this manual; x is
an arbitrary letter).
\*QC-a c\*U creates a new window running a shell and switches to that
window immediately, regardless of the state of the process running
in the current window.
.I Screen
recognizes several such commands; each command consists of
\*QC-a\*U followed by a one-letter function.
For convenience, the letter after a \*QC-a\*U can be entered both with or
without the control key pressed (with the exception of
\*QC-a C-a\*U and \*QC-a a\*U; see below), thus, \*QC-a c\*U as well as
\*QC-a C-c\*U can be used to create a window.
.PP
The following commands are recognized by
.IR screen :
.IP "\fBC-a c\fP or \fBC-a C-c\fP"
Create a new window with a shell and switch to that window.
.IP "\fBC-a k\fP or \fBC-a C-k\fP"
Kill the current window and switch to the previously displayed window.
.IP "\fBC-a C-\e\fP"
Kill all windows and terminate
.IR screen .
.IP "\fBC-a d\fP or \fBC-a C-d\fP"
Detach
.I screen
(disconnect it from the terminal and put it into the
background).
A detached
.I screen
can be resumed by invoking
.I screen
with the
.B \-r
option.
.IP "\fBC-a C-a\fP\0\0\0\0\0"
Switch to the previously displayed window.
.IP "\fBC-a 0\fP to \fBC-a 9\fP"
Switch to the window with the number 0 (1, 2, .., 9, respectively).
When a new window is established, the first available number from the
range 0..9 is assigned to this window.
Thus, the first window can be activated by \*QC-a 0\*U; at most
10 windows can be present at any time.
.IP "\fBC-a space\fP or \fBC-a C-space\fP or \fBC-a n\fP or \fBC-a C-n\fP"
Switch to the next window.  This function can be used repeatedly to
cycle through the list of windows.
(Control-space is not supported by all terminals.)
.IP "\fBC-a p\fP or \fBC-a C-p\fP or \fBC-a -\fP"
Switch to the previous window (the opposite of \fBC-a space\fP).
.IP "\fBC-a l\fP or \fBC-a C-l\fP"
Redisplay the current window.
.IP "\fBC-a z\fP or \fBC-a C-z\fP"
Suspend
.IR screen .
.IP "\fBC-a h\fP or \fBC-a C-h\fP"
Write a hardcopy of the current window to the file \*Qhardcopy.\fIn\fP\*U
in the window's current directory,
where \fIn\fP is the number of the current window.
.IP "\fBC-a .\fP (Control-a dot)"
Write the termcap entry for the virtual terminal of the currently active
window to the file \*Q.termcap\*U in the directory \*Q$HOME/.screen\*U.
This termcap entry is identical to the value of the environment symbol
TERMCAP that is set up by
.I screen
for each window.
.IP "\fBC-a w\fP or \fBC-a C-w\fP"
Display a list of all windows.
For each window, the number of the window and the process that has been
started in the window is displayed; the current window is marked with a
`*'.
.IP "\fBC-a t\fP or \fBC-a C-t\fP"
Print in the message line the time of day, the host name, the load averages
over 1, 5, and 15 minutes (if this is available on your system),
the cursor position of the current window in the form \*Q(colum,row)\*U
starting with \*U(0,0)\*U, an indication if flow control
and (for the current window)
insert mode, origin mode, wrap mode, and keypad application
mode are enabled or not (indicated by a '+' or '-'),
the currently active character set (\fIG0\fP, \fIG1\fP, \fIG2\fP,
or \fIG3\fP), and the terminal character sets that are currently
designated as \fIG0\fP through \fIG3\fP.
.IP "\fBC-a v\fP or \fBC-a C-v\fP"
Display the version.
.IP "\fBC-a a\fP\0\0\0\0\0"
Send the character \*QC-a\*U to the processes running in the window.
.IP "\fBC-a s\fP or \fBC-a C-s\fP"
Send a Control-s to the program running in the window.
.IP "\fBC-a q\fP or \fBC-a C-q\fP"
Send a Control-q to the program running in the window.
.IP
.PP
The
.B \-e
option can be used to specify a different command character and
a character which, when typed immediately after the command character,
generates a literal command character.
The defaults for these two characters are \*QC-a\*U and `a'.
(Note that the function to switch to the previous window is actually the
command character typed twice; for instance, when
.I screen
is called with the option \*Q\fB\-e]x\fP\*U (or \*Q\fB\-e ]x\fP\*U),
this function becomes \*Q]]\*U).
.SH CUSTOMIZATION
When
.I screen
is invoked, it executes initialization commands from the file
\*Q.screenrc\*U in the user's home directory.
Commands in \*Q.screenrc\*U are mainly used to automatically
establish a number of windows each time
.I screen
is called, and to bind functions to specific keys.
Each line in \*Q.screenrc\*U contains one initialization command; lines
starting with `#' are ignored.
Commands can have arguments; arguments are separated by tabs and spaces
and can be surrounded by single quotes or double quotes.
.PP
The following initialization commands are recognized by
.IR screen :
.PP
.B "escape \fIxy\fP"
.PP
Set the command character to \fIx\fP and the character generating a literal
command character to \fIy\fP (see the \-e option above).
.PP
.B "bell \fImessage\fP"
.PP
When a bell character is sent to a background window,
.I screen
displays a notification in the message line (see below).
The notification message can be re-defined by means of the \*Qbell\*U
command; each occurrence of `%' in \fImessage\fP is replaced by
the number of the window to which a bell has been sent.
The default message is
.PP
	Bell in window %
.PP
An empty message can be supplied to the \*Qbell\*U command to suppress
output of a message line (bell "").
.PP
.B "mode \fImode\fP"
.PP
The mode of each newly allocated pseudo-tty is set to \fImode\fP.
\fIMode\fP is an octal number.
When no \*Qmode\*U command is given, mode 0622 is used.
.PP
.B "screen [\fIn\fP] [\fIcmds args\fP]"
.PP
Establish a window.
If an optional number \fIn\fP in the range 0..9 is given, the window
number \fIn\fP is assigned to the newly created window (or, if this
number is already in use, the next higher number).
Note that \fIn\fP has a value of zero for the standard shell window
created after \*Q.screenrc\*U has been read.
If a command is specified after \*Qscreen\*U, this command (with the given
arguments) is started in the window; if no command is given, a shell
is created in the window.
Thus, if your \*Q.screenrc\*U contains the lines
.PP
.nf
	# example for .screenrc:
	screen 1
	screen 2 telnet foobar
.fi
.PP
.I screen
creates a shell window (window #1), a window with a TELNET connection
to the machine foobar (window #2), and, finally, a second shell window
(the default window) which gets a window number of zero.
When the initialization is completed,
.I screen
always switches to the default window, so window #0 is displayed
when the above \*Q.screenrc\*U is used.
.PP
.B "chdir [\fIdirectory\fP]"
.PP
Change the \fIcurrent directory\fP of
.I screen
to the specified directory or, if called without an argument,
to the home directory (the value of the environment symbol $HOME).
All windows that are created by means of the \*Qscreen\*U command
from within \*Q.screenrc\*U or by means of \*QC-a c'' are running
in the \fIcurrent directory\fP; the \fIcurrent directory\fP is
initially the directory from which the shell command
.I screen
has been invoked.
Hardcopy files are always written to the directory in which the current
window has been created (that is, \fInot\fP in the current directory
of the shell running in the window).
.PP
.B "bind \fIkey\fP [\fIfunction\fP | \fIcmd args\fP]"
.PP
Bind a function to a key.
By default, each function provided by
.I screen
is bound to one or more keys as indicated by the above table, e.\|g. the
function to create a new window is bound to \*QC-c\*U and \*Qc\*U.
The \*Qbind\*U command can be used to redefine the key bindings and to
define new bindings.
The \fIkey\fP
argument is either a single character, a sequence of the form
\*Q^x\*U meaning \*QC-x\*U, or an octal number specifying the
ASCII code of the character.
If no further argument is given, any previously established binding
for this key is removed.
The \fIfunction\fP argument can be one of the following keywords:
.PP
.nf
	shell	Create new window with a shell
	kill	Kill the current window
	quit	Kill all windows and terminate
	detach	Detach \fIscreen\fP
	other	Switch to previously displayed window
	next	Switch to the next window
	prev	Switch to the previous window
	redisplay	Redisplay current window
	hardcopy	Make hardcopy of current window
	termcap	Write termcap entry to $HOME/.screen/.termcap
	suspend	Suspend \fIscreen\fP
	windows	Display list of window
	info	Print useful information in the message line
	xon	Send Control-q
	xoff	Send Control-s
	version	Display the version
	select0	Switch to window #0
	\0\0...
	select9	Switch to window #9
.fi
.PP
In addition, a key can be bound such that a window is created running
a different command than the shell when that key is pressed.
In this case, the command optionally followed by
arguments must be given instead of one of the above-listed keywords.
For example, the commands
.PP
.nf
	bind ' ' windows
	bind ^f telnet foobar
	bind 033 su
.fi
.PP
would bind the space key to the function that displays a list
of windows (that is, the function usually invoked by \*QC-a C-w\*U
or \*QC-a w\*U would also be available as \*QC-a space\*U),
bind \*QC-f\*U to the function \*Qcreate a window with a TELNET
connection to foobar\*U, and bind \*Qescape\*U to the function
that creates a window with a super-user shell.
.SH "VIRTUAL TERMINAL"
.I Screen
prints error messages and other diagnostics in a \fImessage line\fP above
the bottom of the screen.
The message line is removed when a key is pressed or, automatically,
after a couple of seconds.
The message line facility can be used by an application running in
the current window by means of the ANSI \fIPrivacy message\fP
control sequence (for instance, from within the shell, something like
.IP
echo '^[^Hello world^[\e'   (where ^[ is an \fIescape\fP)
.PP
can be used to display a message line.
.PP
When the `NF' capability is found in the termcap entry of the
terminal on which
.I screen
has been started, flow control is turned off for the terminal.
This enables the user to send XON and XOFF characters to the
program running in a window (this is required by the \fIemacs\fP
editor, for instance).
The command line options 
.B \-n
and
.B \-f
can be used to turn flow control off or on, respectively, independently
of the `NF' capability.
.PP
.I
Screen
never writes in the last position of the screen, unless the boolean
capability `LP' is found in the termcap entry of the terminal.
Usually,
.I screen
cannot predict whether or not a particular terminal scrolls when
a character is written in the last column of the last line;
`LP' indicates that it is safe to write in this position.
Note that the `LP' capability is independent of `am' (automatic
margins); for certain terminals, such as the VT100, it is reasonable
to set `am' as well as `LP' in the corresponding termcap entry
(the VT100 does not move the cursor when a character is written in
the last column of each line).
.PP
.I Screen
puts into the environment of each process started in a newly created
window the symbols \*QWINDOW=\fIn\fP\*U (where \fIn\fP is the number
of the respective window), \*QTERM=screen\*U, and a TERMCAP variable
reflecting the capabilities of the virtual terminal emulated by
.IR screen .
The actual set of capabilities supported by the virtual terminal
depends on the capabilities supported by the physical terminal.
If, for instance, the physical terminal does not support standout mode,
.I screen
does not put the `so' and `se' capabilities into the window's TERMCAP
variable, accordingly. 
However, a minimum number of capabilities must be supported by a
terminal in order to run
.IR screen ,
namely scrolling, clear screen, and direct cursor addressing
(in addition,
.I screen
does not run on hardcopy terminals or on terminals that overstrike).
.PP
When the boolean `G0' capability is present in the termcap entry
for the terminal on which
.I screen
has been called, the terminal emulation of
.I screen
supports multiple character sets.
This allows an application to make use of, for instance,
the VT100 graphics character set or national character sets.
The following control functions from ISO 2022 are supported:
\fIlock shift G0\fP (\fISI\fP), \fIlock shift G1\fP (\fISO\fP),
\fIlock shift G2\fP, \fIlock shift G3\fP, \fIsingle shift G2\fP,
and \fIsingle shift G3\fP.
When a virtual terminal is created or reset, the ASCII character
set is designated as \fIG0\fP through \fIG3\fP.
.PP
When the `po' and `pf' capabilities are present in the terminal's
termcap entry, applications running in a
.I screen
window can send output to the printer port of the terminal.
This allows a user to have an application in one window
sending output to a printer connected to the terminal, while all
other windows are still active (the printer port is enabled
and disabled again for each chunk of output).
As a side-effect, programs running in different windows can
send output to the printer simultaneously.
Data sent to the printer is not displayed in the window.
.PP
Some capabilities are only put into the TERMCAP
variable of the virtual terminal if they can be efficiently
implemented by the physical terminal.
For instance, `dl' (delete line) is only put into the TERMCAP
variable if the terminal supports either delete line itself or
scrolling regions.
If
.I screen
is called with the
.B \-a
option, \fIall\fP capabilities are put into the environment,
even if
.I screen
must redraw parts of the display in order to implement a function.
.PP
The following is a list of control sequences recognized by
.IR screen .
\*Q(V)\*U and \*Q(A)\*U indicate VT100-specific and ANSI- or
ISO-specific functions, respectively.
.PP
.nf
.TP 20
.B "ESC E"
	Next Line
.TP 20
.B "ESC D"
	Index
.TP 20
.B "ESC M"
	Reverse Index
.TP 20
.B "ESC H"
	Horizontal Tab Set
.TP 20
.B "ESC 7"
(V)	Save Cursor and attributes
.TP 20
.B "ESC 8"
(V)	Restore Cursor and Attributes
.TP 20
.B "ESC c"
	Reset to Initial State
.TP 20
.B "ESC ="
(V)	Application Keypad Mode
.TP 20
.B "ESC >"
(V)	Numeric Keypad Mode
.TP 20
.B "ESC # 8"
(V)	Fill Screen with E's
.TP 20
.B "ESC \e"
(A)	String Terminator
.TP 20
.B "ESC ^"
(A)	Privacy Message (Message Line)
.TP 20
.B "ESC P"
(A)	Device Control String (not used)
.TP 20
.B "ESC _"
(A)	Application Program Command (not used)
.TP 20
.B "ESC ]"
(A)	Operating System Command (not used)
.TP 20
.B "Control-N"
(A)	Lock Shift G1 (SO)
.TP 20
.B "Control-O"
(A)	Lock Shift G0 (SI)
.TP 20
.B "ESC n"
(A)	Lock Shift G2
.TP 20
.B "ESC o"
(A)	Lock Shift G3
.TP 20
.B "ESC N"
(A)	Single Shift G2
.TP 20
.B "ESC O"
(A)	Single Shift G3
.TP 20
.B "ESC ( Pcs"
(A)	Designate character set as G0
.TP 20
.B "ESC ) Pcs"
(A)	Designate character set as G1
.TP 20
.B "ESC * Pcs"
(A)	Designate character set as G2
.TP 20
.B "ESC + Pcs"
(A)	Designate character set as G3
.TP 20
.B "ESC [ Pn ; Pn H"
	Direct Cursor Addressing
.TP 20
.B "ESC [ Pn ; Pn f"
	Direct Cursor Addressing
.TP 20
.B "ESC [ Pn J"
	Erase in Display
.TP 20
\h'\w'ESC 'u'Pn = None or \fB0\fP
	From Cursor to End of Screen
.TP 20
\h'\w'ESC 'u'\fB1\fP
	From Beginning of Screen to Cursor
.TP 20
\h'\w'ESC 'u'\fB2\fP
	Entire Screen
.TP 20
.B "ESC [ Pn K"
	Erase in Line
.TP 20
\h'\w'ESC 'u'Pn = None or \fB0\fP
	From Cursor to End of Line
.TP 20
\h'\w'ESC 'u'\fB1\fP
	From Beginning of Line to Cursor
.TP 20
\h'\w'ESC 'u'\fB2\fP
	Entire Line
.TP 20
.B "ESC [ Pn A"
	Cursor Up
.TP 20
.B "ESC [ Pn B"
	Cursor Down
.TP 20
.B "ESC [ Pn C"
	Cursor Right
.TP 20
.B "ESC [ Pn D"
	Cursor Left
.TP 20
.B "ESC [ Ps ;...; Ps m"
	Select Graphic Rendition
.TP 20
\h'\w'ESC 'u'Ps = None or \fB0\fP
	Default Rendition
.TP 20
\h'\w'ESC 'u'\fB1\fP
	Bold
.TP 20
\h'\w'ESC 'u'\fB2\fP
(A)	Faint
.TP 20
\h'\w'ESC 'u'\fB3\fP
(A)	\fIStandout\fP Mode (ANSI: Italicised)
.TP 20
\h'\w'ESC 'u'\fB4\fP
	Underlined
.TP 20
\h'\w'ESC 'u'\fB5\fP
	Blinking
.TP 20
\h'\w'ESC 'u'\fB7\fP
	Negative Image
.TP 20
\h'\w'ESC 'u'\fB22\fP
(A)	Normal Intensity
.TP 20
\h'\w'ESC 'u'\fB23\fP
(A)	\fIStandout\fP Mode off (ANSI: Italicised off)
.TP 20
\h'\w'ESC 'u'\fB24\fP
(A)	Not Underlined
.TP 20
\h'\w'ESC 'u'\fB25\fP
(A)	Not Blinking
.TP 20
\h'\w'ESC 'u'\fB27\fP
(A)	Positive Image
.TP 20
.B "ESC [ Pn g"
	Tab Clear
.TP 20
\h'\w'ESC 'u'Pn = None or \fB0\fP
	Clear Tab at Current Position
.TP 20
\h'\w'ESC 'u'\fB3\fP
	Clear All Tabs
.TP 20
.B "ESC [ Pn ; Pn r"
(V)	Set Scrolling Region
.TP 20
.B "ESC [ Pn I"
(A)	Horizontal Tab
.TP 20
.B "ESC [ Pn Z"
(A)	Backward Tab
.TP 20
.B "ESC [ Pn L"
(A)	Insert Line
.TP 20
.B "ESC [ Pn M"
(A)	Delete Line
.TP 20
.B "ESC [ Pn @"
(A)	Insert Character
.TP 20
.B "ESC [ Pn P"
(A)	Delete Character
.TP 20
.B "ESC [ Ps  ;...; Ps h"
	Set Mode
.TP 20
.B "ESC [ Ps  ;...; Ps l"
	Reset Mode
.TP 20
\h'\w'ESC 'u'Ps = \fB4\fP
(A)	Insert Mode
.TP 20
\h'\w'ESC 'u'\fB?5\fP
(V)	Visible Bell (\fIOn\fP followed by \fIOff\fP)
.TP 20
\h'\w'ESC 'u'\fB?6\fP
(V)	\fIOrigin\fP Mode
.TP 20
\h'\w'ESC 'u'\fB?7\fP
(V)	\fIWrap\fP Mode
.TP 20
.B "ESC [ 5 i"
(A)	Start relay to printer (ANSI Media Copy)
.TP 20
.B "ESC [ 4 i"
(A)	Stop relay to printer (ANSI Media Copy)
.fi
.SH FILES
.nf
.ta 2i
$(HOME)/.screenrc	\fIscreen\fP initialization commands
.br
$(HOME)/.screen	Directory created by \fIscreen\fP
.br
$(HOME)/.screen/\fIhost.tty\fP	Socket created by \fIscreen\fP
.br
hardcopy.[0-9]	Screen images created by the hardcopy function
.br
/etc/termcap	Terminal capability data base
.br
/var/utmp	Login records
.fi
.SH "SEE ALSO"
termcap(5), utmp(5)
.SH AUTHOR
Oliver Laumann
.SH BUGS
Standout mode is not cleared before newline or cursor addressing.
.PP
If `LP' is not set but `am' is set, the last character in the last line is never
written, and it is not correctly re-displayed when the screen is
scrolled up or when a character is deleted in the last line.
.PP
The VT100 \*Qwrap around with cursor addressing\*U bug is not compensated
when
.I screen
is running on a VT100.
.PP
`AL,' `DL', and similar parameterized capabilities are not used if present.
.PP
`dm' (delete mode), `xn', and `xs' are not handled
correctly (they are ignored). 
.PP
The \fIGR\fP set of ISO 2022 is not supported.
.PP
`ms' is not advertised in the termcap entry (in order to compensate
a bug in
.IR curses (3X)).
.PP
Scrolling regions are only emulated if the physical terminal supports
scrolling regions.
.PP
.I Screen
does not make use of hardware tabs.
.PP
.I Screen
must be installed as set-uid with owner root in order to be able
to correctly change the owner of the tty device file for each
window.
Special permission may also be required to write the file \*Q/etc/utmp\*U.
.PP
Entries in \*Q/etc/utmp\*U are not removed when
.I screen
is killed with SIGKILL.
Commit message
This repository is read-only for this account.
Repository snapshot

Current branch
master
Visibility
public
Your access
Read
Remote
Configured
File activity

View file history