pmempool_check_init(), pmempool_check(), pmempool_check_end() - checks pmempool health

       To  perform the checks provided by libpmempool, a checkcontext must first be initialized using the pmem‐pool_check_init() function described in this section.  Once initialized, the checkcontext 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 structpmempool_check_status structure.  Status messages are described later below.

       When the checks are completed, pmempool_check() returns NULL.  The check must be  finalized  using  pmem‐pool_check_end(), which returns an enumpmempool_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 structpmempool_check_args.  structpmempool_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 poolset 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 poolset has no defined replicas.

       The pmempool_check() function starts or resumes the check indicated by ppc.  When the next status is gen‐
       erated, the check is paused and pmempool_check() returns a pointer to  the  structpmempool_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 PMEM‐POOL_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 structpmempool_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().

       This is an example of a checkcontext 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.   Be‐
       fore the check it will not create a backup of the pool (backup_path==NULL).  If the check finds any is‐
       sues 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_AD‐VANCED).  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_FOR‐MAT_STR flag indicates string format statuses (structpmempool_check_status).  Currently this is the only
       supported status format so this flag is required.

pmempool_check_init(), pmempool_check(), pmempool_check_end() - checks pmempool health

       Currently, checking the consistency of a pmemobj pool is not supported.

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 appropri‐
       ately.

       Each call to pmempool_check() returns a pointer to a structpmempool_check_status structure when a status
       is generated.  When the check completes, pmempool_check() returns NULL.

       The pmempool_check_end() function returns an enumpmempool_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).

libpmemlog(7), libpmemobj(7) and <https://pmem.io>

              #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);