openpbs/doc/man3/rpp.3

.\" Copyright (C) 1994-2018 Altair Engineering, Inc.
.\" For more information, contact Altair at www.altair.com.
.\"
.\" This file is part of the PBS Professional ("PBS Pro") software.
.\"
.\" Open Source License Information:
.\"
.\" PBS Pro is free software. You can redistribute it and/or modify it under the
.\" terms of the GNU Affero General Public License as published by the Free
.\" Software Foundation, either version 3 of the License, or (at your option) any
.\" later version.
.\"
.\" PBS Pro is distributed in the hope that it will be useful, but WITHOUT ANY
.\" WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
.\" FOR A PARTICULAR PURPOSE.
.\" See the GNU Affero General Public License for more details.
.\"
.\" You should have received a copy of the GNU Affero General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.\"
.\" Commercial License Information:
.\"
.\" For a copy of the commercial license terms and conditions,
.\" go to: (http://www.pbspro.com/UserArea/agreement.html)
.\" or contact the Altair Legal Department.
.\"
.\" Altair’s dual-license business model allows companies, individuals, and
.\" organizations to create proprietary derivative works of PBS Pro and
.\" distribute them - whether embedded or bundled with other software -
.\" under a commercial license agreement.
.\"
.\" Use of Altair’s trademarks, including but not limited to "PBS™",
.\" "PBS Professional®", and "PBS Pro™" and Altair’s logos is subject to Altair's
.\" trademark licensing policies.
.\"
.TH RPP 3 "1 Oct 2009" Local "PBS Professional"
.SH 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
.SH SYNOPSIS

.B #include <sys/types.h>
.br
.B #include <netinet/in.h>
.br
.B #include <rpp.h>

.LP
.B
int rpp_open(addr)
.RS 6
struct sockadd_in \(**addr;
.RE
.LP
.B
int rpp_bind(port)
.RS 6
int port;
.RE
.LP
.B
int rpp_poll()
.LP
.B
int rpp_io()
.LP
.B
int rpp_read(stream, buf, len)
.RS 6
u_int stream;
.br
char \(**buf;
.br
int len;
.RE
.LP
.B
int rpp_write(stream, buf, len)
.RS 6
u_int stream;
.br
char \(**buf;
.br
int len;
.RE
.LP
.B
int rpp_close(stream)
.RS 6
u_int stream;
.RE
.LP
.B
struct sockadd_in \(**rpp_getaddr(stream)
.RS 6
u_int stream;
.RE
.LP
.B
int rpp_flush(stream)
.RS 6
u_int stream;
.RE
.LP
.B
int rpp_terminate()
.LP
.B
int rpp_shutdown()
.LP
.B
int rpp_rcommit(stream, flag)
.RS 6
u_int stream;
.br
int flag;
.RE
.LP
.B
int rpp_wcommit(stream, flag)
.RS 6
u_int stream;
.br
int flag;
.RE
.LP
.B
int rpp_eom(stream)
.RS 6
u_int stream;
.RE
.LP
.B
int rpp_getc(stream)
.RS 6
u_int stream;
.RE
.LP
.B
int rpp_putc(stream, c)
.RS 6
u_int stream;
.br
int c;
.RE
.SH DESCRIPTION
.LP
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.
.LP
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
.BR malloc (3V).
.LP

In order to use any of the above with Windows, initialize the network
library and link with 
.B winsock2.  
To do this, call 
.B winsock_init() 
before calling the function and link against the 
.B ws2_32.lib 
library.

.B rpp_open(\|)
initializes a new stream connection to
.IR 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.
.LP
.B rpp_bind(\|)
is an initialization call which is used to bind the UDP socket used
by RPP to a particular
.IR port .
The file descriptor of the UDP socket used by the library is returned.
.LP
.B 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.
.LP
.B rpp_io(\|)
processes any packets which are waiting to be sent or received 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.
.LP
.B rpp_read(\!)
transfers up to
.IR len
characters of a message from
.IR stream
into
.IR buf .
If all of a message has been read, the return value will be less than
.IR 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
.B rpp_poll(\!)
is used to determine the stream is ready for reading, the call to
.IR rpp_read(\!)
will return immediately.  Otherwise, the call will block waiting for
a message to arrive.
.LP
.B rpp_write(\|)
adds information to the current message on a
.IR stream .
The data in
.IR buf
numbering
.IR len
characters is transferred 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.
.LP
.B rpp_close(\!)
disconnects the
.IR stream
from its peer and frees all resources associated with the stream.
The return value is -1 on error and 0 otherwise.
.LP
.B rpp_getaddr(\!)
returns the address which a
.IR stream
is connected to.  If the stream is not open, a
.SM NULL
pointer is returned.
.LP
.B rpp_flush(\!)
marks the end of a message and commits all the data which has been
written to the specified
.IR stream .
A zero is returned if the message
has been successfully committed.
A -1 is returned on error.
.LP
.B 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
.B rpp
and calls
.B fork() ,
the child
.B must
call rpp_terminate() so it will not cause a conflict with the parent's
communication.
.LP
.B rpp_shutdown(\!)
is used to free all memory associated with all streams and close the
UDP socket.  An attempt is made to send all outstanding messages before
returning.
.LP
.B rpp_rcommit(\!)
is used to "commit" or "de-commit" the information read from a message.
As calls are made to
.IR rpp_read(\!) ,
the number of characters transferred out of the message are counted.  If
.IR rpp_rcommit(\!)
is called with
.IR flag
being non-zero (TRUE), the current position in the message is marked
as the commit point.  If
.IR rpp_rcommit(\!)
is called with
.IR flag
being zero (FALSE), a subsequent call to
.IR rpp_read(\!)
will return characters from the message following the last commit point.
If an entire message has been read,
.IR rpp_read(\!)
will continue to return zero as the number of bytes transferred until
.IR rpp_eom(\!)
is called to commit the complete message.
.LP
.B rpp_wcommit(\!)
is used to "commit" or "de-commit" the information written to a stream.
As calls are made to
.IR rpp_write(\!) ,
the number of characters transferred into the message are counted.  If
.IR rpp_wcommit(\!)
is called with
.IR flag
being non-zero (TRUE), the current position in the message is marked
as the commit point.  If
.IR rpp_wcommit(\!)
is called with
.IR flag
being zero (FALSE), a subsequent call to
.IR rpp_write(\!)
will transfer characters into the stream following the last commit point.
A call to
.IR rpp_flush(\!)
does an automatic write commit to the current position.
.LP
.B rpp_eom(\!)
is called to terminate processing of the current message.
.SH SEE ALSO
.BR tcp (4P),
.BR udp (4P)