######## Commands for opening and closing sockets ###########

Socket * ServerSock( int port_number )

Opens a socket on port number 'port_number' on the machine that the
server program is running on.  Returns a pointer to an open socket
that clients may use to connect to. If an error occurs, SeverSock
returns SS_NULL.

SOCKET * ConnectSock( char * hostname, int port_number )

Allows a client program to connect to a socket on port 'port_number'
on system 'hostname'.  Returns a pointer to an open socket which the
client program can use to communicate with the server program.  If the
command fails for any reason, it returns SS_NULL.

SOCKET * AcceptSock( SOCKET * server_socket )

Uses the accept() system call to accept a connect request from a
client.  The variable 'server_socket' must point to the socket opened
by the server program using the ServerSock() command.  Returns a
pointer to an open socket that the server program may use to
communicate with the client program.  AcceptSock() blocks if there are
no connection requests pending on the server socket. If this command
fails for any reason, it returns SS_NULL.

int SockClose( SOCKET * sp)

Closes the socket pointed to by 'sp', and performs some internal
housecleaning.  Returns 0 if successful, otherwise returns SS_EOF.

######## Commands for reading from and writing to sockets ########
Most of these commands are intended to behave similarly to their stdio
namesakes; replace FILE in your man pages with SOCKET and you'll
have a pretty good description of what these routines do.  For example:
SockPuts() behaves similarly to the stdio function fputs().

int SockGetc( SOCKET * sp )

Returns the next character (byte) to be input from the socket 'sp'.

int SockPutc( char c, SOCKET * sp )

Writes the character 'c' to the socket 'sp'.  Returns the character
written.

int SockWrites( char * string, SOCKET * sp )
int SockPuts( char * string, SOCKET * sp )

These functions write the string 'string' to the socket 'sp'.
SockPuts returns the value of the last character written to the buffer
if successful, otherwise it returns SS_EOF. SockWrites returns 0 if
successful, otherwise returns SS_EOF.  SockPuts buffers it's output,
while SockWrites issues the SockFlush() command on 'sp' to force
characters in 'string' to be sent.

char * SockGets( char * buffer, int nbytes, SOCKET * sp )

Reads characters from the socket 'sp' into 'buffer' until nbytes have
been read, a newline character is read, or an end of file is reached.
If the end of file is reached SockGets returns SS_EOF, otherwise it
returns 'buffer'.

int SockFlush( SOCKET * sp)

Forces any buffered data in 'sp' to be sent.  Returns 0 on success,
and SS_EOF on failure.

################ Checking sockets ###############
These routines are built around the select() system call, and are
used to check for sockets being ready for reading and writing,
or to wait for an event to occur ( like the arival of data from
another machine ).

int SockSelect( double timeval, char * flag )

This function performs a select() system call on all open sockets.
SockSelect() returns the number of sockets which select() found to be
ready.  To examine the state of a particular socket after calling
SockSelect() you must use one of: IsReadSet(), IsWriteSet(), or
IsExceptSet().  The select call will block for 'timeval' seconds if
timeval is positive.  If 'timeval' is negative, then the select call
will block indefinitely until at least one of the open sockets is
ready.  The variable 'flag' is used to determine what the select()
will check for:

 	'flag'		select() checks for
        -----           ------------------
	"r"		socket ready to be read from.
	"w"		socket ready to be written to.
	"e"		socket has exceptional condition pending.

Any combination of the set {r,w,e} may be used in any order.  For
example: flag = "er", will cause select() to check for sockets ready
to be read from or having exceptional conditions pending.

int IsWriteSet( SOCKET * sp )
int IsReadSet( SOCKET * sp )
int IsExceptSet( SOCKET * sp )

These functions check a particular socket to see it is ready for
reading, writing, or has an exceptional condition pending.  If the
socket is ready, the functions return 1, otherwise they return 0.
These functions use information obtained during the last SockSelect()
call.

int SockIsRead( SOCKET * sp )
int SockIsWrite( SOCKET * sp )

These functions combine the select() system call and FD_ISSET() macro,
and are used to check whether a socket is ready for reading or
writing.  If the socket is ready the functions return 1, otherwise
they return 0.  These functions have no timeval parameter (see
SockSelect()), and return immediately.

