pmem_ctl(5)

1PMEM_CTL(5)                PMDK Programmer's Manual                PMEM_CTL(5)
2
3
4

NAME

6       ctl  -  interface for examination and modification of the library’s in‐
7       ternal state.
8

DESCRIPTION

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

CTL EXTERNAL CONFIGURATION

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

NAME

DESCRIPTION

CTL EXTERNAL CONFIGURATION

SEE ALSO