Path: utzoo!mnetor!uunet!husc6!cmcl2!nrl-cmf!ames!pasteur!ucbvax!hplabs!felix!dhw68k!macintosh
From: jdb@mordor.s1.gov (John Bruner)
Newsgroups: comp.sources.mac
Subject: UW v4.2 (part 1 of 9)
Message-ID: <6493@dhw68k.cts.com>
Date: 4 Apr 88 15:13:33 GMT
Sender: macintosh@dhw68k.cts.com
Organization: Lawrence Livermore National Laboratory, S-1 Project
Lines: 1129
Approved: bytebug@dhw68k.cts.com (Roger L. Long)

[UW v4.2 - part 1 of 9]

---
#! /bin/sh
# This is a shell archive, meaning:
# 1. Remove everything above the #! /bin/sh line.
# 2. Save the resulting text in a file.
# 3. Execute the file with /bin/sh (not csh) to create the files:
#	README
#	Makefile
#	doc/uw.l
#	doc/uwlib.ms
# This archive created: Mon Apr  4 07:51:41 1988
# By:	Roger L. Long (macintosh@dhw68k.cts.com)
export PATH; PATH=/bin:$PATH
echo shar: extracting "'README'" '(4003 characters)'
if test -f 'README'
then
	echo shar: will not over-write existing file "'README'"
else
sed 's/^X//' << \SHAR_EOF > 'README'
X			    UW Version 4.2
X			    31 January 1988
X
XThis is version 4.2 of UW, a multiple-window interface to UNIX for
Xthe Macintosh computer.  The distribution for UW consists of two
Xbinary files for the Macintosh (in BinHex 4.0 format) and a number
Xof source files for the (BSD) UNIX server.
X
XThe distribution includes the following directories:
X
X	h	- all UW include files
X	server	- source code for the UW server
X	lib	- source code for the UW programmer's library
X	utility	- source code for miscellaneous utility programs
X	doc	- [nt]roff documentation (-ms and -man formats)
X	hqx	- Macintosh binary files
X	misc	- other things of possible interest
X
XThe two Macintosh files are "uw.hqx", which is the executable binary
Xand "uw.doc.hqx", which is a MacWrite-format document describing the
XMacintosh user interface.
X
XUW was developed alternately on a Sun 3 and 4.3BSD VAX.  It also
Xhas been tested (more briefly) on a Sun 2 (release 2.0), Integrated
XSolutions VME 68020 (release 3.05), and a Pyramid. It depends quite a
Xbit upon BSD-specific features such as interprocess communication and
Xwill not run without modification on a System V UNIX system.
X
XThis distribution, like the version 3.4 distribution, includes
Xmake files for both 4.2BSD and 4.3BSD.  The choice of make files
Xand other configuration options is determined by the top-level
X"Makefile".  Comments in that file describe the configuration options.
X
XA "make install" in the top-level directory will compile and install
Xall of the (UNIX) pieces of the UW distribution.  As distributed,
Xthis will create a link between the directory name "/usr/include/uw"
Xand the "h" subdirectory and will create a "/usr/local/bin/libuw.a"
Xlibrary file.  These two steps allow application program to use
X	#include <uw/uwlib.h>
Xand
X	cc -o xyzzy xyzzy.o -luw
Xfor greater convenience in creating programs that use the UW library.
X
XIf you do not have the "getopt" library routine, you will find the
Xsource in "misc/getopt.c"  This source code was publicly distributed by
XAT&T and is also available in the "mod.sources" archive.  You should
Xcompile it and install it in your machine's "/lib/libc.a"  (Note that
Xsince it uses "strchr", you should compile it on a BSD system with the
Xcommand "cc -O -c getopt.c -Dstrchr=index".)  [Sorry, I can't find a
Xmanual page which I can (legally) include.]  If you can't change
X"libc.a", then you should add it to the makefiles in the "server"
Xand "lib" directories.
X
XVersion 4.2 is primarily a maintenance release.  Because of constraints
Xon the author's time, few things have changed since version 4.1.  Some
Xof the differences are:
X
X    1)	UW v4.2 is compatible with Multifinder.  It understands background
X	events, so it can receive input and update windows even when
X	another application's window is active.
X
X    2)	Some problems relating to keyboard mapping have been fixed.
X	UW recognizes the Control and ESC keys.  The mapping for the
X	numeric keypad still seems to be incomplete.  The author is
X	hampered by the fact that his development machine still has
X	its original 512K Mac keyboard.  (He dislikes the Mac+ and
X	SE keyboards.)
X
X    3)	A new window type -- plot -- has been defined.  This type of
X	window can only be created by the host.  It interprets output
X	in UNIX v7 plot(5) format.
X
X    4)	Windows may use 7, 9, 10, or 12 point fixed-width fonts.
X	UW includes non-Apple-copyrighted Mishawaka fonts for these sizes.
X
XUW is not public domain.  It is copyrighted.  However, permission to
Xcopy UW is given provided that the copies are not sold and that the
Xcopyright notices are retained.
X
XComments about UW can be sent to the author (me) at the following
Xaddresses:
X
X	ARPANET/MILNET:	jdb@mordor.s1.gov
X
X	UUCP:		{lll-crg,decwrl,caip}!mordor!jdb
X
X	U.S. Mail:	John Bruner
X			Lawrence Livermore National Laboratory
X			P.O. Box 5503, L-276
X			Livermore, CA  94550
X
XI try to answer all mail, but sometimes am unable to do so for reasons
Xbeyond my control (e.g. incomplete or incorrect return addresses,
Xfinicky mailers).
SHAR_EOF
if test 4003 -ne "`wc -c < 'README'`"
then
	echo shar: error transmitting "'README'" '(should have been 4003 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'Makefile'" '(2432 characters)'
if test -f 'Makefile'
then
	echo shar: will not over-write existing file "'Makefile'"
else
sed 's/^X//' << \SHAR_EOF > 'Makefile'
X#! /bin/make -f
X#
X#	Makefile for UW version 4.2
X#
X# Specify VERSION 4.3 for 4.3BSD, 4.2 for 4.2BSD (including Sun 3.x)
X#
X# DEFINES is a list of the site-dependent compile-time options:
X# 	-DUTMP		attempt to update "/etc/utmp" (who) file
X# 	-DV7TTYS	V7-format "/etc/ttys" (pre-4.3BSD)
X#	-DSETOWN_BUG	fcntl(fd, F_SETOWN, pgrp) is broken (pre-4.3BSD)
X#	-Dvoid=int	kludge around broken C compilers
X#
X# UTMP specifies that UW should attempt to update the "/etc/utmp" file.
X# On some (foolish) systems this file is world-writeable.  Other
X# installations may wish AFTER CAREFUL EXAMINATION OF THE ISSUES to
X# install the UW server with group write access to the utmp file.
X#
X# V7TTYS should be used for V7-derived systems that do not have 4.3BSD's
X# "/etc/ttys" file.  This includes 4.2BSD and Sun UNIX.  There is no
X# support for USG's "/etc/inittab".
X#
X# SETOWN_BUG should be defined if the fcntl(fd, F_SETOWN, pgrp) system
X# call is broken (as it is in 4.2BSD and Sun 3.0 UNIX).  On those
X# machines the third argument must be negative to specify a process ID
X# and positive to specify a process group.
X#
X# Some C compilers do not understand pointers to void functions.  The
X# common kludge around this problem is to substitute "int" for "void"
X# everywhere.  "lint" doesn't like this, but the program will compile
X# into working code.
X#
XBINDIR	=	/usr/local/bin
XINCDIR	=	/usr/include/uw
XLIBDIR	=	/usr/local/lib
XVERSION	=	4.3
X
XDEFINES	=	-DUTMP
X
XMKFILES	=	server/Makefile lib/Makefile utility/Makefile hqx/Makefile
X
Xall:	DEFINES $(MKFILES)
X	cd server; make
X	cd lib; make
X	cd utility; make
X	cd hqx; make
X
Xdepend:
X	cd server; make depend
X	cd lib; make depend
X	cd utility; make depend
X
Xinstall:	all
X	ln -s `pwd`/h $(INCDIR)
X	install -s server/uw $(BINDIR)/uw
X	install -s utility/uwtool $(BINDIR)/uwtool
X	install -s utility/uwtitle $(BINDIR)/uwtitle
X	install -s utility/uwterm $(BINDIR)/uwterm
X	install -s utility/uwplot $(BINDIR)/uwplot
X	cp lib/libuw.a $(LIBDIR); ranlib $(LIBDIR)/libuw.a
X
Xclean:
X	cd server; make clean
X	cd lib; make clean
X	cd utility; make clean
X
XDEFINES:	Makefile
X	echo "" $(DEFINES) > DEFINES
X
Xserver/Makefile:	Makefile server/Makefile_$(VERSION)
X	cd server; cp Makefile_$(VERSION) Makefile; make depend
X
Xlib/Makefile:	Makefile lib/Makefile_$(VERSION)
X	cd lib; cp Makefile_$(VERSION) Makefile; make depend
X
Xutility/Makefile:	Makefile utility/Makefile_$(VERSION)
X	cd utility; cp Makefile_$(VERSION) Makefile; make depend
SHAR_EOF
if test 2432 -ne "`wc -c < 'Makefile'`"
then
	echo shar: error transmitting "'Makefile'" '(should have been 2432 characters)'
fi
fi # end of overwriting check
if test ! -d doc
then
	echo shar: mkdir doc
	mkdir doc
fi
echo shar: extracting "'doc/uw.l'" '(2391 characters)'
if test -f 'doc/uw.l'
then
	echo shar: will not over-write existing file "'doc/uw.l'"
else
sed 's/^X//' << \SHAR_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.
SHAR_EOF
if test 2391 -ne "`wc -c < 'doc/uw.l'`"
then
	echo shar: error transmitting "'doc/uw.l'" '(should have been 2391 characters)'
fi
fi # end of overwriting check
echo shar: extracting "'doc/uwlib.ms'" '(25462 characters)'
if test -f 'doc/uwlib.ms'
then
	echo shar: will not over-write existing file "'doc/uwlib.ms'"
else
sed 's/^X//' << \SHAR_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.
SHAR_EOF
if test 25462 -ne "`wc -c < 'doc/uwlib.ms'`"
then
	echo shar: error transmitting "'doc/uwlib.ms'" '(should have been 25462 characters)'
fi
fi # end of overwriting check
#	End of shell archive
exit 0
--- end of part 1 ---