X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=blobdiff_plain;ds=sidebyside;f=doc%2Fsrc%2Fman%2Frmr_get_rcvfd.3.xfm;fp=doc%2Fsrc%2Fman%2Frmr_get_rcvfd.3.xfm;h=8300d4e76bf3a7560339140c883c909b0a44c99e;hb=fd9cc7a5b3355146388ebdf4d558cb284c66c5f1;hp=0000000000000000000000000000000000000000;hpb=008bc5b4414cebe48cecf63e8c817a02f7c3ce74;p=ric-plt%2Flib%2Frmr.git

diff --git a/doc/src/man/rmr_get_rcvfd.3.xfm b/doc/src/man/rmr_get_rcvfd.3.xfm
new file mode 100644
index 0000000..8300d4e
--- /dev/null
+++ b/doc/src/man/rmr_get_rcvfd.3.xfm
@@ -0,0 +1,150 @@
+.if false
+==================================================================================
+	Copyright (c) 2019 Nokia 
+	Copyright (c) 2018-2019 AT&T Intellectual Property.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+==================================================================================
+.fi
+
+.if false
+	Mnemonic	rmr_get_rcvfd.3.xfm
+	Abstract	The manual page for the rmr_get_rcvfd function.
+	Author		E. Scott Daniels
+	Date		11 February 2019
+.fi
+
+.** if formatting with tfm, the roff.im will cause roff output to be generated
+.** if formatting with pfm, then pretty postscript will be generated
+.gv e LIB lib
+.if pfm
+	.im &{lib}/generic_ps.im
+.ei
+	.gv e OUTPUT_RST use_rst
+	.if .ev &use_rst 1 = 
+		.im &{lib}/rst.im
+	.ei
+		.im &{lib}/roff.im
+	.fi
+.fi
+
+&line_len(6i)
+
+&h1(RMR Library Functions)
+&h2(NAME)
+	rmr_get_rcvfd
+
+&h2(SYNOPSIS)
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+void* rmr_get_rcvfd( void* ctx )
+&ex_end
+
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_get_rcvfd) function returns a file descriptor which may be given to epoll_wait()
+by an application that wishes to use event poll in a single thread rather than block
+on the arrival of a message via calls to rmr_rcv_msg().
+When epoll_wait() indicates that this file descriptor is ready, a call to rmr_rcv_msg()
+will not block as at least one message has been received. 
+
+&space
+The context (ctx) pointer passed in is the pointer returned by the call to rmr_init().
+
+&space
+&bold(NOTE^:) There is no support for epoll in Nanomsg, thus his function is only supported 
+when linking with the NNG version of RMr and the file descriptor returned when using the 
+Nanomsg verfsion will always return an error.
+
+
+&h2(RETURN VALUE)
+The &cw(rmr_get_rcvfd) function returns a file descriptor greater or equal to 0 on success
+and -1 on error.  
+If this function is called from a user application linked against the Nanomsg RMr library, 
+calls will always return -1 with errno set to EINVAL.
+
+&h2(ERRORS)
+The following error values are specifically set by this RMR function. In some cases the
+error message of a system call is propagated up, and thus this list might be incomplete.
+
+&beg_dlist(.75i : ^&bold_font )
+&di(EINVAL) The use of this function is invalid in this environment.
+&end_dlist
+
+&h2(EXAMPLE)
+The following short code bit illustrates the use of this function. Error checking has
+been omitted for clarity.
+&space
+
+&ex_start
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/epoll.h>
+#include <rmr/rmr.h>
+
+int main() {
+    int rcv_fd;     // pollable fd
+    void* mrc;      //msg router context
+    struct epoll_event events[10];          // support 10 events to poll
+    struct epoll_event epe;                 // event definition for event to listen to
+    int     ep_fd = -1;
+    rmr_mbuf_t* msg = NULL;
+    int nready;
+    int i;
+ 
+    mrc = rmr_init( "43086", RMR_MAX_RCV_BYTES, RMRFL_NONE );
+    rcv_fd = rmr_get_rcvfd( mrc );
+ 
+	ep_fd = epoll_create1( 0 );			// initialise epoll environment
+    epe.events = EPOLLIN;
+    epe.data.fd = rcv_fd;
+    epoll_ctl( ep_fd, EPOLL_CTL_ADD, rcv_fd, &epe );    // add our info to the mix
+ 
+    while( 1 ) {
+        nready = epoll_wait( ep_fd, events, 10, -1 );       // -1 == block forever (no timeout)
+        for( i = 0; i < nready && i < 10; i++ ) {           // loop through to find what is ready
+            if( events[i].data.fd == rcv_fd ) {             // RMr has something
+                msg = rmr_rcv_msg( mrc, msg );
+                if( msg ) {
+                    // do something with msg
+                }
+            }
+ 
+            // check for other ready fds....
+        }
+    }
+}
+&ex_end
+
+&h2(SEE ALSO )
+rmr_alloc_msg(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_payload_size(3),
+rmr_send_msg(3),
+rmr_rcv_msg(3),
+rmr_rcv_specific(3),
+rmr_rts_msg(3),
+rmr_ready(3),
+rmr_fib(3),
+rmr_has_str(3),
+rmr_tokenise(3),
+rmr_mk_ring(3),
+rmr_ring_free(3)
+
+
+.qu
+