.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

.gv e LIB lib
.im &{lib}/man/setup.im 

&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