usr.bin/window/README

   1 /*-
   2  * Copyright (c) 1990, 1993
   3  *      The Regents of the University of California.  All rights reserved.
   4  *
   5  * This code is derived from software contributed to Berkeley by
   6  *  Edward Wang at The University of California, Berkeley.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions
  10  * are met:
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in the
  15  *    documentation and/or other materials provided with the distribution.
  16  * 3. Neither the name of the University nor the names of its contributors
  17  *    may be used to endorse or promote products derived from this software
  18  *    without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30  * SUCH DAMAGE.
  31  *
  32  *      @(#)README      8.1 (Berkeley) 6/6/93
  33  */
  34
  35 Compilation notes:
  36
  37      Compiler options:
  38
  39         BYTE_ORDER (used only in ww.h)
  40                 It should already be defined in machine/endian.h.
  41                 The code knows about BIG_ENDIAN, LITTLE_ENDIAN, and PDP_ENDIAN.
  42                 It only cares about byte order in words, so PDP_ENDIAN
  43                 is the same as LITTLE_ENDIAN.
  44         OLD_TTY
  45                 If you don't have Posix termios, then define this.
  46         VMIN_BUG
  47                 Even if you have Posix termios, define this if the MIN and TIME
  48                 feature in noncanonical mode doesn't work correctly.
  49
  50      Ok, there's another one, STR_DEBUG.  It turns on consistency checks
  51      in the string allocator.  It's been left on since performace doesn't
  52      seem to suffer.  There's an abort() somewhere when an inconsistency
  53      is found.  It hasn't happened in years.
  54
  55      The file local.h contains locally tunable constants.
  56
  57      The makefile used to be updated with mkmf; it has been changed
  58 at various times to use cpp -M and, currently, mkdep.  The only library
  59 it needs is termcap.
  60
  61      Window, as is, only runs on 4.3 (or later) machines.
  62
  63      On 4.2 machines, at least these modifications must be done:
  64
  65         delete uses of window size ioctls: TIOCGWINSZ, TIOCSWINSZ,
  66                 struct winsize
  67         add to ww.h
  68                 typedef int fd_set;
  69                 #define FD_ZERO(s) (*(s) = 0)
  70                 #define FD_SET(b, s) (*(s) |= 1 << (b))
  71                 #define FD_ISSET(b, s) (*(s) & 1 << (b))
  72         add to ww.h
  73                 #define sigmask(s) (1 << (s) - 1)
  74
  75
  76 A few notes about the internals:
  77
  78      The window package.  Windows are opened by calling wwopen().
  79 Wwwrite() is the primitive for writing to windows.  Wwputc(), wwputs(),
  80 and wwprintf() are also supported.  Some of the outputs to windows are
  81 delayed.  Wwupdate() updates the terminal to match the internal screen
  82 buffer.  Wwspawn() spawns a child process on the other end of a window,
  83 with its environment tailored to the window.  Visible windows are
  84 doubly linked in the order of their overlap.  Wwadd() inserts a window
  85 into the list at a given place.  Wwdelete() deletes it.  Windows not in
  86 the list are not visible, though wwwrite() still works.  Window was
  87 written before the days of X and Sunview, so some of the terminology
  88 is not standard.
  89
  90      Most functions return -1 on error.  Wwopen() returns the null
  91 pointer.  An error number is saved in wwerrno.  Wwerror() returns an
  92 error string based on wwerrno suitable for printing.
  93
  94      The terminal drivers perform all output to the physical terminal,
  95 including special functions like character and line insertion and
  96 deletion.  The window package keeps a list of known terminals.  At
  97 initialization time, the terminal type is matched against the list to
  98 find the right terminal driver to use.  The last driver, the generic
  99 driver, matches all terminals and uses the termcap database.  The
 100 interface between the window package the terminal driver is the `tt'
 101 structure.  It contains pointers to functions to perform special
 102 functions and terminal output, as well as flags about the
 103 characteristics of the terminal.  Most of these ideas are borrowed
 104 from the Maryland window package, which in turn is based on Goslin's
 105 Emacs.
 106
 107      The IO system is semi-synchronous.  Terminal input is signal
 108 driven, and everything else is done synchronously with a single
 109 poll().  It is roughly event-driven, though not in a clean way.
 110
 111      Normally, in both conversation mode and command mode, window
 112 sleeps in a poll() in wwiomux() waiting for data from the
 113 pseudo-terminals.  At the same time, terminal input causes SIGIO which
 114 is caught by wwrint().  The poll() returns when at least one of the
 115 pseudo-terminals becomes ready for reading.
 116
 117      Wwrint() is the interrupt handler for tty input.  It reads input
 118 into a linear buffer accessed through four pointers:
 119
 120         +-------+--------------+----------------+
 121         | empty |    data      |   empty        |
 122         +-------+--------------+----------------+
 123         ^       ^               ^                ^
 124         |       |               |                |
 125        wwib    wwibp           wwibq            wwibe
 126
 127 Wwrint() appends characters at the end and increments wwibq (*wwibq++
 128 = c), and characters are taken off the buffer at wwibp using the
 129 wwgetc() and wwpeekc() macros.  As is the convention in C, wwibq
 130 and wwibe point to one position beyond the end.  In addition,
 131 wwrint() will do a longjmp(wwjmpbuf) if wwsetjmp is true.  This is
 132 used by wwiomux() to interrupt the poll() which would otherwise
 133 resume after the interrupt.  (Actually, I hear this is not true,
 134 but the longjmp feature is used to avoid a race condition as well.
 135 Anyway, it means I didn't have to depend on a feature in a
 136 daily-changing kernel, but that's another story.) The macro
 137 wwinterrupt() returns true if the input buffer is non-empty.
 138 Wwupdate(), wwwrite(), and wwiomux() check this condition and will
 139 return at the first convenient opportunity when it becomes true.
 140 In the case of wwwrite(), the flag ww_nointr in the window structure
 141 overrides this.  This feature allows the user to interrupt lengthy
 142 outputs safely.  The structure of the input buffer is designed to
 143 avoid race conditions without blocking interrupts.
 144
 145      Actually, wwsetjmp and wwinterrupt() are part of a software
 146 interrupt scheme used by the two interrupt catchers wwrint() and
 147 wwchild().  Asserting the interrupt lets the synchronous parts of
 148 the program know that there's an interesting asynchronous condition
 149 (i.e., got a keyboard character, or a child process died) that they
 150 might want to process before anything else.  The synchronous routines
 151 can check for this condition with wwinterrupt() or by arranging
 152 that a longjmp() be done.
 153
 154      Wwiomux() copies pseudo-terminal output into their corresponding
 155 windows.  Without anything to do, it blocks in a poll(), waiting for
 156 read ready on pseudo-terminals.  Reads are done into per-window buffers
 157 in the window structures.  When there is at least one buffer non-empty,
 158 wwiomux() finds the top most of these windows and writes it using
 159 wwwrite().  Then the process is repeated.  A non-blocking poll() is
 160 done after a wwwrite() to pick up any output that may have come in
 161 during the write, which may take a long time.  Specifically, we use
 162 this to stop output or flush buffer when a pseudo-terminal tells us to
 163 (we use pty packet mode).  The poll() blocks only when all of the
 164 windows' buffers are empty.  A wwupdate() is done prior to this, which
 165 is the only time the screen is guaranteed to be completely up to date.
 166 Wwiomux() loops until wwinterrupt() becomes true.
 167
 168      The top level routine for all this is mloop().  In conversation
 169 mode, it simply calls wwiomux(), which only returns when input is
 170 available.  The input buffer is then written to the pseudo-terminal of
 171 the current window.  If the escape character is found in the input,
 172 command mode is entered.  Otherwise, the process is repeated.  In
 173 command mode, control is transferred to docmd() which returns only when
 174 conversation mode is reentered.  Docmd() and other command processing
 175 routines typically wait for input in a loop:
 176
 177         while (wwpeekc() < 0)
 178                 wwiomux();
 179
 180 When the loop terminates, wwgetc() is used to read the input buffer.
 181
 182      Output to the physical terminal is handled by the lowest level
 183 routines of the window package, in the files ttoutput.c and tt.h.  The
 184 standard IO package is not used, to get better control over buffering
 185 and to use non-blocking reads in wwrint().  The buffer size is set to
 186 approximately one second of output time, based on the baudrate.
 187
 188      The result of all this complexity is faster response time,
 189 especially in output stopping and flushing.  Wwwrite() checks
 190 wwinterrupt() after every line.  It also calls wwupdate() for each line
 191 it writes.  The output buffer is limited to one second of output time.
 192 Thus, there is usually only a delay of one to two lines plus one second
 193 after a ^C or ^S.  Also, commands that produce lengthy output can be
 194 aborted without actually showing all of it on the terminal.  (Try the
 195 '?' command followed by escape immediately.)