18.2.88. PMIx_Data_buffer_unload

PMIx_Data_buffer_unload — Extract the raw byte payload from a pmix_data_buffer_t.

18.2.88.1. SYNOPSIS

#include <pmix.h>

void PMIx_Data_buffer_unload(pmix_data_buffer_t *b,
                             char **bytes, size_t *sz);

18.2.88.2. INPUT PARAMETERS

b: Pointer to the source pmix_data_buffer_t whose payload is to be extracted.

18.2.88.3. OUTPUT PARAMETERS

bytes: Address of a char * in which the pointer to the extracted payload is returned.
sz: Address of a size_t in which the number of extracted bytes is returned.

18.2.88.4. DESCRIPTION

Remove the packed byte payload from b and hand it to the caller. The function extracts the buffer’s contents via PMIx_Data_unload(3); on success it stores the pointer to the payload in *bytes and its length in *sz.

The transfer is a move, not a copy: ownership of the underlying memory passes out of the buffer to the caller, and the buffer is left empty. No new allocation is made and no byte-copy is performed. Because the caller now owns the returned memory, it becomes responsible for eventually freeing *bytes. The emptied buffer may itself still be destructed or released as usual; doing so will not free the payload that has been handed off.

If the extraction fails, *bytes is set to NULL and *sz is set to zero.

The extracted payload is in packed (serialized) form. It may be transmitted, stored, and later reintroduced into a buffer with PMIx_Data_buffer_load(3) for subsequent unpacking.

18.2.88.5. RETURN VALUE

PMIx_Data_buffer_unload returns no value (void). Failure is signalled by *bytes being set to NULL and *sz to zero.

18.2.88.6. NOTES

PMIx_Data_buffer_unload is an OpenPMIx convenience routine. The Standard-defined interface for this operation is the PMIX_DATA_BUFFER_UNLOAD macro, which is implemented in terms of this function.