18.2.75. PMIx_Data_copy

PMIx_Data_copy — Copy a data value from one location to another.

18.2.75.1. SYNOPSIS

#include <pmix.h>

pmix_status_t PMIx_Data_copy(void **dest, void *src,
                             pmix_data_type_t type);

18.2.75.2. INPUT PARAMETERS

src: A pointer to the memory location from which the data is to be copied.
type: The type of the data to be copied — must be one of the PMIx defined data types (see pmix_data_type_t).

18.2.75.3. OUTPUT PARAMETERS

dest: The address of a pointer into which the address of the resulting data is to be stored. The function allocates the storage for the copied value and returns a pointer to it in *dest. The caller is responsible for releasing that storage when it is no longer needed (e.g., with free for a simple type, or the appropriate PMIx release macro for a PMIx-defined structure).

18.2.75.4. DESCRIPTION

Copy a data value from one location to another. Since registered data types can be complex structures, the system needs some way to know how to copy the data from one location to another (e.g., for storage in the registry). This function, which can call other copy functions to build up complex data types, defines the method for making a copy of the specified data type.

If the specified type is composed of multiple PMIx data types, the function will ensure that each of these internal portions is also copied correctly as part of the operation, producing a fully independent (deep) copy. The source data referenced by src is not modified.

18.2.75.5. 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 provided src or dest is NULL.
PMIX_ERR_UNKNOWN_DATA_TYPE — the specified data type is not known to this implementation.
PMIX_ERR_OUT_OF_RESOURCE — not enough memory to support the operation.

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

18.2.75.6. NOTES

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