docs/rmr_torcv_msg.3.rst

   1
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 .. CAUTION: this document is generated from source in doc/src/rtd.
   6 .. To make changes edit the source and recompile the document.
   7 .. Do NOT make changes directly to .rst or .md files.
   8
   9
  10 ============================================================================================
  11 Man Page: rmr_torcv_msg
  12 ============================================================================================
  13
  14 RMR Library Functions
  15 ============================================================================================
  16
  17
  18 NAME
  19 --------------------------------------------------------------------------------------------
  20
  21 rmr_torcv_msg
  22
  23 SYNOPSIS
  24 --------------------------------------------------------------------------------------------
  25
  26
  27 ::
  28
  29  #include <rmr/rmr.h>
  30  rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
  31
  32
  33
  34 DESCRIPTION
  35 --------------------------------------------------------------------------------------------
  36
  37 The rmr_torcv_msg function will pause for *ms_to*
  38 milliseconds waiting for a message to arrive. If a message
  39 arrives before the timeout expires the message buffer
  40 returned will have a status of RMR_OK and the payload will
  41 contain the data received. If the timeout expires before the
  42 message is received, the status will have the value
  43 RMR_ERR_TIMEOUT. When a received message is returned the
  44 message buffer will also contain the message type and length
  45 set by the sender. If messages were queued while waiting for
  46 the response to a previous invocation of rmr_call, the oldest
  47 message is removed from the queue and returned without delay.
  48
  49 The *vctx* pointer is the pointer returned by the rmr_init
  50 function. *Old_msg* is a pointer to a previously used message
  51 buffer or NULL. The ability to reuse message buffers helps to
  52 avoid alloc/free cycles in the user application. When no
  53 buffer is available to supply, the receive function will
  54 allocate one.
  55
  56 RETURN VALUE
  57 --------------------------------------------------------------------------------------------
  58
  59 The function returns a pointer to the rmr_mbuf_t structure
  60 which references the message information (state, length,
  61 payload), or a nil pointer in the case of an extreme error.
  62
  63 ERRORS
  64 --------------------------------------------------------------------------------------------
  65
  66 The *state* field in the message buffer will be one of the
  67 following:
  68
  69
  70
  71 RMR_OK
  72
  73   The message buffer (payload) references the received data.
  74
  75
  76 RMR_ERR_INITFAILED
  77
  78   The first call to this function must initialise an
  79   underlying system notification mechanism. On failure, this
  80   error is returned and errno will have the system error
  81   status set. If this function fails to intialise, the poll
  82   mechansim, it is likely that message receives will never
  83   be successful.
  84
  85
  86 RMR_ERR_TIMEOUT
  87
  88   The timeout expired before a complete message was
  89   received. All other fields in the message buffer are not
  90   valid.
  91
  92
  93 RMR_ERR_EMPTY
  94
  95   A message was received, but it had no payload. All other
  96   fields in the message buffer are not valid.
  97
  98
  99
 100
 101 INVAL
 102
 103   Parameter(s) passed to the function were not valid.
 104
 105
 106 EBADF
 107
 108   The underlying message transport is unable to process the
 109   request.
 110
 111
 112 ENOTSUP
 113
 114   The underlying message transport is unable to process the
 115   request.
 116
 117
 118 EFSM
 119
 120   The underlying message transport is unable to process the
 121   request.
 122
 123
 124 EAGAIN
 125
 126   The underlying message transport is unable to process the
 127   request.
 128
 129
 130 EINTR
 131
 132   The underlying message transport is unable to process the
 133   request.
 134
 135
 136 ETIMEDOUT
 137
 138   The underlying message transport is unable to process the
 139   request.
 140
 141
 142 ETERM
 143
 144   The underlying message transport is unable to process the
 145   request.
 146
 147
 148 EXAMPLE
 149 --------------------------------------------------------------------------------------------
 150
 151
 152 SEE ALSO
 153 --------------------------------------------------------------------------------------------
 154
 155 rmr_alloc_msg(3), rmr_call(3), rmr_free_msg(3),
 156 rmr_get_rcvfd(3), rmr_init(3), rmr_payload_size(3),
 157 rmr_rcv_msg(3), rmr_send_msg(3), rmr_rcv_specific(3),
 158 rmr_rts_msg(3), rmr_ready(3), rmr_fib(3), rmr_has_str(3),
 159 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)