Debian Codegraph @

COSMIC/DOC/sockets.tex

raw
1 \documentclass[12pt]{article}
2
3 \title{\textbf{The Simple Sockets Library \\ \normalsize\em Version 6}}
4 \author{Charles E. Campbell, Jr., {\normalsize Ph.D.} \and Terry McRoberts}
5
6 \def\COSMIC{{\small COSMIC}}
7 \def\SSL{{\small SSL}}
8 \def\IRL{{\small IRL}}
9 \def\TCP{{\small TCP/IP }}
10 \def\TradeMark{{\tiny (tm) }}
11
12 \newtheorem{example}{Example}[section]
13
14 \newcommand{\widepage}{
15 \setlength{\topmargin}{0.0in}
16 \setlength{\textheight}{8.75in}
17 \setlength{\footskip}{0.25in}
18 \setlength{\oddsidemargin}{0in}
19 \setlength{\textwidth}{6.5in}
20 }
21 \widepage
22 \renewcommand{\thepage}{}
23
24 \begin{document}
25
26 \maketitle
27
28 \begin{abstract}
29 {
30 The {\em Simple Sockets Library} (\SSL) allows~C~programmers to use
31 interprocess communications via Berkeley sockets simply and quickly.
32 The programmer is able to move information easily between processes
33 on the same or different machines connected via Ethernet \TradeMark and using
34 the \TCP\ protocol. Most of the \SSL's functions resemble C's file i/o
35 functions, so~C~programmers will find the {\SSL} easy to learn.
36 \vspace{1ex}
37
38 The {\SSL} currently runs under various {\small UNIX \TradeMark} machines:
39 {\small IRIX \TradeMark} (Silicon Graphics), SunOS \TradeMark (Sun), Domain O/S
40 \TradeMark (Apollo), Ultrix \TradeMark (Dec), {\small AIX \TradeMark} ({\small
41 IBM}), {\small SCO \TradeMark}, {\small OSF \TradeMark}, and {\small VMS} 5.x
42 \TradeMark, and {\small MS-DOS \TradeMark} (using Borland C++ 5.0).
43 }
44
45 \vspace{.25in}
46 \begin{table}[h]
47 \begin{center}
48 \small
49 {\bf Keywords} \footnotesize
50 \begin{tabular}{ll}
51 Socket Interprocess Communications & Intermachine Communications \\
52 Berkeley Sockets & Ethernet \\
53 {\TCP} & Robotics \\
54 Machine Control &
55 \end{tabular}
56 \end{center}
57 \end{table}
58
59 \end{abstract}
60
61 \titlepage
62 \tableofcontents
63 \newpage
64 \setcounter{page}{1}
65 \renewcommand{\thepage}{\arabic{page}}
66
67 \section{Copyright}
68 \begin{verbatim}
69 Copyright: Copyright (C) 1999-2005 Charles E. Campbell, Jr.
70 Permission is hereby granted to use and distribute this
71 code and documentation, with or without modifications,
72 provided that this copyright notice is copied with
73 it. Like anything else that's free, the Simple Sockets
74 Library is provided *as is* and comes with no warranty
75 of any kind, either expressed or implied. By using
76 this software, you agree that in no event will the
77 copyright holder be liable for any damages resulting
78 from the use of this software.
79 \end{verbatim}
80 \section{Introduction}
81
82 The {\em Simple Sockets Library} (henceforth to be abbreviated as the \SSL)
83 allows~C~programmers to develop systems of cooperating programs using Berkeley
84 streaming Sockets running under the {\TCP} protocol over Ethernet. The
85 {\SSL} provides simple ways to move information between programs running on the
86 same or different machines and does so with little overhead. During
87 experiments with the {\em Sreadbytes} and {\em Swrite} functions, for example,
88 between two machines,~a~$44,000$ bytes/second transfer rate was achieved with
89 4~bytes per packet and over $1,000,000$ bytes/second was achieved with
90 128~bytes per packet. Of course, heavily loaded networks will affect the rate
91 individual users achieve. The {\SSL} provides {\em two-way} communications.
92
93 The {\SSL} was designed to resemble the {\small FILE} i/o system provided
94 by the standard~C~libraries (ie.~fopen, fclose, fputs, etc. map to
95 {\SSL} analogs Sopen, Sclose, Sputs, etc.). Thus,~C~programmers typically
96 find the {\SSL} easy to learn.
97
98 A~good analogy for the {\SSL} refers to the phone system. There are three types
99 of Sockets supported by the {\SSL} that concern the user:~a~{\em server},~a~{\em
100 client}, and an {\em accept} socket. ~A~server is analogous to someone waiting
101 by several phones for~a~call,~a~client is analogous to someone making~a~call,
102 and an accept is analogous to~a~(server) person accepting the call by picking
103 up one of the phones.
104
105 Thus, one must have~a~server for~a~client to make~a~successful connection. The
106 server must in turn accept the connection. Unlike our overworked server
107 person, however, the computer using the {\SSL} is perfectly happy handling
108 multiple ``accept'' Sockets concurrently.
109
110 The {\SSL} itself is provided in three main parts (see Table~\ref{three-parts}).
111 The {\em Library} is composed of~C~functions and the {\em PortMaster} and the
112 {\em Utilities} are self-contained programs.
113
114 \begin{table}[ht]
115 \caption{\bf The Three Parts of the \SSL}
116 \label{three-parts}
117 \begin{description}
118
119 \item[Library] The functions that the users will link to are in the
120 library.
121
122 \item[PortMaster] The PortMaster is~a~d\"aemon program which runs in
123 the background. It allows {\em clients} to connect to {\em servers}
124 using any available ports.
125
126 \item[Utilities] There are several utility programs provided with
127 the \SSL: {\tt sktdbg}, {\tt srmsrvr}, and {\tt spmtable}.
128 \end{description}
129 \end{table}
130
131 The {\SSL} was used at the
132 Intelligent Robotics Laboratory (\IRL) since May, 1991. The software appears
133 to be stable at the current writing and reasonably robust. For example, the
134 PortMaster,~a~background process provided in the {\SSL} distribution, is
135 resistant to hanging (and thereby being unresponsive). It uses {\em
136 Stimeoutwait\/}s (see the Reference Manual) to return to its normal quiescent
137 mode when communications with one of its clients ceases unexpectedly.
138
139 The \IRL\ uses the {\SSL} to control its three robots; its use of the Ethernet
140 is consequently somewhat heavy. Those of you who wish to control machinery or
141 otherwise present~a~heavy load may wish to purchase~a~``bridge'' to isolate
142 your machines from your local network. This isolation will benefit both the
143 you and the network, as the heavy user will not be afflicted with slowdowns due
144 to the network and the network will not be bothered with lots of packets which
145 slows all its users down.
146
147
148 \newpage
149 \section{The Library}
150
151 The user of the {\SSL} accesses it by linking his or her program to~a~{\em
152 library}. ~A~software library is typically~a~single file which consists of some
153 linkage information along with pre-compiled {\em object code}; unfortunately,
154 methods for producing~a~library and linking to it vary from system to system
155 and compiler to compiler. Directions for several systems appear in the Section
156 on Implementation.
157
158 Practically speaking,~a~library is composed of~a~number of pre-compiled C
159 functions to be utilized by the programmer. The calls made available in the
160 {\SSL} are reminiscent of those used by the various file functions in the C
161 language (see Table~\ref{reminiscent}).
162
163 \begin{table}[thb]
164 \begin{center}
165 \caption{Simple Sockets and Related File {\protect\small I/O} Functions}
166 \label{reminiscent}
167 \begin{tabular}{||l|l||} \hline\hline
168 {\em File Function} & {\em Socket Function} \\ \hline
169 fopen & Sopen \\
170 fclose & Sclose \\
171 fread & Sread \\
172 fwrite & Swrite \\
173 fgets & Sgets \\
174 fputs & Sputs \\
175 fprintf & Sprintf \\
176 fscanf & Sscanf \\ \hline\hline
177 \end{tabular}
178 \end{center}
179 \end{table}
180
181 The Sockets library depends upon the {\em PortMaster} running on your host
182 machine. Only one copy of the PortMaster need be running at any time on~a~given
183 machine, and may be started up by anyone by running the {\em Spm} program in
184 the background. On Unix, the {\em Spm} program will put itself into the
185 background. One may determine if your system has~a~PortMaster running by
186 typing {\em spmtable} first -- it will inform you of any existing servers if
187 the PortMaster is up or tell you that the PortMaster is not up otherwise.
188
189 A~new feature of the {\SSL} allows servers to share another machine's PortMaster.
190 Thus, the {\SSL} supports both distributed and centralized socket name to port
191 mapping. If the machine on which~a~server is to run doesn't have~a~PortMaster,
192 such as older {\small MSDOS} machines, then it can ``borrow'' another machine's
193 PortMaster.
194
195 A~program may open~a~server Socket,~a~client Socket, or an accept Socket.
196 Following the phone system analogy, assume that~a~server Socket is opened
197 first. Then,~a~different program may open~a~client Socket which attempts to
198 connect to the server -- it succeeds when the server program ``notices'' that
199 there is~a~connection waiting on the server Socket and then generates an accept
200 Socket. The client Socket can open, however, before the server accepts the
201 client; there just won't be any two-way communication until the server does
202 accept the client.
203
204 \subsection{User Guide}
205
206 Software using~C~must \verb`#include "sockets.h"` and must link to the \SSL.
207 Directions for doing so will vary from system to system and also depend upon
208 where the installer placed the libraries. Please refer to your compiler
209 documentation and the {\SSL} installer to know how to set up library linkage
210 paths and for the include path to the {\em sockets.h} file.
211
212 The software below illustrates some typical Socket code fragments to get a
213 connected socket, assuming that the \verb`sockets.h` file is on your compiler's
214 include search path. If the \verb`sockets.h` file has been placed in a
215 standard system directory (not wise - updates to the compiler may wipe it off!)
216 then you may have to substitute \verb`#include <sockets.h>` for \verb`#include`
217 "sockets.h"` in the following examples.
218
219 \begin{example}~A~server with one accept \\ \label{one-accept}
220 \begin{verbatim}
221 #include "sockets.h"
222 Socket *server;
223 Socket *skt;
224 server= Sopen("servername","s");
225 skt = Saccept(server);
226 ...
227 Sclose(skt);
228 Sclose(server);
229 \end{verbatim}
230 \end{example}
231
232 Note in Example~\ref{one-accept} that the servername is completely up to the
233 programmer to select. Please note that all servers share the same namespace on
234 any given machine, however.
235
236 \begin{example}~A~server with multiple accepts \\ \label{multi-accept}
237 \begin{verbatim}
238 #include "sockets.h"
239 Socket *server=NULL;
240 Socket *skt=NULL;
241 server= Sopen("servername","s");
242 do {
243 skt= Saccept(server);
244 ...
245 Sclose(skt);
246 } while(whatever);
247 Sclose(server);
248 \end{verbatim}
249 \end{example}
250
251 Again, the programmer may select any servername. Note that the {\em accept}
252 Socket (``skt'') is re-used in Example~\ref{multi-accept}. Actually, coding
253 of multiple accept sockets is usually a bit more involved; see \verb`multiskt.c`
254 in the {\small EXAMPLES} directory. I usually set up a doubly-linked list
255 containing a Socket pointer for each such accepted client and put them
256 on the mask (using \verb`Smaskset()`). I can then use \verb`Smaskwait()` or
257 \verb`Smasktimeoutwait()` to wait for any Socket, including the server itself,
258 that needs attention. Upon closing such a Socket, I also use \verb`Smaskunset()`
259 to remove it from the mask and do a double-link deletion.
260
261 \begin{example}~A~client \\ \label{client}
262 \begin{verbatim}
263 #include "sockets.h"
264 Socket *client;
265 while(1) {
266 client= Sopen("serverName","c");
267 if(client) break;
268 sleep(1);
269 }
270 ...
271 Sclose(client);
272 \end{verbatim}
273 \end{example}
274
275 In Example~\ref{client}, the \verb`serverName` may be in the optional form
276 \verb`serverName@machineName`. Without the machine name specification, the
277 PortMaster on the machine that the client is running on will be searched for
278 the server. The \verb`smsrvr.c` and \verb`smclient.c` example programs provided
279 in the {\SSL} distribution give complete illustrations of Examples~\ref{one-accept}
280 and \ref{client}.
281
282 Note that the Sopen() of a client will fail if the server is not already up; in
283 which case, a null pointer is returned. Example~\ref{client} illustrates a
284 probing method (in this case, once a second). Example~\ref{blockingclient}
285 shows an option to have Sopen() block until the requested server is available.
286
287 \begin{example}~A~blocking~until~open~client \\ \label{blockingclient}
288 \begin{verbatim}
289 #include "sockets.h"
290 Socket *client;
291 client= Sopen("serverName","b");
292 ...
293 Sclose(client);
294 \end{verbatim}
295 \end{example}
296
297 In Example~\ref{blockingclient}, the requested server may or may not be up already.
298 If the server is available, a normal client connection is opened. If the server
299 is {\it not} available, then the client will block (wait) until the server
300 is brought up. Internally, the PortMaster places any clients that open using
301 this option on a waiting list when the server is not available. When the server
302 connects to the PortMaster, the PortMaster then checks its waiting list for
303 clients who wish to connect.
304
305 \begin{example} Using Sopenv \\ \label{using-sopenv}
306 \begin{verbatim}
307 #include "sockets.h"
308 Socket *client;
309 while(1) {
310 client= Sopenv("serverName","c","SKTPATH");
311 if(client) break;
312 sleep(1);
313 }
314 ...
315 Sclose(client);
316 \end{verbatim}
317 \end{example}
318
319 The {\SSL} allows the programmer to set up~a~group of machines for making client
320 connections. In Example~\ref{using-sopenv}, the {\SSL} tries to open~a~client
321 to~a~server named \verb`serverName` on any machine on the {\small SKTPATH}.
322 The ``{\small SKTPATH}'' is an environment variable typically of the form
323 \verb`machine1:machine2:machine3`, ie.~a list of machine names separated by
324 colons. This example also shows~a~typical client connection attempt and sleep
325 polling loop.
326
327 A~somewhat larger example is included in the distribution: \verb`multiskt.c`.
328 This example program concurrently accepts multiple clients on~a~single server,
329 reads any messages sent its way from any of its clients, and sends~a~modified
330 version back to the sending client. It uses the {\em Smaskwait} functions to
331 block the multiskt process for friendly multi-tasking. It is~a~useful program
332 to study in conjunction with the Manual below.
333
334 Connected sockets are~a~pre-requisite for any of the {\small I/O} Socket
335 functions described in the next section. Note that the server should have a
336 unique name on any given machine. Servers may have the same name on different
337 machines, although this may be confusing. It is suggested that one use the
338 name of the process (at least as~a~prefix) for that purpose. Note that the
339 only things that one can do with~a~server Socket are: open one, close one,
340 generate an accept Socket with one, and test/block on one (for clients
341 requesting connection). The {\SSL} supports up to $10$ clients concurrently
342 awaiting acceptance on~a~server Socket, although many machines will limit
343 that to $5$ (silently).
344
345 The {\SSL} supports two way communication of data between~a~client and an accept
346 Socket. Since the processes are not likely to be synchronized, often one
347 process must somehow wait until the other process has sent it something. There
348 are two methods to support this under the \SSL: polling and interrupt-driven.
349 The polling method uses~a~lot of {\small CPU} time, but lets the program do
350 other tasks in the meantime. The interrupt-driven approach hangs the process
351 (aka blocks and suspends) until something shows up on the Socket. The
352 Smask{\small XXX} group of functions allows one to hang the process until
353 something shows up on any number of Sockets -- sort of~a~big {\small OR} gate!
354
355 The Smask{\small XXX} alternative to polling also allows the programmer to
356 insert non-socket file descriptors into the mask via Smaskfdset (and to remove
357 them via Smaskunfdset) such as serial ports (ex. open with DEVICE), graphics queues
358 (ex. {\small SGI}s with qgetfd), etc.
359
360
361 \subsection{Reference Manual}
362
363 This section contains~a~description of the functions available in the Socket
364 Library. The {\SSL} returns three types of Sockets:~a~server, client, and an
365 accept Socket. ~A~Socket itself is~a~data structure {\em type} set up by the
366 \verb`sockets.h` header file. The Socket is deliberately used in~a~fashion
367 reminiscent of the use of {\small FILE} pointers so that the~C~user who knows
368 how to read and write~a~file will immediately feel comfortable with reading and
369 writing Sockets.
370
371 \begin{center}
372 \begin{tabular}{||ll|l|l||} \hline\hline
373 {\em Return} & & {\em Function} & {\em Argument} \\
374 {\em Type} & & {\em Name} & {\em List} \\
375 \hline
376 Socket & * & Saccept & (Socket *skt) \\
377 void & & Sclose & (Socket *skt) \\
378 char & * & Sgets & (char *buf, int maxbuf, Socket *skt) \\
379 int & & Smaskfdisset & (int fd) \\
380 void & & Smaskfdset & (int fd) \\
381 fd\_set & & Smaskget & () \\
382 int & & Smaskisset & (Socket *skt) \\
383 void & & Smaskpop & () \\
384 void & & Smaskpush & () \\
385 void & & Smaskset & (Socket *skt) \\
386 int & & Smasktest & () \\
387 void & & Smasktime & (long seconds,long useconds) \\
388 void & & Smaskunset & (Socket *skt) \\
389 void & & Smaskunfdset & (int fd) \\
390 void & & Smaskuse & (fd\_set usermask) \\
391 int & & Smaskwait & () \\
392 Socket & * & Sopen & (char *skthost, char *mode) \\
393 Socket & * & Sopenv & (char *srvrname,char *ctrl,char *envvar) \\
394 int & & Speek & (Socket *skt, char *buf, int buflen) \\
395 unsigned long & & Speeraddr & (Socket *skt) \\
396 char & * & Speername & (Socket *skt) \\
397 void & & Sprintf & (Socket *skt, char *fmt,...) \\
398 char & * & Sprtskt & (Socket *skt) \\
399 void & & Sputs & (char *buf, Socket *skt) \\
400 int & & Sread & (Socket *skt, char *buf, int buflen) \\
401 int & & Sreadbytes & (Socket *skt, char *buf, int buflen) \\
402 int & & Srmsrvr & (char *skthost) \\
403 int & & Sscanf & (Socket *skt, char *fmt, ...) \\
404 int & & Stest & (Socket *skt) \\
405 int & & Stimeoutwait & (Socket *skt,long seconds,long useconds) \\
406 int & & Svprintf & (Socket *skt, char *fmt, void *args) \\
407 int & & Swait & (Socket *skt) \\
408 int & & Swrite & (Socket *skt, char *buf, int buflen) \\
409 \hline\hline
410 \end{tabular}
411 \end{center}
412
413 \begin{description}
414
415 \item[Socket *Saccept(Socket *skt)] \ This function takes~a~server Socket and produces~a~Socket which has
416 accepted~a~connection. This function may be used as often as wanted on the
417 same server Socket! Note that one must have successfully opened~a~server
418 prior to using Saccept to accept connections (see Examples~\ref{one-accept}
419 and \ref{multi-accept}).
420
421 If this operation is unsuccessful, then Saccept will return~a~null Socket
422 pointer.
423
424 \item[void Sclose(Socket *skt)] \ This function closes~a~Socket of any type (server, client, accept). The
425 Sclose function communicates with the local PortMaster whenever~a~server is
426 closed.
427
428 \item[char *Sgets(char *buf, int maxbuf, Socket *skt)] \ This is an I/O function which assumes that one has already opened a
429 connected Socket ({\em skt}). It will attempt to get~a~null-terminated
430 string from the Socket (up to maxbuf characters). This call will block
431 (aka hang, sleep) until~a~string shows up, but otherwise acts much as a
432 fgets() function does.
433
434 If Sgets has~a~socket error, then~a~null pointer is returned. Otherwise,
435 it returns the ``{\em buf}'' pointer.
436
437 \item[int Smaskfdisset(int fd)] \ The Smaskfdisset() function works in conjunction with the Smaskwait()
438 function. After the Smaskwait() function returns, one can use
439 Smaskfdisset(skt) to test if~a~particular file descriptor is read-ready.
440
441 \item[void Smaskfdset(int fd)] \ The Smask{\small XXX} functions use~a~{\it mask} of type {\it fd\_set}
442 internally. Other operations, such as use of~a~serial port under
443 Unix or the {\small\it GL} queue for {\small SGI}'s Irises (see their
444 qgetfd() function) use file descriptors. This function allows one to
445 set up the Smask{\small XXX} mask with one or more of those file
446 descriptors.
447
448 \item[Smask Smaskget()] \ The Smask{\small XXX} functions use~a~{\it mask} of type {\it fd\_set}
449 internally. Other operations, such as use of~a~serial port under
450 Unix, can also be used to set masks. This function provides access to
451 the mask set up by Smaskset. The mate to this function is Smaskuse().
452
453 \item[int Smaskisset(Socket *skt)] \ The Smaskisset() function works in conjunction with the Smaskwait()
454 function. After the Smaskwait() function returns, one can use
455 Smaskisset(skt) to test if~a~particular Socket is read-ready. It is
456 simpler then and thereby faster than Smasktest().
457
458 \item[void Smaskpop()] \ The Smaskpop() function, along with the Smaskpush() function, allows
459 the programmer to manipulate an internal stack of masks. The ``top''
460 mask is the current mask.
461
462 \item[void Smaskpush()] \ The Smaskpush() function, along with the Smaskpop() function, allows
463 the programmer to manipulate an internal stack of masks. The ``top''
464 mask is the current mask.
465
466 \item[void Smaskset(Socket *skt)] \ This function is part of the {\em Smask{\small XXX}} group. Sockets may be
467 set up for Smaskwait'ing one at~a~time. Note that all Sockets are
468 effectively {\small OR}'ed together for blocking; to clear the mask, pass a
469 {\small NULL} Socket pointer to Smaskset: Smaskset((Socket *) {\small
470 NULL});.
471
472 \item[int Smasktest()] \ This function is part of the {\em Smask{\small XXX}} group. The Smasktest
473 function supports polling -- one may determine if anything is on any of the
474 Smaskset Sockets and immediately receive~a~positive integer if there is,
475 ~a~0 if there isn't, and~a~negative number if there's an error.
476
477 \item[void Smasktime(long seconds,long useconds)] \ This function is part of the {\em Smask{\small XXX}} group.
478 Normally Smaskwait will block ``forever'' (well, at least as long as
479 the machine stays up!). However, one can specify~a~time limit -- then
480 Smaskwait will return with~a~value of 0 if the time limit is exceeded. One
481 may specify the time limit in seconds and micro-seconds. To clear the time
482 limit (ie.~restore Smaskwait to waiting forever), pass~a~negative time in
483 either or both arguments to Smasktime. Waiting forever is also set up when
484 both arguments to Smasktime are zero.
485
486 \item[void Smaskunfdset(int fd)] \ This function is part of the {\em Smask{\small XXX}} group.
487 File descriptors may be entered into the mask via the Smaskfdset()
488 function, and this function can remove it from the mask. This function
489 is similar to the Smaskunset() function.
490
491 \item[void Smaskunset(Socket *skt)] \ This function is part of the {\em Smask{\small XXX}} group. Sockets may be
492 removed from the Smaskwait's mask one at~a~time via this function. Like
493 {\em Smaskset},~a~{\em Smaskunset((Socket *) {\small NULL});} will clear
494 the entire mask.
495
496 \item[void Smaskuse(Smask usermask)] \ This function is part of the {\em Smask{\small XXX}} group. The internal
497 {\em mask} in Smask{\small XXX} can be set up by the user via this
498 function. Often, Smaskset will be used to set up an internal mask,
499 Smaskget will be used to obtain the resulting mask, and Smaskuse will
500 be used to apply that mask.
501
502 \item[int Smaskwait()] \ This function is part of the {\em Smask{\small XXX}} group. The {\em
503 Smaskwait} function will block (aka hang) the process until any Socket set
504 via Smaskset has something waiting on it to be read. Note that Sockets set
505 by Smaskset are retained; ie.~they must be explicitly cleared by passing a
506 {\small NULL} Socket pointer to Smaskset.
507
508 Smaskwait returns~a~positive number if something is waiting on a
509 Socket, zero if~a~timeout occurs, and~a~negative number on an error.
510
511 \item[Socket *Sopen(char *skthost, char *mode)] \ This function is the workhorse for opening Sockets. Basically, it can make
512 either~a~server or~a~client depending on the mode.
513
514 \begin{center}
515 \begin{tabular}{|cl|}
516 \hline
517 \multicolumn{1}{|c}{\em Mode} &
518 \multicolumn{1}{c|}{\em Effect} \\
519 \hline
520 {\em s} & open~a~server \\
521 {\em S} & open~a~server but, on failure, retry after using Srmsrvr \\
522 {\em c} & open~a~client \\
523 {\em b} & open~a~blocking~client \\
524 {\em s\verb`###`} & open~a~server with the specified port number \\
525 {\em S\verb`###`} & like {\em S} above, but with the specified port \\
526 {\em c\verb`###`} & open~a~client to~a~server with the specified port \\
527 \hline
528 \end{tabular}
529 \end{center}
530
531 The {\em skthost} is the name of the server. If one is making~a~{\em
532 client} Socket, then one may optionally use the form
533 ``servername@hostname'' for the skthost. The ``@hostname'' form is not
534 necessary for clients to servers that are on the same host as the client,
535 as the default host is the local host. The ``servername@hostname'' form
536 makes no sense for servers, and so, for opening servers, Sopen will ignore
537 any ``@hostname'' portion of skthost.
538
539 The {\em ``S''} mode for opening servers, like the {\em ``s''} mode, will
540 cause Sopen to attempt to open~a~server, but if unsuccessful, Sopen will
541 then use Srmsrvr using the provided skthost and then retry opening the
542 server. In the case of {\em s\verb`###`} or {\em S\verb`###`}, the servers
543 are set up with the \TCP\ option {\small SO\_REUSEADDR}. This option
544 alleviates some of the difficulties associated with re-starting servers
545 with fixed ports.
546
547 If the skthost is null or an empty string (""), the PortMaster is bypassed.
548 One must specify a port number to use in that case. A warning is issued
549 (as well as a null \verb`Socket*`) because that is typically a programming
550 error, not a user error.
551
552 The PortMaster is also always bypassed for clients which specify port
553 number ({\em c\verb`###`}). In the latter case,~a~client connection is
554 immediately attempted to the user-specified port number. If the function
555 is not successful,~a~null Socket pointer is returned.
556
557 If the user-specified server port mode is used with a skthost, the server
558 will be registered with its PortMaster; clients need {\em not} use
559 specified-port mode to connect (ie.~they may set \verb`mode` to \verb`"c"`)
560 so long as they specify the correct name of the server.
561
562 PortMaster sharing (by setting the environment variable \verb`PMSHARE`)
563 causes servers to work with the {\em\small PMSHARE\/}-specified
564 machine's PortMaster. Clients should use the name of the machine that
565 the {\em PortMaster} is on; the eventual connection will be made with the
566 appropriate server program, even though it is running on~a~different
567 machine than the PortMaster it uses. See Example~\ref{pmsharing} for
568 an illustration of how PortMaster sharing works.
569
570 \item[Socket *Sopenv(char *srvrname,char *ctrl,char *envvar)] \ The {\em Sopenv} function is used to open client Sockets, but is formulated
571 to resemble the {\em Sopen} function with one additional argument.
572 Assuming your computer system supports the concept of environment
573 variables, the Sopenv function can use an environment variable of your
574 choice to help it open~a~client. Typically,~a~{\small SKTPATH} environment
575 variable gets set up by the user with~a~colon-separated list of machine
576 names (ex. setenv {\small SKTPATH} ``gryphon:dragon:xorn''). The Sopenv
577 function attempts to open~a~client to~a~server of the given name on the
578 current machine first, and then attempts to do so on each machine in the
579 given sequence. If \verb`env_var` is NULL or~a~null string, then
580 \verb`SKTPATH` will be used instead.
581
582 If successful,~a~Socket pointer is returned, otherwise~a~{\small NULL}
583 Socket pointer is returned. Please see Saccept on how to use servers.
584
585 \item[int Speek(Socket *skt, char *buf, int buflen)] \ The {\em Speek} function behaves like Sread --- up to {\em buflen} bytes,
586 the buffer will be filled by whatever is currently on the Socket. This
587 function does not remove those bytes from the Socket, however, and those
588 bytes will be returned again on subsequent Speek, Sread, etc.\ calls. This
589 function does \underline{not} block (aka hang, sleep).
590
591 It will return EOF on select error, some negative number on recv error,
592 zero if no data is present on the Socket, and~a~positive count of the
593 available bytes otherwise. In the latter case, {\em buf} will have~a~copy
594 of the bytes available.
595
596 {\small MS-DOS}: Speek will only return~a~1 when data is available on
597 the Socket, not the number of bytes available. Furthermore, the buffer
598 {\em buf} will be~a~zero-length string with just~a~null byte.
599
600 \item[unsigned long Speeraddr(Socket *skt)] \ The {\em Speeraddr} function returns the internet address of the
601 peer Socket.
602
603 \item[char *Speername(Socket *skt)] \ The {\em Speername} function returns the name of the peer Socket.
604 Internally, it has three buffers; thus it can be used up to three times
605 in the same printf statement.
606
607 \item[void Sprintf(Socket *skt, char *fmt,...)] \ The {\em Sprintf} function acts in an analogous fashion to fprintf,
608 sprintf, etc, by putting formatted strings, appropriately null byte
609 terminated, through the Socket. Thus, one may use either {\em Sgets} or
610 an appropriate {\em Sscanf} to receive the information.
611
612 \item[char *Sprtskt(Socket *skt)] \ The {\em Sprtskt} function returns~a~string describing the Socket.
613
614 \item[void Sputs(char *buf, Socket *skt)] \ The {\em Sputs} function puts~a~null byte terminated string on the Socket
615 in~a~fashion analogous to fputs.
616
617 \item[int Sread(Socket *skt, char *buf, int buflen)] \ The {\em Sread} function is similar to the {\em read}
618 function in Unix. This function can block (aka hang, sleep) if nothing is
619 on the Socket. Otherwise, it will return up to {\em buflen} bytes in the
620 buffer ``{\em buf}''. This function will return whatever is on the Socket,
621 and doesn't try to insure that buflen bytes are read. It returns the
622 number of bytes read from the Socket.
623
624 On error, an EOF is returned.
625
626 \item[int Sreadbytes(Socket *skt, char *buf, int buflen)] \ The {\em Sreadbytes} function behaves much like Sread, and it too can block
627 (aka hang, sleep) if nothing is on the Socket. However, it will not return
628 until buflen bytes are read from the Socket and placed in ``buf''.
629
630 On error, an EOF is returned.
631
632 \item[int Srmsrvr(char *skthost)] \ The {\em Srmsrvr} function is made available to take care of those
633 situations when {\small skt = Sopen(``servername'',``s'')} fails because
634 the servername has been inadvertently left in the PortMaster's PortTable.
635 This untoward event can happen, for example, when~a~process is
636 aborted/exited without calling Sclose on its server(s). The Srmsrvr
637 function will remove~a~server (or server@host) from the PortMaster's
638 PortTable. Note: it will \underline{not} close the associated Socket, nor
639 free up any Socket memory, and is \underline{not}~a~substitute for Sclose.
640
641 The {\em Srmsrvr} function will return either {\small PM\_OK} (if
642 successful) or {\small PM\_SORRY} (otherwise).
643
644 \item[int Sscanf(Socket *skt, char *fmt, ...)] \ The {\em Sscanf} function acts much the same as sscanf and fscanf, taking
645 format strings and additional arguments in~a~like manner. The arguments
646 Sscanf takes, of course, must all be appropriate pointers. This function
647 will block if insufficient data is available on the socket according to the
648 {\em fmt}.
649
650 The {\em Sscanf} function returns the number of arguments for which it read
651 data, which may be zero or incomplete if~a~socket error occurred.
652 Normally, the returned count should equal the number of arguments with
653 which Sscanf was provided.
654
655 \item[int Stest(Socket *skt)] \ The {\em Stest} function allows one to determine if anything is available
656 on the specified Socket, {\em without blocking}.
657
658 It will return EOF on select error, some negative number on recv error,
659 zero if no data is present on the Socket, and~a~positive count of the
660 available bytes otherwise.
661
662 {\small MS-DOS}: Stest will only return~a~1 when data is available
663 on the Socket, not the number of bytes available.
664
665 \item[int Stimeoutwait(Socket *skt,long seconds,long useconds)] \ The {\em Stimeoutwait} function blocks on the given Socket, but for no
666 longer than the number of seconds plus the number of microseconds specified.
667 The function returns the number of bytes available on the Socket (which may be
668 zero), -1 if there was an error, and -2 on timeout.
669
670 \item[int Svprintf(Socket *skt, char *fmt, void *args)] \ The {\em Svprintf} function reads bytes using~a~printf family format string
671 from the Socket. As each format code is processed, the associated argument
672 is changed in the {\em args} vector. It returns the number of format items
673 processed.
674
675 \item[int Swait(Socket *skt)] \ The {\em Swait} function will block (aka hang, sleep) until the specified
676 Socket has data available.
677
678 It will return EOF on select error, some negative number on recv error,
679 zero if no data is present on the Socket, and~a~positive count of the
680 available bytes otherwise.
681
682 \item[int Swrite(Socket *skt, char *buf, int buflen)] \ The {\em Swrite} function will write {\em buflen} bytes from the {\em buf}
683 buffer onto the specified Socket.
684
685 The function will return~a~count of the number of bytes transmitted through
686 the Socket, which should be equal to {\em buflen}. If the output is less
687 than {\em buflen}, then an error occurred while writing to the Socket.
688
689 \end{description}
690
691
692 \subsection{Hints}
693
694 The {\em Hints} below have been found useful at the Intelligent Robotics
695 Laboratory. They are based on almost a~year's experience with the \SSL.
696
697 \begin{enumerate}
698
699 \item The ``Sscanf'' function is dangerous. It will block until all of
700 the format codes in its {\em fmt} string have been used. If somehow
701 ~a~programmer sends an improper string and Sscanf is used to receive it,
702 then the receiving program will probably hang for quite~a~while.
703 Dr.~Campbell has found that it is somewhat safer to use {\em Sgets} to
704 get an entire string from the Socket and then use {\em sscanf} and
705 {\em stpnxt} to parse it.
706
707 \item Polling is unfriendly to other processes -- it wastes~a~tremendous
708 amount of {\small CPU} time merely querying the Socket(s) to see if
709 anything is awaiting action. The various blocking functions are much
710 better: Swait, Stimeoutwait, Smask{\small XXX}, etc.
711
712 \item Unless your processes will always run on the same kind of machine,
713 portability considerations argue against using Sread and Swrite to move
714 non-character string data around -- ie. floats, doubles, and even ints.
715 Even if the programmer tests out the machines and verifies that (s)he
716 can safely move, say,~a~double around, or even~a~vector of doubles,
717 data structures (\verb`struct XXX { ... }`) may have ``holes'' in them
718 placed there for word or byte alignment reasons. These ``holes'' may
719 not be there (or may be placed differently) by other machines and compilers.
720
721 \item The Srmsrvr function is~a~rather rude function -- there is no
722 ownership check of~a~server. Please use your process name (or your id) as
723 part of your server name so that servers do not clash. Remember: your
724 server's name is in only one ``name space'' shared by all users on your
725 machine.
726
727 \item For those of you who wish to use other services (ex.~serial ports)
728 which can use the {\em select} function provided by \TCP, check out Smaskfdset
729 and its mate, Smaskunfdset.
730
731 \item The \IRL\ has been using~a~leading two character command
732 convention: \verb`tp~L~x~y~z rx ry rz` will tell the ``left'' T3 robot to
733 move to ``x~y~z'' (inches) in space with an orientation of ``rx ry rz''
734 degrees (roll, pitch, yaw). Longer words provide more readability but take
735 up more bandwidth. Experimentally, Dr.~Campbell has found that \TCP
736 can transfer about 10,000 packets per second with up to 128 bytes in a
737 packet. Loaded systems will, of course, achieve less throughput.
738
739 \item It is~a~good idea for clients to inform servers that they are
740 quitting. The \IRL\ has used the following convention: \verb`tq`
741 {\em t\/}ells the server that the messaging client is {\em q\/}uitting.
742 Also,~a~\verb`tQ` tells the server to shut itself down. The server then
743 emits~a~\verb`tq` to all of its clients to inform them that the server is
744 shutting down (except for the one client who issued the shutdown command),
745 and then closes itself down with Sclose.
746
747 \item The server-client relationship is intimately involved with
748 object-oriented messaging -- refer to the literature on object-oriented
749 concepts.
750
751 \item The {\SSL} can be used to support~a~{\em no startup sequencing} paradigm.
752 Typically, clients who attempt to Sopen and fail should go into a
753 poll - sleep loop:
754
755 \begin{example} Client Socket Polling \\ \label{client-polling}
756 \begin{verbatim}
757 skt= Sopen("servername","c");
758 while(!skt) {
759 sleep(1);
760 skt= Sopen("servername","c");
761 }
762 \end{verbatim}
763 \end{example}
764
765 The {\em multiskt.c} program illustrates how servers should be able
766 to accept multiple clients using blocking judiciously.
767
768 This non-sequencing approach allows one to bring up programs which have
769 servers and/or clients without worrying about what comes first. For two
770 programs, this isn't terribly serious, but at the \IRL\ numerous
771 programs providing numerous services are available and sequencing would
772 be~a~nightmare.
773
774 \item As alluded to earlier, clients should tell servers and servers should
775 tell clients when they are going down. The program that is {\em not}
776 quitting should return to an ``awaiting another client (or server)'' mode
777 (ie.~see the preceding item). Thus,~a~troublesome program can be brought
778 down, the programs to which it is communicating will gracefully terminate
779 their connections, and the programmer can then (hopefully) fix the problem.
780 When the program is restarted, the non-sequencing approach will allow the
781 program to seamlessly re-enter into communications with the other software.
782
783 \item When~a~machine is down, and an attempt to connect~a~client Socket using
784 either {\em Sopen\/} directly or {\em Sopenv\/} to~a~server either normally
785 or possibly on that machine, the Sopen will fail but will take an inordinately
786 long time doing so (connection timeout).
787
788 \item When~a~program dies abruptly, connected Sockets appear to {\em select}()
789 to have something on them (select is used by Stest, Smasktest, Swait,
790 Smaskwait, Speek, Stimeoutwait). Hence, functions which normally block
791 (Smaskwait, Swait) no longer block. On computers which can {\small
792 MSG\_PEEK} (Unix, Vms), the Stest, Speek, Sgets, and Sscanf functions will
793 detect this situation and will return an error indication ({\small EOF},
794 {\small NULL} pointer, incomplete argument processed count) to indicate that
795 the Socket has~a~problem (one should then Sclose the affected Socket).
796
797 Furthermore, attempts to write to such dead Sockets may generate
798 {\small SIGPIPE}s on Unix boxes. Unix programmers should write and install
799 signal handlers for {\small SIGPIPE}s.
800
801 \item For multiple concurrent Sockets, one should generate routines for both
802 closing and opening them.
803
804 \begin{example} Client Opening Function \\ \label{client-opening}
805 \begin{verbatim}
806 #include "sockets.h"
807 typedef struct clientlist_str ClientList;
808 struct clientlist_str {
809 Socket *skt;
810 ClientList *nxt,*prv;
811 }
812 ClientList *clhd=NULL;
813 ClientList *cltl=NULL;
814 ...
815 ClientList *openClient(char *srvrname)
816 {
817 Socket *skt;
818 ClientList *clist;
819 while(1) {
820 skt= Sopen(srvrname,"c");
821 if(!skt) sleep(1);
822 }
823 clist= (ClientList *) malloc(sizeof(ClientList));
824 if(cltl) cltl->nxt= clist;
825 else clhd = clist;
826 clist->prv= cltl;
827 clist->nxt= NULL;
828 cltl = clist;
829 Smaskset(skt);
830 clist->skt= skt;
831 return clist;
832 }
833 \end{verbatim}
834 \end{example}
835
836 The \verb`openClient`() function polls once~a~second in attempting to
837 open~a~client Socket. Once it succeeds,~a~ClientList data structure
838 is allocated, double-linked, and~a~pointer to it returned. In addition,
839 the new client Socket is added to the Smask.
840
841 \begin{example} Client Closing Function \\ \label{client-closing}
842 \begin{verbatim}
843 void closeClient(ClientList *clist)
844 {
845 if(clist) {
846 Smaskunset(clist->skt);
847 Sclose(clist->skt);
848 clist->skt= NULL;
849 }
850 }
851 \end{verbatim}
852 \end{example}
853
854 The \verb`closeClient`() function removes the client Socket from the Smask
855 system, closes the Socket, and then sets the skt pointer to NULL to guarantee
856 that the now dead socket won't be inadvertently re-used somehow.
857
858 \item It is usually advisable to use some sort of handshaking protocol between
859 server and client, especially when large data blocks are being moved. The {\TCP} buffers can easily get filled and data get lost otherwise. To facilitate this,
860 the {\SSL} sets sockets up with the {\small TCP\_NODELAY} option so that small
861 packets are moved out across and not collected (collection of small packets
862 normally improves network efficiency since there's less overhead per byte of data).
863
864 \end{enumerate}
865
866 \newpage
867 \section{The PortMaster}
868
869 Servers have names provided by the program which opens them. When~a~server is
870 to be opened, the Sopen function temporarily opens~a~Socket to the PortMaster
871 running on the same machine. The Sopen function then tells the PortMaster the
872 server's {\em name} and the (random) {\em port} assigned to the new server, and
873 then closes down the connection. The PortMaster retains~a~list of all active
874 servers and ports running on its machine.
875
876 A~client is opened using the Sopen function, too. In that case,~a~connection
877 is made to the PortMaster on the machine where the requested server is
878 running. The PortMaster then tells the Sopen function the port number
879 associated with the requested server, and then closes down the temporary
880 connection. The Sopen function then attempts to connect to the server using
881 the given port.
882
883 The server program can use its server Socket to test if any clients are waiting
884 to be connected to it (via the Stest function). If~a~client is waiting, then
885 the server's program can {\em accept} the connection, generating an accept
886 Socket (via Saccept). Once the connection is accepted, the program attempting
887 to open the client Socket will finally receive~a~Socket pointer.
888
889
890 \subsection{Users Guide}
891
892 The PortMaster is probably the simplest program to run: under {\small UNIX},
893 type \verb`Spm &` and under {\small VMS} type \verb`run/detach Spm`. The
894 PortMaster will only allow one copy of itself to run on any given computer. It
895 uses~a~fixed port address ($1750$, now registered with {\small IANA}) and
896 implements~a~table of server names mapping to random ports. Although
897 knowledgeable users could change the PortMaster's fixed port, this is
898 discouraged: hopefully, PortMasters will proliferate across the world and, if
899 they all use the same port on their machines, will be able to communicate with
900 one another. In other words, the {\SSL} will be unable to communicate with
901 other {\SSL} systems which use~a~different port for its PortMaster.
902
903 Since {\small MS-DOS} is not~a~multi-tasking operating system, unlike
904 {\small UNIX}, {\small VMS}, or {\small Amiga-DOS}, one cannot have a
905 PortMaster running in the background --- there is no background. Hence,
906 {\small MS-DOS} programs are currently restricted to using client Sockets only,
907 {\em unless} they can share another machine's PortMaster (see below).
908
909 The PortMaster now supports~a~firewall: one can instruct the PortMaster
910 to restrict access to~a~group of machines by their host addresses. See the
911 section on {\em The PortMaster Firewall} below.
912
913 \subsection{Sharing PortMasters}
914
915 PortMasters can now be {\em shared}. This feature was installed mainly to
916 support {\small MSDOS} -- since it doesn't have~a~background process
917 capability, it cannot run PortMasters. Hence, it is normally restricted to
918 running clients only, because servers normally announce their presence to their
919 host's PortMaster. If the environment variable \verb`PMSHARE` is set to some other
920 machine, that other machine's PortMaster will be used by the host's processes
921 attempting to open servers. From the client's viewpoint, the server appears to
922 be on the machine with the PortMaster -- the client doesn't need to know about
923 where the server actually is.
924
925 \begin{example} PortMaster Sharing \rm \\ \label{pmsharing}
926 \begin{tabular}{|l|l|l|} \hline
927 \multicolumn{1}{|c|}{\bf Machine} & \multicolumn{1}{c|}{\bf Machine} & \multicolumn{1}{c|}{\bf Machine} \\
928 \multicolumn{1}{|c|}{\bf A} & \multicolumn{1}{c|}{\bf B} & \multicolumn{1}{c|}{\bf C} \\
929 \hline
930 & & \\
931 PMSHARE=machineb & & \\
932 & & \\
933 opens server {\em ASrvr} & & \\
934 & & \\
935 & B's PortMaster & \\
936 & now has {\em ASrvr} & \\
937 & on its list & \\
938 & & \\
939 & & pgm opens client \\
940 & & to ASrvr@machineb \\
941 & & \\
942 & B's PortMaster & \\
943 & satisfies & \\
944 & client's request & \\
945 & & \\
946 & & pgm has client to \\
947 & & {\em ASrvr} on~A~ \\
948 \hline
949 \end{tabular}
950 \end{example}
951
952 In Example~\ref{pmsharing}, three machines are in use. However, machines
953 B~and~C~could have been the same machine. In essence, when~A~shares B's
954 PortMaster, the servers on~A~appear to be on~B~insofar as Sopen'ing~a~client
955 is concerned. Internally, of course, B's PortMaster knows where the {\em ASrvr}
956 is, and clients end up being connected to the server on machine A.
957
958 \subsection{Theory of Operation}
959
960 Normally, users of the {\SSL} will not need to read this section. However,
961 for those who are curious...
962
963 There are two main benefits to using the \SSL: the functions are similar
964 to those that the~C~programmer already knows how to use and hence the {\SSL}
965 has~a~rapid learning curve, and second, servers are assigned to currently
966 available ports. The PortMaster is integral to providing the second benefit.
967
968 Berkeley sockets are assigned ports, which are basically just integers. The
969 port is used internally to assign the flow of data to the correct places.
970 One must assign~a~specific port to~a~server or, alternatively, allow the
971 system to assign any available port to it. Clients must use that same port
972 number to connect to the desired server. Hence, the problem with using the
973 ``any available port'' is how to get the client process to know what the
974 currently assigned port is! Programmers using Berkeley sockets have typically
975 just assigned~a~fixed port to their server and hard-coded the clients with that
976 port. If some other process just happens to use that same port, then things
977 get messy -- re-compile, wait until the other process goes away, etc. On a
978 machine where there are many users, co-operation between the users may be
979 impractical.
980
981 The PortMaster solves the problem of associating~a~server name with~a~randomly
982 assigned (and available) port, and making that association available to
983 clients. The PortMaster itself uses~a~fixed port, and so servers and clients
984 always know ``where'' it is. Whenever~a~server opens (using the Sopen("{\small
985 XXX}","s") call), the Sopen function makes~a~Socket data structure, creates a
986 Berkeley socket, initializes and binds the socket with any available port, and
987 then connects to the PortMaster, {\em using its fixed port}. It then sends a
988 ``message'' ({\small PM\_SERVER}, which is simply an integer) to the
989 PortMaster, telling it the type of Socket it is. Subsequently, the PortMaster
990 gets the new server's name and the port it is assigned to.
991
992 When~a~client opens, it makes~a~Socket, initializes~a~Berkeley socket as a
993 client (using the {\small AF\_INET} format), gets~a~``host'' entity pointer
994 (the server's machine is known as~a~host), and then connects to the PortMaster
995 on the host machine. It then sends~a~``{\small PM\_CLIENT}'' to that
996 PortMaster and the desired server's name; that PortMaster will respond with the
997 associated port number (if there is one). The client then closes down the
998 connection to the target host's PortMaster, and initializes~a~Berkeley socket
999 with the port number it just received and returns~a~client Socket pointer to
1000 the user.
1001
1002 Thus, the \SSL's PortMaster system is~a~distributed database. There are
1003 advantages and disadvantages to this scheme. No PortMaster knows anything about
1004 servers residing on other machines; if~a~machine goes down, other machines
1005 which have no need to communicate with the downed machine are not affected.
1006
1007 On the other hand,~a~single machine with~a~single PortMaster would obviate the
1008 need for clients to know what machines they wish to connect to, and could
1009 force servers on all machines to have unique names (as it is, servers can have
1010 the same name so long as they run on different machines). As~a~palliative, the
1011 {\em Sopenv} function supports the concept of~a~{\em machine path} via the
1012 use of environment variables. Using the Sopenv function, clients can ``hunt''
1013 down~a~given server by attempting to open~a~client one at~a~time on each machine
1014 until~a~server of that name is found. Thus, the user can designate~a~local
1015 group of machines via an environment variable (typically, the
1016 ``{\small SKTPATH}'' environment variable is used for this purpose).
1017
1018 The PortMaster talks to its temporary clients using~a~relatively simple
1019 protocol based on ``messages'' (integers) defined in the \verb`sockets.h`
1020 header file. Table~\ref{portmaster} illustrates the protocol. If the
1021 PortMaster is using its firewall capability, it immediately checks all of
1022 its temporary clients for approved machine status;~a~{\small PM\_SORRY} is
1023 issued immediately prior to the protocol in Table~\ref{portmaster} upon
1024 failure to be approved. The connection is then summarily severed.
1025
1026 \begin{table}[thb]
1027 \begin{center}
1028 \caption{\bf The PortMaster Protocol}
1029 \vspace{.2in}
1030 \label{portmaster}
1031 \begin{tabular}{||l|l|l||} \hline\hline
1032 \multicolumn{1}{||c|}{\em Event} & \multicolumn{1}{c|}{\em Client Sends} & \multicolumn{1}{c||}{\em PortMaster Sends} \\
1033 \hline\hline
1034 {\small PM\_CLIENT} & & \\
1035 & & {\small PM\_OK / PM\_RESEND} \\
1036 & "sktname" & \\
1037 & & {\small PM\_OK / PM\_SORRY} \\
1038 & & port \\ \hline
1039 {\small PM\_CLIENTWAIT} & & \\
1040 & & {\small PM\_OK / PM\_RESEND} \\
1041 & "sktname" & \\
1042 & & {\small PM\_OK / PM\_SORRY} \\
1043 & & port \\ \hline
1044 {\small PM\_CLOSE} & & \\
1045 & & {\small PM\_OK / PM\_RESEND} \\
1046 & port & \\
1047 & & {\small PM\_OK / PM\_SORRY} \\ \hline
1048 {\small PM\_QUIT} & & \\
1049 & & {\small PM\_OK / PM\_RESEND} \\
1050 & "PortMaster" & \\ \hline
1051 {\small PM\_SERVER} & & {\small PM\_OK / PM\_RESEND} \\
1052 & "sktname" & \\
1053 & port & \\
1054 & & {\small PM\_OK / PM\_SORRY} \\ \hline
1055 & {\small PM\_OK} & \\ \hline
1056 {\small PM\_TABLE} & & \\
1057 & & {\small PM\_OK / PM\_RESEND} \\
1058 & & count of servers \\
1059 & & "server : port" \\
1060 & & ... \\ \hline
1061 {\small PM\_FWINIT} & & \\
1062 & & {\small PM\_OK / PM\_RESEND} \\
1063 \hline\hline
1064 \end{tabular}
1065 \end{center}
1066 \end{table}
1067
1068 As indicated in Table~\ref{portmaster}, the PortMaster handles more events than
1069 just the {\small PM\_SERVER} and {\small PM\_CLIENT} events mentioned earlier.
1070 When~a~client opens to the PortMaster, it identifies the type of service it
1071 wishes by sending that PortMaster~a~``message'': {\small PM\_SERVER}, {\small
1072 PM\_CLIENT}, {\small PM\_CLOSE}, {\small PM\_TABLE}, or {\small PM\_QUIT}.
1073 These messages are discussed below. Whenever the PortMaster does not
1074 understand the initial message (due to garbling or whatever), the PortMaster
1075 will immediately issue~a~{\small PM\_RESEND} message and then wait for data.
1076 It will continue doing so for up to {\small PM\_MAXTRY} times (in the
1077 \verb`sockets.h` file as sent, {\small PM\_MAXTRY} is defined as $20$). If the
1078 limit of re-tries is reached, the PortMaster will peremptorily close down the
1079 connection and go back to its usual quiescent state waiting for~a~new
1080 connection.
1081
1082 The PortMaster will wait no more than {\small TIMEOUT} seconds for data, which
1083 is set to 20 seconds in \verb`Spm.c` as delivered. If that amount of time
1084 elapses, the PortMaster will summarily close down the temporary client and
1085 continue for more business.
1086
1087 \begin{description}
1088
1089 \item[{\small PM\_CLIENT}] tells the PortMaster that~a~client is attempting
1090 to open. The PortMaster normally responds with~a~{\small PM\_OK} and the
1091 program attempting to open~a~client responds with~a~null-byte terminated
1092 string (the requested server name). If the PortMaster finds the requested
1093 server in its list, then it responds with~a~{\small PM\_OK} and then the
1094 port number, otherwise it sends~a~{\small PM\_SORRY}.
1095
1096 If the PortMaster is using~a~firewall, it may respond immediately with
1097 ~a~{\small PM\_SORRY} if the client is originating from an unapproved
1098 machine.
1099
1100 \item[{\small PM\_CLIENTWAIT}] acts much like a {\small PM\_CLIENT}, except
1101 that the PortMaster will wait (block) before sending the final
1102 {\small PM\_OK} and port number. Thus clients can request a block
1103 until the desired server is up.
1104
1105 \item[{\small PM\_CLOSE}] tells the PortMaster that~a~server is closing down.
1106 The PortMaster will normally respond with~a~{\small PM\_OK}; the program
1107 closing down the server (via {\em Sclose}) will then send the port number.
1108 The PortMaster will then remove the associated server from its internal
1109 list of servers and respond with~a~{\small PM\_OK} if the designated
1110 server was in its list and~a~{\small PM\_SORRY} otherwise.
1111
1112 \item[{\small PM\_FWINIT}] tells the PortMaster to re-read its firewall
1113 datafile. The PortMaster will then respond with~a~{\small PM\_OK} if
1114 it worked or {\small PM\_RESEND} if something got garbled.
1115
1116 \item[{\small PM\_QUIT}] tells the PortMaster that~a~shutdown command is
1117 to be sent. The PortMaster responds with~a~{\small PM\_OK}, and the program
1118 shutting down the PortMaster issues~a~null-byte terminated string,
1119 ``PortMaster'' (just to guarantee that~a~shutdown is really wanted). The
1120 PortMaster will then shutdown. This operation requires some knowledge of
1121 the protocol as no {\SSL} function is provided to make shutting down the
1122 PortMaster easy. However, the \verb`sktdbg` program does provide an easy
1123 way to shut down the PortMaster. Concerned system administrators may wish
1124 to remove the ``shut'' command from \verb`sktdbg`. Shutting down the
1125 PortMaster does not affect currently connected Sockets; however, new
1126 connections between servers and clients cannot be made. On the other hand,
1127 starting up~a~new PortMaster is easy and anyone may do so -- the \verb`Spm`
1128 program itself will refuse to allow two PortMasters to run concurrently (and
1129 will say so).
1130
1131 \item[{\small PM\_SERVER}] tells the PortMaster that~a~server has been
1132 opened. The PortMaster will normally respond with~a~{\small PM\_OK}
1133 and then the program opening~a~server will send~a~string giving the
1134 new server's name and then will send its port.
1135
1136 The PortMaster will then respond with~a~{\small PM\_OK} upon success or
1137 ~a~{\small PM\_SORRY} if~a~server by that name already exists.
1138
1139 If the PortMaster is using~a~firewall, it may respond immediately with a
1140 {\small PM\_SORRY} if the server is originating from an unapproved machine.
1141 When PortMaster sharing is not operating, this event should never occur, as
1142 servers can then only be legally generated on the same machine that the
1143 PortMaster resides upon. The PortMaster enters its own host onto its
1144 internal firewall table whenever use of~a~firewall is enabled.
1145
1146 \item[{\small PM\_TABLE}] tells the PortMaster to give out~a~list of the
1147 servers it currently knows about. Normally the PortMaster will respond with
1148 ~a~{\small PM\_OK},~a~count of servers (in network standard 2-byte format,
1149 see the Berkeley ``ntohs'' function for details), and~a~sequence of strings
1150 giving the server name and associated port number. The \verb`spmtable`
1151 program and \verb`sktdbg`'s ``table'' function use this facility.
1152
1153 \end{description}
1154
1155 \subsubsection{The PortMaster Firewall}
1156
1157 The PortMaster supports~a~{\em firewall} to keep out socket requests from
1158 unapproved machines. The firewall consists of~a~list of machines' internet
1159 addresses in~a~file. One specifies the file by one of two methods:
1160
1161 \begin{enumerate}
1162 \item Startup with \verb# Spm -f#{\em full-path-to-filename}
1163 \item Initialization of an environment variable, {\small SPMFIREWALL},
1164 to the {\em full-path-to-filename}.
1165 \end{enumerate}
1166
1167 The {\em full-path-to-filename} file contains records of the form:
1168 \begin{verbatim}
1169 * * number number number number
1170 \end{verbatim}
1171
1172 where the four \verb`number`s are the internet addresses of the machines
1173 permitted to talk to the PortMaster. The \verb`*` indicates accept any number
1174 in that field. The firewall function examines incoming internet addresses by
1175 use of the {\em getpeername} function.
1176
1177 The firewall file, often called {\em spmfirewall.dat}, may contain blank
1178 lines. The \verb`#` is assumed to begin~a~comment and is stripped off.
1179
1180
1181 \newpage
1182 \section{The Utilities}
1183
1184 There are several utilities provided with the \SSL, and they are explained
1185 below. These are all complete programs in themselves, and can serve as
1186 lessons on how to use the \SSL.
1187
1188 \begin{description}
1189
1190 \item[sktdbg] \verb`server-name {s|c}` {\em sktdbg} is the \SSL's testing program. One may open server Sockets,
1191 accept Sockets, and client Sockets, test out how other program's Sockets
1192 are communicating, etc. See the subsection on {\em sktdbg} below. The
1193 ``server-name'' may take two forms: \verb`servername` or
1194 \verb`servername@machine-name`. The latter form may be used when
1195 attempting to open clients to servers residing on machines other than the
1196 one the user is currently running \verb`sktdbg` on.
1197
1198 \item[spmchk] \verb`[machine]` This program tests the current machine by default, the named machine
1199 otherwise, for the presence of~a~PortMaster. It will return~a~0 if
1200 the PortMaster is present, or~a~1 otherwise, and is useful in scripts:
1201
1202 \begin{center}
1203 spmchk \verb`||` (nohup Spm \verb`>` /dev/null \&) \end{center}
1204
1205 Translated for non-csh/ksh users: if spmchk finds no PortMaster on the
1206 current machine, start one up in the background in ``no hangup on user
1207 exit'' mode, with output headed to the bit bucket. {\small (thanks go
1208 to Marty Olevitch for this program)}.
1209
1210 For {\small VMS} users:
1211
1212 \begin{center}
1213 \begin{minipage}[h]{5in}
1214 \begin{verbatim}
1215 spmchk:= [fullpath]spmchk.exe
1216 set noon
1217 spmchk
1218 if '$SEVERITY' .ne. 1 then run/detach [fullpath]Spm.exe
1219 set on
1220 \end{verbatim}
1221 \end{minipage}
1222 \end{center}
1223
1224 \item[spmtable] \verb`[machine [machine [machine ...]]]` This program lists the servers and port numbers on the requested machines.
1225 If no machine is listed, then the current machine will be used.
1226
1227 \item[srmsrvr] \verb`[server-name [server-name [server-name ...]]]` Sometimes the all-knowledgeable and omnipotent programmer finds~a~need to
1228 hit the control-c key or otherwise kill~a~running program with~a~server
1229 Socket. In such cases, the PortMaster does not get informed that the
1230 server has gone down. This utility will tell the PortMaster to forcibly
1231 remove the named server(s) from its list.
1232
1233 \end{description}
1234
1235 Except when using \verb`sktdbg` to open~a~server with \verb`sktdbg`, the server
1236 names above can also have the form \verb`srvr@machine-name`. This name
1237 specifies~a~server on~a~specific machine. Note that the machine-name is its
1238 normal abbreviation (ie.~hostname) or its full name (ie.~hostname.someplace.com).
1239
1240
1241 \subsection{The \texttt{sktdbg} Program}
1242
1243 The \verb`sktdbg` program was originally~a~testing facility to debug the {\SSL}
1244 itself, but has proven exceptionally useful in debugging programs which use the
1245 \SSL. Consequently, it is provided as part of the package.
1246
1247 To start up \verb`sktdbg`, one must choose between starting up~a~server or
1248 attempting to open~a~client Socket.
1249
1250 \begin{example} Starting up~a~sktdbg Server \\ \label{sktdbg-srvr}
1251 sktdbg servername s
1252 \end{example}
1253
1254 \begin{example} Starting up~a~sktdbg Client \\ \label{sktdbg-client}
1255 sktdbg servername c
1256 \end{example}
1257
1258 One may also ask sktdbg to explain itself.
1259
1260 \begin{example} sktdbg Explanation \\ \label{sktdbg-explain}
1261 sktdbg "?"
1262 \end{example}
1263
1264 When the \verb`sktdbg` program is started, the first thing it does is attempt
1265 to create the requested type of Socket. Typically, attempts to make~a~server
1266 will succeed; if it doesn't, it will report~a~warning, apply Srmsrvr(), and try
1267 a~second time to open the server again. If it fails twice, then usually the
1268 PortMaster is not running on your machine.
1269
1270 Attempts to open~a~client to~a~non-existent server also yields an error
1271 message: ``unable to Sopen(srvrname,c)''. If the server is up and running,
1272 then~a~client Socket will be set up.
1273
1274 The \verb`sktdbg` program then prints out~a~little menu of actions that the
1275 user can take with it.
1276
1277 \begin{table}[thb]
1278 \begin{center}
1279 \caption{sktdbg Help Menu}
1280 \label{sktdbg-help}
1281 \begin{verbatim}
1282 Socket Test Commands
1283 accept
1284 close
1285 fwinit
1286 fput
1287 get
1288 menu
1289 peek
1290 printf
1291 put
1292 q
1293 quit
1294 read
1295 rmsrvr
1296 scanf
1297 shutdown
1298 table
1299 test
1300 wait
1301 write
1302 ?
1303 ( 0 bytes) Enter:
1304 \end{verbatim}
1305 \end{center}
1306 \end{table}
1307
1308 The ``Enter'' prompt now also shows the number of bytes waiting on the queue
1309 for reading. This number is updated only when the prompt is generated; ie. it
1310 is not~a~dynamic value, but is often useful.
1311
1312 In Table~\ref{sktdbg-help}, there are 20 commands available, and are
1313 described below.
1314
1315 \begin{description}
1316
1317 \item[accept] \ Used by~a~server Socket to accept clients. Note that one
1318 may first do {\em test} to determine if~a~client is waiting.
1319
1320 \item[close] \ Used by~a~server Socket to close down an accept Socket.
1321
1322 \item[fput] \ This function takes~a~filename, {\em fput filename}, which sktdbg then opens.
1323 Every line in it, minus trailing white space, is sent via Sputs across the
1324 Socket. Sktdbg then closes the file.
1325
1326 \item[fwinit] \ This call issues~a~{\small PM\_FWINIT} to the local machine's PortMaster.
1327 The PortMaster will then re-read the firewall data file that it was optionally
1328 started up with (if it had none, then this command will have no effect). The
1329 fwinit command is useful for the owner of the firewall data file to change it
1330 and have the PortMaster update itself without bringing down the PortMaster and
1331 restarting it.
1332
1333 \item[get] \ Uses Sgets to get~a~null-terminated string from the client. This call will
1334 block until something arrives for up to 60 seconds.
1335
1336 \item[isset] \ Uses Smaskwait() with negligible timeout (1 microsecond!) and then uses
1337 Smaskisset() to determine if the socket is read-ready. This function
1338 was included mostly for testing Smaskisset().
1339
1340 \item[menu] \ Repeats the {\em Socket Test Commands} menu (just like ``?'' below).
1341
1342 \item[peek] \ Uses Speek to peek at what the client has sent. This call
1343 will not block, even if nothing is there yet.
1344
1345 \item[printf] printf your-word Uses Sprintf to send "your-word 7 8. itworked!" through the Socket.
1346
1347 \item[put] put your various sundry strings across Uses Sputs to send your strings on the same line through the Socket.
1348
1349 \item[q] \ This function ``quits'' -- uses Sclose to close down all Sockets that
1350 \verb`sktdbg` is using and exits. Just like ``quit''.
1351
1352 \item[quit] \ This function ``quits'' -- uses Sclose to close down all Sockets that
1353 \verb`sktdbg` is using and exits. Just like ``q''.
1354
1355 \item[read] \ This function uses Sread to read whatever is on the Socket, and prints
1356 it out assuming that it received~a~string.
1357
1358 \item[rmsrvr] rmsrvr server-name This function uses Srmsrvr to remove~a~server.
1359
1360 \item[scanf] \ This function accepts~a~subset of format code: \%c, \%d, \%f, and \%s.
1361 It will call Sscanf once for each format code given to it.
1362
1363 \item[shutdown] \ This function is {\em dangerous}! It will shut down the PortMaster on
1364 your current machine and perform~a~quit. Use of this function is
1365 strongly discouraged unless it is necessary to pull down~a~PortMaster.
1366
1367 \item[table] \ The {\em table} function communicates with the PortMaster and prints out
1368 ~a~table of all current servers and their ports (rather like spmtable).
1369
1370 \item[test] \ The {\em test} function prints out the number of bytes awaiting perusal
1371 by~a~get or read operation. It does not block, even if nothing is
1372 waiting -- it will return 0 in such~a~case.
1373
1374 \item[wait] \ This function will block the process until something shows up on the
1375 accept or client Socket.
1376
1377 \item[write] write your sundry thoughts and words This function will {\em Swrite} your words, appropriately null-byte
1378 terminated, through the Socket. It can be read by the {\em read} function.
1379
1380 \item[?] \ Repeats the {\em Socket Test Commands} menu (just like ``menu'' above).
1381
1382 \end{description}
1383
1384 This program is really quite simple to learn and run, and is useful to help
1385 the installer verify that the {\SSL} is installed correctly.
1386
1387
1388 \newpage
1389 \section{Installation Instructions}
1390
1391 Installation varies, of course, from operating system to operating system.
1392
1393
1394 \subsection{Unix}
1395
1396 \begin{enumerate}
1397
1398 \item Make~a~{\tt SKTS} subdirectory somewhere, and extract the contents
1399 of the tape into that subdirectory (typically, {\tt tar -xvop}, but
1400 systems will vary and you may need to specify~a~tape drive).
1401
1402 \item If your machine is not {\small ANSI C} compliant, but supports
1403 prototyping anyway, edit the \verb`sockets.h` file to \verb`#`define {\small
1404 \_\_PROTOTYPE\_\_} for your machine.
1405
1406 \item Type {\tt make all}.
1407
1408 \end{enumerate}
1409
1410 These instructions should result in the {\SSL} being compiled, the utilities
1411 being compiled, and the PortMaster being compiled. ~A~{\em simpleskts.a}
1412 library results. Although the PortMaster gets started by the make
1413 instructions, you may occasionally need to re-start it (for example, after the
1414 computer goes down). System administrators should know how to modify their
1415 operating system to automatically bring up the PortMaster during~a~re-boot.
1416
1417 Users may wish to place
1418
1419 \begin{center}
1420 \begin{tabular}{ll}
1421 setenv SKTPATH machine:machine:machine...` & csh users \\
1422 export SKTPATH=machine:machine:machine...` & ksh users \\
1423 SKTPATH:==machine:machine:machine...` & vms users \\
1424 set SKTPATH=machine:machine:machine...` & msdos users \\
1425 \end{tabular}
1426 \end{center}
1427
1428 \noindent
1429 in their .login, .profile, login.com, and autoexec.bat respectively. To link
1430 to the \SSL, one must include ``sockets.h''. For example, under {\small UNIX},
1431 a~user should have~a~{\small .HDR} subdirectory with all his/her favorite
1432 header files and use ``\verb`cc ... -I~/.HDR ... simpleskts.a`''.
1433
1434
1435 \subsection{Vms}
1436
1437 \begin{enumerate}
1438
1439 \item Make~a~{\tt SKTS} subdirectory somewhere, and extract the contents
1440 of the tape into that subdirectory. The original tape was~a~quarter-inch
1441 cartridge in Unix tar format, but you may well receive~a~different format.
1442
1443 \item Type \verb`@makeskts`
1444 \end{enumerate}
1445
1446 The ``makeskts'' command script will create several subdirectories, compile the
1447 \SSL, and set up~a~``simpleskts.olb'' library. It will {\bf not} attempt to
1448 start up the PortMaster. Change to the ``{\small EXE}'' subdirectory under the
1449 {\small SKTS} subdirectory. The PortMaster should be started via
1450 \verb`run/detach Spm`; you may or may not have sufficient privileges to do so.
1451 One may spawn the PortMaster, but as soon as you log off the PortMaster will
1452 rudely terminate. Due to the potential problem with privileges, the command
1453 script will not start up the PortMaster itself.
1454
1455 In order to make use of command-line arguments for sktdbg, etc, {\small VMS} requires
1456 that you first make ``logical symbols.'' In your \verb`<login.com>`,
1457 place the following lines (with appropriately modified {\small YOURDIR}):
1458
1459 \begin{center}
1460 \begin{tabular}{lcl}
1461 \$ spmchk & :== & \$[{\small YOURDIR.SKTS.EXE}]spmchk.exe \\
1462 \$ spmtable & :== & \$[{\small YOURDIR.SKTS.EXE}]spmtable.exe \\
1463 \$ spm & :== & \$[{\small YOURDIR.SKTS.EXE}]spm.exe \\
1464 \$ srmsrvr & :== & \$[{\small YOURDIR.SKTS.EXE}]srmsrvr.exe
1465 \end{tabular}
1466 \end{center}
1467
1468 \subsection{Windows 95 ( or more recent)}
1469
1470 As of Version 2.08, the {\SSL} runs under Windows 95. One may
1471 have~a~PortMaster running in the background on those machines,
1472 too! Since the present author only has Borland C++, only that
1473 compiler has been tested. Other compilers may need to modify the
1474 \verb`<`Sinit.c\verb`>` file to include any \TCP\ initialization
1475 they may require.
1476
1477 \begin{enumerate}
1478 \item Set up your system with an appropriate~C~compiler, Ethernet card,
1479 and \TCP.
1480 \item Copy the contents of <ssl.tar.gz> onto your computer.
1481 \item Use gunzip and untar to get the uncompressed files
1482 \item Open~a~{\small MSDOS} console, change directory to ...\verb`\`{\COSMIC}
1483 \item mkwin95
1484 \end{enumerate}
1485
1486 The {\sf smplskts.lib} and various {\sf *.exe} files should be generated
1487 in the {\COSMIC} subdirectory. You may well want to have the Simple Sockets
1488 Library's PortMaster (Spm) always running in background. To accomplish this:
1489
1490 \begin{enumerate}
1491 \item On your workbench, click the right mouse button
1492 \item Select {\sf New}
1493 \item Select {\sf Shortcut}
1494 \item Put the fully specified path to Spm.exe in the
1495 {\sf Command Line} dialog box.
1496 \item Put {\sf Spm} as the shortcut's name
1497 \item Right-mouse click on the {\sf Spm} shortcut
1498 \item Select {\sf Properties}
1499 \item Select the {\sf Shortcut} tab
1500 \item In the {\sf Run} dialog, left mouse click on the
1501 down arrow and select {\sf minimized}.
1502 \item Bring up Explorer
1503 \item Click on the \verb`+` in the left hand window near {\sf Windows}
1504 \item Click on the \verb`+` in the left hand window near {\sf Start Menu}
1505 \item Click on the \verb`+` in the left hand window near {\sf Programs}
1506 \item Double click on {\sf StartUp}
1507 \item Put the mouse cursor on the {\sf Spm} shortcut; press the right
1508 mouse button and drag it over the right hand Explorer window.
1509 \item Select {\sf Copy Here}. You will now need to re-boot your machine
1510 for this operation to take effect.
1511 \end{enumerate}
1512
1513 \subsection{Older Ms-Dos}
1514
1515 The {\SSL} was compiled and tested using the Wollongong {\TCP} package with
1516 MicroSoft~C~(v6.0). Other compilers and {\TCP} packages may require adjustment
1517 to the {\SSL} code. You {\bf must} have~a~\TCP package for your machine,
1518 however -- that is what provides Berkeley sockets over which the {\SSL} provides
1519 a~convenient overlay. Also, you {\bf must} have an Ethernet card for your
1520 machine -- that provides the hardware over which the information flows.
1521 Neither the {\TCP} package, the~C~compiler, nor the Ethernet hardware come with
1522 the \SSL.
1523
1524 \begin{enumerate}
1525
1526 \item The {\SSL} makes several assumptions, unfortunately, about
1527 where include files are (ex. see {\em Speek.c\/}). The installer
1528 will undoubtedly need to customize these include lines. These
1529 areas will always be in \verb`#ifdef MSDOS` ... \verb`#endif` zones.
1530 \item Acquire~a~\TCP package for your computer (ie.~Wollongong).
1531 \item Acquire~a~C compiler for your computer (ie.~Microsoft C, v6.0).
1532 \item Acquire an Ethernet card and {\TCP} address for your computer.
1533 \item Copy the contents of the provided diskette into your subdirectory.
1534 \item For those of you with the software mentioned in
1535 Table~\ref{msdos-swlist}:
1536 \begin{enumerate}
1537 \item Make~a~directory: \verb`c:\c600\socket`
1538 \item Make~a~directory: \verb`c:\c600\socket\exe`
1539 \item Copy {\em wintcp.lib} to \verb`c:\c600\socket`
1540 \item Copy {\em socket.lib} to \verb`c:\c600\socket`
1541 \item Copy {\em slibce.lib} to \verb`c:\c600\socket`
1542 \item Disable the {\small MSDOS} linker -- possibly by renaming it
1543 to {\em doslink}. Use the MicroSoft~C~linker instead.
1544 \item Return to the directory where you placed the {\SSL} software.
1545 \item Type {\em makeskt} (which will use the
1546 {\em Makeskt.bat} command script). This script will use
1547 {\em Makelib.}, compile, create the {\em smplskts.lib} library,
1548 and generate {\em sktdbg.exe}, {\em spmtable.exe}, and
1549 {\em srmsrvr.exe}.
1550 \item You should be done installing the software at this point.
1551 \end{enumerate}
1552 \item If your compiler is not {\small ANSI C} compliant, but supports
1553 prototyping, edit the \verb`sockets.h` file to define {\small
1554 \_\_PROTOTYPE\_\_} for your machine.
1555 \item Follow your compiler's directions to compile to object file format
1556 all the~C~files in \verb`SKTS` and \verb`SKTS\EXE`.
1557 \item Follow your compiler's directions to set up~a~``library'' (a {\tt .LIB}
1558 file) with all the {\tt .OBJ} files in the \verb`SKTS` subdirectory.
1559 \item Change to the \verb`SKTS\EXE` subdirectory and follow your compiler's
1560 instructions to link each of the object files, one at~a~time, to the
1561 ``smplskts.lib'' library, the {\TCP} library, and whatever
1562 libraries your compiler normally needs.
1563
1564 \end{enumerate}
1565
1566 The installation should yield~a~{\em smplskts.lib} (or something similar)
1567 library and three executable files (sktdbg.exe, spmtable.exe, and
1568 spmtable.exe).
1569
1570 Note that the ``{\small SPM.EXE}'' file should not be generated; you could
1571 generate and execute it, but your clone could not use it as it does not allow
1572 the PortMaster to run in the background. No attempt has been made to insure
1573 that the PortMaster is actually compilable under MicroSoft C, either. Someday
1574 a~kludge to allow MS-DOS programs to be their own PortMaster may be developed,
1575 but that day is not yet. Using Wollongong \TCP, one will be restricted to
1576 three (or five if its ``kernel'' is rebuilt) clients.
1577
1578 The software in Table~\ref{msdos-swlist} was used by the \IRL\ and is known to
1579 work properly with the \SSL. Other software may work but has not been tested.
1580
1581 \begin{table}[h]
1582 \begin{center}
1583 \caption{\bf Ms-Dos Software known to work with the \protect{\small\bf SSL}}
1584 \label{msdos-swlist}
1585 \begin{tabular}{ll}
1586 \multicolumn{1}{c}{\em Software Product} & \multicolumn{1}{c}{\em Company} \\
1587 MicroSoft C, v6.0 & MicroSoft \\
1588 {\small Win/API} for {\small DOS}, v4.1 & The Wollongong Group, Inc. \\
1589 & PO Box 51860 \\
1590 & Palo Alto, CA 94303-4374 \\
1591 & (415)-962-7100 \\
1592 Wollongong Win/{\small TCP}, v4.1.1 & The Wollongong Group, Inc. \\
1593 \end{tabular}
1594 \end{center}
1595 \end{table}
1596
1597
1598 \newpage
1599 \section{Appendix: Miscellaneous Functions}
1600
1601 The {\SSL} uses nine functions from Dr.~Campbell's {\em xtdio} library; these
1602 have been gathered together and made part of the {\em simpleskts.a} library.
1603 Several of the functions use~a~special data file, {\em rdcolor.dat}.
1604
1605 Note: the {\em error} and {\em outofmem} functions claim they will
1606 ``terminate'' under certain conditions. Actually, they will call the function
1607 {\em (*error\_exit)(int~rtn)}, which by default is the {\em exit} function.
1608 Programmers may easily prevent or otherwise control termination by simply
1609 setting {\em error\_exit} to point to some other function.
1610
1611 \begin{description}
1612
1613 \item[void error(int severity,char *fmt,...)] \ The {\em error} function prints out an error, warning, or note type of
1614 message to stdout. This function takes four kinds of ``severity'': {\small
1615 SEVERE}, {\small ERROR}, {\small WARNING}, and {\small NOTE}. Both the
1616 {\small SEVERE} and {\small ERROR} levels will {\em terminate} the
1617 program. The other two, {\small WARNING} and {\small NOTE}, will not do
1618 so. The termination action tends to enforce~a~standard for what errors
1619 versus warnings mean! If your terminal type is supported by the {\em
1620 rdcolor.dat} file (see rdcolor below), {\small SEVERE} and {\small ERROR}
1621 messages are printed with~a~red leader, {\small WARNING}s with~a~yellow
1622 leader, and {\small NOTE}s with~a~cyan leader.
1623
1624 \item[FILE *fopenv(char *filename,char *ctrl,char *env\_var)] \ The {\em fopenv} provides~a~file opening service akin to that provided
1625 by the {\em Sopenv} function for the \SSL. The {\em fopen()} function
1626 will be used with the given filename and ctrl strings, and upon failure,
1627 the environment variable in {\em env\_var} will be used like a
1628 {\small PATH} variable in attempts to open the file in one directory after
1629 another (until success). If none of the {\em fopen\/}s succeed, then
1630 the {\em fopenv} function will return~a~{\small NULL} pointer.
1631
1632 \item[void outofmem(void *ptr,char *fmt,...)] \ The {\em outofmem} function checks if {\em ptr} is {\small NULL}; if it is
1633 not, the function immediately returns.
1634
1635 However, if the {\em ptr} pointer is in fact {\small NULL}, then the
1636 {\em fmt} and any subsequent arguments will be used like~a~regular printf
1637 to give~a~message to the user. The program will then terminate.
1638
1639 \item[void rdcolor(void)] \ This function reads the {\em rdcolor.dat} file, which essentially is an
1640 extended ``termcap'' file. It uses the ``RDCOLOR'' environment variable with
1641 {\em fopenv} to search for the {\em rdcolor.dat} file. The function uses
1642 that file to set up various string variables ({\small RED}, {\small CLEAR},
1643 -- see below).
1644
1645 \item[void rdcputs(char *s,FILE *fp)] \ This function puts~a~string out to the {\small FILE} pointer {\em fp},
1646 except that those strings ({\small XRED}, {\small XUWHITE}, etc.) are
1647 interpreted using the {\em rdcolor}-provided string instead.
1648
1649 \item[char *sprt(char *s)] \ This function returns~a~pointer to~a~static buffer (there are four of them).
1650 The string {\em s} has all of its characters made into ``visible'' forms:
1651 control characters become \^A through \^Z and characters with {\small ANSI}
1652 values greater than or equal to $128$ are made into \verb`~###` sequences.
1653 Characters which are normally visible are left unchanged.
1654
1655 \item[void srmtrblk(char *s)] \ This function removes any trailing ``blanks'' (white space) from the
1656 end of~a~string.
1657
1658 \item[char *stpblk(char *p)] \ This function returns~a~pointer to the first non-white space character
1659 in the string {\em p} (ie.~steps past blanks).
1660
1661 \item[char *stpnxt(char *s,char *fmt)] \ This function returns~a~pointer to the first character in {\em s} which
1662 would not have been read by~a~{\em sscanf(s,fmt,...)} function. Useful
1663 for quick and dirty parsing.
1664
1665 \item[char *strnxtfmt(char *fmt)] \ The {\em strnxtfmt} function returns~a~pointer to the beginning of the
1666 (next) format code substring. If {\em fmt} is {\small NULL}, then the
1667 previous format string is used (ie.~a pointer to the last {\em fmt} code
1668 is retained and the~a~pointer to the next format code pointer will be
1669 returned). This function bears some similarity to {\small strtok} except
1670 that it jumps from format code to format code (used by Sscanf).
1671
1672 \end{description}
1673
1674 The {\em rdcolor.dat\/} file describes terminal escape sequences to use
1675 to control color and~a~few other actions. Each line which does not begin
1676 with~a~white space character is assumed to be~a~terminal line: terminal
1677 types are separated by vertical bars and the line is terminated by~a~colon.
1678 There are~a~number of strings defined (see Table~\ref{rdcolor}).
1679
1680 \begin{table}[thb]
1681 \begin{center}
1682 \caption{rdcolor.dat strings}
1683 \label{rdcolor}
1684 \begin{tabular}{||l|l||}
1685 \hline\hline
1686 {\em String Name} & {\em Function} \\
1687 \hline
1688 {\small BLACK} & subsequent chars are black \\
1689 {\small RED} & subsequent chars are red \\
1690 {\small GREEN} & subsequent chars are green \\
1691 {\small YELLOW} & subsequent chars are yellow \\
1692 {\small BLUE} & subsequent chars are blue \\
1693 {\small MAGENTA} & subsequent chars are magenta \\
1694 {\small CYAN} & subsequent chars are cyan \\
1695 {\small WHITE} & subsequent chars are white \\
1696 & \\
1697 {\small UBLACK} & subsequent chars are underlined and black \\
1698 {\small URED} & subsequent chars are underlined and red \\
1699 {\small UGREEN} & subsequent chars are underlined and green \\
1700 {\small UYELLOW} & subsequent chars are underlined and yellow \\
1701 {\small UBLUE} & subsequent chars are underlined and blue \\
1702 {\small UMAGENTA} & subsequent chars are underlined and magenta \\
1703 {\small UCYAN} & subsequent chars are underlined and cyan \\
1704 {\small UWHITE} & subsequent chars are underlined and white \\
1705 & \\
1706 {\small RVBLACK} & subsequent chars are reverse-video and black \\
1707 {\small RVRED} & subsequent chars are reverse-video and red \\
1708 {\small RVGREEN} & subsequent chars are reverse-video and green \\
1709 {\small RVYELLOW} & subsequent chars are reverse-video and yellow \\
1710 {\small RVBLUE} & subsequent chars are reverse-video and blue \\
1711 {\small RVMAGENTA} & subsequent chars are reverse-video and magenta \\
1712 {\small RVCYAN} & subsequent chars are reverse-video and cyan \\
1713 {\small RVWHITE} & subsequent chars are reverse-video and white \\
1714 & \\
1715 {\small NRML} & subsequent chars are ``normal'' \\
1716 {\small BOLD} & subsequent chars are ``bold'' \\
1717 {\small CLEAR} & the screen is cleared \\
1718 \hline\hline
1719 \end{tabular}
1720 \end{center}
1721 \end{table}
1722
1723 Escape sequences may include the sequence \verb`\e` for the {\small ESCAPE}
1724 character and \verb`\b` for~a~blank. Please see the {\em rdcolor.dat} file
1725 for examples.
1726 \end{document}