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