rpp(3)
NAME
rpp_open, rpp_bind, rpp_poll, rpp_io, rpp_read, rpp_write, rpp_close,
rpp_getaddr, rpp_flush, rpp_terminate, rpp_shutdown, rpp_rcommit,
rpp_wcommit, rpp_eom, rpp_getc, rpp_putc - reliable packet protocol
SYNOPSIS
#include <sys/types.h> #include <netinet/in.h> #include <rpp.h> int rpp_open(addr) struct sockadd_in *addr; int rpp_bind(port) int port; int rpp_poll() int rpp_io() int rpp_read(stream, buf, len) u_int stream; char *buf; int len; int rpp_write(stream, buf, len) u_int stream; char *buf; int len; int rpp_close(stream) u_int stream; struct sockadd_in *rpp_getaddr(stream) u_int stream; int rpp_flush(stream) u_int stream; int rpp_terminate() int rpp_shutdown() int rpp_rcommit(stream, flag) u_int stream; int flag; int rpp_wcommit(stream, flag) u_int stream; int flag; int rpp_eom(stream) u_int stream; int rpp_getc(stream) u_int stream; int rpp_putc(stream, c) u_int stream; int c;
DESCRIPTION
These functions provide reliable, flow-controlled, two-way transmission
of data. Each data path will be called a "stream" in this document.
The advantage of RPP over TCP is that many streams can be multiplexed
over one socket. This allows simultaneous connections over many
streams without regard to the system imposed file descriptor limit.
Data is sent and received in "messages". A message may be of any
length and is either received completely or not at all. Long messages
will cause the library to use large amounts of memory in the heap by
calling malloc(3V).
rpp_open() initializes a new stream connection to addr and returns the
stream identifier. This is an integer with a value greater than or
equal to zero. A negative number indicates an error. In this case,
errno will be set.
rpp_bind() is an initialization call which is used to bind the UDP
socket used by RPP to a particular port. The file descriptor of the
UDP socket used by the library is returned.
rpp_poll() returns the stream identifier of a stream with data to read.
If no stream is ready to read, a -2 is returned. A -1 is returned if
an error occurs.
rpp_io() processes any packets which are waiting to be sent or resceived over the UDP socket. This routine should be called if a section
of code could be executing for more than a few (~10) seconds without
calling any other rpp function. A -1 is returned if an error occurs, 0
otherwise.
rpp_read() transfers up to len characters of a message from stream into buf. If all of a message has been read, the return value will be less than len. The return value could be zero if all of a message had previously been read. A -1 is returned on error. A -2 is returned if the peer has closed its connection. If rpp_poll() is used to determine the stream is ready for reading, the call to rpp_read() will return immediately. Otherwise, the call will block waiting for a message to arrive.
rpp_write() adds information to the current message on a stream. The
data in buf numbering len characters is transfered to the stream. The
number of characters added to the stream are returned or a -1 on error.
In this case, errno will be set. A -2 is returned if the peer has
closed its connection.
rpp_close() disconnects the stream from its peer and frees all
resources associated with the stream. The return value is -1 on error
and 0 otherwise. rpp_getaddr() returns the address which a stream is
connected to. If the stream is not open, a NULL pointer is returned.
rpp_flush() marks the end of a message and commits all the data which
has been written to the specified stream. A zero is returned if the
message has been successfully committed. A -1 is returned on error.
rpp_terminate() is used to free all memory associated with all streams
and close the UDP socket. This is done without attempting to send any
final messages that may be waiting. If a process is using rpp and
calls fork() , the child must call rpp_terminate() so it will not cause
a conflict with the parent's communication.
rpp_shutdown() is used to free all memory associated with all streams
and close the UDP socket. An attepmt is made to send all outstanding
messages before returning.
rpp_rcommit() is used to "commit" or "de-commit" the information read
from a message. As calls are made to rpp_read(), the number of characters transfered out of the message are counted. If rpp_rcommit() is
called with flag being non-zero (TRUE), the current position in the
message is marked as the commit point. If rpp_rcommit() is called with
flag being zero (FALSE), a subsequent call to rpp_read() will return
characters from the message following the last commit point. If an
entire message has been read, rpp_read() will continue to return zero
as the number of bytes transfered until rpp_eom() is called to commit
the complete message.
rpp_wcommit() is used to "commit" or "de-commit" the information written to a stream. As calls are made to rpp_write(), the number of characters transfered into the message are counted. If rpp_wcommit() is called with flag being non-zero (TRUE), the current position in the message is marked as the commit point. If rpp_wcommit() is called with flag being zero (FALSE), a subsequent call to rpp_write() will transfer characters into the stream following the last commit point. A call to rpp_flush() does an automatic write commit to the current position.
rpp_eom() is called to terminate processing of the current message.