PREV UP NEXT C++ socket classes for OS/2

3.3: Reading and Writing

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_open()
returns a non-zero number if the socket descriptor is open else return 0.
s.is_eof()
returns a non-zero number if the socket has seen EOF while reading else return 0.
s.write(buf, bufsz)
returns an int which must be equal to 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)
same as 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)
same as sockbuf::send but works on unconnected sockets. sa specifies the to address for the message.
s.sendmsg(msgh, msgf)
same as sockbuf::send but sends a struct msghdr object instead.
s.sys_write(buf, bufsz)
calls sockbuf::write and returns the result. Unlike sockbuf::write sockbuf::sys_write is declared as a virtual function.
s.read(buf, bufsz)
returns an int which is the number of chars read into the 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)
same as 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)
same as sockbuf::recv but works on unconnected sockets. sa specifies the from address for the message.
s.recvmsg(msgh, msgf)
same as sockbuf::recv but reads a struct msghdr object instead.
s.sys_read(buf, bufsz)
calls 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)
returns a non-zero int if 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)
returns a non-zero int if data can be written onto the communication channel of 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)
returns non-zero int if 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()
flushes the output buffer and returns the number of chars flushed. In case of error, return EOF. sockbuf::flush_output is a protected member function and it is not available for general public.
s.doallocate()
allocates free store for read and write buffers of 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()
returns the unread char in the buffer as an unsigned char if there is any. Else returns EOF if 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)
if 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()
calls 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)
write 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)
sets the recv timeout to 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)
sets the send timeout to 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.