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
36 .\" $FreeBSD: src/usr.bin/window/window.1,v 1.5.2.6 2002/06/21 15:30:19 charnier Exp $
37 .\" $DragonFly: src/usr.bin/window/window.1,v 1.3 2006/02/17 19:39:17 swildner Exp $
44 .Nd window environment
50 .Op Fl e Ar escape-char
55 utility implements a window environment on
59 A window is a rectangular portion of the physical terminal
60 screen associated with a set of processes. Its size and
61 position can be changed by the user at any time. Processes
62 communicate with their window in the same way they normally
63 interact with a terminal\-through their standard input, output,
64 and diagnostic file descriptors. The window program handles the
65 details of redirecting input and output to and from the
66 windows. At any one time, only one window can receive
67 input from the keyboard, but all windows can simultaneously send output
72 starts up, the commands (see long commands below)
75 in the user's home directory are
76 executed. If it does not exist, two equal sized windows spanning
77 the terminal screen are created by default.
79 The command line options are
82 Turn on terse mode (see
86 Fast. Don't perform any startup action.
90 and create the two default
92 .It Fl e Ar escape-char
93 Set the escape character to
96 can be a single character, or in the form
100 is any character, meaning
101 .No control\- Ns Ar X .
105 as a long command (see below)
106 before doing anything else.
109 Windows can overlap and are framed as necessary. Each window
110 is named by one of the digits ``1'' to ``9''. This one-character
111 identifier, as well as a user definable label string, are displayed
112 with the window on the top edge of its frame. A window can be
113 designated to be in the
115 in which case it will always be
116 on top of all normal, non-foreground windows, and can be covered
117 only by other foreground windows. A window need not be completely
118 within the edges of the terminal screen. Thus a large window
119 (possibly larger than the screen) may be positioned to show only
120 a portion of its full size.
122 Each window has a cursor and a set of control functions. Most intelligent
123 terminal operations such as line and
124 character deletion and insertion are supported. Display modes
125 such as underlining and reverse video are available if they are
126 supported by the terminal. In addition,
127 similar to terminals with multiple pages of memory,
128 each window has a text buffer which can have more lines than the window
130 .Ss Process Environment
131 With each newly created window, a shell program is spawned with its
132 process environment tailored to that window. Its standard input,
133 output, and diagnostic file descriptors are bound to one end of either
134 a pseudo-terminal (see
140 If a pseudo-terminal is used, then its special
141 characters and modes (see
143 are copied from the physical
146 entry tailored to this window is created
147 and passed as environment (see
151 The termcap entry contains the window's size and
152 characteristics as well as information from the physical terminal,
153 such as the existence of underline, reverse video, and other display
154 modes, and the codes produced by the terminal's function keys,
155 if any. In addition, the window size attributes of the pseudo-terminal
156 are set to reflect the size of this window, and updated whenever
157 it is changed by the user. In particular, the editor
160 this information to redraw its display.
162 During normal execution,
164 can be in one of two states:
165 conversation mode and command mode. In conversation mode, the
166 terminal's real cursor is placed at the cursor position of a particular
167 window--called the current window--and input from the keyboard is sent
168 to the process in that window. The current window is always
169 on top of all other windows, except those in foreground. In addition,
170 it is set apart by highlighting its identifier and label in reverse video.
174 escape character (normally
177 mode switches it into command mode. In command mode, the top line of
178 the terminal screen becomes the command prompt window, and
180 interprets input from the keyboard as commands to manipulate windows.
182 There are two types of commands: short commands are usually one or two
183 key strokes; long commands are strings either typed by the user in the
184 command window (see the
186 command below), or read from a file (see
192 represents one of the digits ``1'' to ``9''
193 corresponding to the windows 1 to 9.
196 .No control\- Ns Ar X ,
199 is any character. In particular,
204 is the escape key, or
210 as the current window
211 and return to conversation mode.
215 but stay in command mode.
217 Select the previous window and return to conversation
218 mode. This is useful for toggling between two windows.
220 Return to conversation mode.
222 Return to conversation mode and write
225 current window. Thus, typing two
228 mode sends one to the current window. If the
230 escape is changed to some other character, that
231 character takes the place of
235 List a short summary of commands.
241 Confirmation is requested.
246 Create a new window. The user is prompted for the positions
247 of the upper left and lower right corners of the window.
248 The cursor is placed on the screen and the keys ``h'', ``j'',
250 move the cursor left, down, up, and right, respectively.
251 The keys ``H'', ``J'', ``K'', and ``L'' move the cursor to the respective
252 limits of the screen. Typing a number before the movement keys
253 repeats the movement that number of times. Return enters the cursor position
254 as the upper left corner of the window. The lower right corner
255 is entered in the same manner. During this process,
256 the placement of the new window is indicated by a rectangular
257 box drawn on the screen, corresponding to where the new window
258 will be framed. Typing escape at any point
259 cancels this command.
261 This window becomes the current window,
262 and is given the first available ID. The default buffer size
267 Only fully visible windows can be created this way.
271 The process in the window is sent
272 the hangup signal (see
276 handle this signal correctly and cause no problems.
280 to another location. A box in the shape
281 of the window is drawn on
282 the screen to indicate the new position of the window, and the same keys as
285 command are used to position the box. The
286 window can be moved partially off-screen.
290 to its previous position.
292 Change the size of window
295 to enter the new lower right corner of the window. A box
296 is drawn to indicate the new window size. The same
301 are used to enter the position.
305 to its previous size.
307 Scroll the current window up by one line.
309 Scroll the current window down by one line.
311 Scroll the current window up by half the window size.
313 Scroll the current window down by half the window size.
315 Scroll the current window up by the full window size.
317 Scroll the current window down by the full window size.
319 Move the cursor of the current window left by one column.
321 Move the cursor of the current window down by one line.
323 Move the cursor of the current window up by one line.
325 Move the cursor of the current window right by one column.
327 Yank. The user is prompted to enter two points within the current
328 window. Then the content of the current window between those two points
329 is saved in the yank buffer.
331 Put. The content of the yank buffer is written to the current
334 Stop output in the current window.
336 Start output in the current window.
338 Enter a line to be executed as long commands.
340 editing characters (erase character, erase word, erase line)
344 Long commands are a sequence of statements
345 parsed much like a programming language, with a syntax
346 similar to that of C. Numeric and string expressions and variables
347 are supported, as well as conditional statements.
349 There are two data types: string and number. A string is a sequence
350 of letters or digits beginning with a letter. ``_'' and ``.'' are
351 considered letters. Alternately, non-alphanumeric characters can
352 be included in strings by quoting them in ``"'' or escaping them
353 with ``\\''. In addition, the ``\\'' sequences of C are supported,
354 both inside and outside quotes (e.g., ``\\n'' is a new line,
355 ``\\r'' a carriage return). For example, these are legal strings:
356 abcde01234, "&#$^*&#", ab"$#"cd, ab\\$\\#cd, "/usr/ucb/window".
358 A number is an integer value in one of three forms:
359 a decimal number, an octal number preceded by ``0'',
360 or a hexadecimal number preceded by ``0x'' or ``0X''. The natural
361 machine integer size is used (i.e., the signed integer type
362 of the C compiler). As in C, a non-zero number represents
365 The character ``#'' begins a comment which terminates at the
368 A statement is either a conditional or an expression. Expression
369 statements are terminated with a new line or ``;''. To continue
370 an expression on the next line, terminate the first line with ``\\''.
371 .Ss Conditional Statement
374 utility has a single control structure:
375 the fully bracketed if statement in the form
377 .Bd -literal -offset indent -compact
394 parts are optional, and the latter can
395 be repeated any number of times.
401 are similar to those in the
402 C language, with most C operators supported on numeric
403 operands. In addition, some are overloaded to operate on strings.
405 When an expression is used as a statement, its value is discarded
406 after evaluation. Therefore, only expressions with side
407 effects (assignments and function calls) are useful as statements.
409 Single valued (no arrays) variables are supported, of both
410 numeric and string values. Some variables are predefined. They
413 The operators in order of increasing precedence:
420 Assignment. The variable of name
422 which must be string valued,
423 is assigned the result of
439 (non-zero numeric value); returns the value of
455 Logical or. Numeric values only. Short circuit evaluation is supported
466 Logical and with short circuit evaluation. Numeric values only.
472 Bitwise or. Numeric values only.
478 Bitwise exclusive or. Numeric values only.
484 Bitwise and. Numeric values only.
493 Comparison (equal and not equal, respectively). The boolean
494 result (either 1 or 0) of the comparison is returned. The
495 operands can be numeric or string valued. One string operand
496 forces the other to be converted to a string in necessary.
508 Less than, greater than, less than or equal to,
509 greater than or equal to. Both numeric and string values, with
510 automatic conversion as above.
519 If both operands are numbers,
522 shifted left (or right) by
527 a string, then its first (or last)
532 is also a string, then its length is used
533 in place of its value).
542 Addition and subtraction on numbers. For ``+'', if one
543 argument is a string, then the other is converted to a string,
544 and the result is the concatenation of the two strings.
556 Multiplication, division, modulo. Numbers only.
558 .Ic \- Ns Aq Va expr ,
559 .Ic ~ Ns Aq Va expr ,
560 .Ic \&! Ns Aq Va expr ,
561 .Ic \&$ Ns Aq Va expr ,
562 .Ic \&$? Ns Aq Va expr
564 The first three are unary minus, bitwise complement and logical complement
565 on numbers only. The operator, ``$'', takes
568 the value of the variable of that name. If
573 and it appears within an alias macro (see below),
574 then it refers to the nth argument of the alias invocation. ``$?''
575 tests for the existence of the variable
578 if it exists or 0 otherwise.
580 .Ao Va expr Ac Ns Pq Aq Ar arglist
584 must be a string that is the unique
585 prefix of the name of a builtin
588 or the full name of a user defined alias macro. In the case of a builtin
591 can be in one of two forms:
592 .Bd -literal -offset indent
593 <expr1>, <expr2>, ...
594 argname1 = <expr1>, argname2 = <expr2>, ...
597 The two forms can in fact be intermixed, but the result is
598 unpredictable. Most arguments can be omitted; default values will
599 be supplied for them. The
601 can be unique prefixes
602 of the argument names. The commas separating
603 arguments are used only to disambiguate, and can usually be omitted.
605 Only the first argument form is valid for user defined aliases. Aliases
606 are defined using the
608 builtin function (see below). Arguments
609 are accessed via a variant of the variable mechanism (see ``$'' operator
612 Most functions return value, but some are used for side effect
613 only and so must be used as statements. When a function or an alias is used
614 as a statement, the parentheses surrounding
615 the argument list may be omitted. Aliases return no value.
617 .Ss Builtin Functions
618 The arguments are listed by name in their natural
619 order. Optional arguments are in square brackets
622 that have no names are in angle brackets
624 An argument meant to be a boolean flag (often named
635 obvious meanings, or it can be a numeric expression,
636 in which case a non-zero value is true.
640 .Bq Aq Ar string\-list
642 If no argument is given, all currently defined alias macros are
645 is defined as an alias,
647 .Aq Ar string\-list > .
648 The previous definition of
650 if any, is returned. Default for
653 .It Ic close Ns Pq Aq Ar window\-list
654 Close the windows specified in
655 .Aq Ar window\-list .
660 than all windows are closed. No value is returned.
661 .It Ic cursormodes Ns Pq Bq Ar modes
662 Set the window cursor to
666 or of the mode bits defined as the variables
675 (graphics, terminal dependent). Return
676 value is the previous modes. Default is no change.
678 .Li cursor($m_rev$m_blk)
679 sets the window cursors to blinking
681 .It Ic default_nline Ns Pq Bq Ar nline
682 Set the default buffer size to
685 48 lines. Returns the old default buffer size. Default is
686 no change. Using a very large buffer can slow the program down
688 .It Ic default_shell Ns Pq Bq Aq Ar string\-list
689 Set the default window shell program to
690 .Aq Ar string\-list .
692 the first string in the old shell setting. Default is no change. Initially,
693 the default shell is taken from the environment variable
695 .It Ic default_smooth Ns Pq Bq Ar flag
696 Set the default value of the
701 (see below). The argument
702 is a boolean flag (one of
710 as described above). Default is no change.
711 The old value (as a number) is returned.
712 The initial value is 1 (true).
714 .Ic echo Ns ( Op Ar window ,
715 .Bq Aq Ar string\-list )
717 Write the list of strings,
722 by spaces and terminated with a new line. The strings are only
723 displayed in the window, the processes in the window are not
726 below). No value is returned. Default
727 is the current window.
728 .It Ic escape Ns Pq Bq Ar escapec
729 Set the escape character to
732 escape character as a one-character string. Default is no
735 can be a string of a single character, or
739 .No control\- Ns Ar X .
741 .Ic foreground Ns ( Bq Ar window ,
746 in or out of foreground.
748 is a boolean value. The old foreground flag
749 is returned. Default for
751 is the current window,
756 .Ic label Ns ( Bq Ar window ,
764 label as a string. Default for
769 is no change. To turn
770 off a label, set it to an empty string ("").
772 No arguments. List the identifiers and labels of all windows. No
774 .It Ic select Ns Pq Bq Ar window
777 the current window. The previous current window
778 is returned. Default is no change.
779 .It Ic source Ns Pq Ar filename
780 Read and execute the long commands in
782 Returns \-1 if the file cannot be read, 0 otherwise.
783 .It Ic terse Ns Pq Bq flag
786 In terse mode, the command window
787 stays hidden even in command mode, and errors are reported by
788 sounding the terminal's bell.
793 above. Returns the old terse flag.
794 Default is no change.
795 .It Ic unalias Ns Pq Ar alias
802 .It Ic unset Ns Pq Ar variable
809 .It Ic variables Ns Pq
810 No arguments. List all variables. No value is returned.
812 .Ic window Ns ( Bq Ar row ,
825 Open a window with upper left corner at
834 then that many lines are allocated for the text buffer. Otherwise,
835 the default buffer size is used. Default values for
842 the upper, left-most, lower, or right-most extremes of the
851 interpreted in the same way as the argument to
854 they mean, respectively, put a frame around this window (default true),
855 allocate pseudo-terminal for this window rather than socketpair (default
856 true), and map new line characters in this window to carriage return
857 and line feed (default true if socketpair is used, false otherwise).
858 Normally, a window is automatically closed when its process
861 to true (default false) prevents this
864 is true, the screen is updated more frequently
865 (for this window) to produce a more terminal-like behavior.
872 is a list of strings that will be used as the shell
873 program to place in the window (default is the program specified
876 see above). The created window's identifier
877 is returned as a number.
879 .Ic write Ns ( Bq Ar window ,
880 .Bq Aq Ar string\-list )
882 Send the list of strings,
887 by spaces but not terminated with a new line. The strings are actually
888 given to the window as input. No value is returned. Default
889 is the current window.
891 .Ss Predefined Variables
892 These variables are for information only. Redefining them does
893 not affect the internal operation of
895 .Bl -tag -width modes
897 The baud rate as a number between 50 and 38400.
899 The display modes (reverse video, underline, blinking, graphics)
900 supported by the physical terminal. The value of
902 is the bitwise or of some of the one bit values,
909 These values are useful
910 in setting the window cursors' modes (see
914 The blinking mode bit.
916 The graphics mode bit (not very useful).
918 The reverse video mode bit.
920 The underline mode bit.
922 The number of columns on the physical screen.
924 The number of rows on the physical screen.
926 The terminal type. The standard name, found in the second name
927 field of the terminal's
934 utility utilizes these environment variables:
941 .Bl -tag -width /dev/[pt]ty[pq]? -compact
943 startup command file.
944 .It Pa /dev/[pt]ty[pq]?
945 pseudo-terminal devices.
948 Should be self explanatory.
projects / dragonfly.git / blob