Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RPP(3)			   Library Functions Manual			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 res-
       ceived 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 pre-
       viously 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 immedi-
       ately.  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 re-
       sources 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 charac-
       ters 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 en-
       tire  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 writ-
       ten to a	stream.	 As calls are made to rpp_write(), the number of char-
       acters  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
       tcp(4P),	udp(4P)

			       28 February 1996				RPP(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rpp&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help