usr.bin/window/window.1

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