1@(#)README 3.7 08/04/86 2 3/* 4 * Copyright (c) 1983 Regents of the University of California, 5 * All rights reserved. Redistribution permitted subject to 6 * the terms of the Berkeley Software License Agreement. 7 */ 8 9Compilation notes: 10 11 There is only one compiler option: 12 13 mc68000 use 68000 byte ordering 14 It should already be defined in the preprocessor. 15 16 The file local.h contains locally tunable constants. 17 18 The makefile should be updated with mkmf. The only library it needs 19is termcap. 20 21 Window, as is, only runs on 4.3 machines. 22 23 On 4.2 machines, at least these modifications must be done: 24 25 delete uses of window size ioctls: TIOCGWINSZ, TIOCSWINSZ, 26 struct winsize 27 add to ww.h 28 typedef int fd_set; 29 #define FD_ZERO(s) (*(s) = 0) 30 #define FD_SET(b, s) (*(s) |= 1 << (b)) 31 #define FD_ISSET(b, s) (*(s) & 1 << (b)) 32 add to ww.h 33 #define sigmask(s) (1 << (s) - 1) 34 35 36A few notes about the internals: 37 38 The window package. Windows are opened by calling wwopen(). 39Wwwrite() is the primitive for writing to windows. Wwputc(), wwputs(), 40and wwprintf() are also supported. Some of the outputs to windows are 41delayed. Wwupdate() updates the terminal to match the internal screen 42buffer. Wwspawn() spawns a child process on the other end of a window, 43with it's environment tailored to the window. Visible windows are 44doubly linked in the order of their overlap. Wwadd() inserts a window 45into the list at a given place. Wwdelete() deletes it. Windows not in 46the list are not visible, though wwwrite() still works. 47 48 Most functions return -1 on error. Wwopen() returns the null 49pointer. An error number is saved in wwerrno. Wwerror() returns an 50error string based on wwerrno suitable for printing. 51 52 The terminal drivers perform all output to the physical terminal, 53including special functions like character and line insertion and 54deletion. The window package keeps a list of known terminals. At 55initialization time, the terminal type is matched against the list to 56find the right terminal driver to use. The last driver, the generic 57driver, matches all terminals and uses the termcap database. The 58interface between the window package the terminal driver is the `tt' 59structure. It contains pointers to functions to perform special 60functions and terminal output, as well as flags about the 61characteristics of the terminal. 62 63 The IO system is semi-synchronous. Terminal input is signal 64driven, and everything else is done synchronously with a single 65select(). 66 67 Normally, in both conversation mode and command mode, window 68sleeps in a select() in wwiomux() waiting for data from the 69pseudo-terminals. At the same time, terminal input causes SIGIO which 70is caught by wwrint(). The select() returns when at least one of the 71pseudo-terminals becomes ready for reading. 72 73 Wwrint() is the interrupt handler for tty input. It reads input 74into a linear buffer accessed through four pointers: 75 76 +-------+--------------+----------------+ 77 | empty | data | empty | 78 +-------+--------------+----------------+ 79 ^ ^ ^ ^ 80 | | | | 81 wwib wwibp wwibq wwibe 82 83Wwrint() appends characters at the end and increments wwibq (*wwibq++ = 84c), and characters are taken from the buffer at wwibp using the 85wwgetc() and wwpeekc() macros. As is the convention in C, wwibq and 86wwibe point to one position beyond the end. In addition, wwrint() will 87do a longjmp(wwjmpbuf) if wwsetjmp is true. This is used by wwiomux() 88to interrupt the select() which would otherwise resume after the 89interrupt. The macro wwinterrupt() returns true if the input buffer is 90non-empty. Wwupdate(), wwwrite(), and wwiomux() check this condition 91and will return at the first convenient opportunity when it becomes 92true. In the case of wwwrite(), the flag ww_nointr in the window 93structure overrides this. This feature allows the user to interrupt 94lengthy outputs safely. The structure of the input buffer is designed 95to avoid race conditions without blocking interrupts. 96 97 Wwiomux() copies pseudo-terminal outputs into their corresponding 98windows. Without anything to do, it blocks in a select(), waiting for 99read ready on pseudo-terminals. Reads are done into per-window buffers 100in the window structures. When there is at least one buffer non-empty, 101wwiomux() finds the top most of these windows and writes it using 102wwwrite(). Then the process is repeated. A non-blocking select() is 103done after a wwwrite() to pick up any output that may have come in 104during the write, which may take a long time. Specifically, we use 105this to stop output or flush buffer when a pseudo-terminal tells us to 106(we use pty packet mode). The select() blocks only when all of the 107windows' buffers are empty. A wwupdate() is done prior to this, which 108is the only time the screen is guaranteed to be completely up to date. 109Wwiomux() loops until wwinterrupt() becomes true. 110 111 The top level routine for all this is mloop(). In conversation 112mode, it simply calls wwiomux(), which only returns when input is 113available. The input buffer is then written to the pseudo-terminal of 114the current window. If the escape character is found in the input, 115command mode is entered. Otherwise, the process is repeated. In 116command mode, control is transferred to docmd() which returns only when 117conversation mode is reentered. Docmd() and other command processing 118routines typically wait for input in a loop: 119 120 while (wwpeekc() < 0) 121 wwiomux(); 122 123When the loop terminates, wwgetc() is used to read the input buffer. 124 125 Output to the physical terminal is handled by the lowest level 126routines of the window package, in the files ttoutput.c and tt.h. The 127standard IO package is not used, to get better control over buffering 128and to use non-blocking reads in wwrint(). The buffer size is set to 129approximately one second of output time, based on the baudrate. 130 131 The result of all this complexity is faster response time, 132especially in output stopping and flushing. Wwwrite() checks 133wwinterrupt() after every line. It also calls wwupdate() for each line 134it writes. The output buffer is limited to one second of output time. 135Thus, there is usually only a delay of one to two lines plus one second 136after a ^C or ^S. Also, commands that produce lengthy output can be 137aborted without actually showing all of it on the terminal. (Try the 138'?' command followed by escape immediately.) 139