.. 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_torcv_msg 
============================================================================================ 
 
RMR Library Functions 
============================================================================================ 
 
 
NAME 
-------------------------------------------------------------------------------------------- 
 
rmr_torcv_msg 
 
SYNOPSIS 
-------------------------------------------------------------------------------------------- 
 
 
:: 
  
 #include <rmr/rmr.h>
 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
 
 
 
DESCRIPTION 
-------------------------------------------------------------------------------------------- 
 
The rmr_torcv_msg function will pause for *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 rmr_call, the oldest 
message is removed from the queue and returned without delay. 
 
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. 
 
RETURN VALUE 
-------------------------------------------------------------------------------------------- 
 
The function returns a pointer to the rmr_mbuf_t structure 
which references the message information (state, length, 
payload), or a nil pointer in the case of an extreme error. 
 
ERRORS 
-------------------------------------------------------------------------------------------- 
 
The *state* field in the message buffer will be one of the 
following: 
 
 
 
RMR_OK 
   
  The message buffer (payload) references the received data. 
   
 
RMR_ERR_INITFAILED 
   
  The first call to this function must initialise an 
  underlying system notification mechanism. On failure, this 
  error is returned and errno will have the system error 
  status set. If this function fails to intialise, the poll 
  mechansim, it is likely that message receives will never 
  be successful. 
   
 
RMR_ERR_TIMEOUT 
   
  The timeout expired before a complete message was 
  received. All other fields in the message buffer are not 
  valid. 
   
 
RMR_ERR_EMPTY 
   
  A message was received, but it had no payload. All other 
  fields in the message buffer are not valid. 
 
 
 
 
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 
-------------------------------------------------------------------------------------------- 
 
 
SEE ALSO 
-------------------------------------------------------------------------------------------- 
 
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)