LGDCommunicationKit, Release 1.0 (prerelease)
Copyright ã 1993, Looking Glass Design, Inc.
All rights reserved.

Project Manager:	Paul Girone
Original Author: 	Mike Gobbi
Creation Date:	June 28, 1993
$Revision: 1.3 $

Looking Glass Design
Communication Kit

Library:	libLGDcommkit.a

Palette:	LGDCommunicationKit.palette

Header File Directory:	¼include/lgd/commkit/

Import:	commkit.h

Introduction

The Looking Glass Design Communication Kit enables both applications and command-line executables to access the serial ports conveniently.

Kit Classes and Protocols

The LGDCommunicationKit consists of one protocol and two classes.

Protocols

LGDBasicPortProtocol
Adopted by:  LGDSerialPort, LGDAppSerialPort
This protocol defines the basic functionality provided by a serial port object.  Applications which use serial port objects may choose to use only those methods listed in this protocol to ensure that any serial port object may be substituted for the LGDSerialPort without breaking the application.

Classes

LGDSerialPort
Inherits from:  Object
Adopted protocols:  LGDBasicPortProtocol
This object provides basic serial port functionality.  It does not depend on any classes other than Object, so it may be used in any program, even ones which do not use the appkit.

LGDAppSerialPort
Inherits from:  LGDSerialPort : Object
Adopted protocols:  LGDBasicPortProtocol
This object adds some application-style functionality to the serial port object.  Instances of this class may have targets and action set, and the target will be notified whenever there is data available at the serial port.  This class may only be used in application which contain an instance of the Application class and which have a DisplayPostScript context.

Standard Devices

There are several standard unix devices which connect to the serial ports.  On the 68030/040 hardware, the devices come in pairs ± one for serial port A, and another similarly named device for serial port B.  Some computers (68040+) have hardware flow control, while others do not.  The flow-control devices are used when the hardware supports RTS/CTS flow control.

	ttya	ttyb	Used for incoming connections from directly connected terminals without flow control.
	
	ttyfa	ttyfb	Used for incoming connections from directly connected terminals with flow control.
	
	ttyda	ttydb	Used for incoming connections from modems.
	
	ttydfa	ttydfb	Used by systems whose hardware supports RTS/CTS flow control (68040 and later) for incoming connections from modems.
	
	cua	cub	Used for outgoing connections to modems.
	
	cufa	cufb	Used by systems whose hardware supports RTS/CTS flow control (68040 and later) for outgoing connections to modems.

Standard File Locations

There are two sets of files used by the serial port.  These files represent locks and devices.

Device Lock Files

Device lock files are generally found in /usr/spool/uucp/LCK/ and are named by appending ª..LCKº to the device name (ie.  the device cua would have the lock file /usr/spool/uucp/LCK/cua..LCK).  The lock file contains the ID of the process which locked the device, either in octal (default NeXTstep uucp), or in ascii (HoneyDanBer uucp, Taylor uucp, and the LGDCommunicationKit).  This ID can be used to determine whether a lock has gone stale (the locking process has terminated without removing the lock) and should be removed.  This is done automatically by Taylor uucp.

When a process wants to use a device to form a connection immediately, it first checks to see whether there is a lock file corresponding to that device.  If so, the device is in use and cannot be opened.  If the process can be blocked without problem (generally only true of programs run from a nightly script), it may first attempt to open the device.  The process will block until such time as the device is available (possibly after several hours delay).  After opening the device, the process will creat a lock file to let other processes know that the device is taken.

It is possible to open a device without first obtaining a lock, but this is generally considered a very bad idea.  If two processes open a device at once, then unix ªflips a coinº whenever a byte comes in to determine which process will get the data.  Needless to say, this will generally cause the competing programs to fail, since they are not getting the entire input stream.

Device Files

The serial devices are implemented in unix using a file representation.  The device files are generally found in /dev/ and are represented by files with the same name as the device (ie. the device cua would correspond to the unix file /dev/cua).  These files are opened for reading and writing by the LGDSerialPort object to allow two-way communication.

Lock and Device File Permissions

On virtually all unix sites, the device files will be owned by uucp and will have write permission only by the owner.  The device lock directory are also owned by uucp (the lock files are owned by whatever process created them), and will often be writable only by the owner as well.  Thus, in order to write software that uses the serial ports, it will be necessary to do one of three things:

Run programs under root id
This is a very dangerous thing to do, and we strongly reccommend that this solution never be used.

Run programs under uucp id
This is much less dangerous, since the only files that can be accidentally damaged are those owned by uucp.  Still, there are a lot of these files to damage, and this option should only be taken once the program has been thouroughly tested.

Change the file permissions
This creates a potential security hole, since any user could then run a program to listen at the device and grab passwords as they are entered by remote-log-on users.  On the other hand, there is little chance of harming any of the files used by uucp, since only the locks and devices will be writable.  If the group ownership of the devices is changed to a special group (such as spusers) and only group write permission is given, then the compromise to system security can be minimized.