Path: utzoo!utgpu!cs.utexas.edu!sdd.hp.com!caen!ox.com!math.fu-berlin.de!unido!estevax!norisc!iain From: iain@norisc.UUCP (Iain Lea) Newsgroups: alt.sources Subject: Man page for ss (simple socket library) Message-ID: <345@norisc.UUCP> Date: 17 Jun 91 10:48:49 GMT Sender: iain@norisc.UUCP (Iain Lea) Organization: Siemens AG AUT 92 Germany Lines: 262 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 #include \.\.\. \.\.\. 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 #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 #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@zeus.opt-sci.arizona.edu) .br Hubert Bartels (hgb@catalina.opt-sci.arizona.edu) --cut here-- -- EMAIL iain@norisc.uucp !unido!estevax!norisc!iain SNAIL Siemens AG, AUT 922C, Postfach 4848, Germany PHONE +49-911-895-3853