---

3 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 (see 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 character. 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. (see Command Character).

‘-f’

‘-fn’

‘-fa’

Set flow-control to on, off, or automatic switching mode, respectively. This option is equivalent to the defflow command (see Flow Control).

‘-h num’

Set the history scrollback buffer to be num lines high. Equivalent to the defscrollback command (see Copying).

‘-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 (see Flow Control). Its use is discouraged.

‘-l’

‘-ln’

Turn login mode on or off (for /etc/utmp updating). This option is equivalent to the deflogin command (see 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; see 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 to turn on automatic output logging for the windows.

‘-Logfile "file"’

By default logfile name is "screenlog.0". You can set new logfile name with the -Logfile option.

‘-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.

‘-O’

Select a more optimal output mode for your terminal rather than true VT100 emulation (only affects auto-margin terminals without ‘LP’). This can also be set in your .screenrc by specifying ‘OP’ in the termcap command.

‘-p name_or_number|-|=|+’

Preselect a window. This is useful when you want to reattach to a specific window or you want to send a command via the ‘-X’ option to a specific window. As with screen’s select command, ‘-’ selects the blank window. As a special case for reattach, ‘=’ brings up the windowlist on the blank window, while a ‘+’ will create new window. The command will not be executed if the specified window could not be found.

‘-P’

Turns authentication on. By default screen allows to attach without enter the user’s password. This option changes this behavior, i.e. enables authentication. The same effect can be done by using "auth on" command.

‘-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.

‘-Q’

Some commands now can be queried from a remote session using this flag, e.g. ’screen -Q windows’. The commands will send the response to the stdout of the querying process. If there was an error in the command, then the querying process will exit with a non-zero status.

The commands that can be queried now are: echo info lastmsg number select time title windows

‘-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 (see 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’

resumes screen only when it’s unambiguous which one to attach, usually when only one screen is detached. Otherwise lists available sessions.

‘-RR’

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 (see Shell). See also there.

‘-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 (see Session Name).

‘-t name’

Set the title (name) for the default shell or specified program. This option is equivalent to the shelltitle command (see Shell).

‘-T term’

Set the $TERM enviroment variable using the specified term as opposed to the default setting of screen.

‘-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). Screen refuses to attach from within itself. But when cascading multiple screens, loops are not detected; take care.

‘-X’

Send the specified command to a running screen session. You may use the -S option to specify the screen session if you have several running. 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.