1 .\" Copyright (c) 1985, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Edward Wang at The University of California, Berkeley.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" @(#)window.1 8.2 (Berkeley) 12/30/93
43 .Nd window environment
49 .Op Fl e Ar escape-char
53 implements a window environment on
57 A window is a rectangular portion of the physical terminal
58 screen associated with a set of processes. Its size and
59 position can be changed by the user at any time. Processes
60 communicate with their window in the same way they normally
61 interact with a terminal\-through their standard input, output,
62 and diagnostic file descriptors. The window program handles the
63 details of redirecting input and output to and from the
64 windows. At any one time, only one window can receive
65 input from the keyboard, but all windows can simultaneously send output
70 starts up, the commands (see long commands below)
73 in the user's home directory are
74 executed. If it does not exist, two equal sized windows spanning
75 the terminal screen are created by default.
77 The command line options are
80 Turn on terse mode (see
84 Fast. Don't perform any startup action.
88 and create the two default
90 .It Fl e Ar escape-char
91 Set the escape character to
94 can be a single character, or in the form
98 is any character, meaning
99 .No control\- Ns Ar X .
103 as a long command (see below)
104 before doing anything else.
107 Windows can overlap and are framed as necessary. Each window
108 is named by one of the digits ``1'' to ``9''. This one-character
109 identifier, as well as a user definable label string, are displayed
110 with the window on the top edge of its frame. A window can be
111 designated to be in the
113 in which case it will always be
114 on top of all normal, non-foreground windows, and can be covered
115 only by other foreground windows. A window need not be completely
116 within the edges of the terminal screen. Thus a large window
117 (possibly larger than the screen) may be positioned to show only
118 a portion of its full size.
120 Each window has a cursor and a set of control functions. Most intelligent
121 terminal operations such as line and
122 character deletion and insertion are supported. Display modes
123 such as underlining and reverse video are available if they are
124 supported by the terminal. In addition,
125 similar to terminals with multiple pages of memory,
126 each window has a text buffer which can have more lines than the window
128 .Ss Process Environment
129 With each newly created window, a shell program is spawned with its
130 process environment tailored to that window. Its standard input,
131 output, and diagnostic file descriptors are bound to one end of either
132 a pseudo-terminal (see
138 If a pseudo-terminal is used, then its special
139 characters and modes (see
141 are copied from the physical
144 entry tailored to this window is created
145 and passed as environment (see
149 The termcap entry contains the window's size and
150 characteristics as well as information from the physical terminal,
151 such as the existence of underline, reverse video, and other display
152 modes, and the codes produced by the terminal's function keys,
153 if any. In addition, the window size attributes of the pseudo-terminal
154 are set to reflect the size of this window, and updated whenever
155 it is changed by the user. In particular, the editor
158 this information to redraw its display.
160 During normal execution,
162 can be in one of two states:
163 conversation mode and command mode. In conversation mode, the
164 terminal's real cursor is placed at the cursor position of a particular
165 window--called the current window--and input from the keyboard is sent
166 to the process in that window. The current window is always
167 on top of all other windows, except those in foreground. In addition,
168 it is set apart by highlighting its identifier and label in reverse video.
172 escape character (normally
175 mode switches it into command mode. In command mode, the top line of
176 the terminal screen becomes the command prompt window, and
178 interprets input from the keyboard as commands to manipulate windows.
180 There are two types of commands: short commands are usually one or two
181 key strokes; long commands are strings either typed by the user in the
182 command window (see the
184 command below), or read from a file (see
190 represents one of the digits ``1'' to ``9''
191 corresponding to the windows 1 to 9.
194 .No control\- Ns Ar X ,
197 is any character. In particular,
202 is the escape key, or
208 as the current window
209 and return to conversation mode.
213 but stay in command mode.
215 Select the previous window and return to conversation
216 mode. This is useful for toggling between two windows.
218 Return to conversation mode.
220 Return to conversation mode and write
223 current window. Thus, typing two
226 mode sends one to the current window. If the
228 escape is changed to some other character, that
229 character takes the place of
233 List a short summary of commands.
239 Confirmation is requested.
244 Create a new window. The user is prompted for the positions
245 of the upper left and lower right corners of the window.
246 The cursor is placed on the screen and the keys ``h'', ``j'',
248 move the cursor left, down, up, and right, respectively.
249 The keys ``H'', ``J'', ``K'', and ``L'' move the cursor to the respective
250 limits of the screen. Typing a number before the movement keys
251 repeats the movement that number of times. Return enters the cursor position
252 as the upper left corner of the window. The lower right corner
253 is entered in the same manner. During this process,
254 the placement of the new window is indicated by a rectangular
255 box drawn on the screen, corresponding to where the new window
256 will be framed. Typing escape at any point
257 cancels this command.
259 This window becomes the current window,
260 and is given the first available ID. The default buffer size
265 Only fully visible windows can be created this way.
269 The process in the window is sent
270 the hangup signal (see
274 handle this signal correctly and cause no problems.
278 to another location. A box in the shape
279 of the window is drawn on
280 the screen to indicate the new position of the window, and the same keys as
283 command are used to position the box. The
284 window can be moved partially off-screen.
288 to its previous position.
290 Change the size of window
293 to enter the new lower right corner of the window. A box
294 is drawn to indicate the new window size. The same
299 are used to enter the position.
303 to its previous size.
305 Scroll the current window up by one line.
307 Scroll the current window down by one line.
309 Scroll the current window up by half the window size.
311 Scroll the current window down by half the window size.
313 Scroll the current window up by the full window size.
315 Scroll the current window down by the full window size.
317 Move the cursor of the current window left by one column.
319 Move the cursor of the current window down by one line.
321 Move the cursor of the current window up by one line.
323 Move the cursor of the current window right by one column.
325 Yank. The user is prompted to enter two points within the current
326 window. Then the content of the current window between those two points
327 is saved in the yank buffer.
329 Put. The content of the yank buffer is written to the current
332 Stop output in the current window.
334 Start output in the current window.
336 Enter a line to be executed as long commands.
338 editing characters (erase character, erase word, erase line)
342 Long commands are a sequence of statements
343 parsed much like a programming language, with a syntax
344 similar to that of C. Numeric and string expressions and variables
345 are supported, as well as conditional statements.
347 There are two data types: string and number. A string is a sequence
348 of letters or digits beginning with a letter. ``_'' and ``.'' are
349 considered letters. Alternately, non-alphanumeric characters can
350 be included in strings by quoting them in ``"'' or escaping them
351 with ``\\''. In addition, the ``\\'' sequences of C are supported,
352 both inside and outside quotes (e.g., ``\\n'' is a new line,
353 ``\\r'' a carriage return). For example, these are legal strings:
354 abcde01234, "&#$^*&#", ab"$#"cd, ab\\$\\#cd, "/usr/ucb/window".
356 A number is an integer value in one of three forms:
357 a decimal number, an octal number preceded by ``0'',
358 or a hexadecimal number preceded by ``0x'' or ``0X''. The natural
359 machine integer size is used (i.e., the signed integer type
360 of the C compiler). As in C, a non-zero number represents
363 The character ``#'' begins a comment which terminates at the
366 A statement is either a conditional or an expression. Expression
367 statements are terminated with a new line or ``;''. To continue
368 an expression on the next line, terminate the first line with ``\\''.
369 .Ss Conditional Statement
371 has a single control structure:
372 the fully bracketed if statement in the form
374 .Bd -literal -offset indent -compact
391 parts are optional, and the latter can
392 be repeated any number of times.
398 are similar to those in the
399 C language, with most C operators supported on numeric
400 operands. In addition, some are overloaded to operate on strings.
402 When an expression is used as a statement, its value is discarded
403 after evaluation. Therefore, only expressions with side
404 effects (assignments and function calls) are useful as statements.
406 Single valued (no arrays) variables are supported, of both
407 numeric and string values. Some variables are predefined. They
410 The operators in order of increasing precedence:
417 Assignment. The variable of name
419 which must be string valued,
420 is assigned the result of
436 (non-zero numeric value); returns the value of
452 Logical or. Numeric values only. Short circuit evaluation is supported
463 Logical and with short circuit evaluation. Numeric values only.
469 Bitwise or. Numeric values only.
475 Bitwise exclusive or. Numeric values only.
481 Bitwise and. Numeric values only.
490 Comparison (equal and not equal, respectively). The boolean
491 result (either 1 or 0) of the comparison is returned. The
492 operands can be numeric or string valued. One string operand
493 forces the other to be converted to a string in necessary.
505 Less than, greater than, less than or equal to,
506 greater than or equal to. Both numeric and string values, with
507 automatic conversion as above.
516 If both operands are numbers,
519 shifted left (or right) by
524 a string, then its first (or last)
529 is also a string, then its length is used
530 in place of its value).
539 Addition and subtraction on numbers. For ``+'', if one
540 argument is a string, then the other is converted to a string,
541 and the result is the concatenation of the two strings.
553 Multiplication, division, modulo. Numbers only.
555 .Ic \- Ns Aq Va expr ,
556 .Ic ~ Ns Aq Va expr ,
557 .Ic \&! Ns Aq Va expr ,
558 .Ic \&$ Ns Aq Va expr ,
559 .Ic \&$? Ns Aq Va expr
561 The first three are unary minus, bitwise complement and logical complement
562 on numbers only. The operator, ``$'', takes
565 the value of the variable of that name. If
570 and it appears within an alias macro (see below),
571 then it refers to the nth argument of the alias invocation. ``$?''
572 tests for the existence of the variable
575 if it exists or 0 otherwise.
577 .Ao Va expr Ac Ns Pq Aq Ar arglist
581 must be a string that is the unique
582 prefix of the name of a builtin
585 or the full name of a user defined alias macro. In the case of a builtin
588 can be in one of two forms:
589 .Bd -literal -offset indent
590 <expr1>, <expr2>, ...
591 argname1 = <expr1>, argname2 = <expr2>, ...
594 The two forms can in fact be intermixed, but the result is
595 unpredictable. Most arguments can be omitted; default values will
596 be supplied for them. The
598 can be unique prefixes
599 of the argument names. The commas separating
600 arguments are used only to disambiguate, and can usually be omitted.
602 Only the first argument form is valid for user defined aliases. Aliases
603 are defined using the
605 builtin function (see below). Arguments
606 are accessed via a variant of the variable mechanism (see ``$'' operator
609 Most functions return value, but some are used for side effect
610 only and so must be used as statements. When a function or an alias is used
611 as a statement, the parentheses surrounding
612 the argument list may be omitted. Aliases return no value.
614 .Ss Builtin Functions
615 The arguments are listed by name in their natural
616 order. Optional arguments are in square brackets
619 that have no names are in angle brackets
621 An argument meant to be a boolean flag (often named
632 obvious meanings, or it can be a numeric expression,
633 in which case a non-zero value is true.
636 .Ic alias Ns Po Bq Aq Ar string ,
637 .Bq Aq Ar string\-list Pc
639 If no argument is given, all currently defined alias macros are
642 is defined as an alias,
644 .Aq Ar string\-list > .
645 The previous definition of
647 if any, is returned. Default for
650 .It Ic close Ns Pq Aq Ar window\-list
651 Close the windows specified in
652 .Aq Ar window\-list .
657 than all windows are closed. No value is returned.
658 .It Ic cursormodes Ns Pq Bq Ar modes
659 Set the window cursor to
663 or of the mode bits defined as the variables
672 (graphics, terminal dependent). Return
673 value is the previous modes. Default is no change.
675 .Li cursor($m_rev$m_blk)
676 sets the window cursors to blinking
678 .It Ic default_nline Ns Pq Bq Ar nline
679 Set the default buffer size to
682 48 lines. Returns the old default buffer size. Default is
683 no change. Using a very large buffer can slow the program down
685 .It Ic default_shell Ns Pq Bq Aq Ar string\-list
686 Set the default window shell program to
687 .Aq Ar string\-list .
689 the first string in the old shell setting. Default is no change. Initially,
690 the default shell is taken from the environment variable
692 .It Ic default_smooth Ns Pq Bq Ar flag
693 Set the default value of the
698 (see below). The argument
699 is a boolean flag (one of
707 as described above). Default is no change.
708 The old value (as a number) is returned.
709 The initial value is 1 (true).
711 .Ic echo Ns ( Op Ar window ,
712 .Bq Aq Ar string\-list )
714 Write the list of strings,
719 by spaces and terminated with a new line. The strings are only
720 displayed in the window, the processes in the window are not
723 below). No value is returned. Default
724 is the current window.
725 .It Ic escape Ns Pq Bq Ar escapec
726 Set the escape character to
729 escape character as a one-character string. Default is no
732 can be a string of a single character, or
736 .No control\- Ns Ar X .
738 .Ic foreground Ns ( Bq Ar window ,
743 in or out of foreground.
745 is a boolean value. The old foreground flag
746 is returned. Default for
748 is the current window,
753 .Ic label Ns ( Bq Ar window ,
761 label as a string. Default for
766 is no change. To turn
767 off a label, set it to an empty string ("").
769 No arguments. List the identifiers and labels of all windows. No
771 .It Ic select Ns Pq Bq Ar window
774 the current window. The previous current window
775 is returned. Default is no change.
776 .It Ic source Ns Pq Ar filename
777 Read and execute the long commands in
779 Returns \-1 if the file cannot be read, 0 otherwise.
780 .It Ic terse Ns Pq Bq flag
783 In terse mode, the command window
784 stays hidden even in command mode, and errors are reported by
785 sounding the terminal's bell.
790 above. Returns the old terse flag.
791 Default is no change.
792 .It Ic unalias Ns Pq Ar alias
799 .It Ic unset Ns Pq Ar variable
806 .It Ic variables Ns Pq
807 No arguments. List all variables. No value is returned.
809 .Ic window Ns ( Bq Ar row ,
822 Open a window with upper left corner at
831 then that many lines are allocated for the text buffer. Otherwise,
832 the default buffer size is used. Default values for
839 the upper, left-most, lower, or right-most extremes of the
848 interpreted in the same way as the argument to
851 they mean, respectively, put a frame around this window (default true),
852 allocate pseudo-terminal for this window rather than socketpair (default
853 true), and map new line characters in this window to carriage return
854 and line feed (default true if socketpair is used, false otherwise).
855 Normally, a window is automatically closed when its process
858 to true (default false) prevents this
861 is true, the screen is updated more frequently
862 (for this window) to produce a more terminal-like behavior.
869 is a list of strings that will be used as the shell
870 program to place in the window (default is the program specified
873 see above). The created window's identifier
874 is returned as a number.
876 .Ic write Ns ( Bq Ar window ,
877 .Bq Aq Ar string\-list )
879 Send the list of strings,
884 by spaces but not terminated with a new line. The strings are actually
885 given to the window as input. No value is returned. Default
886 is the current window.
888 .Ss Predefined Variables
889 These variables are for information only. Redefining them does
890 not affect the internal operation of
892 .Bl -tag -width modes
894 The baud rate as a number between 50 and 38400.
896 The display modes (reverse video, underline, blinking, graphics)
897 supported by the physical terminal. The value of
899 is the bitwise or of some of the one bit values,
906 These values are useful
907 in setting the window cursors' modes (see
911 The blinking mode bit.
913 The graphics mode bit (not very useful).
915 The reverse video mode bit.
917 The underline mode bit.
919 The number of columns on the physical screen.
921 The number of rows on the physical screen.
923 The terminal type. The standard name, found in the second name
924 field of the terminal's
929 utilizes these environment variables:
936 .Bl -tag -width /dev/[pt]ty[pq]? -compact
938 startup command file.
939 .It Pa /dev/[pt]ty[pq]?
940 pseudo-terminal devices.
948 Should be self explanatory.