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