.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-31" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2022, Intel Corporation
.SH NAME
.PP
\f[B]pmempool_check_init\f[R](), \f[B]pmempool_check\f[R](),
\f[B]pmempool_check_end\f[R]() - checks pmempool health
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[R]
.fi
.SH DESCRIPTION
.PP
To perform the checks provided by \f[B]libpmempool\f[R], a \f[I]check
context\f[R] must first be initialized using the
\f[B]pmempool_check_init\f[R]() function described in this section.
Once initialized, the \f[I]check context\f[R] is represented by an
opaque handle of type \f[I]PMEMpoolcheck*\f[R], which is passed to all
of the other functions available in \f[B]libpmempool\f[R]
.PP
To execute checks, \f[B]pmempool_check\f[R]() must be called
iteratively.
Each call generates a new check status, represented by a \f[I]struct
pmempool_check_status\f[R] structure.
Status messages are described later below.
.PP
When the checks are completed, \f[B]pmempool_check\f[R]() returns NULL.
The check must be finalized using \f[B]pmempool_check_end\f[R](), which
returns an \f[I]enum pmempool_check_result\f[R] describing the results
of the entire check.
.PP
\f[B]pmempool_check_init\f[R]() initializes the check context.
\f[I]args\f[R] describes parameters of the check context.
\f[I]args_size\f[R] should be equal to the size of the \f[I]struct
pmempool_check_args\f[R].
\f[I]struct pmempool_check_args\f[R] is defined as follows:
.IP
.nf
\f[C]
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;
};
\f[R]
.fi
.PP
The \f[I]flags\f[R] argument accepts any combination of the following
values (ORed):
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_REPAIR\f[R] - perform repairs
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_DRY_RUN\f[R] - emulate repairs, not supported on
Device DAX
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_ADVANCED\f[R] - perform hazardous repairs
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_ALWAYS_YES\f[R] - do not ask before repairs
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_VERBOSE\f[R] - generate info statuses
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_FORMAT_STR\f[R] - generate string format statuses
.PP
\f[I]pool_type\f[R] must match the type of the \f[I]pool\f[R] being
processed.
Pool type detection may be enabled by setting \f[I]pool_type\f[R] to
\f[B]PMEMPOOL_POOL_TYPE_DETECT\f[R].
A pool type detection failure ends the check.
.PP
\f[I]backup_path\f[R] may be:
.IP \[bu] 2
NULL.
No backup will be performed.
.IP \[bu] 2
a non-existent file: \f[I]backup_path\f[R] will be created and backup
will be performed.
\f[I]path\f[R] must be a single file \f[I]pool\f[R].
.IP \[bu] 2
an existing \f[I]pool set\f[R] file: Backup will be performed as defined
by the \f[I]backup_path\f[R] pool set.
\f[I]path\f[R] must be a pool set, and \f[I]backup_path\f[R] must have
the same structure (the same number of parts with exactly the same size)
as the \f[I]path\f[R] pool set.
.PP
Backup is supported only if the source \f[I]pool set\f[R] has no defined
replicas.
.PP
The \f[B]pmempool_check\f[R]() function starts or resumes the check
indicated by \f[I]ppc\f[R].
When the next status is generated, the check is paused and
\f[B]pmempool_check\f[R]() returns a pointer to the \f[I]struct
pmempool_check_status\f[R] structure:
.IP
.nf
\f[C]
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;
};
\f[R]
.fi
.PP
This structure can describe three types of statuses:
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_MSG_TYPE_INFO\f[R] - detailed information about the
check.
Generated only if a \f[B]PMEMPOOL_CHECK_VERBOSE\f[R] flag was set.
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_MSG_TYPE_ERROR\f[R] - An error was encountered.
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_MSG_TYPE_QUESTION\f[R] - question.
Generated only if an \f[B]PMEMPOOL_CHECK_ALWAYS_YES\f[R] flag was not
set.
It requires \f[I]answer\f[R] to be set to \[lq]yes\[rq] or \[lq]no\[rq]
before continuing.
.PP
After calling \f[B]pmempool_check\f[R]() again, the previously provided
\f[I]struct pmempool_check_status\f[R] pointer must be considered
invalid.
.PP
The \f[B]pmempool_check_end\f[R]() function finalizes the check and
releases all related resources.
\f[I]ppc\f[R] is invalid after calling \f[B]pmempool_check_end\f[R]().
.SH RETURN VALUE
.PP
\f[B]pmempool_check_init\f[R]() returns an opaque handle of type
\f[I]PMEMpoolcheck*\f[R].
If the provided parameters are invalid or the initialization process
fails, \f[B]pmempool_check_init\f[R]() returns NULL and sets
\f[I]errno\f[R] appropriately.
.PP
Each call to \f[B]pmempool_check\f[R]() returns a pointer to a
\f[I]struct pmempool_check_status\f[R] structure when a status is
generated.
When the check completes, \f[B]pmempool_check\f[R]() returns NULL.
.PP
The \f[B]pmempool_check_end\f[R]() function returns an \f[I]enum
pmempool_check_result\f[R] summarizing the results of the finalized
check.
\f[B]pmempool_check_end\f[R]() can return one of the following values:
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_RESULT_CONSISTENT\f[R] - the \f[I]pool\f[R] is
consistent
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_RESULT_NOT_CONSISTENT\f[R] - the \f[I]pool\f[R] is
not consistent
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_RESULT_REPAIRED\f[R] - the \f[I]pool\f[R] has issues
but all repair steps completed successfully
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_RESULT_CANNOT_REPAIR\f[R] - the \f[I]pool\f[R] has
issues which can not be repaired
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_RESULT_ERROR\f[R] - the \f[I]pool\f[R] has errors or
the check encountered an issue
.IP \[bu] 2
\f[B]PMEMPOOL_CHECK_RESULT_SYNC_REQ\f[R] - the \f[I]pool\f[R] has single
healthy replica.
To fix remaining issues use \f[B]pmempool_sync\f[R](3).
.SH EXAMPLE
.PP
This is an example of a \f[I]check context\f[R] initialization:
.IP
.nf
\f[C]
struct pmempool_check_args args =
{
    .path = \[dq]/path/to/blk.pool\[dq],
    .backup_path = NULL,
    .pool_type = PMEMPOOL_POOL_TYPE_BLK,
    .flags = PMEMPOOL_CHECK_REPAIR | PMEMPOOL_CHECK_DRY_RUN |
        PMEMPOOL_CHECK_VERBOSE | PMEMPOOL_CHECK_FORMAT_STR
};
\f[R]
.fi
.IP
.nf
\f[C]
PMEMpoolcheck *ppc = pmempool_check_init(&args, sizeof(args));
\f[R]
.fi
.PP
The check will process a \f[I]pool\f[R] of type
\f[B]PMEMPOOL_POOL_TYPE_BLK\f[R] located in the path
\f[I]/path/to/blk.pool\f[R].
Before the check it will not create a backup of the \f[I]pool\f[R]
(\f[I]backup_path == NULL\f[R]).
If the check finds any issues it will try to perform repair steps
(\f[B]PMEMPOOL_CHECK_REPAIR\f[R]), but it will not make any changes to
the \f[I]pool\f[R] (\f[B]PMEMPOOL_CHECK_DRY_RUN\f[R]) and it will not
perform any dangerous repair steps (no
\f[B]PMEMPOOL_CHECK_ADVANCED\f[R]).
The check will ask before performing any repair steps (no
\f[B]PMEMPOOL_CHECK_ALWAYS_YES\f[R]).
It will also generate detailed information about the check
(\f[B]PMEMPOOL_CHECK_VERBOSE\f[R]).
The \f[B]PMEMPOOL_CHECK_FORMAT_STR\f[R] flag indicates string format
statuses (\f[I]struct pmempool_check_status\f[R]).
Currently this is the only supported status format so this flag is
required.
.SH NOTES
.PP
Currently, checking the consistency of a \f[I]pmemobj\f[R] pool is
\f[B]not\f[R] supported.
.SH SEE ALSO
.PP
\f[B]libpmemlog\f[R](7), \f[B]libpmemobj\f[R](7) and
\f[B]<https://pmem.io>\f[R]