Annotation of src/usr.bin/window/window.1, Revision 1.6
1.6 ! aaron 1: .\" $OpenBSD: window.1,v 1.5 1998/11/04 22:36:41 aaron Exp $
1.1 deraadt 2: .\" $NetBSD: window.1,v 1.3 1995/09/28 10:35:05 tls Exp $
3: .\"
4: .\" Copyright (c) 1985, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" Edward Wang at The University of California, Berkeley.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\" 3. All advertising materials mentioning features or use of this software
19: .\" must display the following acknowledgement:
20: .\" This product includes software developed by the University of
21: .\" California, Berkeley and its contributors.
22: .\" 4. Neither the name of the University nor the names of its contributors
23: .\" may be used to endorse or promote products derived from this software
24: .\" without specific prior written permission.
25: .\"
26: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36: .\" SUCH DAMAGE.
37: .\"
38: .\" @(#)window.1 8.2 (Berkeley) 12/30/93
39: .\"
40: .Dd December 30, 1993
41: .Dt WINDOW 1
42: .Os BSD 4.3
43: .Sh NAME
44: .Nm window
45: .Nd window environment
46: .Sh SYNOPSIS
47: .Nm window
48: .Op Fl t
49: .Op Fl f
50: .Op Fl d
51: .Op Fl e Ar escape-char
52: .Op Fl c Ar command
53: .Sh DESCRIPTION
1.4 aaron 54: .Nm window
1.1 deraadt 55: implements a window environment on
56: .Tn ASCII
57: terminals.
58: .Pp
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
1.4 aaron 63: interact with a terminal - through their standard input, output,
1.1 deraadt 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
68: to the display.
69: .Pp
70: When
71: .Nm window
72: starts up, the commands (see long commands below)
73: contained in the file
74: .Pa .windowrc
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.
78: .Pp
1.4 aaron 79: The command line options are:
1.1 deraadt 80: .Bl -tag -width Fl
81: .It Fl t
82: Turn on terse mode (see
83: .Ic terse
84: command below).
85: .It Fl f
86: Fast. Don't perform any startup action.
87: .It Fl d
88: Ignore
89: .Pa .windowrc
90: and create the two default
91: windows instead.
92: .It Fl e Ar escape-char
93: Set the escape character to
94: .Ar escape-char .
95: .Ar Escape-char
96: can be a single character, or in the form
97: .Ic ^X
98: where
99: .Ar X
100: is any character, meaning
101: .No control\- Ns Ar X .
102: .It Fl c Ar command
103: Execute the string
104: .Ar command
105: as a long command (see below)
106: before doing anything else.
107: .El
108: .Pp
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
114: .Ar foreground ,
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.
121: .Pp
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
129: itself.
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
135: .Xr (pty 4 )
136: or a
137: .Ux
138: domain socket
139: .Xr (socketpair 4 ) .
140: If a pseudo-terminal is used, then its special
141: characters and modes (see
142: .Xr stty 1 )
143: are copied from the physical
144: terminal. A
145: .Xr termcap 5
146: entry tailored to this window is created
147: and passed as environment
148: .Xr (environ 5 )
149: variable
150: .Ev TERMCAP .
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
158: .Xr vi 1
159: uses
160: this information to redraw its display.
161: .Ss Operation
162: During normal execution,
163: .Nm window
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.
171: .Pp
172: Typing
173: .Nm window Ns 's
174: escape character (normally
175: .Ic ^P )
176: in conversation
177: mode switches it into command mode. In command mode, the top line of
178: the terminal screen becomes the command prompt window, and
179: .Nm window
180: interprets input from the keyboard as commands to manipulate windows.
181: .Pp
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
185: .Dq Ic \&:
186: command below), or read from a file (see
187: .Ic source
188: below).
189: .Ss Short Commands
190: Below,
191: .Ar \&#
192: represents one of the digits ``1'' to ``9''
193: corresponding to the windows 1 to 9.
194: .Ic ^X
195: means
196: .No control\- Ns Ar X ,
197: where
198: .Ar X
199: is any character. In particular,
200: .Ic ^^
201: is
1.5 aaron 202: .Li control\-^ .
1.1 deraadt 203: .Ar Escape
204: is the escape key, or
205: .Ic ^\&[ .
206: .Bl -tag -width Ds
207: .It Ar #
208: Select window
209: .Ar #
210: as the current window
211: and return to conversation mode.
212: .It Ic \&% Ns Ar #
213: Select window
214: .Ar #
215: but stay in command mode.
216: .It Ic ^^
217: Select the previous window and return to conversation
218: mode. This is useful for toggling between two windows.
219: .It Ic escape
220: Return to conversation mode.
221: .It Ic ^P
222: Return to conversation mode and write
223: .Ic ^P
224: to the
225: current window. Thus, typing two
226: .Ic ^P Ns 's
227: in conversation
228: mode sends one to the current window. If the
229: .Nm window
230: escape is changed to some other character, that
231: character takes the place of
232: .Ic ^P
233: here.
234: .It Ic ?
235: List a short summary of commands.
236: .It Ic ^L
237: Refresh the screen.
238: .It Ic q
239: Exit
240: .Nm window .
241: Confirmation is requested.
242: .It Ic ^Z
243: Suspend
244: .Nm window .
245: .It Ic w
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'',
249: ``k'', and ``l''
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.
260: .Pp
261: This window becomes the current window,
262: and is given the first available ID. The default buffer size
263: is used (see
264: .Ar default_nline
265: command below).
266: .Pp
267: Only fully visible windows can be created this way.
268: .It Ic c Ns Ar #
269: Close window
270: .Ar # .
271: The process in the window is sent
272: the hangup signal (see
273: .Xr kill 1 ) .
274: .Xr Csh 1
275: should
276: handle this signal correctly and cause no problems.
277: .It Ic m Ns Ar #
278: Move window
279: .Ar #
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
283: those for the
284: .Ic w
285: command are used to position the box. The
286: window can be moved partially off-screen.
287: .It Ic M Ns Ar #
288: Move window
289: .Ar #
290: to its previous position.
291: .It Ic s Ns Ar #
292: Change the size of window
293: .Ar # .
294: The user is prompted
295: to enter the new lower right corner of the window. A box
296: is drawn to indicate the new window size. The same
297: keys used in
298: .Ic w
299: and
300: .Ic m
301: are used to enter the position.
302: .It Ic S Ns Ar #
303: Change window
304: .Ar #
305: to its previous size.
306: .It Ic ^Y
307: Scroll the current window up by one line.
308: .It Ic ^E
309: Scroll the current window down by one line.
310: .It Ic ^U
311: Scroll the current window up by half the window size.
312: .It Ic ^D
313: Scroll the current window down by half the window size.
314: .It Ic ^B
315: Scroll the current window up by the full window size.
316: .It Ic ^F
317: Scroll the current window down by the full window size.
318: .It Ic h
319: Move the cursor of the current window left by one column.
320: .It Ic j
321: Move the cursor of the current window down by one line.
322: .It Ic k
323: Move the cursor of the current window up by one line.
324: .It Ic l
325: Move the cursor of the current window right by one column.
326: .It Ic y
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.
330: .It Ic p
331: Put. The content of the yank buffer is written to the current
332: window as input.
333: .It Ic ^S
334: Stop output in the current window.
335: .It Ic ^Q
336: Start output in the current window.
337: .It Ic :
338: Enter a line to be executed as long commands.
339: Normal line
340: editing characters (erase character, erase word, erase line)
341: are supported.
342: .El
343: .Ss Long Commands
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.
348: .Pp
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".
357: .Pp
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
363: a boolean true.
364: .Pp
365: The character ``#'' begins a comment which terminates at the
366: end of the line.
367: .Pp
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
1.4 aaron 372: .Nm window
1.1 deraadt 373: has a single control structure:
374: the fully bracketed if statement in the form
375: .Pp
376: .Bd -literal -offset indent -compact
377: if <expr> then
378: \t<statement>
379: \t...
380: elsif <expr> then
381: \t<statement>
382: \t...
383: else
384: \t<statement>
385: \t...
386: endif
387: .Ed
388: .Pp
389: The
390: .Ic else
391: and
392: .Ic elsif
393: parts are optional, and the latter can
394: be repeated any number of times.
395: <Expr>
396: must be numeric.
397: .Ss Expressions
398: Expressions in
399: .Nm window
400: are similar to those in the
401: C language, with most C operators supported on numeric
402: operands. In addition, some are overloaded to operate on strings.
403: .Pp
404: When an expression is used as a statement, its value is discarded
405: after evaluation. Therefore, only expressions with side
406: effects (assignments and function calls) are useful as statements.
407: .Pp
408: Single valued (no arrays) variables are supported, of both
409: numeric and string values. Some variables are predefined. They
410: are listed below.
411: .Pp
412: The operators in order of increasing precedence:
413: .Bl -tag -width Fl
414: .It Xo
415: .Aq Va expr1
416: .Ic =
417: .Aq Va expr2
418: .Xc
419: Assignment. The variable of name
420: .Aq Va expr1 ,
421: which must be string valued,
422: is assigned the result of
423: .Aq Va expr2 .
424: Returns the value of
425: .Aq Va expr2 .
426: .It Xo
427: .Aq Va expr1
428: .Ic ?
429: .Aq Va expr2
430: .Ic :
431: .Aq Va expr3
432: .Xc
433: Returns the value of
434: .Aq Va expr2
435: if
436: .Aq Va expr1
437: evaluates true
438: (non-zero numeric value); returns the value of
439: .Aq Va expr3
440: otherwise. Only
441: one of
442: .Aq Va expr2
443: and
444: .Aq Va expr3
445: is evaluated.
446: .Aq Va Expr1
447: must
448: be numeric.
449: .It Xo
450: .Aq Va expr1
451: .Ic \&|\&|
452: .Aq Va expr2
453: .Xc
454: Logical or. Numeric values only. Short circuit evaluation is supported
455: (i.e., if
456: .Aq Va expr1
457: evaluates true, then
458: .Aq Va expr2
459: is not evaluated).
460: .It Xo
461: .Aq Va expr1
462: .Ic \&&\&&
463: .Aq Va expr2
464: .Xc
465: Logical and with short circuit evaluation. Numeric values only.
466: .It Xo
467: .Aq Va expr1
468: .Ic \&|
469: .Aq Va expr2
470: .Xc
471: Bitwise or. Numeric values only.
472: .It Xo
473: .Aq Va expr1
474: .Ic ^
475: .Aq Va expr2
476: .Xc
477: Bitwise exclusive or. Numeric values only.
478: .It Xo
479: .Aq Va expr1
480: .Ic \&&
481: .Aq Va expr2
482: .Xc
483: Bitwise and. Numeric values only.
484: .It Xo
485: .Aq Va expr1
486: .Ic ==
487: .Aq Va expr2 ,
488: .Aq Va expr1
489: .Ic !=
490: .Aq expr2
491: .Xc
492: Comparison (equal and not equal, respectively). The boolean
493: result (either 1 or 0) of the comparison is returned. The
494: operands can be numeric or string valued. One string operand
495: forces the other to be converted to a string in necessary.
496: .It Xo
497: .Aq Va expr1
498: .Ic <
499: .Aq Va expr2 ,
500: .Aq Va expr1
501: .Ic >
502: .Aq Va expr2 ,
503: .Aq Va expr1
504: .Ic <=
505: .Aq Va expr2 ,
506: .Xc
507: Less than, greater than, less than or equal to,
508: greater than or equal to. Both numeric and string values, with
509: automatic conversion as above.
510: .It Xo
511: .Aq Va expr1
512: .Ic <<
513: .Aq Va expr2 ,
514: .Aq Va expr1
515: .Ic >>
516: .Aq Va expr2
517: .Xc
518: If both operands are numbers,
519: .Aq Va expr1
520: is bit
521: shifted left (or right) by
522: .Aq Va expr2
523: bits. If
524: .Aq Va expr1
525: is
526: a string, then its first (or last)
527: .Aq Va expr2
528: characters are
529: returns (if
530: .Aq Va expr2
531: is also a string, then its length is used
532: in place of its value).
533: .It Xo
534: .Aq Va expr1
535: .Ic +
536: .Aq Va expr2 ,
537: .Aq Va expr1
538: .Ic -
539: .Aq Va expr2
540: .Xc
541: Addition and subtraction on numbers. For ``+'', if one
542: argument is a string, then the other is converted to a string,
543: and the result is the concatenation of the two strings.
544: .It Xo
545: .Aq Va expr1
546: .Ic \&*
547: .Aq Va expr2 ,
548: .Aq Va expr1
549: .Ic \&/
550: .Aq Va expr2 ,
551: .Aq Va expr1
552: .Ic \&%
553: .Aq Va expr2
554: .Xc
555: Multiplication, division, modulo. Numbers only.
556: .It Xo
557: .Ic \- Ns Aq Va expr ,
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: .Xc
563: The first three are unary minus, bitwise complement and logical complement
564: on numbers only. The operator, ``$'', takes
565: .Aq Va expr
566: and returns
567: the value of the variable of that name. If
568: .Aq Va expr
569: is numeric
570: with value
571: .Ar n
572: and it appears within an alias macro (see below),
573: then it refers to the nth argument of the alias invocation. ``$?''
574: tests for the existence of the variable
575: .Aq Va expr ,
576: and returns 1
577: if it exists or 0 otherwise.
578: .It Xo
579: .Ao Va expr Ac Ns Pq Aq Ar arglist
580: .Xc
581: Function call.
582: .Aq Va Expr
583: must be a string that is the unique
1.6 ! aaron 584: prefix of the name of a built-in
1.1 deraadt 585: .Nm window
586: function
1.6 ! aaron 587: or the full name of a user defined alias macro. In the case of a built-in
1.1 deraadt 588: function,
589: .Aq Ar arglist
590: can be in one of two forms:
591: .Bd -literal -offset indent
592: <expr1>, <expr2>, ...
593: argname1 = <expr1>, argname2 = <expr2>, ...
594: .Ed
595: .Pp
596: The two forms can in fact be intermixed, but the result is
597: unpredictable. Most arguments can be omitted; default values will
598: be supplied for them. The
599: .Ar argnames
600: can be unique prefixes
601: of the argument names. The commas separating
602: arguments are used only to disambiguate, and can usually be omitted.
603: .Pp
604: Only the first argument form is valid for user defined aliases. Aliases
605: are defined using the
606: .Ic alias
1.6 ! aaron 607: built-in function (see below). Arguments
1.1 deraadt 608: are accessed via a variant of the variable mechanism (see ``$'' operator
609: above).
610: .Pp
611: Most functions return value, but some are used for side effect
612: only and so must be used as statements. When a function or an alias is used
613: as a statement, the parentheses surrounding
614: the argument list may be omitted. Aliases return no value.
615: .El
1.6 ! aaron 616: .Ss Built-in Functions
1.1 deraadt 617: The arguments are listed by name in their natural
618: order. Optional arguments are in square brackets
619: .Sq Op .
620: Arguments
621: that have no names are in angle brackets
622: .Sq <> .
623: An argument meant to be a boolean flag (often named
624: .Ar flag )
625: can be one of
626: .Ar on ,
627: .Ar off ,
628: .Ar yes ,
629: .Ar no ,
630: .Ar true ,
631: or
632: .Ar false ,
633: with
634: obvious meanings, or it can be a numeric expression,
635: in which case a non-zero value is true.
636: .Bl -tag -width Fl
637: .It Xo
638: .Ic alias Ns Po Bq Aq Ar string ,
639: .Bq Aq Ar string\-list Pc
640: .Xc
641: If no argument is given, all currently defined alias macros are
642: listed. Otherwise,
643: .Aq Ar string
644: is defined as an alias,
645: with expansion
646: .Aq Ar string\-list > .
647: The previous definition of
648: .Aq Ar string ,
649: if any, is returned. Default for
650: .Aq Ar string\-list
651: is no change.
652: .It Ic close Ns Pq Aq Ar window\-list
653: Close the windows specified in
654: .Aq Ar window\-list .
655: If
656: .Aq Ar window\-list
657: is the word
658: .Ar all ,
659: than all windows are closed. No value is returned.
660: .It Ic cursormodes Ns Pq Bq Ar modes
661: Set the window cursor to
662: .Ar modes .
663: .Ar Modes
664: is the bitwise
665: or of the mode bits defined as the variables
666: .Ar m_ul
667: (underline),
668: .Ar m_rev
669: (reverse video),
670: .Ar m_blk
671: (blinking),
672: and
673: .Ar m_grp
674: (graphics, terminal dependent). Return
675: value is the previous modes. Default is no change.
676: For example,
677: .Li cursor($m_rev$m_blk)
678: sets the window cursors to blinking
679: reverse video.
680: .It Ic default_nline Ns Pq Bq Ar nline
681: Set the default buffer size to
682: .Ar nline .
683: Initially, it is
684: 48 lines. Returns the old default buffer size. Default is
685: no change. Using a very large buffer can slow the program down
686: considerably.
687: .It Ic default_shell Ns Pq Bq Aq Ar string\-list
688: Set the default window shell program to
689: .Aq Ar string\-list .
690: Returns
691: the first string in the old shell setting. Default is no change. Initially,
692: the default shell is taken from the environment variable
693: .Ev SHELL .
694: .It Ic default_smooth Ns Pq Bq Ar flag
695: Set the default value of the
696: .Ar smooth
697: argument
698: to the command
699: .Nm window
700: (see below). The argument
701: is a boolean flag (one of
702: .Ar on ,
703: .Ar off ,
704: .Ar yes ,
705: .Ar no ,
706: .Ar true ,
707: .Ar false ,
708: or a number,
709: as described above). Default is no change.
710: The old value (as a number) is returned.
711: The initial value is 1 (true).
712: .It Xo
713: .Ic echo Ns ( Op Ar window ,
714: .Bq Aq Ar string\-list )
715: .Xc
716: Write the list of strings,
717: .Aq Ar string-list ,
718: to
719: .Nm window ,
720: separated
721: by spaces and terminated with a new line. The strings are only
722: displayed in the window, the processes in the window are not
723: involved (see
724: .Ic write
725: below). No value is returned. Default
726: is the current window.
727: .It Ic escape Ns Pq Bq Ar escapec
728: Set the escape character to
729: .Ar escape-char .
730: Returns the old
731: escape character as a one-character string. Default is no
732: change.
733: .Ar Escapec
734: can be a string of a single character, or
735: in the form
736: .Fl ^X ,
737: meaning
738: .No control\- Ns Ar X .
739: .It Xo
740: .Ic foreground Ns ( Bq Ar window ,
741: .Bq Ar flag )
742: .Xc
743: Move
744: .Nm window
745: in or out of foreground.
746: .Ar Flag
747: is a boolean value. The old foreground flag
748: is returned. Default for
749: .Nm window
750: is the current window,
751: default for
752: .Ar flag
753: is no change.
754: .It Xo
755: .Ic label Ns ( Bq Ar window ,
756: .Bq Ar label )
757: .Xc
758: Set the label of
759: .Nm window
760: to
761: .Ar label .
762: Returns the old
763: label as a string. Default for
764: .Nm window
765: is the current
766: window, default for
767: .Ar label
768: is no change. To turn
769: off a label, set it to an empty string ("").
770: .It Ic list Ns Pq
771: No arguments. List the identifiers and labels of all windows. No
772: value is returned.
773: .It Ic select Ns Pq Bq Ar window
774: Make
775: .Nm window
776: the current window. The previous current window
777: is returned. Default is no change.
778: .It Ic source Ns Pq Ar filename
779: Read and execute the long commands in
780: .Ar filename .
781: Returns \-1 if the file cannot be read, 0 otherwise.
782: .It Ic terse Ns Pq Bq flag
783: Set terse mode to
784: .Ar flag .
785: In terse mode, the command window
786: stays hidden even in command mode, and errors are reported by
787: sounding the terminal's bell.
788: .Ar Flag
789: can take on the same
790: values as in
791: .Ar foreground
792: above. Returns the old terse flag.
793: Default is no change.
794: .It Ic unalias Ns Pq Ar alias
795: Undefine
796: .Ar alias .
797: Returns -1 if
798: .Ar alias
799: does not exist,
800: 0 otherwise.
801: .It Ic unset Ns Pq Ar variable
802: Undefine
803: .Ar variable .
804: Returns -1 if
805: .Ar variable
806: does not exist,
807: 0 otherwise.
808: .It Ic variables Ns Pq
809: No arguments. List all variables. No value is returned.
810: .It Xo
811: .Ic window Ns ( Bq Ar row ,
812: .Bq Ar column ,
813: .Bq Ar nrow ,
814: .Bq Ar ncol ,
815: .Bq Ar nline ,
816: .Bq Ar label ,
817: .Bq Ar pty ,
818: .Bq Ar frame ,
819: .Bq Ar mapnl ,
820: .Bq Ar keepopen ,
821: .Bq Ar smooth ,
822: .Bq Ar shell ) .
823: .Xc
824: Open a window with upper left corner at
825: .Ar row ,
826: .Ar column
827: and size
828: .Ar nrow ,
829: .Ar ncol .
830: If
831: .Ar nline
832: is specified,
833: then that many lines are allocated for the text buffer. Otherwise,
834: the default buffer size is used. Default values for
835: .Ar row ,
836: .Ar column ,
837: .Ar nrow ,
838: and
839: .Ar ncol
840: are, respectively,
841: the upper, left-most, lower, or right-most extremes of the
842: screen.
843: .Ar Label
844: is the label string.
845: .Ar Frame ,
846: .Ar pty ,
847: and
848: .Ar mapnl
849: are flag values
850: interpreted in the same way as the argument to
851: .Ar foreground
852: (see above);
853: they mean, respectively, put a frame around this window (default true),
854: allocate pseudo-terminal for this window rather than socketpair (default
855: true), and map new line characters in this window to carriage return
856: and line feed (default true if socketpair is used, false otherwise).
857: Normally, a window is automatically closed when its process
858: exits. Setting
859: .Ar keepopen
860: to true (default false) prevents this
861: action. When
862: .Ar smooth
863: is true, the screen is updated more frequently
864: (for this window) to produce a more terminal-like behavior.
865: The default value of
866: .Ar smooth
867: is set by the
868: .Ar default_smooth
869: command (see above).
870: .Ar Shell
871: is a list of strings that will be used as the shell
872: program to place in the window (default is the program specified
873: by
874: .Ar default_shell ,
875: see above). The created window's identifier
876: is returned as a number.
877: .It Xo
878: .Ic write Ns ( Bq Ar window ,
879: .Bq Aq Ar string\-list )
880: .Xc
881: Send the list of strings,
882: .Aq Ar string-list ,
883: to
884: .Nm window ,
885: separated
886: by spaces but not terminated with a new line. The strings are actually
887: given to the window as input. No value is returned. Default
888: is the current window.
889: .El
890: .Ss Predefined Variables
891: These variables are for information only. Redefining them does
892: not affect the internal operation of
893: .Nm window .
894: .Bl -tag -width modes
895: .It Ar baud
896: The baud rate as a number between 50 and 38400.
897: .It Ar modes
898: The display modes (reverse video, underline, blinking, graphics)
899: supported by the physical terminal. The value of
900: .Ar modes
901: is the bitwise or of some of the one bit values,
902: .Ar m_blk ,
903: .Ar m_grp ,
904: .Ar m_rev ,
905: and
906: .Ar m_ul
907: (see below).
908: These values are useful
909: in setting the window cursors' modes (see
910: .Ar cursormodes
911: above).
912: .It Ar m_blk
913: The blinking mode bit.
914: .It Ar m_grp
915: The graphics mode bit (not very useful).
916: .It Ar m_rev
917: The reverse video mode bit.
918: .It Ar m_ul
919: The underline mode bit.
920: .It Ar ncol
921: The number of columns on the physical screen.
922: .It Ar nrow
923: The number of rows on the physical screen.
924: .It Ar term
925: The terminal type. The standard name, found in the second name
926: field of the terminal's
927: .Ev TERMCAP
928: entry, is used.
929: .Sh ENVIRONMENT
1.4 aaron 930: .Nm window
1.1 deraadt 931: utilizes these environment variables:
932: .Ev HOME ,
933: .Ev SHELL ,
934: .Ev TERM ,
935: .Ev TERMCAP ,
936: .Ev WINDOW_ID .
937: .Sh FILES
938: .Bl -tag -width /dev/[pt]ty[pq]? -compact
939: .It Pa ~/.windowrc
1.4 aaron 940: startup command file
1.1 deraadt 941: .It Pa /dev/[pt]ty[pq]?
1.4 aaron 942: pseudo-terminal devices
1.1 deraadt 943: .El
944: .Sh HISTORY
945: The
946: .Nm window
947: command appeared in
948: .Bx 4.3 .
949: .Sh DIAGNOSTICS
950: Should be self explanatory.