Provided by: libpmempool-dev_1.8-1ubuntu1_amd64 
NAME
pmempool_check_init(), pmempool_check(), pmempool_check_end() - checks pmempool health
SYNOPSIS
#include <libpmempool.h>
PMEMpoolcheck *pmempool_check_init(struct pmempool_check_args *args,
size_t args_size);
struct pmempool_check_status *pmempool_check(PMEMpoolcheck *ppc);
enum pmempool_check_result pmempool_check_end(PMEMpoolcheck *ppc);
DESCRIPTION
To perform the checks provided by libpmempool, a check context must first be initialized
using the pmempool_check_init() 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_check() must be called iteratively. Each call generates a new
check status, represented by a struct pmempool_check_status structure. Status messages
are described later below.
When the checks are completed, pmempool_check() 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_init() initializes the check context. args describes parameters of the
check context. args_size should be equal to the size of the struct pmempool_check_args.
struct pmempool_check_args is defined as follows:
struct pmempool_check_args
{
/* 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;
};
The flags argument accepts any combination of the following values (ORed):
• PMEMPOOL_CHECK_REPAIR - perform repairs
• PMEMPOOL_CHECK_DRY_RUN - emulate repairs, not supported on Device DAX
• PMEMPOOL_CHECK_ADVANCED - perform hazardous repairs
• PMEMPOOL_CHECK_ALWAYS_YES - do not ask before repairs
• PMEMPOOL_CHECK_VERBOSE - generate info statuses
• PMEMPOOL_CHECK_FORMAT_STR - generate string format statuses
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:
• NULL. No backup will be performed.
• a non-existent file: backup_path will be created and backup will be performed. path
must be a single file pool.
• an existing pool set file: Backup will be performed as defined by the backup_path pool
set. path must be a pool set, and backup_path must have the same structure (the same
number of parts with exactly the same size) as the path pool set.
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_check() function starts or resumes the check indicated by ppc. When the next
status is generated, the check is paused and pmempool_check() returns a pointer to the
struct pmempool_check_status structure:
struct pmempool_check_status
{
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;
};
This structure can describe three types of statuses:
• PMEMPOOL_CHECK_MSG_TYPE_INFO - detailed information about the check. Generated only if
a PMEMPOOL_CHECK_VERBOSE flag was set.
• PMEMPOOL_CHECK_MSG_TYPE_ERROR - An error was encountered.
• PMEMPOOL_CHECK_MSG_TYPE_QUESTION - question. Generated only if an
PMEMPOOL_CHECK_ALWAYS_YES flag was not set. It requires answer to be set to “yes” or
“no” before continuing.
After calling pmempool_check() again, the previously provided struct pmempool_check_status
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_init() returns an opaque handle of type PMEMpoolcheck*. If the provided
parameters are invalid or the initialization process fails, pmempool_check_init() returns
NULL and sets errno appropriately.
Each call to pmempool_check() returns a pointer to a struct pmempool_check_status
structure when a status is generated. When the check completes, pmempool_check() 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:
• PMEMPOOL_CHECK_RESULT_CONSISTENT - the pool is consistent
• PMEMPOOL_CHECK_RESULT_NOT_CONSISTENT - the pool is not consistent
• PMEMPOOL_CHECK_RESULT_REPAIRED - the pool has issues but all repair steps completed
successfully
• PMEMPOOL_CHECK_RESULT_CANNOT_REPAIR - the pool has issues which can not be repaired
• PMEMPOOL_CHECK_RESULT_ERROR - the pool has errors or the check encountered an issue
• PMEMPOOL_CHECK_RESULT_SYNC_REQ - the pool has single healthy replica. To fix remaining
issues use pmempool_sync(3).
EXAMPLE
This is an example of a check context initialization:
struct pmempool_check_args 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_init(&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>