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 .** if formatting with tfm, the roff.im will cause roff output to be generated
  27 .** if formatting with pfm, then pretty postscript will be generated
  28 .gv e LIB lib
  29 .if pfm
  30         .im &{lib}/generic_ps.im
  31 .ei
  32         .gv e OUTPUT_RST use_rst
  33         .if .ev &use_rst 1 =
  34                 .im &{lib}/rst.im
  35         .ei
  36                 .im &{lib}/roff.im
  37         .fi
  38 .fi
  39
  40 &line_len(6i)
  41
  42 &h1(RMR Library Functions)
  43 &h2(NAME)
  44         rmr_torcv_msg
  45
  46 &h2(SYNOPSIS )
  47 &indent
  48 &ex_start
  49 #include <rmr/rmr.h>
  50
  51 rmr_mbuf_t* rmr_torcv_msg( void* vctx, rmr_mbuf_t* old_msg, int ms_to );
  52 &ex_end
  53 &uindent
  54
  55 &h2(DESCRIPTION)
  56 The &cw(rmr_torcv_msg) function will pause for &ital(ms_to) milliseconds waiting
  57 for a message to arrive.
  58 If a message arrives before the timeout expires the message buffer returned
  59 will have a status of RMR_OK and the payload will contain the data received.
  60 If the timeout expires before the message is received, the status will
  61 have the value RMR_ERR_TIMEOUT.
  62 When a received message is returned the message buffer will also contain the
  63 message type and length set by the sender.
  64 If messages were queued while waiting for the response to a previous invocation
  65 of &cw(rmr_call,)  the oldest message is removed from the queue and returned
  66 without delay.
  67
  68 &space
  69 The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
  70 &ital(Old_msg) is a pointer to a previously used message buffer or NULL.
  71 The ability to reuse message buffers helps to avoid alloc/free cycles in the
  72 user application.
  73 When no buffer is available to supply, the receive function will allocate one.
  74
  75 &h2(RETURN VALUE)
  76 The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
  77 the message information (state, length, payload), or a NULL pointer in the case
  78 of an extreme error.
  79
  80 &h2(ERRORS)
  81 The &ital(state) field in the message buffer will be one of the following:
  82 &space
  83 &beg_dlist(.75i : ^&bold_font )
  84 &di(RMR_OK) The message buffer (payload) references the received data.
  85
  86 &space
  87 &di(RMR_ERR_TIMEOUT) The timeout expired before a complete message was received.
  88         All other fields in the message buffer are not valid.
  89
  90 &space
  91 &di(RMR_ERR_EMPTY) A message was received, but it had no payload. All other
  92         fields in the message buffer are not valid.
  93 &end_dlist
  94 &space
  95
  96 &beg_dlist(.75i : ^&bold_font )
  97 &di(INVAL) Parameter(s) passed to the function were not valid.
  98
  99 &half_space
 100 &di(EBADF) The underlying message transport is unable to process the request.
 101
 102 &half_space
 103 &di(ENOTSUP) The underlying message transport is unable to process the request.
 104
 105 &half_space
 106 &di(EFSM) The underlying message transport is unable to process the request.
 107
 108 &half_space
 109 &di(EAGAIN) The underlying message transport is unable to process the request.
 110
 111 &half_space
 112 &di(EINTR) The underlying message transport is unable to process the request.
 113
 114 &half_space
 115 &di(ETIMEDOUT) The underlying message transport is unable to process the request.
 116
 117 &half_space
 118 &di(ETERM) The underlying message transport is unable to process the request.
 119 &end_dlist
 120
 121 &h2(EXAMPLE)
 122
 123 &h2(SEE ALSO )
 124 .ju off
 125 rmr_alloc_msg(3),
 126 rmr_call(3),
 127 rmr_free_msg(3),
 128 rmr_get_rcvfd(3),
 129 rmr_init(3),
 130 rmr_payload_size(3),
 131 rmr_rcv_msg(3),
 132 rmr_send_msg(3),
 133 rmr_rcv_specific(3),
 134 rmr_rts_msg(3),
 135 rmr_ready(3),
 136 rmr_fib(3),
 137 rmr_has_str(3),
 138 rmr_tokenise(3),
 139 rmr_mk_ring(3),
 140 rmr_ring_free(3)
 141 .ju on
 142
 143
 144 .qu
 145