doc/src/man/rmr_rcv_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_rcv_msg_man.xfm
  21         Abstract        The manual page for the rmr_rcv_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_rcv_msg
  34
  35 &h2(SYNOPSIS )
  36 &indent
  37 &ex_start
  38 #include <rmr/rmr.h>
  39
  40 rmr_mbuf_t* rmr_rcv_msg( void* vctx, rmr_mbuf_t* old_msg );
  41 &ex_end
  42 &uindent
  43
  44 &h2(DESCRIPTION)
  45 The &cw(rmr_rcv_msg) function blocks until a message is received, returning
  46 the message to the caller via a pointer to a &cw(rmr_mbuf_t) structure type.
  47 If messages were queued while waiting for the response to a previous invocation
  48 of &cw(rmr_call,)  the oldest message is removed from the queue and returned
  49 without delay.
  50
  51 &space
  52 The &ital(vctx) pointer is the pointer returned by the &cw(rmr_init) function.
  53 &ital(Old_msg) is a pointer to a previously used message buffer or NULL.
  54 The ability to reuse message buffers helps to avoid alloc/free cycles in the
  55 user application.
  56 When no buffer is available to supply, the receive function will allocate one.
  57
  58 &h2(RETURN VALUE)
  59 The function returns a pointer to the &cw(rmr_mbuf_t) structure which references
  60 the message information (state, length, payload), or a NULL pointer in the case
  61 of an extreme error.
  62
  63 &h2(ERRORS)
  64 The &ital(state) field in the message buffer will indicate either &cw(RMR_OK) or
  65 &cw(RMR_ERR_EMPTY) if an empty message was received.
  66 If a nil pointer is returned, or any other state value was set in the message
  67 buffer,  &cw(errno) will be set to one of the following:
  68 &space
  69
  70 &beg_dlist(.75i : ^&bold_font )
  71 &di(INVAL) Parameter(s) passed to the function were not valid.
  72
  73 &half_space
  74 &di(EBADF) The underlying message transport is unable to process the request.
  75
  76 &half_space
  77 &di(ENOTSUP) The underlying message transport is unable to process the request.
  78
  79 &half_space
  80 &di(EFSM) The underlying message transport is unable to process the request.
  81
  82 &half_space
  83 &di(EAGAIN) The underlying message transport is unable to process the request.
  84
  85 &half_space
  86 &di(EINTR) The underlying message transport is unable to process the request.
  87
  88 &half_space
  89 &di(ETIMEDOUT) The underlying message transport is unable to process the request.
  90
  91 &half_space
  92 &di(ETERM) The underlying message transport is unable to process the request.
  93 &end_dlist
  94
  95 &h2(EXAMPLE)
  96
  97 &h2(SEE ALSO )
  98 .ju off
  99 rmr_alloc_msg(3),
 100 rmr_call(3),
 101 rmr_free_msg(3),
 102 rmr_get_rcvfd(3),
 103 rmr_init(3),
 104 rmr_mk_ring(3),
 105 rmr_payload_size(3),
 106 rmr_send_msg(3),
 107 rmr_torcv_msg(3),
 108 rmr_rcv_specific(3),
 109 rmr_rts_msg(3),
 110 rmr_ready(3),
 111 rmr_ring_free(3),
 112 rmr_torcv_msg(3)
 113 .ju on
 114
 115
 116 .qu
 117