sockbuf
class offers several ways to read and write and tailors
the behavior of several virtual functions of streambuf
for socket
communication.
In case of error, sockbuf::error(const char*)
is called.
In what follows,
s
is a sockbuf
object
buf
is buffer of type char*
bufsz
is an integer and is less than sizeof(buf)
msgf
is an integer and denotes the message flag
sa
is of type sockAddr
msgh
is a pointer to struct msghdr
wp
is an integer and denotes time in seconds
c
is a char
s.is_open()
s.is_eof()
s.write(buf, bufsz)
bufsz
if bufsz
chars in
the 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 Timeouts.
s.send(buf, bufsz, msgf)
sockbuf::write
described above but allows the user to
control the transmission of messages using the message flag msgf
.
If msgf
is sockbuf::msg_oob
and the socket type of
s
is sockbuf::sock_stream
, s
sends the message in
out-of-band mode. If msgf
is sockbuf::msg_dontroute
,
s
sends the outgoing packets without routing. If msgf
is
0, which is the default case, sockbuf::send
behaves exactly like
sockbuf::write
.
s.sendto(sa, buf, bufsz, msgf)
sockbuf::send
but works on unconnected sockets. sa
specifies the to address for the message.
s.sendmsg(msgh, msgf)
sockbuf::send
but sends a struct msghdr
object
instead.
s.sys_write(buf, bufsz)
sockbuf::write
and returns the result. Unlike
sockbuf::write
sockbuf::sys_write
is declared as a virtual
function.
s.read(buf, bufsz)
buf
. In
case of EOF, return EOF. Here, bufsz
indicates the size of the
buf
. In case of timeouts, return 0 Timeouts.
s.recv(buf, bufsz, msgf)
sockbuf::read
described above but allows the user to receive
out-of-band data if msgf
is sockbuf::msg_oob
or to
preview the data waiting to be read if msgf
is
sockbuf::msg_peek
. If msgf
is 0, which is the default
case, sockbuf::recv
behaves exactly like sockbuf::read
.
s.recvfrom(sa, buf, bufsz, msgf)
sockbuf::recv
but works on unconnected sockets. sa
specifies the from address for the message.
s.recvmsg(msgh, msgf)
sockbuf::recv
but reads a struct msghdr
object
instead.
s.sys_read(buf, bufsz)
sockbuf::read
and returns the result. Unlike
sockbuf::read
sockbuf::sys_read
is declared as a virtual
function.
s.is_readready(wp_sec, wp_usec)
s
has data waiting to be read from the
communication channel. If wp_sec >= 0
, it waits for
wp_sec 10^6 + wp_usec
microseconds before returning 0 in case
there are no data waiting to be read. If wp_sec < 0
, then it waits until
a datum arrives at the communication channel. wp_usec
defaults to 0.
Please Note: The data waiting in sockbuf
's own buffer is
different from the data waiting in the communication channel.
s.is_writeready(wp_sec, wp_usec)
s
. If wp_sec >= 0
, it waits for
wp_sec 10^6 + wp_usec
microseconds before returning 0 in case no
data can be written. If wp_sec < 0
, then it waits until
the communication channel is ready to accept data. wp_usec
defaults to 0.
Please Note: The buffer of the sockbuf
class is different
from the buffer of the communication channel buffer.
s.is_exceptionpending(wp_sec, wp_usec)
s
has any exception events pending.
If wp_sec >= 0
, it waits for wp_sec 10^6 + wp_usec
microseconds before returning 0 in case s
does
not have any exception events pending. If wp_sec < 0
,
then it waits until an expception event occurs. wp_usec
defaults
to 0.
Please Note: The exceptions that
sockbuf::is_exceptionpending
is looking for are different from
the C++ exceptions.
s.flush_output()
sockbuf::flush_output
is a
protected member function and it is not available for general public.
s.doallocate()
s
and returns
1 if allocation is done and returns 0 if there is no need.
sockbuf::doallocate
is a protected virtual member function and it
is not available for general public.
s.underflow()
s
cannot allocate space for the buffers,
cannot read or peer is closed. sockbuf::underflow
is a protected
virtual member function and it is not available for general public.
s.overflow(c)
c==EOF
, call and return the result of flush_output()
,
else if c=='\n'
and s
is linebuffered, call
flush_output()
and return c
unless flush_output()
returns EOF, in which case return EOF. In any other case, insert char
c
into the buffer and return c
as an unsigned char.
sockbuf::overflow
is a protected member virtual function and it is not
available for general public.
Node: linebuffered mode does not work with AT&T IOStream library.
Use explicit flushing to flush sockbuf
.
s.sync()
flush_output()
and returns the result. Useful if the user needs
to flush the output without writing newline char into the write buffer.
s.xsputn(buf, bufsz)
bufsz
chars into the buffer and returns the number of chars
successfully written. Output is flushed if any char in
buf[0..bufsz-1]
is '\n'
.
s.recvtimeout(wp)
wp
seconds. If wp
is -1, it is a
block and if wp
is 0, it is a poll.
It affects all read functions. If the socket is not read ready within
wp
seconds, the read call will return 0. It also affects
sockbuf::underflow
. sockbuf::underflow
will not set the
_S_EOF_SEEN
flag if it is returning EOF because of timeout.
sockbuf::recvtimeout
returns the old recv timeout value.
s.sendtimeout(wp)
wp
seconds. If wp
is -1, it is a
block and if wp
is 0, it is a poll.
It affects all write functions. If the socket is not write ready within
wp
seconds, the write call will return 0.
sockbuf::sendtimeout
returns the old send timeout value.