socket++.texi

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

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