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