Invoking `Screen'
*****************
Screen has the following command-line options:
`-a'
Include _all_ capabilities (with some minor exceptions) in each
window's termcap, even if `screen' must redraw parts of the display
in order to implement a function.
`-A'
Adapt the sizes of all windows to the size of the display. By
default, `screen' may try to restore its old window sizes when
attaching to resizable terminals (those with `WS' in their
descriptions, e.g. `suncmd' or some varieties of `xterm').
`-c FILE'
Use FILE as the user's configuration file instead of the default
of `$HOME/.screenrc'.
`-d [PID.SESSIONNAME]'
`-D [PID.SESSIONNAME]'
Do not start `screen', but instead detach a `screen' session
running elsewhere (Note:Detach). `-d' has the same effect as
typing `C-a d' from the controlling terminal for the session.
`-D' is the equivalent to the power detach key. If no session can
be detached, this option is ignored. In combination with the
`-r'/`-R' option more powerful effects can be achieved:
`-d -r'
Reattach a session and if necessary detach it first.
`-d -R'
Reattach a session and if necessary detach or even create
it first.
`-d -RR'
Reattach a session and if necessary detach or create it. Use
the first session if more than one session is available.
`-D -r'
Reattach a session. If necessary detach and logout remotely
first.
`-D -R'
Attach here and now. In detail this means: If a session is
running, then reattach. If necessary detach and logout
remotely first. If it was not running create it and notify
the user. This is the author's favorite.
`-D -RR'
Attach here and now. Whatever that means, just do it.
_Note_: It is a good idea to check the status of your sessions
with `screen -list' before using this option.
`-e XY'
Set the command character to X, and the character generating a
literal command character (when typed after the command character)
to Y. The defaults are `C-a' and `a', which can be specified as
`-e^Aa'. When creating a `screen' session, this option sets the
default command caracter. In a multiuser session all users added
will start off with this command character. But when attaching to
an already running session, this option only changes the command
character of the attaching user. This option is equivalent to the
commands `defescape' or `escape' respectively. (Note:Command
Character).
`-f'
`-fn'
`-fa'
Set flow-control to on, off, or automatic switching mode,
respectively. This option is equivalent to the `defflow' command
(Note:Flow Control).
`-h NUM'
Set the history scrollback buffer to be NUM lines high.
Equivalent to the `defscrollback' command (Note:Copy).
`-i'
Cause the interrupt key (usually `C-c') to interrupt the display
immediately when flow control is on. This option is equivalent to
the `interrupt' argument to the `defflow' command (Note:Flow
Control). Its use is discouraged.
`-l'
`-ln'
Turn login mode on or off (for `/var/run/utmp' updating). This
option is equivalent to the `deflogin' command (Note:Login).
`-ls [MATCH]'
`-list [MATCH]'
Do not start `screen', but instead print a list of session
identification strings (usually of the form PID.TTY.HOST; Note:Session Name). Sessions marked `detached' can be resumed with
`screen -r'. Those marked `attached' are running and have a
controlling terminal. If the session runs in multiuser mode, it
is marked `multi'. Sessions marked as `unreachable' either live
on a different host or are dead. An unreachable session is
considered dead, when its name matches either the name of the
local host, or the specified parameter, if any. See the `-r' flag
for a description how to construct matches. Sessions marked as
`dead' should be thoroughly checked and removed. Ask your system
administrator if you are not sure. Remove sessions with the
`-wipe' option.
`-L'
Tell `screen' that your auto-margin terminal allows programs to
write to the last column of the last row of the screen without
scrolling. This can also be set in your `.screenrc' by specifying
`xn' in a `termcap' command (Note:Termcap).
`-m'
Tell `screen' to ignore the `$STY' environment variable. When
this option is used, a new session will always be created,
regardless of whether `screen' is being called from within another
`screen' session or not. This flag has a special meaning in
connection with the `-d' option:
`-d -m'
Start `screen' in _detached_ mode. This creates a new session
but doesn't attach to it. This is useful for system startup
scripts.
`-D -m'
This also starts `screen' in _detached_ mode, but doesn't fork
a new process. The command exits if the session terminates.
`-q'
Suppress printing of error messages. In combination with `-ls' the
exit value is set as follows: 9 indicates a directory without
sessions. 10 indicates a directory with running but not attachable
sessions. 11 (or more) indicates 1 (or more) usable sessions. In
combination with `-r' the exit value is as follows: 10 indicates
that there is no session to resume. 12 (or more) indicates that
there are 2 (or more) sessions to resume and you should specify
which one to choose. In all other cases `-q' has no effect.
`-r [PID.SESSIONNAME]'
`-r SESSIONOWNER/[PID.SESSIONNAME]'
Resume a detached `screen' session. No other options (except
combinations with `-d' or `-D') may be specified, though the
session name (Note:Session Name) may be needed to distinguish
between multiple detached `screen' sessions. The second form is
used to connect to another user's screen session which runs in
multiuser mode. This indicates that screen should look for
sessions in another user's directory. This requires setuid-root.
`-R'
Resume the first appropriate detached `screen' session. If
successful, all other command-line options are ignored. If no
detached session exists, start a new session using the specified
options, just as if `-R' had not been specified. This option is
set by default if screen is run as a login-shell (actually screen
uses `-xRR' in that case). For combinations with the `-D'/`-d'
option see there.
`-s PROGRAM'
Set the default shell to be PROGRAM. By default, `screen' uses
the value of the environment variable `$SHELL', or `/bin/sh' if it
is not defined. This option is equivalent to the `shell' command
(Note:Shell).
`-S SESSIONNAME'
Set the name of the new session to SESSIONNAME. This option can
be used to specify a meaningful name for the session in place of
the default TTY.HOST suffix. This name identifies the session for
the `screen -list' and `screen -r' commands. This option is
equivalent to the `sessionname' command (Note:Session Name).
`-t NAME'
Set the title (name) for the default shell or specified program.
This option is equivalent to the `shelltitle' command (Note:Shell).
`-U'
Run screen in UTF-8 mode. This option tells screen that your
terminal sends and understands UTF-8 encoded characters. It also
sets the default encoding for new windows to `utf8'.
`-v'
Print the version number.
`-wipe [MATCH]'
List available screens like `screen -ls', but remove destroyed
sessions instead of marking them as `dead'. An unreachable
session is considered dead, when its name matches either the name
of the local host, or the explicitly given parameter, if any. See
the `-r' flag for a description how to construct matches.
`-x'
Attach to a session which is already attached elsewhere
(multi-display mode).
`-X'
Send the specified command to a running screen session. You can use
the `-d' or `-r' option to tell screen to look only for attached
or detached screen sessions. Note that this command doesn't work
if the session is password protected.