docs/rmr_realloc_payload.3.rst

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