1() PMDK Programmer's Manual ()
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 The pmempool_check() function starts or resumes the check indicated by
88 ppc. When the next status is generated, the check is paused and pmem‐
89 pool_check() returns a pointer to the struct pmempool_check_status
90 structure:
91 struct pmempool_check_status
93 {
94 enum pmempool_check_msg_type type; /* type of the status */
95 struct
96 {
97 const char *msg; /* status message string */
98 const char *answer; /* answer to message if applicable */
99 } str;
100 };
101 This structure can describe three types of statuses:
103 • PMEMPOOL_CHECK_MSG_TYPE_INFO - detailed information about the check.
105 Generated only if a PMEMPOOL_CHECK_VERBOSE flag was set.
106 • PMEMPOOL_CHECK_MSG_TYPE_ERROR - An error was encountered.
108 • PMEMPOOL_CHECK_MSG_TYPE_QUESTION - question. Generated only if an
110 PMEMPOOL_CHECK_ALWAYS_YES flag was not set. It requires answer to be
111 set to “yes” or “no” before continuing.
112 After calling pmempool_check() again, the previously provided struct
114 pmempool_check_status pointer must be considered invalid.
115 The pmempool_check_end() function finalizes the check and releases all
117 related resources. ppc is invalid after calling pmempool_check_end().
118
120 pmempool_check_init() returns an opaque handle of type PMEMpoolcheck*.
121 If the provided parameters are invalid or the initialization process
122 fails, pmempool_check_init() returns NULL and sets errno appropriately.
123 Each call to pmempool_check() returns a pointer to a struct pmem‐
125 pool_check_status structure when a status is generated. When the check
126 completes, pmempool_check() returns NULL.
127 The pmempool_check_end() function returns an enum pmempool_check_result
129 summarizing the results of the finalized check. pmempool_check_end()
130 can return one of the following values:
131 • PMEMPOOL_CHECK_RESULT_CONSISTENT - the pool is consistent
133 • PMEMPOOL_CHECK_RESULT_NOT_CONSISTENT - the pool is not consistent
135 • PMEMPOOL_CHECK_RESULT_REPAIRED - the pool has issues but all repair
137 steps completed successfully
138 • PMEMPOOL_CHECK_RESULT_CANNOT_REPAIR - the pool has issues which can
140 not be repaired
141 • PMEMPOOL_CHECK_RESULT_ERROR - the pool has errors or the check en‐
143 countered an issue
144 • PMEMPOOL_CHECK_RESULT_SYNC_REQ - the pool has single healthy replica.
146 To fix remaining issues use pmempool_sync(3).
147
149 This is an example of a check context initialization:
150 struct pmempool_check_args args =
152 {
153 .path = "/path/to/blk.pool",
154 .backup_path = NULL,
155 .pool_type = PMEMPOOL_POOL_TYPE_BLK,
156 .flags = PMEMPOOL_CHECK_REPAIR | PMEMPOOL_CHECK_DRY_RUN |
157 PMEMPOOL_CHECK_VERBOSE | PMEMPOOL_CHECK_FORMAT_STR
158 };
159 PMEMpoolcheck *ppc = pmempool_check_init(&args, sizeof(args));
161 The check will process a pool of type PMEMPOOL_POOL_TYPE_BLK located in
163 the path /path/to/blk.pool. Before the check it will not create a
164 backup of the pool (backup_path == NULL). If the check finds any is‐
165 sues it will try to perform repair steps (PMEMPOOL_CHECK_REPAIR), but
166 it will not make any changes to the pool (PMEMPOOL_CHECK_DRY_RUN) and
167 it will not perform any dangerous repair steps (no PMEMPOOL_CHECK_AD‐
168 VANCED). The check will ask before performing any repair steps (no
169 PMEMPOOL_CHECK_ALWAYS_YES). It will also generate detailed information
170 about the check (PMEMPOOL_CHECK_VERBOSE). The PMEMPOOL_CHECK_FOR‐
171 MAT_STR flag indicates string format statuses (struct pmem‐
172 pool_check_status). Currently this is the only supported status format
173 so this flag is required.
174
176 Currently, checking the consistency of a pmemobj pool is not supported.
177
179 libpmemlog(7), libpmemobj(7) and <https://pmem.io>
180PMDK - 2023-06-05 ()