.\" OpenPBS (Portable Batch System) v2.3 Software License .\" .\" Copyright (c) 1999-2000 Veridian Information Solutions, Inc. .\" All rights reserved. .\" .\" --------------------------------------------------------------------------- .\" For a license to use or redistribute the OpenPBS software under conditions .\" other than those described below, or to purchase support for this software, .\" please contact Veridian Systems, PBS Products Department ("Licensor") at: .\" .\" www.OpenPBS.org +1 650 967-4675 sales@OpenPBS.org .\" 877 902-4PBS (US toll-free) .\" --------------------------------------------------------------------------- .\" .\" This license covers use of the OpenPBS v2.3 software (the "Software") at .\" your site or location, and, for certain users, redistribution of the .\" Software to other sites and locations. Use and redistribution of .\" OpenPBS v2.3 in source and binary forms, with or without modification, .\" are permitted provided that all of the following conditions are met. .\" After December 31, 2001, only conditions 3-6 must be met: .\" .\" 1. Commercial and/or non-commercial use of the Software is permitted .\" provided a current software registration is on file at www.OpenPBS.org. .\" If use of this software contributes to a publication, product, or service .\" proper attribution must be given; see www.OpenPBS.org/credit.html .\" .\" 2. Redistribution in any form is only permitted for non-commercial, .\" non-profit purposes. There can be no charge for the Software or any .\" software incorporating the Software. Further, there can be no .\" expectation of revenue generated as a consequence of redistributing .\" the Software. .\" .\" 3. Any Redistribution of source code must retain the above copyright notice .\" and the acknowledgment contained in paragraph 6, this list of conditions .\" and the disclaimer contained in paragraph 7. .\" .\" 4. Any Redistribution in binary form must reproduce the above copyright .\" notice and the acknowledgment contained in paragraph 6, this list of .\" conditions and the disclaimer contained in paragraph 7 in the .\" documentation and/or other materials provided with the distribution. .\" .\" 5. Redistributions in any form must be accompanied by information on how to .\" obtain complete source code for the OpenPBS software and any .\" modifications and/or additions to the OpenPBS software. The source code .\" must either be included in the distribution or be available for no more .\" than the cost of distribution plus a nominal fee, and all modifications .\" and additions to the Software must be freely redistributable by any party .\" (including Licensor) without restriction. .\" .\" 6. All advertising materials mentioning features or use of the Software must .\" display the following acknowledgment: .\" .\" "This product includes software developed by NASA Ames Research Center, .\" Lawrence Livermore National Laboratory, and Veridian Information .\" Solutions, Inc. .\" Visit www.OpenPBS.org for OpenPBS software support, .\" products, and information." .\" .\" 7. DISCLAIMER OF WARRANTY .\" .\" THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. ANY EXPRESS .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT .\" ARE EXPRESSLY DISCLAIMED. .\" .\" IN NO EVENT SHALL VERIDIAN CORPORATION, ITS AFFILIATED COMPANIES, OR THE .\" U.S. GOVERNMENT OR ANY OF ITS AGENCIES BE LIABLE FOR ANY DIRECT OR INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, .\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" This license will be governed by the laws of the Commonwealth of Virginia, .\" without reference to its choice of law rules. .\" @(#)string.3 1.32 90/02/03 TMP; .TH RPP 3 "28 February 1996" .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 .nf .B #include #include #include .ft .fi .LP .nf .B int rpp_open(addr) struct sockadd_in \(**addr; .ft .fi .LP .nf .B int rpp_bind(port) int port; .ft .fi .LP .nf .B int rpp_poll() .ft .fi .LP .nf .B int rpp_io() .ft .fi .LP .nf .B int rpp_read(stream, buf, len) u_int stream; char \(**buf; int len; .ft .fi .LP .nf .B int rpp_write(stream, buf, len) u_int stream; char \(**buf; int len; .ft .fi .LP .nf .B int rpp_close(stream) u_int stream; .ft .fi .LP .nf .B struct sockadd_in \(**rpp_getaddr(stream) u_int stream; .ft .fi .LP .nf .B int rpp_flush(stream) u_int stream; .ft .fi .LP .nf .B int rpp_terminate() .ft .fi .LP .nf .B int rpp_shutdown() .ft .fi .LP .nf .B int rpp_rcommit(stream, flag) u_int stream; int flag; .ft .fi .LP .nf .B int rpp_wcommit(stream, flag) u_int stream; int flag; .ft .fi .LP .nf .B int rpp_eom(stream) u_int stream; .ft .fi .LP .nf .B int rpp_getc(stream) u_int stream; .ft .fi .LP .nf .B int rpp_putc(stream, c) u_int stream; int c; .ft .fi .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 .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 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. .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 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. .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. .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 attepmt 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 transfered 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 transfered 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 transfered 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)