PMEMOBJ_GET_USER_DATA(3)

✨ NAME ✨

pmemobj_open(), pmemobj_create(), pmemobj_close(), pmemobj_check(), pmemobj_set_user_data(), pmemobj_get_user_data() — bestie, these are the ones that create, open, close and validate your persistent memory transactional object store 💖

(they live in the PMDK Programmer's Manual, iykyk)

---

🌸 SYNOPSIS 🌸

#include <libpmemobj.h>

PMEMobjpool *pmemobj_open(const char *path, const char *layout);
PMEMobjpool *pmemobj_create(const char *path, const char *layout,
    size_t poolsize, mode_t mode);
void pmemobj_close(PMEMobjpool *pop);
int pmemobj_check(const char *path, const char *layout);

void pmemobj_set_user_data(PMEMobjpool *pop, void *data);
void *pmemobj_get_user_data(PMEMobjpool *pop);

---

🦋 DESCRIPTION 🦋

okay so. to even use the pmem-resident transactional object store that libpmemobj(7) gives you, you gotta make a memory pool first, and that's literally what pmemobj_create() does (more on her below). already got a pool? then you open it with pmemobj_open(). easy.

as of libpmemobj 1.11, these functions are thread-safe 💅 — but if you're out here on an earlier version of the library, be careful, bestie, fr fr.

once it's created, your memory pool is represented by an opaque handle of type PMEMobjpool*, and you pass that lil guy to basically every other libpmemobj(7) function. under the hood, libpmemobj(7) is gonna use either pmem_persist(3) or msync(2) when it needs to flush changes — depends on whether the memory pool looks like actual persistent memory or just a regular file (peep the pmem_is_pmem(3) function over in libpmem(7) if you want the tea ☕). and no, you do not need to flush changes yourself when you're using the object memory API from libpmemobj(7). she handles it. periodt.

💫 pmemobj_create()

pmemobj_create() creates a transactional object store with the given total poolsize.

• path — names the memory pool file that's getting created.
• layout — your application's layout type, as a string. and listen: libpmemobj(7) does not interpret this name at all, but it can be used as a check when pmemobj_open() gets called. the layout name, including the terminating null byte (\0), cannot be longer than PMEMOBJ_MAX_LAYOUT as defined in <libpmemobj.h>. a NULL layout is equivalent to using an empty string as the layout name. 🫶
• mode — the permissions to use when creating the file, as described by creat(2).

the memory pool file is fully allocated to the size poolsize using posix_fallocate(3). but hmm, you can choose to take responsibility for creating the memory pool file yourself — create it before calling pmemobj_create(), then specify poolsize as zero. in that case pmemobj_create() takes the pool size from the size of the existing file, and verifies the file looks empty by searching for any non-zero data in the pool header at the beginning of the file. the minimum net pool size the library allows for a local transactional object store is defined in <libpmemobj.h> as PMEMOBJ_MIN_POOL. ✨

🎀 pool sets, the multi-file era 🎀

depending on how the system is configured, your available non-volatile memory space might be split across multiple memory devices. in that case the max size of the pmemobj memory pool could be capped by the capacity of a single memory device. libpmemobj(7) lets you build a persistent memory resident object store spanning multiple memory devices by creating persistent memory pools made of multiple files, where each part of such a pool set may live on a different memory device or pmem-aware filesystem. iconic, honestly. 🌈

you can create all the parts of the pool set with pmemobj_create(); however, the recommended method for creating pool sets is with the pmempool(1) utility. (do it the recommended way, bestie, trust.)

when you're creating a pool set made of multiple files:

• the path argument passed to pmemobj_create() must point to the special set file that defines the pool layout and the location of all the parts of the pool set.
• the poolsize argument must be 0.
• the meaning of the layout and mode arguments does not change, except that the same mode is used for creation of all the parts of the pool set.

the set file is a plain text file, and its structure is described in poolset(5). 📝

💜 pmemobj_open()

pmemobj_open() opens an existing object store memory pool. just like pmemobj_create(), path must identify either an existing obj memory pool file, or the set file used to create a pool set. if layout is non-NULL, it gets compared to the layout name that was provided to pmemobj_create() when the pool was first created — this is how you verify the layout of the pool matches what you expected. also, your application must have permission to open the file and memory map it with read/write permissions. 🔐

⚠️ heads up bestie: if the pool contains bad blocks inside, opening can be aborted by the SIGBUS signal, because currently the pool is not checked against bad blocks during opening. you can turn that checking on by setting the CHECK_BAD_BLOCKS compat feature. for details see the description of this feature in pmempool-feature(1). 💀

🌸 pmemobj_close()

pmemobj_close() closes the memory pool indicated by pop and deletes the memory pool handle. the object store itself lives on in the file that contains it and may be re-opened later using pmemobj_open(), as described above. she's not gone, she's just resting 😌

🧚 pmemobj_check()

pmemobj_check() performs a consistency check of the file indicated by path. it opens the given path read-only, so it never makes any changes to the file. 🫶

🚫 this function is not supported on Device DAX.

⭐ pmemobj_set_user_data() / pmemobj_get_user_data()

pmemobj_set_user_data() associates custom volatile state — represented by the pointer data — with the given pool pop. that state can later be retrieved with the pmemobj_get_user_data() function.

💀 this state does not survive pool close. it's giving temporary.

if pmemobj_set_user_data() was never called for a given pool, pmemobj_get_user_data() will return NULL.

---

👑 RETURN VALUE 👑

• pmemobj_create() returns a memory pool handle, to be used with most of the functions in libpmemobj(7). on error it returns NULL and sets errno appropriately. 😭
• pmemobj_open() returns a memory pool handle, to be used with most of the functions in libpmemobj(7). if an error prevents the pool from being opened, or if the given layout does not match the pool's layout, pmemobj_open() returns NULL and sets errno appropriately.
• pmemobj_close() returns no value. nothing. nada. 💅
• pmemobj_check() returns 1 if the memory pool is found to be consistent. any inconsistencies found will cause pmemobj_check() to return 0, in which case the use of the file with libpmemobj(7) will result in undefined behavior 🚨. the debug version of libpmemobj(7) will provide additional details on inconsistencies when PMEMOBJ_LOG_LEVEL is at least 1, as described in the DEBUGGING AND ERROR HANDLING section in libpmemobj(7). pmemobj_check() returns -1 and sets errno if it cannot perform the consistency check due to other errors.

---

🍓 CAVEATS 🍓

not all file systems support posix_fallocate(3). pmemobj_create() will fail if the underlying file system does not support posix_fallocate(3). so like, check that first, bestie, or you're gonna have a bad time 😭

---

🌈 SEE ALSO 🌈

creat(2), msync(2), pmem_is_pmem(3), pmem_persist(3), posix_fallocate(3), libpmem(7), libpmemobj(7) and https://pmem.io

---

and that's the whole page, bestie 🫶 this one's from the <b>PMDK</b> set, dated 2025-07-24 — go forth and persist (responsibly) 💖✨