NAME

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

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.

SEE ALSO