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