1PMEM_CTL(5) PMDK Programmer's Manual PMEM_CTL(5)
2
3
4
6 ctl - interface for examination and modification of the library's in‐
7 ternal state.
8
10 The CTL namespace is organized in a tree structure. Starting from the
11 root, each node can be either internal, containing other elements, or a
12 leaf. Internal nodes themselves can only contain other nodes and can‐
13 not be entry points. There are two types of those nodes: named and in‐
14 dexed. Named nodes have string identifiers. Indexed nodes represent
15 an abstract array index and have an associated string identifier. The
16 index itself is provided by the user. A collection of indexes present
17 on the path of an entry point is provided to the handler functions as
18 name and index pairs.
19
20 Entry points are the leaves of the CTL namespace structure. Each entry
21 point can read from the internal state, write to the internal state,
22 exec a function or a combination of these operations.
23
24 The entry points are listed in the following format:
25
26 name | r(ead)w(rite)x(ecute) | global/- | read argument type | write
27 argument type | exec argument type | config argument type
28
29 A description of pmem_ctl functions can be found on the following manu‐
30 al pages: libpmemblk_ctl_get(3), libpmemlog_ctl_get(3), libpmemo‐
31 bj_ctl_get(3)
32
34 In addition to direct function call, each write entry point can also be
35 set using two alternative methods.
36
37 The first method is to load a configuration directly from the PMEM‐
38 BLK_CONF/ PMEMLOG_CONF/ PMEMOBJ_CONF environment variable. A properly
39 formatted ctl config string is a single-line sequence of queries sepa‐
40 rated by `;':
41
42 query0;query1;...;queryN
43
44 A single query is constructed from the name of the ctl write entry
45 point and the argument, separated by `=':
46
47 entry_point=entry_point_argument
48
49 The entry point argument type is defined by the entry point itself, but
50 there are three predefined primitives:
51
52 *) integer: represented by a sequence of [0-9] characters that form
53 a single number.
54 *) boolean: represented by a single character: y/n/Y/N/0/1, each
55 corresponds to true or false. If the argument contains any
56 trailing characters, they are ignored.
57 *) string: a simple sequence of characters.
58
59 There are also complex argument types that are formed from the primi‐
60 tives separated by a `,':
61
62 first_arg,second_arg
63
64 In summary, a full configuration sequence looks like this:
65
66 (first_entry_point)=(arguments, ...);...;(last_entry_point)=(arguments, ...);
67
68 As an example, to set both prefault at_open and at_create variables:
69
70 PMEMBLK_CONF="prefault.at_open=1;prefault.at_create=1"
71
72 The second method of loading an external configuration is to set the
73 PMEMBLK_CONF_FILE/ PMEMLOG_CONF_FILE/ PMEMOBJ_CONF_FILE environment
74 variable to point to a file that contains a sequence of ctl queries.
75 The parsing rules are all the same, but the file can also contain
76 white-spaces and comments.
77
78 To create a comment, simply use `#' anywhere in a line and everything
79 afterwards, until a new line, will be ignored.
80
81 An example configuration file:
82
83 #########################
84 # My pmemblk configuration
85 #########################
86 #
87 # Global settings:
88 prefault. # modify the behavior of pre-faulting
89 at_open = 1; # prefault when the pool is opened
90
91 prefault.
92 at_create = 0; # but don't prefault when it's created
93
94 # Per-pool settings:
95 # ...
96
98 libpmemblk_ctl_get(3), libpmemlog_ctl_get(3), libpmemobj_ctl_get(3) and
99 <https://pmem.io>
100
101
102
103PMDK - pmem_ctl API version 1.4 2022-05-24 PMEM_CTL(5)