doc/src/man/rmr_torcv_msg.3.xfm

   1 .if false
   2 ==================================================================================
   3         Copyright (c) 2019 Nokia
   4         Copyright (c) 2018-2019 AT&T Intellectual Property.
   5
   6    Licensed under the Apache License, Version 2.0 (the "License");
   7    you may not use this file except in compliance with the License.
   8    You may obtain a copy of the License at
   9
  10        http://www.apache.org/licenses/LICENSE-2.0
  11
  12    Unless required by applicable law or agreed to in writing, software
  13    distributed under the License is distributed on an "AS IS" BASIS,
  14    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15    See the License for the specific language governing permissions and
  16    limitations under the License.
  17 ==================================================================================
  18 .fi
  19 .if false
  20         Mnemonic        rmr_torcv_msg_man.xfm
  21         Abstract        The manual page for the rmr_torcv_msg function.
  22         Author          E. Scott Daniels
  23         Date            29 January 2019
  24 .fi
  25
  26 .gv e LIB lib
  27 .im &{lib}/man/setup.im
  28
  29 &line_len(6i)
  30
  31 &h1(RMR Library Functions)
  32 &h2(NAME)
  33         rmr_torcv_msg
  34
  35 &h2(SYNOPSIS )
  36 &indent
  37 &ex_start
  38 #include <rmr/rmr.h>
  39
  40 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
  41 &ex_end
  42 &uindent
  43
  44 &h2(DESCRIPTION)
  45 The &cw(rmr_torcv_msg) function will pause for &ital(ms_to) milliseconds waiting
  46 for a message to arrive.
  47 If a message arrives before the timeout expires the message buffer returned
  48 will have a status of RMR_OK and the payload will contain the data received.
  49 If the timeout expires before the message is received, the status will
  50 have the value RMR_ERR_TIMEOUT.
  51 When a received message is returned the message buffer will also contain the
  52 message type and length set by the sender.
  53 If messages were queued while waiting for the response to a previous invocation
  54 of &cw(rmr_call,)  the oldest message is removed from the queue and returned
  55 without delay.
  56
  57 &space
  58 The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
  59 &ital(Old_msg) is a pointer to a previously used message buffer or NULL.
  60 The ability to reuse message buffers helps to avoid alloc/free cycles in the
  61 user application.
  62 When no buffer is available to supply, the receive function will allocate one.
  63
  64 &h2(RETURN VALUE)
  65 The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
  66 the message information (state, length, payload), or a NULL pointer in the case
  67 of an extreme error.
  68
  69 &h2(ERRORS)
  70 The &ital(state) field in the message buffer will be one of the following:
  71 &space
  72 &beg_dlist(.75i : ^&bold_font )
  73 &di(RMR_OK) The message buffer (payload) references the received data.
  74
  75 &space
  76 &di(RMR_ERR_INITFAILED) The first call to this function must initialise an underlying
  77         system notification mechanism. On failure, this error is returned and errno
  78         will have the system error status set.  If this function fails to intialise,
  79         the poll mechansim, it is likely that message receives will never be successful.
  80
  81 &space
  82 &di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
  83         All other fields in the message buffer are not valid.
  84
  85 &space
  86 &di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
  87         fields in the message buffer are not valid.
  88 &end_dlist
  89 &space
  90
  91 &beg_dlist(.75i : ^&bold_font )
  92 &di(INVAL) Parameter(s) passed to the function were not valid.
  93
  94 &half_space
  95 &di(EBADF) The underlying message transport is unable to process the request.
  96
  97 &half_space
  98 &di(ENOTSUP) The underlying message transport is unable to process the request.
  99
 100 &half_space
 101 &di(EFSM) The underlying message transport is unable to process the request.
 102
 103 &half_space
 104 &di(EAGAIN) The underlying message transport is unable to process the request.
 105
 106 &half_space
 107 &di(EINTR) The underlying message transport is unable to process the request.
 108
 109 &half_space
 110 &di(ETIMEDOUT) The underlying message transport is unable to process the request.
 111
 112 &half_space
 113 &di(ETERM) The underlying message transport is unable to process the request.
 114 &end_dlist
 115
 116 &h2(EXAMPLE)
 117
 118 &h2(SEE ALSO )
 119 .ju off
 120 rmr_alloc_msg(3),
 121 rmr_call(3),
 122 rmr_free_msg(3),
 123 rmr_get_rcvfd(3),
 124 rmr_init(3),
 125 rmr_payload_size(3),
 126 rmr_rcv_msg(3),
 127 rmr_send_msg(3),
 128 rmr_rcv_specific(3),
 129 rmr_rts_msg(3),
 130 rmr_ready(3),
 131 rmr_fib(3),
 132 rmr_has_str(3),
 133 rmr_tokenise(3),
 134 rmr_mk_ring(3),
 135 rmr_ring_free(3)
 136 .ju on
 137
 138
 139 .qu
 140