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.
10 ============================================================================================
11 Man Page: rmr_realloc_payload
12 ============================================================================================
15 ============================================================================================
19 --------------------------------------------------------------------------------------------
24 --------------------------------------------------------------------------------------------
30 extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
35 --------------------------------------------------------------------------------------------
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.
45 Cloning The Message Buffer
46 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
55 Message Buffer Metadata
56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
65 --------------------------------------------------------------------------------------------
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.
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.
84 --------------------------------------------------------------------------------------------
86 These value of *errno* will reflect the error condition if a
87 nil pointer is returned:
93 Memory allocation of the new payload failed.
98 The pointer passed in was nil, or refrenced an invalid
99 message, or the required length was not valid.
103 --------------------------------------------------------------------------------------------
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
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
116 fprintf( stderr, "[ERR] realloc returned a nil pointer: %s\\n", strerror( errno ) );
118 // populate and send ack message
125 --------------------------------------------------------------------------------------------
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)