17.2.4. PMIx_Value_unload — OpenPMIx 6.1.1rc2 documentation

# 17.2.4. PMIx_Value_unload

PMIx_Value_unload — Unload the contents of a pmix_value_t(5)

## 17.2.4.1. SYNOPSIS

    #include <pmix.h>

    pmix_status_t PMIx_Value_unload(pmix_value_t *val,
                                    void **data,
                                    size_t *sz);

### 17.2.4.1.1. Python Syntax

No Python equivalent - the `pmix_value_t` equivalent in Python is a dictionary containing a `value` and `type` field. It is therefore unnecessary to provide an equivalent “unload” function.

## 17.2.4.2. INPUT PARAMETERS

- `val`: Pointer to a pmix_value_t(5) struct containing the value to be unloaded.

- `data`: Pointer to the location where the data value is to be returned

- `sz`: Pointer to return the size of the unloaded value

## 17.2.4.3. DESCRIPTION

The `PMIx_Value_unload` function follows the format of the data in the pmix_value_t structure. If the data type in the pmix_value_t(5) is:

> - a standard datatype (e.g., a size_t) or a PMIx abstraction of a standard datatype (e.g., a pmix_status_t(5), then the function just copies the data across. The caller needs to provide the storage for the data.

> - a pointer (e.g., the (void*)ptr field) or a PMIx defined structure (e.g., the pmix_byte_object_t(5)), then the function malloc’s the storage for the value, copies the fields into the new storage, and returns that storage to the caller. The caller needs to provide storage for the pointer to the returned value.

So in other words, the caller needs to provide storage (and a pointer to) the place where the final data is to be put. If it’s a statndard data field, the value will be placed in the provided storage. If it’s a PMIx-defined struct, then the function will place the pointer to that malloc’d data in the provided storage.

The source pmix_value_t will not be altered in any way, and it can be modified or free’d without affecting the unloaded data once the function has completed.

Note that this has an unusual side effect. For example, consider the case where the `pmix_value_t` contains a `pmix_byte_object_t`. In this case, the caller would need to pass the address of a pointer to a `pmix_byte_object_t` to the PMIx_Value_unload function since the byte object (and not its internal data) is what is being unloaded. The returned size, therefore, is the size of a `pmix_byte_object_t`, not the number of bytes in the `bytes` field of the object.

## 17.2.4.4. RETURN VALUE

Returns `PMIX_SUCCESS` on success. On error, a negative value corresponding to a PMIx `errno` is returned.

## 17.2.4.5. EXAMPLES

Unloading a string:

    pmix_value_t val;
    char *str;
    size_t sz;
    pmix_status_t rc;

    val.type = PMIX_STRING;
    val.data.string = "this is a string";

    rc = PMIx_Value_unload(&val, (void**)&str, &sz);

On return of `PMIX_SUCCESS`, the variable str will point to a new copy of the string “this is a string”, and sz will equal the length of that string. Note that the function placed the location of the string into the provided str location as the `char*` datatype is a standard one. Similarly:

    pmix_value_t val;
    uint32_t u32, *uptr;
    pmix_status_t rc;

    val.type = PMIX_UINT32;
    val.data.u32 = 1234;
    uptr = &u32;

    rc = PMIx_Value_unload(&val, (void**)&uptr, &sz);

On return of `PMIX_SUCCESS`, the variable u32 will contain a value of 1234 and sz will equal 4. However:

>     pmix_value_t val;
>     pmix_byte_object_t *bo;
>     pmix_status_t rc;

>     val.type = PMIX_BYTE_OBJECT;
>     val.data.bo.bytes = malloc(32);
>     val.data.bo.size = 32;

>     rc = PMIx_Value_unload(&val, (void**)&bo, &sz);

On return of `PMIX_SUCCESS`, the variable bo will point to a newly allocated pmix_byte_object_t(5) struct containing a bytes field of 32 bytes and a size of 32 because this is a PMIx-defined data structure. The sz parameter will equal 16 as that is the size of the structure.

See also

pmix_value_t(5)