pmempool API version 1.3

The PMDK repository on GitHub is the ultimate source of information on PMDK from release 2.0! For all questions and to submit eventual issues please follow to that repository. The PMDK documentation collected here should be valid up to the 1.13.1 release but is maintained only on a best-effort basis and may not reflect the latest state of the art.

comment: <> (SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT) comment: <> (LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,) comment: <> (DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY) comment: <> (THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT) comment: <> ((INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE) comment: <> (OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.)

NAME
SYNOPSIS
DESCRIPTION
COMPATIBILITY
DISCLAIMER
RETURN VALUE
SEE ALSO

NAME

pmempool_feature_queryU()/pmempool_feature_queryW(), pmempool_feature_enableU()/pmempool_feature_enableW(), pmempool_feature_disableU()/pmempool_feature_disableW() - toggle or query pool set features

SYNOPSIS

#include <libpmempool.h>

int pmempool_feature_queryU(const char *path, enum pmempool_feature feature, unsigned flags);
int pmempool_feature_queryW(const wchar_t *path, enum pmempool_feature feature, unsigned flags);

int pmempool_feature_enableU(const char *path, enum pmempool_feature feature, unsigned flags);
int pmempool_feature_enableW(const wchar_t *path, enum pmempool_feature feature, unsigned flags);

int pmempool_feature_disableU(const char *path, enum pmempool_feature feature, unsigned flags);
int pmempool_feature_disableW(const wchar_t *path, enum pmempool_feature feature, unsigned flags);

NOTE: The PMDK API supports UNICODE. If the PMDK_UTF8_API macro is defined, basic API functions are expanded to the UTF-8 API with postfix U. Otherwise they are expanded to the UNICODE API with postfix W.

DESCRIPTION

The feature argument accepts following values:

  • PMEMPOOL_FEAT_SINGLEHDR - only the first part in each replica contains the pool part internal metadata. This value can be used only with pmempool_feature_query(). It can not be enabled or disabled. For details see poolset(5).

  • PMEMPOOL_FEAT_CKSUM_2K - only the first 2KiB of pool part internal metadata is checksummed. Other features may depend on this one to store additional metadata in otherwise unused second 2KiB part of a header. When PMEMPOOL_FEAT_CKSUM_2K is disabled whole 4KiB is checksummed.

  • PMEMPOOL_FEAT_SHUTDOWN_STATE - enables additional check performed during pool open which verifies pool consistency in the presence of dirty shutdown. PMEMPOOL_FEAT_CKSUM_2K has to be enabled prior to PMEMPOOL_FEAT_SHUTDOWN_STATE otherwise enabling PMEMPOOL_FEAT_SHUTDOWN_STATE will fail.

  • PMEMPOOL_FEAT_CHECK_BAD_BLOCKS - enables checking bad blocks performed during opening a pool and fixing bad blocks performed by pmempool-sync during syncing a pool. For details see pmempool-feature(1).

The pmempool_feature_queryU()/pmempool_feature_queryW() function checks state of feature in the pool set pointed by path.

The pmempool_feature_enableU()/pmempool_feature_enableW() function enables feature in the pool set pointed by path.

The pmempool_feature_disableU()/pmempool_feature_disableW() function disables feature in the pool set pointed by path.

COMPATIBILITY

Poolsets with features not defined in this document (e.g. enabled by the newer software version) are not supported.

DISCLAIMER

pmempool_feature_queryU()/pmempool_feature_queryW(), pmempool_feature_enableU()/pmempool_feature_enableW() and pmempool_feature_disableU()/pmempool_feature_disableW() are not fail safe.

RETURN VALUE

On success, pmempool_feature_queryU()/pmempool_feature_queryW() returns 0 if feature is disabled or 1 if it is enabled. On error, it returns -1 and sets errno accordingly.

On success, pmempool_feature_enableU()/pmempool_feature_enableW() returns 0. On error, it returns -1 and sets errno accordingly.

On success, pmempool_feature_disableU()/pmempool_feature_disableW() returns 0. On error, it returns -1 and sets errno accordingly.

If path points poolset with remote replica errno is set to EINVAL and function returns -1.

If non zero flags are provided errno is set to EINVAL and function returns -1.

SEE ALSO

poolset(5) and http://pmem.io

The contents of this web site and the associated GitHub repositories are BSD-licensed open source.