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