Garbo/Garbo.cdr/mac/unix/uw_shar.sit/uw-42-part2.shar

Text File | 1989-09-14 | 57KB | 1,711 lines

#Date: Wed, 2 Mar 88 10:00:18 PST
#From: [e-mail] (Edward Rothberg)
#Subject: UW 4.2 part 2 of 8
: This is a shar archive.  Extract with sh, not csh.
if test ! -d doc; then
    echo mkdir doc
    mkdir doc
fi
echo x - doc/uwlib.ms
sed -e 's/^X//' > doc/uwlib.ms << '!EOF!doc/uwlib.ms!'
X.\" This file should be processed by nroff or troff with the -ms macro set
X.ds uw \s-2UW\s0
X.DA September 30, 1986
X.TL
XThe UW Programmer's Library
X.AU
XJohn D. Bruner
X.SH
XIntroduction
X.PP
X\*(uw is a multiple-window Macintosh interface to a 4.2BSD UNIX\**.
X.FS
XMacintosh is a trademark of McIntosh Laboratories which
Xis licensed to Apple Computer, Inc.
XUNIX is a registered trademark of Bell Laboratories.
X.FE
X\*(uw version 3 comprises a server,
Xa set of utility programs,
Xand an program-level interface.
XThis manual describes the services which are available
Xin the \*(uw programmer's library.
XThis library allow programs to create,
Xcommunicate with,
Xand perform some control operations upon
Xwindows on the Macintosh.
X.SH
XBackground
X.PP
XBefore the library routines themselves can be discussed,
Xit is necessary to consider some aspects of the \*(uw
Xserver.
XThe server which was distributed with \*(uw versions 1.6 and 2.10
Xcommunicated with the Macintosh using a protocol which
Xis referred to as the ``original protocol.''
XThe version 3 server is capable of communicating in this protocol;
Xhowever,
Xit also supports an ``extended protocol.''
XFor convenience,
Xthese protocols are assigned numbers:
Xprotocol 1 is the original protocol
Xand protocol 2 is the extended protocol.
X.PP
XProtocol 1 provides a mechanism for
Xthe creation and destruction of windows
Xas well as a means to multiplex a single
Xcommunications line among several windows.
XIt provides a mechanism for transmitting
Xcontrol and ``meta'' characters,
Xand it also provides two ``maintenance functions''
Xwhich are used for startup and shutdown.
X.PP
XProtocol 2 provides two significant enhancements
Xrelative to protocol 1.
XFirst,
Xwindow creation messages specify the window emulation type
X(\fIe.g.\fP adm-31, vt52).
XSecond,
Xadditional information about windows,
Xcalled ``window options,''
Xis transmitted between the Macintosh client and the
Xserver on the host.
X.PP
XWindow options are an ``out-of-band'' channel of
Xinformation between the Macintosh and the host.
XThere are two types:
Xgeneric
X(common to all window types)
Xand emulation-specific.
XThe following are generic:
X.DS
Xwindow visibility
Xwindow type
Xwindow position (pixel address of top left corner)
Xwindow title
Xwindow size in pixels
X.DE
XThe following window options are specific to
Xcursor-addressible terminal emulations:
X.DS
Xterminal size (number of rows and columns)
Xfont size index (small=0, large=1)
Xmouse handling (clipboard or encoded send-to-host)
Xbell characteristics (audible, visible)
Xcursor appearance (block or underscore)
X.DE
X.PP
XThe server distinguishes between two window classes \(em
Xinternal and external.
XInternal windows are handled entirely by the server.
XThey are always terminal emulations and are always
Xassociated with a pseudo-terminal device.
X.PP
XBy contrast,
Xan external window always involves some outside process.
XThe server communicates with this process through one
Xor two Internet domain network connections.
XThere is always a ``data'' connection,
Xthrough which the external process exchanges information
X(indirectly, through the server)
Xwith the Macintosh.
XThere may also be a ``control'' connection
Xthrough which the external process exchanges
Xwindow option information
X(again indirectly)
Xwith the Macintosh.
XThe server acts as a multiplexor and demultiplexor
Xfor external windows.
XIt also caches window option information;
Xhowever,
Xit does not perform host-end emulation-specific tasks.
X.PP
XInternal and external windows meet different needs.
XTerminal emulation on the local host is best performed
Xby internal windows,
Xbecause fewer processes are involved
X(and response time is better).
XExternal windows are suitable for remote processes
X(\fIi.e.\fP those on another Internet host)
Xor for non-terminal tasks such as file transfer.
XThe \*(uw application library contains routines
Xto create and manipulate both classes of windows.
X.SH
XWindow ID's and Network Addresses
X.PP
XA unique 32-bit identification number is associated
Xwith each window that a server manipulates.
XSome operations
X(described below)
Xrequire the window number to be specified.
XWhen the server creates a new internal window,
Xit passes the window ID as the environment variable
X``UW_ID''.
X.PP
XThe server creates two network sockets upon which to receive
Xincoming messages.
XOne socket receives UNIX-domain datagrams,
Xthe other listens for Internet-domain stream connections.
XThe addresses of these sockets are placed in the environment
Xas the variables ``UW_UIPC''
X(UNIX-domain)
Xand ``UW_INET''
X(Internet domain).
X.SH
XData Types and Data Structures
X.PP
XThe \*(uw programmer's library uses a number
Xof simple and structured data types.
X.IP uwid_t 1i
XUnique window ID numbers are represented by the data type ``uwid_t''.
X.IP UWIN
XLibrary routines which operate upon external windows
Xput a range of window information into a structure.
XThe type ``UWIN'' is a pointer to the structure.
XAn object of this datatype is referred to as a ``window descriptor.''
XThis declaration is intended to be used as an abstract unit
X(in the manner of the standard I/O library's ``FILE\ *'').
X.IP uwtype_t
XWindow emulation types have the data type ``uwtype_t''.
XThe following emulation types are defined:
X.DS
X.ta 8n 24n 32n
X#define    UWT_ADM31    0    /* ADM-31 cursor-addressible terminal */
X#define    UWT_VT52    1    /* VT52 cursor-addressible terminal */
X#define    UWT_ANSI    2    /* ANSI-compatible terminal */
X#define    UWT_TEK4010    3    /* Tektronix 4010 graphics terminal */
X#define    UWT_FTP    4    /* File transfer */
X#define    UWT_PRINT    5    /* Output to Macintosh printer */
X.DE
X.IP uwopt_t
XWindow options are assigned numbers whose type is ``uwopt_t''.
XThe names of the options are:
X.DS
X.ta 8n 28n 32n
X#define    UWOP_VIS    1    /* visibility */
X#define    UWOP_TYPE    2    /* window type */
X#define    UWOP_POS    3    /* window position */
X#define    UWOP_TITLE    4    /* window title */
X#define    UWOP_WSIZE    5    /* window size (in bits) */
X#define    UWOP_TSIZE    8    /* terminal size (row,col) */
X#define    UWOP_TFONTSZ    9    /* small/large font size */
X#define    UWOP_TCLIPB    10    /* clipboard/mouse encoding */
X#define    UWOP_TBELL    11    /* audible, visual bell */
X#define    UWOP_TCURS    12    /* cursor shape */
X.DE
X.IP uwoptcmd_t
XThe window option commands
Xwhich are passed between the Macintosh and the host
Xhave type ``uwoptcmd_t''.
XThese commands are:
X.DS
X.ta 8n 24n 32n
X#define    UWOC_SET    0        /* set value of option */
X#define    UWOC_ASK    2        /* ask for value of option */
X#define    UWOC_DO    4        /* report changes in value */
X#define    UWOC_DONT    5        /* don't report changes */
X#define    UWOC_WILL    6        /* will report changes */
X#define    UWOC_WONT    7        /* won't report changes */
X.DE
X.IP "union uwoptval"
XWhen a function requires a window option value as an argument,
Xthe value of the window option is placed into a
Xunion declared as ``union uwoptval''.
XThe address of this union is passed to the function.
XThis union is declared as follows:
X.DS
X.ta 8n 16n 24n
Xunion uwoptval {
X    unsigned char    uwov_1bit;
X    unsigned char    uwov_2bit;
X    unsigned char    uwov_6bit;
X    unsigned short    uwov_12bit;
X    struct {
X        unsigned short v,h;
X    }        uwov_point;
X    char        uwov_string[256];
X};
X.DE
XThe union member used for a particular option
Xdepends upon the option number.
XAt present,
Xthe types of the window options and
Xcorresponding union members are:
X.DS
X.ta 1i
Xvisibility    uwov_1bit
Xtype    uwov_6bit
Xposition    uwov_point
Xtitle        uwov_string (null terminated)
Xbit size    uwov_point
Xtty size    uwov_point
Xfont size    uwov_1bit
Xclipboard    uwov_1bit
Xbell        uwov_2bit
Xcursor type    uwov_1bit
X.DE
X.IP "uwerr_t"
XWhen a library routine returns an error indication,
Xfurther information about the type of error can be
Xobtained from the global variable ``uwerrno''.
X(Depending upon the type of error,
Xthe external variable ``errno'' may also contain
Xpertinent information.)
X\*(uw error numbers have type ``uwerr_t'',
Xand are defined as follows:
X.DS
X.ta 8n 24n 32n
X#define    UWE_NONE    0    /* no error */
X#define    UWE_ERRNO    1    /* system call error, consult errno */
X#define    UWE_NXTYPE    2    /* nonexistent window type */
X#define    UWE_DUPID    3    /* window ID duplicated (in use) */
X#define    UWE_NOTIMPL    4    /* operation not implemented yet */
X#define    UWE_NXSERV    5    /* non-existent server */
X#define    UWE_NOMEM    6    /* unable to allocate required memory */
X#define    UWE_INVAL    7    /* invalid argument to function */
X#define    UWE_NOCTL    8    /* no control file descriptor */
X.DE
X.SH
XInternal Window Interface
X.PP
XWhen an internal window is created by an external process,
Xa UNIX-domain datagram is sent to the server.
XThis datagram contains
X(as ``access rights'')
Xa file descriptor for the ``master'' side of a pseudo-terminal.
XThe server assumes that the external process
Xhas started some program on the ``slave'' side of the pseudo-terminal.
XAfter sending the datagram,
Xthe sender has no direct handle to manipulate
Xthe window.
XIt has,
Xin effect,
Xrelinquished all control.
X(It should close the master side of the pseudo-terminal
Xafter sending the datagram.)
XTo provide some additional flexibility,
Xit is possible to change the value of a window option
Xfor any window
X(even ``external'' windows)
Xif the window's unique ID is known.
XThe creator of the window has no special privileges
Xin this regard.
X.LP
X[One thing which the internal window routines
Xin the \*(uw library completely ignore
Xis the fact that datagrams are not guaranteed to be reliable.
XUNIX-domain datagrams almost always seem to work,
Xbut they can fail.
XIn the author's experience this has never been a problem,
Xbut let the user beware.]
X.LP
XThe following routines are available:
X.IP uw_fork 1i
XThis routine is similar in concept to the system call ``fork''.
XIt creates a new process
Xand returns twice \(em
Xonce in the parent and once in the child.
XIn addition to creating a new process,
X``uw_fork'' also arranges for the new process to be
Xassociated with an internal window.
XIt opens a pseudo-terminal,
Xredirects the child's standard input,
Xstandard output,
Xand standard error,
Xand sends a UNIX-domain datagram to the \*(uw server.
XIt returns the unique ID associated with the window
Xin the parent,
Xand returns 0 in the child.
X(\(mi1 is returned if the routine fails.)
X.DS
Xuwid_t uw_fork(uwtype_t wtype, int *pidp);
X.DE
XThe first argument specifies the type of the new window.
XIf the second argument to ``uw_fork'' is a non-NULL pointer,
Xthe process-ID of the child will be stored at that address
Xin the parent process.
X(In the child, ``*pidp'' will be zero.)
X.IP uw_cmd
XThis routine builds upon the functionality of the ``uw_fork'' routine.
XIt creates a new window with ``uw_fork''
Xand then executes a specified command.
XIt takes the window type,
Xthe name of an executable file,
Xand an argument list
Xas parameters;
Xit uses these as arguments to ``uw_fork''
Xand the C library routine ``execvp''.
XIt returns the window ID number to its caller:
X.DS
Xuwid_t uw_cmd(uwtype_t wtype, char *file, char **argv);
X.DE
X(\(mi1 is returned if the routine fails.)
X.IP uw_shell
X``uw_shell'' is similar to ``uw_cmd'' except that it
Xexecutes an arbitrary shell command:
X.DS
Xuwid_t uw_shell(uwtype_t wtype, char *cmd);
X.DE
X(\(mi1 is returned if the routine fails.)
XBy default the Bourne shell is used;
Xhowever,
Xthe shell may be changed by patching the global variable ``uwshellname''.
X.DS
Xchar *uwshellname = "/bin/sh";
X.DE
X.IP uw_rsetopt
XThis routine changes the value of a window option
Xfor an existing window
X(named as a window ID).
XThe window may be either internal or external.
XThe specified window option is set to a desired value.
XZero is returned if the appropriate UNIX-domain message
Xwas successfully sent;
X\(mi1 is returned if the operation failed.
X(Since ``uw_rsetopt'' does not receive a reply from the server,
Xit is unable to determine whether or not the command ``succeeded''.
XRather,
Xit returns zero if the command was successfully transmitted.)
X.DS
Xint uw_rsetopt(uwid_t uwid, uwopt_t optnum, union uwoptval *optval);
X.DE
X``optval'' points to a ``union uwoptval'' structure
X(described above)
Xin which the member corresponding to ``optnum''
Xhas been initialized.
X.IP "uw_perror"
XWhen an error is reported by a \*(uw library routine,
Xthe cause of the error is saved in the external variable
X``uwerrno''.
XIf the error was UWE_ERRNO,
Xthe standard external variable ``errno''
Xwill also be meaningful.
X(The routines which operate upon external windows,
Xdescribed in the following section,
Xalso save this information in the window descriptor.)
XThe routine ``uw_perror'' may be used to decode and print
Xerror messages:
X.DS
Xvoid uw_perror(char *usermesg, uwerr_t uwerr, int err)
X.DE
Xwhere ``usermesg'' is a pointer to a user-specified string,
X``uwerr'' is the \*(uw error code
X(usually ``uwerrno''),
Xand ``err'' is the system call error code
X(usually ``errno'').
X[System call error numbers are defined in ``/usr/include/errno.h''.]
X.sp
XThe \*(uw error messages may also be accessed directly.
XTwo external variables aid in user-formatted error messages:
X.DS
Xextern char *uwerrlist[];
Xextern unsigned uwnerr;
X.DE
XIf the error number is greater than or equal to ``uwnerr'',
Xno error message string exists.
X(This ``cannot happen.'')
XOtherwise,
Xthe error message string is obtained by indexing into
X``uwerrlist''.
X.PP
XThe preceeding routines are sufficient to implement
Xa (simplified) version of the ``uwtool'' program,
Xwhich creates a new
X(internal)
Xwindow running a specified command:
X.DS
X.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n
X/*
X *      uwtool
X *
X * Copyright 1986 by John D. Bruner.  All rights reserved.  Permission to
X * copy this program is given provided that the copy is not sold and that
X * this copyright notice is included.
X */
X#include <strings.h>
X#include "uwlib.h"
X
Xmain(argc, argv)
Xint argc;
Xchar **argv;
X{
X        register uwid_t uwid;
X        register char *fname, *term;
X    register wtype_t wtype;
X        char *av[2];
X        union uwoptval optval;
X        extern int errno;
X        extern char *getenv();
X
X        /*
X         * If called with no arguments, create a new window using the
X         * current shell according to the SHELL environment variable
X         * (or "/bin/sh" if that doesn't exist).  If called with
X         * arguments, argv[1] through argv[argc\-1] are the arguments
X         * to the command.
X         */
X        if (argc == 1) {
X                if ((fname = getenv("SHELL")) == (char *)0)
X                        fname = "/bin/sh";
X                av[0] = fname;
X                av[1] = (char *)0;
X                argv = av;
X        } else
X                fname = *++argv;
X
X    if ((term=getenv("TERM")) != (char *)0)
X        wtype = uw_ttype(term);
X    else
X        wtype = UWT_ADM31;
X
X        if ((uwid = uw_cmd(wtype, fname, argv)) < 0) {
X                (void)strncpy(optval.uwov_string, fname,
X                    sizeof optval.uwov_string);
X                (void)uw_rsetopt(uwid, UWOP_TITLE, &optval);
X                return(0);
X        } else {
X                uw_perror("uwtool", uwerrno, errno);
X                return(1);
X        }
X}
X.DE
XAfter the first part of the function has massaged the argument list,
Xthe ``uw_cmd'' routine creates a new window
Xrunning the command ``fname'' with argument list ``argv''.
XIf the window ID is positive,
Xthe window creation succeeded.
XAfter copying the name of the program into a ``union uwoptval'',
Xthe program calls ``uw_rsetopt'' to set the window title
Xto that string.
XIf the window ID returned by ``uw_cmd'' was \(mi1,
Xthe window creation failed.
XIn this case,
Xthe program calls ``uw_perror'' to report the error.
X.SH
XExternal Window Interface
X.LP
XThe remainder of the \*(uw library routines provide access to
Xexternal windows.
XIn contrast to internal windows,
Xa client process creates an external window
Xby establishing an Internet-domain stream connection
Xto the server and sending the server a ``create window'' command.
XThe server will establish a second stream connection
Xback to the client.
XData is passed between the client and the server on the first connection,
Xwhile control information is passed through the second.
X[Because the server and client communicate through one or
Xtwo stream connection(s)
Xinstead of by sending datagrams,
Xthe unreliability problems noted above for internal windows
Xdo not apply to external windows.]
X.LP
XThe \*(uw library provides mechanisms for creating external windows,
Xkilling them,
Xand manipulating window options.
XWhen a window is created a window descriptor
X(item of type UWIN)
Xis returned;
Xthis is used as an argument to all other external-window routines.
X.LP
XThe following routines are provided:
X.IP "uw_new" 1i
XThis function creates a new external window of the specified type.
XThe calling sequence is:
X.DS
XUWIN uw_new(uwtype_t uwtype, struct sockaddr_in *server)
X.DE
Xwhere ``uwtype'' is the window type
Xand ``server'' is a pointer to a structure specifying
Xthe Internet address of the server.
X(If ``server'' is a NULL pointer,
Xthe server will be determined by examining the
Xenvironment variable ``UW_INET''.)
XIf the window creation succeeded,
X``uw_new'' will return a non-NULL window descriptor;
Xotherwise,
Xit will return NULL, and
Xthe global variables ``uwerrno'' and ``errno''
Xmay be examined to determine the cause of the error.
X.IP "uw_detach"
XThis function ``detaches'' the window from the program
Xso that it no longer is able to perform control operations
Xupon the window.
XThe data connection to the window remains open.
XThis function should be used when the data connection to a window
Xwill be handled by a different process
Xthan the control connection,
X.I e.g.
Xin a child process after a ``fork''.
XIt is strongly recommended that no more than one process
Xhave control access to a window at any one time.
XThe calling sequence is
X.DS
Xuw_detach(UWIN uwin);
X.DE
Xwhere ``uwin'' is the window descriptor.
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
XIf the routine fails,
Xthe error status will be stored in the UWIN data item
Xas well as in the global variables ``uwerrno'' and ``errno''.
X.IP "uw_close"
XThis function closes a window.
XBoth the control and data connections to the window are closed.
XIf multiple processes have access to a window
X(\fIe.g.\fP because of a ``fork''),
Xthen the window will be destroyed when the last connection
Xto it is closed.
XThe calling sequence is
X.DS
Xuw_close(UWIN uwin);
X.DE
Xwhere ``uwin'' is the window descriptor
X.IP "uw_kill"
XAt times it may be desirable for one process to destroy
Xa window even if the window is in use by other processes.
XThe ``uw_kill'' function performs this task.
XThe caller must have control access to the window
X(it must not be ``detached'').
XThe syntax is:
X.DS
Xuw_kill(UWIN uwin);
X.DE
Xwhere ``uwin'' is the window descriptor.
XWhen a window is killed
X(either by ``uw_kill'' or upon command from the Macintosh)
Xthe server closes its data channel.
XAny further attempts to read or write to the window
Xwill produce end-of-file or error conditions,
Xrespectively.
X.IP "uw_optfn"
XIf a process has control access to a window,
Xthen it will periodically receive
Xwindow option messages from the Macintosh client
X(through the server).
XThe \*(uw library receives these messages by enabling
Xasynchronous I/O notification on the control channel
Xand providing a SIGIO signal handler.
XSometimes it is desirable for an external process
Xto field incoming option messages itself.
XTo do so,
Xit must notify the \*(uw library by calling the
Xroutine ``uw_optfn'':
X.DS
Xvoid (*uw_optfn(UWIN uwin, uwopt_t optnum, void (*optfn)())();
X.DE
Xwhere ``uwin'' is the window descriptor,
X``optnum'' is the desired window option,
Xand ``optfn'' is a pointer to a function which
Xwill be called when a message about window option ``optnum''
Xis received.
X``uw_optfn'' returns the previous function.
XTo disable processing for a window option,
Xspecify a NULL pointer for ``optfn''.
XThe user-supplied ``optfn'' is called with the following arguments:
X.DS
X.ta 8n
Xvoid (*optfn)(UWIN uwin, uwopt_t optnum, uwoptcmd_t optcmd,
X    union uwoptval *optval);
X.DE
Xwhere ``uwin'' is the window descriptor,
X``optnum'' is the window option number,
X``optcmd'' is the window option command,
Xand
X(if ``optcmd'' is UWOC_SET)
X``optval'' is a pointer to the new value of the window option.
X.sp
XBecause the \*(uw library provides a signal handler for SIGIO,
Xif other portions of the program wish to catch SIGIO,
Xthen some care must be taken
Xto ensure that all signal handlers are called.
XThe \*(uw library saves the return value from
X``signal'' when it installs its handler.
XIf this is not SIG_IGN,
Xthen that routine will be called after \*(uw has
Xcompleted its signal processing.
XIn a similar fashion,
Xif the calling program establishes a signal handler,
Xit should save the previous value and call the indicated
Xfunction
X(if not SIG_IGN).
XFor example,
Xif the caller uses ``signal'':
X.DS
X.ta 8n 16n
Xoldhandler = signal(SIGIO, myhandler);
X\&...
Xmyhandler(sig, code, scp)
Xint sig, code;
Xstruct sigcontext *scp;
X{
X    ... code to handle exception ...
X    if (oldhandler != SIG_IGN)
X        (*oldhandler)(sig, code, scp);
X}
X.DE
XAlthough from time to time
Xthe Macintosh may ask the server for the current
Xvalue of a window option,
Xthe \*(uw server caches the current value of each
Xwindow option
Xand responds to these inquiries directly.
XTherefore,
Xthe major reason for establishing a window option function
Xwith ``uw_optfn'' is to process incoming UWOC_SET messages,
X.I i.e.
Xmessages from the Macintosh that the value of a window
Xoption has changed.
X.IP "uw_optcmd"
XThis function allows a program with control access to a window
Xto send window option commands.
XThe calling sequence is
X.DS
X.ta 8n
Xuw_optcmd(UWIN uwin, uwopt_t optnum, uwoptcmd_t optcmd,
X    union uwoptval *optval);
X.DE
Xwhere ``uwin'' is the window descriptor,
X``optnum'' is the window option number,
X``optcmd'' is the command,
Xand ``optval'' is a pointer to the option value.
XOf the six window option messages,
Xonly the UWOC_SET,
XUWOC_DO,
Xand UWOC_DONT
Xmessages are very useful.
XUWOC_SET changes the value of a window option
X(``optval'' points to the new value).
XUWOC_DO and UWOC_DONT instruct the Macintosh to
Xreport or not report
X(respectively)
Xwhen a user action changes the value of a window option there.
XWhen it creates a window,
Xthe \*(uw server instructs the Macintosh to report all
Xchanges to window options.
XMost programs will probably not need to issue UWOC_DO or UWOC_DONT commands.
X.IP uw_gvis
XThis function fetches the current visibility
Xstatus of a specified window:
X.DS
Xint uw_gvis(UWIN uwin, int *vp);
X.DE
X``vp'' is a pointer to an integer where the visibility status
X(0 or 1 for invisible or visible, respectively)
Xis returned.
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
X.IP uw_svis
XThis function changes the visibility status of a specified window:
X.DS
Xint uw_svis(UWIN uwin, int v);
X.DE
XIf ``v'' is nonzero then the window ``uwin'' will be made visible;
Xotherwise,
Xthe specified window will be made invisible.
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
X.IP uw_gpos
XThis function returns the current position on the screen
Xof a specified window:
X.DS
X.ta 8n 20n 28n
Xstruct uwpoint {
X    unsigned    uwp_v;    /* vertical component */
X    unsigned    uwp_h;    /* horizontal component */
X};
X
Xint uw_gpos(UWIN uwin, struct uwpoint *pp);
X.DE
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
X.IP uw_spos
XThis function sets the position of a specified window to
Xa desired location:
X.DS
Xint uw_spos(UWIN uwin, struct uwpoint *pp);
X.DE
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
X.IP uw_gwsize
XThis function returns the current size in pixels
Xof a specified window.
XThe size is expressed as a ``uwpoint'',
Xas defined above.
X.DS
Xint uw_gwsize(UWIN uwin, struct uwpoint *pp);
X.DE
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
X.IP uw_swsize
XThis function sets a specified window to a new size:
X.DS
Xint uw_swsize(UWIN uwin, struct uwpoint *pp);
X.DE
X.IP uw_gtitle
XThis function returns the title of a specified window.
XThe title has type ``uwtitle_t'':
X.DS
Xtypedef char uwtitle_t[256];
X
Xint uw_gtitle(UWIN uwin, uwtitle_t ttl);
X.DE
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
X.IP uw_stitle
XThis function sets the title of a specified window:
X.DS
Xint uw_stitle(UWIN uwin, uwtitle_t ttl);
X.DE
X.IP uw_gtype
XThis function returns the type of a specified window:
X.DS
Xint uw_gtype(UWIN uwin, uwtype_t *tp);
X.DE
X``tp'' points to a variable which receives the window type.
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
X.IP uw_stype
XThis function sets the type of a specified window:
X.DS
Xint uw_stype(UWIN uwin, uwtype_t t);
X.DE
X``t'' is the new window type.
XZero is returned for success,
Xwhile \(mi1 is returned for failure.
X.IP "UW_DATAFD"
XThis macro extracts the file descriptor for the data connection
Xfrom a window descriptor:
X.DS
Xint UW_DATAFD(UWIN uwin);
X.DE
X.IP "UW_ID"
XThis macro returns the unique window ID associated with a
Xwindow descriptor:
X.DS
Xuwid_t UW_ID(UWIN uwin);
X.DE
X.IP "UW_PERROR"
XWhen the \*(uw library detects an error
Xit always places the error information into the
Xglobal variables ``uwerrno'' and ``errno''.
XIf the error is associated with a valid window descriptor,
Xit will also store the information in the window descriptor.
XThe macro ``UW_PERROR'' is used to print an error message
Xaccording to the error status in a window descriptor:
X.DS
Xvoid UW_PERROR(char *message, UWIN uwin);
X.DE
Xwhere ``message'' is any user-supplied message and
X``uwin'' is a window descriptor.
X.SH
XCopyright
X.LP
XThis document copyright 1986 by John D. Bruner.
XPermission to copy is given,
Xprovided that the copies are not sold
Xand that this copyright notice is included.
!EOF!doc/uwlib.ms!
echo x - doc/uwproto.ms
sed -e 's/^X//' > doc/uwproto.ms << '!EOF!doc/uwproto.ms!'
X.\" This file should be processed by nroff or troff with the -ms macro set
X.ds uw "\s-2UW\s0
X.de T=
X.ie t .ta 8n 28n 36n 44n
X.el .ta 8n 24n 32n 40n
X..
X.DA September 30, 1986
X.TL
XUW Protocol
X.AU
XJohn D. Bruner
X.SH
XIntroduction
X.PP
X\*(uw is a multiple-window interface to UNIX.\**
X.FS
XUNIX is a registered trademark of American Telephone and Telegraph.
X.br
XMacintosh is a trademark of McIntosh Laboratories,
Xand is licensed to Apple Computer.
X.br
XADM-31 is a trademark of Lear Siegler, Inc.
X.br
XVT52 is a trademark of Digital Equipment Corporation.
X.br
XThe Tektronix 4010 is a graphics terminal manufactured
Xby Tektronix, Inc.
X.FE
XIt comprises two parts:
Xa program which runs on a Macintosh
X(referred to hereafter as ``the client'')
Xand a server program which runs on the UNIX system
X(``the host'').
XThese two programs exchange information by sending
Xdata across a serial communications line.
XThis information consists of data
Xand control and status messages relating to its presentation.
XThe structure of this information is defined by
Xthe \*(uw protocol
Xand is the subject matter of this document.
X.PP
X\*(uw version 3 actually defines three protocols.
XInternally they are assigned numbered,
Xwhile the user interface and documentation refer to them
Xby name.
XThe correspondence is as follows:
X.IP 0
XProtocol 0 is referred to as the ``serverless protocol''
Xor ``single terminal emulator protocol,''
Xbecause its use does not require a server on the host.
X.IP 1
XProtocol 1 is called the ``original \*(uw protocol,''
Xbecause it was the only protocol supported by the first
Xversions of \*(uw
X(versions 1.6 and 2.10).
X.IP 2
XProtocol 2 is called the ``extended \*(uw protocol,''
Xor (sometimes)
Xthe ``\*(uw version 3 protocol.''
X.SH
XProtocol 0 \(em The Serverless Protocol
X.PP
XProtocol 0 is not really a \*(uw protocol at all.
XThe client speaks protocol 0 when it is communicating
Xdirectly with a host,
Xrather than communicating through a server program
Xrunning on the host.
XProtocol 0 is simply 7-bit or 8-bit ASCII.
XEvery byte transmitted in protocol 0 represents itself,
Xwith the possible exception of the two flow-control characters
XXON (control-Q)
Xand
XXOFF (control-S).
XProtocol 0 does not specify whether these characters are
Xto be used for flow-control purposes or for data transmission.
XThe client program on the Macintosh and the host's terminal driver
Xcan be configured to use or ignore flow-control.
X.PP
XProtocol 0 does not specify whether data is transmitted
Xusing 8-bit ASCII or 7-bit ASCII.
XThe user must choose the appropriate transmission format
Xand is reponsible for configuring both the client and the host
Xaccordingly.
X.SH
XProtocol 1 \(em The Original \*(uw Protocol
X.PP
XProtocol 1 was the only protocol which was used in
Xthe first versions of \*(uw
X(versions 1.6 and 2.10).
XIt defines seven ``windows,''
Xeach of which is an independent data stream.
XThrough the transmission of appropriate commands,
Xwindows may be created or destroyed,
Xand data may be directed to a particular window.
XData which is transmitted from the client to the host
Xis referred to as ``input data,''
Xwhile data transmitted from the host to the client
Xis referred to as ``output data.''
XIn each direction a ``current window'' specifies
Xthe recipient of data bytes.
X(For example,
Xif the client wishes to send data to window 4,
Xit first sends a ``select window 4 as input window''
Xcommand and then sends the data.
XUntil the client sends another ``select input window'' command,
Xall further data that it transmits will be received
Xas data for window 4.)
XThe current input window and current output window may be different.
X.PP
XProtocol 1 encodes all information into 7-bit symbols;
Xit does not depend upon the value of the most-significant bit
X(sometimes used for parity purposes).
XCommands are encoded into two bytes:
Xa prefix byte (P1_IAC)
Xand a command byte.
XBit 7
X(the second most-significant bit, octal 0100)
Xspecifies whether the command was sent from the host to the client or
X.I "vice versa:"
X.DS
X.T=
X#define    P1_IAC    0001    /* intrepret following byte as a command */
X#define    P1_DIR    0100    /* command direction: */
X#define    P1_DIR_HTOM    0000    /*    from host to Mac (client) */
X#define    P1_DIR_MTOH    0100    /*    from Mac (client) to host */
X.DE
XThe command's function is encoded into the next three bits.
XThere are only seven commands:
X.DS
X.T=
X#define    P1_FN    0070    /* function code: */
X#define    P1_FN_NEWW    0000    /*    create new window */
X#define    P1_FN_KILLW    0010    /*    kill (destroy) window */
X#define    P1_FN_ISELW    0020    /*    select window for input data */
X#define    P1_FN_OSELW    0030    /*    select window for output data */
X#define    P1_FN_META    0050    /*    add META to next data character */
X#define    P1_FN_CTLCH    0060    /*    send control character as data */
X#define    P1_FN_MAINT    0070    /*    perform "maintenance function" */
X.DE
X(The client does not send the P1_FN_OSELW command;
Xsimilarly,
Xthe host does not send the P1_FN_ISELW command.)
X.PP
XThe least-significant three bits of the command byte
Xspecify an argument to the function.
XFor the ``new window'' (P1_FN_NEWW),
X``kill window'' (P1_FN_KILLW),
X``select input'' (P1_FN_ISELW),
Xand
X``select output'' (P1_FN_OSELW)
Xcommands,
Xthe low three bits specify a window number.
XWindow number zero is not used.
X.PP
XThere are no arguments to the P1_FN_META command.
XIt directs that the next data byte to be transmitted
Xbe considered a ``meta'' character;
X.I i.e.
Xa byte with the most-significant bit
X(octal 0200)
Xset.
X.PP
XThe P1_FN_CTLCH command is used to encode three
Xdata characters which cannot be transmitted directly as data.
XThese are P1_IAC
X(which,
Xif encountered in a transmission,
Xindicates the start of a two-character command),
Xand the flow-control characters XON (021)
Xand XOFF (023).
XThe low-order three bits of the command byte specify the character:
X.DS
X.T=
X#define    P1_CC    7    /* control character specifier: */
X#define    P1_CC_IAC    1    /*    P1_IAC (001) */
X#define    P1_CC_XON    2    /*    XON (021) */
X#define    P1_CC_XOFF    3    /*    XOFF (023) */
X.DE
XA meta-control character is transmitted as a P1_FN_META
Xcommand followed by the appropriate P1_FN_CTLCH command.
XThus,
Xthe octal character 0201 would be transmitted from the
Xhost to the client as
Xa four-byte sequence:
X.DS
X.T=
X0001    (P1_IAC)
X0050    (P1_DIR_HTOM|P1_FN_META)
X0001    (P1_IAC)
X0061    (P1_DIR_HTOM|P1_FN_CTLCH|P1_CC_IAC)
X.DE
XNote that since the host does not send P1_FN_OSELW commands
Xand the client sends commands with the 0100 bit set,
Xthe XON and XOFF control characters will never be sent as command bytes.
X.PP
X``Maintenance functions'' are defined for operations
Xwhich are performed infrequently.
XProtocol 1 defines two maintenance functions:
X.DS
X.T=
X#define    P1_MF    7    /* maintenance functions: */
X#define    P1_MF_ENTRY    0    /*    start up */
X#define    P1_MF_EXIT    7    /*    exit */
X.DE
XThe server sends the P1_MF_ENTRY command when it starts up.
XThe client responds to this by killing any windows that it
Xhas created
X(silently,
X.I i.e.
Xwithout sending P1_FN_KILLW messages to the host).
XEither the client or the server may send the P1_MF_EXIT command
Xto terminate the session.
XWhen the server on the host receives P1_MF_EXIT
Xit terminates;
Xwhen the client receives this command it will reset to a
Xsimple known state.
X.SH
XProtocol 2
X.PP
X\*(uw version 3 provides a number of capabilities
Xthat earlier versions of \*(uw did not.
XAmong these is an expansion of the host-client interaction.
XIn order to accomodate the increased flow of information
Xit was necessary to extend the \*(uw protocol.
XOne of the significant extensions in protocol 2
Xis support for a concept called ``window options.''
XWindow options are described in more detail in the next section.
X.PP
XProtocol 2 is very similar to protocol 1.
XLike protocol 1,
Xprotocol 2 multiplexes a single communications stream
Xamong a maximum of seven windows.
XCommand bytes in protocol 2 are encoded in the same
Xfashion as in protocol 1:
Xa prefix byte
X(P2_IAC)
Xfollowed by a command byte.
XHowever,
Xunlike protocol 1,
Xsome protocol 2 commands require more than one command byte.
X.PP
XThe protocol 2 functions are:
X.DS
X.T=
X#define    P2_FN    0070    /* function code: */
X#define    P2_FN_NEWW    0000    /*    create new window */
X#define    P2_FN_KILLW    0010    /*    kill (destroy) window */
X#define    P2_FN_ISELW    0020    /*    select window for input data */
X#define    P2_FN_OSELW    0030    /*    select window for output data */
X#define    P2_FN_WOPT    0040    /*    communicate window options */
X#define    P2_FN_META    0050    /*    add META to next data character */
X#define    P2_FN_CTLCH    0060    /*    send control character as data */
X#define    P2_FN_MAINT    0070    /*    perform "maintenance function" */
X.DE
XThe P2_FN_KILLW,
XP2_FN_ISELW,
XP2_FN_OSELW,
Xand P2_FN_CTLCH
Xcommands are identical to their counterparts in protocol 1.
X.PP
XThe low-order three bits of the P2_FN_META command
Xrepresent a control character.
X(The low-order three bits of the P1_FN_META command are ignored.)
XThe encoding is identical to the encoding
Xfor the P2_FN_CTLCH command:
X.DS
X.T=
X#define    P2_CC    7    /* control character specifier: */
X#define    P2_CC_IAC    1    /*    P2_IAC (001) */
X#define    P2_CC_XON    2    /*    XON (021) */
X#define    P2_CC_XOFF    3    /*    XOFF (023) */
X.DE
XIf the low-order three bits are zero,
Xthen the P2_FN_META command acts like the P1_FN_META command \(em
Xthe META bit is set in the next data byte.
XIf the low-order three bits are not all zero,
Xthe the P2_FN_META command specifies a META-control character.
XThus, the following are all equivalent:
X.DS
XP1_IAC\ \ P1_FN_META\ \ P1_IAC\ \ P1_FN_CTLCH|P1_CC_IAC
XP2_IAC\ \ P2_FN_META\ \ P2_IAC\ \ P2_FN_CTLCH|P2_CC_IAC
XP2_IAC\ \ P2_FN_META|P2_CC_IAC
X.DE
X.PP
XThe P2_FN_NEWW command differs from the P1_FN_NEWW command
Xin that the protocol 2 command includes an extra byte.
XThe byte following the command byte
Xspecifies the type of the window that is being created.
XThe numeric value of the window type is
Xadded to the ASCII value for a space (blank);
Xhence,
Xthe window type is always represented by a printable character.
XAs an example,
Xif the host wishes to create window 2
Xwith window type 1 (VT-52),
Xthe command sequence is:
X.DS
X.T=
X0001    (P2_IAC)
X0002    (P2_DIR_HTOM|P2_FN_NEWW|2)
X0041    (`!')
X.DE
X.PP
XThe following maintenance functions (P2_FN_MAINT) are defined:
X.DS
X.T=
X#define    P2_MF    7    /* maintenance functions: */
X#define    P2_MF_ENTRY    0    /*    start up */
X#define    P2_MF_ASKPCL    2    /*    request protocol negotiation */
X#define    P2_MF_CANPCL    3    /*    suggest protocol */
X#define    P2_MF_SETPCL    4    /*    set new protocol */
X#define    P2_MF_EXIT    7    /*    exit */
X.DE
XThe representations of
XP2_MF_ENTRY and P2_MF_EXIT are identical to those in protocol 1.
XThe definition of the ``entry'' function is extended
Xslightly in protocol 2.
XIn protocol 1,
Xthe P1_MF_ENTRY command is only sent by the server when it starts up.
XThe client recognizes this command and initializes itself.
XIn protocol 2,
Xthe client is permitted to send the P2_MF_ENTRY command
Xto the server.
XUpon receipt of this command,
Xthe server issues the sequence of P2_FN_NEWW commands
Xand P2_FN_WOPT commands
X(described below)
Xwhich will reconstruct all of the existing windows
Xon the client in their current state.
XThe client uses this command to ``restart'' itself after a crash
Xor other interruption on its end of the connection.
XThe three new maintenance functions are used for protocol negotiation.
XProtocol negotiation is described in detail below.
X.PP
XProtocol 2 defines the new command
XP2_FN_WOPT
Xto transmit window option information
Xbetween the client and server.
XThe P2_FN_WOPT command is followed by a variable-length
Xstring of bytes which encode the window options information.
XThe next section describes the meaning and encoding of
Xwindow option information.
X.SH
XWindow Options
X.PP
XWindow options are window attributes
X(the latter is a more meaningful name).
XFor each window,
Xa maximum of 31 window options may be defined.
XThese are divided into two categories:
Xgeneric and emulation-specific.
XGeneric window options are attributes which are common
Xto all window emulation types.
XEmulation-specific options are meaningful only for some
Xsubset of the available emulation types.
XThe following options are generic:
X.DS
X.T=
X#define    WOG_END    0    /* [used as an endmarker] */
X#define    WOG_VIS    1    /* visibility */
X#define    WOG_TYPE    2    /* window emulation type */
X#define    WOG_POS    3    /* window position on screen */
X#define    WOG_TITLE    4    /* window title */
X#define    WOG_SIZE    5    /* window size (in pixels) */
X#define    WOG_6    6    /* [unassigned, reserved] */
X#define    WOG_7    7    /* [unassigned, reserved] */
X.DE
XTerminal emulations define the following emulation-specific options:
X.DS
X.T=
X#define    WOTTY_SIZE    8    /* (row,col) terminal size */
X#define    WOTTY_FONTSZ    9    /* font size index */
X#define    WOTTY_MOUSE    10    /* mouse interpretation */
X#define    WOTTY_BELL    11    /* audible, visual bell */
X#define    WOTTY_CURSOR    12    /* cursor shape */
X.DE
XWindow option values are structured types composed
Xof the following primitive types:
X.DS
Xfixed-length character vectors
Xvariable-length character strings
Xspecified-width unsigned integer data
X.DE
X.PP
XThe host and client may exchange the following commands
Xregarding window options:
X.DS
X.T=
X#define    WOC_SET    0    /* change value of option */
X#define    WOC_INQUIRE    2    /* ask about current option value */
X#define    WOC_DO    4    /* do report changes to option */
X#define    WOC_DONT    5    /* don't report changes to option */
X#define    WOC_WILL    6    /* will report changes to option */
X#define    WOC_WONT    7    /* won't report changes to option */
X.DE
XThe ``set'' command is sent by either the client or the host
Xto specify the current value of a window option.
XThe ``inquire'' command is sent by either the client or the host
Xwhen it wishes to know the current value of an option.
XThe recipient of an ``inquire'' command responds with a
X``set'' command that specifies the current option value.
X.PP
XThe remaining four window option commands
Xare used by the host
Xto set up automatic reporting by the client
Xwhen the value of a window option changes.
XIf the host wishes to be informed
Xwhen the value of a window option changes
X(\fIe.g.\fP when a window is retitled),
Xit sends a ``do'' command to the client.
XThe client responds to the ``do'' command
Xwith a ``will'' command
Xfollowed immediately by a ``set'' command
X(reporting the current value of the option).
XThereafter,
Xwhenever the value of that option changes
Xthe client will send a ``set'' command with the new value
Xto the host.
XIf the host wishes the client to stop sending
Xthese ``set'' commands,
Xthe host sends the client a ``don't'' command.
XThe client responds with a ``won't'' message.
X.PP
XThe reporting status of generic window options is not affected
Xif the window emulation types changes;
Xhowever,
Xif the emulation type changes,
Xthen reporting for emulation-specific options is ended.
XIf the host wishes the client to continue
Xreporting changes in some emulation-specific window options,
Xit must send the appropriate ``do'' commands.
X.PP
XWindow option commands are grouped together and transmitted
Xcollectively as part of a P2_FN_WOPT command.
XThat is,
Xthe P2_IAC and P2_FN_WOPT command are immediately
Xfollowed by a variable-length string of bytes
Xwhich contain window option commands for one or
Xmore options.
XThe end of a sequence of window option (sub)commands
Xis indicated by a command which specifies window option zero
X(WOG_END).
X.PP
XAll window option commands begin with a one or two
Xbyte command specifier.
XThe one-byte form is called the ``short'' form,
Xwhile the two-byte form is the ``long'' form:
X.DS
X.ta 8n 32n 48n
X#define    WONUM_MIN    1    /* minimum option number */
X#define    WONUM_GENERIC    7    /* maximum generic option number */
X#define    WONUM_SHORT    14    /* maximum short option number */
X#define    WONUM_MAX    31    /* maximum option number */
X#define    WONUM_MASK    (017<<3)    /* mask for extraction */
X#define    WONUM_SENCODE(n)    (((n)&017)<<3)    /* short encoding function */
X#define    WONUM_SDECODE(b)    (((b)>>3)&017)    /* short decoding function */
X#define    WONUM_LPREFIX    (017<<3)    /*long encoding prefix */
X#define    WONUM_LENCODE(n)    ((n)+' ')    /* long encoding function */
X#define    WONUM_LDECODE(c)    (((c)&0177)-' ')    /* long decoding function */
X.DE
XCommands
Xspecifing options whose numbers are in the range WONUM_MIN to WONUM_SHORT
Xmay use the short form.
XIn this case,
Xthe window option number is encoded according to WONUM_SENCODE:
Xit is shifted left by three bits.
XThe command byte consists of a bitwise ``or'' of
Xthe window option command
X(\fIe.g.\fP WOC_INQUIRE)
Xand the encoded short option number.
X.PP
XCommands which specify options whose numbers are greater than WONUM_SHORT
Xmust use the long form.
X(The long form may be used for options whose numbers are less than WONUM_SHORT,
Xbut there is no reason to do so.)
XIn this case,
Xthe first byte contains a bitwise ``or'' of
Xthe window option command
X(\fIe.g.\fP WOC_INQUIRE)
Xand the special prefix WONUM_LPREFIX.
XThe second byte is encoded by WONUM_LENCODE:
Xthe window option number is added to the ASCII code for a space
X(thus this byte is always printable).
X.PP
XAll of the window option commands begin with the
Xone or two byte option command specifier.
XUnlike the other window option commands
X(which use no additional bytes),
Xthe WOC_SET command is followed by encoded data
X(the value of the option).
XOption values are constructed from three primitive
Xdata types
X(as noted above).
X.IP chars 8n
XThe simplest type of data is a fixed-length character vector.
XThis is represented directly.
XThe vector must consist of printable characters.
X[This restriction may be eliminated in the future.
XThe current implementation is able to process non-printable
Xcharacters
X(including XON and XOFF)
Xcorrectly.]
X.IP string
XLike character vectors,
Xstrings have a maximum length.
XHowever,
Xunlike character vectors,
Xstrings may contain non-printing characters.
XAlso,
Xwhile all characters in a character vector are sent,
Xa string may be shorter than its maximum length.
XIt is terminated by a null (000) byte.
X[Hence,
Xa string may not contain an embedded null byte.]
X.IP udata
XThe remaining data type is unsigned integer data.
XThis data has a fixed width measured in bits.
XThe value is encoded in ``little-endian'' fashion
Xinto the low six bits of successive characters.
XThe (octal) 0100 bit of each character is set.
XThe number of characters required to hold an integer
Xvaries from one
X(for data which is one to six bits wide)
Xto six
X(for data which is thirty-two bits wide).
X.PP
XThe window options defined above have arguments as follows
X(all integers are unsigned):
X.IP WOG_VIS 20n
XThis is a 1-bit integer
Xwhich is nonzero iff the window is visible.
X.IP WOG_POS
XThis consists of two 12-bit integers
Xwhich respectively specify the vertical and horizontal
Xoffsets of the window on the client's screen.
X.IP WOG_TITLE
XThis is a string of maximum length 256
Xwhich specifies the window's title.
X.IP WOG_SIZE
XThis consists of two 12-bit integers
Xwhich respectively specify the vertical and horizontal
Xsize of the window on the client's screen
X(in pixels).
X.IP WOTTY_SIZE
XThis consists of two 12-bit integers
Xwhich respectively specify the window size in rows and columns.
X.IP WOTTY_FONTSZ
XThis is a 6-bit integer which is a font size index.
XAt present,
Xit specifies a ``small'' font if zero
Xand a ``large'' font if nonzero.
X.IP WOTTY_MOUSE
XThis is a 1-bit integer
Xwhich is nonzero iff
Xmouse events are to be encoded and sent
Xas data to the host.
X.IP WOTTY_BELL
XThis is a 2-bit integer.
XThe low-order bit is set iff the window should
Xdisplay bells visually;
Xthe other bit is set iff the client should report
Xbells within this window audibly.
X.IP WOTTY_CURSOR
XThis is a 1-bit integer
Xwhich is zero if the window is using a block cursor
Xand nonzero if the window is using an underscore cursor.
X.PP
XOne design decision which the author now regrets
Xis an overloading of the WOTTY_SIZE option.
XIf the host can handle window size changes on pseudo-terminals
X(\fIe.g.\fP 4.3BSD can),
Xthen the client is capable of changing the view size of a window
Xor its actual size,
Xaccording to the user's preference.
XIf the host cannot handle window size changes,
Xthe client does not allow the view size to be changed.
XThe client assumes that the host can handle window size
Xchanges if it receives a WOC_DO command for the WOTTY_SIZE option.
X.SH
XProtocol Negotiation
X.PP
XIt is possible that at some time the versions of a \*(uw server
Xand client will not match;
X.I e.g.
Xa version 2.10 client will be used with a version 3.4 server.
XIt is desirable that such combinations will work ``correctly'' \(em
Xthat the server will communicate with the client using protocol 1
Xrather than trying to use protocol 2.
XIn order to accomplish this,
Xthree new maintenance functions
Xare defined by which the server and client
Xmay negotiate the protocol which is to be used.
XVersion 3 clients and servers recognize these maintenance
Xfunctions in both protocol 1 and protocol 2.
XOlder clients and servers do not recognize these functions
Xat all.
X.PP
XThe protocol negotiation maintenance functions were
Xdescribed above for protocol 2.
XThey are repeated here for protocol 1
X(the encodings are identical):
X.DS
X.T=
X#define    P1_MF_ASKPCL    2    /*    request protocol negotiation */
X#define    P1_MF_CANPCL    3    /*    suggest protocol */
X#define    P1_MF_SETPCL    4    /*    set new protocol */
X.DE
XP1_MF_ASKPCL is encoded in a single command byte
X(following P1_IAC).
XThe P1_MF_CANPCL and P1_MF_SETPCL command bytes are
Xfollowed by an additional byte which names a protocol.
XFor the purposes of protocol negotiation,
Xprotocols 1 and 2 are represented by the ASCII
Xcharacters space and exclamation-mark,
Xrespectively.
X.PP
XThe client and server always start operation in protocol 1.
X(The user may have instructed the client to use protocol 2;
Xnonetheless,
Xit will use protocol 1 until protocol negotiations are complete.)
XWhen the server is started
Xit will send a P1_MF_ENTRY maintenance command to the client.
XIf the client knows about protocol 2 and wishes to use it,
Xit will send a P1_MF_ASKPCL to the server.
XIf the client does not know about protocol 2,
Xit will not send P1_MF_ASKPCL,
Xprotocol negotiation will never be started,
Xand both sides will continue to use protocol 1.
X.PP
XIf the server can support something other than protocol 1
Xit will respond to the P1_MF_ASKPCL with a
XP1_MF_CANPCL which names the most extensive protocol that it can support.
X(At present,
Xthis will be protocol 2;
Xhowever,
Xin the future it might name some other protocol.)
XOld servers,
Xwhich do not recognize P1_MF_ASKPCL,
Xwill ignore the maintenance function.
XThe client will time out after five seconds
Xand retry several times
X(three in the present implementation);
Xif the server never responds
Xthe client will ``give up'' and will
Xcontinue to use protocol 1 indefinitely.
X.PP
XWhen the client receives P1_MF_CANPCL from the server,
Xit will examine the server's suggested protocol.
XIf this protocol is unacceptable to the client,
Xit will respond with its own P1_MF_CANPCL,
Xnaming the most extensive protocol that it can support.
XThe server,
Xupon receipt of this P1_MF_CANPCL,
Xwill examine the client's suggested protocol.
XIf it is unacceptable to the server,
Xit will name the second-most extensive protocol that it can support.
XEach time that the client or server receives a
XP1_MF_CANPCL that names a protocol it cannot support,
Xit will respond with a different,
Xless extensive suggestion of its own.
XSince the number of protocols is finite,
Xeventually someone will suggest protocol 1,
Xwhich both sides are required to support.
X.PP
XWhen the client or server receives a P1_MF_CANPCL
Xthat names a protocol that it
X.I can
Xsupport,
Xit will instruct its counterpart to start using that protocol
Xby sending a P1_MF_SETPCL that names that protocol.
XHenceforth,
Xthe new protocol will be used.
X.PP
XProtocol 2 allows the client to send a P2_MF_ENTRY
Xmaintenance command to the server.
X(This is encoded identically to a P1_MF_ENTRY command.)
XIf the server receives this maintenance command and
Xit is using a protocol other than protocol 1,
Xit will immediately respond with a P1_FN_SETPCL which
Xnames the protocol that it is using.
XIt will then proceed to send ``new window'' and
X(if applicable)
X``window option'' commands to the client
Xto reconstruct the client's current state.
X.SH
XPostscript
X.PP
XThere are a number of obvious problems with the mechanism
Xfor protocol negotiation.
XIt is possible for one party to send a SETPCL
Xcommand and begin listening for input in a new protocol
Xwhile it is still receiving buffered commands in the old protocol
Xfrom the other party.
XIt probably would have been better to have established
Xa ``current protocol'',
Xsimilar to the ``current window'' scheme used for data transfer.
XThis scheme was born out of the desire to allow
Xold servers and clients to work with new ones.
XIt ``works'' if things are relatively quiescent,
Xas they are when the server first starts up
X(before it creates its first window).
X.PP
XThis document is still incomplete.
XAt this time it is more useful as a conceptual guide
Xto the \*(uw protocol
Xthan a definitive reference.
X.SH
XCopyright
X.LP
XThis document copyright 1986 by John D. Bruner.
XPermission to copy is given,
Xprovided that the copies are not sold
Xand that this copyright notice is included.
!EOF!doc/uwproto.ms!
echo x - doc/uw.l
sed -e 's/^X//' > doc/uw.l << '!EOF!doc/uw.l!'
X.TH UW 1 "14 September 1986"
X.UC 4
X.SH NAME
Xuw \- multiple-window Macintosh interface to UNIX
X.SH SYNOPSIS
X.B uw [
X.BI \-f filename
X] [
X.B \-n
X] [
X.B \-s
X]
X.SH DESCRIPTION
X.I Uw
Xis a server program on UNIX that works with the program
X.I uw
Xon the Macintosh.
XIt provides the Macintosh program with access to
Xa maximum of seven independent I/O sessions.
XAn I/O session may be directly associated with a pseudo-terminal
Xor may simply be a communications channel to an external
XUNIX process.
XThe host program multiplexes the input and output onto one RS\-232 line.
X.PP
XMost commonly,
Xsessions will be directly associated with pseudo-terminals.
XThe Macintosh program will emulate
Xa Lear Siegler ADM-31 terminal
X(tset adm31),
Xa DEC VT52,
Xan ANSI-compatible terminal
X(tset ansi or tset aaa-24),
Xand a Tektronix 4010.
XEach window
X(on the Macintosh)
Xhas its own terminal emulation and can be resized at will.
XWindow size changes on the Macintosh can be propagated to the host,
Xor the Macintosh may be directed to display the lower left portion
Xof a larger logical terminal size.
X.PP
XIf the file `.uwrc' exists in the user's home directory,
Xthen
X.I uw
Xwill execute it when starting up.
XIf `.uwrc' is an executable file,
Xit will be directly invoked;
Xotherwise,
Xa shell will be spawned to interpret it.
XAn alternate startup file may be specified using the
X`\-f' flag;
Xalternately,
Xthe `\-n' flag instructs
X.I uw
Xnot to execute any startup file.
X.PP
XThe `\-s' flag prevents
X.I uw
Xfrom listening for UNIX-domain datagrams.
XThus,
Xit prevents external processes from manipulating
Xwindows which they did not create.
XThis may be of value in an environment where
Xother users are considered `hostile.'
X.SH LIMITATIONS
X.I Uw
Xis of no use on unix unless
X.I uw
Xis being run on the Macintosh.
X.br
XIf there is a stream of output in one window there will be lag in
Xrecognizing characters typed in another.
X.SH SEE ALSO
Xuwtool(L), uwtitle(L), uwterm(L)
X.br
X.I uw
XMacintosh documentation
X(`UW \(em A Multiple-Window Interface to UNIX').
X.br
X`The UW Programmer's Library'
X.SH AUTHOR
XProgram written by John Bruner, Lawrence Livermore Laboratories 7/85,11/85,9/86
X.br
XThis document is based upon a document created by
Xby Chris Borton, UC San Diego 11/13/85,
Xedited 9/86 by John Bruner.
X.SH BUGS
XThe `\-s' flag greatly reduces the utility of a `.uwrc' file,
Xsince it prevents
X.I uwtool
Xand
X.I uwtitle
Xfrom working.
!EOF!doc/uw.l!
echo x - doc/uwplot.l
sed -e 's/^X//' > doc/uwplot.l << '!EOF!doc/uwplot.l!'
X.TH UWPLOT 1 "28 April 1987"
X.UC 4
X.SH NAME
Xuwplot \- plot filter for use with UW
X.SH SYNOPSIS
X.B uwplot
X[
X.BI \-t title
X] [
X.BI \-n serveraddr
X]
X.SH DESCRIPTION
X.I Uwplot
Xis a utility program for use with the
X.I uw
Xmultiple-window interface to UNIX.
XIt creates a window,
Xreads plotting instructions from the standard input,
Xand displays the result in the window.
X(The plotting commands are produced by programs
Xwhich use the standard UNIX
X.I plot
Xpackage.)
X.PP
XThe title of the newly-created window may be
Xspecified with the `\-t' option.
XIf this option is omitted,
Xthe title will be the name of the command
Xwhich created it
X(\fIi.e.\fP `uwplot').
X.PP
XNormally
X.I uwplot
Xwill examine the environment for the variable `UW_INET'
Xand will connect to the
X.I uw
Xserver with that address.
XThe `\-n' flag can be used to specify an alternate
Xserver network address.
XThe address should have the form `xxxxxxxx.ddd'
Xwhere `x' is a hexadecimal digit
Xand `d' is a decimal digit.
XThe hexadecimal number is the host's Internet address
Xand the decimal number is the port on which the
Xserver is listening for connections.
X.PP
X`linemod' commands in the plot file are
Xintended to select the color in which the
Xplot is drawn;
Xhowever, this feature is untested.
XThe old-model Quickdraw colors may be
Xspecified by name
X(all lower-case).
XThe standard plot linemod names are mapped to
Xcolors as follows:
X.sp
X.nf
X.ta 1i
Xblack    solid
Xred    shortdashed
Xgreen    dotdashed
Xblue    longdashed
Xyellow    dotted
X.fi
X.PP
XThe present implementation on the Macintosh
Xis a square window with vertical and horizontal
Xdimensions of 300 pixels.
XArcs are not drawn correctly when
Xthe vertical and horizontal scaling factors
Xare unequal.
X.SH LIMITATIONS
X.I Uwterm
Xis of no use on unix unless
Xthe server is running and
X.I uw
Xis being run on the Macintosh.
X.SH SEE ALSO
Xplot(1G), plot(3X), plot(5), uw(L)
X.br
X.I uw
XMacintosh documentation
X(`UW \(em A Multiple-Window Interface to UNIX')
X.br
X`The UW Programmer's Library'
X.SH AUTHOR
XJohn Bruner, Lawrence Livermore National Laboratory, 10/86.
!EOF!doc/uwplot.l!
exit 0
: end of shell archive