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