docs/rmr_torcv_msg.3.rst

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