1PMEMPOOL_CHECK_INIT(3) PMDK Programmer's Manual PMEMPOOL_CHECK_INIT(3)
2
6 pmempool_check_init(), pmempool_check(), pmempool_check_end() - checks
7 pmempool health
8
10 #include <libpmempool.h>
11 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
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 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 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 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 struct pmempool_check_args
39 {
40 /* path to the pool to check */
41 const char *path;
42 /* optional backup path */
44 const char *backup_path;
45 /* type of the pool */
47 enum pmempool_pool_type pool_type;
48 /* parameters */
50 int flags;
51 };
52 The flags argument accepts any combination of the following values
54 (ORed):
55 • PMEMPOOL_CHECK_REPAIR - perform repairs
57 • PMEMPOOL_CHECK_DRY_RUN - emulate repairs, not supported on Device DAX
59 • PMEMPOOL_CHECK_ADVANCED - perform hazardous repairs
61 • PMEMPOOL_CHECK_ALWAYS_YES - do not ask before repairs
63 • PMEMPOOL_CHECK_VERBOSE - generate info statuses
65 • PMEMPOOL_CHECK_FORMAT_STR - generate string format statuses
67 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 backup_path may be:
73 • NULL. No backup will be performed.
75 • a non-existent file: backup_path will be created and backup will be
77 performed. path must be a single file pool.
78 • 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 Backup is supported only if the source pool set has no defined repli‐
85 cas.
86 Neither path nor backup_path may specify a pool set with remote repli‐
88 cas.
89 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 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 This structure can describe three types of statuses:
106 • PMEMPOOL_CHECK_MSG_TYPE_INFO - detailed information about the check.
108 Generated only if a PMEMPOOL_CHECK_VERBOSE flag was set.
109 • PMEMPOOL_CHECK_MSG_TYPE_ERROR - An error was encountered.
111 • 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 After calling pmempool_check() again, the previously provided struct
117 pmempool_check_status pointer must be considered invalid.
118 The pmempool_check_end() function finalizes the check and releases all
120 related resources. ppc is invalid after calling pmempool_check_end().
121
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 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 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 • PMEMPOOL_CHECK_RESULT_CONSISTENT - the pool is consistent
136 • PMEMPOOL_CHECK_RESULT_NOT_CONSISTENT - the pool is not consistent
138 • PMEMPOOL_CHECK_RESULT_REPAIRED - the pool has issues but all repair
140 steps completed successfully
141 • PMEMPOOL_CHECK_RESULT_CANNOT_REPAIR - the pool has issues which can
143 not be repaired
144 • PMEMPOOL_CHECK_RESULT_ERROR - the pool has errors or the check en‐
146 countered an issue
147 • PMEMPOOL_CHECK_RESULT_SYNC_REQ - the pool has single healthy replica.
149 To fix remaining issues use pmempool_sync(3).
150
152 This is an example of a check context initialization:
153 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 PMEMpoolcheck *ppc = pmempool_check_init(&args, sizeof(args));
164 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
179 Currently, checking the consistency of a pmemobj pool is not supported.
180
182 libpmemlog(7), libpmemobj(7) and <https://pmem.io>
183PMDK - pmempool API version 1.3 2021-09-24 PMEMPOOL_CHECK_INIT(3)