--- name: "pmempool_check_init" section: "3" platform: "linux" package: "libpmempool-dev" version: "1.13.1-1.1+b1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/pmempool_check_init" --- # pmempool\_check\_init(3) checks pmempool health ## NAME **pmempool\_check\_init**(), **pmempool\_check**(), **pmempool\_check\_end**() - checks pmempool health ## SYNOPSIS - ``` #include 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); ``` ## DESCRIPTION To perform the checks provided by **libpmempool**, a *check* *context* must first be initialized using the **pmempool\_check\_init**() function described in this section. Once initialized, the *check context* 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 *struct* *pmempool\_check\_status* structure. Status messages are described later below. When the checks are completed, **pmempool\_check**() returns NULL. The check must be finalized using **pmempool\_check\_end**(), which returns an *enum pmempool\_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 *struct* *pmempool\_check\_args*. *struct pmempool\_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 *pool set* 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 *pool set* has no defined replicas. The **pmempool\_check**() function starts or resumes the check indicated by *ppc*. When the next status is generated, the check is paused and **pmempool\_check**() returns a pointer to the *struct* *pmempool\_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 **PMEMPOOL\_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 *struct pmempool\_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**(). ## RETURN VALUE **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* appropriately. Each call to **pmempool\_check**() returns a pointer to a *struct pmempool\_check\_status* structure when a status is generated. When the check completes, **pmempool\_check**() returns NULL. The **pmempool\_check\_end**() function returns an *enum* *pmempool\_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)](/pmempool_sync/3.md). ## EXAMPLE This is an example of a *check context* 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*. Before the check it will not create a backup of the *pool* (*backup\_path == NULL*). If the check finds any issues 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\_ADVANCED**). 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\_FORMAT\_STR** flag indicates string format statuses (*struct pmempool\_check\_status*). Currently this is the only supported status format so this flag is required. ## NOTES Currently, checking the consistency of a *pmemobj* pool is **not** supported. ## SEE ALSO [**libpmemlog**(7)](/libpmemlog/7.md), [**libpmemobj**(7)](/libpmemobj/7.md) and **\**