PMDK man page

pmempool_check_init

NAME
SYNOPSIS
DESCRIPTION
RETURN VALUE
EXAMPLE
NOTES
SEE ALSO

NAME

pmempool_check_initU()/pmempool_check_initW(), pmempool_checkU()/pmempool_checkW(), pmempool_check_end() - checks pmempool health

SYNOPSIS

#include <libpmempool.h>

PMEMpoolcheck *pmempool_check_initU(struct pmempool_check_argsU *args, 
	size_t args_size);
PMEMpoolcheck *pmempool_check_initW(struct pmempool_check_argsW *args, 
	size_t args_size);
struct pmempool_check_statusU *pmempool_checkU(PMEMpoolcheck *ppc);
struct pmempool_check_statusW *pmempool_checkW(PMEMpoolcheck *ppc);
enum pmempool_check_result pmempool_check_end(PMEMpoolcheck *ppc);

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

To perform the checks provided by libpmempool, a check context must first be initialized using the pmempool_check_initU()/pmempool_check_initW() function described in this section. Once initialized, the check context is represented by an opaque handle of type PMEMpoolcheck*, which is passed to all of the other functions available in libpmempool

To execute checks, pmempool_checkU()/pmempool_checkW() must be called iteratively. Each call generates a new check status, represented by a struct pmempool_check_statusU/struct pmempool_check_statusW structure. Status messages are described later below.

When the checks are completed, pmempool_checkU()/pmempool_checkW() returns NULL. The check must be finalized using pmempool_check_end(), which returns an enum pmempool_check_result describing the results of the entire check.

pmempool_check_initU()/pmempool_check_initW() initializes the check context. args describes parameters of the check context. args_size should be equal to the size of the struct pmempool_check_argsU/struct pmempool_check_argsW. struct pmempool_check_argsU/struct pmempool_check_argsW is defined as follows:

struct pmempool_check_argsU
{
	/* path to the pool to check */
	const char *path;

	/* optional backup path */
	const char *backup_path;

	/* type of the pool */
	enum pmempool_pool_type pool_type;

	/* parameters */
	int flags;
};

struct pmempool_check_argsW
{
	/* path to the pool to check */
	const wchar_t *path;

	/* optional backup path */
	const wchar_t *backup_path;

	/* type of the pool */
	enum pmempool_pool_type pool_type;

	/* parameters */
	int flags;
};

The flags argument accepts any combination of the following values (ORed):

pool_type must match the type of the pool being processed. Pool type detection may be enabled by setting pool_type to PMEMPOOL_POOL_TYPE_DETECT. A pool type detection failure ends the check.

backup_path may be:

Backup is supported only if the source pool set has no defined replicas.

Neither path nor backup_path may specify a pool set with remote replicas.

The pmempool_checkU()/pmempool_checkW() function starts or resumes the check indicated by ppc. When the next status is generated, the check is paused and pmempool_checkU()/pmempool_checkW() returns a pointer to the struct pmempool_check_statusU/struct pmempool_check_statusW structure:

{

struct pmempool_check_statusU
{
	enum pmempool_check_msg_type type; /* type of the status */
	struct
	{
		const char *msg; /* status message string */
		const char *answer; /* answer to message if applicable */
	} str;
};

struct pmempool_check_statusW
{
	enum pmempool_check_msg_type type; /* type of the status */
	struct
	{
		const wchar_t *msg; /* status message string */
		const wchar_t *answer; /* answer to message if applicable */
	} str;
};

This structure can describe three types of statuses:

After calling pmempool_checkU()/pmempool_checkW() again, the previously provided struct pmempool_check_statusU/struct pmempool_check_statusW pointer must be considered invalid.

The pmempool_check_end() function finalizes the check and releases all related resources. ppc is invalid after calling pmempool_check_end().

RETURN VALUE

pmempool_check_initU()/pmempool_check_initW() returns an opaque handle of type PMEMpoolcheck*. If the provided parameters are invalid or the initialization process fails, pmempool_check_initU()/pmempool_check_initW() returns NULL and sets errno appropriately.

Each call to pmempool_checkU()/pmempool_checkW() returns a pointer to a struct pmempool_check_statusU/struct pmempool_check_statusW structure when a status is generated. When the check completes, pmempool_checkU()/pmempool_checkW() returns NULL.

The pmempool_check_end() function returns an enum pmempool_check_result summarizing the results of the finalized check. pmempool_check_end() can return one of the following values:

EXAMPLE

This is an example of a check context initialization:

struct pmempool_check_argsU args =
{
	.path = "/path/to/blk.pool",
	.backup_path = NULL,
	.pool_type = PMEMPOOL_POOL_TYPE_BLK,
	.flags = PMEMPOOL_CHECK_REPAIR | PMEMPOOL_CHECK_DRY_RUN |
		PMEMPOOL_CHECK_VERBOSE | PMEMPOOL_CHECK_FORMAT_STR
};

PMEMpoolcheck *ppc = pmempool_check_initU(&args, sizeof(args));

The check will process a pool of type PMEMPOOL_POOL_TYPE_BLK located in the path /path/to/blk.pool. Before the check it will not create a backup of the pool (backup_path == NULL). If the check finds any issues it will try to perform repair steps (PMEMPOOL_CHECK_REPAIR), but it will not make any changes to the pool (PMEMPOOL_CHECK_DRY_RUN) and it will not perform any dangerous repair steps (no PMEMPOOL_CHECK_ADVANCED). The check will ask before performing any repair steps (no PMEMPOOL_CHECK_ALWAYS_YES). It will also generate detailed information about the check (PMEMPOOL_CHECK_VERBOSE). The PMEMPOOL_CHECK_FORMAT_STR flag indicates string format statuses (struct pmempool_check_status). Currently this is the only supported status format so this flag is required.

NOTES

Currently, checking the consistency of a pmemobj pool is not supported.

SEE ALSO

libpmemlog(7), libpmemobj(7) and https://pmem.io