1PMEMPOOL_CHECK_INIT(3)     PMDK Programmer's Manual     PMEMPOOL_CHECK_INIT(3)
2
3
4

NAME

6       pmempool_check_init(),  pmempool_check(), pmempool_check_end() - checks
7       pmempool health
8

SYNOPSIS

10              #include <libpmempool.h>
11
12              PMEMpoolcheck *pmempool_check_init(struct pmempool_check_args *args,
13                  size_t args_size);
14              struct pmempool_check_status *pmempool_check(PMEMpoolcheck *ppc);
15              enum pmempool_check_result pmempool_check_end(PMEMpoolcheck *ppc);
16

DESCRIPTION

18       To perform the checks provided by libpmempool,  a  check  context  must
19       first be initialized using the pmempool_check_init() function described
20       in this section.  Once initialized, the check context is represented by
21       an  opaque handle of type PMEMpoolcheck*, which is passed to all of the
22       other functions available in libpmempool
23
24       To execute checks, pmempool_check() must be called  iteratively.   Each
25       call  generates  a  new  check  status,  represented  by a struct pmem‐
26       pool_check_status structure.  Status messages are described  later  be‐
27       low.
28
29       When  the  checks  are  completed,  pmempool_check() returns NULL.  The
30       check must be finalized using pmempool_check_end(),  which  returns  an
31       enum pmempool_check_result describing the results of the entire check.
32
33       pmempool_check_init()  initializes  the  check context.  args describes
34       parameters of the check context.  args_size should be equal to the size
35       of  the  struct pmempool_check_args.  struct pmempool_check_args is de‐
36       fined as follows:
37
38              struct pmempool_check_args
39              {
40                  /* path to the pool to check */
41                  const char *path;
42
43                  /* optional backup path */
44                  const char *backup_path;
45
46                  /* type of the pool */
47                  enum pmempool_pool_type pool_type;
48
49                  /* parameters */
50                  int flags;
51              };
52
53       The flags argument accepts any  combination  of  the  following  values
54       (ORed):
55
56       · PMEMPOOL_CHECK_REPAIR - perform repairs
57
58       · PMEMPOOL_CHECK_DRY_RUN - emulate repairs, not supported on Device DAX
59
60       · PMEMPOOL_CHECK_ADVANCED - perform hazardous repairs
61
62       · PMEMPOOL_CHECK_ALWAYS_YES - do not ask before repairs
63
64       · PMEMPOOL_CHECK_VERBOSE - generate info statuses
65
66       · PMEMPOOL_CHECK_FORMAT_STR - generate string format statuses
67
68       pool_type  must  match the type of the pool being processed.  Pool type
69       detection may be enabled by setting pool_type to PMEMPOOL_POOL_TYPE_DE‐
70       TECT.  A pool type detection failure ends the check.
71
72       backup_path may be:
73
74       · NULL.  No backup will be performed.
75
76       · a  non-existent  file: backup_path will be created and backup will be
77         performed.  path must be a single file pool.
78
79       · an existing pool set file: Backup will be performed as defined by the
80         backup_path  pool set.  path must be a pool set, and backup_path must
81         have the same structure (the same number of parts  with  exactly  the
82         same size) as the path pool set.
83
84       Backup  is  supported only if the source pool set has no defined repli‐
85       cas.
86
87       Neither path nor backup_path may specify a pool set with remote  repli‐
88       cas.
89
90       The  pmempool_check() function starts or resumes the check indicated by
91       ppc.  When the next status is generated, the check is paused and  pmem‐
92       pool_check()  returns  a  pointer  to  the struct pmempool_check_status
93       structure:
94
95              struct pmempool_check_status
96              {
97                  enum pmempool_check_msg_type type; /* type of the status */
98                  struct
99                  {
100                      const char *msg; /* status message string */
101                      const char *answer; /* answer to message if applicable */
102                  } str;
103              };
104
105       This structure can describe three types of statuses:
106
107       · PMEMPOOL_CHECK_MSG_TYPE_INFO - detailed information about the  check.
108         Generated only if a PMEMPOOL_CHECK_VERBOSE flag was set.
109
110       · PMEMPOOL_CHECK_MSG_TYPE_ERROR - An error was encountered.
111
112       · PMEMPOOL_CHECK_MSG_TYPE_QUESTION  -  question.   Generated only if an
113         PMEMPOOL_CHECK_ALWAYS_YES flag was not set.  It requires answer to be
114         set to “yes” or “no” before continuing.
115
116       After  calling  pmempool_check()  again, the previously provided struct
117       pmempool_check_status pointer must be considered invalid.
118
119       The pmempool_check_end() function finalizes the check and releases  all
120       related resources.  ppc is invalid after calling pmempool_check_end().
121

RETURN VALUE

123       pmempool_check_init()  returns an opaque handle of type PMEMpoolcheck*.
124       If the provided parameters are invalid or  the  initialization  process
125       fails, pmempool_check_init() returns NULL and sets errno appropriately.
126
127       Each  call  to  pmempool_check()  returns  a  pointer to a struct pmem‐
128       pool_check_status structure when a status is generated.  When the check
129       completes, pmempool_check() returns NULL.
130
131       The pmempool_check_end() function returns an enum pmempool_check_result
132       summarizing the results of the finalized  check.   pmempool_check_end()
133       can return one of the following values:
134
135       · PMEMPOOL_CHECK_RESULT_CONSISTENT - the pool is consistent
136
137       · PMEMPOOL_CHECK_RESULT_NOT_CONSISTENT - the pool is not consistent
138
139       · PMEMPOOL_CHECK_RESULT_REPAIRED  -  the pool has issues but all repair
140         steps completed successfully
141
142       · PMEMPOOL_CHECK_RESULT_CANNOT_REPAIR - the pool has issues  which  can
143         not be repaired
144
145       · PMEMPOOL_CHECK_RESULT_ERROR  -  the  pool has errors or the check en‐
146         countered an issue
147
148       · PMEMPOOL_CHECK_RESULT_SYNC_REQ - the pool has single healthy replica.
149         To fix remaining issues use pmempool_sync(3).
150

EXAMPLE

152       This is an example of a check context initialization:
153
154              struct pmempool_check_args args =
155              {
156                  .path = "/path/to/blk.pool",
157                  .backup_path = NULL,
158                  .pool_type = PMEMPOOL_POOL_TYPE_BLK,
159                  .flags = PMEMPOOL_CHECK_REPAIR | PMEMPOOL_CHECK_DRY_RUN |
160                      PMEMPOOL_CHECK_VERBOSE | PMEMPOOL_CHECK_FORMAT_STR
161              };
162
163              PMEMpoolcheck *ppc = pmempool_check_init(&args, sizeof(args));
164
165       The check will process a pool of type PMEMPOOL_POOL_TYPE_BLK located in
166       the path /path/to/blk.pool.  Before the check  it  will  not  create  a
167       backup  of  the pool (backup_path == NULL).  If the check finds any is‐
168       sues it will try to perform repair steps  (PMEMPOOL_CHECK_REPAIR),  but
169       it  will  not make any changes to the pool (PMEMPOOL_CHECK_DRY_RUN) and
170       it will not perform any dangerous repair steps  (no  PMEMPOOL_CHECK_AD‐
171       VANCED).   The  check  will  ask before performing any repair steps (no
172       PMEMPOOL_CHECK_ALWAYS_YES).  It will also generate detailed information
173       about  the  check  (PMEMPOOL_CHECK_VERBOSE).   The  PMEMPOOL_CHECK_FOR‐
174       MAT_STR  flag  indicates   string   format   statuses   (struct   pmem‐
175       pool_check_status).  Currently this is the only supported status format
176       so this flag is required.
177

NOTES

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

SEE ALSO

182       libpmemlog(7), libpmemobj(7) and <https://pmem.io>
183
184
185
186PMDK - pmempool API version 1.3   2020-01-31            PMEMPOOL_CHECK_INIT(3)
Impressum