socket++.texi

《CODE READING》配套书源代码 《CODE READING》配套书源代码

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename socket++.info
@settitle   C++ socket classes
@c %**end of header
@syncodeindex fn cp

@iftex
@finalout
@end iftex

@ifinfo
This info file describes the C++ family of socket classes.

Copyright (C) 1992,1993,1994 Gnanasekaran Swaminathan <gs4t@@virginia.edu>

Permission is granted to make and distribute verbatim copies of this
document provided the copyright notice and this permission notice
are preserved on all copies.
@end ifinfo

@titlepage
@title C++ Socket Classes
@subtitle Version: 12Jan97 1.11
@author Gnanasekaran Swaminathan

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1992,1993,1994 Gnanasekaran Swaminathan

@sp 2
This is Version: 12Jan97 1.11 of the C++ family of socket classes.
@sp 2

Permission is granted to make and distribute verbatim copies of this
document provided the copyright notice and this permission notice
are preserved on all copies.
@end titlepage

@ifinfo
@node    Top,       Copying, (dir),     (dir)
@top Socket++ Library

Socket++ is a family of C++ classes that gives the same
interface as the iostream classes for input and output
for communication between processes.@refill

This documentation describes Version: 12Jan97 1.11 of
socket++ library.@refill
@end ifinfo

@menu
* Copying::                     Copyright information.
* Acknowledgments::             Thanks!
* Overview of Socket++::        Overview of socket++ library.
* sockbuf Class::               Socket streambuf class.
* sockAddr Class::              Base class for socket addresses.

* sockinetbuf Class::           Socket class for INET address family.
* sockinetaddr Class::          Address class for INET address family of
                                        sockets.

* sockunixbuf Class::           Socket class for UNIX address family.
* sockunixaddr Class::          Address class for UNIX address family of
                                        sockets.

* sockstream Classes::          I/O socket stream classes and some examples.
* pipestream Classes::          I/O stream classes that provides pipe,
                                        socketpair, and popen facilities.

* Fork Class::                  Use the Fork class to fork a child
                                        process.

* protocol Class::              Protocol base class.
* echo Class::                  Class implementing the Echo protocol.
* smtp Class::                  Class implementing the SMTP protocol.

* Error Handling::              Describes the default error handling in
                                        the socket++ library.
* Pitfalls::                    Common mistakes that socket++ library
                                        users make.

* Index::                       Index to concepts and program names
@end menu

@node Copying
@unnumbered Socket++ Library Copyright Notice
@cindex copyright notice
@cindex Copyright

Copyright (C) 1992,1993,1994 Gnanasekaran Swaminathan

Permission is granted to use at your own risk and distribute this
software in source and binary forms provided the above copyright
notice and this paragraph are preserved on all copies. This software
is provided "as is" with no express or implied warranty.@refill

@node Acknowledgments
@unnumbered Acknowledgments
@cindex acknowledgments

Gordon Joly <G.Joly@@cs.ucl.ac.uk> for reporting bugs in
pipestream class implementation and providing an ftp site
for the socket++ library at
	cs.ucl.ac.uk:~ftp/coside/gnu/socket++-1.x.tar.gz
He also knows how to make the socket++ library a shared
library. 

Jim Anderson for reporting a bug in sockinet.C

Carl Gay <cgay@@skinner.cs.uoregon.edu> for reporting a bug
and a fix in sockinet.C

Oliver Imbusch <flabes@@parystec.de> for reporting a bug
in Makefile.in and suggesting several enhancements for sockbuf class.

Dierk Wendt <wendt@@lambda.hella.de> for reporting errors
in the socket++ documentation.

Per Bothner <bothner@@cygnus.com> for configure, config.sub,
config.shared and move-if-change files that are used
to generate Makefile. These files are taken from his libg++-2.4
and hence, these files are governed by the Copyright Notice found
in the file LICENCE in libg++.

@node Overview of Socket++
@chapter Overview of Socket++ Library
@cindex overview of socket++

Socket++ library defines a family of C++ classes that can be used
more effectively than directly calling the underlying low-level
system functions. One distinct advantage of the socket++ is that
it has the same interface as that of the iostream so that
the users can perform type-safe input output. See your local
IOStream library documentation for more information on iostreams.@refill

@code{streambuf} counterpart of the socket++ is @code{sockbuf}.
@code{sockbuf} is an endpoint for communication with yet another
@code{sockbuf} or simply a @code{socket} descriptor. @code{sockbuf}
has also methods that act as interfaces for most of the commonly
used system calls that involve sockets. @xref{sockbuf Class}, for more
information on the socket buffer class.

For each communication domain, we derive a new class from @code{sockbuf}
that has some additional methods that are specific to that domain. At
present, only @var{unix} and @var{inet} domains are supported.
@code{sockunixbuf} class and @code{sockinetbuf} class define the @var{unix}
and @var{inet} domain of sockets respectively. @xref{sockunixbuf Class}, for
@var{unix} sockets and @xref{sockinetbuf Class}, for @var{inet} sockets.

We also have domain specific socket address classes that are
derived from a common base class called @code{sockAddr}.
@code{sockunixaddr} class is used for @var{unix} domain addresses
and @code{sockinetaddr} class is used for @var{inet} domain
addresses. For more information on address classes see @ref{sockAddr Class},
@ref{sockunixaddr Class}, and @ref{sockinetaddr Class}.
@quotation
@emph{Note}: @code{sockAddr} is not spelled @code{sockaddr} in
order to prevent name clash with the @code{struct sockaddr} declared
in @file{<sys/socket.h>}.
@end quotation

We noted earlier that socket++ provides the same interface as the
iostream library. For example, in the internet domain, we have
@code{isockinet}, @code{osockinet}, and @code{iosockinet} classes
that are counterparts to @code{istream}, @code{ostream}, and
@code{iostream} classes of IOStream library.
For more details on @code{iosockstream} classes see @xref{sockstream Classes}.

The services of @code{pipe()}, @code{socketpair()}, and @code{popen()}
system calls are provided by the @code{pipestream} class.
@xref{pipestream Classes}.

@node sockbuf Class
@chapter @code{sockbuf} Class
@cindex sockbuf class
@cindex class sockbuf

@code{sockbuf} class is derived from @code{streambuf} class of the
iostream library. You can simultaneously read and write into a
@code{sockbuf} just like you can listen and talk through a telephone. To
accomplish the above goal, we maintain two independent buffers for
reading and writing.

@menu
* Constructors::              How to construct a @code{sockbuf} object
                                     and how to open a socket?
* Destructor::                How to destruct a @code{sockbuf} object
                                     and how to close a socket?
* Reading and Writing::       How to use @code{sockbuf} as @code{streambuf}?
* Connection Establishment::  How to bind an address and establish a
                                     connection?
* Socket Options::            How to set and get socket options?
* Timeouts::                  How to gracefully handle connection inactivity?
@end menu

@node Constructors
@section Constructors
@cindex sockbuf constructors
@findex sockbuf::type

@code{sockbuf} constructors sets up an endpoint for communication. A
@code{sockbuf} object so created can be read from and written to in
linebuffered mode. To change mode, refer to @code{streambuf} class
in your IOStream library.
@quotation
@cindex flushing buffers
@emph{Note}: If you are using AT&T IOStream library, then the
linebuffered mode is permanently turned off. Thus, you need to
explicitly flush a socket stream. You can flush a socket stream buffer
in one of the following four ways:
@example
    // os is a socket ostream
    os << "this is a test" << endl;
    os << "this is a test\n" << flush;
    os << "this is a test\n"; os.flush ();
    os << "this is a test\n"; os->sync ();
@end example
@end quotation

@code{sockbuf} objects are created as follows where
@itemize @minus
@item
@code{s} and @code{so} are @code{sockbuf} objects
@item
@code{sd} is an integer which is a socket descriptor
@item
@code{af} and @code{proto} are integers which denote domain number and
protocol number respectively
@item
@code{ty} is a @code{sockbuf::type} and must be one of
@code{sockbuf::sock_stream}, @code{sockbuf::sock_dgram},
@code{sockbuf::sock_raw}, @code{sockbuf::sock_rdm}, and
@code{sockbuf::sock_seqpacket}
@end itemize

@table @code

@item sockbuf s(sd);
@itemx sockbuf s;
@findex sockbuf::sockbuf
Set socket descriptor of @code{s} to @code{sd} (defaults to -1).
@code{sockbuf} destructor will close @code{sd}.

@item sockbuf s(af, ty, proto);
Set socket descriptor of @code{s} to @code{::socket(af, int(ty), proto);}

@item sockbuf so(s);
Set socket descriptor of @code{so} to the socket descriptor of @code{s}.

@item s.open(ty, proto)
@findex sockbuf::open
does nothing and returns simply @code{0}, the null pointer
to @code{sockbuf}.

@item s.is_open()
@findex sockbuf::is_open
returns a non-zero number if the socket descriptor is open else return
0.

@item s = so;
@findex sockbuf::operator=
return a reference @code{s} after assigning @code{s} with @code{so}.

@end table

@node Destructor
@section Destructor
@cindex sockbuf destructor
@findex sockbuf::shuthow

@code{sockbuf::~sockbuf()} flushes output and closes its socket if no other
sockbuf is referencing it and _S_DELETE_DONT_CLOSE flag is not set. It
also deletes its read and write buffers.

In what follows,
@itemize @minus
@item
@code{s} is a @code{sockbuf} object
@item
@code{how} is of type @code{sockbuf::shuthow} and must be one of
@code{sockbuf::shut_read}, @code{sockbuf::shut_write}, and
@code{sockbuf::shut_readwrite}
@end itemize

@table @code
@item sockbuf::~sockbuf()
@findex sockbuf::~sockbuf
flushes output and closes its socket if no other
@code{sockbuf} object is referencing it before deleting its read and
write buffers. If the _S_DELETE_DONT_CLOSE flag is set, then the socket
is not closed.

@item s.close()
@findex sockbuf::close
closes the socket even if it is referenced by other @code{sockbuf}
objects and _S_DELETE_DONT_CLOSE flag is set.

@item s.shutdown(how)
@findex sockbuf::shutdown
shuts down read if @code{how} is @code{sockbuf::shut_read}, shuts down
write if @code{how} is @code{sockbuf::shut_write}, and shuts down both
read and write if @code{how} is @code{sockbuf::shut_readwrite}.

@end table

@node Reading and Writing
@section Reading and Writing
@cindex sockbuf reading
@cindex sockbuf writing

@code{sockbuf} class offers several ways to read and write and tailors
the behavior of several virtual functions of @code{streambuf} for socket
communication.

In case of error, @code{sockbuf::error(const char*)} is called.

In what follows, 
@itemize @minus
@item
@code{s} is a @code{sockbuf} object
@item
@code{buf} is buffer of type @code{char*}
@item
@code{bufsz} is an integer and is less than @code{sizeof(buf)}
@item
@code{msgf} is an integer and denotes the message flag
@item
@code{sa} is of type @code{sockAddr}
@item
@code{msgh} is a pointer to @code{struct msghdr}
@item
@code{wp} is an integer and denotes time in seconds
@item
@code{c} is a char
@end itemize

@table @code

@item s.is_open()
@findex sockbuf::is_open
returns a non-zero number if the socket descriptor is open else return
0.

@item s.is_eof()
@findex sockbuf::is_eof
returns a non-zero number if the socket has seen EOF while reading else
return 0.

@item s.write(buf, bufsz)
@findex sockbuf::write
returns an int which must be equal to @code{bufsz} if @code{bufsz} chars in
the @code{buf} are written successfully. It returns 0 if there is
nothing to write or if, in case of timeouts, the socket is not ready
for write @ref{Timeouts}.

@item s.send(buf, bufsz, msgf)
@findex sockbuf::send
@findex sockbuf::msgflag
same as @code{sockbuf::write} described above but allows the user to
control the transmission of messages using the message flag @code{msgf}.
If @code{msgf} is @code{sockbuf::msg_oob} and the socket type of
@code{s} is @code{sockbuf::sock_stream}, @code{s} sends the message in
@var{out-of-band} mode. If @code{msgf} is @code{sockbuf::msg_dontroute},
@code{s} sends the outgoing packets without routing. If @code{msgf} is
0, which is the default case, @code{sockbuf::send} behaves exactly like
@code{sockbuf::write}.

@item s.sendto(sa, buf, bufsz, msgf)
@findex sockbuf::sendto
same as @code{sockbuf::send} but works on unconnected sockets. @code{sa}
specifies the @var{to} address for the message.

@item s.sendmsg(msgh, msgf)
@findex sockbuf::sendmsg
same as @code{sockbuf::send} but sends a @code{struct msghdr} object
instead.

@item s.sys_write(buf, bufsz)
@findex sockbuf::sys_write
calls @code{sockbuf::write} and returns the result. Unlike
@code{sockbuf::write} @code{sockbuf::sys_write} is declared as a virtual
function.

@item s.read(buf, bufsz)
@findex sockbuf::read
returns an int which is the number of chars read into the @code{buf}. In
case of EOF, return EOF. Here, @code{bufsz} indicates the size of the
@code{buf}. In case of timeouts, return 0 @ref{Timeouts}.

@item s.recv(buf, bufsz, msgf)
@findex sockbuf::recv
@findex sockbuf::msgflag
same as @code{sockbuf::read} described above but allows the user to receive
@var{out-of-band} data if @code{msgf} is @code{sockbuf::msg_oob} or to
preview the data waiting to be read if @code{msgf} is
@code{sockbuf::msg_peek}. If @code{msgf} is 0, which is the default
case, @code{sockbuf::recv} behaves exactly like @code{sockbuf::read}.

@item s.recvfrom(sa, buf, bufsz, msgf)
@findex sockbuf::recvfrom
same as @code{sockbuf::recv} but works on unconnected sockets. @code{sa}
specifies the @var{from} address for the message.

@item s.recvmsg(msgh, msgf)
@findex sockbuf::recvmsg
same as @code{sockbuf::recv} but reads a @code{struct msghdr} object
instead.

@item s.sys_read(buf, bufsz)
@findex sockbuf::sys_read
calls @code{sockbuf::read} and returns the result. Unlike
@code{sockbuf::read} @code{sockbuf::sys_read} is declared as a virtual