PMEMBLK_CREATE(3)

✨ NAME ✨

bestie. gather round. we're talking pmemblk_check(3) today — that's the star of the show, but she brought her whole friend group. this page is the one-stop for pmemblk_create() (DEPRECATED), pmemblk_open() (DEPRECATED), pmemblk_close() (DEPRECATED) and pmemblk_check() (DEPRECATED) — the four functions that create, open, close and validate a block pool. it's all from the PMDK Programmer's Manual, and yes, they're all deprecated, we'll talk about that energy. 💅

---

📖 SYNOPSIS 📖

#include <libpmemblk.h>

PMEMblkpool *pmemblk_create(const char *path, size_t bsize,
        size_t poolsize, mode_t mode);
PMEMblkpool *pmemblk_open(const char *path, size_t bsize);
void pmemblk_close(PMEMblkpool *pbp);
int pmemblk_check(const char *path, size_t bsize);

---

🦋 DESCRIPTION 🦋

okay so first up, the girl who does it all: pmemblk_create(). she makes a block memory pool, and it's got the given total poolsize, chopped up into as many elements of size bsize as will actually fit in there. and here's the tea — because a block memory pool is transactional, she needs a lil bit of space overhead, so the number of blocks you actually get is less than poolsize/bsize. that real number is handed to you via the pmemblk_nblock(3) function. and because of how this whole thing is implemented, the number of available blocks for the user cannot be less than 256. that translates to at least 512 internal blocks. no cap. 🌸

path is the name of the memory pool file she's creating. mode is 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). 💖

now, you can take matters into your own hands — the caller may choose to take responsibility for creating the memory pool file by creating it before calling pmemblk_create(), and then specifying poolsize as zero. in that case pmemblk_create() will take the pool size from the size of the existing file, and will verify that 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 is equal to the file size. the minimum net pool size allowed by the library for a block pool is defined in <libpmemblk.h> as PMEMBLK_MIN_POOL. and bsize? she can be any non-zero value. however — and this is important — libpmemblk will silently round up the given size to PMEMBLK_MIN_BLK, as defined in <libpmemblk.h>. silently. like she's not gonna tell you. 🙈

depending on the configuration of the system, the available non-volatile memory space may be divided into multiple memory devices. in that case, the maximum size of the pmemblk memory pool could be limited by the capacity of a single memory device. libpmemblk(7) allows building a persistent memory resident array spanning multiple memory devices by creation of persistent memory pools consisting of multiple files, where each part of such a pool set may be stored on a different memory device or pmem-aware filesystem. multi-device slay. ✨

creation of all the parts of the pool set can be done with pmemblk_create() — however, the recommended method for creating pool sets is by using the pmempool(1) utility. (recommended, bestie. take the hint.)

when creating a pool set consisting of multiple files, the path argument passed to pmemblk_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 mode argument does not change, except that the same mode is used for creation of all the parts of the pool set. for more information on pool set format, see poolset(5). 🎀

---

next up: pmemblk_open(). she opens an existing block memory pool. as with pmemblk_create(), path must identify either an existing block memory pool file, or the set file used to create a pool set. the application must have permission to open the file and memory map the file or pool set with read/write permissions. if bsize is non-zero, pmemblk_open() will verify that the given block size matches the block size used when the pool was created. otherwise, pmemblk_open() will open the pool without verifying the block size. you can figure out the bsize using the pmemblk_bsize(3) function. 🫶

💀 be aware that 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. it can be turned on by setting the CHECK_BAD_BLOCKS compat feature. for details see description of this feature in pmempool-feature(1). yes really. that's the vibe.

pmemblk_close() closes the memory pool indicated by pbp and deletes the memory pool handle. but the block memory pool itself lives on in the file that contains it — she's fine, she's thriving — and may be re-opened at a later time using pmemblk_open() as described above. 💜

and finally, the main character herself: pmemblk_check(). she performs a consistency check of the file indicated by path, and returns 1 if the memory pool is found to be consistent. if the pool is found not to be consistent, further use of the file with libpmemblk will result in undefined behavior. (undefined behavior!! the scariest two words in the game, fr fr. 😭)

the debug version of libpmemblk will provide additional details on inconsistencies when PMEMBLK_LOG_LEVEL is at least 1, as described in the DEBUGGING AND ERROR HANDLING section in libpmemblk(7). pmemblk_check() opens the given path read-only so it never makes any changes to the file. she's a look-don't-touch queen. 👑

⚠️ this function is not supported on Device DAX.

---

🌈 RETURN VALUE 🌈

on success, pmemblk_create() returns a PMEMblkpool* handle to the block memory pool. on error, it returns NULL and sets errno appropriately.

on success, pmemblk_open() returns a PMEMblkpool* handle that can be used with most of the functions in libpmemblk(7). on error, it returns NULL and sets errno appropriately. possible errors include:

• failure to open path
• path specifies a set file and any of the pool set files cannot be opened
• path specifies a set file and the actual size of any file does not match the corresponding part size defined in the set file
• bsize is non-zero and does not match the block size given when the pool was created. errno is set to EINVAL in this case.

pmemblk_close() returns no value. that's it. nothing. she gives you nothing back and that's valid. 💅

pmemblk_check() returns 1 if the memory pool is found to be consistent. if the check is successfully performed but the pool is found to be inconsistent, pmemblk_check() returns 0. this includes the case where bsize is non-zero and does not match the block size given when the pool was created. if the consistency check cannot be performed, pmemblk_check() returns -1 and sets errno appropriately. three possible outcomes, three possible moods. ⭐

---

🍓 CAVEATS 🍓

not all file systems support posix_fallocate(3). pmemblk_create() will fail if the underlying file system does not support posix_fallocate(3). so like, check your filesystem first, bestie. don't be out here surprised. 🙈

---

👀 SEE ALSO 👀

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

---

okay that's the whole page, you ate that. this was the PMDK Programmer's Manual, dated 2023-05-31, from the PMDK crew — and every single one of those functions up top is DEPRECATED, so like, noted, but now you know them anyway. mwah. 🫶✨💖