.\" Automatically generated by Pandoc 2.2.1
.\"
.TH "PMEMPOOL_CHECK_INIT" "3" "2019-02-19" "PMDK - pmempool API version 1.3" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2019, Intel Corporation
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\"     * Redistributions of source code must retain the above copyright
.\"       notice, this list of conditions and the following disclaimer.
.\"
.\"     * Redistributions in binary form must reproduce the above copyright
.\"       notice, this list of conditions and the following disclaimer in
.\"       the documentation and/or other materials provided with the
.\"       distribution.
.\"
.\"     * Neither the name of the copyright holder nor the names of its
.\"       contributors may be used to endorse or promote products derived
.\"       from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.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]<http://pmem.io>\f[]