PMEMBLK_CTL_EXEC(3)

💖 PMEMBLK_CTL_EXEC(3) 💖

okay bestie, so this one lives in the PMDK Programmer's Manual (yes, that PMDK, the persistent memory one, we love her) and she's here to teach you how to peek at and poke around inside libpmemblk's internal settings. 🫶

⚠️ heads up: every single function on this page is DEPRECATED, and the whole thing is marked EXPERIMENTAL. Not me warning you first thing. 😭

---

✨ NAME ✨

pmemblk_ctl_get() (DEPRECATED), pmemblk_ctl_set() (DEPRECATED), pmemblk_ctl_exec() (DEPRECATED) — literally just "query and modify libpmemblk internal behavior" but make it a whole vibe (EXPERIMENTAL).

---

🌈 SYNOPSIS 🌈

#include <libpmemblk.h>

int pmemblk_ctl_get(PMEMblkpool *pbp, const char *name, void *arg); (EXPERIMENTAL)
int pmemblk_ctl_set(PMEMblkpool *pbp, const char *name, void *arg); (EXPERIMENTAL)
int pmemblk_ctl_exec(PMEMblkpool *pbp, const char *name, void *arg); (EXPERIMENTAL)

like. look at those signatures. gorgeous. no cap. 💅

---

🌸 DESCRIPTION 🌸

so pmemblk_ctl_get(), pmemblk_ctl_set() and pmemblk_ctl_exec() are the trio that gives you one uniform interface for querying and modifying the internal behavior of libpmemblk(7) through the control (CTL) namespace. iconic behavior honestly.

the name argument picks an entry point, exactly as defined in the CTL namespace specification. the entry point's own description tells you whether that extra arg is required or not. those two things together — name + arg — make up a CTL query. slay.

these functions and the entry points are thread-safe unless the description says otherwise down below. and if there are special conditions for calling an entry point? they're spelled out explicitly in its description, so read it, bestie, fr fr.

the functions propagate the return value of the entry point. and if either name or arg is invalid? boom, -1 is returned. 💀

if the CTL query you provided is valid, the CTL functions will always return 0 on success and -1 on failure — unless the entry point description says otherwise.

see more in the pmem_ctl(5) man page. yes, we're linking you to another page. it's giving "read the docs" energy. 🙈

---

👑 CTL NAMESPACE 👑

okay this is the main character section. every entry point, one by one, no skips:

• prefault.at_create | rw | global | int | int | - | boolean — if you set this, every page of the pool gets touched and written to when the pool is created, which triggers page allocation and minimizes the performance impact of pagefaults. affects only the pmemblk_create() function. always returns 0. ✨
• prefault.at_open | rw | global | int | int | - | boolean — if you set this, every page of the pool gets touched and written to when the pool is opened, to trigger page allocation and minimize the performance impact of pagefaults. affects only the pmemblk_open() function. always returns 0. ✨
• sds.at_create | rw | global | int | int | - | boolean — if you set this, it force-enables or force-disables the SDS feature during pool creation. affects only the pmemblk_create() function. want the tea on SDS (that's the SHUTDOWN_STATE feature)? check pmempool_feature_query(3). always returns 0. ✨
• copy_on_write.at_open | rw | global | int | int | - | boolean — if you set this, the pool gets mapped in such a way that modifications don't reach the underlying medium. from your perspective as the user, that means when the pool is closed, all changes are reverted. basically undo, but make it a mapping.

🚫 not supported for pools located on Device DAX. periodt.

always returns 0. ✨

---

🦋 CTL EXTERNAL CONFIGURATION 🦋

plot twist: you don't only get to set each write entry point by calling the function directly. there are two alternative methods, bestie:

1. load a configuration directly from the PMEMBLK_CONF environment variable. 🎀
2. set the PMEMBLK_CONF_FILE environment variable to point to a file that contains a sequence of ctl queries. 📄

see more in the pmem_ctl(5) man page. (yes, again. she's everywhere.)

---

⭐ SEE ALSO ⭐

libpmemblk(7), pmem_ctl(5) and <https://pmem.io> 🦋

---

okay that's the whole page, you ate that. mwah. 💖

this was the PMDK page, dated 2023-05-31 — so if you're reading this way later, no judgement, but also, it's giving vintage. 🎀 bye bestie, go read pmem_ctl(5) 💅