Return to README CVS log

Up to [CSRG BSD Unix] / 43BSD / ucb / window

Annotation of 43BSD/ucb/window/README, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.