diff options
Diffstat (limited to 'src/doc/screen.1')
-rw-r--r-- | src/doc/screen.1 | 296 |
1 files changed, 262 insertions, 34 deletions
diff --git a/src/doc/screen.1 b/src/doc/screen.1 index 879dc83..a250b92 100644 --- a/src/doc/screen.1 +++ b/src/doc/screen.1 @@ -97,7 +97,9 @@ 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. +to its window. - Note that you cannot transport environment variables from +the invoking shell to the application (emacs in this case), because it is +forked from the parent screen process, not from the invoking shell. .PP If \*Q/etc/utmp\*U is writable by .IR screen , @@ -231,7 +233,11 @@ The use of this option is discouraged. turns login mode on or off (for /etc/utmp updating). This can also be defined through the \*Qdeflogin\*U .screenrc command. .TP 5 -.BR \-ls " and " \-list +.BR \-ls " [" \fImatch ] +.PD 0 +.TP 5 +.BR \-list " [" \fImatch ] +.PD does not start .IR screen , but prints a list of @@ -282,12 +288,14 @@ emulation (only affects auto-margin terminals without `LP'). This can also be set in your .screenrc by specifying `OP' in a \*Qtermcap\*U command. .TP 5 -.BI "\-p " number_or_name +.BI "\-p " number_or_name|-|=|+ Preselect a window. This is useful when you want to reattach to a specific window or you want to send a command via the \*Q-X\*U option to a specific window. As with screen's select command, \*Q-\*U selects the blank window. As a special case for reattach, \*Q=\*U -brings up the windowlist on the blank window. +brings up the windowlist on the blank window, while a \*Q+\*U +will create a new window. The command will not be +executed if the specified window could not be found. .TP 5 .B \-q Suppress printing of error messages. In combination with \*Q-ls\*U the exit @@ -299,6 +307,23 @@ 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-q\*U has no effect. .TP 5 +.B \-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: + \fBecho\fP + \fBinfo\fP + \fBlastmsg\fP + \fBnumber\fP + \fBselect\fP + \fBtime\fP + \fBtitle\fP + \fBwindows\fP +.TP 5 .BR \-r " [" \fIpid.tty.host ] .PD 0 .TP 5 @@ -326,7 +351,7 @@ had not been specified. The option is set by default if is run as a login-shell (actually screen uses \*Q-xRR\*U in that case). For combinations with the \fB\-d\fP/\fB\-D\fP option see there. .TP 5 -.B \-s +.BI "\-s " program sets the default shell to the program specified, instead of the value in the environment variable $SHELL (or \*Q/bin/sh\*U if not defined). This can also be defined through the \*Qshell\*U .screenrc command. @@ -341,6 +366,10 @@ default [\fItty.host\fP] suffix. sets the title (a.\|k.\|a.) for the default shell or specified program. See also the \*Qshelltitle\*U .screenrc command. .TP 5 +.BI "\-T " term +Set the $TERM enviroment varible using the spcified term as +opposed to the defualt setting of \fBscreen\fP. +.TP 5 .B \-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 @@ -370,7 +399,6 @@ the \fB-d\fP or \fB-r\fP 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. - .SH "DEFAULT KEY BINDINGS" .ta 12n 26n As mentioned, each @@ -509,7 +537,7 @@ automatic margins on and off). .PD Send a control-s to the current window. .IP "\fBC-a S\fP (split)" -Split the current region into two new ones. +Split the current region horizontally into two new ones. See also \fIonly, remove, focus\fP. .IP "\fBC-a t\fP" .PD 0 @@ -561,6 +589,8 @@ Enter command line mode. .IP "\fBC-a esc\fP (copy)" .PD Enter copy/scrollback mode. +.IP "\fBC-a C-]\fP" +.PD 0 .IP "\fBC-a ]\fP (paste .)" .PD Write the contents of the paste buffer to the stdin queue of the @@ -582,6 +612,8 @@ Shows where comes from, where it went to and why you can use it. .IP "\fBC-a _\fP (silence)" Start/stop monitoring the current window for inactivity. +.IP "\fBC-a |\fP (split -v)" +Split the current region vertically into two new ones. .IP "\fBC-a *\fP (displays)" Show a listing of all currently attached displays. @@ -1084,7 +1116,8 @@ This command is normally used together with the \*Qidle\*U command. .B blankerprg .RI [ "program args" ] .PP -Defines a blanker program. Disables the blanker program if no +Defines a blanker program. Disables the blanker program if an +empty argument is given. Shows the currently set blanker program if no arguments are given. .sp .ne 3 @@ -1550,6 +1583,12 @@ Same as the \fBmonitor\fP command except that the default setting for new windows is changed. Initial setting is `off'. .sp .ne 3 +.BR "defmousetrack on" | off +.PP +Same as the \fBmousetrack\fP command except that the default setting for new +windows is changed. Initial setting is `off'. +.sp +.ne 3 .B defnonblock .BR on | off | \fInumsecs .PP @@ -1645,7 +1684,7 @@ Shows a tabular listing of all currently connected user front-ends (displays). This is most useful for multiuser sessions. .sp .ne 3 -.BR "digraph " [ \fIpreset ] +.BR "digraph " [ \fIpreset [ \fI unicode-value ] ] .PP This command prompts the user for a digraph sequence. The next two characters typed are looked up in a builtin table and the @@ -1659,6 +1698,11 @@ number instead. The optional argument is treated as user input, thus one can create an \*Qumlaut\*U key. For example the command "bindkey ^K digraph '"'" enables the user to generate an a-umlaut by typing CTRL-K a. +When a non-zero +.I unicode-value +is specified, a new digraph is created with the specified preset. The digraph is unset +if a zero value is provided for the +.I unicode-value. .sp .ne 3 .B dumptermcap @@ -1855,6 +1899,20 @@ region respectively. Useful bindings are (j and k as in vi) Note that \fBk\fP is traditionally bound to the \fIkill\fP command. .sp .ne 3 +.BI "focusminsize [ ( " width "|max|_ ) ( " height "|max|_ ) ]" +.PP +This forces any currently selected region to be automatically +resized at least a certain \fIwidth\fP and \fIheight\fP. All +other surrounding regions will be resized in order to accommodate. +This constraint follows everytime the \*Qfocus\*U command is +used. The \*Qresize\*U command can be used to increase either +dimension of a region, but never below what is set with +\*Qfocusminsize\*U. The underscore `_' is a synonym for +\fBmax\fP. Setting a \fIwidth\fP and \fIheight\fP of `0 0' +(zero zero) will undo any constraints and allow for manual resizing. +Without any parameters, the minimum width and height is shown. +.sp +.ne 3 .BR "gr " [ on | off ] .PP Turn GR charset switching on/off. Whenever screen sees an input @@ -1864,6 +1922,15 @@ default (see also \*Qdefgr\*U) is not to process GR switching because otherwise the ISO88591 charset would not work. .sp .ne 3 +.BI group +.RI [ grouptitle ] +.PP +Change or show the group the current window belongs to. Windows can +be moved around between different groups by specifying the name of +the destination group. Without specifying a group, the title of the +current group is displayed. +.sp +.ne 3 .B hardcopy .RB [ -h ] .RI [ file ] @@ -2002,7 +2069,7 @@ Sets a command that is run after the specified number of seconds inactivity is reached. This command will normally be the \*Qblanker\*U command to create a screen blanker, but it can be any screen command. If no command is specified, only the timeout is set. A timeout of -zero (ot the special timeout \fBoff\fP) disables the timer. +zero (or the special timeout \fBoff\fP) disables the timer. If no arguments are given, the current settings are displayed. .sp .ne 3 @@ -2085,6 +2152,123 @@ away when you press a key (unless your terminal has a hardware status line). Refer to the commands \*Qmsgwait\*U and \*Qmsgminwait\*U for fine tuning. .sp .ne 3 +.BR "layout new " [\fItitle\fP] +.PP +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 \*Qlayout\*U. You +can always change the title later by using the command +\fBlayout title\fP. +.sp +.ne 3 +.BR "layout remove " [\fIn|title\fP] +.PP +Remove, or in other words, delete the specified layout. Either +the number or the title can be specified. Without either +specification, \fIscreen\fP will remove the current layout. + +Removing a layout does not affect your set windows or regions. +.sp +.ne 3 +.B layout next +.PP +Switch to the next layout available +.sp +.ne 3 +.B layout prev +.PP +Switch to the previous layout available +.sp +.ne 3 +.BR "layout select " [\fIn|title\fP] +.PP +Select the desired layout. Either the number or the title can +be specified. Without either specification, \fIscreen\fP will +prompt and ask which screen is desired. To see which layouts are +available, use the \fBlayout show\fP command. +.sp +.ne 3 +.B layout show +.PP +List on the message line the number(s) and title(s) of the available +layout(s). The current layout is flagged. +.sp +.ne 3 +.BR "layout title " [\fItitle\fP] +.PP +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. +.sp +.ne 3 +.BR "layout number " [\fIn\fP] +.PP +Change or display the number of the current layout. An integer given +will be used to number the layout. Without any options, the current +number and title is displayed on the message line. +.sp +.ne 3 +.BR "layout attach " [\fItitle\fP|\fB:last\fP] +.PP +Change or display which layout to reattach back to. The default is +\fB:last\fP, which tells \fIscreen\fP to reattach back to the last +used layout just before detachment. By supplying a title, You can +instruct \fIscreen\fP 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. +.sp +.ne 3 +.BR "layout save " [\fIn|title\fP] +.PP +Remember the current arrangement of regions. When used, \fIscreen\fP +will remember the arrangement of vertically and horizontally split +regions. This arrangement is restored when a \fIscreen\fP session +is reattached or switched back from a different layout. If the +session ends or the \fIscreen\fP process dies, the layout +arrangements are lost. The \fBlayout dump\fP command should help +in this siutation. If a number +or title is supplied, \fIscreen\fP will remember the arrangement of +that particular layout. Without any options, \fIscreen\fP will +remember the current layout. + +Saving your regions can be done automatically by using the +\fBlayout autosave\fP command. +.sp +.ne 3 +.BR "layout autosave " [\fBon|off\fP] +.PP +Change or display the status of automatcally saving layouts. The +default is \fBon\fP, meaning when \fIscreen\fP 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 \fBoff\fP, that arrangement will only be +restored to either to the last manual save, using \fBlayout save\fP, +or to when the layout was first created, to a single region with +a single window. Without either an \fBon\fP or \fBoff\fP, the +current status is displayed on the message line. +.sp +.ne 3 +.BR "layout dump " [\fIfilename\fP] +.PP +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 \fIlayout-dump\fP, saved in the directory that the +\fIscreen\fP process was started in. If the file already exists, +\fBlayout dump\fP will append to that file. As an example: +.PP +.nf + C-a : layout dump /home/user/.screenrc +.fi +.PP +will save or append the layout to the user's \fI.screenrc\fP file. +.sp +.ne 3 .B license .PP Display the disclaimer page. This is done whenever @@ -2218,7 +2402,8 @@ single statement. .BI "maxwin " num .PP Set the maximum window number screen will create. Doesn't affect -already existing windows. The number may only be decreased. +already existing windows. The number can be increased only when there are no +existing windows. .sp .ne 3 .B meta @@ -2236,6 +2421,18 @@ with an `@' in the window-status display. Monitoring is initially off for all windows. .sp .ne 3 +.BR "mousetrack " [ on | off ] +.PP +This command determines whether +.I 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 \fBon\fP +or \fBoff\fP, the current state is displayed. The default state +is determined by the \*Qdefmousetrack\*U command. +.sp +.ne 3 .BI "msgminwait " sec .PP Defines the time @@ -2276,7 +2473,8 @@ available if .I screen was compiled with the NETHACK flag defined. The default setting is then determined by the presence of the environment -variable $NETHACKOPTIONS. +variable $NETHACKOPTIONS and the file ~/.nethackrc - if either one is present, +the default is \fBon\fP. .sp .ne 3 .B next @@ -2300,11 +2498,12 @@ some time it restarts to accept characters, screen will unblock the display and redisplay the updated window contents. .sp .ne 3 -.BR "number " [ \fIn ] +.BR "number " [[+|-] \fIn ] .PP -Change the current windows number. If the given number \fIn\fP is already +Change the current window's number. If the given number \fIn\fP is already used by another window, both windows exchange their numbers. If no argument is -specified, the current window number (and title) is shown. +specified, the current window number (and title) is shown. Using `+' or `-' +will change the window's number by the relative amount specified. .sp .ne 3 .BR "obuflimit " [ \fIlimit ] @@ -2518,6 +2717,15 @@ Unlinks the screen-exchange file used by the commands \*Qwritebuf\*U and \*Qreadbuf\*U. .sp .ne 3 +.B "rendition bell" | monitor | silence | so +.RB "\fIattr\fR " [ \fIcolor ] +.PP +Change the way +.I screen +renders the titles of windows that have monitor or bell flags set in caption or hardstatus or windowlist. See the \*QSTRING ESCAPES\*U chapter for the syntax of the modifiers. +The default for monitor is currently \*Q=b \*U (bold, active colors), for bell \*Q=ub \*U (underline, bold and active colors), and \*Q=u \*U for silence. +.sp +.ne 3 .B "reset" .PP Reset the virtual terminal to its \*Qpower-on\*U values. Useful when strange @@ -2544,7 +2752,7 @@ resize min minimize current region height .PP .sp .ne 3 -.B "screen \fP[\fI-opts\fP] [\fIn\fP] [\fIcmd\fP [\fIargs\fP]]" +.B "screen \fP[\fI-opts\fP] [\fIn\fP] [\fIcmd\fP [\fIargs\fP]|\fB//group\fP]" .PP Establish a new window. The flow-control options (\fB\-f\fP, \fB\-fn\fP and \fB\-fa\fP), @@ -2553,11 +2761,14 @@ title (a.\|k.\|a.) option (\fB\-t\fP), login options (\fB-l\fP and \fB-ln\fP) and scrollback option (\fB-h\fP <num>) may be specified with each command. The option (\fB-M\fP) turns monitoring on for this window. The option (\fB-L\fP) turns output logging on for this 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 available number). +If an optional number \fIn\fP in the range 0..MAXWIN-1 is given, +the window number \fIn\fP 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 \*Qscreen\*U, this command (with the given arguments) is started in the window; otherwise, a shell is created. +If \fB//group\fP is supplied, a container-type window is created in +which other windows may be created inside it. + Thus, if your \*Q.screenrc\*U contains the lines .sp .nf @@ -2601,7 +2812,7 @@ When a new window is established, the first available number is assigned to this window. Thus, the first window can be activated by \*Qselect 0\*U. The number of windows is limited at compile-time by the MAXWIN -configuration parameter. +configuration parameter (which defaults to 40). There are two special WindowIDs, \*Q-\*U selects the internal blank window and \*Q.\*U selects the current window. The latter is useful if used with screen's \*Q-X\*U option. @@ -2612,8 +2823,10 @@ latter is useful if used with screen's \*Q-X\*U option. Rename the current session. Note, that for \*Qscreen -list\*U the name shows up with the process-id prepended. If the argument \*Qname\*U is omitted, the name of this session is displayed. Caution: The $STY -environment variables still reflects the old name. This may result in -confusion. +environment variables will still reflect the old name in pre-existing +shells. This may result in confusion. Use of this command is generally +discouraged. Use the \*Q-S\*U command-line option if you want to +name a new session. The default is constructed from the tty and host names. .sp .ne 3 @@ -2705,20 +2918,17 @@ default screenrc files to have an effect. .B sorendition .RB [ "\fIattr\fR " [ \fIcolor ]] .PP -Change the way -.I screen -does highlighting for text marking and printing messages. -See the \*QSTRING ESCAPES\*U chapter for the syntax of the modifiers. -The default is currently \*Q=s dd\*U (standout, default colors). +This command is deprecated. See "rendition so" instead. .sp .ne 3 .B split +.RB [ -v ] .PP 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. Use the \*Qremove\*U or the -\*Qonly\*U command to delete regions. -Use \*Qfocus\*U to toggle between regions. +window is displayed on the new region. Splits are made horizontally +unless -v is used. Use the \*Qremove\*U or the \*Qonly\*U command +to delete regions. Use \*Qfocus\*U to toggle between regions. .sp .ne 3 .B "startup_message on\fP|\fBoff" @@ -2727,21 +2937,22 @@ Select whether you want to see the copyright notice during startup. Default is `on', as you probably noticed. .sp .ne 3 -.B stuff -.I string +.B stuff +.RB [ "\fIstring\fR" ] .PP Stuff the string .I string in the input buffer of the current window. This is like the \*Qpaste\*U command but with much less overhead. +Without a paramter, screen will prompt for a string to stuff. You cannot paste large buffers with the \*Qstuff\*U command. It is most useful for key bindings. See also \*Qbindkey\*U. .sp .ne 3 .B su -.RB [ username " [" password -.RB [ password2 ]] +.RI [ username " [" password +.RI [ password2 ]]] .PP Substitute the user of a display. The command prompts for all parameters that are omitted. If passwords are specified as parameters, they have to be @@ -2904,6 +3115,14 @@ prompts for one. This command was known as `aka' in previous releases. .sp .ne 3 +.BI "unbindall " +.PP +Unbind all the bindings. This can be useful when +screen is used solely for its detaching abilities, such as when +letting a console application run as a daemon. If, for some reason, +it is necessary to bind commands after this, use 'screen -X'. +.sp +.ne 3 .BI "unsetenv " var .PP Unset an environment variable. @@ -2992,6 +3211,7 @@ vice versa. .B windowlist .RB [ -b ] .RB [ -m ] +.RB [ -g ] .br .B windowlist .B string @@ -3004,6 +3224,8 @@ vice versa. Display all windows in a table for visual window selection. The desired window can be selected via the standard movement keys (see the \*Qcopy\*U command) and activated via the return key. +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 -b option is given, screen will switch to the blank window before @@ -3012,6 +3234,10 @@ The .B -m option changes the order of the windows, instead of sorting by window numbers screen uses its internal most-recently-used list. +The +.B -g +option will show the windows inside any groups in that level +and downwards. The table format can be changed with the \fBstring\fP and \fBtitle\fP option, the title is displayed as table heading, while @@ -3307,6 +3533,8 @@ month number month name .IP n window number +.IP P +sets %? to true if the current region is in copy/paste mode .IP S session name .IP s |