c%2B%2B/socket%2B%2B-1.10/socket%2B%2B.texi

\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: 17Oct95 1.10
@author Gnanasekaran Swaminathan

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

@sp 2
This is Version: 17Oct95 1.10 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: 17Oct95 1.10 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
function.

@item s.is_readready(wp_sec, wp_usec)
@findex sockbuf::is_readready
returns a non-zero int if @code{s} has data waiting to be read from the
communication channel. If @code{wp_sec >= 0}, it waits for
@code{wp_sec 10^6 + wp_usec} microseconds before returning 0 in case
there are no data waiting to be read. If @code{wp_sec < 0}, then it waits until
a datum arrives at the communication channel. @code{wp_usec} defaults to 0.
@quotation
@emph{Please Note}: The data waiting in @code{sockbuf}'s own buffer is
different from the data waiting in the communication channel.
@end quotation

@item s.is_writeready(wp_sec, wp_usec)
@findex sockbuf::is_writeready
returns a non-zero int if data can be written onto the communication
channel of @code{s}. If @code{wp_sec >= 0}, it waits for
@code{wp_sec 10^6 + wp_usec} microseconds before returning 0 in case no
data can be written. If @code{wp_sec < 0}, then it waits until
the communication channel is ready to accept data. @code{wp_usec}
defaults to 0.
@quotation
@emph{Please Note}: The buffer of the @code{sockbuf} class is different
from the buffer of the communication channel buffer.
@end quotation

@item s.is_exceptionpending(wp_sec, wp_usec)
@findex sockbuf::is_exceptionpending
returns non-zero int if @code{s} has any exception events pending.
If @code{wp_sec >= 0}, it waits for @code{wp_sec 10^6 + wp_usec}
microseconds before returning 0 in case @code{s} does
not have any exception events pending. If @code{wp_sec < 0},
then it waits until an expception event occurs. @code{wp_usec} defaults
to 0.
@quotation
@emph{Please Note}: The exceptions that
@code{sockbuf::is_exceptionpending} is looking for are different from
the C++ exceptions.
@end quotation

@item s.flush_output()
@findex sockbuf::flush_output
flushes the output buffer and returns the number of chars flushed.
In case of error, return EOF. @code{sockbuf::flush_output} is a
protected member function and it is not available for general public.

@item s.doallocate()
@findex sockbuf::doallocate
allocates free store for read and write buffers of @code{s} and returns
1 if allocation is done and returns 0 if there is no need.
@code{sockbuf::doallocate} is a protected virtual member function and it
is not available for general public.

@item s.underflow()
@findex sockbuf::underflow
returns the unread char in the buffer as an unsigned char if there is
any. Else returns EOF if @code{s} cannot allocate space for the buffers,
cannot read or peer is closed. @code{sockbuf::underflow} is a protected
virtual member function and it is not available for general public.

@item s.overflow(c)
@findex sockbuf::overflow
if @code{c==EOF}, call and return the result of @code{flush_output()},
else if @code{c=='\n'} and @code{s} is linebuffered, call
@code{flush_output()} and return @code{c} unless @code{flush_output()}
returns EOF, in which case return EOF. In any other case, insert char
@code{c} into the buffer and return @code{c} as an unsigned char.
@code{sockbuf::overflow} is a protected member virtual function and it is not
available for general public.
@quotation
@emph{Node:} linebuffered mode does not work with AT&T IOStream library.
Use explicit flushing to flush @code{sockbuf}.
@end quotation

@item s.sync()
@findex sockbuf::sync
@cindex flushing output
calls @code{flush_output()} and returns the result. Useful if the user needs
to flush the output without writing newline char into the write buffer.

@item s.xsputn(buf, bufsz)
@findex sockbuf::xsputn
write @code{bufsz} chars into the buffer and returns the number of chars
successfully written. Output is flushed if any char in
@code{buf[0..bufsz-1]} is @code{'\n'}.

@item s.recvtimeout(wp)
@findex sockbuf::recvtimeout
sets the recv timeout to @code{wp} seconds. If @code{wp} is -1, it is a
block and if @code{wp} is 0, it is a poll.

It affects all read functions. If the socket is not read ready within
@code{wp} seconds, the read call will return 0. It also affects
@code{sockbuf::underflow}. @code{sockbuf::underflow} will not set the
@code{_S_EOF_SEEN} flag if it is returning EOF because of timeout.

@code{sockbuf::recvtimeout} returns the old recv timeout value.

@item s.sendtimeout(wp)
@findex sockbuf::sendtimeout
sets the send timeout to @code{wp} seconds. If @code{wp} is -1, it is a
block and if @code{wp} is 0, it is a poll.

It affects all write functions. If the socket is not write ready within
@code{wp} seconds, the write call will return 0. 

@code{sockbuf::sendtimeout} returns the old send timeout value.

@end table

@node Connection Establishment
@section Establishing connections
@cindex connection establishment
@cindex names

A name must be bound to a @code{sockbuf} if processes want to refer to
it and use it for communication. Names must be unique. A @var{unix} name
is a 3-tuple, @var{<protocol, local path, peer path>}. An @var{inet} name
is a 5-tuple, @var{<protocol, local addr, local port, peer addr, peer
port>}. @code{sockbuf::bind} is used to specify the local half of the
name---@var{<local path>} for @var{unix} and @var{<local addr, local
port>} for @var{inet}. @code{sockbuf::connect} and
@code{sockbuf::accept} are used to specify the peer half of the
name---@var{<peer path>} for @var{unix} and @var{<peer addr, peer port>}
for @var{inet}.

In what follows,
@itemize @minus
@item
@code{s} and @code{so} are @code{sockbuf} objects
@item
@code{sa} is a @code{sockAddr} object
@item
@code{nc} is an integer denoting the number of connections to allow
@end itemize

@table @code

@item s.bind(sa)
@findex sockbuf::bind
@cindex binding addresses
binds @code{sockAddr} @code{sa} as the local half of the name for
@code{s}. It returns 0 on success and returns the errno on failure.

@item s.connect(sa)
@findex sockbuf::connect
@cindex connect
@code{sockbuf::connect} uses @code{sa} to provide the peer half of the
name for @code{s} and to establish the connection itself.
@code{sockbuf::connect} also provides the local half of the name
automatically and hence, the user should not use @code{sockbuf::bind} to
bind any local half of the name. It returns 0 on success and returns
the errno on failure.


@item s.listen(nc)
@findex sockbuf::listen
@cindex listening
makes @code{s} ready to accept connections. @code{nc} specifies the
maximum number of outstanding connections that may be queued and must be
at least 1 and less than or equal to @code{sockbuf::somaxconn} which
is usually 5 on most systems.

@item sockbuf so = s.accept(sa)
@itemx sockbuf so = s.accept()
@findex sockbuf::accept
@cindex accepting connections
accepts connections and returns the peer address in @code{sa}. @code{s}
must be a listening @code{sockbuf}. See @code{sockbuf::listen} above.

@end table

@node Socket Options
@section Getting and Setting Socket Options
@cindex socket options
@cindex option setting
@cindex option getting

Socket options are used to control a socket communication. New options
can be set and old value of the options can be retrived at the protocol
level or at the socket level by using @code{setopt} and
@code{getopt} member functions. In addition, you can also use special
member functions to get and set specific options.

In what follows,
@itemize @minus
@item
@code{s} is a @code{sockbuf} object
@item
@code{opval} is an integer and denotes the option value
@item
@code{op} is of type @code{sockbuf::option} and must be one of
@itemize @bullet
@item
@code{sockbuf::so_error} used to retrieve and clear error status
@item
@code{sockbuf::so_type} used to retrieve type of the socket
@item
@code{sockbuf::so_debug} is used to specify recording of debugging
information
@item
@code{sockbuf::so_reuseaddr} is used to specify the reuse of local address
@item 
@code{sockbuf::so_keepalive} is used to specify whether to keep connections
alive or not
@item
@code{sockbuf::so_dontroute} is used to specify whether to route messages
or not
@item
@code{sockbuf::so_broadcast} is used to specify whether to broadcast
@code{sockbuf::sock_dgram} messages or not
@item
@code{sockbuf::so_oobinline} is used to specify whether to inline
@var{out-of-band} data or not.
@item
@code{sockbuf::so_linger} is used to specify for how long to linger before
shutting down
@item
@code{sockbuf::so_sndbuf} is used to retrieve and to set the size of the
send buffer (communication channel buffer not @code{sockbuf}'s internal
buffer)
@item
@code{sockbuf::so_rcvbuf} is used to retrieve and to set the size of the
recv buffer (communication channel buffer not @code{sockbuf}'s internal
buffer)
@end itemize
@end itemize

@table @code

@item s.getopt(op, &opval, sizeof(opval), oplevel)
@findex sockbuf::getopt
@cindex getsockopt
gets the option value of the @code{sockbuf::option} @code{op}  at the
option level @code{oplevel} in @code{opval}. It returns the actual size
of the buffer @code{opval} used. The default value of the @code{oplevel}
is @code{sockbuf::sol_socket}.

@item s.setopt(op, &opval, sizeof(opval), oplevel)
@findex sockbuf::setopt
@cindex setsockopt
sets the option value of the @code{sockbuf::option} @code{op}  at the
option level @code{oplevel} to @code{opval}. The default value of the
@code{oplevel} is @code{sockbuf::sol_socket}.

@item s.gettype()
@findex sockbuf::gettype
gets the socket type of @code{s}. The return type is
@code{sockbuf::type}.

@item s.clearerror()
@findex sockbuf::clearerror
gets and clears the error status of the socket.

@item s.debug(opval)
@findex sockbuf::debug
if @code{opval} is not -1, set the @code{sockbuf::so_debug} option value
to @code{opval}. In any case, return the old option value of
@code{sockbuf::so_debug} option. The default value of @code{opval} is
-1.

@item s.reuseaddr(opval)
@findex sockbuf::reuseaddr
if @code{opval} is not -1, set the @code{sockbuf::so_reuseaddr} option value
to @code{opval}. In any case, return the old option value of
@code{sockbuf::so_reuseaddr} option. The default value of @code{opval}
is -1.

@item s.dontroute(opval)
@findex sockbuf::dontroute
if @code{opval} is not -1, set the @code{sockbuf::so_dontroute} option value
to @code{opval}. In any case, return the old option value of
@code{sockbuf::so_dontroute} option. The default value of @code{opval}
is -1.

@item s.oobinline(opval)
@findex sockbuf::oobinline
if @code{opval} is not -1, set the @code{sockbuf::so_oobinline} option value
to @code{opval}. In any case, return the old option value of
@code{sockbuf::so_oobinline} option. The default value of @code{opval}
is -1.

@item s.broadcast(opval)
@findex sockbuf::broadcast
if @code{opval} is not -1, set the @code{sockbuf::so_broadcast} option value
to @code{opval}. In any case, return the old option value of
@code{sockbuf::so_broadcast} option. The default value of @code{opval}
is -1.

@item s.keepalive(opval)
@findex sockbuf::keepalive
if @code{opval} is not -1, set the @code{sockbuf::so_keepalive} option value
to @code{opval}. In any case, return the old option value of
@code{sockbuf::so_keepalive} option. The default value of @code{opval}
is -1.

@item s.sendbufsz(opval)
@findex sockbuf::sndbuf
if @code{opval} is not -1, set the new send buffer size to @code{opval}.
In any case, return the old buffer size of the send buffer. The default
value of @code{opval} is -1.

@item s.recvbufsz(opval)
@findex sockbuf::rcvbuf
if @code{opval} is not -1, set the new recv buffer size to @code{opval}.
In any case, return the old buffer size of the recv buffer. The default
value of @code{opval} is -1.

@item s.linger(tim)
@findex sockbuf::linger
if @code{tim} is positive, set the linger time to tim seconds.
If @code{tim} is 0, set the linger off.
In any case, return the old linger time if it was set earlier.
Otherwise return -1. The default value of @code{tim} is -1.

@end table

@node Timeouts
@section Time Outs While Reading and Writing
@cindex timeouts
@cindex read timeouts
@cindex write timeouts

Time outs are very useful in handling data of unknown sizes
and formats while reading and writing. For example, how does
one communicate with a socket that sends chunks of data
of unknown size and format? If only @code{sockbuf::read} is used
without time out, it will block indefinitely.
In such cases, time out facility is the only answer.

The following idiom is recommended. @xref{Pitfalls} for a complete
example.

@example
    int old_tmo = s.recvtimeout (2) // set time out (2 seconds here)
    for (;;) @{ // read or write
        char buf[256];
        int rval = s.read (buf, 256);
        if (rval == 0 || rval == EOF) break;
        // process buf here
    @}
    s.recvtimeout (old_tmo); // reset time out
@end example
        
In what follows,
@itemize @minus
@item
@code{s} is a @code{sockbuf} object
@item
@code{wp} is waiting period in seconds
@end itemize

@table @code

@item s.recvtimeout(wp)
@findex sockbuf::recvtimeout
sets the recv timeout to @code{wp} seconds. If @code{wp} is -1, it is a
block and if @code{wp} is 0, it is a poll.

It affects all read functions. If the socket is not read ready within
@code{wp} seconds, the read call will return 0. It also affects
@code{sockbuf::underflow}. @code{sockbuf::underflow} will not set the
@code{_S_EOF_SEEN} flag if it is returning EOF because of timeout.

@code{sockbuf::recvtimeout} returns the old recv timeout value.

@item s.sendtimeout(wp)
@findex sockbuf::sendtimeout
sets the send timeout to @code{wp} seconds. If @code{wp} is -1, it is a
block and if @code{wp} is 0, it is a poll.

It affects all write functions. If the socket is not write ready within
@code{wp} seconds, the write call will return 0. 

@code{sockbuf::sendtimeout} returns the old send timeout value.

@end table

@node sockAddr Class
@chapter sockAddr Class
@cindex sockAddr class
@cindex base address class

Class @code{sockAddr} is an abstract base class for all socket address
classes. That is, domain specific socket address classes are all derived
from @code{sockAddr} class. 
@quotation
@emph{Note}: @code{sockAddr} is not spelled @code{sockaddr} in
order to prevent name clash with @code{struct sockaddr} declared
in @file{<sys/socket.h>}.
@end quotation

Non-abstract derived classes must have definitions for the following
functions.

@table @code

@item sockAddr::operator void* ()
@findex sockAddr::operator void*
should simply return @code{this}.

@item sockAddr::size()
@findex sockAddr::size
should return @code{sizeof(*this)}. The return type is @code{int}.

@item sockAddr::family()
@findex sockAddr::family
should return address family (domain name) of the socket address. The
return type is @code{int}

@end table

@node sockinetbuf Class
@chapter sockinetbuf Class
@cindex sockinetbuf class
@cindex inet domain

@code{sockinetbuf} class is derived from @code{sockbuf} class and inherits
most of the public functions of @code{sockbuf}. @xref{sockbuf Class},
for more information on @code{sockbuf}. In addition, it provides methods
for getting @code{sockinetaddr} of local and peer connections.
@xref{sockinetaddr Class}, for more information on @code{sockinetaddr}.

@menu
* Methods sockinetbuf::         Describes sockinetbuf member functions.
* Datagram INET::               A pair of example programs demonstrating
                                    datagram connection in inet domain.
* Stream INET::                 A pair of example programs demonstrating
                                    stream connection in inet domain.
@end menu

@node Methods sockinetbuf
@section Methods

In what follows,
@itemize @minus
@item
@code{ty} denotes the type of the socket connection and is of type
@code{sockbuf::type}
@item
@code{proto} denotes the protocol and is of type int
@item
@code{si, ins} are @code{sockbuf} objects and are in @var{inet} domain
@item
@code{adr} denotes an @var{inet} address in host byte order and is of
type unsigned long
@item
@code{serv} denotes a service like "nntp" and is of type char*
@item
@code{proto} denotes a protocol like "tcp" and is of type char*
@item
@code{thostname} is of type char* and denotes the name of a host like
@code{"kelvin.acc.virginia.edu"} or @code{"128.143.24.31"}.
@item
@code{portno} denotes a port in host byte order and is of type int
@end itemize

@table @code

@item sockinetbuf ins(ty, proto)
@findex sockinetbuf::sockinetbuf
Constructs a @code{sockinetbuf} object @code{ins} whose socket
communication type is @code{ty} and protocol is @code{proto}.
@code{proto} defaults to 0. 

@item sockinetbuf ins(si)
Constructs a @code{sockinetbuf} object @code{ins} which uses the same
socket as @code{si} uses.

@item ins = si
@findex sockinetbuf::operator =
performs the same function as @code{sockbuf::operator=}.
@xref{sockbuf Class}, for more details.

@item ins.open(ty, proto)
@findex sockinetbuf::open
create a new @code{sockinetbuf} whose type and protocol are
@code{ty} and @code{proto} respectively and assign it to @code{ins}.

@item sockinetaddr sina = ins.localaddr()
@findex sockinetbuf::localaddr
@findex getsockname (see sockinetbuf::localaddr)
returns the local @var{inet} address of the @code{sockinetbuf} object
@code{ins}. The call will make sense only after a call to either
@code{sockbuf::bind} or @code{sockbuf::connect}.

@item sockinetaddr sina = ins.peeraddr()
@findex sockinetbuf::peeraddr
@findex getpeername (see sockinetbuf::peeraddr)
returns the peer @var{inet} address of the @code{sockinetbuf} object
@code{ins}. The call will make sense only after a call to
@code{sockbuf::connect}.

@item const char* hn = ins.localhost()
@findex sockinetbuf::localhost
returns the local @var{inet} thostname of the @code{sockinetbuf} object
@code{ins}. The call will make sense only after a call to either
@code{sockbuf::bind} or @code{sockbuf::connect}.

@item const char* hn = ins.peerhost()
@findex sockinetbuf::peerhost
returns the peer @var{inet} thostname of the @code{sockinetbuf} object
@code{ins}. The call will make sense only after a call to
@code{sockbuf::connect}.

@item int pn = ins.localport()
@findex sockinetbuf::localport
returns the local @var{inet} port number of the @code{sockinetbuf} object
@code{ins} in host byte order. The call will make sense only after a
call to either @code{sockbuf::bind} or @code{sockbuf::connect}.

@item int pn = ins.peerport()
@findex sockinetbuf::peerport
returns the peer @var{inet} port number of the @code{sockinetbuf} object
@code{ins} in local host byte order. The call will make sense only after a
call to @code{sockbuf::connect}.

@item ins.bind ()
@findex sockinetbuf::bind
binds @code{ins} to the default address @var{INADDR_ANY} and the default
port. It returns 0 on success and returns the errno on failure.

@item ins.bind (adr, portno)
binds @code{ins} to the address @code{adr} and the port @code{portno}.
It returns 0 on success and returns the errno on failure.

@item ins.bind (adr, serv, proto)
binds @code{ins} to the address, @code{adr} and the port corresponding to
the service @code{serv} and the protocol @code{proto}>.
It returns 0 on success and returns the errno on failure.

@item ins.bind (thostname, portno)
binds @code{ins} to the address corresponding to the hostname
@code{thostname} and the port @code{portno}.
It returns 0 on success and returns the errno on failure.

@item ins.bind (thostname, serv, proto)
binds @code{ins} to the address corresponding to the hostname
@code{thostname} and the port corresponding to the service @code{serv}
and the protocol @code{proto}>. It returns 0 on success and
returns the errno on failure.

@item ins.connect (adr, portno)
@findex sockinetbuf::connect
connects @code{ins} to the address @code{adr} and the port @code{portno}.
It returns 0 on success and returns the errno on failure.

@item ins.connect (adr, serv, proto)
connects @code{ins} to the address, @code{adr} and the port corresponding to
the service @code{serv} and the protocol @code{proto}>.
It returns 0 on success and returns the errno on failure.

@item ins.connect (thostname, portno)
connects @code{ins} to the address corresponding to the hostname
@code{thostname} and the port @code{portno}.
It returns 0 on success and returns the errno on failure.

@item ins.connect (thostname, serv, proto)
connects @code{ins} to the address corresponding to the hostname
@code{thostname} and the port corresponding to the service @code{serv}
and the protocol @code{proto}>.
It returns 0 on success and returns the errno on failure.

@end table

@node Datagram INET
@section @var{inet} Datagram Sockets
@cindex sockinetbuf dgram example
@cindex datagram inet
@cindex isockinet example
@cindex osockinet example

The following two programs illustrates how to use @code{sockinetbuf} class
for datagram connection in @var{inet} domain. @code{tdinread.cc} also
shows how to use @code{isockinet} class and @code{tdinwrite.cc} shows
how to use @code{osockinet} class.

@subheading tdinread.cc
@example
// reads data sent by tdinwrite.cc
#include <sockinet.h>

int main(int ac, char** av)
@{
        isockinet  is (sockbuf::sock_dgram);
        is->bind();

        cout << "localhost = " << so.localhost() << endl
             << "localport = " << so.localport() << endl;

        char         buf[256];
        int          n;

        is >> n;
        cout << av[0] << ": ";
        while(n--) @{
                is >> buf;
                cout << buf << ' ';
        @}
        cout << endl;

        return 0;
@}
@end example

@subheading tdinwrite.cc
@example
// sends data to tdinread.cc
#include <sockinetbuf.h>
#include <stdlib.h>

int main(int ac, char** av)
@{
        if (ac < 3) @{
                cerr << "USAGE: " << av[0] << " thostname port-number "
                     << "data ... " << endl;
                return 1;
        @}

        osockinet os (sockbuf::sock_dgram);
        os->connect (av[1], atoi(av[2]));

        cout << "local: " << so.localport() << ' '
                          << so.localhost() << endl
             << "peer:  " << so.peerport() << ' '
                          << so.peerhost() << endl;

        os << ac-3; av += 3;
        while(*av) os << *av++ << ' ';
        os << endl;

        return 0;        
@}

@end example

@node Stream INET
@section @var{inet} Stream Sockets
@cindex stream inet
@cindex sockinetbuf stream example
@cindex iosockinet example

The following two programs illustrates the use of @code{sockinetbuf} class
for stream connection in @var{inet} domain. It also shows how to use
@code{iosockinet} class.

@subheading tsinread.cc
@example
// receives strings from tsinwrite.cc and sends the strlen
// of each string back to tsinwrite.cc
#include        <sockinet.h>

int main()
@{
        sockinetbuf     si(sockbuf::sock_stream);
        si.bind();

        cout << si.localhost() << ' ' << si.localport() << endl;
        si.listen();

        iosockinet s = si.accept();
        char          buf[1024];

        while (s >> buf) @{
                cout << buf << ' ';
                s << ::strlen(buf) << endl;
        @}
        cout << endl;
        
        return 0;
@}
@end example

@subheading tsinwrite.cc
@example
// sends strings to tsinread.cc and gets back their length
// usage: tsinwrite hostname portno
//        see the output of tsinread for what hostname and portno to use

#include        <sockinet.h>
#include        <stdlib.h>

int main(int ac, char** av)
@{
        iosockinet sio (sockbuf::sock_stream);
        sio->connect (av[1], atoi (av[2]));

        sio << "Hello! This is a test\n" << flush;

        // terminate the while loop in tsinread.cc
        si.shutdown(sockbuf::shut_write);

        int len;
        while (s >> len) cout << len << ' ';
        cout << endl;

        return 0;
@}
@end example

@node sockinetaddr Class
@chapter sockinetaddr Class
@cindex sockinetaddr class
@cindex inet address class

Class @code{sockinetaddr} is derived from @code{sockAddr} declared in
@code{<sockstream.h>} and from @code{sockaddr_in} declared in
@code{<netinet/in.h>}. Always use a @code{sockinetaddr} object for an
address with @var{inet} domain of sockets. @xref{Connection
Establishment}.

In what follows,
@itemize @minus
@item
@code{adr} denotes an @var{inet} address in host byte order and is of
type unsigned long
@item
@code{serv} denotes a service like "nntp" and is of type char*
@item
@code{proto} denotes a protocol like "tcp" and is of type char*
@item
@code{thostname} is of type char* and denotes the name of a host like
@code{"kelvin.acc.virginia.edu"} or @code{"128.143.24.31"}.
@item
@code{portno} denotes a port in host byte order and is of type int
@end itemize

@table @code

@item sockinetaddr sina
@findex sockinetaddr::sockinetaddr
Constructs a @code{sockinetaddr} object @code{sina} with default address
@var{INADDR_ANY} and default port number 0.

@item sockinetaddr sina(adr, portno)
Constructs a @code{sockinetaddr} object @code{sina} setting inet address
to @code{adr} and the port number to @code{portno}. @code{portno}
defaults to 0.

@item sockinetaddr sina(adr, serv, proto)
Constructs a @code{sockinetaddr} object @code{sina} setting inet address
to @code{adr} and the port number corresponding to the service
@code{serv} and the protocol @code{proto}. The protocol defaults to "tcp".

@item sockinetaddr sina(thostname, portno)
Constructs a @code{sockinetaddr} object @code{sina} setting inet address
to the address of @code{thostname} and the port number to @code{portno}.
@code{portno} defaults to 0.

@item sockinetaddr sina(thostname, serv, proto)
Constructs a @code{sockinetaddr} object @code{sina} setting inet address
to the address of @code{thostname} and the port number corresponding to
the service @code{serv} and the protocol @code{proto}. The protocol
defaults to "tcp".

@item void* a = sina
@findex sockinetaddr::operator void*
returns the address of the @code{sockaddr_in} part of
@code{sockinetaddr} object @code{sina} as void*.

@item int sz = sina.size()
@findex sockinetaddr::size
returns the sizeof @code{sockaddr_in} part of @code{sockinetaddr} object
@code{sina}.

@item int af = sina.family()
@findex sockinetaddr::family
returns @code{sockinetbuf::af_inet} if all is well.

@item int pn = sina.getport()
@findex sockinetaddr::getport
returns the port number of the @code{sockinetaddr} object @code{sina} in
host byte order.

@item const char* hn = getthostname()
@findex sockinetaddr::getthostname
returns the host name of the @code{sockinetaddr} object @code{sina}.

@end table

@node sockunixbuf Class
@chapter sockunixbuf Class
@cindex sockunixbuf class
@cindex unix domain

@code{sockunixbuf} class is derived from @code{sockbuf} class declared in
@code{<sockstream.h>} and hence, inherits most of the public member
functions of @code{sockbuf}. @xref{sockbuf Class}, for more information
on @code{sockbuf}. 

@menu
* Methods sockunixbuf::         Describes sockunixbuf member functions
* Datagram UNIX::               A pair of example programs demonstrating
                                    datagram connection in @var{unix} domain
* Stream UNIX::                 A pair of example programs demonstrating
                                    stream connection in @var{unix} domain
@end menu

@node Methods sockunixbuf
@section Methods

In what follows,
@itemize @minus
@item
@code{ty} denotes the socket type and is of type @code{sockbuf::type}
@item
@code{proto} denotes the protocol number and is of type int
@item
@code{su} is a @code{sockbuf} and must be in @var{unix} domain
@item
@code{path} is the @var{unix} path name like "/tmp/unix_socket"
@end itemize

@table @code

@item sockunixbuf uns(ty, proto)
@findex sockunixbuf::sockunixbuf
Constructs a @code{sockunixbuf} object @code{uns} with @code{ty} as its
type and @code{proto} as its protocol number. @code{proto} defaults to
0.

@item sockunixbuf uns = su
Constructs a @code{sockunixbuf} object @code{uns} which uses the same
socket as is used by @code{su}.

@item uns = su
@findex sockunixbuf::operator =
@code{sockunixbuf} object @code{uns} closes its current socket if no other
@code{sockbuf} is referring to it and uses the socket that @code{sockbuf}
object @code{su} is using.

@item uns.open(ty, proto)
@findex sockunixbuf::open
create a @code{sockunixbuf} object with @code{ty} as its type and
@code{proto} as its protocol and assign the @code{sockunixbuf} object so
created to @code{*this}. It returns @code{this}. @code{proto} defaults
to 0.

@item uns.bind(path)
@findex sockunixbuf::bind
binds @code{uns} to the @var{unix} pathname @code{path}.
It returns 0 on success and returns the errno on failure.

@item uns.connect(path)
@findex sockunixbuf::connect
connects @code{uns} to the @var{unix} pathname @code{path}.
It returns 0 on success and returns the errno on failure.

@end table

@node Datagram UNIX
@section @var{unix} Datagram Sockets
@cindex datagram unix
@cindex isockunix example
@cindex osockunix example

The following two programs illustrates how to use @code{sockunixbuf} class
for datagram connection in @var{unix} domain. @code{tdunread.cc} also
shows how to use @code{isockunix} class and @code{tdunwrite.cc} shows
how to use @code{osockunix} class.

@subheading tdunread.cc
@example
// reads data sent by tdunwrite.cc
#include <sockunix.h>
#include <unistd.h>
#include <errno.h>

int main(int ac, char** av)
@{
        if (ac != 2) @{
                cerr << "USAGE: " << av[0] << " socket_path_name\n";
                return 1;
        @}
        
        // isockunix builds the sockunixbuf object
        isockunix       su (sockbuf::sock_dgram);
    
        su->bind(av[1]);

        cout << "Socket name = " << av[1] << endl;

        if (chmod(av[1], 0777) == -1) @{
                perror("chmod");
                return 1;
        @}

        char buf[1024];
        int i;
        su >> i;
        cout << av[0] << ": " << i << " strings: ";
        while (i--) @{
                su >> buf;
                cout  << buf << ' ';
        @}
        cout << endl;
        
        unlink(av[1]);
        return 0;
@}
@end example

@subheading tdunwrite.cc
@example
// sends data to tdunread.cc
#include <sockunix.h>

int main(int ac, char** av)
@{
        if (ac < 2) @{
                cerr << "USAGE: " << av[0]
                     << " socket_path_name data...\n";
                return 1;
        @}

        osockunix       su (sockbuf::sock_dgram);

        su->connect (av[1]);

        su << ac << ' ';
        while (*av) @{ su << av[i] << ' '; av++; @}
        su << endl;

        return 0;
@}
@end example

@node Stream UNIX
@section @var{unix} Stream Sockets
@cindex stream unix
@cindex sockunixbuf example
@cindex iosockunix example

The following two programs illustrates how to use @code{sockunixbuf} class
for stream connection in @var{unix} domain. It also shows how to use
@code{iosockunix} class.

@subheading tsunread.cc
@example
// exchanges char strings with tsunwrite.cc
#include <sockunix.h>
#include <unistd.h>
#include <errno.h>

int main(int ac, char** av)
@{
        if (ac != 2) @{
                cerr << "USAGE: " << av[0] << " socket_path_name\n";
                return 1;
        @}
        
        sockunixbuf  su(sockbuf::sock_stream);
        su.bind(av [1]);

        cout << "Socket name = " << av[1] << endl;

        if (chmod(av[1], 0777) == -1) @{
                perror("chmod");
                return 1;
        @}

        su.listen(3);
        
        iosockunix ioput = su.accept ();
        char       buf[1024];
        
        ioput << av[0] << ' ' << av[1] << endl;
        while ( ioput >> buf ) cout << av[0] << ": " << buf << endl;
        unlink(av[1]);
        return 0;
@}
@end example

@subheading tsunwrite.cc
@example
// exchanges char strings with tsunread.cc
#include <sockunix.h>

int main(int ac, char** av)
@{
        if (ac < 2) @{
                cerr << "USAGE: " << av[0]
                     << " socket_path_name data...\n";
                return 1;
        @}

        iosockunix oput (sockbuf::sock_stream);
        oput->connect (av [1]);

        char buf[128];

        oput >> buf;
        cout << buf << ' ';
        oput >> buf;
        cout << buf << endl;

        while (*av) oput << *av++ << ' ';
        oput << endl;
        
        return 0;
@}
@end example

@node sockunixaddr Class
@chapter sockunixaddr Class
@cindex sockunixaddr class
@cindex unix address class

Class @code{sockunixaddr} is derived from class @code{sockAddr} declared in
@code{<sockstream.h>} and from struct @code{sockaddr_un} declared in
@code{<sys/un.h>}. Always use @code{sockunixaddr} objects for addresses
with @var{unix} domain of sockets. @xref{Connection Establishment}.

In what follows,
@itemize @minus
@item
@code{path} is the @var{unix} path name like "/tmp/unix_socket"
@end itemize

@table @code

@item sockunixaddr suna(path)
@findex sockunixaddr::sockunixaddr
Constructs a @code{sockunixaddr} object @code{suna} with @code{path} as
the @var{unix} path name.

@item void* a = suna
@findex sockunixaddr::operator void*
returns the address of the @code{sockaddr_un} part of
@code{sockunixaddr} object @code{suna} as void*.

@item int sz = suna.size()
@findex sockunixaddr::size
returns the sizeof @code{sockaddr_un} part of @code{sockunixaddr} object
@code{suna}.

@item int af = suna.family()
@findex sockunixaddr::family
returns @code{sockunixbuf::af_unix} if all is well.

@end table

@node sockstream Classes
@chapter sockstream Classes
@cindex sockstream classes
@cindex iosockstream classes

sockstream classes are designed in such a way that they provide the same
interface as their stream counterparts do. We have @code{isockstream}
derived from @code{istream} and @code{osockstream} derived from
@code{ostream}. We also have @code{iosockstream} which is derived from
@code{iostream}.

Each domain also has its own set of @code{stream} classes. For example,
@code{unix} domain has @code{isockunix}, @code{osockunix}, and
@code{iosockunix} derived from @code{isockstream}, @code{osockstream},
and @code{iosockstream} respectively. Similarly, @code{inet} domain has
@code{isockinet}, @code{osockinet}, and @code{iosockinet}.

@menu
* iosockstream::             Generic IOStream classes for sockbuf
                                   buffers.
* iosockinet::               IOStream classes for @var{inet} domain of
                                   sockets.
* iosockunix::               IOStream classes for @var{unix} domain of
                                   sockets.
@end menu

@node iosockstream
@section iosockstreams

@subsection isockstream Class
@cindex isockstream class

Since @code{isockstream} is publicly derived from @code{istream}, most
of the public functions of @code{istream} are also available in
@code{isockstream}. 

@code{isockstream} redefines @code{rdbuf()} defined in its virtual base
class @code{ios}. Since, @code{ios::rdbuf()} is not virtual, care must
be taken to call the correct @code{rdbuf()} through a reference or a
pointer to an object of class @code{isockstream}.

In what follows,
@itemize @minus
@item
@code{sb} is a @code{sockbuf} object
@item
@code{sbp} is a pointer to a @code{sockbuf} object
@end itemize

@table @code

@item isockstream is(sb)
@findex isockstream::isockstream
Constructs an @code{isockstream} object @code{is} with @code{sb} as its
@code{sockbuf}.

@item isockstream is(sbp)
Constructs an @code{isockstream} object @code{is} with @code{*sbp} as its
@code{sockbuf}.

@item sbp = is.rdbuf()
@findex isockstream::rdbuf
returns a pointer to the @code{sockbuf} of the @code{isockstream} object
@code{is}.

@item isockstream::operator -> ()
@findex isockstream::operator->
returns a pointer to the @code{isockstream}'s @code{sockbuf} so that
the user can use @code{isockstream} object as a @code{sockbuf} object.

@example
    is->connect (sa); // same as is.rdbuf()->connect (sa);
@end example

@end table

@subsection osockstream Class
@cindex osockstream class

Since @code{osockstream} is publicly derived from @code{ostream}, most
of the public functions of @code{ostream} are also available in
@code{osockstream}. 

@code{osockstream} redefines @code{rdbuf()} defined in its virtual base
class @code{ios}. Since, @code{ios::rdbuf()} is not virtual, care must
be taken to call the correct @code{rdbuf()} through a reference or a
pointer to an object of class @code{osockstream}.

In what follows,
@itemize @minus
@item
@code{sb} is a @code{sockbuf} object
@item
@code{sbp} is a pointer to a @code{sockbuf} object
@end itemize

@table @code

@item osockstream os(sb)
@findex osockstream::osockstream
Constructs an @code{osockstream} object @code{os} with @code{sb} as its
@code{sockbuf}.

@item osockstream os(sbp)
Constructs an @code{osockstream} object @code{os} with @code{*sbp} as its
@code{sockbuf}.

@item sbp = os.rdbuf()
@findex osockstream::rdbuf
returns a pointer to the @code{sockbuf} of the @code{osockstream} object
@code{os}.

@item osockstream::operator -> ()
@findex osockstream::operator->
returns a pointer to the @code{osockstream}'s @code{sockbuf} so that
the user can use @code{osockstream} object as a @code{sockbuf} object.

@example
    os->connect (sa); // same as os.rdbuf()->connect (sa);
@end example

@end table

@subsection iosockstream Class
@cindex iosockstream class

Since @code{iosockstream} is publicly derived from @code{iostream}, most
of the public functions of @code{iostream} are also available in
@code{iosockstream}. 

@code{iosockstream} redefines @code{rdbuf()} defined in its virtual base
class @code{ios}. Since, @code{ios::rdbuf()} is not virtual, care must
be taken to call the correct @code{rdbuf()} through a reference or a
pointer to an object of class @code{iosockstream}.

In what follows,
@itemize @minus
@item
@code{sb} is a @code{sockbuf} object
@item
@code{sbp} is a pointer to a @code{sockbuf} object
@end itemize

@table @code

@item iosockstream io(sb)
@findex iosockstream::iosockstream
Constructs an @code{iosockstream} object @code{io} with @code{sb} as its
@code{sockbuf}.

@item iosockstream io(sbp)
Constructs an @code{iosockstream} object @code{io} with @code{*sbp} as its
@code{sockbuf}.

@item sbp = io.rdbuf()
@findex iosockstream::rdbuf
returns a pointer to the @code{sockbuf} of the @code{iosockstream} object
@code{io}.

@item iosockstream::operator -> ()
@findex iosockstream::operator->
returns a pointer to the @code{iosockstream}'s @code{sockbuf} so that
the user can use @code{iosockstream} object as a @code{sockbuf} object.

@example
    io->connect (sa); // same as io.rdbuf()->connect (sa);
@end example

@end table

@node iosockinet
@section iosockinet Stream Classes

We discus only @code{isockinet} class here. @code{osockinet} and
@code{iosockinet} are similar and are left out. However, they are
covered in the examples that follow.

@subsection isockinet
@cindex isockinet class
@cindex class isockinet

@code{isockinet} is used to handle interprocess communication in
@var{inet} domain. It is derived from @code{isockstream} class and it
uses a @code{sockinetbuf} as its stream buffer. @xref{iosockstream}, for
more details on @code{isockstream}. @xref{sockinetbuf Class}, for
information on @code{sockinetbuf}.

In what follows,
@itemize @minus
@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}
@item
@code{proto} denotes the protocol number and is of type int
@item
@code{sb} is a @code{sockbuf} object and must be in @var{inet} domain
@item
@code{sinp} is a pointer to an object of @code{sockinetbuf}
@end itemize

@table @code

@item isockinet is (ty, proto)
@findex isockinet::isockinet
constructs an @code{isockinet} object @code{is} whose @code{sockinetbuf}
buffer is of the type @code{ty} and has the protocol number
@code{proto}. The default protocol number is 0.

@item isockinet is (sb)
constructs a @code{isockinet} object @code{is} whose @code{sockinetbuf}
is @code{sb}. @code{sb} must be in @var{inet} domain.

@item isockinet is (sinp)
constructs a @code{isockinet} object @code{is} whose @code{sockinetbuf}
is @code{sinp}.

@item sinp = is.rdbuf ()
@findex isockinet::rdbuf
returns a pointer to the @code{sockinetbuf} of @code{isockinet} object
@code{is}.

@item isockinet::operator ->
@findex isockinet::operator->
returns @code{sockinetbuf} of @code{sockinet} so that the @code{sockinet}
object acts as a smart pointer to @code{sockinetbuf}.

@example
        is->localhost (); // same as is.rdbuf ()->localhost ();
@end example

@end table

@subsection iosockinet examples
@cindex iosockinet examples

The first pair of examples demonstrates datagram socket connections in the
@var{inet} domain. First, @code{tdinread} prints its local host and
local port on stdout and waits for input in the connection.
@code{tdinwrite} is started with the local host and local port of
@code{tdinread} as arguments. It sends the string "How do ye do!" to
@code{tdinread} which in turn reads the string and prints on its stdout.

@example
// tdinread.cc
#include <sockinet.h>

int main ()
@{
    char buf[256];
    isockinet is (sockbuf::sock_dgram);
    is->bind ();

    cout << is->localhost() << ' ' << is->localport() << endl;

    is.getline (buf);
    cout << buf << endl;

    return 0;
@}
@end example

@example
// tdinwrite.cc--tdinwrite hostname portno
#include <sockinet.h>
#include <stdlib.h>

int main (int ac, char** av)
@{
    osockinet os (sockbuf::sock_dgram);
    os->connect (av[1], atoi(av[2]));
    os << "How do ye do!" << endl;
    return 0;
@}
@end example

The next example communicates with an nntp server through a
@code{sockbuf::sock_stream} socket connection in @var{inet} domain.
After establishing a connection to the nntp server, it sends a "HELP"
command and gets back the HELP message before sending the "QUIT"
command.

@example
// tnntp.cc
#include <sockinet.h>

int main ()
@{
    char  buf[1024];
    iosockinet io (sockbuf::sock_stream);
    io->connect ("murdoch.acc.virginia.edu", "nntp", "tcp");
    io.getline (buf, 1024); cout << buf << endl;
    io << "HELP\r\n" << flush;
    io.getline (buf, 1024); cout << buf << endl;
    while (io.getline (buf, 1024))
        if (buf[0] == '.' && buf[1] == '\r') break;
        else if (buf[0] == '.' && buf[1] == '.') cout << buf+1 << endl;
        else cout << buf << endl;
    io << "QUIT\r\n" << flush;
    io.getline (buf, 1024); cout << buf << endl;
    return 0;
@}
@end example

@node iosockunix
@section iosockunix Classes
@cindex iosockunix class

We discuss only @code{isockunix} here. @code{osockunix} and
@code{iosockunix} are similar.

@subsection isockunix class
@cindex isockunix class
@cindex class isockunix

@code{isockunix} is used to handle interprocess communication in
@var{unix} domain. It is derived from @code{isockstream} class and it
uses a @code{sockunixbuf} as its stream buffer. @xref{iosockstream}, for
more details on @code{isockstream}. @xref{sockunixbuf Class}, for
information on @code{sockunixbuf}.

In what follows,
@itemize @minus
@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}
@item
@code{proto} denotes the protocol number and is of type int
@item
@code{sb} is a @code{sockbuf} object and must be in @var{unix} domain
@item
@code{sinp} is a pointer to an object of @code{sockunixbuf}
@end itemize

@table @code

@item isockunix is (ty, proto)
@findex isockunix::isockunix
constructs an @code{isockunix} object @code{is} whose @code{sockunixbuf}
buffer is of the type @code{ty} and has the protocol number
@code{proto}. The default protocol number is 0.

@item isockunix is (sb)
constructs a @code{isockunix} object @code{is} whose @code{sockunixbuf}
is @code{sb}. @code{sb} must be in @var{unix} domain.

@item isockunix is (sinp)
constructs a @code{isockunix} object @code{is} whose @code{sockunixbuf}
is @code{sinp}.

@item sinp = is.rdbuf ()
@findex isockunix::rdbuf
returns a pointer to the @code{sockunixbuf} of @code{isockunix} object
@code{is}.

@item isockunix::operator ->
@findex isockunix::operator->
returns @code{sockunixbuf} of @code{sockunix} so that the @code{sockunix}
object acts as a smart pointer to @code{sockunixbuf}.

@example
        is->localhost (); // same as is.rdbuf ()->localhost ();
@end example

@end table

@subsection iosockunix examples
@cindex iosockunix examples

@code{tsunread} listens for connections. When @code{tsunwrite} requests
connection, @code{tsunread} accepts it and waits for input.
@code{tsunwrite} sends the string "Hello!!!" to @code{tsunread}.
@code{tsunread} reads the string sent by @code{tsunwrite} and prints on
its stdout.

@example
// tsunread.cc
#include <sockunix.h>
#include <unistd.h>

int main ()
@{
    sockunixbuf sunb (sockbuf::sock_stream);
    sunb.bind ("/tmp/socket+-");
    sunb.listen (2);
    isockunix is = sunb.accept ();
    char buf[32];
    is >> buf; cout << buf << endl;
    unlink ("/tmp/socket+-");
    return 0;
@}
@end example

@example
// tsunwrite.cc
#include <sockunix.h>
int main ()
@{
    osockunix os (sockbuf::sock_stream);
    os->connect ("/tmp/socket++");
    os << "Hello!!!\n" << flush;
    return 0;
@}
@end example    

@node pipestream Classes
@chapter pipestream Classes
@cindex pipestream classes
@cindex pipestream examples
@findex popen
@findex pipe
@findex socketpair

@code{pipestream} stream classes provide the services of the @var{UNIX}
system calls @code{pipe} and @code{socketpair} and the C library
function @code{popen}. @code{ipipestream}, @code{opipestream}, and
@code{iopipestream} are obtained by simply deriving from
@code{isockstream}, @code{osockstream} and @code{iosockstream}
respectively. @xref{sockstream Classes} for details.

In what follows,
@itemize @minus
@item
@code{ip} is an @code{ipipestream} object
@item
@code{op} is an @code{opipestream} object
@item
@code{iop} is an @code{iopipestream} object
@item
@code{cmd} is a char* denoting an executable like "wc"
@item
@code{ty} is of type @code{sockbuf::type} indicating the type of the
connection
@item
@code{proto} is an @code{int} denoting a protocol number
@end itemize

@table @code

@item ipipestream ip(cmd)
@findex ipipestream::ipipestream
construct an @code{ipipestream} object @code{ip} such that the output of
the command @code{cmd} is available as input through @code{ip}.

@item opipestream op(cmd)
@findex opipestream::opipestream
construct an @code{opipestream} object @code{op} such that the input for
the command @code{cmd} can be send through @code{op}.

@item iopipestream iop(cmd)
@findex iopipestream::iopipestream
construct an @code{iopipestream} object @code{iop} such that the input
and the output to the command @code{cmd} can be sent and received
through @code{iop}.

@item iopipestream iop(ty, proto)
construct a @code{iopipestream} object @code{iop} whose socket is a
socketpair of type @code{ty} with protocol number @code{proto}.
@code{ty} defaults to @code{sockbuf::sock_stream} and @code{proto}
defaults to 0. Object @code{iop} can be used either as a @code{pipe} or
as a @code{socketpair}.

@item iop.pid ()
@findex iopipestream::pid
return the process id of the child if the current process is the parent
or return 0. If the process has not forked yet, return -1.

@item iopipestream::fork ()
@findex iopipestream::fork
@code{fork()} is a static function of class @code{iopipestream}.
@code{fork()} forks the current process and appropriately sets the
@code{cpid} field of the @code{iopipestream} objects that have not
forked yet.

@end table

@menu
* pipe Example::                 How to use pipestream as pipe?
* socketpair Example::           How to use pipestream as socketpair?
* popen Example::                How to use pipestream as popen?
@end menu

@node pipe Example
@section pipestream as pipe
@cindex pipe example

@code{pipe} is used to communicate between parent and child processes in
the @var{unix} domain. 

The following example illustrates how to use @code{iopipestream} class as
a @code{pipe}. The parent sends the string "I am the parent" to the
child and receives the string "I am the child" from child. The child, in
turn, receives the string "I am the parent" from parent and sends the
string "I am the child" to the parent. Note the same @code{iopipestream}
object is used for input and output in each process.

@example
#include <pipestream.h>

int main()
@{
        iopipestream p;
        if ( p.fork() ) @{
                char buf[128];
                p << "I am the parent\n" << flush;
                cout << "parent: ";
                while(p >> buf)
                        cout << buf << ' ';
                cout << endl;
        @}else @{
                char buf[128];
                p.getline(buf, 127);
                cout << "child: " << buf << endl;
                p << "I am the child\n" << flush;
        @}
        return 0;
@}
@end example

@node socketpair Example
@section pipestream as socketpair
@cindex socketpair example

Like pipes, socketpairs also allow communication between parent and
child processes. But socketpairs are more flexible than pipes in the
sense that they let the users choose the socket type and protocol.

The following example illustrates the use of @code{iopipestream} class as
a @code{socketpair} whose type is @code{sockbuf::sock_dgram}. The parent
sends the string "I am the parent" to the child and receives the string
"I am the child" from the child. The child, in turn, receives and sends
the strings "I am the parent" and "I am the child" respectively from and
to the parent. Note in the following example that the same
@code{iopipestream} object is used for both the input and the output in
each process.

@example
#include <pipestream.h>

int main()
@{
        iopipestream p(sockbuf::sock_dgram);
        if ( iopipestream::fork() ) @{
                char buf[128];
                p << "I am the parent\n" << flush;
                p.getline(buf, 127);
                cout << "parent: " << buf << endl;
        @}else @{
                char buf[128];
                p.getline(buf, 127);
                cout << "child: " << buf << endl;
                p << "I am the child\n" << flush;
        @}
        return 0;
@}
@end example

@node popen Example
@section pipestream as popen
@cindex popen example

@code{popen} is used to call an executable and send inputs and
outputs to that executable. For example, the following example
executes "/bin/date", gets its output, and prints it to stdout.

@example
#include <pipestream.h>

int main ()
@{
    char buf[128];
    ipipestream p("/bin/date");

    p.getline (buf, 127);
    cout << buf << endl;
    return 0;
@}
@end example

Here is an example that prints "Hello World!!" on stdout. It uses
@code{opipestream} object.

@example
#include <pipestream.h>

int main ()
@{
    opipestream p("/bin/cat");
    p << "Hello World!!\n" << endl;
    return 0;
@}
@end example

The following example illustrates the use of @code{iopipestream} for
both input and output.

@example
#include <pipestream.h>

int main()
@{
        char buf[128];
        iopipestream p("lpc");
        p << "help\nquit\n" << flush;
        while ( p.getline(buf, 127) ) cout << buf << endl;
        return 0;
@}
@end example

@node Fork Class
@chapter Fork Class
@cindex fork class

You can effectively use the @code{Fork} wrapper class to create child
processes. You can use the @code{Fork} class, instead of directly using the
system call fork (), if you desire the following:

@itemize @bullet
@item
Avoid zombie processes
@item
Optionally kill child processes when the parent process terminates.
@item
Want to know the reason for abnormal termination of child processes.
@end itemize

In what follows,
@itemize @minus
@item
@code{killchild} is an integer.
@item
@code{reason} is an integer.
@item
@code{signo} is a valid signal.
@item
@code{f} is a @code{Fork} object.
@end itemize

@table @code

@item Fork f(killchild, reason)
@findex Fork::Fork
constructs a @code{Fork} object @code{f}. The constructor creates a child
process. When the parent process terminates, it will kill the child
process if @code{killchild} is not 0. Otherwise, the parent process will
wait until all its child processes die. If @code{reason} is not 0, then
it gives the reason for a child process's death on the stderr.

@item f.is_child ()
@findex Fork::is_child
returns 1 if the current process is the child process following the
fork in constructing the @code{Fork} object @code{f}. Otherwise, return 0.

@item f.is_parent ()
@findex Fork::is_parent
returns 1 if the current process is the parent process following the
fork in constructing the @code{Fork} object @code{f}. Otherwise, return 0.

@item f.process_id ()
@findex Fork::process_id
returns the process id of the child process, if the current process
is the parent process. Returns 0, if the current process is the child
process. Returns -1, if fork failed.

@item Fork::suicide_signal (signo)
@findex Fork::suicide_signal
is a static function. Upon the reciept of the signal
@code{signo}, the current process will kill all its child processes
created through @code{Fork::Fork(int, int)} irrespective of the value of
the @code{killchild} flag used in the construction of the @code{Fork}
objects. @code{signo} defaults to SIGTERM signal.

@end table

@section Fork Example
@cindex fork example

The following example illustrates the use of the @code{Fork} class to
create child processes. First, we set up @var{SIGTERM} signal handler
to kill all the child processes, by callling @code{Fork::suicide_signal
()}. Second, we create several child and grandchild processes.

You can kill the top most parent process and all its children by sending
a @var{SIGTERM} signal to the top most parent process.

@example
// tfork.C
#include <iostream.h>
#include <Fork.h>

static void print (char* name, pid_t child)
@{
  if (child)
    cerr << "Parent " << getppid () << "; "
      << name << ' ' << getpid () << "; Child " << child << ";\n";
@}

int main (int ac, char** av)
@{
  Fork::suicide_signal (SIGTERM);

  Fork a(0, 1);
  
  print ("a", a.process_id ());

  if (a.is_child ()) @{
    sleep (3000);
  @} else if (a.is_parent ()) @{
    Fork b (1, 1);
    print ("b", b.process_id ());
    @{
      Fork c (b.is_parent (), 1);
      if (b.is_child ())
        print ("cchild", c.process_id ());
      else
        print ("cparent", c.process_id ());
      if (c.is_child ()) @{
        sleep (3000);
        return 0;
      @}
    @}
    if (b.is_child ()) @{
      sleep (120);
      return 0x8;
    @}
  @}

  return 0;
@}      

@end example

@node protocol Class
@chapter Class protocol
@cindex protocol class

@code{protocol} class is the base class for all the other application
protocol classes like @code{echo}, @code{smtp}, etc. @code{protocol}
is derived publicly from @code{iosockstream}. It uses @code{protocolbuf}
class, a nested class of @code{protocol},  as its stream buffer.

The @code{protocol} class is an abstract class and thus, you cannot
instantiate an object of @code{protocol}. 

@section Class protocol::protocolbuf
@cindex protocolbuf class

@code{protocol::protocolbuf} class is publicly derived from
@code{sockinetbuf} and thus, it inherits all the latter's public member
functions. In addition, the @code{protocolbuf} defines the following
member functions.

In what follows,
@itemize @minus
@item
@code{p} is an object of a non-abstract class derived from
@code{protocolbuf}.
@item
@code{pname} is the transport protocol name which is either
@code{protocol::tcp} or @code{protocol::udp}.
@item
@code{addr} is an unsigned long denoting the valid address of a machine in
host byte order.
@item
@code{host} is a char string denoting the name of a machine like
"kelvin.seas.virginia.edu".
@item
@code{portno} is an int and denotes the port number in host byte order.
@end itemize

@table @code

@item protocol::protocolbuf::protocolbuf (pname)
@findex protocolbuf::protocolbuf
constructs @code{protocolbuf} object with the transport protocol set to
@code{pname}.

@item p.protocol_name ()
@findex protcolbuf::protocol_name
returns the name of the transport protocol of @code{p} as a char string.

@item p.rfc_name ()
@findex protocolbuf::rfc_name
returns the name of the application protocol name of @code{p} as a char
string. @code{protocolbuf::rfc_name ()} is a pure virtual function;
thus, any class derived from @code{protocol::protocolbuf} should provide
a definition for @code{protocolbuf::rfc_name ()}.

@item p.rfc_doc ()
@findex protocolbuf::rfc_doc
returns the RFC document name of the application protocol of
@code{p} as a char string. @code{protocolbuf::rfc_doc ()} is a pure
virtual function; thus, any class derived from
@code{protocol::protocolbuf} should provide a definition for
@code{protocolbuf::rfc_doc ()}.

@item p.serve_clients (portno)
@findex protocolbuf::serve_clients
converts @code{p} into a server. Use the port specified in
@code{/etc/services} for the application if @code{portno} < 0. Use a
default port if @code{0 <= portno <= 1024}. Otherwise, use @code{portno}
as the port to accept clients requesting service.
@code{protocolbuf::serve_clients()} is pure virtual function; thus,
any class derived from @code{protocol::protocolbuf} should provide a
definition for @code{protocolbuf::serve_clients()}.

Please do not change the meaning of @code{portno} when you derive
your own class.

@item p.bind ()
@findex protocolbuf::bind
same as @code{p.serve_clients (-1)}.
It returns 0 on success and returns the errno on failure.

@item p.connect ()
@findex protocolbuf::connect
connects to the local host's server for the application. @code{p} acts as
the client. It returns 0 on success and returns the errno on failure.

@item p.connect (addr)
connects to the server running at the machine with address, @code{addr}.
@code{p} acts as the client.
It returns 0 on success and returns the errno on failure.

@item p.connect (host)
connects to the server running at the machine, @code{host}.
@code{p} acts as the client.
It returns 0 on success and returns the errno on failure.

@item p.connect (host, portno)
connects to the server servicing clients at @code{portno} at the machine,
@code{host}. Unlike this connect call, the other variants of connect
uses the port specified in the @code{/etc/services} file.
It returns 0 on success and returns the errno on failure.

@end table

@node echo Class
@chapter Echo Class
@cindex echo class

The @code{echo} class implements RFC 862. An @code{echo} object, as a
client, will get back what ever data it sends to an @code{echo} server.
Similarly, an @code{echo} object, as a server, will echo back the data
it receives from its client.

The @code{echo} class is derived from @code{protocol} class, and uses
@code{echo::echobuf} as its stream buffer. @code{echo::echobuf} is in
turn is derived from @code{protocol::protcolbuf}.

In what follows,
@itemize @minus
@item
@code{e} is a @code{echo} object.
@item
@code{pname} is a transport protocol name and must be either
@code{protocol::tcp} or @code{protocol::udp}.
@end itemize

@table @code

@item echo e (pname)
@findex echo::echo
constructs the @code{echo} object, @code{e} with @code{pname} as its
transport protocol name.

@item echo::operator -> ()
@findex echo::operator->
an @code{echo} object is a smart pointer for the underlying
@code{echobuf}.

@end table

@subsection tsecho.C
@example
// echo server. Serves clients at port 4000.
#include <echo.h>
#include <stdlib.h>

int main ()
@{
  echo server (protocol::tcp);
  server->serve_clients (4000);
  return 1;
@}
@end example

@subsection tcecho.C
@example
// echo client. Sends "mary had a litte lamb" to the server
#include <echo.h>
#include <stdlib.h>

int main ()
@{
  echo e(protocol::tcp);

  e->connect ("kelvin.seas.virginia.edu", 4000);

  cout << e->rfc_name () << ' ' << e->rfc_doc () << endl;

  e << "mary had a little lamb\r\n" << flush;

  char buf [256];
  e.getline (buf, 255);

  cout << "got back: " << buf << endl;
  return 0;
@}

@end example

@node smtp Class
@chapter SMTP Class
@cindex smtp class

The @code{smtp} class, which is derived from @code{protocol} class,
implements RFC 821. It can be used only as a client. Server function
is not yet implemented.

@code{smtp} uses @code{smtp::smtpbuf} as its underlying stream buffer.
Also, like the @code{protocol} class, @code{smtp} is a smart pointer
class for it is @code{smtp::smtpbuf}.

In what follows,
@itemize @minus
@item
@code{s} is an @code{smtp} object.
@item
@code{sb} is an @code{smtp::smtpbuf} object.
@item
@code{io} is a pointer to an @code{ostream}.
@item
@code{buf} is a char buffer of length @code{buflen}.
@item
@code{str, str0, str1, ...} are all char strings.
@end itemize

@table @code

@item smtp s (io)
@findex smtp::smtp
constructs an @code{smtp} client, @code{s}. Any response the client gets
from the server is sent to the ostream, @code{io}.

@item sb.get_response ()
@findex smtpbuf::get_response
gets the server response and sends it to @code{io} of the @code{smtpbuf}.

@item sb.send_cmd (str0, str1, str2)
@findex smtpbuf::send_cmd
concatenates strings @code{str0}, @code{str1}, and @code{str2} and sends the
concatenated string to the server before getting its response.

@item sb.send_buf (buf, buflen)
@findex smtpbuf::send_buf
sends the contents of the @code{buf} to the server.

@item sb.helo ()
@item sb.help (str)
@item sb.quit ()
@item sb.turn ()
@item sb.rset ()
@item sb.noop ()
@item sb.data ()
@item sb.vrfy (str)
@item sb.expn (str)
implements the respective @var{smtp} commands. See RFC 821 for the
meaning of each.

@item sb.mail (str)
sends the mail command to the server. @code{str} is the the reverse path
or the @var{FROM} address.

@item sb.rcpt (str)
sends the recipient command to the server. @code{str} is the forward path
or the @var{TO} address.

@item sb.data (buf, buflen)
sends the contents of the buffer, @code{buf} as the mail data to the recipient
previously established through @code{smtpbuf::rcpt()} calls.

@item sb.data (filename)
sends the contents of the file, @code{filename} as the mail data to the
recipient previously established through @code{smtpbuf::rcpt()} calls.

@end table

@subsection tcsmtp.C
@example
// smtp client.
// The president sends a message to gs4t@@virginia.edu.
#include <smtp.h>
#include <stdio.h>
#include <pwd.h>
#include <unistd.h>

int main ()
@{
  smtp client (&cout);

  // establish connection
  client->connect ("fulton.seas.virginia.edu");
  client->helo ();

  // get help
  client->help ();

  // setup the FROM address
  client->mail ("president@@whitehouse.gov");

  // setup the TO address
  client->rcpt ("gs4t@@virginia.edu");

  // send the message
  client->data ();
  client << "Hi Sekar, I appoint you as the director of NASA\r\n" << flush;
  client << "    -Bill, Hill, and Chel\r\n" << flush;
  cout << client; // get the server response.
  
  // finally quit
  client->quit ();

  return 0;
@}

@end example

@node Error Handling
@chapter Error Handling
@cindex error handling

Each class in the Socket++ library uses @code{error(const char*)} member
function to report any errors that may occur during a system call. It
first calls @code{perror()} to report the error message for the
@code{errno} set by the system call. It then calls
@code{sock_error (const char* nm, const char* errmsg)}
where @code{nm} is the name of the class.

The @code{sock_error()} function simply prints the @code{nm} and the
@code{errmsg} on the @var{stderr}.

@node Pitfalls
@chapter Pitfalls
@cindex pitfalls
@cindex common mistakes

Deadlocks in datagram sockets are the most common mistakes that novices
make. To alleviate the problem, @code{sockbuf} class provides timeout
facilities that can be used effectively to avoid deadlocks.

Consider the following simple tsmtp example which sends the HELP command to a
smtp server and gets back the help message. Suppose it does not know
the size of the help message nor the format of the message. In such
cases, the timeout facilities of @code{sockbuf} class provides the
required tools.

The example terminates the help message reception if the there is no
input activity from the smtp server for 10 seconds.

@subheading tsmtp.cc
@example
@cindex timeout example
#include <sockinet.h>

int main()
@{
        iosockinet   sio(sockbuf::sock_stream);

        sio->connect("kelvin.seas.virginia.edu", "smtp", "tcp");

        char buf[512];
        sio.getline(buf, 511); cout << buf << endl;
        sio << "HELO kelvin\n" << flush;
        sio.getline(buf, 511); cout << buf << endl;

        sio << "HELP\n" << flush;

        // set the receive timeout to 10 seconds
        int tmo = sio->recvtimeout(10);

        while ( sio.getline(buf, 511) ) cout << buf << endl;
                // if the above while loop terminated due to timeout
                // clear the state of sio.
        if ( !sio->is_eof() )
                sio.clear();  
        sio->recvtimeout(tmo); // reset the receive timeout time

        sio << "QUIT\n" << flush;
        sio.getline(buf, 511); cout << buf << endl;
        return 0;
@}
@end example

@node    Index
@unnumbered Index

@printindex cp
     
@contents
@bye

Revision:	1.2
Committed:	Wed Jun 13 19:37:29 2001 UTC (23 years, 3 months ago) by tdb
Content type:	application/x-texinfo
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+0 -0 lines
State:	*FILE REMOVED*
Error occurred while calculating annotation data.
Log Message:	Basically done a make distclean (or make real-clean in this case). No idea why we needed all this "generated" stuff lying about. Left libsocket++.a though, until the main Makefile will use it.