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