sockets.tex

项目描述: slsnif is a serial port logging utility. It listens to the specified serial port and logs all

\verb`        sleep(1);`                                     \\
\verb`        }`                                             \\
\verb`    ...`                                               \\
\verb`    Sclose(client);`
\end{example}

The \SSL\ allows the programmer to set up~a~group of machines for making client
connections.  In Example~\ref{using-sopenv}, the \SSL\ tries to open~a~client
to~a~server named \verb`serverName` on any machine on the {\small SKTPATH}.
The ``{\small SKTPATH}'' is an environment variable typically of the form
\verb`machine1:machine2:machine3`, ie.~a list of machine names separated by
colons.  This example also shows~a~typical client connection attempt and sleep
polling loop.

A~somewhat larger example is included in the distribution: \verb`multiskt.c`.
This example program concurrently accepts multiple clients on~a~single server,
reads any messages sent its way from any of its clients, and sends~a~modified
version back to the sending client.  It uses the {\em Smaskwait} functions to
block the multiskt process for friendly multi-tasking.  It is~a~useful program
to study in conjunction with the Manual below.

Connected sockets are~a~pre-requisite for any of the {\small I/O} Socket
functions described in the next section.  Note that the server should have a
unique name on any given machine. Servers may have the same name on different
machines, although this may be confusing.  It is suggested that one use the
name of the process (at least as~a~prefix) for that purpose.  Note that the
only things that one can do with~a~server Socket are: open one, close one,
generate an accept Socket with one, and test/block on one (for clients
requesting connection).  The \SSL\ supports up to $10$ clients concurrently
awaiting acceptance on~a~server Socket, although many machines will limit
that to $5$ (silently).

The \SSL\ supports two way communication of data between~a~client and an accept
Socket.  Since the processes are not likely to be synchronized, often one
process must somehow wait until the other process has sent it something.  There
are two methods to support this under the \SSL: polling and interrupt-driven.
The polling method uses~a~lot of {\small CPU} time, but lets the program do
other tasks in the meantime.  The interrupt-driven approach hangs the process
(aka blocks and suspends) until something shows up on the Socket.  The
Smask{\small XXX} group of functions allows one to hang the process until
something shows up on any number of Sockets -- sort of~a~big {\small OR} gate!

The Smask{\small XXX} alternative to polling also allows the programmer to
insert non-socket file descriptors into the mask via Smaskfdset (and to remove
them via Smaskunfdset) such as serial ports (ex. open with DEVICE), graphics queues
(ex. {\small SGI}s with qgetfd), etc.


\subsection{Reference Manual}

This section contains~a~description of the functions available in the Socket
Library.  The \SSL\ returns three types of Sockets:~a~server, client, and an
accept Socket. ~A~Socket itself is~a~data structure {\em type} set up by the
\verb`sockets.h` header file.  The Socket is deliberately used in~a~fashion
reminiscent of the use of {\small FILE} pointers so that the~C~user who knows
how to read and write~a~file will immediately feel comfortable with reading and
writing Sockets.

\begin{center}
  \begin{tabular}{||ll|l|l||} \hline\hline
  {\em Return}  &   & {\em Function} & {\em Argument}                           \\
  {\em Type}    &   & {\em Name}     & {\em List}                               \\
  \hline
  Socket        & * & Saccept        & (Socket *skt)                            \\
  void          &   & Sclose         & (Socket *skt)                            \\
  char          & * & Sgets          & (char *buf, int maxbuf, Socket *skt)     \\
  int           &   & Smaskfdisset   & (int fd)                                 \\
  void          &   & Smaskfdset     & (int fd)                                 \\
  fd\_set       &   & Smaskget       & ()                                       \\
  int           &   & Smaskisset     & (Socket *skt)                            \\
  void          &   & Smaskpop       & ()                                       \\
  void          &   & Smaskpush      & ()                                       \\
  void          &   & Smaskset       & (Socket *skt)                            \\
  int           &   & Smasktest      & ()                                       \\
  void          &   & Smasktime      & (long seconds,long useconds)             \\
  void          &   & Smaskunset     & (Socket *skt)                            \\
  void          &   & Smaskunfdset   & (int fd)                                 \\
  void          &   & Smaskuse       & (fd\_set usermask)                       \\
  int           &   & Smaskwait      & ()                                       \\
  Socket        & * & Sopen          & (char *skthost, char *mode)              \\
  Socket        & * & Sopenv         & (char *srvrname,char *ctrl,char *envvar) \\
  int           &   & Speek          & (Socket *skt, char *buf, int buflen)     \\
  unsigned long &   & Speeraddr      & (Socket *skt)                            \\
  char          & * & Speername      & (Socket *skt)                            \\
  void          &   & Sprintf        & (Socket *skt, char *fmt,...)             \\
  char          & * & Sprtskt        & (Socket *skt)                            \\
  void          &   & Sputs          & (char *buf, Socket *skt)                 \\
  int           &   & Sread          & (Socket *skt, char *buf, int buflen)     \\
  int           &   & Sreadbytes     & (Socket *skt, char *buf, int buflen)     \\
  int           &   & Srmsrvr        & (char *skthost)                          \\
  int           &   & Sscanf         & (Socket *skt, char *fmt, ...)            \\
  int           &   & Stest          & (Socket *skt)                            \\
  int           &   & Stimeoutwait   & (Socket *skt,long seconds,long useconds) \\
  int           &   & Svprintf       & (Socket *skt, char *fmt, void *args)     \\
  int           &   & Swait          & (Socket *skt)                            \\
  int           &   & Swrite         & (Socket *skt, char *buf, int buflen)     \\
  \hline\hline
  \end{tabular}
\end{center}

\begin{description}

\item[Socket *Saccept(Socket *skt)] \ \\
    This function takes~a~server Socket and produces~a~Socket which has
    accepted~a~connection.  This function may be used as often as wanted on the
    same server Socket!  Note that one must have successfully opened~a~server
    prior to using Saccept to accept connections (see Examples~\ref{one-accept}
    and \ref{multi-accept}).

    If this operation is unsuccessful, then Saccept will return~a~null Socket
    pointer.

\item[void Sclose(Socket *skt)] \ \\
    This function closes~a~Socket of any type (server, client, accept).  The
    Sclose function communicates with the local PortMaster whenever~a~server is
    closed.

\item[char *Sgets(char *buf, int maxbuf, Socket *skt)] \ \\
    This is an I/O function which assumes that one has already opened a
    connected Socket ({\em skt}).  It will attempt to get~a~null-terminated
    string from the Socket (up to maxbuf characters).  This call will block
    (aka hang, sleep) until~a~string shows up, but otherwise acts much as a
    fgets() function does.

    If Sgets has~a~socket error, then~a~null pointer is returned.  Otherwise,
    it returns the ``{\em buf}'' pointer.

\item[int Smaskfdisset(int fd)] \ \\
    The Smaskfdisset() function works in conjunction with the Smaskwait()
    function.  After the Smaskwait() function returns, one can use
    Smaskfdisset(skt) to test if~a~particular file descriptor is read-ready.

\item[void Smaskfdset(int fd)] \ \\
    The Smask{\small XXX} functions use~a~{\it mask} of type {\it fd\_set}
    internally.  Other operations, such as use of~a~serial port under
    Unix or the {\small\it GL} queue for {\small SGI}'s Irises (see their
    qgetfd() function) use file descriptors.  This function allows one to
    set up the Smask{\small XXX} mask with one or more of those file
    descriptors.

\item[Smask Smaskget()] \ \\
    The Smask{\small XXX} functions use~a~{\it mask} of type {\it fd\_set}
    internally.  Other operations, such as use of~a~serial port under
    Unix, can also be used to set masks.  This function provides access to
    the mask set up by Smaskset.  The mate to this function is Smaskuse().

\item[int Smaskisset(Socket *skt)] \ \\
    The Smaskisset() function works in conjunction with the Smaskwait()
    function.  After the Smaskwait() function returns, one can use
    Smaskisset(skt) to test if~a~particular Socket is read-ready.  It is
    simpler then and thereby faster than Smasktest().

\item[void Smaskpop()] \ \\
    The Smaskpop() function, along with the Smaskpush() function, allows
    the programmer to manipulate an internal stack of masks.  The ``top''
    mask is the current mask.

\item[void Smaskpush()] \ \\
    The Smaskpush() function, along with the Smaskpop() function, allows
    the programmer to manipulate an internal stack of masks.  The ``top''
    mask is the current mask.

\item[void Smaskset(Socket *skt)] \ \\
    This function is part of the {\em Smask{\small XXX}} group.  Sockets may be
    set up for Smaskwait'ing one at~a~time.   Note that all Sockets are
    effectively {\small OR}'ed together for blocking; to clear the mask, pass a
    {\small NULL} Socket pointer to Smaskset:  Smaskset((Socket *) {\small
    NULL});.

\item[int Smasktest()] \ \\
    This function is part of the {\em Smask{\small XXX}} group.  The Smasktest
    function supports polling -- one may determine if anything is on any of the
    Smaskset Sockets and immediately receive~a~positive integer if there is,
   ~a~0 if there isn't, and~a~negative number if there's an error.

\item[void Smasktime(long seconds,long useconds)] \ \\
    This function is part of the {\em Smask{\small XXX}} group.
    Normally Smaskwait will block ``forever'' (well, at least as long as
    the machine stays up!).  However, one can specify~a~time limit -- then
    Smaskwait will return with~a~value of 0 if the time limit is exceeded.  One
    may specify the time limit in seconds and micro-seconds.  To clear the time
    limit (ie.~restore Smaskwait to waiting forever), pass~a~negative time in
    either or both arguments to Smasktime.  Waiting forever is also set up when
    both arguments to Smasktime are zero.

\item[void Smaskunfdset(int fd)] \ \\
    This function is part of the {\em Smask{\small XXX}} group.
    File descriptors may be entered into the mask via the Smaskfdset()
    function, and this function can remove it from the mask.  This function
    is similar to the Smaskunset() function.

\item[void Smaskunset(Socket *skt)] \ \\
    This function is part of the {\em Smask{\small XXX}} group.  Sockets may be
    removed from the Smaskwait's mask one at~a~time via this function.  Like
    {\em Smaskset},~a~{\em Smaskunset((Socket *) {\small NULL});} will clear
    the entire mask.

\item[void Smaskuse(Smask usermask)] \ \\
    This function is part of the {\em Smask{\small XXX}} group.  The internal
    {\em mask} in Smask{\small XXX} can be set up by the user via this
    function.  Often, Smaskset will be used to set up an internal mask,
    Smaskget will be used to obtain the resulting mask, and Smaskuse will
    be used to apply that mask.

\item[int Smaskwait()] \ \\
    This function is part of the {\em Smask{\small XXX}} group.  The {\em
    Smaskwait}  function will block (aka hang) the process until any Socket set
    via Smaskset has something waiting on it to be read.  Note that Sockets set
    by Smaskset are retained; ie.~they must be explicitly cleared by passing a
    {\small NULL} Socket pointer to Smaskset.

    Smaskwait returns~a~positive number if something is waiting on a
    Socket, zero if~a~timeout occurs, and~a~negative number on an error.

\item[Socket *Sopen(char *skthost, char *mode)] \ \\
    This function is the workhorse for opening Sockets.  Basically, it can make
    either~a~server or~a~client depending on the mode.

      \begin{center}
      \begin{tabular}{|cl|}
      \hline
       \multicolumn{1}{|c}{\em Mode}  &
       \multicolumn{1}{c|}{\em Effect}                                               \\
      \hline
        {\em s}           & open~a~server                                            \\
        {\em S}           & open~a~server but, on failure, retry after using Srmsrvr \\
        {\em c}           & open~a~client                                            \\
        {\em s\verb`###`} & open~a~server with the specified port number             \\
        {\em S\verb`###`} & like {\em S} above, but with the specified port          \\
        {\em c\verb`###`} & open~a~client to~a~server with the specified port        \\
      \hline
      \end{tabular}
      \end{center}

    The {\em skthost} is the name of the server.  If one is making~a~{\em
    client} Socket, then one may optionally use the form
    ``servername@hostname'' for the skthost.  The ``@hostname'' form is not
    necessary for clients to servers that are on the same host as the client,
    as the default host is the local host.  The ``servername@hostname'' form
    makes no sense for servers, and so, for opening servers, Sopen will ignore
    any ``@hostname'' portion of skthost.

    The {\em ``S''} mode for opening servers, like the {\em ``s''} mode, will
    cause Sopen to attempt to open~a~server, but if unsuccessful, Sopen will
    then use Srmsrvr using the provided skthost and then retry opening the
    server.  In the case of {\em s\verb`###`} or {\em S\verb`###`}, the servers
    are set up with the \TCP\ option {\small SO\_REUSEADDR}.  This option
    alleviates some of the difficulties associated with re-starting servers
    with fixed ports.

    If the skthost is null or an empty string (""), the PortMaster is bypassed.
    One must specify a port number to use in that case.  A warning is issued
    (as well as a null \verb`Socket*`) because that is typically a programming
    error, not a user error.

    The PortMaster is also always bypassed for clients which specify port
    number ({\em c\verb`###`}).  In the latter case,~a~client connection is
    immediately attempted to the user-specified port number.  If the function
    is not successful,~a~null Socket pointer is returned.

    If the user-specified server port mode is used with a skthost, the server