diff options
Diffstat (limited to 'usr.bin/window/README')
| -rw-r--r-- | usr.bin/window/README | 199 |
1 files changed, 0 insertions, 199 deletions
diff --git a/usr.bin/window/README b/usr.bin/window/README deleted file mode 100644 index 42d45b368a36..000000000000 --- a/usr.bin/window/README +++ /dev/null @@ -1,199 +0,0 @@ -/*- - * Copyright (c) 1990, 1993 - * The Regents of the University of California. All rights reserved. - * - * This code is derived from software contributed to Berkeley by - * Edward Wang at The University of California, Berkeley. - * - * Redistribution and use in source and binary forms, with or without - * modification, are permitted provided that the following conditions - * are met: - * 1. Redistributions of source code must retain the above copyright - * notice, this list of conditions and the following disclaimer. - * 2. Redistributions in binary form must reproduce the above copyright - * notice, this list of conditions and the following disclaimer in the - * documentation and/or other materials provided with the distribution. - * 3. All advertising materials mentioning features or use of this software - * must display the following acknowledgement: - * This product includes software developed by the University of - * California, Berkeley and its contributors. - * 4. Neither the name of the University nor the names of its contributors - * may be used to endorse or promote products derived from this software - * without specific prior written permission. - * - * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND - * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE - * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE - * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL - * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS - * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT - * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY - * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - * SUCH DAMAGE. - * - * @(#)README 8.1 (Berkeley) 6/6/93 - */ - -Compilation notes: - - Compiler options: - - BYTE_ORDER (used only in ww.h) - It should already be defined in machine/endian.h. - The code knows about BIG_ENDIAN, LITTLE_ENDIAN, and PDP_ENDIAN. - It only cares about byte order in words, so PDP_ENDIAN - is the same as LITTLE_ENDIAN. - OLD_TTY - If you don't have Posix termios, then define this. - VMIN_BUG - Even if you have Posix termios, define this if the MIN and TIME - feature in noncanonical mode doesn't work correctly. - - Ok, there's another one, STR_DEBUG. It turns on consistency checks - in the string allocator. It's been left on since performace doesn't - seem to suffer. There's an abort() somewhere when an inconsistency - is found. It hasn't happened in years. - - The file local.h contains locally tunable constants. - - The makefile used to be updated with mkmf; it has been changed -at various times to use cpp -M and, currently, mkdep. The only library -it needs is termcap. - - Window, as is, only runs on 4.3 (or later) machines. - - On 4.2 machines, at least these modifications must be done: - - delete uses of window size ioctls: TIOCGWINSZ, TIOCSWINSZ, - struct winsize - add to ww.h - typedef int fd_set; - #define FD_ZERO(s) (*(s) = 0) - #define FD_SET(b, s) (*(s) |= 1 << (b)) - #define FD_ISSET(b, s) (*(s) & 1 << (b)) - add to ww.h - #define sigmask(s) (1 << (s) - 1) - - -A few notes about the internals: - - The window package. Windows are opened by calling wwopen(). -Wwwrite() is the primitive for writing to windows. Wwputc(), wwputs(), -and wwprintf() are also supported. Some of the outputs to windows are -delayed. Wwupdate() updates the terminal to match the internal screen -buffer. Wwspawn() spawns a child process on the other end of a window, -with its environment tailored to the window. Visible windows are -doubly linked in the order of their overlap. Wwadd() inserts a window -into the list at a given place. Wwdelete() deletes it. Windows not in -the list are not visible, though wwwrite() still works. Window was -written before the days of X and Sunview, so some of the terminology -is not standard. - - Most functions return -1 on error. Wwopen() returns the null -pointer. An error number is saved in wwerrno. Wwerror() returns an -error string based on wwerrno suitable for printing. - - The terminal drivers perform all output to the physical terminal, -including special functions like character and line insertion and -deletion. The window package keeps a list of known terminals. At -initialization time, the terminal type is matched against the list to -find the right terminal driver to use. The last driver, the generic -driver, matches all terminals and uses the termcap database. The -interface between the window package the terminal driver is the `tt' -structure. It contains pointers to functions to perform special -functions and terminal output, as well as flags about the -characteristics of the terminal. Most of these ideas are borrowed -from the Maryland window package, which in turn is based on Goslin's -Emacs. - - The IO system is semi-synchronous. Terminal input is signal -driven, and everything else is done synchronously with a single -select(). It is roughly event-driven, though not in a clean way. - - Normally, in both conversation mode and command mode, window -sleeps in a select() in wwiomux() waiting for data from the -pseudo-terminals. At the same time, terminal input causes SIGIO which -is caught by wwrint(). The select() returns when at least one of the -pseudo-terminals becomes ready for reading. - - Wwrint() is the interrupt handler for tty input. It reads input -into a linear buffer accessed through four pointers: - - +-------+--------------+----------------+ - | empty | data | empty | - +-------+--------------+----------------+ - ^ ^ ^ ^ - | | | | - wwib wwibp wwibq wwibe - -Wwrint() appends characters at the end and increments wwibq (*wwibq++ -= c), and characters are taken off the buffer at wwibp using the -wwgetc() and wwpeekc() macros. As is the convention in C, wwibq -and wwibe point to one position beyond the end. In addition, -wwrint() will do a longjmp(wwjmpbuf) if wwsetjmp is true. This is -used by wwiomux() to interrupt the select() which would otherwise -resume after the interrupt. (Actually, I hear this is not true, -but the longjmp feature is used to avoid a race condition as well. -Anyway, it means I didn't have to depend on a feature in a -daily-changing kernel, but that's another story.) The macro -wwinterrupt() returns true if the input buffer is non-empty. -Wwupdate(), wwwrite(), and wwiomux() check this condition and will -return at the first convenient opportunity when it becomes true. -In the case of wwwrite(), the flag ww_nointr in the window structure -overrides this. This feature allows the user to interrupt lengthy -outputs safely. The structure of the input buffer is designed to -avoid race conditions without blocking interrupts. - - Actually, wwsetjmp and wwinterrupt() are part of a software -interrupt scheme used by the two interrupt catchers wwrint() and -wwchild(). Asserting the interrupt lets the synchronous parts of -the program know that there's an interesting asynchronous condition -(i.e., got a keyboard character, or a child process died) that they -might want to process before anything else. The synchronous routines -can check for this condition with wwinterrupt() or by arranging -that a longjmp() be done. - - Wwiomux() copies pseudo-terminal output into their corresponding -windows. Without anything to do, it blocks in a select(), waiting for -read ready on pseudo-terminals. Reads are done into per-window buffers -in the window structures. When there is at least one buffer non-empty, -wwiomux() finds the top most of these windows and writes it using -wwwrite(). Then the process is repeated. A non-blocking select() is -done after a wwwrite() to pick up any output that may have come in -during the write, which may take a long time. Specifically, we use -this to stop output or flush buffer when a pseudo-terminal tells us to -(we use pty packet mode). The select() blocks only when all of the -windows' buffers are empty. A wwupdate() is done prior to this, which -is the only time the screen is guaranteed to be completely up to date. -Wwiomux() loops until wwinterrupt() becomes true. - - The top level routine for all this is mloop(). In conversation -mode, it simply calls wwiomux(), which only returns when input is -available. The input buffer is then written to the pseudo-terminal of -the current window. If the escape character is found in the input, -command mode is entered. Otherwise, the process is repeated. In -command mode, control is transferred to docmd() which returns only when -conversation mode is reentered. Docmd() and other command processing -routines typically wait for input in a loop: - - while (wwpeekc() < 0) - wwiomux(); - -When the loop terminates, wwgetc() is used to read the input buffer. - - Output to the physical terminal is handled by the lowest level -routines of the window package, in the files ttoutput.c and tt.h. The -standard IO package is not used, to get better control over buffering -and to use non-blocking reads in wwrint(). The buffer size is set to -approximately one second of output time, based on the baudrate. - - The result of all this complexity is faster response time, -especially in output stopping and flushing. Wwwrite() checks -wwinterrupt() after every line. It also calls wwupdate() for each line -it writes. The output buffer is limited to one second of output time. -Thus, there is usually only a delay of one to two lines plus one second -after a ^C or ^S. Also, commands that produce lengthy output can be -aborted without actually showing all of it on the terminal. (Try the -'?' command followed by escape immediately.) |