Man page for ss (simple socket library)
Iain Lea
iain at norisc.UUCP
Mon Jun 17 20:48:49 AEST 1991
Included below is a man page I have patched together from the
readme, docs etc that came supplied with 'ss' when it was posted
to alt.sources earlier this year.
Enjoy
Iain
--cut here--
.TH SS 3 "Version 1.00"
.SH NAME
ss \- High level library of commands for opening and closing sockets
.SH SYNOPSIS
cc test.c -o test -lss
.SH DESCRIPTION
The Simple Socket library is intended to simplify programming with BSD
sockets, by providing a set of functions which mimic the stdio library.
The basic data type used by the library is the SOCKET, which is analogous
to the stdio FILE data type. Here's a comparison of some code fragments
to illustrate the similarities:
.PP
.nf
Using stdio IO Using Simple Sockets IO
#include <stdio.h> #include <ss.h>
\.\.\. \.\.\.
FILE *fp; SOCKET *sp;
\.\.\. \.\.\.
fp = fopen ("foobar.dat","r"); sp = ConnectSock ("whereami.edu", 4010)
\.\.\. \.\.\.
fgets (buffer, 99, fp); SockGets (buffer, 99, sp);
.fi
.PP
The calls which open and close the sockets themselves hide many of the
gory details associated with using sockets, and provide a more natural
interface. The call to \fIConnectSock()\fP above takes two arguments: a
host name, and a port number. Which is a good deal simpler than the
series of steps one normally takes to establish a connection using
standard system calls.
.PP
This library assumes communications using \fIstreams\fP as opposed to
\fIdatagrams\fP, as they are quite similar to the stdio \fIstreams\fP.
In addition, the library does not use \fIioctl()\fP to modify socket
characteristics. So if you want to make the sockets non blocking (for
example), you'll have to modify the library code. Instead, sockets
should be checked to see if they are ready to be accessed before
trying to read from one.
.PP
Much of the code is based on a version of the stdio library written by
Hubert Bartels.
.SH COMMANDS FOR OPENING AND CLOSING SOCKETS
.TP
\fBSOCKET *ServerSock (int port_number)\fP
Opens a socket on port number 'port_number' on the machine that the
server program is running on. It returns a pointer to an open socket
that clients may use to connect to. If an error occurs it returns
SS_NULL.
.TP
\fBSOCKET *ConnectSock (char *hostname, int port_number)\fP
Allows a client program to connect to a socket on port 'port_number'
on system 'hostname'. It returns a pointer to an open socket which the
client program can use to communicate with the server program. If an
error occurs it returns SS_NULL.
.TP
\fBSOCKET *AcceptSock (SOCKET *server_socket)\fP
Uses the \fIaccept()\fP 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 \fIServerSock()\fP command. It returns
a pointer to an open socket that the server program may use to
communicate with the client program. If an error occurs it returns
SS_NULL. \fIAcceptSock()\fP blocks if there are no connection requests
pending on the server socket.
.TP
\fBint SockClose (SOCKET *sp)\fP
Closes the socket pointed to by 'sp', and performs some internal
housecleaning. It returns 0 if successful, otherwise it returns SS_EOF.
.SH 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:
\fISockPuts()\fP behaves similarly to the stdio function \fIfputs()\fP.
.TP
\fBint SockGetc (SOCKET *sp)\fP
Returns the next character (byte) to be input from the socket 'sp'.
.TP
\fBint SockPutc (char c, SOCKET *sp)\fP
Writes the character 'c' to the socket 'sp'. It returns the character
written.
.TP
\fBint SockWrites (char *string, SOCKET *sp)\fP
This function writes the string 'string' to the socket 'sp'.
It returns 0 if successful, otherwise it returns SS_EOF. It issues the
\fISockFlush()\fP command on 'sp' to force characters in 'string' to be sent.
.TP
\fBint SockPuts (char *string, SOCKET *sp)\fP
This function writes the string 'string' to the socket 'sp'.
It returns the value of the last character written to the buffer if
successful, otherwise it returns SS_EOF. SockPuts buffers it's output.
.TP
\fBchar *SockGets (char *buffer, int nbytes, SOCKET *sp)\fP
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 it returns SS_NULL, otherwise it
returns 'buffer'.
.TP
\fBint SockFlush (SOCKET *sp)\fP
Forces any buffered data in 'sp' to be sent. It returns 0 on success,
otherwise it it returns SS_EOF.
.SH COMMANDS FOR CHECKING THE STATUS OF SOCKETS
These routines are built around the \fIselect()\fP 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 arrival of data from
another machine).
.TP
\fBint SockSelect (double timeval, char *flag)\fP
This function performs a \fIselect()\fP system call on all open sockets.
It returns the number of sockets which \fIselect()\fP found to be
ready. To examine the state of a particular socket after calling
\fISockSelect()\fP you must use one of: \fIIsReadSet()\fP,
\fIIsWriteSet()\fP, or \fIIsExceptSet()\fP. 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 \fIselect()\fP will check for:
.nf
'flag' select() checks for:
"r" socket ready to be read from.
"w" socket ready to be written to.
"e" socket has exceptional condition pending.
.fi
Any combination of the set {r,w,e} may be used in any order. For
example: flag = "er", will cause \fIselect()\fP to check for sockets
ready to be read from or having exceptional conditions pending.
.TP
\fBint IsReadSet (SOCKET *sp)\fP
This function checks socket 'sp' to see if it is ready for
reading. If the socket is ready, the function return 1, otherwise it
returns 0. This function uses information obtained during the last
\fISockSelect()\fP call.
.TP
\fBint IsWriteSet (SOCKET *sp)\fP
This function checks socket 'sp' to see if it is ready for
writing. If the socket is ready, the function return 1, otherwise it
returns 0. This function uses information obtained during the last
\fISockSelect()\fP call.
.TP
\fBint IsExceptSet (SOCKET *sp)\fP
This function checks socket 'sp' to see if an exceptional
condition is pending. If the socket is ready, the function return 1,
otherwise it returns 0. This function uses information obtained
during the last \fISockSelect()\fP call.
.TP
\fBint SockIsRead (SOCKET *sp)\fP
This function combines the \fIselect()\fP system call and \fIFD_ISSET()\fP
macro, and is used to check whether socket 'sp' is ready for reading.
If the socket is ready the functions return 1, otherwise it returns 0.
This function has no timeval parameter (see \fISockSelect()\fP), and
returns immediately.
.TP
\fBint SockIsWrite (SOCKET *sp)\fP
This function combines the \fIselect()\fP system call and \fIFD_ISSET()\fP
macro, and is used to check whether socket 'sp' is ready for writing.
If the socket is ready the functions return 1, otherwise it returns 0.
This function has no timeval parameter (see \fISockSelect()\fP), and
returns immediately.
.SH EXAMPLE
.nf
/*
* SERVER.C example program (cc server.c -o server -lss)
*/
#include <stdio.h>
#include "ss.h"
main (argc, argv)
int argc;
char *argv[];
{
SOCKET *ssp, *csp;
char buffer[100], *result;
char *progname;
int n_read;
progname = argv[0];
/*
* open a socket that clients can connect to.
*/
ssp = ServerSock (4010);
/* Wait for a client to connect. Accept input from the client.
* Close the client socket pointer when the connection is broken
* by the client. Then wait again for another connection.
*/
printf("Use ^C to stop this program\\n");
while (1) {
/*
* Wait for a client to connect.
*/
csp = AcceptSock (ssp);
printf("%s: Accepted a client.\\n", progname);
/* Read whatever the client sends, and print that out to
* the standard output.
*/
while ((result=SockGets(buffer,sizeof(buffer)-1,csp)) != SS_NULL) {
printf ("%s: %s", progname, buffer);
}
/*
* Close the socket.
*/
SockClose (csp);
printf ("%s: Client disconnected.\\n", progname);
}
}
/*
* CLIENT.C example program (cc client.c -o client -lss)
*/
#include <stdio.h>
#include "ss.h"
main ()
{
char *line, buffer[200];
SOCKET *ssp;
/*
* Establish a connection with the server.
*/
ssp = ConnectSock ("whereami.edu", 4010);
if (ssp == SS_NULL)
sserror ("server: ConnectSock()", EXIT);
/*
* Get text from the stdin, and send it to the server program
*/
printf ("Enter text (^d to quit)\\n");
while ((line = gets (buffer)) != NULL) {
sprintf (buffer, "%s\\n", line);
SockWrites (buffer, ssp);
}
printf ("Client finished\\n");
SockClose (ssp);
exit (0);
}
.fi
.SH AUTHORS
Mat Watson (mat at zeus.opt-sci.arizona.edu)
.br
Hubert Bartels (hgb at catalina.opt-sci.arizona.edu)
--cut here--
--
EMAIL iain at norisc.uucp !unido!estevax!norisc!iain
SNAIL Siemens AG, AUT 922C, Postfach 4848, Germany
PHONE +49-911-895-3853
More information about the Alt.sources
mailing list