Annotation of src/usr.bin/window/window.1, Revision 1.7
1.7 ! aaron 1: .\" $OpenBSD: window.1,v 1.6 1999/05/12 21:58:32 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
1.7 ! aaron 42: .Os
1.1 deraadt 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.7 ! aaron 54: .Nm
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
1.7 ! aaron 71: .Nm
1.1 deraadt 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.
1.7 ! aaron 92: .It Fl e Ar escape-char
1.1 deraadt 93: Set the escape character to
1.7 ! aaron 94: .Ar escape-char .
! 95: .Ar escape-char
1.1 deraadt 96: can be a single character, or in the form
97: .Ic ^X
98: where
99: .Ar X
100: is any character, meaning
1.7 ! aaron 101: .No control\- Ns Ar X .
! 102: .It Fl c Ar command
1.1 deraadt 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
1.7 ! aaron 110: is named by one of the digits 1\-9. This one-character
1.1 deraadt 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,
1.7 ! aaron 163: .Nm
1.1 deraadt 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
1.7 ! aaron 173: .Nm window Ns 's
1.1 deraadt 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
1.7 ! aaron 179: .Nm
1.1 deraadt 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 \&#
1.7 ! aaron 192: represents one of the digits 1\-9
1.1 deraadt 193: corresponding to the windows 1 to 9.
194: .Ic ^X
195: means
1.7 ! aaron 196: .No control\- Ns Ar X ,
1.1 deraadt 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.
1.7 ! aaron 212: .It Ic \&% Ns Ar #
1.1 deraadt 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
1.7 ! aaron 229: .Nm
1.1 deraadt 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
1.7 ! aaron 240: .Nm window .
1.1 deraadt 241: Confirmation is requested.
242: .It Ic ^Z
243: Suspend
1.7 ! aaron 244: .Nm window .
1.1 deraadt 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.
1.7 ! aaron 248: The cursor is placed on the screen and the keys
! 249: .Sq h ,
! 250: .Sq j ,
! 251: .Sq k ,
! 252: and
! 253: .Sq l
1.1 deraadt 254: move the cursor left, down, up, and right, respectively.
1.7 ! aaron 255: The keys
! 256: .Sq H ,
! 257: .Sq J ,
! 258: .Sq K ,
! 259: and
! 260: .Sq L
! 261: move the cursor to the respective
1.1 deraadt 262: limits of the screen. Typing a number before the movement keys
263: repeats the movement that number of times. Return enters the cursor position
264: as the upper left corner of the window. The lower right corner
265: is entered in the same manner. During this process,
266: the placement of the new window is indicated by a rectangular
267: box drawn on the screen, corresponding to where the new window
268: will be framed. Typing escape at any point
269: cancels this command.
270: .Pp
271: This window becomes the current window,
272: and is given the first available ID. The default buffer size
273: is used (see
274: .Ar default_nline
275: command below).
276: .Pp
277: Only fully visible windows can be created this way.
1.7 ! aaron 278: .It Ic c Ns Ar #
1.1 deraadt 279: Close window
280: .Ar # .
281: The process in the window is sent
282: the hangup signal (see
283: .Xr kill 1 ) .
284: .Xr Csh 1
285: should
286: handle this signal correctly and cause no problems.
1.7 ! aaron 287: .It Ic m Ns Ar #
1.1 deraadt 288: Move window
289: .Ar #
290: to another location. A box in the shape
291: of the window is drawn on
292: the screen to indicate the new position of the window, and the same keys as
293: those for the
294: .Ic w
295: command are used to position the box. The
296: window can be moved partially off-screen.
1.7 ! aaron 297: .It Ic M Ns Ar #
1.1 deraadt 298: Move window
299: .Ar #
300: to its previous position.
1.7 ! aaron 301: .It Ic s Ns Ar #
1.1 deraadt 302: Change the size of window
303: .Ar # .
304: The user is prompted
305: to enter the new lower right corner of the window. A box
306: is drawn to indicate the new window size. The same
307: keys used in
308: .Ic w
309: and
310: .Ic m
311: are used to enter the position.
1.7 ! aaron 312: .It Ic S Ns Ar #
1.1 deraadt 313: Change window
314: .Ar #
315: to its previous size.
316: .It Ic ^Y
317: Scroll the current window up by one line.
318: .It Ic ^E
319: Scroll the current window down by one line.
320: .It Ic ^U
321: Scroll the current window up by half the window size.
322: .It Ic ^D
323: Scroll the current window down by half the window size.
324: .It Ic ^B
325: Scroll the current window up by the full window size.
326: .It Ic ^F
327: Scroll the current window down by the full window size.
328: .It Ic h
329: Move the cursor of the current window left by one column.
330: .It Ic j
331: Move the cursor of the current window down by one line.
332: .It Ic k
333: Move the cursor of the current window up by one line.
334: .It Ic l
335: Move the cursor of the current window right by one column.
336: .It Ic y
337: Yank. The user is prompted to enter two points within the current
338: window. Then the content of the current window between those two points
339: is saved in the yank buffer.
340: .It Ic p
341: Put. The content of the yank buffer is written to the current
342: window as input.
343: .It Ic ^S
344: Stop output in the current window.
345: .It Ic ^Q
346: Start output in the current window.
347: .It Ic :
348: Enter a line to be executed as long commands.
349: Normal line
350: editing characters (erase character, erase word, erase line)
351: are supported.
352: .El
353: .Ss Long Commands
354: Long commands are a sequence of statements
355: parsed much like a programming language, with a syntax
356: similar to that of C. Numeric and string expressions and variables
357: are supported, as well as conditional statements.
358: .Pp
359: There are two data types: string and number. A string is a sequence
1.7 ! aaron 360: of letters or digits beginning with a letter.
! 361: .Ql _
! 362: and
! 363: .Ql \&.
! 364: are considered letters. Alternately, non-alphanumeric characters can
! 365: be included in strings by quoting them in
! 366: .Ql \&"
! 367: or escaping them with
! 368: .Ql \e .
! 369: In addition, the
! 370: .Ql \e
! 371: sequences of C are supported,
! 372: both inside and outside quotes (e.g.,
! 373: .Ql \en
! 374: is a newline,
! 375: .Ql \er
! 376: a carriage return). For example, these are legal strings:
1.1 deraadt 377: abcde01234, "&#$^*&#", ab"$#"cd, ab\\$\\#cd, "/usr/ucb/window".
378: .Pp
379: A number is an integer value in one of three forms:
1.7 ! aaron 380: a decimal number, an octal number preceded by
! 381: .Sq 0 ,
! 382: or a hexadecimal number preceded by
! 383: .Sq 0x
! 384: or
! 385: .Sq 0X .
! 386: The natural
1.1 deraadt 387: machine integer size is used (i.e., the signed integer type
388: of the C compiler). As in C, a non-zero number represents
389: a boolean true.
390: .Pp
1.7 ! aaron 391: The character
! 392: .Ql #
! 393: begins a comment which terminates at the end of the line.
1.1 deraadt 394: .Pp
395: A statement is either a conditional or an expression. Expression
1.7 ! aaron 396: statements are terminated with a new line or
! 397: .Ql \&; .
! 398: To continue
! 399: an expression on the next line, terminate the first line with
! 400: .Ql \e .
1.1 deraadt 401: .Ss Conditional Statement
1.7 ! aaron 402: .Nm
1.1 deraadt 403: has a single control structure:
404: the fully bracketed if statement in the form
405: .Pp
406: .Bd -literal -offset indent -compact
407: if <expr> then
408: \t<statement>
409: \t...
410: elsif <expr> then
411: \t<statement>
412: \t...
413: else
414: \t<statement>
415: \t...
416: endif
417: .Ed
418: .Pp
419: The
420: .Ic else
421: and
422: .Ic elsif
423: parts are optional, and the latter can
424: be repeated any number of times.
425: <Expr>
426: must be numeric.
427: .Ss Expressions
428: Expressions in
1.7 ! aaron 429: .Nm
1.1 deraadt 430: are similar to those in the
431: C language, with most C operators supported on numeric
432: operands. In addition, some are overloaded to operate on strings.
433: .Pp
434: When an expression is used as a statement, its value is discarded
435: after evaluation. Therefore, only expressions with side
436: effects (assignments and function calls) are useful as statements.
437: .Pp
438: Single valued (no arrays) variables are supported, of both
439: numeric and string values. Some variables are predefined. They
440: are listed below.
441: .Pp
442: The operators in order of increasing precedence:
443: .Bl -tag -width Fl
444: .It Xo
445: .Aq Va expr1
446: .Ic =
447: .Aq Va expr2
448: .Xc
449: Assignment. The variable of name
1.7 ! aaron 450: .Aq Va expr1 ,
1.1 deraadt 451: which must be string valued,
452: is assigned the result of
1.7 ! aaron 453: .Aq Va expr2 .
1.1 deraadt 454: Returns the value of
1.7 ! aaron 455: .Aq Va expr2 .
1.1 deraadt 456: .It Xo
457: .Aq Va expr1
458: .Ic ?
459: .Aq Va expr2
460: .Ic :
461: .Aq Va expr3
462: .Xc
463: Returns the value of
1.7 ! aaron 464: .Aq Va expr2
1.1 deraadt 465: if
1.7 ! aaron 466: .Aq Va expr1
1.1 deraadt 467: evaluates true
468: (non-zero numeric value); returns the value of
1.7 ! aaron 469: .Aq Va expr3
1.1 deraadt 470: otherwise. Only
471: one of
1.7 ! aaron 472: .Aq Va expr2
1.1 deraadt 473: and
1.7 ! aaron 474: .Aq Va expr3
1.1 deraadt 475: is evaluated.
1.7 ! aaron 476: .Aq Va Expr1
1.1 deraadt 477: must
478: be numeric.
479: .It Xo
480: .Aq Va expr1
481: .Ic \&|\&|
482: .Aq Va expr2
483: .Xc
484: Logical or. Numeric values only. Short circuit evaluation is supported
485: (i.e., if
1.7 ! aaron 486: .Aq Va expr1
1.1 deraadt 487: evaluates true, then
1.7 ! aaron 488: .Aq Va expr2
1.1 deraadt 489: is not evaluated).
490: .It Xo
491: .Aq Va expr1
492: .Ic \&&\&&
493: .Aq Va expr2
494: .Xc
495: Logical and with short circuit evaluation. Numeric values only.
496: .It Xo
497: .Aq Va expr1
498: .Ic \&|
499: .Aq Va expr2
500: .Xc
501: Bitwise or. Numeric values only.
502: .It Xo
503: .Aq Va expr1
504: .Ic ^
505: .Aq Va expr2
506: .Xc
507: Bitwise exclusive or. Numeric values only.
508: .It Xo
509: .Aq Va expr1
510: .Ic \&&
511: .Aq Va expr2
512: .Xc
513: Bitwise and. Numeric values only.
514: .It Xo
515: .Aq Va expr1
516: .Ic ==
517: .Aq Va expr2 ,
518: .Aq Va expr1
519: .Ic !=
520: .Aq expr2
521: .Xc
522: Comparison (equal and not equal, respectively). The boolean
523: result (either 1 or 0) of the comparison is returned. The
524: operands can be numeric or string valued. One string operand
525: forces the other to be converted to a string in necessary.
526: .It Xo
527: .Aq Va expr1
528: .Ic <
529: .Aq Va expr2 ,
530: .Aq Va expr1
531: .Ic >
532: .Aq Va expr2 ,
533: .Aq Va expr1
534: .Ic <=
535: .Aq Va expr2 ,
536: .Xc
537: Less than, greater than, less than or equal to,
538: greater than or equal to. Both numeric and string values, with
539: automatic conversion as above.
540: .It Xo
541: .Aq Va expr1
542: .Ic <<
543: .Aq Va expr2 ,
544: .Aq Va expr1
545: .Ic >>
546: .Aq Va expr2
547: .Xc
548: If both operands are numbers,
549: .Aq Va expr1
550: is bit
551: shifted left (or right) by
552: .Aq Va expr2
553: bits. If
554: .Aq Va expr1
555: is
556: a string, then its first (or last)
557: .Aq Va expr2
558: characters are
559: returns (if
560: .Aq Va expr2
561: is also a string, then its length is used
562: in place of its value).
563: .It Xo
564: .Aq Va expr1
565: .Ic +
566: .Aq Va expr2 ,
567: .Aq Va expr1
568: .Ic -
569: .Aq Va expr2
570: .Xc
1.7 ! aaron 571: Addition and subtraction on numbers. For
! 572: .Ql + ,
! 573: if one
1.1 deraadt 574: argument is a string, then the other is converted to a string,
575: and the result is the concatenation of the two strings.
576: .It Xo
577: .Aq Va expr1
578: .Ic \&*
579: .Aq Va expr2 ,
580: .Aq Va expr1
581: .Ic \&/
582: .Aq Va expr2 ,
583: .Aq Va expr1
584: .Ic \&%
585: .Aq Va expr2
586: .Xc
587: Multiplication, division, modulo. Numbers only.
588: .It Xo
589: .Ic \- Ns Aq Va expr ,
590: .Ic ~ Ns Aq Va expr ,
591: .Ic \&! Ns Aq Va expr ,
592: .Ic \&$ Ns Aq Va expr ,
593: .Ic \&$? Ns Aq Va expr
594: .Xc
595: The first three are unary minus, bitwise complement and logical complement
1.7 ! aaron 596: on numbers only. The operator,
! 597: .Ql $ ,
! 598: takes
1.1 deraadt 599: .Aq Va expr
600: and returns
601: the value of the variable of that name. If
602: .Aq Va expr
603: is numeric
604: with value
605: .Ar n
606: and it appears within an alias macro (see below),
1.7 ! aaron 607: then it refers to the nth argument of the alias invocation.
! 608: .Ql $?
1.1 deraadt 609: tests for the existence of the variable
610: .Aq Va expr ,
611: and returns 1
612: if it exists or 0 otherwise.
613: .It Xo
614: .Ao Va expr Ac Ns Pq Aq Ar arglist
615: .Xc
616: Function call.
617: .Aq Va Expr
618: must be a string that is the unique
1.6 aaron 619: prefix of the name of a built-in
1.7 ! aaron 620: .Nm
1.1 deraadt 621: function
1.6 aaron 622: or the full name of a user defined alias macro. In the case of a built-in
1.1 deraadt 623: function,
624: .Aq Ar arglist
625: can be in one of two forms:
626: .Bd -literal -offset indent
627: <expr1>, <expr2>, ...
628: argname1 = <expr1>, argname2 = <expr2>, ...
629: .Ed
630: .Pp
631: The two forms can in fact be intermixed, but the result is
632: unpredictable. Most arguments can be omitted; default values will
633: be supplied for them. The
634: .Ar argnames
635: can be unique prefixes
636: of the argument names. The commas separating
637: arguments are used only to disambiguate, and can usually be omitted.
638: .Pp
639: Only the first argument form is valid for user defined aliases. Aliases
640: are defined using the
641: .Ic alias
1.6 aaron 642: built-in function (see below). Arguments
1.7 ! aaron 643: are accessed via a variant of the variable mechanism (see the
! 644: .Ql $
! 645: operator above).
1.1 deraadt 646: .Pp
647: Most functions return value, but some are used for side effect
648: only and so must be used as statements. When a function or an alias is used
649: as a statement, the parentheses surrounding
650: the argument list may be omitted. Aliases return no value.
651: .El
1.6 aaron 652: .Ss Built-in Functions
1.1 deraadt 653: The arguments are listed by name in their natural
654: order. Optional arguments are in square brackets
655: .Sq Op .
656: Arguments
657: that have no names are in angle brackets
658: .Sq <> .
659: An argument meant to be a boolean flag (often named
660: .Ar flag )
661: can be one of
662: .Ar on ,
663: .Ar off ,
664: .Ar yes ,
665: .Ar no ,
666: .Ar true ,
667: or
668: .Ar false ,
669: with
670: obvious meanings, or it can be a numeric expression,
671: in which case a non-zero value is true.
672: .Bl -tag -width Fl
673: .It Xo
674: .Ic alias Ns Po Bq Aq Ar string ,
675: .Bq Aq Ar string\-list Pc
676: .Xc
677: If no argument is given, all currently defined alias macros are
678: listed. Otherwise,
679: .Aq Ar string
680: is defined as an alias,
681: with expansion
1.7 ! aaron 682: .Aq Ar string\-list > .
1.1 deraadt 683: The previous definition of
684: .Aq Ar string ,
685: if any, is returned. Default for
686: .Aq Ar string\-list
687: is no change.
688: .It Ic close Ns Pq Aq Ar window\-list
689: Close the windows specified in
690: .Aq Ar window\-list .
691: If
692: .Aq Ar window\-list
693: is the word
694: .Ar all ,
695: than all windows are closed. No value is returned.
696: .It Ic cursormodes Ns Pq Bq Ar modes
697: Set the window cursor to
698: .Ar modes .
699: .Ar Modes
700: is the bitwise
701: or of the mode bits defined as the variables
702: .Ar m_ul
703: (underline),
704: .Ar m_rev
705: (reverse video),
706: .Ar m_blk
707: (blinking),
708: and
709: .Ar m_grp
710: (graphics, terminal dependent). Return
711: value is the previous modes. Default is no change.
712: For example,
713: .Li cursor($m_rev$m_blk)
714: sets the window cursors to blinking
715: reverse video.
716: .It Ic default_nline Ns Pq Bq Ar nline
717: Set the default buffer size to
718: .Ar nline .
719: Initially, it is
720: 48 lines. Returns the old default buffer size. Default is
721: no change. Using a very large buffer can slow the program down
722: considerably.
723: .It Ic default_shell Ns Pq Bq Aq Ar string\-list
724: Set the default window shell program to
725: .Aq Ar string\-list .
726: Returns
727: the first string in the old shell setting. Default is no change. Initially,
728: the default shell is taken from the environment variable
729: .Ev SHELL .
730: .It Ic default_smooth Ns Pq Bq Ar flag
731: Set the default value of the
732: .Ar smooth
733: argument
734: to the command
1.7 ! aaron 735: .Nm
1.1 deraadt 736: (see below). The argument
737: is a boolean flag (one of
738: .Ar on ,
739: .Ar off ,
740: .Ar yes ,
741: .Ar no ,
742: .Ar true ,
743: .Ar false ,
744: or a number,
745: as described above). Default is no change.
746: The old value (as a number) is returned.
747: The initial value is 1 (true).
748: .It Xo
749: .Ic echo Ns ( Op Ar window ,
750: .Bq Aq Ar string\-list )
751: .Xc
752: Write the list of strings,
753: .Aq Ar string-list ,
754: to
1.7 ! aaron 755: .Nm window ,
1.1 deraadt 756: separated
757: by spaces and terminated with a new line. The strings are only
758: displayed in the window, the processes in the window are not
759: involved (see
760: .Ic write
761: below). No value is returned. Default
762: is the current window.
763: .It Ic escape Ns Pq Bq Ar escapec
764: Set the escape character to
765: .Ar escape-char .
766: Returns the old
767: escape character as a one-character string. Default is no
768: change.
769: .Ar Escapec
770: can be a string of a single character, or
771: in the form
772: .Fl ^X ,
773: meaning
774: .No control\- Ns Ar X .
775: .It Xo
776: .Ic foreground Ns ( Bq Ar window ,
1.7 ! aaron 777: .Bq Ar flag )
1.1 deraadt 778: .Xc
779: Move
1.7 ! aaron 780: .Nm
1.1 deraadt 781: in or out of foreground.
782: .Ar Flag
783: is a boolean value. The old foreground flag
784: is returned. Default for
1.7 ! aaron 785: .Nm
1.1 deraadt 786: is the current window,
787: default for
788: .Ar flag
789: is no change.
790: .It Xo
791: .Ic label Ns ( Bq Ar window ,
1.7 ! aaron 792: .Bq Ar label )
1.1 deraadt 793: .Xc
794: Set the label of
1.7 ! aaron 795: .Nm
1.1 deraadt 796: to
797: .Ar label .
798: Returns the old
799: label as a string. Default for
1.7 ! aaron 800: .Nm
1.1 deraadt 801: is the current
802: window, default for
803: .Ar label
804: is no change. To turn
805: off a label, set it to an empty string ("").
806: .It Ic list Ns Pq
807: No arguments. List the identifiers and labels of all windows. No
808: value is returned.
809: .It Ic select Ns Pq Bq Ar window
810: Make
1.7 ! aaron 811: .Nm
1.1 deraadt 812: the current window. The previous current window
813: is returned. Default is no change.
814: .It Ic source Ns Pq Ar filename
815: Read and execute the long commands in
816: .Ar filename .
817: Returns \-1 if the file cannot be read, 0 otherwise.
818: .It Ic terse Ns Pq Bq flag
819: Set terse mode to
820: .Ar flag .
821: In terse mode, the command window
822: stays hidden even in command mode, and errors are reported by
823: sounding the terminal's bell.
824: .Ar Flag
825: can take on the same
826: values as in
827: .Ar foreground
828: above. Returns the old terse flag.
829: Default is no change.
830: .It Ic unalias Ns Pq Ar alias
831: Undefine
832: .Ar alias .
833: Returns -1 if
834: .Ar alias
835: does not exist,
836: 0 otherwise.
837: .It Ic unset Ns Pq Ar variable
838: Undefine
839: .Ar variable .
840: Returns -1 if
841: .Ar variable
842: does not exist,
843: 0 otherwise.
844: .It Ic variables Ns Pq
845: No arguments. List all variables. No value is returned.
846: .It Xo
847: .Ic window Ns ( Bq Ar row ,
848: .Bq Ar column ,
849: .Bq Ar nrow ,
850: .Bq Ar ncol ,
851: .Bq Ar nline ,
852: .Bq Ar label ,
1.7 ! aaron 853: .Bq Ar pty ,
1.1 deraadt 854: .Bq Ar frame ,
855: .Bq Ar mapnl ,
856: .Bq Ar keepopen ,
857: .Bq Ar smooth ,
1.7 ! aaron 858: .Bq Ar shell ) .
1.1 deraadt 859: .Xc
860: Open a window with upper left corner at
861: .Ar row ,
862: .Ar column
863: and size
864: .Ar nrow ,
865: .Ar ncol .
866: If
867: .Ar nline
868: is specified,
869: then that many lines are allocated for the text buffer. Otherwise,
870: the default buffer size is used. Default values for
871: .Ar row ,
872: .Ar column ,
873: .Ar nrow ,
874: and
875: .Ar ncol
876: are, respectively,
877: the upper, left-most, lower, or right-most extremes of the
878: screen.
879: .Ar Label
880: is the label string.
881: .Ar Frame ,
882: .Ar pty ,
883: and
884: .Ar mapnl
885: are flag values
886: interpreted in the same way as the argument to
887: .Ar foreground
888: (see above);
889: they mean, respectively, put a frame around this window (default true),
890: allocate pseudo-terminal for this window rather than socketpair (default
891: true), and map new line characters in this window to carriage return
892: and line feed (default true if socketpair is used, false otherwise).
893: Normally, a window is automatically closed when its process
894: exits. Setting
895: .Ar keepopen
896: to true (default false) prevents this
897: action. When
898: .Ar smooth
899: is true, the screen is updated more frequently
900: (for this window) to produce a more terminal-like behavior.
901: The default value of
902: .Ar smooth
903: is set by the
904: .Ar default_smooth
905: command (see above).
906: .Ar Shell
907: is a list of strings that will be used as the shell
908: program to place in the window (default is the program specified
909: by
1.7 ! aaron 910: .Ar default_shell ,
1.1 deraadt 911: see above). The created window's identifier
912: is returned as a number.
913: .It Xo
914: .Ic write Ns ( Bq Ar window ,
915: .Bq Aq Ar string\-list )
916: .Xc
917: Send the list of strings,
918: .Aq Ar string-list ,
919: to
1.7 ! aaron 920: .Nm window ,
1.1 deraadt 921: separated
922: by spaces but not terminated with a new line. The strings are actually
923: given to the window as input. No value is returned. Default
924: is the current window.
925: .El
926: .Ss Predefined Variables
927: These variables are for information only. Redefining them does
928: not affect the internal operation of
1.7 ! aaron 929: .Nm window .
1.1 deraadt 930: .Bl -tag -width modes
931: .It Ar baud
932: The baud rate as a number between 50 and 38400.
933: .It Ar modes
934: The display modes (reverse video, underline, blinking, graphics)
935: supported by the physical terminal. The value of
936: .Ar modes
937: is the bitwise or of some of the one bit values,
938: .Ar m_blk ,
939: .Ar m_grp ,
940: .Ar m_rev ,
941: and
942: .Ar m_ul
943: (see below).
944: These values are useful
945: in setting the window cursors' modes (see
946: .Ar cursormodes
947: above).
948: .It Ar m_blk
949: The blinking mode bit.
950: .It Ar m_grp
951: The graphics mode bit (not very useful).
952: .It Ar m_rev
953: The reverse video mode bit.
954: .It Ar m_ul
955: The underline mode bit.
956: .It Ar ncol
957: The number of columns on the physical screen.
958: .It Ar nrow
959: The number of rows on the physical screen.
960: .It Ar term
961: The terminal type. The standard name, found in the second name
962: field of the terminal's
963: .Ev TERMCAP
964: entry, is used.
965: .Sh ENVIRONMENT
1.7 ! aaron 966: .Nm
1.1 deraadt 967: utilizes these environment variables:
968: .Ev HOME ,
969: .Ev SHELL ,
970: .Ev TERM ,
971: .Ev TERMCAP ,
972: .Ev WINDOW_ID .
973: .Sh FILES
974: .Bl -tag -width /dev/[pt]ty[pq]? -compact
975: .It Pa ~/.windowrc
1.4 aaron 976: startup command file
1.7 ! aaron 977: .It Pa /dev/[pt]ty[pq]?
1.4 aaron 978: pseudo-terminal devices
1.1 deraadt 979: .El
980: .Sh HISTORY
981: The
1.7 ! aaron 982: .Nm
1.1 deraadt 983: command appeared in
984: .Bx 4.3 .
985: .Sh DIAGNOSTICS
986: Should be self explanatory.