home *** CD-ROM | disk | FTP | other *** search
/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 3 / 3490 < prev    next >
Internet Message Format  |  1991-06-18  |  10KB
  1. From: iain@norisc.UUCP (Iain Lea)
  2. Newsgroups: alt.sources
  3. Subject: Man page for ss (simple socket library)
  4. Message-ID: <345@norisc.UUCP>
  5. Date: 17 Jun 91 10:48:49 GMT
  6.  
  7. Included below is a man page I have patched together from the
  8. readme, docs etc that came supplied with 'ss' when it was posted
  9. to alt.sources earlier this year.
  10.  
  11. Enjoy
  12.  
  13. Iain
  14.  
  15. --cut here--
  16.  
  17. .TH SS 3 "Version 1.00"
  18. .SH NAME
  19. ss \- High level library of commands for opening and closing sockets
  20. .SH SYNOPSIS
  21. cc test.c -o test -lss
  22. .SH DESCRIPTION
  23. The Simple Socket library is intended to simplify programming with BSD
  24. sockets, by providing a set of functions which mimic the stdio library.
  25. The basic data type used by the library is the SOCKET, which is analogous
  26. to the stdio FILE data type.  Here's a comparison of some code fragments
  27. to illustrate the similarities:
  28. .PP
  29. .nf
  30.     Using stdio IO            Using Simple Sockets IO
  31.  
  32.     #include <stdio.h>        #include <ss.h>
  33.     \.\.\.                \.\.\.
  34.     FILE *fp;            SOCKET *sp;
  35.     \.\.\.                \.\.\.
  36.     fp = fopen ("foobar.dat","r");    sp = ConnectSock ("whereami.edu", 4010)
  37.     \.\.\.                \.\.\.
  38.     fgets (buffer, 99, fp);        SockGets (buffer, 99, sp);
  39. .fi
  40. .PP
  41. The calls which open and close the sockets themselves hide many of the
  42. gory details associated with using sockets, and provide a more natural
  43. interface. The call to \fIConnectSock()\fP above takes two arguments: a
  44. host name, and a port number.  Which is a good deal simpler than the
  45. series of steps one normally takes to establish a connection using
  46. standard system calls.
  47. .PP
  48. This library assumes communications using \fIstreams\fP as opposed to
  49. \fIdatagrams\fP, as they are quite similar to the stdio \fIstreams\fP.
  50. In addition, the library does not use \fIioctl()\fP to modify socket
  51. characteristics.  So if you want to make the sockets non blocking (for
  52. example), you'll have to modify the library code. Instead, sockets
  53. should be checked to see if they are ready to be accessed before
  54. trying to read from one.
  55. .PP
  56. Much of the code is based on a version of the stdio library written by
  57. Hubert Bartels.
  58. .SH COMMANDS FOR OPENING AND CLOSING SOCKETS
  59. .TP
  60. \fBSOCKET *ServerSock (int port_number)\fP
  61. Opens a socket on port number 'port_number' on the machine that the
  62. server program is running on. It returns a pointer to an open socket
  63. that clients may use to connect to. If an error occurs it returns
  64. SS_NULL.
  65. .TP
  66. \fBSOCKET *ConnectSock (char *hostname, int port_number)\fP
  67. Allows a client program to connect to a socket on port 'port_number'
  68. on system 'hostname'. It returns a pointer to an open socket which the
  69. client program can use to communicate with the server program. If an
  70. error occurs it returns SS_NULL.
  71. .TP
  72. \fBSOCKET *AcceptSock (SOCKET *server_socket)\fP
  73. Uses the \fIaccept()\fP system call to accept a connect request from a
  74. client. The variable 'server_socket' must point to the socket opened
  75. by the server program using the \fIServerSock()\fP command. It returns 
  76. a pointer to an open socket that the server program may use to
  77. communicate with the client program. If an error occurs it returns
  78. SS_NULL. \fIAcceptSock()\fP blocks if there are no connection requests
  79. pending on the server socket.
  80. .TP
  81. \fBint SockClose (SOCKET *sp)\fP
  82. Closes the socket pointed to by 'sp', and performs some internal
  83. housecleaning. It returns 0 if successful, otherwise it returns SS_EOF.
  84. .SH COMMANDS FOR READING FROM AND WRITING TO SOCKETS
  85. Most of these commands are intended to behave similarly to their stdio
  86. namesakes; replace FILE in your man pages with SOCKET and you'll
  87. have a pretty good description of what these routines do. For example:
  88. \fISockPuts()\fP behaves similarly to the stdio function \fIfputs()\fP.
  89. .TP
  90. \fBint SockGetc (SOCKET *sp)\fP
  91. Returns the next character (byte) to be input from the socket 'sp'.
  92. .TP
  93. \fBint SockPutc (char c, SOCKET *sp)\fP
  94. Writes the character 'c' to the socket 'sp'. It returns the character
  95. written.
  96. .TP
  97. \fBint SockWrites (char *string, SOCKET *sp)\fP
  98. This function writes the string 'string' to the socket 'sp'.
  99. It returns 0 if successful, otherwise it returns SS_EOF. It issues the
  100. \fISockFlush()\fP command on 'sp' to force characters in 'string' to be sent.
  101. .TP
  102. \fBint SockPuts (char *string, SOCKET *sp)\fP
  103. This function writes the string 'string' to the socket 'sp'.
  104. It returns the value of the last character written to the buffer if
  105. successful, otherwise it returns SS_EOF. SockPuts buffers it's output.
  106. .TP
  107. \fBchar *SockGets (char *buffer, int nbytes, SOCKET *sp)\fP
  108. Reads characters from the socket 'sp' into 'buffer' until 'nbytes' have
  109. been read, a newline character is read, or an end of file is reached.
  110. If the end of file is reached it returns SS_NULL, otherwise it
  111. returns 'buffer'.
  112. .TP
  113. \fBint SockFlush (SOCKET *sp)\fP
  114. Forces any buffered data in 'sp' to be sent. It returns 0 on success,
  115.  otherwise it it returns SS_EOF.
  116. .SH COMMANDS FOR CHECKING THE STATUS OF SOCKETS
  117. These routines are built around the \fIselect()\fP system call, and are
  118. used to check for sockets being ready for reading and writing,
  119. or to wait for an event to occur (like the arrival of data from
  120. another machine).
  121. .TP
  122. \fBint SockSelect (double timeval, char *flag)\fP
  123. This function performs a \fIselect()\fP system call on all open sockets.
  124. It returns the number of sockets which \fIselect()\fP found to be
  125. ready.  To examine the state of a particular socket after calling
  126. \fISockSelect()\fP you must use one of: \fIIsReadSet()\fP,
  127. \fIIsWriteSet()\fP, or \fIIsExceptSet()\fP. The select call will block
  128. for 'timeval' seconds if 'timeval' is positive.  If 'timeval' is
  129. negative, then the select call will block indefinitely until at least
  130. one of the open sockets is ready. The variable 'flag' is used to
  131. determine what the \fIselect()\fP will check for:
  132. .nf
  133.     'flag'    select() checks for:
  134.     "r"    socket ready to be read from.
  135.     "w"    socket ready to be written to.
  136.     "e"    socket has exceptional condition pending.
  137. .fi
  138. Any combination of the set {r,w,e} may be used in any order.  For
  139. example: flag = "er", will cause \fIselect()\fP to check for sockets
  140. ready to be read from or having exceptional conditions pending.
  141. .TP
  142. \fBint IsReadSet (SOCKET *sp)\fP
  143. This function checks socket 'sp' to see if it is ready for
  144. reading. If the socket is ready, the function return 1, otherwise it
  145. returns 0. This function uses information obtained during the last
  146. \fISockSelect()\fP call.
  147. .TP
  148. \fBint IsWriteSet (SOCKET *sp)\fP
  149. This function checks socket 'sp' to see if it is ready for
  150. writing. If the socket is ready, the function return 1, otherwise it
  151. returns 0. This function uses information obtained during the last
  152. \fISockSelect()\fP call.
  153. .TP
  154. \fBint IsExceptSet (SOCKET *sp)\fP
  155. This function checks socket 'sp' to see if an exceptional
  156. condition is pending. If the socket is ready, the function return 1,
  157. otherwise it returns 0. This function uses information obtained
  158. during the last \fISockSelect()\fP call.
  159. .TP
  160. \fBint SockIsRead (SOCKET *sp)\fP
  161. This function combines the \fIselect()\fP system call and \fIFD_ISSET()\fP
  162. macro, and is used to check whether socket 'sp' is ready for reading.
  163. If the socket is ready the functions return 1, otherwise it returns 0.
  164. This function has no timeval parameter (see \fISockSelect()\fP), and
  165. returns immediately.
  166. .TP
  167. \fBint SockIsWrite (SOCKET *sp)\fP
  168. This function combines the \fIselect()\fP system call and \fIFD_ISSET()\fP
  169. macro, and is used to check whether socket 'sp' is ready for writing.
  170. If the socket is ready the functions return 1, otherwise it returns 0.
  171. This function has no timeval parameter (see \fISockSelect()\fP), and
  172. returns immediately.
  173. .SH EXAMPLE
  174. .nf
  175. /*
  176.  * SERVER.C example program (cc server.c -o server -lss)
  177.  */
  178.  
  179. #include <stdio.h>
  180. #include "ss.h"
  181.  
  182. main (argc, argv)
  183.     int argc;
  184.     char *argv[];
  185. {
  186.     SOCKET *ssp, *csp;
  187.     char buffer[100], *result;
  188.     char *progname;    
  189.     int n_read;
  190.  
  191.     progname = argv[0];
  192.   
  193.     /*
  194.      * open a socket that clients can connect to.
  195.      */
  196.     ssp = ServerSock (4010);
  197.  
  198.     /* Wait for a client to connect.  Accept input from the client.
  199.      * Close the client socket pointer when the connection is broken
  200.      * by the client.  Then wait again for another connection. 
  201.      */
  202.     printf("Use ^C to stop this program\\n");
  203.  
  204.     while (1) {
  205.         /*
  206.          * Wait for a client to connect.
  207.          */
  208.         csp = AcceptSock (ssp);
  209.  
  210.         printf("%s: Accepted a client.\\n", progname);
  211.  
  212.         /* Read whatever the client sends, and print that out to 
  213.          * the standard output.
  214.          */
  215.         while ((result=SockGets(buffer,sizeof(buffer)-1,csp)) != SS_NULL) {
  216.             printf ("%s: %s", progname, buffer);
  217.         }
  218.  
  219.         /*
  220.          * Close the socket.
  221.          */
  222.         SockClose (csp);
  223.         printf ("%s: Client disconnected.\\n", progname);
  224.     }
  225. }
  226.  
  227. /*
  228.  * CLIENT.C example program (cc client.c -o client -lss)
  229.  */
  230.  
  231. #include <stdio.h>
  232. #include "ss.h"
  233.  
  234. main ()
  235. {
  236.     char *line, buffer[200];
  237.     SOCKET *ssp;
  238.  
  239.     /*
  240.      * Establish a connection with the server.
  241.      */
  242.     ssp = ConnectSock ("whereami.edu", 4010);
  243.     if (ssp == SS_NULL)
  244.         sserror ("server: ConnectSock()", EXIT);
  245.  
  246.     /*
  247.      * Get text from the stdin, and send it to the server program 
  248.      */
  249.     printf ("Enter text (^d to quit)\\n");
  250.     while ((line = gets (buffer)) != NULL) {
  251.         sprintf (buffer, "%s\\n", line);
  252.         SockWrites (buffer, ssp);
  253.     }
  254.     printf ("Client finished\\n");
  255.     SockClose (ssp);
  256.     exit (0);
  257. }
  258. .fi
  259. .SH AUTHORS
  260. Mat Watson (mat@zeus.opt-sci.arizona.edu)
  261. .br
  262. Hubert Bartels (hgb@catalina.opt-sci.arizona.edu)
  263. --cut here--
  264.  
  265. --
  266. EMAIL  iain@norisc.uucp  !unido!estevax!norisc!iain
  267. SNAIL  Siemens AG, AUT 922C, Postfach 4848, Germany
  268. PHONE  +49-911-895-3853
  269.