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