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