Tuesday, December 25, 2012

'man screen' revised and abridged

screen is one of the most useful programs on the planet. But the manpage, at 3,000+ lines, is daunting. I found I could remove over half of it and still retain the information I find useful. Of course, if I ever need any of the information I removed, it's only one man screen away.


************************
**                    **
**   screen manpage   **
**                    **
************************

Revised and abridged by Nathan Cutler, 2012-12-22 to contain only what I
considered relevant for "basic" usage of screen. The aims of this exercise
are to (1) learn screen, and (2) make it easier to find pertinent
information in the manpage.


REALLY BASIC STUFF TO REMEMBER

   Invocation:
       # find out if there are any running screen sessions; they will be
       # listed as "Attached" (meaning the screen session is "attached" to,
       # or displayed on, a terminal somewhere) of "Detached", which means
       # not currently attached to a terminal, not visible by any human, 
       # "disembodied". Generally speaking you don't want to run more than
       # one session.
       $ screen -ls 
       
       # when you know there are no screen sessions currently running and
       # you want to start one
       $ screen          

       # when "screen -ls" shows a detached session and you want to
       # reattach to it
       $ screen -r

       # there is an attached session running on another terminal and you
       # want to move it to this one (take control of it away from the
       # other terminal)
       $ screen -d -r

       # the previous case _PLUS_ you also want to log off the other 
       # terminal automatically
       $ screen -D -r

       # there is an attached session on another terminal and you want to
       # enter multi-display mode (e.g. your colleague and you share a
       # screen session while both logged on as 'root')
       $ screen -x

   Start a bash shell in a new window within 'screen':
       C-a c

   List what windows are available:
       C-a "     (ESC to exit)

   Detach (leave screen session, along with all forked processes therein,
   running in the background -- this is a handy way to turn any process
   into a "daemon"):
       C-a d

   "Power detach" (detach screen and log off the terminal in one go):
       C-a D

   Display screen's ':' command-line prompt:
       C-a :

   Window width/height:
       When only one user is connected to a screen session, screen detects
       resizing of the xterm window and automatically resizes its virtual
       terminal windows to match.

       In multi-display mode, this feature is disabled. To manually change
       the window size, use the "height -w" and "width -w" screen commands
       (see below under 'CUSTOMIZATION').

       The 'best practice' for sharing a screen via "screen -x" is to first
       find out which person has the bigger screen. If using an xterm, the
       window should be maximized. Then the person with the smaller screen
       should issue the screen command "fit" (C-a : fit ).


MY ~/.screenrc FILE:
    
     bind h focus left
     bind j focus down
     bind k focus up
     bind l focus right
     bind K kill
     caption always "%3n %t%=%c"
     chdir
     defutf8 on
     defscrollback 5000
     startup_message off
     vbell on
     verbose on


SYNOPSIS
       screen [ -options ] [ cmd [ args ] ]
       screen -r [[pid.]tty[.host]]
       screen -r sessionowner/[[pid.]tty[.host]]


DESCRIPTION
       Screen  is  a full-screen window manager that multiplexes a physical
       terminal between sev- eral processes (typically interactive shells).
       There is a scrollback history buffer for each virtual terminal and a
       copy-and-paste mechanism that allows moving text regions between
       windows.

       When screen is called, it creates a single window with a shell in
       it  (or  the  specified command)  and  then  gets  out of your way
       so that you can use the program as you normally would.  Then, at any
       time, you can create new (full-screen) windows with other programs
       in them  (including  more shells), kill existing windows, view a
       list of windows, turn output logging on and off, copy-and-paste text
       between  windows,  view  the  scrollback  history, switch  between
       windows  in whatever manner you wish, etc. All windows run their
       programs completely independent of each other. Programs continue to
       run when their window  is  cur- rently not visible and even when the
       whole screen session is detached from the user's ter- minal.  When a
       program terminates, screen (per default) kills the  window  that
       contained it.  If this window was in the foreground, the display
       switches to the previous window; if none are left, screen exits. 

       Everything you type is sent to the program running in the current
       window.  The only excep- tion  to  this  is the one keystroke that
       is used to initiate a command to the window man- ager.  By default,
       each command begins with a control-a (abbreviated C-a from now on),
       and is followed by one other keystroke.  The command character and
       all the key bindings can be fully customized to be anything you
       like, though they are always two characters in length.

       The  standard  way  to  create a new window is to type "C-a c".
       This 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.  

       In addition, new windows can be created by running a command like:

              screen emacs prog.c

       from a shell prompt within a previously created window.  This will
       not run another copy of screen,  but  will instead supply the
       command name and its arguments to the window manager (specified in
       the $STY environment variable) who will use it to  create  the  new
       window.  The  above example would start the emacs editor (editing
       prog.c) and switch to its window.

       If you're impatient and want to get started without doing a lot more
       reading,  you  should remember  this  one command:  "C-a ?".  Typing
       these two characters will display a list of the available screen
       commands and their bindings.


COMMAND-LINE OPTIONS

       -A   Adapt the sizes of all windows to the size of  the  current
     terminal.   By  default, screen  tries  to  restore its old
     window sizes when attaching to resizable terminals

       -d|-D [pid.tty.host]
     does not start screen, but detaches the elsewhere running
     screen session. It has  the same  effect  as typing "C-a d"
     from screen's controlling terminal. -D is the equiva- lent 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 -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 always a good idea to check the status  of  your
     sessions  by  means  of "screen -list" (or "screen -ls").

       -h num
            Specifies the history scrollback buffer to be num lines high.

       -ls [match]
       -list [match]
     does  not  start  screen,  but prints a list of pid.tty.host
     strings identifying your screen sessions.  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   tells screen to turn on automatic output logging for the
            windows.

       -r [pid.tty.host]
     resumes a detached screen session.  No other options (except
     combinations with -d/-D) may be specified, though an optional
     prefix of [pid.]tty.host may be needed  to  dis- tinguish
     between multiple detached screen sessions. [NOTE: there is no
     use in having multiple screen sessions.]

       -R   attempts to resume the first detached screen session it finds.   
     If successful,  all other  command-line options are ignored.
     If no detached session exists, starts a new session using the
     specified options, just as if -R had not been specified. The
     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.

       -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 win- dows to `utf8'.

       -v   Print version number.

       -x   Attach  to  a  not  detached screen session. (Multi display
     mode.) NOTE: ENABLES A TERMINAL TO BE SHARED BY TWO OR MORE
     PEOPLE, WHICH CAN BE EXTREMELY USEFUL.


DEFAULT KEY BINDINGS
       As  mentioned,  each  screen  command consists of a "C-a" followed
       by one other character.  For your convenience, all commands that are
       bound to lower-case letters are also bound  to their control
       character counterparts (with the exception of "C-a a"; see below),
       thus, "C- a c" as well as "C-a C-c" can be used to create a window.

       The name of the command is shown in parentheses after the key
       binding. See section "CUSTOMIZATION"  for a description of the
       command.

       The following table shows the default key bindings:

       C-a '       (select)      Prompt for a window name or number to 
                                 switch to.

       C-a "       (windowlist -b)
                                 Present a list of all windows for selection.

       C-a 0       (select 0)
        ...           ...
       C-a 9       (select 9)
       C-a -       (select -)    Switch to window number 0 - 9, or to the 
                                 blank window.

       C-a tab     (focus)       Switch  the  input  focus  to  the next 
                                 region.  See also split, remove, only.

       C-a C-a     (other)       Toggle to the window displayed previously. 

       C-a a       (meta)        Send the command character (C-a) to window. 
                                 See escape command.

       C-a A       (title)       Allow the user to enter a name for the 
                                 current window.

       C-a c
       C-a C-c     (screen)      Create a new window with a shell and switch 
                                 to that window.

       C-a C       (clear)       Clear the screen.

       C-a d
       C-a C-d     (detach)      Detach screen from this terminal.

       C-a D D     (pow_detach)  Detach and logout [from whatever system 
                                 screen is running on].

       C-a F       (fit)         Resize the window to the current region size.

       C-a h       (hardcopy)    Write a hardcopy of the current window to 
                                 the file "hardcopy.n".

       C-a H       (log)         Begins/ends  logging  of the current window 
                                 to the file "screen-log.n".

       C-a i
       C-a C-i     (info)        Show info about this window.

       C-a k
       C-a C-k     (kill)        Destroy current window.

       C-a l
       C-a C-l     (redisplay)   Fully refresh current window.

       C-a m
       C-a C-m     (lastmsg)     Repeat the last message displayed in the 
                                 message line.

       C-a M       (monitor)     Toggles monitoring of the current window.

       C-a space
       C-a n
       C-a C-n     (next)        Switch to the next window.

       C-a backspace
       C-a h
       C-a p
       C-a C-p     (prev)        Switch to the previous window (opposite of 
                                 C-a n).

       C-a q
       C-a C-q     (xon)         Send a control-q to the current window.

       C-a Q       (only)        Delete all regions but the current one.  
                                 See also split, remove, focus.

       C-a s
       C-a C-s     (xoff)        Send a control-s to the current window.

       C-a S       (split)       Split  the  current  region horizontally 
     into two new ones.  See also only, remove,
     focus.

       C-a t
       C-a C-t     (time)        Show system information.

       C-a v       (version)     Display the version and compilation date.

       C-a w
       C-a C-w     (windows)     Show a list of windows.

       C-a X       (remove)      Kill the current region.  See also split, 
                                 only, focus.

       C-a z
       C-a C-z     (suspend)     Suspend screen.  Your system must support 
                                 BSD-style job-control.

       C-a Z       (reset)       Reset the virtual terminal to its "power-on" 
                                 values.

       C-a ?       (help)        Show key bindings.

       C-a C-\     (quit)        Kill all windows and terminate screen.

       C-a :       (colon)       Enter command line mode.

       C-a [
       C-a C-[
       C-a esc     (copy)        Enter copy/scrollback mode.

       C-a C-]
       C-a ]       (paste .)     Write the contents of the paste buffer to 
                                 the stdin queue of the current window.

       C-a >       (writebuf)    Write paste buffer to the screen-exchange 
                                 file (/tmp/screen-exchange).

       C-a <       (readbuf)     Reads the screen-exchange file 
     (/tmp/screen-exchange) into the paste
     buffer.

       C-a =       (removebuf)   Removes the file used by C-a < and C-a >.

       C-a _       (silence)     Start/stop monitoring the current window 
                                 for inactivity.

       C-a |       (split -v)    Split the current region vertically into 
                                 two new ones.

       C-a *       (displays)    Show a listing of all currently attached 
                                 displays.



CUSTOMIZATION
       When  screen  is  invoked,  it   executes   initialization
       commands   from   the   files "/usr/local/etc/screenrc"  and
       ".screenrc"  in  the  user's home directory.

       Commands in these files are used to set options, bind functions to
       keys, and to  automati- cally establish one or more windows at the
       beginning of your screen session.  Commands are listed one per line,
       with empty lines being ignored.

       Two   configuration   files  are  shipped  as  examples  with  your
       screen  distribution: "etc/screenrc" and "etc/etcscreenrc". They
       contain a number of useful examples for various commands.

       Customization  can  also  be  done 'on-line'. To enter the command
       mode type `C-a :'. Note that commands starting with "def" change
       default values, while others change current  set- tings.

       The following commands are available:

       bufferfile [exchange-file]

       Change  the  filename used for reading and writing with the paste
       buffer.  If the optional argument to the "bufferfile"  command  is
       omitted,  the  default  setting  ("/tmp/screen- exchange")  is
       reactivated.   The following example will paste the system's
       password file into the screen window (using the paste buffer, where
       a copy remains):

                   C-a : bufferfile /etc/passwd
                   C-a < C-a ]
                   C-a : bufferfile

       caption always|splitonly [string]

       This command controls the display of the window captions. Normally a
       caption is only  used if  more  than  one window is shown on the
       display (split screen mode). But if the type is set to always screen
       shows a caption even if only one window is displayed. The default
       is splitonly.

       chdir [directory]

       Change the current directory of screen to the specified directory
       or, if called without an argument, to your home directory (the value
       of the environment variable $HOME).  All  win- dows that are created
       by means of the "screen" command from within ".screenrc" or by means
       of "C-a : screen ..." or "C-a c" use this as their default
       directory.   Without  a  chdir command,  this  would  be  the
       directory from which screen was invoked.  Hardcopy and log files are
       always written to the window's default directory, not the current
       directory  of the  process  running  in  the  window.   You  can use
       this command multiple times in your .screenrc to start various
       windows in different default directories, but  the  last  chdir
       value will affect all the windows you create interactively.

       console [on|off]

       Grabs or un-grabs the machines console output to  a  window.   Note:
       Only  the  owner  of /dev/console  can  grab the console output.
       This command is only available if the machine supports the ioctl
       TIOCCONS.

       copy

       Enter copy/scrollback mode. This allows you to copy text from the
       current window  and  its history into the paste buffer. In this mode
       a vi-like `full screen editor' is active:

       Movement keys (same as in 'vi')

       Marking:
           The copy range is specified by setting two marks. The text 
    between these marks will be highlighted. Press space or enter 
    to set the first or second mark respectively. If  mousetrack  
    is  set  to `on', marks can also be set using left mouse click.
         Y and y used to mark one whole line or to mark from start of line.
         W marks exactly one word.

       Repeat count (same as in 'vi')

       Searching:
         / Vi-like search forward.
         ? Vi-like search backward.
         C-a s Emacs style incremental search forward.
         C-r Emacs style reverse i-search.
         n Find next search pattern.
         N Find previous search pattern.

       Specials:
         a before the final space key to toggle in append mode. Thus the 
    contents  of  the  paste buffer will not be overwritten, but is
           appended to.
         A toggles in append mode and sets a (second) mark.
         > sets  the  (second)  mark  and writes the contents of the paste 
    buffer to the screen- exchange file (/tmp/screen-exchange per
    default) once copy-mode is finished.  This example demonstrates
    how to dump the whole scrollback buffer to that file: "C-A [ g
    SPACE G $ >".
         C-g gives information about the current line and column.
         x or  o  exchanges  the first mark and the current cursor position. 
    You can use this to adjust an already placed mark.
         C-l ('el') will redraw the screen.
         @ does nothing. Does not even exit copy mode.
         All keys not described here exit copy mode (I recommend 'q').

       detach

       Detach  the  screen  session  (disconnect  it  from the terminal and
       put it into the back- ground).  This returns you to the shell where
       you invoked screen.  A detached  screen  can be  resumed  by
       invoking  screen  with  the  -r  option  (see  also section
       "COMMAND-LINE OPTIONS"). 

       dinfo

       Show  what screen thinks about your terminal. Useful if you want to
       know why features like color or the alternate charset don't work.

       displays  [bound by default to C-a *]

       Shows a tabular listing of all currently connected user front-ends  
       (displays).   This  is most useful for multiuser sessions.  The 
       following keys can be used in displays list:
         k, C-p, or up Move up one line.
         j, C-n, or down Move down one line.
         C-a or home Move to the first line.
         C-e or end Move to the last line.
         C-u or C-d Move one half page up or down.
         C-b or C-f Move one full page up or down.
         space Refresh the list
         d Detach that display
         D Power detach that display
         C-g, enter, or escape Exit the list

       The following is an example of what "displays" could look like:

              xterm 80x42 jnweiger@/dev/ttyp4     0(m11)   &rWx
              facit 80x24 mlschroe@/dev/ttyhf nb 11(tcsh)   rwx
              xterm 80x42 jnhollma@/dev/ttyp5     0(m11)   &R.x
               (A)   (B)     (C)     (D)     (E) (F)(G)   (H)(I)

       The legend is as follows:
       (A) The terminal type known by screen for this display.
       (B) Displays geometry as width x height.
       (C) Username who is logged in at the display.
       (D) Device name of the display or the attached device
       (E)  Display is in blocking or nonblocking mode.
       (F) Number of the window
       (G) Name/title of window
       (H) Whether the window is shared
       (I) Window permissions.

       echo [-n] message

       Do not use in .screenrc, because the message will go by so fast
       as to be invisible.  See also "sleep".  Echo is also useful  for  
       online checking  of  environment variables.

       escape xy

       Set  the  command  character to x and the character generating a
       literal command character (by triggering the "meta" command) to y
       (similar to the  -e  option).   Each  argument  is either  a  single
       character, a two-character sequence of the form "^x" (meaning
       "C-x"), a backslash followed by an octal number (specifying the
       ASCII code of the character),  or  a backslash followed by a second
       character, such as "\^" or "\\".  The default is "^Aa".

       fit

       Change the window size to the size of the current region. This
       command is  needed  because screen  doesn't  adapt  the window size
       automatically if the window is displayed more than once.

       focus [up|down|top|bottom]

       Move  the  input  focus  to  the next region. This is done in a
       cyclic way so that the top region is selected after the bottom one.
       If no subcommand is given it defaults to  `down'.  `up'  cycles  in
       the  opposite  order, `top' and `bottom' go to the top and bottom
       region respectively. Useful bindings are (j and k as in vi)
           bind j focus down
           bind k focus up
           bind t focus top
           bind b focus bottom
       Note that k is traditionally bound to the kill command.

       focusminsize [ ( width|max|_ ) ( height|max|_ ) ]

       This forces any currently selected region to be automatically
       resized at least  a  certain width  and  height. All other
       surrounding regions will be resized in order to accommodate.  This
       constraint follows everytime the "focus" command is used. The
       "resize" command can be used to increase either dimension of a
       region, but never below what is set with "focusminsize". The
       underscore `_' is a synonym for max. Setting a width and height of
       `0 0'  (zero zero)  will  undo  any constraints and allow for manual
       resizing.  Without any parameters, the minimum width and height is
       shown.

       hardcopy [-h] [file]

       Writes  out  the  currently displayed image to the file file, or, if
       no filename is speci- fied, to hardcopy.n in the default directory,
       where n is the number of the current window.  This  either  appends
       or overwrites the file if it exists. See below.  If the option -h is
       specified, dump also the contents of the scrollback buffer.

       hardcopy_append on|off

       If set to "on", screen will append to the "hardcopy.n" files created
       by the  command  "C-a h", otherwise these files are overwritten each
       time.  Default is `off'.

       hardcopydir directory

       Defines a directory where hardcopy files will be placed. If unset,
       hardcopys are dumped in screen's current working directory.

       height [-w|-d] [lines [cols]]

       Set the display height to a specified number of lines. When no
       argument is given  it  tog- gles  between  24 and 42 lines display.
       You can also specify a width if you want to change both values.  The
       -w option tells screen to leave the display size unchanged and just
       set the window size, -d vice versa.

       help [-c class]

       Not  really  a  online  help, but displays a help screen showing you
       all the key bindings.  The first pages list all the internal
       commands followed by their current bindings.  Subse- quent  pages
       will  display  the  custom  commands, one command per key.  Press
       space when you're done reading each page, or return to exit early.
       All other characters are ignored.  If  the  "-c" option is given,
       display all bound commands for the specified command class.  See
       also "DEFAULT KEY BINDINGS" section.

       ignorecase [on|off]

       Tell screen to ignore the case of characters in searches. Default is
       `off'.  Without  any options, the state of ignorecase is toggled.

       info

       Uses  the  message  line  to display some information about the
       current window: the cursor position in the form "(column,row)"
       starting with "(1,1)", the terminal width  and  height plus  the
       size of the scrollback buffer in lines, like in "(80,24)+50", the
       current state of window XON/XOFF flow control is shown like this
       (See also section FLOW CONTROL):

         +flow     automatic flow control, currently on.
         -flow     automatic flow control, currently off.
         +(+)flow  flow control enabled. Agrees with automatic control.
         -(+)flow  flow control disabled. Disagrees with automatic control.
         +(-)flow  flow control enabled. Disagrees with automatic control.
         -(-)flow  flow control disabled. Agrees with automatic control.

       The current line wrap setting (`+wrap' indicates enabled, `-wrap'
       not) is also shown.  The flags  `ins',  `org',  `app',  `log', `mon'
       or `nored' are displayed when the window is in insert mode, origin
       mode, application-keypad mode, has output logging, activity
       monitoring or partial redraw enabled.

       The currently active character set (G0, G1, G2, or G3) and in square
       brackets the terminal character sets that are currently designated
       as G0 through G3 is shown. If the  window  is in UTF-8 mode, the
       string "UTF-8" is shown instead.

       Additional  modes depending on the type of the window are displayed
       at the end of the sta- tus line (See also chapter "WINDOW TYPES").
       If the state machine of the terminal emulator is in a non-default
       state, the info line  is started with a string identifying the
       current state.  For system information use the "time" command.

       kill

       Kill current window.  If  there  is  an  `exec' command running then
       it is killed. Otherwise the process (shell) running in the window
       receives a HANGUP condition, the window  structure  is  removed  and
       screen  (your  display)  switches  to  another window.  When the
       last window is destroyed, screen exits.  After a kill screen
       switches to the previously displayed window.

       lastmsg

       Redisplay  the  last  contents of the message/status line.  Useful
       if you're typing when a message appears, because  the message goes
       away when you press a key (unless your terminal has  a  hardware
       status line).  Refer to the commands "msgwait" and "msgminwait" for
       fine tuning.

       layout new [title]

       Create a new layout. The screen will change to one whole region and
       be  switched  to  the blank  window.  From  here, you build the
       regions and the windows they show as you desire.  The new layout
       will be numbered with the smallest available integer, starting  with
       zero.  You  can  optionally  give  a title to your new layout.
       Otherwise, it will have a default title of "layout". You can always
       change the title  later  by  using  the  command  layout title.

       layout remove [n|title]

       Remove, or in other words, delete the specified layout. Either the
       number or the title can be specified. Without either specification,
       screen will remove the current layout.

       Removing a layout does not affect your set windows or regions.

       layout next

       Switch to the next layout available

       layout prev

       Switch to the previous layout available

       layout select [n|title]

       Select the desired layout. Either the number or the title can be
       specified. Without either specification,  screen  will  prompt and
       ask which screen is desired. To see which layouts are available, use
       the layout show command.

       layout show

       List on the message line the number(s) and title(s) of the available
       layout(s).  The  cur- rent layout is flagged.

       layout title [title]

       Change or display the title of the current layout. A string given
       will be used to name the layout. Without any options, the current
       title and number  is  displayed  on  the  message line.

       layout number [n]

       Change  or display the number of the current layout. An integer
       given will be used to num- ber the layout. Without any options, the
       current number and title is displayed on the mes- sage line.

       layout attach [title|:last]

       Change  or  display  which  layout  to reattach back to. The default
       is :last, which tells screen to reattach back to the last used
       layout just before  detachment.  By  supplying  a title, You can
       instruct screen to reattach to a particular layout regardless which
       one was used at the time of detachment. Without any options, the
       layout to  reattach  to  will  be shown in the message line.

       layout save [n|title]

       Remember  the current arrangement of regions. When used, screen will
       remember the arrange- ment of vertically and horizontally split
       regions. This arrangement  is  restored  when  a screen session is
       reattached or switched back from a different layout. If the session
       ends or the screen process dies, the layout arrangements are  lost.
       The  layout  dump  command should  help in this siutation. If a
       number or title is supplied, screen will remember the arrangement of
       that particular layout. Without any options, screen will remember
       the  cur- rent layout.

       Saving your regions can be done automatically by using the layout
       autosave command.

       layout autosave [on|off]

       Change  or  display  the status of automatcally saving layouts. The
       default is on, meaning when screen is detached or changed to a
       different layout, the arrangement of  regions  and windows will be
       remembered at the time of change and restored upon return.  If
       autosave is set to off, that arrangement will only be restored to
       either  to  the  last  manual  save, using layout save, or to when
       the layout was first created, to a single region with a sin- gle
       window. Without either an on or off, the current status is displayed
       on  the  message line.

       layout dump [filename]

       Write to a file the order of splits made in the current layout. This
       is useful to recreate the order of your regions used  in  your
       current  layout.  Only  the  current  layout  is recorded.  While
       the  order  of  the regions are recorded, the sizes of those regions
       and which windows correspond to which regions are  not.  If  no
       filename  is  specified,  the default  is layout-dump, saved in the
       directory that the screen process was started in. If the file
       already exists, layout dump will append to that file. As an example:

                   C-a : layout dump /home/user/.screenrc

       will save or append the layout to the user's .screenrc file.

       license

       Display the disclaimer page. This is done whenever  screen  is
       started  without  options, which should be often enough. See also
       the "startup_message" command.

       log [on|off]

       Start/stop writing output of the current window to a file
       "screenlog.n"  in  the  window's default  directory,  where  n  is
       the  number of the current window. This filename can be changed with
       the `logfile' command. If no parameter is given, the state of
       logging is tog- gled.  The  session  log  is  appended  to the
       previous contents of the file if it already exists. The current
       contents and the contents of the scrollback history are  not
       included in the session log.  Default is `off'.

       logfile filename
       logfile flush secs

       Defines  the  name  the log files will get. The default is
       "screenlog.%n". The second form changes the number of seconds screen
       will wait before flushing the logfile buffer  to  the file-system.
       The default value is 10 seconds.

       logtstamp [on|off]
       logtstamp after [secs]
       logtstamp string [string]

       This  command  controls logfile time-stamp mechanism of screen.  If
       time-stamps are turned "on", screen adds a string containing the
       current time to the logfile after two minutes of inactivity.  When
       output continues and more than another two minutes have passed, a
       second time-stamp is added to document the restart of the output.
       You  can  change  this  timeout with the second form of the command.
       The third form is used for customizing the time-stamp string (`--
       %n:%t -- time-stamp -- %M/%d/%y %c:%s --\n' by default).

       monitor [on|off]

       Toggles activity monitoring of windows.  When monitoring is turned
       on and an affected win- dow is switched into the background, you
       will receive the activity notification message in the status line at
       the first sign of output and the window will also be marked with an
       `@' in the window-status display.  Monitoring is initially off for
       all windows.

       mousetrack [on|off]

       This  command  determines whether screen will watch for mouse
       clicks. When this command is enabled, regions that have been split
       in various ways can be selected by pointing to  them with  a  mouse
       and left-clicking them. Without specifying on or off, the current
       state is displayed. The default state is determined by the
       "defmousetrack" command.

       msgwait sec

       Defines  the time a message is displayed if screen is not disturbed
       by other activity. The default is 5 seconds.

       next

       Switch  to the next window.  This command can be used repeatedly to
       cycle through the list of windows.

       number [[+|-]n]

       Change the current window's number. If the given number n is already
       used by another  win- dow,  both windows exchange their numbers. If
       no argument is specified, the current window number (and title) is
       shown. Using `+' or `-' will change the window's number by the rela-
       tive amount specified.

       obuflimit [limit]

       If  the  output  buffer contains more bytes than the specified
       limit, no more data will be read from the windows. The default value
       is 256. If you have a fast display (like  xterm), you  can  set it
       to some higher value. If no argument is specified, the current
       setting is displayed.

       only

       Kill all regions but the current one.

       other

       Switch to the window displayed previously. If this window does no
       longer exist, other  has the same effect as next.

       paste [registers [dest_reg]]

       Write  the  (concatenated)  contents  of the specified registers to
       the stdin queue of the current window. The register '.' is treated
       as the paste buffer. If no parameter is  given the  user is prompted
       for a single register to paste.  The paste buffer can be filled with
       the copy, history and readbuf commands.  Other registers can be
       filled with the  register, readreg  and  paste  commands.  If paste
       is called with a second argument, the contents of the specified
       registers is pasted into the named destination register rather than
       the win- dow.  If '.' is used as the second argument, the displays
       paste buffer is the destination.  Note, that "paste" uses a wide
       variety of resources: Whenever a second argument is  speci- fied  no
       current  window is needed. When the source specification only
       contains registers (not the paste buffer) then there need not be a
       current display  (terminal  attached),  as the registers are a
       global resource. The paste buffer exists once for every user.

       prev

       Switch to the window with the next lower number.  This command can
       be used  repeatedly  to cycle through the list of windows.

       quit [bound by default to C-a C-\]

       Kill all windows and terminate screen.

       readbuf [-e encoding] [filename]

       Reads  the  contents of the specified file into the paste buffer.
       You can tell screen the encoding of the file via the -e option.  If
       no  file  is  specified,  the  screen-exchange filename is used.
       See also "bufferfile" command.

       readreg [-e encoding] [register [filename]]

       Does one of two things, dependent on number of arguments: with zero
       or one arguments it it duplicates the paste buffer contents into the
       register specified or entered at the prompt.  With  two  arguments
       it  reads  the contents of the named file into the register, just as
       readbuf reads the screen-exchange file into the paste buffer.  You
       can  tell  screen  the encoding  of  the  file  via the -e option.
       The following example will paste the system's password file into the
       screen window (using register p, where a copy remains):

                   C-a : readreg p /etc/passwd
                   C-a : paste p

       register [-e encoding] key string

       Save the specified string to the register key.  The encoding of the
       string can  be  speci- fied via the -e option.  See also the "paste"
       command.

       remove

       Kill the current region. This is a no-op if there is only one
       region.

       removebuf

       Unlinks the screen-exchange file used by the commands "writebuf" and
       "readbuf".

       reset

       Reset the virtual terminal to its "power-on" values. Useful when
       strange  settings  (like scroll regions or graphics character set)
       are left over from an application.

       resize

       Resize  the current region. The space will be removed from or added
       to the region below or if there's not enough space from the region
       above.

              resize +N   increase current region height by N

              resize -N   decrease current region height by N

              resize  N   set current region height to N

              resize  =   make all windows equally high

              resize  max maximize current region height

              resize  min minimize current region height

       screen [-opts] [n] [cmd [args]|//group]

       Establish a new window.  title (a.k.a.) option (-t) and scrollback
       option (-h ) may be specified with each command.  The option
       (-M)  turns  monitoring  on  for this window.  The option (-L) turns
       output logging on for this window.  If an optional number n in the
       range 0..MAXWIN-1 is given, the window number n  is assigned to the
       newly created window (or, if this number is already in-use, the next
       available number).  If a command is specified after "screen", this
       command (with the given arguments)  is  started  in the window;
       otherwise, a shell is created.

       Thus, if your ".screenrc" contains the lines

                   # example for .screenrc:
                   screen 1
                   screen -t foobar -L 2 telnet foobar

       screen creates a shell window (in window #1) and a window with a
       TELNET connection to  the machine foobar (using the title "foobar"
       in window #2) and will write a logfile ("screenlog.2") of the telnet
       session.  When the initialization is completed, screen switches to
       the last window specified in your .screenrc file or, if none, opens
       a default window #0.

       scrollback num

       Set the size of the scrollback buffer for the current windows to num
       lines.  The  default scrollback  is 100 lines.  See also the
       "defscrollback" command and use "info" to view the current setting.
       To access and use the contents in the scrollback buffer, use  the
       "copy" command.

       select [WindowID]

       Switch  to  the  window  identified  by  WindowID.  This can be a
       prefix of a window title (alphanumeric window name) or a window
       number.  The parameter is optional and if  omitted, you get prompted
       for an identifier.  When a new window is established, the first
       available number is assigned to this window.  Thus, the first window
       can be activated by "select 0".  The  number  of  windows  is
       limited at compile-time by the MAXWIN configuration parameter (which
       defaults to 40).  There are two special WindowIDs, "-" selects the
       internal  blank window and "." selects the current window.

       setenv [var [string]]

       Set the environment variable var to value string.  If only var is
       specified, the user will be prompted to enter a value.  If no
       parameters are specified, the user will  be  prompted for  both
       variable  and  value.  The  environment is inherited by all
       subsequently forked shells.

       shelltitle title

       Set the title for all shells created during startup  or  by  the
       C-A  C-c  command.   For details about what a title is, see the
       discussion entitled "TITLES (naming windows)".

       silence [on|off|sec]

       Toggles  silence  monitoring of windows.  When silence is turned on
       and an affected window is switched into the background, you will
       receive the silence notification message in  the status  line  after
       a specified period of inactivity (silence). The default timeout can
       be changed with the `silencewait' command or by specifying a number
       of  seconds  instead  of `on' or `off'.  Silence is initially off
       for all windows.

       silencewait sec

       Define  the  time  that  all windows monitored for silence should
       wait before displaying a message. Default 30 seconds.

       sleep num

       This command will pause the execution of a  .screenrc  file  for
       num  seconds.   Keyboard activity  will  end the sleep.  It may be
       used to give users a chance to read the messages output by "echo".

       slowpaste msec

       Define the speed at which text is inserted into the current window
       by the paste ("C-a  ]") command.   If  the  slowpaste  value  is
       nonzero  text is written character by character.  screen will make a
       pause of msec milliseconds after each single character write  to
       allow the application to process its input. Only use slowpaste if
       your underlying system exposes flow control problems while pasting
       large amounts of text.

       sort

       Sort the windows in alphabetical order of the window tiles. [titles?]

       split [-v]

       Split the current region into two new ones. All regions on the
       display are resized to make room  for the new region. The blank
       window is displayed on the new region. Splits are made horizontally
       unless -v is used. Use the "remove" or the "only" command to delete
       regions.  Use "focus" to toggle between regions.

       startup_message on|off

       Select  whether  you want to see the copyright notice during
       startup.  Default is `on', as you probably noticed.

       stuff [string]

       Stuff the string string in the input buffer of the  current  window.
       This  is  like  the "paste" command but with much less overhead.
       Without a parameter, screen will prompt for a string to stuff.  You
       cannot paste large buffers with the "stuff" command. It is most use-
       ful for key bindings. See also "bindkey".

       suspend

       Suspend  screen.  The windows are in the `detached' state, while
       screen is suspended. This feature relies on the shell being able to
       do job control.

       time [string]

       Uses the message line to display the time of day, the host name,
       and  the  load  averages over  1,  5,  and  15  minutes (if this is
       available on your system).  For window specific information, use
       "info".

       title [windowtitle]

       Set the name of the current window to windowtitle. If no name is
       specified, screen prompts for one. This command was known as `aka'
       in previous releases.

       unsetenv var

       Unset an environment variable.

       vbell [on|off]

       Sets the visual bell setting for this window. Omitting the parameter
       toggles the  setting.  If  vbell  is switched on, but your terminal
       does not support a visual bell, a `vbell-mes- sage' is displayed in
       the status line when the bell character (^G)  is  received.   Visual
       bell support of a terminal is defined by the termcap variable `vb'
       (terminfo: 'flash').  Per default, vbell is off, thus the audible
       bell is used.  See also `bell_msg'.

       vbell_msg [message]

       Sets the visual bell message. message is printed to the status line
       if the window receives a bell character (^G), vbell is set to "on",
       but the terminal does not  support  a  visual bell.  The default
       message is "Wuff, Wuff!!".  Without a parameter, the current message
       is shown.

       vbellwait sec

       Define a delay in seconds after each display of screen's visual bell
       message. The  default is 1 second.

       verbose [on|off]

       If  verbose  is  switched on, the command name is echoed, whenever a
       window is created (or resurrected from zombie state). Default is
       off.  Without a parameter, the current  setting is shown.

       version

       Print the current version and the compile date in the status line.

       wall message

       Write a message to all displays. The message will appear in the
       terminal's status line.

       width [-w|-d] [cols [lines]]

       Toggle  the  window width between 80 and 132 columns or set it to
       cols columns if an argu- ment is specified.  The -w option tells
       screen to leave the  display  size unchanged and just set the window
       size, -d vice versa.

       windowlist [-b] [-m] [-g]

       Display  all  windows  in  a table for visual window selection.  If
       screen was in a window group, screen will back out of the group and
       then display the windows in that  group.   If the -b option is
       given, screen will switch to the blank window before presenting the
       list, so that the current window is also selectable.  The -m option
       changes  the  order  of  the windows,  instead of sorting by window
       numbers screen uses its internal most-recently-used list.  The -g
       option will show the windows inside any groups in that level and
       downwards.

       The following keys are used to navigate in "windowlist":
         k, C-p, or up Move up one line.
         j, C-n, or down Move down one line.
         C-g or escape Exit windowlist.
         C-a or home Move to the first line.
         C-e or end Move to the last line.
         C-u or C-d Move one half page up or down.
         C-b or C-f Move one full page up or down.
         0..9 Using the number keys, move to the selected line.
         / Search.
         n Repeat search in the forward direction.
         N Repeat search in the backward direction.
         m Toggle MRU.
         g Toggle group nesting.
         a All window view.
         C-h or backspace Back out the group.
         , Switch numbers with the previous window.
         . Switch numbers with the next window.
         K Kill that window.
         space or enter Select that window.

       windows

       Uses the message line to display a list of all the windows.  Each
       window is listed by num- ber  with the name of process that has been
       started in the window (or its title); the cur- rent window is marked
       with a `*'; the previous window is marked with a `-'; all  the  win-
       dows  that  are "logged in" are marked with a `$'; a background
       window that has received a bell is marked with a `!'; a background
       window that is being monitored and has had  activ- ity  occur  is
       marked  with an `@'; a window which has output logging turned on is
       marked with `(L)'; windows occupied by other users are marked with
       `&';  windows  in  the  zombie state  are marked with `Z'.  If this
       list is too long to fit on the terminal's status line only the
       portion around the current window is displayed.

       wrap [on|off]

       Sets the line-wrap setting for the current window.  When line-wrap
       is on, the second  con- secutive printable character output at the
       last column of a line will wrap to the start of the following line.
       As an added feature, backspace (^H) will also wrap through  the
       left margin  to  the previous line.  Default is `on'. Without any
       options, the state of wrap is toggled.

       writebuf [-e encoding] [filename]

       Writes the contents of the paste buffer to the specified file, or
       the  public  accessible screen-exchange  file  if no filename is
       given. This is thought of as a primitive means of communication
       between screen users on the same host. If an encoding is specified
       the paste buffer  is  recoded  on  the  fly to match the encoding.
       The filename can be set with the bufferfile command and defaults to
       "/tmp/screen-exchange".


TITLES (naming windows)
       You can customize each window's name in the window display (viewed
       with the "windows" com- mand  (C-a  w)) by setting it with one of
       the title commands.  Normally the name displayed is the actual
       command name of the program created in the window.  However, it is
       sometimes useful  to  distinguish various programs of the same name
       or to change the name on-the-fly to reflect the current state of the
       window.

       The default name for all shell windows can be set with the
       "shelltitle"  command  in  the .screenrc  file,  while all other
       windows are created with a "screen" command and thus can have their
       name set with the -t option.  Interactively, there is the
       title-string  escape- sequence  (kname\)  and  the
       "title" command (C-a A).  The former can be output from an
       application to control the window's name under software control,
       and  the  latter will  prompt  for a name when typed.

       Here's some .screenrc examples:

              screen -t top 2 nice top

       Adding  this  line  to your .screenrc would start a nice-d version
       of the "top" command in window 2 named "top" rather than "nice".


THE VIRTUAL TERMINAL
       Each  window  in  a  screen  session  emulates a VT100 terminal,
       with some extra functions added. The VT100 emulator is hard-coded,
       no other terminal types can be emulated.


ENVIRONMENT
       COLUMNS        Number of columns on the terminal (overrides termcap entry).
       HOME           Directory in which to look for .screenrc.
       LINES          Number of lines on the terminal (overrides termcap entry).
       LOCKPRG        Screen lock program.
       PATH           Used for locating programs to run.
       SCREENCAP      For customizing a terminal's TERMCAP value.
       SCREENDIR      Alternate socket directory.
       SCREENRC       Alternate user screenrc file.
       SHELL          Default shell program for opening windows (default  "/bin/sh").   See  also
                      "shell" .screenrc command.
       STY            Alternate socket name.
       SYSSCREENRC    Alternate system screenrc file.
       TERM           Terminal name.
       TERMCAP        Terminal description.
       WINDOW         Window number of a window (at creation time).

FILES
       .../screen-4.?.??/etc/screenrc
       .../screen-4.?.??/etc/etcscreenrc Examples  in the screen distribution package for private
                                         and global initialization files.
       $SYSSCREENRC
       /usr/local/etc/screenrc           screen initialization commands
       $SCREENRC
       $HOME/.screenrc                   Read in after /usr/local/etc/screenrc
       $SCREENDIR/S-
       /local/screens/S-          Socket directories (default)
       /usr/tmp/screens/S-        Alternate socket directories.
       /.termcap       Written by the "termcap" output function
       /usr/tmp/screens/screen-exchange  or
       /tmp/screen-exchange              screen `interprocess communication buffer'
       hardcopy.[0-9]                    Screen images created by the hardcopy function
       screenlog.[0-9]                   Output log files created by the log function
       /usr/lib/terminfo/?/*             or
       /etc/termcap                      Terminal capability databases
       /etc/utmp                         Login records
       $LOCKPRG                          Program that locks a terminal.

COPYLEFT
       Copyright (c) 2010
            Juergen Weigert (jnweiger@immd4.informatik.uni-erlangen.de)
            Sadrul Habib Chowdhury (sadrul@users.sourceforge.net)
       Copyright (c) 2008, 2009
            Juergen Weigert (jnweiger@immd4.informatik.uni-erlangen.de)
            Michael Schroeder (mlschroe@immd4.informatik.uni-erlangen.de)
            Micah Cowan (micah@cowan.name)
            Sadrul Habib Chowdhury (sadrul@users.sourceforge.net)
       Copyright (C) 1993-2003
            Juergen Weigert (jnweiger@immd4.informatik.uni-erlangen.de)
            Michael Schroeder (mlschroe@immd4.informatik.uni-erlangen.de)
       Copyright (C) 1987 Oliver Laumann

       This program is free software; you can redistribute it and/or modify
       it under the terms of the GNU  General  Public License as published
       by the Free Software Foundation; either version 3, or (at your
       option) any later version.  This  program is distributed in the hope
       that it will be useful, but WITHOUT ANY WARRANTY; without even the
       implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the  GNU  General  Public  License  for  more details.

       You  should  have received a copy of the GNU General Public License
       along with this program (see the file COPYING); if not, write to the
       Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
       MA  02111-1307, USA




1 comment:

  1. Well written quick-start! Thanks Nathan. Do you want this to become part of the the official screen documentation? (jw@suse.de)

    ReplyDelete