18.2.77. PMIx_Data_copy_payload

PMIx_Data_copy_payload — Copy a payload from one buffer to another.

18.2.77.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Data_copy_payload(pmix_data_buffer_t *dest,
                                     pmix_data_buffer_t *src);

18.2.77.2. INPUT PARAMETERS

dest: Pointer to the destination pmix_data_buffer_t into which the payload is to be copied.
src: Pointer to the source pmix_data_buffer_t whose payload is to be copied. If src is NULL, the function returns PMIX_SUCCESS without modifying dest.

18.2.77.3. DESCRIPTION

This function appends a copy of the payload in the source buffer onto the destination buffer. Note that this is not a destructive procedure — the source buffer’s payload will remain intact, as will any pre-existing payload in the destination buffer. Only the unpacked (not yet consumed) portion of the source payload is copied.

Both buffers must use the same wire format for the copy to succeed; the operation fails if their types do not match.

18.2.77.4. RETURN VALUE

Returns PMIX_SUCCESS on success. On error, a negative value corresponding to a PMIx error constant is returned, including:

PMIX_ERR_INIT — the PMIx library has not been initialized.
PMIX_ERR_BAD_PARAM — the source and destination pmix_data_buffer_t types do not match.
PMIX_ERR_NOT_SUPPORTED — the PMIx implementation does not support this function.

Any other negative value indicates an appropriate error condition. PMIx error constants are defined in pmix_common.h.

18.2.77.5. NOTES

The library must be initialized (via PMIx_Init(3) or one of the other initialization entry points) before PMIx_Data_copy_payload can be used, as the copy operation is dispatched through the buffer-operations machinery selected at initialization.