| 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} |