Annotation of src/usr.bin/window/window.1, Revision 1.12
1.12 ! aaron 1: .\" $OpenBSD: window.1,v 1.11 2000/07/06 04:06:57 aaron Exp $
1.1 deraadt 2: .\" $NetBSD: window.1,v 1.3 1995/09/28 10:35:05 tls Exp $
3: .\"
4: .\" Copyright (c) 1985, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" Edward Wang at The University of California, Berkeley.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\" 3. All advertising materials mentioning features or use of this software
19: .\" must display the following acknowledgement:
20: .\" This product includes software developed by the University of
21: .\" California, Berkeley and its contributors.
22: .\" 4. Neither the name of the University nor the names of its contributors
23: .\" may be used to endorse or promote products derived from this software
24: .\" without specific prior written permission.
25: .\"
26: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36: .\" SUCH DAMAGE.
37: .\"
38: .\" @(#)window.1 8.2 (Berkeley) 12/30/93
39: .\"
40: .Dd December 30, 1993
41: .Dt WINDOW 1
1.7 aaron 42: .Os
1.1 deraadt 43: .Sh NAME
44: .Nm window
45: .Nd window environment
46: .Sh SYNOPSIS
47: .Nm window
48: .Op Fl t
49: .Op Fl f
50: .Op Fl d
51: .Op Fl e Ar escape-char
52: .Op Fl c Ar command
53: .Sh DESCRIPTION
1.7 aaron 54: .Nm
1.1 deraadt 55: implements a window environment on
56: .Tn ASCII
57: terminals.
58: .Pp
59: A window is a rectangular portion of the physical terminal
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
87: Turn on terse mode (see
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
146: .Xr (pty 4 )
147: or a
148: .Ux
149: domain socket
150: .Xr (socketpair 4 ) .
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
160: .Xr (environ 5 )
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
185: on top of all other windows, except those in foreground.
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.
299: The default buffer size is used (see
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
471: Single valued (no arrays) 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.1 deraadt 567: forces the other to be converted to a string in necessary.
568: .It Xo
569: .Aq Va expr1
570: .Ic <
571: .Aq Va expr2 ,
572: .Aq Va expr1
573: .Ic >
574: .Aq Va expr2 ,
575: .Aq Va expr1
576: .Ic <=
577: .Aq Va expr2 ,
578: .Xc
579: Less than, greater than, less than or equal to,
1.9 aaron 580: greater than or equal to.
581: Both numeric and string values, with automatic conversion as above.
1.1 deraadt 582: .It Xo
583: .Aq Va expr1
584: .Ic <<
585: .Aq Va expr2 ,
586: .Aq Va expr1
587: .Ic >>
588: .Aq Va expr2
589: .Xc
590: If both operands are numbers,
591: .Aq Va expr1
592: is bit
593: shifted left (or right) by
594: .Aq Va expr2
1.9 aaron 595: bits.
596: If
1.1 deraadt 597: .Aq Va expr1
598: is
599: a string, then its first (or last)
600: .Aq Va expr2
601: characters are
602: returns (if
603: .Aq Va expr2
604: is also a string, then its length is used
605: in place of its value).
606: .It Xo
607: .Aq Va expr1
608: .Ic +
609: .Aq Va expr2 ,
610: .Aq Va expr1
611: .Ic -
612: .Aq Va expr2
613: .Xc
1.9 aaron 614: Addition and subtraction on numbers.
615: For
1.7 aaron 616: .Ql + ,
617: if one
1.1 deraadt 618: argument is a string, then the other is converted to a string,
619: and the result is the concatenation of the two strings.
620: .It Xo
621: .Aq Va expr1
622: .Ic \&*
623: .Aq Va expr2 ,
624: .Aq Va expr1
625: .Ic \&/
626: .Aq Va expr2 ,
627: .Aq Va expr1
628: .Ic \&%
629: .Aq Va expr2
630: .Xc
1.9 aaron 631: Multiplication, division, modulo.
632: Numbers only.
1.1 deraadt 633: .It Xo
634: .Ic \- Ns Aq Va expr ,
635: .Ic ~ Ns Aq Va expr ,
636: .Ic \&! Ns Aq Va expr ,
637: .Ic \&$ Ns Aq Va expr ,
638: .Ic \&$? Ns Aq Va expr
639: .Xc
640: The first three are unary minus, bitwise complement and logical complement
1.9 aaron 641: on numbers only.
642: The operator,
1.7 aaron 643: .Ql $ ,
644: takes
1.1 deraadt 645: .Aq Va expr
646: and returns
1.9 aaron 647: the value of the variable of that name.
648: If
1.1 deraadt 649: .Aq Va expr
650: is numeric
651: with value
652: .Ar n
653: and it appears within an alias macro (see below),
1.7 aaron 654: then it refers to the nth argument of the alias invocation.
655: .Ql $?
1.1 deraadt 656: tests for the existence of the variable
657: .Aq Va expr ,
658: and returns 1
659: if it exists or 0 otherwise.
660: .It Xo
661: .Ao Va expr Ac Ns Pq Aq Ar arglist
662: .Xc
663: Function call.
664: .Aq Va Expr
665: must be a string that is the unique
1.6 aaron 666: prefix of the name of a built-in
1.7 aaron 667: .Nm
1.1 deraadt 668: function
1.9 aaron 669: or the full name of a user defined alias macro.
670: In the case of a built-in function,
1.1 deraadt 671: .Aq Ar arglist
672: can be in one of two forms:
673: .Bd -literal -offset indent
674: <expr1>, <expr2>, ...
675: argname1 = <expr1>, argname2 = <expr2>, ...
676: .Ed
677: .Pp
678: The two forms can in fact be intermixed, but the result is
1.9 aaron 679: unpredictable.
680: Most arguments can be omitted; default values will
681: be supplied for them.
682: The
1.1 deraadt 683: .Ar argnames
684: can be unique prefixes
1.9 aaron 685: of the argument names.
686: The commas separating
1.1 deraadt 687: arguments are used only to disambiguate, and can usually be omitted.
688: .Pp
1.9 aaron 689: Only the first argument form is valid for user defined aliases.
690: Aliases are defined using the
1.1 deraadt 691: .Ic alias
1.9 aaron 692: built-in function (see below).
693: Arguments are accessed via a variant of the variable mechanism (see the
1.7 aaron 694: .Ql $
695: operator above).
1.1 deraadt 696: .Pp
697: Most functions return value, but some are used for side effect
1.9 aaron 698: only and so must be used as statements.
699: When a function or an alias is used
1.1 deraadt 700: as a statement, the parentheses surrounding
1.9 aaron 701: the argument list may be omitted.
702: Aliases return no value.
1.1 deraadt 703: .El
1.9 aaron 704: .Ss Built-in functions
1.1 deraadt 705: The arguments are listed by name in their natural
1.9 aaron 706: order.
707: Optional arguments are in square brackets
1.1 deraadt 708: .Sq Op .
709: Arguments
710: that have no names are in angle brackets
711: .Sq <> .
712: An argument meant to be a boolean flag (often named
713: .Ar flag )
714: can be one of
715: .Ar on ,
716: .Ar off ,
717: .Ar yes ,
718: .Ar no ,
719: .Ar true ,
720: or
721: .Ar false ,
722: with
723: obvious meanings, or it can be a numeric expression,
724: in which case a non-zero value is true.
725: .Bl -tag -width Fl
726: .It Xo
727: .Ic alias Ns Po Bq Aq Ar string ,
728: .Bq Aq Ar string\-list Pc
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.7 aaron 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.1 deraadt 741: .Aq Ar string\-list
742: is no change.
743: .It Ic close Ns Pq Aq Ar window\-list
744: Close the windows specified in
745: .Aq Ar window\-list .
746: If
747: .Aq Ar window\-list
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.1 deraadt 780: .It Ic default_shell Ns Pq Bq Aq Ar string\-list
781: Set the default window shell program to
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 ,
808: .Bq Aq Ar string\-list )
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 ,
983: .Bq Aq Ar string\-list )
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