pmempool_check_init man page

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):

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_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:

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:

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 <http://pmem.io>

Referenced By

libpmempool(7).

The man pages pmempool_check(3) and pmempool_check_end(3) are aliases of pmempool_check_init(3).

2019-07-10 PMDK - pmempool API version 1.3 PMDK Programmer's Manual