(screen.info)Invoking Screen

---

Next: Customization Prev: Getting Started Up: Top

---

Enter node , (file) or (file)node

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 (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 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.  (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 '/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) and the corresponding creation timestamps.
     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.

'-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 (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'
     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 most-recently created 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.  'Note:' Time-based session
     selection is a Debian addition.

'-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).  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 (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).

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