--- /dev/null
+.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_torcv_msg_man.xfm
+ Abstract The manual page for the rmr_torcv_msg function.
+ Author E. Scott Daniels
+ Date 29 January 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_torcv_msg
+
+&h2(SYNOPSIS )
+&indent
+&ex_start
+#include <rmr/rmr.h>
+
+rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
+&ex_end
+&uindent
+
+&h2(DESCRIPTION)
+The &cw(rmr_torcv_msg) function will pause for &ital(ms_to) milliseconds waiting
+for a message to arrive.
+If a message arrives before the timeout expires the message buffer returned
+will have a status of RMR_OK and the payload will contain the data received.
+If the timeout expires before the message is received, the status will
+have the value RMR_ERR_TIMEOUT.
+When a received message is returned the message buffer will also contain the
+message type and length set by the sender.
+If messages were queued while waiting for the response to a previous invocation
+of &cw(rmr_call,) the oldest message is removed from the queue and returned
+without delay.
+
+&space
+The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
+&ital(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.
+
+&h2(RETURN VALUE)
+The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
+the message information (state, length, payload), or a NULL pointer in the case
+of an extreme error.
+
+&h2(ERRORS)
+The &ital(state) field in the message buffer will be one of the following:
+&space
+&beg_dlist(.75i : ^&bold_font )
+&di(RMR_OK) The message buffer (payload) references the received data.
+
+&space
+&di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
+ All other fields in the message buffer are not valid.
+
+&space
+&di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
+ fields in the message buffer are not valid.
+&end_dlist
+&space
+
+&beg_dlist(.75i : ^&bold_font )
+&di(INVAL) Parameter(s) passed to the function were not valid.
+
+&half_space
+&di(EBADF) The underlying message transport is unable to process the request.
+
+&half_space
+&di(ENOTSUP) The underlying message transport is unable to process the request.
+
+&half_space
+&di(EFSM) The underlying message transport is unable to process the request.
+
+&half_space
+&di(EAGAIN) The underlying message transport is unable to process the request.
+
+&half_space
+&di(EINTR) The underlying message transport is unable to process the request.
+
+&half_space
+&di(ETIMEDOUT) The underlying message transport is unable to process the request.
+
+&half_space
+&di(ETERM) The underlying message transport is unable to process the request.
+&end_dlist
+
+&h2(EXAMPLE)
+
+&h2(SEE ALSO )
+.ju off
+rmr_alloc_msg(3),
+rmr_call(3),
+rmr_free_msg(3),
+rmr_get_rcvfd(3),
+rmr_init(3),
+rmr_payload_size(3),
+rmr_rcv_msg(3),
+rmr_send_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)
+.ju on
+
+
+.qu
+
Code Review / ric-plt / lib / rmr.git / blobdiff