|
Packit |
95bb47 |
---
|
|
Packit |
95bb47 |
layout: manual
|
|
Packit |
95bb47 |
Content-Style: 'text/css'
|
|
Packit |
95bb47 |
title: _MP(PMEM_CTL, 5)
|
|
Packit |
95bb47 |
collection: pmem_ctl
|
|
Packit |
95bb47 |
header: PMDK
|
|
Packit |
95bb47 |
date: pmem_ctl API version 1.4
|
|
Packit |
95bb47 |
...
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
[comment]: <> (Copyright 2018, Intel Corporation)
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
[comment]: <> (Redistribution and use in source and binary forms, with or without)
|
|
Packit |
95bb47 |
[comment]: <> (modification, are permitted provided that the following conditions)
|
|
Packit |
95bb47 |
[comment]: <> (are met:)
|
|
Packit |
95bb47 |
[comment]: <> ( * Redistributions of source code must retain the above copyright)
|
|
Packit |
95bb47 |
[comment]: <> ( notice, this list of conditions and the following disclaimer.)
|
|
Packit |
95bb47 |
[comment]: <> ( * Redistributions in binary form must reproduce the above copyright)
|
|
Packit |
95bb47 |
[comment]: <> ( notice, this list of conditions and the following disclaimer in)
|
|
Packit |
95bb47 |
[comment]: <> ( the documentation and/or other materials provided with the)
|
|
Packit |
95bb47 |
[comment]: <> ( distribution.)
|
|
Packit |
95bb47 |
[comment]: <> ( * Neither the name of the copyright holder nor the names of its)
|
|
Packit |
95bb47 |
[comment]: <> ( contributors may be used to endorse or promote products derived)
|
|
Packit |
95bb47 |
[comment]: <> ( from this software without specific prior written permission.)
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
[comment]: <> (THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS)
|
|
Packit |
95bb47 |
[comment]: <> ("AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT)
|
|
Packit |
95bb47 |
[comment]: <> (LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR)
|
|
Packit |
95bb47 |
[comment]: <> (A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT)
|
|
Packit |
95bb47 |
[comment]: <> (OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,)
|
|
Packit |
95bb47 |
[comment]: <> (SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT)
|
|
Packit |
95bb47 |
[comment]: <> (LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,)
|
|
Packit |
95bb47 |
[comment]: <> (DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY)
|
|
Packit |
95bb47 |
[comment]: <> (THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT)
|
|
Packit |
95bb47 |
[comment]: <> ((INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE)
|
|
Packit |
95bb47 |
[comment]: <> (OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.)
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
[comment]: <> (pmem_ctl.5 -- man page for CTL)
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
[NAME](#name)
|
|
Packit |
95bb47 |
[DESCRIPTION](#description)
|
|
Packit |
95bb47 |
[CTL EXTERNAL CONFIGURATION](#ctl-external-configuration)
|
|
Packit |
95bb47 |
[SEE ALSO](#see-also)
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
# NAME #
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
ctl -- interface for examination and modification of the library's internal state.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
# DESCRIPTION #
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
The CTL namespace is organized in a tree structure. Starting from the root,
|
|
Packit |
95bb47 |
each node can be either internal, containing other elements, or a leaf.
|
|
Packit |
95bb47 |
Internal nodes themselves can only contain other nodes and cannot be entry
|
|
Packit |
95bb47 |
points. There are two types of those nodes: *named* and *indexed*. Named nodes
|
|
Packit |
95bb47 |
have string identifiers. Indexed nodes represent an abstract array index and
|
|
Packit |
95bb47 |
have an associated string identifier. The index itself is provided by the user.
|
|
Packit |
95bb47 |
A collection of indexes present on the path of an entry point is provided to
|
|
Packit |
95bb47 |
the handler functions as name and index pairs.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
The *name* argument specifies an entry point as defined in the CTL namespace
|
|
Packit |
95bb47 |
specification. The entry point description specifies whether the extra *arg* is
|
|
Packit |
95bb47 |
required. Those two parameters together create a CTL query. The functions and the entry points are thread-safe unless
|
|
Packit |
95bb47 |
indicated otherwise below. If there are special conditions for calling an entry
|
|
Packit |
95bb47 |
point, they are explicitly stated in its description. The functions propagate
|
|
Packit |
95bb47 |
the return value of the entry point. If either *name* or *arg* is invalid, -1
|
|
Packit |
95bb47 |
is returned.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
Entry points are the leaves of the CTL namespace structure. Each entry point
|
|
Packit |
95bb47 |
can read from the internal state, write to the internal state,
|
|
Packit |
95bb47 |
exec a function or a combination of these operations.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
The entry points are listed in the following format:
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
name | r(ead)w(rite)x(ecute) | global/- | read argument type | write argument type | exec argument type | config argument type
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
A description of **pmem_ctl** functions can be found on the following
|
|
Packit |
95bb47 |
manual pages:
|
|
Packit |
95bb47 |
**libpmemblk_ctl_get**(3), **libpmemlog_ctl_get**(3), **libpmemobj_ctl_get**(3)
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
# CTL EXTERNAL CONFIGURATION #
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
In addition to direct function call, each write entry point can also be set
|
|
Packit |
95bb47 |
using two alternative methods.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
The first method is to load a configuration directly from the
|
|
Packit |
95bb47 |
**PMEMBLK_CONF**/ **PMEMLOG_CONF**/ **PMEMOBJ_CONF** environment variable.
|
|
Packit |
95bb47 |
A properly formatted ctl config string is a single-line
|
|
Packit |
95bb47 |
sequence of queries separated by ';':
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
query0;query1;...;queryN
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
A single query is constructed from the name of the ctl write entry point and
|
|
Packit |
95bb47 |
the argument, separated by '=':
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
entry_point=entry_point_argument
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
The entry point argument type is defined by the entry point itself, but there
|
|
Packit |
95bb47 |
are three predefined primitives:
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
*) integer: represented by a sequence of [0-9] characters that form
|
|
Packit |
95bb47 |
a single number.
|
|
Packit |
95bb47 |
*) boolean: represented by a single character: y/n/Y/N/0/1, each
|
|
Packit |
95bb47 |
corresponds to true or false. If the argument contains any
|
|
Packit |
95bb47 |
trailing characters, they are ignored.
|
|
Packit |
95bb47 |
*) string: a simple sequence of characters.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
There are also complex argument types that are formed from the primitives
|
|
Packit |
95bb47 |
separated by a ',':
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
first_arg,second_arg
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
In summary, a full configuration sequence looks like this:
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
(first_entry_point)=(arguments, ...);...;(last_entry_point)=(arguments, ...);
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
As an example, to set both prefault at_open and at_create variables:
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
PMEMBLK_CONF="prefault.at_open=1;prefault.at_create=1"
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
The second method of loading an external configuration is to set the
|
|
Packit |
95bb47 |
**PMEMBLK_CONF_FILE**/ **PMEMLOG_CONF_FILE**/ **PMEMOBJ_CONF_FILE**
|
|
Packit |
95bb47 |
environment variable to point to a file that contains
|
|
Packit |
95bb47 |
a sequence of ctl queries. The parsing rules are all the same, but the file
|
|
Packit |
95bb47 |
can also contain white-spaces and comments.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
To create a comment, simply use '#' anywhere in a line and everything
|
|
Packit |
95bb47 |
afterwards, until a new line, will be ignored.
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
An example configuration file:
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
#########################
|
|
Packit |
95bb47 |
# My pmemblk configuration
|
|
Packit |
95bb47 |
#########################
|
|
Packit |
95bb47 |
#
|
|
Packit |
95bb47 |
# Global settings:
|
|
Packit |
95bb47 |
prefault. # modify the behavior of pre-faulting
|
|
Packit |
95bb47 |
at_open = 1; # prefault when the pool is opened
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
prefault.
|
|
Packit |
95bb47 |
at_create = 0; # but don't prefault when it's created
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
# Per-pool settings:
|
|
Packit |
95bb47 |
# ...
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
```
|
|
Packit |
95bb47 |
# SEE ALSO #
|
|
Packit |
95bb47 |
|
|
Packit |
95bb47 |
**libpmemblk_ctl_get**(3), **libpmemlog_ctl_get**(3), **libpmemobj_ctl_get**(3)
|
|
Packit |
95bb47 |
and **<http://pmem.io>**
|