Add manual pages to RTD as individual files
This change introduces the code to generate man pages
as individual .rst files and the first set of those
into the scrapable docs directory.
Issue-ID: RIC-328
Signed-off-by: E. Scott Daniels <daniels@research.att.com>
Change-Id: I8d0b7b84b0b4fcadf9767d0ba69db64078a38d69
diff --git a/docs/rmr_mt_rcv.3.rst b/docs/rmr_mt_rcv.3.rst
new file mode 100644
index 0000000..c73a3c4
--- /dev/null
+++ b/docs/rmr_mt_rcv.3.rst
@@ -0,0 +1,213 @@
+
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. SPDX-License-Identifier: CC-BY-4.0
+.. CAUTION: this document is generated from source in doc/src/rtd.
+.. To make changes edit the source and recompile the document.
+.. Do NOT make changes directly to .rst or .md files.
+
+
+============================================================================================
+Man Page: rmr_mt_rcv
+============================================================================================
+
+RMR Library Functions
+============================================================================================
+
+
+NAME
+--------------------------------------------------------------------------------------------
+
+rmr_mt_rcv
+
+SYNOPSIS
+--------------------------------------------------------------------------------------------
+
+
+::
+
+ #include <rmr/rmr.h>
+ rmr_mbuf_t* rmr_mt_rcv( void* vctx, rmr_mbuf_t* old_msg, int timeout );
+
+
+
+DESCRIPTION
+--------------------------------------------------------------------------------------------
+
+The rmr_mt_rcv function blocks until a message is received,
+or the timeout period (milliseconds) has passed. The result
+is an RMr message buffer which references a received message.
+In the case of a timeout the state will be reflected in an
+"empty buffer" (if old_msg was not nil, or simply with the
+return of a nil pointer. If a timeout value of zero (0) is
+given, then the function will block until the next message
+received.
+
+The *vctx* pointer is the pointer returned by the rmr_init
+function. *Old_msg* is a pointer to a previously used message
+buffer or NULL. The ability to reuse message buffers helps to
+avoid alloc/free cycles in the user application. When no
+buffer is available to supply, the receive function will
+allocate one.
+
+The *old_msg* parameter allows the user to pass a previously
+generated RMR message back to RMR for reuse. Optionally, the
+user application may pass a nil pointer if no reusable
+message is available. When a timeout occurs, and old_msg was
+not nil, the state will be returned by returning a pointer to
+the old message with the state set.
+
+It is possible to use the *rmr_rcv_msg()* function instead of
+this function. Doing so might be advantageous if the user
+programme does not always start the multi-threaded mode and
+the use of *rmr_rcv_msg()* would make the flow of the code
+more simple. The advantages of using this function are the
+ability to set a timeout without using epoll, and a small
+performance gain (if multi-threaded mode is enabled, and the
+*rmr_rcv_msg()* function is used, it simply invokes this
+function without a timeout value, thus there is the small
+cost of a second call that results). Similarly, the
+*rmr_torcv_msg()* call can be used when in multi-threaded
+mode with the same "pass through" overhead to using this
+function directly.
+
+RETURN VALUE
+--------------------------------------------------------------------------------------------
+
+When a message is received before the timeout period expires,
+a pointer to the RMr message buffer which describes the
+message is returned. This will, with a high probability, be a
+different message buffer than *old_msg;* the user application
+should not continue to use *old_msg* after it is passed to
+this function.
+
+In the event of a timeout the return value will be the old
+msg with the state set, or a nil pointer if no old message
+was provided.
+
+ERRORS
+--------------------------------------------------------------------------------------------
+
+The *state* field in the message buffer will be set to one of
+the following values:
+
+
+
+RMR_OK
+
+ The message was received without error.
+
+
+RMR_ERR_BADARG
+
+ A parameter passed to the function was not valid (e.g. a
+ nil pointer). indicate either RMR_OK or RMR_ERR_EMPTY if
+ an empty message was received.
+
+
+RMR_ERR_EMPTY
+
+ The message received had no associated data. The length of
+ the message will be 0.
+
+
+RMR_ERR_NOTSUPP
+
+ The multi-threaded option was not enabled when RMr was
+ initialised. See the man page for *rmr_init()* for
+ details.
+
+
+RMR_ERR_RCVFAILED
+
+ A hard error occurred preventing the receive from
+ completing.
+
+When a nil pointer is returned, or any other state value was
+set in the message buffer, errno will be set to one of the
+following:
+
+
+
+INVAL
+
+ Parameter(s) passed to the function were not valid.
+
+
+EBADF
+
+ The underlying message transport is unable to process the
+ request.
+
+
+ENOTSUP
+
+ The underlying message transport is unable to process the
+ request.
+
+
+EFSM
+
+ The underlying message transport is unable to process the
+ request.
+
+
+EAGAIN
+
+ The underlying message transport is unable to process the
+ request.
+
+
+EINTR
+
+ The underlying message transport is unable to process the
+ request.
+
+
+ETIMEDOUT
+
+ The underlying message transport is unable to process the
+ request.
+
+
+ETERM
+
+ The underlying message transport is unable to process the
+ request.
+
+
+EXAMPLE
+--------------------------------------------------------------------------------------------
+
+
+
+::
+
+ rmr_mbuf_t* mbuf = NULL; // received msg
+ msg = rmr_mt_recv( mr, mbuf, 100 ); // wait up to 100ms
+ if( msg != NULL ) {
+ switch( msg->state ) {
+ case RMR_OK:
+ printf( "got a good message\\n" );
+ break;
+ case RMR_ERR_EMPTY:
+ printf( "received timed out\\n" );
+ break;
+ default:
+ printf( "receive error: %d\\n", mbuf->state );
+ break;
+ }
+ } else {
+ printf( "receive timeout (nil)\\n" );
+ }
+
+
+
+SEE ALSO
+--------------------------------------------------------------------------------------------
+
+rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
+rmr_get_rcvfd(3), rmr_init(3), rmr_mk_ring(3),
+rmr_mt_call(3), rmr_payload_size(3), rmr_send_msg(3),
+rmr_torcv_msg(3), rmr_rcv_specific(3), rmr_rts_msg(3),
+rmr_ready(3), rmr_ring_free(3), rmr_torcv_msg(3)