PMEMLOG_OPEN(3)

💖 PMEMLOG_CHECK(3) — the PMDK programmer's manual, but make it make sense 💖

okay bestie, sit down, grab a boba, because we're talking about the persistent memory resident log file girlies: pmemlog_create(), pmemlog_open(), pmemlog_close() and pmemlog_check(). they create, open, close and validate that whole situation. ✨

🚨 important vibe check first: all four of these functions are DEPRECATED. yes, literally all of them. the whole squad. just so you know going in. 💀

This page lives in the PMDK Programmer's Manual, in case you were wondering where we are. 🎀

---

🌸 NAME 🌸

pmemlog_create() (DEPRECATED), pmemlog_open() (DEPRECATED), pmemlog_close() (DEPRECATED), pmemlog_check() (DEPRECATED) — create, open, close and validate a persistent memory resident log file. that's the whole job description, no cap. 💅

---

✨ SYNOPSIS ✨

#include <libpmemlog.h>

PMEMlogpool *pmemlog_open(const char *path);
PMEMlogpool *pmemlog_create(const char *path, size_t poolsize, mode_t mode);
void pmemlog_close(PMEMlogpool *plp);
int pmemlog_check(const char *path);

four functions. four little icons. periodt. 👑

---

🦋 DESCRIPTION 🦋

pmemlog_create() — the builder 🏗️

so pmemlog_create() makes a log memory pool with the total poolsize you hand it. but here's the tea: because a log memory pool is transactional (main character energy requires overhead 😭), the actual usable log size ends up less than poolsize. you get the real number from pmemlog_nbyte(3). lowkey important.

• path — the name of the memory pool file you're creating. like, the file name. that's it.
• mode — the permissions to use when creating the file, exactly as described by creat(2).

the memory pool file gets fully allocated to size poolsize using posix_fallocate(3). no half-measures, she commits. 💅

but wait — you can also take matters into your own hands: create the memory pool file yourself before calling pmemlog_create(), then pass poolsize as zero. in that case:

• pmemlog_create() grabs the pool size from the size of the existing file, and
• it verifies the file appears to be empty by searching for any non-zero data in the pool header at the beginning of the file.

the net pool size of a pool file equals the file size. and the minimum net pool size the library allows for a log pool is defined in <libpmemlog.h> as PMEMLOG_MIN_POOL. ✨

multiple memory devices, because of course 💫

depending on how the system is configured, the available non-volatile memory space might be split across multiple memory devices. in that case the max size of the pmemlog memory pool could be capped by the capacity of a single memory device. rude, honestly.

but libpmemlog(7) lets you build persistent memory resident logs that span multiple memory devices by creating persistent memory pools made of multiple files, where each part of the pool set can live on a different memory device or pmem-aware filesystem. slay, we love flexibility. 🌈

you can create all the parts of the pool set with pmemlog_create()… however the recommended method for creating pool sets is with the pmempool(1) utility. trust the utility, bestie. 🫶

pool sets: the rules 📋

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

• the path argument you pass to pmemlog_create() must point to the special set file that defines the pool layout and where all the parts of the pool set live.
• the poolsize argument must be 0.
• the meaning of the mode argument doesn't change — except that the same mode is used for creating all the parts of the pool set.

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

pmemlog_open() — the opener 🚪

pmemlog_open() opens an existing log memory pool. same deal as pmemlog_create(): path must identify either an existing log memory pool file, or the set file used to create a pool set.

your application needs permission to open the file and memory map the file or pool set with read/write permissions. no permission, no entry. 🙈

⚠️ heads up, this part is scary: if the pool has bad blocks inside, opening can be aborted by the SIGBUS signal — because right now the pool is not checked against bad blocks during opening. you can turn that checking on by setting the CHECK_BAD_BLOCKS compat feature. details are in the description of this feature in pmempool-feature(1). 💀

pmemlog_close() — the closer 🎀

pmemlog_close() closes the memory pool indicated by plp and deletes the memory pool handle.

but the log memory pool itself lives on in the file that contains it, and can be re-opened later with pmemlog_open() like we talked about above. it's giving "we'll always have the file." 💜

pmemlog_check() — the validator ✅

pmemlog_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. respectful queen. 👑

🚫 this function is not supported on Device DAX. just so you know.

---

🔥 RETURN VALUE 🔥

• pmemlog_create() — on success, returns a PMEMlogpool* handle to the memory pool, which is what you use with most of the functions from libpmemlog(7). if an error stops any of the pool set files from being created, it returns NULL and sets errno appropriately.
• pmemlog_open() — on success, returns a PMEMlogpool* handle to the memory pool, used with most of the functions from libpmemlog(7). if an error prevents the pool from being opened, or a pool set is being opened and the actual size of any file doesn't match the corresponding part size defined in the set file, it returns NULL and sets errno appropriately.
• pmemlog_close() — returns no value. she gives nothing and that's fine. 💅
• pmemlog_check() — returns 1 if the persistent memory resident log file is found to be consistent.

and now the dramatic part: any inconsistencies will cause pmemlog_check() to return 0, and in that case using the file with libpmemlog will result in undefined behavior. 😭

the debug version of libpmemlog will give you extra details on inconsistencies when PMEMLOG_LOG_LEVEL is at least 1, as described in the DEBUGGING AND ERROR HANDLING section in libpmemlog(7).

pmemlog_check() will return -1 and set errno if it can't perform the consistency check due to other errors. rough. 🙈

---

💀 CAVEATS 💀

not all file systems support posix_fallocate(3). and if the underlying file system doesn't support posix_fallocate(3), then pmemlog_create() will fail. that's it, that's the caveat, no workarounds listed here bestie. 😭

---

👑 SEE ALSO 👑

pmempool(1), creat(2), posix_fallocate(3), pmemlog_nbyte(3), poolset(5), libpmemlog(7) and <https://pmem.io> 🌈

---

and that's the whole page, bestie!! 💖 this came out of the PMDK crew and it's dated 2023-05-31 — so like, keep that in mind when you're reading it, it's not exactly fresh off the press. 🎀 go forth, open your pools, check your consistency, and remember: bad blocks check is OFF by default and SIGBUS does not care about your feelings. byeee! 🦋✨