                    ***** The Socket Stream Library ******

Overview:
--------
The C++ Socket Stream Library was developed with two aims in mind -- to
provide an iostream-based interface for sockets, and to facilitate using
the event driven features provided by BSD-sockets (i.e. SIGURG and SIGIO).

Both have been accomplished.  Included are 3 demo sets.

Also included are an efficient interface to fd_set and select.

Documentation:
-------------
sstream.doc : a document describing the sockbuf and sstream classes much
	      in the manner of the fstream man pages.

select.doc  : a document describing the selset class (which extends fd_sets),
	      an iterator seliter, and 3 routines selwait, seltime, and
	      selpoll which implement select using selsets.

Demos:
-----
There are three sets, each of which show the various ways in which sockets
can be used. Each set consists of a server program and a client program.

server1, client1 : 1 server, 1 client. Usage:
		   server1 <portnumber>
		   client1 <server-host> <portnumber>

		   The client connects to the host, reads a number N  from
		   cin, sends it OOB (out-of-band) to the host. Then
		   it reads N numbers from cin and sends them to the host.

                   The server reads each number, negates it and sends it back
		   to the client (which then displays the number).

		   Demonstrates setting up connections and the implementation
		   of event-driven processing.

server2, client2 : 1 server, multiple clients. Usage
		   server2 <portnumber> <# of clients>
		   client2 <server-host> <portnumber>

                   Client behavior is identical to client1 (it actually
		   uses the same code :)

		   The servers behavior is the same as that of server1,
		   except that it handles multiple connections.

		   Demonstrates the implementation of using event-driven
		   connection acceptance by the server.

server3, client3 : 1 server, multiple clients. Usage
		   server3 <portnumber> <# of clients>
		   client3 <server-host> <portnumber>

                   Client i/o behavior is identical to client1. However
		   instead of sending the number, N, of data to be processed
		   OOB, it sends it as the first (normal) transmission.

		   The server is functionally identical to server2. Instead
		   of using events, it uses a select-loop i.e. a while
		   loop with a select statement.

		   Demonstrates a ``traditional'' server. Also shows the
		   use of the selset routines.

Compiling:
---------
There are two main sources of compilation errors:
1. Libraries not in standard places. If you do not have the CC libraries
   in /usr/local/include/CC change the path in the Makefile
2. SIG_PF expected as second argument to signal(). Change the value of
   SIG in the Makefile.
3. If you are compiling for HPs (and RS/6000), remember to change the value
   of LIB in the Makefile.
4. If you are using g++ and libg++-2.3, uncomment the right lines in the
   Makefile
   

Warning:
-------
These routines have been written and tested successfuly ONLY on a Sun
SparcStation using AT&T cfront 2.0.

They will NOT work with any g++ release prior to 2.0 (and maybe
not even 2.0) since the libraries do not implement iostreams. It has
been tested with g++2.3.3. The event driven code assumes the existence
of SIGIO and SIGURG which are NOT (to the best of my knowledge) part of
SYS V. Even among BSD machines the lower level (ioctl) calls required to
initialize the sockets may vary.

A port to HP-UX 8.0 has been accomplished. CAVEAT: HP-UX delivers SIGIOs
when data is sent from a socket (as well as recv'd) and I do not properly
understand why or how many SIGIOs are delivered per read. Programs which
count on 1 SIGIO per packet recv'd will not work. The iohandler functions,
however, are invoked only on writes.
WARNING: on the HPs remember to alter the Makefile.

A port to the Apollos is in progress. Domain/OS delivers urgent (out-of-band)
messages inline, which makes the job of detecting out-of-band data difficult.

Files:
-----
select.C, select.h:   implements a convenient interface to select. Includes
	              class selset (replaces fd_set), a fast iterator class
		      seliter, and various interfaces to select().
select.doc:           Pseudo-man page describing these.
sstream.C, sstream.h: implements iostreams on top of sockets. Also provides
	              a fairly clean approach to interrupt-driven socket 
		      management.
sstream.doc:          Pseudo-man pages describing the sstream  class & 
		      routines.
server1, client1:     A fairly straight-forward single server/single-client
	              demo.
server2, client2:     Interrupt-driven, multi-client server demo.
server3, client3:     multi-client server,  written using a select-loop.

To Do:
-----
Ensure that all data is read from a socket after a SIGIO on a buffered.
Make sure the right ios::rdstate() bits get set on an error.
Complete port to HP-UX and other BSD machines.

Bug Reports/Author:
-----------------
Mayan Moudgill
(moudgill@cs.cornell.edu)

Acknowledgments:
----------------
Christos Zoulas, for helping me with BSD wizardry when I was stuck, and
for getting me access to a HP.
Rick Carlos, for pointing out a bug in the network vs. host order of 
addresses.
Guilio Prisco, for performing the g++ port.
