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