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