PMIX_VALUE_UNLOAD(3)

📦 version 6.1.1~rc2, in ubuntu stonking

💖 PMIX_VALUE_UNLOAD(3) 💖

okay bestie, welcome to the OpenPMIx manual, part 3 of the "how do I get my stuff back out of a struct" saga 🫶

🌸 NAME 🌸

PMIx_Value_unload — unload the contents of a pmix_value_t(5) ✨

🎀 SYNOPSIS 🎀

#include <pmix.h>

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

✨ Python Syntax ✨

No Python equivalent, bestie — and honestly? there's a reason. 💅 In Python the pmix_value_t equivalent is just a dictionary with a value field and a type field. So an "unload" function would be literally pointless. Not needed, not missed, we move on. 😌

🦋 INPUT PARAMETERS 🦋

  • val — pointer to a pmix_value_t(5) struct that's holding the value you wanna unload. that's the thing we're unpacking. 📦
  • data — pointer to the place where the data value is gonna get returned. yes, a pointer to a pointer. we love indirection here. 🙈
  • sz — pointer that'll get the size of the unloaded value. 📏

👑 DESCRIPTION 👑

So here's the tea ☕: PMIx_Value_unload follows the format of the data inside the pmix_value_t structure. And what it does depends entirely on what datatype that pmix_value_t(5) is holding:

  • if it's a standard datatype (like, say, a size_t) or a PMIx abstraction of a standard datatype (like a pmix_status_t(5)), then the function just copies the data across. simple. the caller needs to provide the storage for the data. 🫶
  • if it's a pointer (like the (void*)ptr field) or a PMIx defined structure (like the pmix_byte_object_t(5)), then the function malloc's the storage for the value, copies the fields into that new storage, and hands that storage back to you. and yes, the caller needs to provide storage for the pointer to the returned value. 🔥

so basically, in other words (and bestie you know I love an "in other words"), the caller has to provide storage — and a pointer to it — for wherever the final data should land. If it's a standard data field, the value gets placed in the storage you provided. If it's a PMIx-defined struct, then the function drops the pointer to that freshly malloc'd data into the storage you provided. either way you supplied the parking spot, it just decides what car goes in it. 🚗💨

ngl, this part is slay: the source pmix_value_t will not be altered in any way, and you can modify it or free it without affecting the unloaded data once the function has completed. it's giving "no strings attached". ✂️💖

⚠️ okay now listen up, because this has an unusual side effect and it trips people up. consider the case where the pmix_value_t contains a pmix_byte_object_t. in that case, the caller would need to pass the address of a pointer to a pmix_byte_object_t to the PMIx_Value_unload function — because the byte object itself (and not its internal data) is what's being unloaded. so the returned size is the size of a pmix_byte_object_t, not the number of bytes in the bytes field of the object. read that twice. i'm serious. 😭📢

🌈 RETURN VALUE 🌈

Returns PMIX_SUCCESS when everything went great. 🎉 On error, a negative value corresponding to a PMIx errno is returned. (negative = bad vibes, check your errno bestie 💀)

⭐ 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. and heads up — the function placed the location of the string into the provided str location because 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. clean. iconic. no cap. 🔢

💜 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. 🫧 but plot twist: the sz parameter will equal 16, as that is the size of the structure. 💀 yes, sixteen. structure size, not payload size. that's the whole unusual-side-effect thing from up above. told you it mattered. 😭

🔍 SEE ALSO 🔍

2014-2026, OpenPMIx Community

and that's the whole page bestie!! 💖 this edition of the PMIX_VALUE_UNLOAD(3) manual comes to you from the OpenPMIx crew, dated Aug 04, 2026 — go unload some values, free your pointers responsibly, and don't forget the byte object thing. mwah. 💅✨🦋

📦 where this page comes from