docs/rmr_realloc_payload.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_realloc_payload
   9 ============================================================================================
  10
  11
  12
  13
  14 RMR LIBRARY FUNCTIONS
  15 =====================
  16
  17
  18
  19 NAME
  20 ----
  21
  22 rmr_realloc_payload
  23
  24
  25 SYNOPSIS
  26 --------
  27
  28
  29 ::
  30
  31  #include <rmr/rmr.h>
  32
  33  extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
  34
  35
  36
  37 DESCRIPTION
  38 -----------
  39
  40 The ``rmr_realloc_payload`` function will return a pointer to
  41 an RMR message buffer struct (rmr_mbuf_t) which has a payload
  42 large enough to accomodate *new_len* bytes. If necessary, the
  43 underlying payload is reallocated, and the bytes from the
  44 original payload are copied if the *copy* parameter is true
  45 (1). If the message passed in has a payload large enough,
  46 there is no additional memory allocation and copying.
  47
  48
  49 Cloning The Message Buffer
  50 --------------------------
  51
  52 This function can also be used to generate a separate copy of
  53 the original message, with the desired payload size, without
  54 destroying the original message buffer or the original
  55 payload. A standalone copy is made only when the *clone*
  56 parameter is true (1). When cloning, the payload is copied to
  57 the cloned message **only** if the *copy* parameter is true.
  58
  59
  60 Message Buffer Metadata
  61 -----------------------
  62
  63 The metadata in the original message buffer (message type,
  64 subscription ID, and payload length) will be preserved if the
  65 *copy* parameter is true. When this parameter is not true
  66 (0), then these values are set to the uninitialised value
  67 (-1) for type and ID, and the length is set to 0.
  68
  69
  70 RETURN VALUE
  71 ------------
  72
  73 The ``rmr_realloc_payload`` function returns a pointer to the
  74 message buffer with the payload which is large enough to hold
  75 *new_len* bytes. If the *clone* option is true, this will be
  76 a pointer to the newly cloned message buffer; the original
  77 message buffer pointer may still be used to reference that
  78 message. It is the calling application's responsibility to
  79 free the memory associateed with both messages using the
  80 rmr_free_msg() function.
  81
  82 When the *clone* option is not used, it is still good
  83 practice by the calling application to capture and use this
  84 reference as it is possible that the message buffer, and not
  85 just the payload buffer, was reallocated. In the event of an
  86 error, a nil pointer will be returned and the value of
  87 *errno* will be set to reflect the problem.
  88
  89
  90 ERRORS
  91 ------
  92
  93 These value of *errno* will reflect the error condition if a
  94 nil pointer is returned:
  95
  96
  97    .. list-table::
  98      :widths: auto
  99      :header-rows: 0
 100      :class: borderless
 101
 102      * - **ENOMEM**
 103        -
 104          Memory allocation of the new payload failed.
 105
 106      * - **EINVAL**
 107        -
 108          The pointer passed in was nil, or referenced an invalid
 109          message, or the required length was not valid.
 110
 111
 112
 113
 114 EXAMPLE
 115 -------
 116
 117 The following code bit illustrates how this function can be
 118 used to reallocate a buffer for a return to sender
 119 acknowledgement message which is larger than the message
 120 received.
 121
 122
 123 ::
 124
 125    if( rmr_payload_size( msg ) < ack_sz ) {              // received message too small for ack
 126      msg = rmr_realloc_payload( msg, ack_sz, 0, 0 );     // reallocate the message with a payload big enough
 127      if( msg == NULL ) {
 128        fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
 129      } else {
 130        // populate and send ack message
 131      }
 132  }
 133
 134
 135
 136
 137 SEE ALSO
 138 --------
 139
 140 rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
 141 rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
 142 rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),
 143 rmr_fib(3), rmr_has_str(3), rmr_set_stimeout(3),
 144 rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3)