Debian Codegraph @

COSMIC/DOC/sockets.txt

raw
1
2
3
4
5 The Simple Sockets Library
6
7 Version 2.09
8
9
10
11 Charles E. Campbell, Jr., Ph.D. Terry McRoberts
12
13
14
15 April 18, 2001
16
17
18
19 Abstract
20
21 The Simple Sockets Library (SSL) allows C programmers to use interprocess com-
22 munications via Berkeley sockets simply and quickly. The programmer is able to move
23 information easily between processes on the same or different machines connected via
24 Ethernet (tm) and using the TCP/IP protocol. Most of the SSL's functions resemble
25 C's file i/o functions, so C programmers will find the SSL easy to learn.
26
27 The SSL currently runs under various UNIX (tm) machines: IRIX (tm) (Silicon
28 Graphics), SunOS (tm) (Sun), Domain O/S (tm) (Apollo), Ultrix (tm) (Dec), AIX (tm)
29 (IBM), SCO (tm) , OSF (tm) , and VMS 5.x (tm) , and MS-DOS (tm) (using Borland C++
30 5.0).
31
32
33
34 Keywords
35 Socket Interprocess CommunicationsIntermachine Communications
36 Berkeley Sockets Ethernet
37 TCP/IP Robotics
38 Machine Control
39
40
41
42
43 Contents
44
45
46 1 Introduction 1
47
48
49 2 The Library 3
50
51 2.1 User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
52
53 2.2 Reference Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
54
55 2.3 Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
56
57
58 3 The PortMaster 16
59
60 3.1 Users Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
61
62 3.2 Sharing PortMasters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
63
64 3.3 Theory of Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
65
66 3.3.1 The PortMaster Firewall . . . . . . . . . . . . . . . . . . . . . . . . . 21
67
68
69 4 The Utilities 22
70
71 4.1 The sktdbg Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
72
73
74 5 Installation Instructions 27
75
76 5.1 Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
77
78 5.2 Vms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
79
80 5.3 Windows 95 ( or more recent) . . . . . . . . . . . . . . . . . . . . . . . . . . 28
81
82 5.4 Older Ms-Dos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
83
84
85 6 Appendix: Miscellaneous Functions 31
86
87
88
89
90 1 Introduction
91
92
93 The Simple Sockets Library (henceforth to be abbreviated as the SSL) allows C programmers
94
95 to develop systems of cooperating programs using Berkeley streaming Sockets running under
96
97 the TCP/IP protocol over Ethernet. The SSL provides simple ways to move information
98
99 between programs running on the same or different machines and does so with little overhead.
100
101 During experiments with the Sreadbytes and Swrite functions, for example, between two
102
103 machines, a 44; 000 bytes/second transfer rate was achieved with 4 bytes per packet and
104
105 over 1; 000; 000 bytes/second was achieved with 128 bytes per packet. Of course, heavily
106
107 loaded networks will affect the rate individual users achieve. The SSL provides two-way
108
109 communications.
110
111 The SSL was designed to resemble the FILE i/o system provided by the standard C li-
112
113 braries (ie. fopen, fclose, fputs, etc. map to SSL analogs Sopen, Sclose, Sputs, etc.). Thus, C pro-
114
115 grammers typically find the SSL easy to learn.
116
117 A good analogy for the SSL refers to the phone system. There are three types of Sockets
118
119 supported by the SSL that concern the user: a server, a client, and an accept socket. A server
120
121 is analogous to someone waiting by several phones for a call, a client is analogous to someone
122
123 making a call, and an accept is analogous to a (server) person accepting the call by picking
124
125 up one of the phones.
126
127 Thus, one must have a server for a client to make a successful connection. The server
128
129 must in turn accept the connection. Unlike our overworked server person, however, the
130
131 computer using the SSL is perfectly happy handling multiple \accept" Sockets concurrently.
132
133 The SSL itself is provided in three main parts (see Table 1). The Library is composed
134
135 of C functions and the PortMaster and the Utilities are self-contained programs.
136
137
138
139 Table 1: The Three Parts of the SSL
140
141
142
143 Library The functions that the users will link to are in the library.
144
145
146 PortMaster The PortMaster is a daemon program which runs in the background. It allows
147
148 clients to connect to servers using any available ports.
149
150
151 UtilitiesThere are several utility programs provided with the SSL: sktdbg, srmsrvr, and
152
153 spmtable.
154
155
156
157 The SSL has been in use at NASA's Goddard Space Flight Center's Intelligent Robotics
158
159 Laboratory (IRL) since May, 1991. The software appears to be stable at the current writing
160
161 and reasonably robust. For example, the PortMaster, a background process provided in
162
163 the SSL distribution, is resistant to hanging (and thereby being unresponsive). It uses
164
165 Stimeoutwaits (see the Reference Manual) to return to its normal quiescent mode when
166
167 communications with one of its clients ceases unexpectedly.
168
169 The IRL uses the SSL to control its three robots; its use of the Ethernet is consequently
170
171 somewhat heavy. Those of you who wish to control machinery or otherwise present a heavy
172
173
174
175 1
176
177
178
179
180 load may wish to purchase a \bridge" to isolate your machines from your local network. This
181
182 isolation will benefit both the you and the network, as the heavy user will not be afflicted
183
184 with slowdowns due to the network and the network will not be bothered with lots of packets
185
186 which slows all its users down.
187
188 Please contact COSMIC if you have serious difficulties (ie. bugs) with the SSL.
189
190
191
192 2
193
194
195
196
197 2 The Library |||
198
199 ||||
200 The user of the SSL accesses|it|by|linking|his|or|her program to a library. A software library
201
202 is typically a single file|which|consists|of|some|linkage|information along with pre-compiled
203
204 object code; unfortunately,|methods|for|producing|a|library|and linking to it vary from system
205
206 to system and compiler to|compiler.|Directions|for|several|systems|appear in the Section on
207
208 Implementation. ||||
209 ||
210 Practically speaking, a|library|is|composed|of a number of pre-compiled C functions to
211
212 be utilized by the programmer.|The|calls|made|available|in|the SSL are reminiscent of those
213
214 used by the various file functions|in|the|C|language|(see Table 2).
215 |||||
216 |||||
217 |||||
218 |||||
219 ||||||
220 Table 2: Simple|Sockets|and|Related|File|I/O|Functions|||
221 ||||
222 ___|___|File|FunctionS___ocket|Function ___ ___
223
224 ___|___|fopen||Sopen ___ ___ ___
225
226 ___|___|fclose|Sclose|___ ___ ___
227
228 ___|___|fread| Sread ___ ___ ___
229 |
230 ___|___|fwrite|Swrite ___ ___ ___
231 |
232 ___|___|fgets| Sgets ___ ___ ___
233
234 ___|___|fputs||Sputs ___ ___ ___
235
236 ___|___|fprintfSprintf___| ___ ___
237 ||
238 ___|___|fscanf Sscanf ___ ___ ___
239
240
241
242 The Sockets library depends upon the PortMaster running on your host machine. Only
243
244 one copy of the PortMaster need be running at any time on a given machine, and may be
245
246 started up by anyone by running the Spm program in the background. On Unix, the Spm
247
248 program will put itself into the background. One may determine if your system has a Port-
249
250 Master running by typing spmtable first { it will inform you of any existing servers if the
251
252 PortMaster is up or tell you that the PortMaster is not up otherwise.
253
254 A new feature of the SSL allows servers to share another machine's PortMaster. Thus, the
255
256 SSL supports both distributed and centralized socket name to port mapping. If the machine
257
258 on which a server is to run doesn't have a PortMaster, such as older MSDOS machines, then
259
260 it can \borrow" another machine's PortMaster.
261
262 A program may open a server Socket, a client Socket, or an accept Socket. Following the
263
264 phone system analogy, assume that a server Socket is opened first. Then, a different program
265
266 may open a client Socket which attempts to connect to the server { it succeeds when the
267
268 server program \notices" that there is a connection waiting on the server Socket and then
269
270 generates an accept Socket. The client Socket can open, however, before the server accepts
271
272 the client; there just won't be any two-way communication until the server does accept the
273
274 client.
275
276
277
278 3
279
280
281
282
283 2.1 User Guide
284
285
286 Software using C must #include "sockets.h" and must link to the SSL. Directions for
287
288 doing so will vary from system to system and also depend upon where the installer placed
289
290 the libraries. Please refer to your compiler documentation and the SSL installer to know how
291
292 to set up library linkage paths and for the include path to the sockets.h file.
293
294 The software below illustrates some typical Socket code fragments to get a connected
295
296 socket, assuming that the sockets.h file is on your compiler's include search path. If the
297
298 sockets.h file has been placed in a standard system directory (not wise - updates to the
299
300 compiler may wipe it off!) then you may have to substitute #include <sockets.h> for
301
302 #include "sockets.h" in the following examples.
303
304
305 Example 2.1 A server with one accept
306
307 #include "sockets.h"
308
309 Socket *server;
310
311 Socket *skt;
312
313 server= Sopen("servername","s");
314
315 skt = Saccept(server);
316
317 ...
318
319 Sclose(skt);
320
321 Sclose(server);
322
323
324 Note in Example 2.1 that the servername is completely up to the programmer to select.
325
326 Please note that all servers share the same namespace on any given machine, however.
327
328
329 Example 2.2 A server with multiple accepts
330
331 #include "sockets.h"
332
333 Socket *server=NULL;
334
335 Socket *skt=NULL;
336
337 server= Sopen("servername","s");
338
339 do {
340
341 skt = Saccept(server);
342
343 ...
344
345 Sclose(skt);
346
347 } while(whatever);
348
349 Sclose(server);
350
351
352 Again, the programmer may select any servername. Note that the accept Socket (\skt")
353
354 is re-used in Example 2.2.
355
356
357 Example 2.3 A client
358
359 #include "sockets.h"
360
361 Socket *client;
362
363 client= Sopen("serverName","c");
364
365 ...
366
367 Sclose(client);
368
369
370
371 4
372
373
374
375
376 In Example 2.3, the serverName may be in the optional form serverName@machineName.
377
378 Without the machine name specification, the PortMaster on the machine that the client is
379
380 running on will be searched for the server. The smsrvr.c and smclient.c example programs
381
382 provided in the SSL distribution give complete illustrations of Examples 2.1 and 2.3.
383
384 Example 2.4 Using Sopenv
385
386 #include "sockets.h"
387
388 Socket *client;
389
390 while(1) {
391
392 client= Sopenv("serverName","c","SKTPATH");
393
394 if(client) break;
395
396 sleep(1);
397
398 }
399
400 ...
401
402 Sclose(client);
403
404 The SSL allows the programmer to set up a group of machines for making client con-
405
406 nections. In Example 2.4, the SSL tries to open a client to a server named serverName on
407
408 any machine on the SKTPATH. The \SKTPATH" is an environment variable typically of the
409
410 form machine1:machine2:machine3, ie. a list of machine names separated by colons. This
411
412 example also shows a typical client connection attempt and sleep polling loop.
413
414 A somewhat larger example is included in the distribution: multiskt.c. This example
415
416 program concurrently accepts multiple clients on a single server, reads any messages sent
417
418 its way from any of its clients, and sends a modified version back to the sending client. It
419
420 uses the Smaskwait functions to block the multiskt process for friendly multi-tasking. It
421
422 is a useful program to study in conjunction with the Manual below.
423
424 Connected sockets are a pre-requisite for any of the I/O Socket functions described in
425
426 the next section. Note that the server should have a unique name on any given machine.
427
428 Servers may have the same name on different machines, although this may be confusing. It
429
430 is suggested that one use the name of the process (at least as a prefix) for that purpose. Note
431
432 that the only things that one can do with a server Socket are: open one, close one, generate
433
434 an accept Socket with one, and test/block on one (for clients requesting connection). The
435
436 SSL supports up to 10 clients concurrently awaiting acceptance on a server Socket, although
437
438 many machines will limit that to 5 (silently).
439
440 The SSL supports two way communication of data between a client and an accept Socket.
441
442 Since the processes are not likely to be synchronized, often one process must somehow wait
443
444 until the other process has sent it something. There are two methods to support this under
445
446 the SSL: polling and interrupt-driven. The polling method uses a lot of CPU time, but
447
448 lets the program do other tasks in the meantime. The interrupt-driven approach hangs the
449
450 process (aka blocks and suspends) until something shows up on the Socket. The SmaskXXX
451
452 group of functions allows one to hang the process until something shows up on any number
453
454 of Sockets { sort of a big OR gate!
455
456 The SmaskXXX alternative to polling also allows the programmer to insert non-socket
457
458 file descriptors into the mask via Smaskfdset (and to remove them via Smaskunfdset) such
459
460 as serial ports (ex. open with DEVICE), graphics queues (ex. SGIs with qgetfd), etc.
461
462
463
464 5
465 ||
466 ||
467 ||
468 ||
469 |||
470 |||
471 |||
472 |||
473 |||
474 |||
475 |||
476 |||
477 |||
478 |||
479 |||
480 |||
481 |||
482 |||
483 |||
484 |||
485 |||
486 |||
487 |||
488 |||
489 |||
490 |||
491 |||
492 |||
493 |||
494 |||
495 |||
496 |||
497 |||
498 |||
499 |||
500 |||
501 |||
502 |||
503 ||||||
504 |||
505 |||
506 |||
507 |||
508 |||
509 2.2 ||Reference|Manual|
510
511 |||||
512 This section|contains|a|description|of the functions available in the Socket Library. The
513
514 SSL returns|three|types|of|Sockets:|a server, client, and an accept Socket. A Socket itself
515 |||
516 is a data|structure|type|set up by the sockets.h header file. The Socket is deliberately used
517
518 in a fashion|reminiscent|of|the|use|of|FILE pointers so that the C user who knows how to
519
520 read and|write|a|file|will|immediately|feel comfortable with reading and writing Sockets.
521 |||
522 |||
523 |
524 ___|___ Return ___Function Ar___gument ___ ___
525 |
526 ___|___ Type ___Name ___List ___ ___
527
528 ___ ___ Socket * ___Saccept (S___ocket *skt) ___ ___
529
530 ___ ___ void ___Sclose (S___ocket *skt) ___ ___
531
532 ___|___|char| * ___Sgets (c___har *buf, int maxbuf, Socket *skt) ___ ___
533 |
534 ___|___|int| ___Smaskfdisset(i___nt fd) ___ ___
535 |
536 ___|___|void| ___Smaskfdset (___int fd) ___ ___
537
538 ___|___|fd|set|| ___Smaskget (___) ___ ___
539
540 ___|___|int| ___Smaskisset (S___ocket *skt) ___ ___
541 ||
542 ___|___|void ___Smaskpop ___() ___ ___
543
544 ___|___|void|| ___Smaskpush (___) ___ ___
545
546 ___|___|void|| ___Smaskset (___Socket *skt) ___ ___
547
548 ___|___|int|| ___Smasktest (___) ___ ___
549
550 ___|___|void|| ___Smasktime (___long seconds,long useconds) ___ ___
551
552 ___|___|void|| ___Smaskunset (___Socket *skt) ___ ___
553
554 ___|___|void|| ___Smaskunfdset(___int fd) ___ ___
555
556 ___|___|void|| ___Smaskuse (___fd|set usermask) ___ ___
557
558 ___|___|int| ___Smaskwait (___) ___ ___
559 |
560 ___|___|Socket| * ___Sopen (___char *skthost, char *mode) ___ ___
561
562 ___|___|Socket||* ___Sopenv (___char *srvrname,char *ctrl,char *envvar) ___ ___
563
564 ___|___|int| ___Speek (___Socket *skt, char *buf, int buflen) ___ ___
565 ||
566 ___|___|unsigned long_Speeraddr (S___ocket *skt) ___ ___
567 ||
568 ___|___|char * ___Speername (___Socket *skt) ___ ___
569
570 ___|___|void|| ___Sprintf (S___ocket *skt, char *fmt,...) ___ ___
571
572 ___|___|char|| * ___Sprtskt (S___ocket *skt) ___ ___
573
574 ___|___|void|| ___Sputs (___char *buf, Socket *skt) ___ ___
575
576 ___|___|int|| ___Sread (___Socket *skt, char *buf, int buflen) ___ ___
577
578 ___|___|int|| ___Sreadbytes (S___ocket *skt, char *buf, int buflen) ___ ___
579
580 ___|___|int|| ___Srmsrvr (___char *skthost) ___ ___
581
582 ___|___|int| ___Sscanf (S___ocket *skt, char *fmt, ...) ___ ___
583 |
584 ___|___|int| ___Stest (S___ocket *skt) ___ ___
585 |
586 ___|___|int| ___Stimeoutwait(S___ocket *skt,long seconds,long useconds) ___ ___
587
588 ___|___|int|| ___Svprintf (S___ocket *skt, char *fmt, void *args) ___ ___
589
590 ___|___|int| ___Swait (___Socket *skt) ___ ___
591 ||
592 ___|___|int ___Swrite (S___ocket *skt, char *buf, int buflen) ___ ___
593
594
595
596 6
597
598
599
600
601 Socket *Saccept(Socket *skt)
602
603 This function takes a server Socket and produces a Socket which has accepted a con-
604
605 nection. This function may be used as often as wanted on the same server Socket!
606
607 Note that one must have successfully opened a server prior to using Saccept to accept
608
609 connections (see Examples 2.1 and 2.2).
610
611 If this operation is unsuccessful, then Saccept will return a null Socket pointer.
612
613
614 void Sclose(Socket *skt)
615
616 This function closes a Socket of any type (server, client, accept). The Sclose function
617
618 communicates with the local PortMaster whenever a server is closed.
619
620
621 char *Sgets(char *buf, int maxbuf, Socket *skt)
622
623 This is an I/O function which assumes that one has already opened a connected Socket
624
625 (skt). It will attempt to get a null-terminated string from the Socket (up to maxbuf
626
627 characters). This call will block (aka hang, sleep) until a string shows up, but otherwise
628
629 acts much as a fgets() function does.
630
631 If Sgets has a socket error, then a null pointer is returned. Otherwise, it returns the
632
633 \buf" pointer.
634
635
636 int Smaskfdisset(int fd)
637
638 The Smaskfdisset() function works in conjunction with the Smaskwait() function. After
639
640 the Smaskwait() function returns, one can use Smaskfdisset(skt) to test if a particular
641
642 file descriptor is read-ready.
643
644
645 void Smaskfdset(int fd)
646
647 The SmaskXXX functions use a mask of type fd|set internally. Other operations, such
648
649 as use of a serial port under Unix or the GL queue for SGI's Irises (see their qgetfd()
650
651 function) use file descriptors. This function allows one to set up the SmaskXXX mask
652
653 with one or more of those file descriptors.
654
655
656 Smask Smaskget()
657
658 The SmaskXXX functions use a mask of type fd|set internally. Other operations, such
659
660 as use of a serial port under Unix, can also be used to set masks. This function provides
661
662 access to the mask set up by Smaskset. The mate to this function is Smaskuse().
663
664
665 int Smaskisset(Socket *skt)
666
667 The Smaskisset() function works in conjunction with the Smaskwait() function. After
668
669 the Smaskwait() function returns, one can use Smaskisset(skt) to test if a particular
670
671 Socket is read-ready. It is simpler then and thereby faster than Smasktest().
672
673
674 void Smaskpop()
675
676 The Smaskpop() function, along with the Smaskpush() function, allows the program-
677
678 mer to manipulate an internal stack of masks. The \top" mask is the current mask.
679
680
681
682 7
683
684
685
686
687 void Smaskpush()
688
689 The Smaskpush() function, along with the Smaskpop() function, allows the program-
690
691 mer to manipulate an internal stack of masks. The \top" mask is the current mask.
692
693
694 void Smaskset(Socket *skt)
695
696 This function is part of the SmaskXXX group. Sockets may be set up for Smaskwait'ing
697
698 one at a time. Note that all Sockets are effectively OR'ed together for blocking; to clear
699
700 the mask, pass a NULL Socket pointer to Smaskset: Smaskset((Socket *) NULL);.
701
702
703 int Smasktest()
704
705 This function is part of the SmaskXXX group. The Smasktest function supports polling
706
707 { one may determine if anything is on any of the Smaskset Sockets and immediately
708
709 receive a positive integer if there is, a 0 if there isn't, and a negative number if there's
710
711 an error.
712
713
714 void Smasktime(long seconds,long useconds)
715
716 This function is part of the SmaskXXX group. Normally Smaskwait will block \forever"
717
718 (well, at least as long as the machine stays up!). However, one can specify a time limit
719
720 { then Smaskwait will return with a value of 0 if the time limit is exceeded. One may
721
722 specify the time limit in seconds and micro-seconds. To clear the time limit (ie. restore
723
724 Smaskwait to waiting forever), pass a negative time in either or both arguments to
725
726 Smasktime. Waiting forever is also set up when both arguments to Smasktime are
727
728 zero.
729
730
731 void Smaskunfdset(int fd)
732
733 This function is part of the SmaskXXX group. File descriptors may be entered into the
734
735 mask via the Smaskfdset() function, and this function can remove it from the mask.
736
737 This function is similar to the Smaskunset() function.
738
739
740 void Smaskunset(Socket *skt)
741
742 This function is part of the SmaskXXX group. Sockets may be removed from the
743
744 Smaskwait's mask one at a time via this function. Like Smaskset, a Smaskunset((Socket
745
746 *) NULL); will clear the entire mask.
747
748
749 void Smaskuse(Smask usermask)
750
751 This function is part of the SmaskXXX group. The internal mask in SmaskXXX can be
752
753 set up by the user via this function. Often, Smaskset will be used to set up an internal
754
755 mask, Smaskget will be used to obtain the resulting mask, and Smaskuse will be used
756
757 to apply that mask.
758
759
760 int Smaskwait()
761
762 This function is part of the SmaskXXX group. The Smaskwait function will block (aka
763
764 hang) the process until any Socket set via Smaskset has something waiting on it to
765
766 be read. Note that Sockets set by Smaskset are retained; ie. they must be explicitly
767
768 cleared by passing a NULL Socket pointer to Smaskset.
769
770
771
772 8
773 |
774 |
775 ||
776 ||
777 ||
778 ||
779 ||
780 ||
781 ||
782 ||
783 ||
784 ||
785 ||
786 ||
787 |||
788 |||
789 |||
790 |||
791 |||
792 |||
793 |||
794 |||
795 |||
796 |||
797 |||
798 |||
799 |||
800 ||||
801 |||||
802 |||
803 |||
804 |||
805 |||
806 ||||
807 Smaskwait|returns|a|positive|number|if something is waiting on a Socket, zero if a time-
808
809 out occurs,|and|a|negative number on an error.
810 |||
811 ||||
812 Socket *Sopen(char|*skthost,|char|*mode)||
813
814 This function|is|the|workhorse|for|opening|Sockets. Basically, it can make either a server
815
816 or a client|depending|on|the|mode.||
817
818 |||
819 |||
820 ||
821 ___|Mode|| Effect ___
822
823 ___|| s open a server ___
824
825 ___|| S open a server but, on failure, retry after using Srmsrvr ___
826
827 ___|| c open a client ___
828
829 ___||s###open a server with the specified port number ___
830
831 ___|S###like S above, but with the specified port ___
832 |
833 ___| c###open a client to a server with the specified port ___
834
835
836
837 The skthost is the name of the server. If one is making a client Socket, then one may
838
839 optionally use the form \servername@hostname" for the skthost. The \@hostname"
840
841 form is not necessary for clients to servers that are on the same host as the client, as
842
843 the default host is the local host. The \servername@hostname" form makes no sense
844
845 for servers, and so, for opening servers, Sopen will ignore any \@hostname" portion of
846
847 skthost.
848
849 The \S" mode for opening servers, like the \s" mode, will cause Sopen to attempt
850
851 to open a server, but if unsuccessful, Sopen will then use Srmsrvr using the provided
852
853 skthost and then retry opening the server. In the case of s### or S###, the servers are
854
855 set up with the TCP/IP option SO|REUSEADDR. This option alleviates some of the
856
857 difficulties associated with re-starting servers with fixed ports.
858
859 If the skthost is null or an empty string (""), the PortMaster is bypassed. One must
860
861 specify a port number to use in that case. A warning is issued (as well as a null
862
863 Socket*) because that is typically a programming error, not a user error.
864
865 The PortMaster is also always bypassed for clients which specify port number (c###).
866
867 In the latter case, a client connection is immediately attempted to the user-specified
868
869 port number. If the function is not successful, a null Socket pointer is returned.
870
871 If the user-specified server port mode is used with a skthost, the server will be registered
872
873 with its PortMaster; clients need not use specified-port mode to connect (ie. they may
874
875 set mode to "c") so long as they specify the correct name of the server.
876
877 PortMaster sharing (by setting the environment variable PMSHARE) causes servers to
878
879 work with the PMSHARE-specified machine's PortMaster. Clients should use the name
880
881 of the machine that the PortMaster is on; the eventual connection will be made with
882
883 the appropriate server program, even though it is running on a different machine than
884
885 the PortMaster it uses. See Example 3.1 for an illustration of how PortMaster sharing
886
887 works.
888
889
890
891 9
892
893
894
895
896 Socket *Sopenv(char *srvrname,char *ctrl,char *envvar)
897
898 The Sopenv function is used to open client Sockets, but is formulated to resemble
899
900 the Sopen function with one additional argument. Assuming your computer system
901
902 supports the concept of environment variables, the Sopenv function can use an en-
903
904 vironment variable of your choice to help it open a client. Typically, a SKTPATH
905
906 environment variable gets set up by the user with a colon-separated list of machine
907
908 names (ex. setenv SKTPATH \gryphon:dragon:xorn"). The Sopenv function attempts
909
910 to open a client to a server of the given name on the current machine first, and then
911
912 attempts to do so on each machine in the given sequence. If env_var is NULL or a null
913
914 string, then SKTPATH will be used instead.
915
916 If successful, a Socket pointer is returned, otherwise a NULL Socket pointer is returned.
917
918 Please see Saccept on how to use servers.
919
920
921 int Speek(Socket *skt, char *buf, int buflen)
922
923 The Speek function behaves like Sread | up to buflen bytes, the buffer will be filled
924
925 by whatever is currently on the Socket. This function does not remove those bytes
926
927 from the Socket, however, and those bytes will be returned again on subsequent Speek,
928
929 Sread, etc. calls. This function does not||block (aka hang, sleep).
930
931 It will return EOF on select error, some negative number on recv error, zero if no data
932
933 is present on the Socket, and a positive count of the available bytes otherwise. In the
934
935 latter case, buf will have a copy of the bytes available.
936
937 MS-DOS: Speek will only return a 1 when data is available on the Socket, not the
938
939 number of bytes available. Furthermore, the buffer buf will be a zero-length string
940
941 with just a null byte.
942
943
944 unsigned long Speeraddr(Socket *skt)
945
946 The Speeraddr function returns the internet address of the peer Socket.
947
948
949 char *Speername(Socket *skt)
950
951 The Speername function returns the name of the peer Socket. Internally, it has three
952
953 buffers; thus it can be used up to three times in the same printf statement.
954
955
956 void Sprintf(Socket *skt, char *fmt,...)
957
958 The Sprintf function acts in an analogous fashion to fprintf, sprintf, etc, by putting
959
960 formatted strings, appropriately null byte terminated, through the Socket. Thus, one
961
962 may use either Sgets or an appropriate Sscanf to receive the information.
963
964
965 char *Sprtskt(Socket *skt)
966
967 The Sprtskt function returns a string describing the Socket.
968
969
970 void Sputs(char *buf, Socket *skt)
971
972 The Sputs function puts a null byte terminated string on the Socket in a fashion
973
974 analogous to fputs.
975
976
977
978 10
979
980
981
982
983 int Sread(Socket *skt, char *buf, int buflen)
984
985 The Sread function is similar to the read function in Unix. This function can block
986
987 (aka hang, sleep) if nothing is on the Socket. Otherwise, it will return up to buflen
988
989 bytes in the buffer \buf". This function will return whatever is on the Socket, and
990
991 doesn't try to insure that buflen bytes are read. It returns the number of bytes read
992
993 from the Socket.
994
995 On error, an EOF is returned.
996
997
998 int Sreadbytes(Socket *skt, char *buf, int buflen)
999
1000 The Sreadbytes function behaves much like Sread, and it too can block (aka hang,
1001
1002 sleep) if nothing is on the Socket. However, it will not return until buflen bytes are
1003
1004 read from the Socket and placed in \buf".
1005
1006 On error, an EOF is returned.
1007
1008
1009 int Srmsrvr(char *skthost)
1010
1011 The Srmsrvr function is made available to take care of those situations when skt =
1012
1013 Sopen(\servername",\s") fails because the servername has been inadvertently left in the
1014
1015 PortMaster's PortTable. This untoward event can happen, for example, when a process
1016
1017 is aborted/exited without calling Sclose on its server(s). The Srmsrvr function will
1018
1019 remove a server (or server@host) from the PortMaster's PortTable. Note: it will not||
1020
1021 close the associated Socket, nor free up any Socket memory, and is not||a substitute for
1022
1023 Sclose.
1024
1025 The Srmsrvr function will return either PM|OK (if successful) or PM|SORRY (other-
1026
1027 wise).
1028
1029
1030 int Sscanf(Socket *skt, char *fmt, ...)
1031
1032 The Sscanf function acts much the same as sscanf and fscanf, taking format strings and
1033
1034 additional arguments in a like manner. The arguments Sscanf takes, of course, must
1035
1036 all be appropriate pointers. This function will block if insufficient data is available on
1037
1038 the socket according to the fmt.
1039
1040 The Sscanf function returns the number of arguments for which it read data, which
1041
1042 may be zero or incomplete if a socket error occurred. Normally, the returned count
1043
1044 should equal the number of arguments with which Sscanf was provided.
1045
1046
1047 int Stest(Socket *skt)
1048
1049 The Stest function allows one to determine if anything is available on the specified
1050
1051 Socket, without blocking.
1052
1053 It will return EOF on select error, some negative number on recv error, zero if no data
1054
1055 is present on the Socket, and a positive count of the available bytes otherwise.
1056
1057 MS-DOS: Stest will only return a 1 when data is available on the Socket, not the number
1058
1059 of bytes available.
1060
1061
1062
1063 11
1064
1065
1066
1067
1068 int Stimeoutwait(Socket *skt,long seconds,long useconds)
1069
1070 The Stimeoutwait function blocks on the given Socket, but for no longer than the
1071
1072 number of seconds plus the number of microseconds specified. The function returns
1073
1074 the number of bytes available on the Socket (which may be zero), -1 if there was an
1075
1076 error, and -2 on timeout.
1077
1078
1079 int Svprintf(Socket *skt, char *fmt, void *args)
1080
1081 The Svprintf function reads bytes using a printf family format string from the Socket.
1082
1083 As each format code is processed, the associated argument is changed in the args vector.
1084
1085 It returns the number of format items processed.
1086
1087
1088 int Swait(Socket *skt)
1089
1090 The Swait function will block (aka hang, sleep) until the specified Socket has data
1091
1092 available.
1093
1094 It will return EOF on select error, some negative number on recv error, zero if no data
1095
1096 is present on the Socket, and a positive count of the available bytes otherwise.
1097
1098
1099 int Swrite(Socket *skt, char *buf, int buflen)
1100
1101 The Swrite function will write buflen bytes from the buf buffer onto the specified Socket.
1102
1103 The function will return a count of the number of bytes transmitted through the Socket,
1104
1105 which should be equal to buflen. If the output is less than buflen, then an error occurred
1106
1107 while writing to the Socket.
1108
1109
1110
1111 2.3 Hints
1112
1113
1114 The Hints below have been found useful at the Intelligent Robotics Laboratory at the God-
1115
1116 dard Space Flight Center. They are based on almost a year's experience with the SSL.
1117
1118
1119 1.The \Sscanf" function is dangerous. It will block until all of the format codes in its fmt
1120
1121 string have been used. If somehow a programmer sends an improper string and Sscanf
1122
1123 is used to receive it, then the receiving program will probably hang for quite a while.
1124
1125 Dr. Campbell has found that it is somewhat safer to use Sgets to get an entire string
1126
1127 from the Socket and then use sscanf and stpnxt to parse it.
1128
1129
1130 2.Polling is unfriendly to other processes { it wastes a tremendous amount of CPU
1131
1132 time merely querying the Socket(s) to see if anything is awaiting action. The various
1133
1134 blocking functions are much better: Swait, Stimeoutwait, SmaskXXX, etc.
1135
1136
1137 3.Unless your processes will always run on the same kind of machine, portability con-
1138
1139 siderations argue against using Sread and Swrite to move non-character string data
1140
1141 around { ie. floats, doubles, and even ints. Even if the programmer tests out the ma-
1142
1143 chines and verifies that (s)he can safely move, say, a double around, or even a vector
1144
1145 of doubles, data structures (struct XXX { ... }) may have \holes" in them placed
1146
1147 there for word or byte alignment reasons. These \holes" may not be there (or may be
1148
1149 placed differently) by other machines and compilers.
1150
1151
1152
1153 12
1154
1155
1156
1157
1158 4.The Srmsrvr function is a rather rude function { there is no ownership check of a server.
1159
1160 Please use your process name (or your id) as part of your server name so that servers
1161
1162 do not clash. Remember: your server's name is in only one \name space" shared by
1163
1164 all users on your machine.
1165
1166
1167 5.For those of you who wish to use other services (ex. serial ports) which can use the
1168
1169 select function provided by TCP/IP , check out Smaskfdset and its mate, Smaskunfdset.
1170
1171
1172 6.The IRL has been using a leading two character command convention:
1173
1174 tp~L~x~y~z rx ry rz will tell the \left" T3 robot to move to \x y z" (inches) in space
1175
1176 with an orientation of \rx ry rz" degrees (roll, pitch, yaw). Longer words provide more
1177
1178 readability but take up more bandwidth. Experimentally, Dr. Campbell has found
1179
1180 that TCP/IP can transfer about 10,000 packets per second with up to 128 bytes in a
1181
1182 packet. Loaded systems will, of course, achieve less throughput.
1183
1184
1185 7.It is a good idea for clients to inform servers that they are quitting. The IRL has
1186
1187 used the following convention: tq tells the server that the messaging client is quitting.
1188
1189 Also, a tQ tells the server to shut itself down. The server then emits a tq to all of its
1190
1191 clients to inform them that the server is shutting down (except for the one client who
1192
1193 issued the shutdown command), and then closes itself down with Sclose.
1194
1195
1196 8.The server-client relationship is intimately involved with object-oriented messaging {
1197
1198 refer to the literature on object-oriented concepts.
1199
1200
1201 9.The SSL can be used to support a no startup sequencing paradigm. Typically, clients
1202
1203 who attempt to Sopen and fail should go into a poll - sleep loop:
1204
1205
1206
1207 Example 2.5 Client Socket Polling
1208
1209 skt= Sopen("servername","c");
1210
1211 while(!skt) {
1212
1213 sleep(1);
1214
1215 skt= Sopen("servername","c");
1216
1217 }
1218
1219
1220
1221 The multiskt.c program illustrates how servers should be able to accept multiple clients
1222
1223 using blocking judiciously.
1224
1225 This non-sequencing approach allows one to bring up programs which have servers
1226
1227 and/or clients without worrying about what comes first. For two programs, this isn't
1228
1229 terribly serious, but at the IRL numerous programs providing numerous services are
1230
1231 available and sequencing would be a nightmare.
1232
1233
1234 10.As alluded to earlier, clients should tell servers and servers should tell clients when they
1235
1236 are going down. The program that is not quitting should return to an \awaiting another
1237
1238 client (or server)" mode (ie. see the preceding item). Thus, a troublesome program can
1239
1240 be brought down, the programs to which it is communicating will gracefully terminate
1241
1242
1243
1244 13
1245
1246
1247
1248
1249 their connections, and the programmer can then (hopefully) fix the problem. When the
1250
1251 program is restarted, the non-sequencing approach will allow the program to seamlessly
1252
1253 re-enter into communications with the other software.
1254
1255
1256 11.When a machine is down, and an attempt to connect a client Socket using either Sopen
1257
1258 directly or Sopenv to a server either normally or possibly on that machine, the Sopen
1259
1260 will fail but will take an inordinately long time doing so (connection timeout).
1261
1262
1263 12.When a program dies abruptly, connected Sockets appear to select() to have something
1264
1265 on them (select is used by Stest, Smasktest, Swait, Smaskwait, Speek, Stimeoutwait).
1266
1267 Hence, functions which normally block (Smaskwait, Swait) no longer block. On com-
1268
1269 puters which can MSG|PEEK (Unix, Vms), the Stest, Speek, Sgets, and Sscanf func-
1270
1271 tions will detect this situation and will return an error indication (EOF, NULL pointer,
1272
1273 incomplete argument processed count) to indicate that the Socket has a problem (one
1274
1275 should then Sclose the affected Socket).
1276
1277 Furthermore, attempts to write to such dead Sockets may generate SIGPIPEs on Unix
1278
1279 boxes. Unix programmers should write and install signal handlers for SIGPIPEs.
1280
1281
1282 13.For multiple concurrent Sockets, one should generate routines for both closing and
1283
1284 opening them.
1285
1286
1287
1288 Example 2.6 Client Opening Function
1289
1290 #include "sockets.h"
1291
1292 typedef struct clientlist_str ClientList;
1293
1294 struct clientlist_str {
1295
1296 Socket *skt;
1297
1298 ClientList *nxt,*prv;
1299
1300 }
1301
1302 ClientList *clhd=NULL;
1303
1304 ClientList *cltl=NULL;
1305
1306 ...
1307
1308 ClientList *openClient(char *srvrname)
1309
1310 {
1311
1312 Socket *skt;
1313
1314 ClientList *clist;
1315
1316 while(1) {
1317
1318 skt= Sopen(srvrname,"c");
1319
1320 if(!skt) sleep(1);
1321
1322 }
1323
1324 clist= (ClientList *) malloc(sizeof(ClientList));
1325
1326 if(cltl) cltl->nxt= clist;
1327
1328 else clhd = clist;
1329
1330 clist->prv= cltl;
1331
1332 clist->nxt= NULL;
1333
1334
1335
1336 14
1337
1338
1339
1340
1341 cltl = clist;
1342
1343 Smaskset(skt);
1344
1345 clist->skt= skt;
1346
1347 return clist;
1348
1349 }
1350
1351
1352
1353 The openClient() function polls once a second in attempting to open a client Socket.
1354
1355 Once it succeeds, a ClientList data structure is allocated, double-linked, and a pointer
1356
1357 to it returned. In addition, the new client Socket is added to the Smask.
1358
1359
1360
1361 Example 2.7 Client Closing Function
1362
1363 void closeClient(ClientList *clist)
1364
1365 {
1366
1367 if(clist) {
1368
1369 Smaskunset(clist->skt);
1370
1371 Sclose(clist->skt);
1372
1373 clist->skt= NULL;
1374
1375 }
1376
1377 }
1378
1379
1380
1381 The closeClient() function removes the client Socket from the Smask system, closes
1382
1383 the Socket, and then sets the skt pointer to NULL to guarantee that the now dead
1384
1385 socket won't be inadvertently re-used somehow.
1386
1387
1388 14.It is usually advisable to use some sort of handshaking protocol between server and
1389
1390 client, especially when large data blocks are being moved. The TCP/IP buffers can
1391
1392 easily get filled and data get lost otherwise. To facilitate this, the SSL sets sockets up
1393
1394 with the TCP|NODELAY option so that small packets are moved out across and not
1395
1396 collected (collection of small packets normally improves network efficiency since there's
1397
1398 less overhead per byte of data).
1399
1400
1401
1402 15
1403
1404
1405
1406
1407 3 The PortMaster
1408
1409
1410 Servers have names provided by the program which opens them. When a server is to be
1411
1412 opened, the Sopen function temporarily opens a Socket to the PortMaster running on the
1413
1414 same machine. The Sopen function then tells the PortMaster the server's name and the (ran-
1415
1416 dom) port assigned to the new server, and then closes down the connection. The PortMaster
1417
1418 retains a list of all active servers and ports running on its machine.
1419
1420 A client is opened using the Sopen function, too. In that case, a connection is made to
1421
1422 the PortMaster on the machine where the requested server is running. The PortMaster then
1423
1424 tells the Sopen function the port number associated with the requested server, and then
1425
1426 closes down the temporary connection. The Sopen function then attempts to connect to the
1427
1428 server using the given port.
1429
1430 The server program can use its server Socket to test if any clients are waiting to be
1431
1432 connected to it (via the Stest function). If a client is waiting, then the server's program
1433
1434 can accept the connection, generating an accept Socket (via Saccept). Once the connection
1435
1436 is accepted, the program attempting to open the client Socket will finally receive a Socket
1437
1438 pointer.
1439
1440
1441
1442 3.1 Users Guide
1443
1444
1445 The PortMaster is probably the simplest program to run: under UNIX, type Spm & and
1446
1447 under VMS type run/detach Spm. The PortMaster will only allow one copy of itself to run
1448
1449 on any given computer. It uses a fixed port address (1750, now registered with IANA) and
1450
1451 implements a table of server names mapping to random ports. Although knowledgeable users
1452
1453 could change the PortMaster's fixed port, this is discouraged: hopefully, PortMasters will
1454
1455 proliferate across the world and, if they all use the same port on their machines, will be able
1456
1457 to communicate with one another. In other words, the SSL will be unable to communicate
1458
1459 with other SSL systems which use a different port for its PortMaster.
1460
1461 Since MS-DOS is not a multi-tasking operating system, unlike UNIX, VMS, or Amiga-DOS,
1462
1463 one cannot have a PortMaster running in the background | there is no background. Hence,
1464
1465 MS-DOS programs are currently restricted to using client Sockets only, unless they can share
1466
1467 another machine's PortMaster (see below).
1468
1469 The PortMaster now supports a firewall: one can instruct the PortMaster to restrict
1470
1471 access to a group of machines by their host addresses. See the section on The PortMaster
1472
1473 Firewall below.
1474
1475
1476
1477 3.2 Sharing PortMasters
1478
1479
1480 PortMasters can now be shared. This feature was installed mainly to support MSDOS {
1481
1482 since it doesn't have a background process capability, it cannot run PortMasters. Hence,
1483
1484 it is normally restricted to running clients only, because servers normally announce their
1485
1486 presence to their host's PortMaster. If the environment variable PMSHARE is set to some other
1487
1488 machine, that other machine's PortMaster will be used by the host's processes attempting
1489
1490
1491
1492 16
1493 |
1494 |
1495 |
1496 |
1497 ||
1498 ||
1499 ||
1500 ||
1501 ||
1502 ||
1503 ||
1504 ||
1505 ||
1506 ||
1507 ||
1508 ||
1509 ||
1510 ||
1511 ||
1512 ||
1513 ||
1514 ||
1515 ||
1516 ||
1517 ||
1518 ||
1519 ||
1520 ||
1521 ||
1522 ||
1523 ||
1524 ||
1525 ||
1526 ||
1527 ||||
1528 ||
1529 ||
1530 ||
1531 |||
1532 |||
1533 to|open|servers.|From the client's viewpoint, the server appears to be on the machine with
1534 ||
1535 the|PortMaster|{|the|client doesn't need to know about where the server actually is.
1536 |||
1537 ||||
1538 Example|3.1|||PortMaster|Sharing
1539 ||
1540 ___|| Machine ___Machine ___ Machine ___
1541 ||
1542 ___||| A ___ B ___ C ___
1543
1544 ___|| ___ ___ ___
1545
1546 ___|PMSHARE=machineb|___ ___ ___
1547
1548 ___|| ___ ___ ___
1549
1550 ___|opens server ASrvr ___ ___ ___
1551 |
1552 ___| ___ ___ ___
1553 |
1554 ___| B'___s PortMaster ___ ___
1555
1556 ___|| no___w has ASrvr ___ ___
1557
1558 ___|| on___its list ___ ___
1559
1560 ___|| ___ ___ ___
1561
1562 ___|| ___ ___pgm opens client ___
1563
1564 ___|| ___ ___to ASrvr@machineb ___
1565
1566 ___|| ___ ___ ___
1567
1568 ___|| B'___s PortMaster ___ ___
1569
1570 ___|| sa___tisfies ___ ___
1571
1572 ___|| cl___ient's request ___ ___
1573
1574 ___|| ___ ___ ___
1575
1576 ___| ___ ___pgm has client to ___
1577 |
1578 ___| ___ ___ASrvr on A ___
1579
1580
1581 In Example 3.1, three machines are in use. However, machines B and C could have been
1582
1583 the same machine. In essence, when A shares B's PortMaster, the servers on A appear to be
1584
1585 on B insofar as Sopen'ing a client is concerned. Internally, of course, B's PortMaster knows
1586
1587 where the ASrvr is, and clients end up being connected to the server on machine A.
1588
1589
1590
1591 3.3 Theory of Operation
1592
1593
1594 Normally, users of the SSL will not need to read this section. However, for those who are
1595
1596 curious...
1597
1598 There are two main benefits to using the SSL: the functions are similar to those that
1599
1600 the C programmer already knows how to use and hence the SSL has a rapid learning curve,
1601
1602 and second, servers are assigned to currently available ports. The PortMaster is integral to
1603
1604 providing the second benefit.
1605
1606 Berkeley sockets are assigned ports, which are basically just integers. The port is used
1607
1608 internally to assign the flow of data to the correct places. One must assign a specific port
1609
1610 to a server or, alternatively, allow the system to assign any available port to it. Clients must
1611
1612 use that same port number to connect to the desired server. Hence, the problem with using
1613
1614 the \any available port" is how to get the client process to know what the currently assigned
1615
1616 port is! Programmers using Berkeley sockets have typically just assigned a fixed port to
1617
1618
1619
1620 17
1621
1622
1623
1624
1625 their server and hard-coded the clients with that port. If some other process just happens
1626
1627 to use that same port, then things get messy { re-compile, wait until the other process goes
1628
1629 away, etc. On a machine where there are many users, co-operation between the users may
1630
1631 be impractical.
1632
1633 The PortMaster solves the problem of associating a server name with a randomly assigned
1634
1635 (and available) port, and making that association available to clients. The PortMaster itself
1636
1637 uses a fixed port, and so servers and clients always know \where" it is. Whenever a server
1638
1639 opens (using the Sopen("XXX","s") call), the Sopen function makes a Socket data structure,
1640
1641 creates a Berkeley socket, initializes and binds the socket with any available port, and then
1642
1643 connects to the PortMaster, using its fixed port. It then sends a \message" (PM|SERVER,
1644
1645 which is simply an integer) to the PortMaster, telling it the type of Socket it is. Subsequently,
1646
1647 the PortMaster gets the new server's name and the port it is assigned to.
1648
1649 When a client opens, it makes a Socket, initializes a Berkeley socket as a client (using
1650
1651 the AF|INET format), gets a \host" entity pointer (the server's machine is known as a host),
1652
1653 and then connects to the PortMaster on the host machine. It then sends a \PM|CLIENT"
1654
1655 to that PortMaster and the desired server's name; that PortMaster will respond with the
1656
1657 associated port number (if there is one). The client then closes down the connection to
1658
1659 the target host's PortMaster, and initializes a Berkeley socket with the port number it just
1660
1661 received and returns a client Socket pointer to the user.
1662
1663 Thus, the SSL's PortMaster system is a distributed database. There are advantages and
1664
1665 disadvantages to this scheme. No PortMaster knows anything about servers residing on other
1666
1667 machines; if a machine goes down, other machines which have no need to communicate with
1668
1669 the downed machine are not affected.
1670
1671 On the other hand, a single machine with a single PortMaster would obviate the need
1672
1673 for clients to know what machines they wish to connect to, and could force servers on
1674
1675 all machines to have unique names (as it is, servers can have the same name so long as
1676
1677 they run on different machines). As a palliative, the Sopenv function supports the concept
1678
1679 of a machine path via the use of environment variables. Using the Sopenv function, clients
1680
1681 can \hunt" down a given server by attempting to open a client one at a time on each machine
1682
1683 until a server of that name is found. Thus, the user can designate a local group of machines
1684
1685 via an environment variable (typically, the \SKTPATH" environment variable is used for this
1686
1687 purpose).
1688
1689 The PortMaster talks to its temporary clients using a relatively simple protocol based on
1690
1691 \messages" (integers) defined in the sockets.h header file. Table 3 illustrates the protocol.
1692
1693 If the PortMaster is using its firewall capability, it immediately checks all of its temporary
1694
1695 clients for approved machine status; a PM|SORRY is issued immediately prior to the protocol
1696
1697 in Table 3 upon failure to be approved. The connection is then summarily severed.
1698
1699 As indicated in Table 3, the PortMaster handles more events than just the PM|SERVER
1700
1701 and PM|CLIENT events mentioned earlier. When a client opens to the PortMaster, it iden-
1702
1703 tifies the type of service it wishes by sending that PortMaster a \message": PM|SERVER,
1704
1705 PM|CLIENT, PM|CLOSE, PM|TABLE, or PM|QUIT. These messages are discussed below.
1706
1707 Whenever the PortMaster does not understand the initial message (due to garbling or what-
1708
1709 ever), the PortMaster will immediately issue a PM|RESEND message and then wait for
1710
1711
1712
1713 18
1714 ||
1715 ||
1716 |||
1717 ||||
1718 ||||
1719 ||||
1720 ||||
1721 ||||
1722 ||||
1723 ||||
1724 ||||
1725 ||||
1726 |||||
1727 |||||
1728 |||||
1729 |||||
1730 |||||
1731 |||||
1732 |||||
1733 |||||
1734 ||||||
1735 ||||||
1736 ||||||
1737 ||||||
1738 ||||||
1739 ||||||
1740 |||||||
1741 |||||||
1742 ||||||||||
1743
1744 |||||||||||
1745 |||||||
1746 |||||||
1747 ||||||||
1748 ||||||||
1749 ||||||||
1750 ||||||||
1751 |||||||||||
1752
1753 ||||||||Table|3:|The|PortMaster|Protocol|
1754 ||||||||
1755 |||||||||
1756 |||||||
1757 ___|___||||EventClie___nt|SendsPo___rtMaster Sends ___ ___
1758 ||||||
1759 ___|___|PM|CLIENT||___||| ___ ___ ___
1760 ||
1761 ___|___|||||||||||| ___ ___PM|OK / PM|RESEND ___ ___
1762
1763 ___|___||||||||"sktn___ame"||||___ ___ ___
1764 |
1765 ___|___||||||| ___ ___PM|OK / PM|SORRY ___ ___
1766 |||||||
1767 ___|___|||||||| ___ ___port ___ ___
1768 |||
1769 ___|___|PM|CLOSE||___||||| ___ ___ ___
1770 |||
1771 ___|___|||||||| ___ ___PM|OK / PM|RESEND ___ ___
1772 ||
1773 ___|___|||||| port ___ ___ ___ ___
1774 ||||||
1775 ___|___||||||| ___ ___PM|OK / PM|SORRY ___ ___
1776
1777 ___|___|PM|QUIT||||___|||| ___ ___ ___
1778
1779 ___|___|||||| ___ ___PM|OK / PM|RESEND ___ ___
1780 |||||
1781 ___|___|||||| "Port___Master" ___ ___ ___
1782
1783 ___|___|PM|SERVER|___||||| ___PM|OK / PM|RESEND ___ ___
1784
1785 ___|___||||||| "sktn___ame" ___ ___ ___
1786
1787 ___|___||| port ___ ___ ___ ___
1788 ||||
1789 ___|___|||||| ___ ___PM|OK / PM|SORRY ___ ___
1790
1791 ___|___|PM|TABLE||___|| ___ ___ ___
1792
1793 ___|___|||| ___ ___PM|OK / PM|RESEND ___ ___
1794 |
1795 ___|___|||| ___ ___count of servers ___ ___
1796
1797 ___|___||| ___ ___"server : port" ___ ___
1798 |||
1799 ___|___|| ___ ___... ___ ___
1800 ||
1801 ___|___|PM|FWINIT ___ ___ ___ ___
1802 ||
1803 ___|___| ___ ___PM|OK / PM|RESEND ___ ___
1804
1805
1806
1807 data. It will continue doing so for up to PM|MAXTRY times (in the sockets.h file as
1808
1809 sent, PM|MAXTRY is defined as 20). If the limit of re-tries is reached, the PortMaster will
1810
1811 peremptorily close down the connection and go back to its usual quiescent state waiting
1812
1813 for a new connection.
1814
1815 The PortMaster will wait no more than TIMEOUT seconds for data, which is set to 20
1816
1817 seconds in Spm.c as delivered. If that amount of time elapses, the PortMaster will summarily
1818
1819 close down the temporary client and continue for more business.
1820
1821
1822
1823 PM|CLIENT tells the PortMaster that a client is attempting to open. The PortMaster
1824
1825 normally responds with a PM|OK and the program attempting to open a client responds
1826
1827 with a null-byte terminated string (the requested server name). If the PortMaster
1828
1829 finds the requested server in its list, then it responds with a PM|OK and then the port
1830
1831 number, otherwise it sends a PM|SORRY.
1832
1833
1834
1835 19
1836
1837
1838
1839
1840 If the PortMaster is using a firewall, it may respond immediately with a PM|SORRY
1841
1842 if the client is originating from an unapproved machine.
1843
1844
1845 PM|CLOSE tells the PortMaster that a server is closing down. The PortMaster will normally
1846
1847 respond with a PM|OK; the program closing down the server (via Sclose) will then
1848
1849 send the port number. The PortMaster will then remove the associated server from its
1850
1851 internal list of servers and respond with a PM|OK if the designated server was in its
1852
1853 list and a PM|SORRY otherwise.
1854
1855
1856 PM|FWINIT tells the PortMaster to re-read its firewall datafile. The PortMaster will then
1857
1858 respond with a PM|OK if it worked or PM|RESEND if something got garbled.
1859
1860
1861 PM|QUIT tells the PortMaster that a shutdown command is to be sent. The PortMaster
1862
1863 responds with a PM|OK, and the program shutting down the PortMaster issues a null-
1864
1865 byte terminated string, \PortMaster" (just to guarantee that a shutdown is really
1866
1867 wanted). The PortMaster will then shutdown. This operation requires some knowledge
1868
1869 of the protocol as no SSL function is provided to make shutting down the PortMaster
1870
1871 easy. However, the sktdbg program does provide an easy way to shut down the Port-
1872
1873 Master. Concerned system administrators may wish to remove the \shut" command
1874
1875 from sktdbg. Shutting down the PortMaster does not affect currently connected Sock-
1876
1877 ets; however, new connections between servers and clients cannot be made. On the
1878
1879 other hand, starting up a new PortMaster is easy and anyone may do so { the Spm
1880
1881 program itself will refuse to allow two PortMasters to run concurrently (and will say
1882
1883 so).
1884
1885
1886 PM|SERVER tells the PortMaster that a server has been opened. The PortMaster will nor-
1887
1888 mally respond with a PM|OK and then the program opening a server will send a string
1889
1890 giving the new server's name and then will send its port.
1891
1892 The PortMaster will then respond with a PM|OK upon success or a PM|SORRY
1893
1894 if a server by that name already exists.
1895
1896 If the PortMaster is using a firewall, it may respond immediately with a PM|SORRY
1897
1898 if the server is originating from an unapproved machine. When PortMaster sharing
1899
1900 is not operating, this event should never occur, as servers can then only be legally
1901
1902 generated on the same machine that the PortMaster resides upon. The PortMaster
1903
1904 enters its own host onto its internal firewall table whenever use of a firewall is enabled.
1905
1906
1907 PM|TABLE tells the PortMaster to give out a list of the servers it currently knows about.
1908
1909 Normally the PortMaster will respond with a PM|OK, a count of servers (in network
1910
1911 standard 2-byte format, see the Berkeley \ntohs" function for details), and a sequence
1912
1913 of strings giving the server name and associated port number. The spmtable program
1914
1915 and sktdbg's \table" function use this facility.
1916
1917
1918
1919 20
1920
1921
1922
1923
1924 3.3.1 The PortMaster Firewall
1925
1926
1927 The PortMaster supports a firewall to keep out socket requests from unapproved machines.
1928
1929 The firewall consists of a list of machines' internet addresses in a file. One specifies the file
1930
1931 by one of two methods:
1932
1933
1934
1935 1.Startup with Spm -ffull-path-to-filename
1936
1937
1938 2.Initialization of an environment variable, SPMFIREWALL, to the full-path-to-filename.
1939
1940
1941
1942 The full-path-to-filename file contains records of the form:
1943
1944
1945 * * number number number number
1946
1947
1948 where the four numbers are the internet addresses of the machines permitted to talk to
1949
1950 the PortMaster. The * indicates accept any number in that field. The firewall function
1951
1952 examines incoming internet addresses by use of the getpeername function.
1953
1954 The firewall file, often called spmfirewall.dat, may contain blank lines. The # is assumed
1955
1956 to begin a comment and is stripped off.
1957
1958
1959
1960 21
1961
1962
1963
1964
1965 4 The Utilities
1966
1967
1968 There are several utilities provided with the SSL, and they are explained below. These are
1969
1970 all complete programs in themselves, and can serve as lessons on how to use the SSL.
1971
1972
1973 sktdbg server-name {s|c}
1974
1975 sktdbg is the SSL's testing program. One may open server Sockets, accept Sockets, and
1976
1977 client Sockets, test out how other program's Sockets are communicating, etc. See the
1978
1979 subsection on sktdbg below. The \server-name" may take two forms: servername or
1980
1981 servername@machine-name. The latter form may be used when attempting to open
1982
1983 clients to servers residing on machines other than the one the user is currently running
1984
1985 sktdbg on.
1986
1987
1988 spmchk [machine]
1989
1990 This program tests the current machine by default, the named machine otherwise, for
1991
1992 the presence of a PortMaster. It will return a 0 if the PortMaster is present, or a 1
1993
1994 otherwise, and is useful in scripts:
1995
1996
1997
1998 spmchk || (nohup Spm > /dev/null &)
1999
2000
2001
2002 Translated for non-csh/ksh users: if spmchk finds no PortMaster on the current ma-
2003
2004 chine, start one up in the background in \no hangup on user exit" mode, with output
2005
2006 headed to the bit bucket. (thanks go to Marty Olevitch for this program).
2007
2008 For VMS users:
2009
2010
2011 spmchk:= [fullpath]spmchk.exe
2012
2013 set noon
2014
2015 spmchk
2016
2017 if '$SEVERITY' .ne. 1 then run/detach [fullpath]Spm.exe
2018
2019 set on
2020
2021
2022
2023 spmtable [machine [machine [machine ...]]]
2024
2025 This program lists the servers and port numbers on the requested machines. If no
2026
2027 machine is listed, then the current machine will be used.
2028
2029
2030 srmsrvr [server-name [server-name [server-name ...]]]
2031
2032 Sometimes the all-knowledgeable and omnipotent programmer finds a need to hit the
2033
2034 control-c key or otherwise kill a running program with a server Socket. In such cases,
2035
2036 the PortMaster does not get informed that the server has gone down. This utility will
2037
2038 tell the PortMaster to forcibly remove the named server(s) from its list.
2039
2040
2041 Except when using sktdbg to open a server with sktdbg, the server names above can
2042
2043 also have the form srvr@machine-name. This name specifies a server on a specific ma-
2044
2045 chine. Note that the machine-name is its normal abbreviation (ie. gryphon) or its full name
2046
2047 (ie. gryphon.gsfc.nasa.gov).
2048
2049
2050
2051 22
2052
2053
2054
2055
2056 4.1 The sktdbg Program
2057
2058
2059 The sktdbg program was originally a testing facility to debug the SSL itself, but has proven
2060
2061 exceptionally useful in debugging programs which use the SSL. Consequently, it is provided
2062
2063 as part of the package.
2064
2065 To start up sktdbg, one must choose between starting up a server or attempting to
2066
2067 open a client Socket.
2068
2069
2070
2071 Example 4.1 Starting up a sktdbg Server
2072
2073 sktdbg servername s
2074
2075
2076
2077 Example 4.2 Starting up a sktdbg Client
2078
2079 sktdbg servername c
2080
2081
2082
2083 One may also ask sktdbg to explain itself.
2084
2085
2086
2087 Example 4.3 sktdbg Explanation
2088
2089 sktdbg "?"
2090
2091
2092
2093 When the sktdbg program is started, the first thing it does is attempt to create the
2094
2095 requested type of Socket. Typically, attempts to make a server will succeed; if it doesn't, it
2096
2097 will report a warning, apply Srmsrvr(), and try a second time to open the server again. If it
2098
2099 fails twice, then usually the PortMaster is not running on your machine.
2100
2101 Attempts to open a client to a non-existent server also yields an error message: \unable
2102
2103 to Sopen(srvrname,c)". If the server is up and running, then a client Socket will be set up.
2104
2105 The sktdbg program then prints out a little menu of actions that the user can take with
2106
2107 it.
2108
2109 The \Enter" prompt now also shows the number of bytes waiting on the queue for reading.
2110
2111 This number is updated only when the prompt is generated; ie. it is not a dynamic value,
2112
2113 but is often useful.
2114
2115 In Table 4, there are 20 commands available, and are described below.
2116
2117
2118
2119 accept
2120
2121 Used by a server Socket to accept clients. Note that one may first do test to determine
2122
2123 if a client is waiting.
2124
2125
2126 close
2127
2128 Used by a server Socket to close down an accept Socket.
2129
2130
2131 fput
2132
2133 This function takes a filename, fput filename, which sktdbg then opens. Every line in
2134
2135 it, minus trailing white space, is sent via Sputs across the Socket. Sktdbg then closes
2136
2137 the file.
2138
2139
2140
2141 23
2142
2143
2144
2145
2146 Table 4: sktdbg Help Menu
2147
2148 Socket Test Commands
2149
2150 accept
2151
2152 close
2153
2154 fwinit
2155
2156 fput
2157
2158 get
2159
2160 menu
2161
2162 peek
2163
2164 printf
2165
2166 put
2167
2168 q
2169
2170 quit
2171
2172 read
2173
2174 rmsrvr
2175
2176 scanf
2177
2178 shutdown
2179
2180 table
2181
2182 test
2183
2184 wait
2185
2186 write
2187
2188 ?
2189
2190 ( 0 bytes) Enter:
2191
2192
2193
2194 fwinit
2195
2196 This call issues a PM|FWINIT to the local machine's PortMaster. The PortMaster will
2197
2198 then re-read the firewall data file that it was optionally started up with (if it had none,
2199
2200 then this command will have no effect). The fwinit command is useful for the owner
2201
2202 of the firewall data file to change it and have the PortMaster update itself without
2203
2204 bringing down the PortMaster and restarting it.
2205
2206
2207 get
2208
2209 Uses Sgets to get a null-terminated string from the client. This call will block until
2210
2211 something arrives for up to 60 seconds.
2212
2213
2214 isset
2215
2216 Uses Smaskwait() with negligible timeout (1 microsecond!) and then uses Smaskisset()
2217
2218 to determine if the socket is read-ready. This function was included mostly for testing
2219
2220 Smaskisset().
2221
2222
2223 menu
2224
2225
2226
2227 24
2228
2229
2230
2231
2232 Repeats the Socket Test Commands menu (just like \?" below).
2233
2234
2235 peek
2236
2237 Uses Speek to peek at what the client has sent. This call will not block, even if nothing
2238
2239 is there yet.
2240
2241
2242 printf printf your-word
2243
2244 Uses Sprintf to send "your-word 7 8. itworked!" through the Socket.
2245
2246
2247 put put your various sundry strings across
2248
2249 Uses Sputs to send your strings on the same line through the Socket.
2250
2251
2252 q
2253
2254 This function \quits" { uses Sclose to close down all Sockets that sktdbg is using and
2255
2256 exits. Just like \quit".
2257
2258
2259 quit
2260
2261 This function \quits" { uses Sclose to close down all Sockets that sktdbg is using and
2262
2263 exits. Just like \q".
2264
2265
2266 read
2267
2268 This function uses Sread to read whatever is on the Socket, and prints it out assuming
2269
2270 that it received a string.
2271
2272
2273 rmsrvr rmsrvr server-name
2274
2275 This function uses Srmsrvr to remove a server.
2276
2277
2278 scanf
2279
2280 This function accepts a subset of format code: %c, %d, %f, and %s. It will call Sscanf
2281
2282 once for each format code given to it.
2283
2284
2285 shutdown
2286
2287 This function is dangerous! It will shut down the PortMaster on your current machine
2288
2289 and perform a quit. Use of this function is strongly discouraged unless it is necessary
2290
2291 to pull down a PortMaster.
2292
2293
2294 table
2295
2296 The table function communicates with the PortMaster and prints out a table of all
2297
2298 current servers and their ports (rather like spmtable).
2299
2300
2301 test
2302
2303 The test function prints out the number of bytes awaiting perusal by a get or read
2304
2305 operation. It does not block, even if nothing is waiting { it will return 0 in such a case.
2306
2307
2308 wait
2309
2310 This function will block the process until something shows up on the accept or client
2311
2312 Socket.
2313
2314
2315
2316 25
2317
2318
2319
2320
2321 write write your sundry thoughts and words
2322
2323 This function will Swrite your words, appropriately null-byte terminated, through the
2324
2325 Socket. It can be read by the read function.
2326
2327
2328 ?
2329
2330 Repeats the Socket Test Commands menu (just like \menu" above).
2331
2332
2333
2334 This program is really quite simple to learn and run, and is useful to help the installer
2335
2336 verify that the SSL is installed correctly.
2337
2338
2339
2340 26
2341
2342
2343
2344
2345 5 Installation Instructions
2346
2347
2348 Installation varies, of course, from operating system to operating system.
2349
2350
2351
2352 5.1 Unix
2353
2354
2355 1.Make a SKTS subdirectory somewhere, and extract the contents of the tape into that
2356
2357 subdirectory (typically, tar -xvop, but systems will vary and you may need to spec-
2358
2359 ify a tape drive).
2360
2361
2362 2.If your machine is not ANSI C compliant, but supports prototyping anyway, edit the
2363
2364 sockets.h file to #define ||PROTOTYPE||for your machine.
2365
2366
2367 3.Type make all.
2368
2369
2370 These instructions should result in the SSL being compiled, the utilities being compiled,
2371
2372 and the PortMaster being compiled. A simpleskts.a library results. Although the PortMaster
2373
2374 gets started by the make instructions, you may occasionally need to re-start it (for example,
2375
2376 after the computer goes down). System administrators should know how to modify their
2377
2378 operating system to automatically bring up the PortMaster during a re-boot.
2379
2380 Users may wish to place
2381
2382
2383 setenv SKTPATH machine:machine:machine... csh users
2384
2385 export SKTPATH=machine:machine:machine... ksh users
2386
2387 SKTPATH:==machine:machine:machine... vms users
2388
2389 set SKTPATH=machine:machine:machine... msdos users
2390
2391
2392 in their .login, .profile, login.com, and autoexec.bat respectively. To link to the SSL, one must
2393
2394 include \sockets.h". For example, under UNIX, a user should have a .HDR subdirectory with
2395
2396 all his/her favorite header files and use \cc ... -I~/.HDR ... simpleskts.a".
2397
2398
2399
2400 5.2 Vms
2401
2402
2403 1.Make a SKTS subdirectory somewhere, and extract the contents of the tape into that
2404
2405 subdirectory. The original tape was a quarter-inch cartridge in Unix tar format, but
2406
2407 you may well receive a different format.
2408
2409
2410 2.Type @makeskts
2411
2412
2413 The \makeskts" command script will create several subdirectories, compile the SSL, and
2414
2415 set up a \simpleskts.olb" library. It will not attempt to start up the PortMaster. Change
2416
2417 to the \EXE" subdirectory under the SKTS subdirectory. The PortMaster should be started
2418
2419 via run/detach Spm; you may or may not have sufficient privileges to do so. One may spawn
2420
2421 the PortMaster, but as soon as you log off the PortMaster will rudely terminate. Due to
2422
2423 the potential problem with privileges, the command script will not start up the PortMaster
2424
2425 itself.
2426
2427
2428
2429 27
2430
2431
2432
2433
2434 In order to make use of command-line arguments for sktdbg, etc, VMS requires that
2435
2436 you first make \logical symbols." In your <login.com>, place the following lines (with
2437
2438 appropriately modified YOURDIR):
2439
2440
2441 $ spmchk :== $[YOURDIR.SKTS.EXE]spmchk.exe
2442
2443 $ spmtable :== $[YOURDIR.SKTS.EXE]spmtable.exe
2444
2445 $ spm :== $[YOURDIR.SKTS.EXE]spm.exe
2446
2447 $ srmsrvr :== $[YOURDIR.SKTS.EXE]srmsrvr.exe
2448
2449
2450
2451 5.3 Windows 95 ( or more recent)
2452
2453
2454 Version 2.08 (currently the latest) of the SSL now runs under Windows 95. One may
2455
2456 have a PortMaster running in the background on those machines, too! Since the present
2457
2458 author only has Borland C++, only that compiler has been tested. Other compilers may
2459
2460 need to modify the <Sinit.c> file to include any TCP/IP initialization they may require.
2461
2462
2463 1.Set up your system with an appropriate C compiler, Ethernet card, and TCP/IP .
2464
2465
2466 2.Copy the contents of <ssl.tar.gz> onto your computer.
2467
2468
2469 3.Use gunzip and untar to get the uncompressed files
2470
2471
2472 4.Open a MSDOS console, change directory to ...\COSMIC
2473
2474
2475 5.mkwin95
2476
2477
2478 The smplskts.lib and various *.exe files should be generated in the COSMIC subdirectory.
2479
2480 You may well want to have the Simple Sockets Library's PortMaster (Spm) always running
2481
2482 in background. To accomplish this:
2483
2484
2485 1.On your workbench, click the right mouse button
2486
2487
2488 2.Select New
2489
2490
2491 3.Select Shortcut
2492
2493
2494 4.Put the fully specified path to Spm.exe in the Command Line dialog box.
2495
2496
2497 5.Put Spm as the shortcut's name
2498
2499
2500 6.Right-mouse click on the Spm shortcut
2501
2502
2503 7.Select Properties
2504
2505
2506 8.Select the Shortcut tab
2507
2508
2509 9.In the Run dialog, left mouse click on the down arrow and select minimized.
2510
2511
2512 10.Bring up Explorer
2513
2514
2515
2516 28
2517
2518
2519
2520
2521 11.Click on the + in the left hand window near Windows
2522
2523
2524 12.Click on the + in the left hand window near Start Menu
2525
2526
2527 13.Click on the + in the left hand window near Programs
2528
2529
2530 14.Double click on StartUp
2531
2532
2533 15.Put the mouse cursor on the Spm shortcut; press the right mouse button and drag it
2534
2535 over the right hand Explorer window.
2536
2537
2538 16.Select Copy Here. You will now need to re-boot your machine for this operation to take
2539
2540 effect.
2541
2542
2543
2544 5.4 Older Ms-Dos
2545
2546
2547 The SSL was compiled and tested using the Wollongong TCP/IP package with MicroSoft C (v6.0).
2548
2549 Other compilers and TCP/IP packages may require adjustment to the SSL code. You must
2550
2551 have a TCP/IP package for your machine, however { that is what provides Berkeley sockets
2552
2553 over which the SSL provides a convenient overlay. Also, you must have an Ethernet card for
2554
2555 your machine { that provides the hardware over which the information flows. Neither the
2556
2557 TCP/IP package, the C compiler, nor the Ethernet hardware come with the SSL.
2558
2559
2560
2561 1.The SSL makes several assumptions, unfortunately, about where include files are (ex.
2562
2563 see Speek.c). The installer will undoubtedly need to customize these include lines.
2564
2565 These areas will always be in #ifdef MSDOS ... #endif zones.
2566
2567
2568 2.Acquire a TCP/IP package for your computer (ie. Wollongong).
2569
2570
2571 3.Acquire a C compiler for your computer (ie. Microsoft C, v6.0).
2572
2573
2574 4.Acquire an Ethernet card and TCP/IP address for your computer.
2575
2576
2577 5.Copy the contents of the provided diskette into your subdirectory.
2578
2579
2580 6.For those of you with the software mentioned in Table 5:
2581
2582
2583 (a) Make a directory: c:\c600\socket
2584
2585 (b) Make a directory: c:\c600\socket\exe
2586
2587 (c) Copy wintcp.lib to c:\c600\socket
2588
2589 (d) Copy socket.lib to c:\c600\socket
2590
2591 (e) Copy slibce.lib to c:\c600\socket
2592
2593 (f) Disable the MSDOS linker { possibly by renaming it to doslink. Use the Mi-
2594
2595 croSoft C linker instead.
2596
2597 (g) Return to the directory where you placed the SSL software.
2598
2599
2600
2601 29
2602
2603
2604
2605
2606 (h) Type makeskt (which will use the Makeskt.bat command script). This script will
2607
2608 use Makelib., compile, create the smplskts.lib library, and generate sktdbg.exe,
2609
2610 spmtable.exe, and srmsrvr.exe.
2611
2612 (i)You should be done installing the software at this point.
2613
2614
2615 7.If your compiler is not ANSI C compliant, but supports prototyping, edit the sockets.h
2616
2617 file to define ||PROTOTYPE||for your machine.
2618
2619
2620 8.Follow your compiler's directions to compile to object file format all the C files in SKTS
2621
2622 and SKTS\EXE.
2623
2624
2625 9.Follow your compiler's directions to set up a \library" (a .LIB file) with all the .OBJ
2626
2627 files in the SKTS subdirectory.
2628
2629
2630 10.Change to the SKTS\EXE subdirectory and follow your compiler's instructions to link
2631
2632 each of the object files, one at a time, to the \smplskts.lib" library, the TCP/IP library,
2633
2634 and whatever libraries your compiler normally needs.
2635
2636
2637
2638 The installation should yield a smplskts.lib (or something similar) library and three exe-
2639
2640 cutable files (sktdbg.exe, spmtable.exe, and spmtable.exe).
2641
2642 Note that the \SPM.EXE" file should not be generated; you could generate and execute
2643
2644 it, but your clone could not use it as it does not allow the PortMaster to run in the back-
2645
2646 ground. No attempt has been made to insure that the PortMaster is actually compilable
2647
2648 under MicroSoft C, either. Someday a kludge to allow MS-DOS programs to be their own
2649
2650 PortMaster may be developed, but that day is not yet. Using Wollongong TCP/IP , one will
2651
2652 be restricted to three (or five if its \kernel" is rebuilt) clients.
2653
2654 The software in Table 5 was used by the IRL and is known to work properly with the
2655
2656 SSL. Other software may work but has not been tested.
2657
2658
2659
2660 Table 5: Ms-Dos Software known to work with the SSL
2661 Software Product Company
2662
2663 MicroSoft C, v6.0 MicroSoft
2664
2665 Win/API for DOS, v4.1 The Wollongong Group, Inc.
2666
2667 PO Box 51860
2668
2669 Palo Alto, CA 94303-4374
2670
2671 (415)-962-7100
2672
2673 Wollongong Win/TCP, v4.1.1 The Wollongong Group, Inc.
2674
2675
2676
2677 30
2678
2679
2680
2681
2682 6 Appendix: Miscellaneous Functions
2683
2684
2685 The SSL uses nine functions from Dr. Campbell's xtdio library; these have been gathered
2686
2687 together and made part of the simpleskts.a library. Several of the functions use a special
2688
2689 data file, rdcolor.dat.
2690
2691 Note: the error and outofmem functions claim they will \terminate" under certain con-
2692
2693 ditions. Actually, they will call the function (*error|exit)(int rtn), which by default is the
2694
2695 exit function. Programmers may easily prevent or otherwise control termination by simply
2696
2697 setting error|exit to point to some other function.
2698
2699
2700
2701 void error(int severity,char *fmt,...)
2702
2703 The error function prints out an error, warning, or note type of message to stdout. This
2704
2705 function takes four kinds of \severity": SEVERE, ERROR, WARNING, and NOTE. Both
2706
2707 the SEVERE and ERROR levels will terminate the program. The other two, WARNING
2708
2709 and NOTE, will not do so. The termination action tends to enforce a standard for what
2710
2711 errors versus warnings mean! If your terminal type is supported by the rdcolor.dat file
2712
2713 (see rdcolor below), SEVERE and ERROR messages are printed with a red leader,
2714
2715 WARNINGs with a yellow leader, and NOTEs with a cyan leader.
2716
2717
2718 FILE *fopenv(char *filename,char *ctrl,char *env|var)
2719
2720 The fopenv provides a file opening service akin to that provided by the Sopenv function
2721
2722 for the SSL. The fopen() function will be used with the given filename and ctrl strings,
2723
2724 and upon failure, the environment variable in env|var will be used like a PATH variable
2725
2726 in attempts to open the file in one directory after another (until success). If none of
2727
2728 the fopens succeed, then the fopenv function will return a NULL pointer.
2729
2730
2731 void outofmem(void *ptr,char *fmt,...)
2732
2733 The outofmem function checks if ptr is NULL; if it is not, the function immediately
2734
2735 returns.
2736
2737 However, if the ptr pointer is in fact NULL, then the fmt and any subsequent arguments
2738
2739 will be used like a regular printf to give a message to the user. The program will then
2740
2741 terminate.
2742
2743
2744 void rdcolor(void)
2745
2746 This function reads the rdcolor.dat file, which essentially is an extended \termcap" file.
2747
2748 It uses the \RDCOLOR" environment variable with fopenv to search for the rdcolor.dat
2749
2750 file. The function uses that file to set up various string variables (RED, CLEAR, { see
2751
2752 below).
2753
2754
2755 void rdcputs(char *s,FILE *fp)
2756
2757 This function puts a string out to the FILE pointer fp, except that those strings (XRED,
2758
2759 XUWHITE, etc.) are interpreted using the rdcolor-provided string instead.
2760
2761
2762 char *sprt(char *s)
2763
2764 This function returns a pointer to a static buffer (there are four of them). The string
2765
2766
2767
2768 31
2769
2770
2771
2772
2773 s has all of its characters made into \visible" forms: control characters become ^A
2774
2775 through ^Z and characters with ANSI values greater than or equal to 128 are made into
2776
2777 ~### sequences. Characters which are normally visible are left unchanged.
2778
2779
2780 void srmtrblk(char *s)
2781
2782 This function removes any trailing \blanks" (white space) from the end of a string.
2783
2784
2785 char *stpblk(char *p)
2786
2787 This function returns a pointer to the first non-white space character in the string p
2788
2789 (ie. steps past blanks).
2790
2791
2792 char *stpnxt(char *s,char *fmt)
2793
2794 This function returns a pointer to the first character in s which would not have been
2795
2796 read by a sscanf(s,fmt,...) function. Useful for quick and dirty parsing.
2797
2798
2799 char *strnxtfmt(char *fmt)
2800
2801 The strnxtfmt function returns a pointer to the beginning of the (next) format code
2802
2803 substring. If fmt is NULL, then the previous format string is used (ie. a pointer to
2804
2805 the last fmt code is retained and the a pointer to the next format code pointer will
2806
2807 be returned). This function bears some similarity to strtok except that it jumps from
2808
2809 format code to format code (used by Sscanf).
2810
2811
2812
2813 The rdcolor.dat file describes terminal escape sequences to use to control color and a few
2814
2815 other actions. Each line which does not begin with a white space character is assumed to
2816
2817 be a terminal line: terminal types are separated by vertical bars and the line is terminated
2818
2819 by a colon. There are a number of strings defined (see Table 6).
2820
2821 Escape sequences may include the sequence \e for the ESCAPE character and \b for a blank.
2822
2823 Please see the rdcolor.dat file for examples.
2824
2825
2826
2827 32
2828 ||
2829 ||
2830 |||
2831 |||
2832 |||
2833 |||
2834 |||
2835 |||
2836 |||
2837 |||
2838 |||
2839 |||
2840 |||
2841 |||
2842 |||
2843 |||
2844 |||
2845 |||
2846 |||
2847 |||
2848 |||
2849 |||
2850 |||
2851 |||
2852 |||
2853 |||
2854 |||
2855 |||
2856 |||
2857 |||
2858
2859 ||||||
2860 |||
2861 |||
2862 |||
2863 |||
2864 |||
2865 |||
2866 |||
2867 |||
2868 |||
2869 |||
2870 |||
2871 |||
2872 |||
2873 |||
2874 |||
2875 |||
2876 |||||| Table 6: rdcolor.dat strings
2877 |
2878 ___|___ String NameFun___ction ___ ___
2879
2880 ___ ___ BLACK subs___equent chars are black ___ ___
2881
2882 ___ ___ RED subse___quent chars are red ___ ___
2883
2884 ___ ___ GREEN subs___equent chars are green ___ ___
2885
2886 ___ ___ YELLOW sub___sequent chars are yellow ___ ___
2887 ||
2888 ___|___|BLUE subs___equent chars are blue ___ ___
2889
2890 ___|___|MAGENTA|sub___sequent|chars are magenta ___ ___
2891
2892 ___|___|CYAN|| subs___equent chars are cyan ___ ___
2893
2894 ___|___|WHITE|| subs___equent chars are white ___ ___
2895
2896 ___|___||| ___ ___ ___
2897
2898 ___|___|UBLACK||subs___equent chars are underlined and black ___ ___
2899
2900 ___|___|URED|| subs___equent chars are underlined and red ___ ___
2901
2902 ___|___|UGREEN||sub___sequent chars are underlined and green ___ ___
2903
2904 ___|___|UYELLOW|sub___sequent chars are underlined and yellow ___ ___
2905 |
2906 ___|___|UBLUE| subs___equent chars are underlined and blue ___ ___
2907
2908 ___|___|UMAGENTAsu___bsequent|chars|are underlined and magenta ___ ___
2909
2910 ___|___|UCYAN| subs___equent chars are underlined and cyan ___ ___
2911 ||
2912 ___|___|UWHITE subs___equent chars are underlined and white ___ ___
2913 ||
2914 ___|___| ___ ___ ___
2915
2916 ___|___|RVBLACK|sub___sequent|chars are reverse-video and black ___ ___
2917
2918 ___|___|RVRED|| subs___equent chars are reverse-video and red ___ ___
2919
2920 ___|___|RVGREEN|sub___sequent|chars are reverse-video and green ___ ___
2921
2922 ___|___|RVYELLOWsub___sequent|chars|are reverse-video and yellow ___ ___
2923
2924 ___|___|RVBLUE||subs___equent chars are reverse-video and blue ___ ___
2925
2926 ___|___|RVMAGENTAs___ubsequent|chars|are reverse-video and magenta ___ ___
2927
2928 ___|___|RVCYAN| subs___equent chars are reverse-video and cyan ___ ___
2929 |
2930 ___|___|RVWHITE|sub___sequent chars are reverse-video and white ___ ___
2931 |
2932 ___|___|| ___ ___ ___
2933
2934 ___|___|NRML|| subs___equent chars are \normal" ___ ___
2935
2936 ___|___|BOLD| subs___equent chars are \bold" ___ ___
2937 ||
2938 ___|___|CLEAR the ___screen is cleared ___ ___
2939
2940
2941
2942 33