PMEM_CTL(5)

✨ NAME ✨

ctl — the interface for examination and modification of the library's internal state 💅 (yes this is PMEM_CTL(5), bestie, come get your lore)

---

🌸 DESCRIPTION 🌸

okay so picture this: the CTL namespace is organized as a tree structure. Starting from the root, every node is either an internal node (it's holding other elements) or a leaf. Internal nodes can only contain other nodes and cannot be entry points — they're the group-chat admins, not the people talking.

There are two types of those nodes:

• named nodes — they have string identifiers 🏷️
• indexed nodes — they represent an abstract array index and also have an associated string identifier. The index itself is provided by the user, so that's on you bestie.

A collection of indexes present on the path of an entry point gets handed to the handler functions as name and index pairs.

Entry points are the leaves of the CTL namespace structure 🌿. Each entry point can:

• read from the internal state
• write to the internal state
• exec a function
• or literally any combination of these three, it's giving multitasking

The entry points are listed in the following format:

name | r(ead)w(rite)x(ecute) | global/- | read argument type | write argument type | exec argument type | config argument type

A description of pmem_ctl functions can be found on the libpmemobj_ctl_get(3) manual page 📖

---

🎀 CTL EXTERNAL CONFIGURATION 🎀

Besides calling the function directly (main character move), each write entry point can also be set using two alternative methods. Two ways to do the same slay thing ✨

💖 Method one: the PMEMOBJ_CONF env var

The first method is to load a configuration directly from the PMEMOBJ_CONF environment variable. A properly formatted ctl config string is a single-line sequence of queries separated by ;:

query0;query1;...;queryN

A single query is constructed from the name of the ctl write entry point and the argument, separated by =:

entry_point=entry_point_argument

The entry point argument type is defined by the entry point itself, but there are three predefined primitives:

• integer: represented by a sequence of [0-9] characters that form a single number 🔢
• boolean: represented by a single character: y/n/Y/N/0/1, each corresponds to true or false. If the argument contains any trailing characters, they are ignored 🙈
• string: a simple sequence of characters

There are also complex argument types that are formed from the primitives separated by a ,:

first_arg,second_arg

In summary, a full configuration sequence looks like this:

(first_entry_point)=(arguments, ...);...;(last_entry_point)=(arguments, ...);

As an example, to set both prefault at_open and at_create variables:

PMEMOBJ_CONF="prefault.at_open=1;prefault.at_create=1"

🦋 Method two: the PMEMOBJ_CONF_FILE env var

The second method of loading an external configuration is to set the PMEMOBJ_CONF_FILE environment variable to point to a file that contains a sequence of ctl queries 📁. The parsing rules are all the same, but the file can also contain white-spaces and comments. Glow up for your config file, honestly.

To create a comment, simply use # anywhere in a line and everything afterwards, until a new line, will be ignored 💀 (gone, reduced to atoms).

An example configuration file:

#########################
# My pmemobj configuration
#########################
#
# Global settings:
prefault. # modify the behavior of pre-faulting
    at_open = 1; # prefault when the pool is opened

prefault.
    at_create = 0; # but don't prefault when it's created

# Per-pool settings:
# ...

fr fr bestie, the whitespace and the line breaks in there are totally fine — the parser eats them for breakfast 🍓

---

👑 SEE ALSO 👑

libpmemobj_ctl_get(3) and https://pmem.io

---

and that's the whole page, no cap 💜 this was the PMDK Programmer's Manual's pmem_ctl(5), brought to you from the PMDK era, dated 2025-07-24 — stay iconic, go read your manpages, mwah 🫶💖