-
-
.. This work is licensed under a Creative Commons Attribution 4.0 International License.
.. SPDX-License-Identifier: CC-BY-4.0
.. CAUTION: this document is generated from source in doc/src/rtd.
.. To make changes edit the source and recompile the document.
.. Do NOT make changes directly to .rst or .md files.
-
============================================================================================
Man Page: rmr_realloc_payload
============================================================================================
-RMR Library Functions
-============================================================================================
-
-
-NAME
---------------------------------------------------------------------------------------------
+
+
+RMR LIBRARY FUNCTIONS
+=====================
+
+
+
+NAME
+----
+
rmr_realloc_payload
-
-SYNOPSIS
---------------------------------------------------------------------------------------------
-
+
+
+SYNOPSIS
+--------
+
::
-
+
#include <rmr/rmr.h>
+
extern rmr_mbuf_t* rmr_realloc_payload( rmr_mbuf_t* msg, int new_len, int copy, int clone );
-
-
-DESCRIPTION
---------------------------------------------------------------------------------------------
-
-The rmr_realloc_payload function will return a pointer to an
-RMR message buffer struct (rmr_mbuf_t) which has a payload
+
+
+DESCRIPTION
+-----------
+
+The ``rmr_realloc_payload`` function will return a pointer to
+an RMR message buffer struct (rmr_mbuf_t) which has a payload
large enough to accomodate *new_len* bytes. If necessary, the
underlying payload is reallocated, and the bytes from the
original payload are copied if the *copy* parameter is true
(1). If the message passed in has a payload large enough,
there is no additional memory allocation and copying.
-
-Cloning The Message Buffer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Cloning The Message Buffer
+--------------------------
+
This function can also be used to generate a separate copy of
the original message, with the desired payload size, without
destroying the original message buffer or the original
payload. A standalone copy is made only when the *clone*
parameter is true (1). When cloning, the payload is copied to
the cloned message **only** if the *copy* parameter is true.
-
-Message Buffer Metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
+
+
+Message Buffer Metadata
+-----------------------
+
The metadata in the original message buffer (message type,
subscription ID, and payload length) will be preserved if the
*copy* parameter is true. When this parameter is not true
(0), then these values are set to the uninitialised value
(-1) for type and ID, and the length is set to 0.
-
-RETURN VALUE
---------------------------------------------------------------------------------------------
-
-The rmr_realloc_payload function returns a pointer to the
+
+
+RETURN VALUE
+------------
+
+The ``rmr_realloc_payload`` function returns a pointer to the
message buffer with the payload which is large enough to hold
*new_len* bytes. If the *clone* option is true, this will be
a pointer to the newly cloned message buffer; the original
just the payload buffer, was reallocated. In the event of an
error, a nil pointer will be returned and the value of
*errno* will be set to reflect the problem.
-
-ERRORS
---------------------------------------------------------------------------------------------
-
+
+
+ERRORS
+------
+
These value of *errno* will reflect the error condition if a
nil pointer is returned:
-
-ENOMEM
-
- Memory allocation of the new payload failed.
-
-
-EINVAL
-
- The pointer passed in was nil, or refrenced an invalid
- message, or the required length was not valid.
-
-
-EXAMPLE
---------------------------------------------------------------------------------------------
-
+ .. list-table::
+ :widths: auto
+ :header-rows: 0
+ :class: borderless
+
+ * - **ENOMEM**
+ -
+ Memory allocation of the new payload failed.
+
+ * - **EINVAL**
+ -
+ The pointer passed in was nil, or referenced an invalid
+ message, or the required length was not valid.
+
+
+
+
+EXAMPLE
+-------
+
The following code bit illustrates how this function can be
used to reallocate a buffer for a return to sender
acknowledgement message which is larger than the message
::
-
+
if( rmr_payload_size( msg ) < ack_sz ) { // received message too small for ack
msg = rmr_realloc_payload( msg, ack_sz, 0, 0 ); // reallocate the message with a payload big enough
if( msg == NULL ) {
// populate and send ack message
}
}
+
-
-
-SEE ALSO
---------------------------------------------------------------------------------------------
-
+
+
+SEE ALSO
+--------
+
rmr_alloc_msg(3), rmr_free_msg(3), rmr_init(3),
rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3),
rmr_rcv_specific(3), rmr_rts_msg(3), rmr_ready(3),