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