1RPP(3) Library Functions Manual RPP(3)
2
6 rpp_open, rpp_bind, rpp_poll, rpp_io, rpp_read, rpp_write, rpp_close,
7 rpp_getaddr, rpp_flush, rpp_terminate, rpp_shutdown, rpp_rcommit,
8 rpp_wcommit, rpp_eom, rpp_getc, rpp_putc - reliable packet protocol
9
11 #include <sys/types.h>
12 #include <netinet/in.h>
13 #include <rpp.h>
14 int rpp_open(addr)
16 struct sockadd_in ∗addr;
17 int rpp_bind(port)
19 int port;
20 int rpp_poll()
22 int rpp_io()
24 int rpp_read(stream, buf, len)
26 u_int stream;
27 char ∗buf;
28 int len;
29 int rpp_write(stream, buf, len)
31 u_int stream;
32 char ∗buf;
33 int len;
34 int rpp_close(stream)
36 u_int stream;
37 struct sockadd_in ∗rpp_getaddr(stream)
39 u_int stream;
40 int rpp_flush(stream)
42 u_int stream;
43 int rpp_terminate()
45 int rpp_shutdown()
47 int rpp_rcommit(stream, flag)
49 u_int stream;
50 int flag;
51 int rpp_wcommit(stream, flag)
53 u_int stream;
54 int flag;
55 int rpp_eom(stream)
57 u_int stream;
58 int rpp_getc(stream)
60 u_int stream;
61 int rpp_putc(stream, c)
63 u_int stream;
64 int c;
65
67 These functions provide reliable, flow-controlled, two-way transmission
68 of data. Each data path will be called a "stream" in this document.
69 The advantage of RPP over TCP is that many streams can be multiplexed
70 over one socket. This allows simultaneous connections over many
71 streams without regard to the system imposed file descriptor limit.
72 Data is sent and received in "messages". A message may be of any
74 length and is either received completely or not at all. Long messages
75 will cause the library to use large amounts of memory in the heap by
76 calling malloc(3V).
77 rpp_open() initializes a new stream connection to addr and returns the
79 stream identifier. This is an integer with a value greater than or
80 equal to zero. A negative number indicates an error. In this case,
81 errno will be set.
82 rpp_bind() is an initialization call which is used to bind the UDP
84 socket used by RPP to a particular port. The file descriptor of the
85 UDP socket used by the library is returned.
86 rpp_poll() returns the stream identifier of a stream with data to read.
88 If no stream is ready to read, a -2 is returned. A -1 is returned if
89 an error occurs.
90 rpp_io() processes any packets which are waiting to be sent or res‐
92 ceived over the UDP socket. This routine should be called if a section
93 of code could be executing for more than a few (~10) seconds without
94 calling any other rpp function. A -1 is returned if an error occurs, 0
95 otherwise.
96 rpp_read() transfers up to len characters of a message from stream into
98 buf. If all of a message has been read, the return value will be less
99 than len. The return value could be zero if all of a message had pre‐
100 viously been read. A -1 is returned on error. A -2 is returned if the
101 peer has closed its connection. If rpp_poll() is used to determine the
102 stream is ready for reading, the call to rpp_read() will return immedi‐
103 ately. Otherwise, the call will block waiting for a message to arrive.
104 rpp_write() adds information to the current message on a stream. The
106 data in buf numbering len characters is transfered to the stream. The
107 number of characters added to the stream are returned or a -1 on error.
108 In this case, errno will be set. A -2 is returned if the peer has
109 closed its connection.
110 rpp_close() disconnects the stream from its peer and frees all
112 resources associated with the stream. The return value is -1 on error
113 and 0 otherwise. rpp_getaddr() returns the address which a stream is
114 connected to. If the stream is not open, a NULL pointer is returned.
115 rpp_flush() marks the end of a message and commits all the data which
117 has been written to the specified stream. A zero is returned if the
118 message has been successfully committed. A -1 is returned on error.
119 rpp_terminate() is used to free all memory associated with all streams
121 and close the UDP socket. This is done without attempting to send any
122 final messages that may be waiting. If a process is using rpp and
123 calls fork() , the child must call rpp_terminate() so it will not cause
124 a conflict with the parent's communication.
125 rpp_shutdown() is used to free all memory associated with all streams
127 and close the UDP socket. An attepmt is made to send all outstanding
128 messages before returning.
129 rpp_rcommit() is used to "commit" or "de-commit" the information read
131 from a message. As calls are made to rpp_read(), the number of charac‐
132 ters transfered out of the message are counted. If rpp_rcommit() is
133 called with flag being non-zero (TRUE), the current position in the
134 message is marked as the commit point. If rpp_rcommit() is called with
135 flag being zero (FALSE), a subsequent call to rpp_read() will return
136 characters from the message following the last commit point. If an
137 entire message has been read, rpp_read() will continue to return zero
138 as the number of bytes transfered until rpp_eom() is called to commit
139 the complete message.
140 rpp_wcommit() is used to "commit" or "de-commit" the information writ‐
142 ten to a stream. As calls are made to rpp_write(), the number of char‐
143 acters transfered into the message are counted. If rpp_wcommit() is
144 called with flag being non-zero (TRUE), the current position in the
145 message is marked as the commit point. If rpp_wcommit() is called with
146 flag being zero (FALSE), a subsequent call to rpp_write() will transfer
147 characters into the stream following the last commit point. A call to
148 rpp_flush() does an automatic write commit to the current position.
149 rpp_eom() is called to terminate processing of the current message.
151
153 tcp(4P), udp(4P)
154 28 February 1996 RPP(3)