Classes
struct	MDBX_chk_line_t
	A virtual row of the report generated during a database integrity check. More...
struct	MDBX_chk_issue_t
	An issue problem was discovered during a database integrity check. More...
struct	MDBX_chk_scope_t
	A hierarchical context during a database integrity check. More...
struct	MDBX_chk_histogram
	A histogram with some statistical information collected during a database integrity check. More...
struct	MDBX_chk_table_t
	Information about a certain key-value table during a database integrity check. More...
struct	MDBX_chk_context_t
	The context for checking the integrity of a database. More...
struct	MDBX_chk_callbacks_t
	A set of callback functions used for checking the integrity of a database. More...
union	MDBX_chk_scope_t.usr_z
union	MDBX_chk_scope_t.usr_v
union	MDBX_chk_scope_t.usr_o
struct	MDBX_chk_histogram.ranges
struct	MDBX_chk_table_t.pages
struct	MDBX_chk_table_t.histogram
struct	MDBX_chk_context_t.result

Macros
#define	mdbx_env_open_for_recoveryT(env, pathname, target_mets, writeable)
#define	mdbx_preopen_snapinfoT(pathname, info, bytes)

Typedefs
typedef struct MDBX_chk_user_table_cookie	MDBX_chk_user_table_cookie_t
	A custom type for binding additional data associated with a certain key-value table during a database integrity check.

Enumerations
enum	MDBX_chk_flags_t { MDBX_CHK_DEFAULTS = 0 , MDBX_CHK_READWRITE = 1 , MDBX_CHK_SKIP_BTREE_TRAVERSAL = 2 , MDBX_CHK_SKIP_KV_TRAVERSAL = 4 , MDBX_CHK_IGNORE_ORDER = 8 }
	Flags/options for checking the integrity of a database. More...
enum	MDBX_chk_severity_t { MDBX_chk_severity_prio_shift = 4 , MDBX_chk_severity_kind_mask = 0xF , MDBX_chk_fatal = 0x00u , MDBX_chk_error = 0x11u , MDBX_chk_warning = 0x22u , MDBX_chk_notice = 0x33u , MDBX_chk_result = 0x44u , MDBX_chk_resolution = 0x55u , MDBX_chk_processing = 0x56u , MDBX_chk_info = 0x67u , MDBX_chk_verbose = 0x78u , MDBX_chk_details = 0x89u , MDBX_chk_extra = 0x9Au }
	Levels of logging/detailing of information supplied via callbacks during a database integrity check. More...
enum	MDBX_chk_stage_t { MDBX_chk_none , MDBX_chk_init , MDBX_chk_lock , MDBX_chk_meta , MDBX_chk_tree , MDBX_chk_gc , MDBX_chk_space , MDBX_chk_maindb , MDBX_chk_tables , MDBX_chk_conclude , MDBX_chk_unlock , MDBX_chk_finalize }
	The verification stages reported via callbacks during a database integrity check. More...

Functions
LIBMDBX_API int	mdbx_txn_lock (MDBX_env *env, bool dont_wait)
	Acquires write-transaction lock. Provided for custom and/or complex locking scenarios.
LIBMDBX_API int	mdbx_txn_unlock (MDBX_env *env)
	Releases write-transaction lock. Provided for custom and/or complex locking scenarios.
LIBMDBX_API int	mdbx_env_open_for_recovery (MDBX_env env, const char pathname, unsigned target_meta, bool writeable)
	Open an environment instance using specific meta-page for checking and recovery.
LIBMDBX_API int	mdbx_env_turn_for_recovery (MDBX_env *env, unsigned target_meta)
	Turn database to the specified meta-page.
LIBMDBX_API int	mdbx_env_chk (MDBX_env env, const MDBX_chk_callbacks_t cb, MDBX_chk_context_t *ctx, const MDBX_chk_flags_t flags, MDBX_chk_severity_t verbosity, unsigned timeout_seconds_16dot16)
	Checks the integrity of a database.
LIBMDBX_API int	mdbx_env_chk_encount_problem (MDBX_chk_context_t *ctx)
	An auxiliary function to account issues detected by an application, including those coming to an application through logging.
LIBMDBX_API const char *	mdbx_ratio2digits (uint64_t numerator, uint64_t denominator, int precision, char *buffer, size_t buffer_size)
	An auxiliary function for converting fractions to string of decimal digits without using floating-point operations.
LIBMDBX_API const char *	mdbx_ratio2percents (uint64_t value, uint64_t whole, char *buffer, size_t buffer_size)
	An auxiliary function for converting fractions to percentage string without using floating-point operations.

Detailed Description

Basically this is internal API for mdbx_chk tool, etc. You should avoid to use it, except some extremal special cases.

Class Documentation

◆ MDBX_chk_line_t

struct MDBX_chk_line_t

A virtual row of the report generated during a database integrity check.

See also: mdbx_env_chk()

Class Members
char *	begin
struct MDBX_chk_context *	ctx
uint8_t	empty
char *	end
char *	out
uint8_t	scope_depth
uint8_t	severity

◆ MDBX_chk_issue_t

struct MDBX_chk_issue_t

An issue problem was discovered during a database integrity check.

See also: mdbx_env_chk()

Class Members
const char *	caption
size_t	count
struct MDBX_chk_issue *	next

◆ MDBX_chk_scope_t

struct MDBX_chk_scope_t

A hierarchical context during a database integrity check.

See also: mdbx_env_chk()

Class Members
struct MDBX_chk_internal *	internal
MDBX_chk_issue_t *	issues
const void *	object
MDBX_chk_stage_t	stage
size_t	subtotal_issues
union MDBX_chk_scope_t.usr_o	usr_o
union MDBX_chk_scope_t.usr_v	usr_v
union MDBX_chk_scope_t.usr_z	usr_z
MDBX_chk_severity_t	verbosity

◆ MDBX_chk_histogram

struct MDBX_chk_histogram

A histogram with some statistical information collected during a database integrity check.

See also: mdbx_env_chk()

Class Members
size_t	amount
size_t	count
size_t	le1_amount
size_t	le1_count
struct MDBX_chk_histogram.ranges	ranges[9]

◆ MDBX_chk_table_t

struct MDBX_chk_table_t

Information about a certain key-value table during a database integrity check.

See also: mdbx_env_chk()

Class Members
MDBX_chk_user_table_cookie_t *	cookie
MDBX_db_flags_t	flags
struct MDBX_chk_table_t.histogram	histogram
int	id
size_t	lost_bytes
MDBX_val	name
struct MDBX_chk_table_t.pages	pages
size_t	payload_bytes

◆ MDBX_chk_context_t

struct MDBX_chk_context_t

The context for checking the integrity of a database.

See also: mdbx_env_chk()

Class Members
MDBX_env *	env
struct MDBX_chk_internal *	internal
struct MDBX_chk_context_t.result	result
MDBX_chk_scope_t *	scope
uint8_t	scope_nesting
MDBX_txn *	txn

◆ MDBX_chk_callbacks_t

struct MDBX_chk_callbacks_t

A set of callback functions used for checking the integrity of a database.

The callback functions are designed to organize interaction with the application code. This includes the integration of application logic that verifies the integrity of a data structure above the key-value level, the preparation and structured output of information about both the progress and the results of verification.

All callback functions are optional, unused ones must be set to ‘nullptr’.

Note: This API has not been frozen yet, and there may be improvements and changes in subsequent versions.

See also: mdbx_env_chk()

Class Members
bool()(MDBX_chk_context_t ctx)	check_break
void()(MDBX_chk_context_t ctx, const char object, uint64_t entry_number, const char issue, const char *extra_fmt, va_list extra_args)	issue
MDBX_chk_line_t ()(MDBX_chk_context_t *ctx, MDBX_chk_severity_t severity)	print_begin
void()(MDBX_chk_line_t , const char *str, size_t len)	print_chars
void()(MDBX_chk_line_t )	print_done
void()(MDBX_chk_line_t )	print_flush
void()(MDBX_chk_line_t , const char *fmt, va_list args)	print_format
void()(MDBX_chk_line_t , const char prefix, const uint64_t value, const char suffix)	print_size
int()(MDBX_chk_context_t ctx, MDBX_chk_scope_t outer, MDBX_chk_scope_t inner, int err)	scope_conclude
void()(MDBX_chk_context_t ctx, MDBX_chk_scope_t outer, MDBX_chk_scope_t inner)	scope_pop
int()(MDBX_chk_context_t ctx, MDBX_chk_scope_t outer, MDBX_chk_scope_t inner, const char *fmt, va_list args)	scope_push
int()(MDBX_chk_context_t ctx, MDBX_chk_stage_t)	stage_begin
int()(MDBX_chk_context_t ctx, MDBX_chk_stage_t, int err)	stage_end
int()(MDBX_chk_context_t ctx, const MDBX_chk_table_t table, MDBX_cursor cursor, int err)	table_conclude
void()(MDBX_chk_context_t ctx, const MDBX_chk_table_t *table)	table_dispose
MDBX_chk_user_table_cookie_t ()(MDBX_chk_context_t ctx, const MDBX_val name, MDBX_db_flags_t flags)	table_filter
int()(MDBX_chk_context_t ctx, const MDBX_chk_table_t table, size_t entry_number, const MDBX_val key, const MDBX_val *value)	table_handle_kv

◆ MDBX_chk_scope_t.usr_z

union MDBX_chk_scope_t.usr_z

Class Members
size_t	number
void *	ptr

◆ MDBX_chk_scope_t.usr_v

union MDBX_chk_scope_t.usr_v

Class Members
size_t	number
void *	ptr

◆ MDBX_chk_scope_t.usr_o

union MDBX_chk_scope_t.usr_o

Class Members
size_t	number
void *	ptr

◆ MDBX_chk_histogram.ranges

struct MDBX_chk_histogram.ranges

Class Members
size_t	amount
size_t	begin
size_t	count
size_t	end

◆ MDBX_chk_table_t.pages

struct MDBX_chk_table_t.pages

Class Members
size_t	all
size_t	branch
size_t	broken
size_t	empty
size_t	leaf
size_t	nested_branch
size_t	nested_leaf
size_t	nested_subleaf

◆ MDBX_chk_table_t.histogram

struct MDBX_chk_table_t.histogram

Class Members
struct MDBX_chk_histogram	height	Tree deep histogram
struct MDBX_chk_histogram	key_len	Keys length histogram
struct MDBX_chk_histogram	large_or_nested_density	Histogram of nested tree(s) branch and leaf pages filling in percents
struct MDBX_chk_histogram	large_pages	Histogram of large/overflow pages length
struct MDBX_chk_histogram	multival	Number of multi-values (aka duplicates) histogram
struct MDBX_chk_histogram	nested_height_or_gc_span_length	Histogram of nested trees height, span length for GC
struct MDBX_chk_histogram	page_age	Histogram of pages age
struct MDBX_chk_histogram	pgno	Histogram of used pgno
struct MDBX_chk_histogram	tree_density	Histogram of branch and leaf pages filling in percents
struct MDBX_chk_histogram	val_len	Values length histogram

◆ MDBX_chk_context_t.result

struct MDBX_chk_context_t.result

Class Members
size_t	alloc_pages
size_t	backed_pages
size_t	gc_pages
size_t	gc_tree_problems
struct MDBX_chk_histogram	histogram_page_age	Histogram of pages age
struct MDBX_chk_histogram	histogram_pgno_payload	Histogram of pgno retained by readers
struct MDBX_chk_histogram	histogram_pgno_retained	Histogram of pgno used by all payload
size_t	kv_tree_problems
size_t	problems_gc
size_t	problems_kv
size_t	problems_meta
size_t	processed_pages
uint64_t	recent_txnid
size_t	reclaimable_pages
uint64_t	steady_txnid
size_t	table_processed
size_t	table_total
const MDBX_chk_table_t const	tables	A pointer to the array of table_total pointers to instances of MDBX_chk_table_t structures with information about all key-value tables, including MainDB and GC.
size_t	total_payload_bytes
size_t	total_problems
size_t	total_unused_bytes
size_t	tree_problems
size_t	unused_pages

Macro Definition Documentation

◆ mdbx_env_open_for_recoveryT

#define mdbx_env_open_for_recoveryT	(	env,
		pathname,
		target_mets,
		writeable )

Value:

mdbx_env_open_for_recoveryW(env, pathname, target_mets, writeable)

mdbx_env_open_for_recoveryW

LIBMDBX_API int mdbx_env_open_for_recoveryW(MDBX_env *env, const wchar_t *pathname, unsigned target_meta, bool writeable)

Open an environment instance using specific meta-page for checking and recovery.

◆ mdbx_preopen_snapinfoT

#define mdbx_preopen_snapinfoT	(	pathname,
		info,
		bytes )

Value:

mdbx_preopen_snapinfoW(pathname, info, bytes)

mdbx_preopen_snapinfoW

LIBMDBX_API int mdbx_preopen_snapinfoW(const wchar_t *pathname, MDBX_envinfo *info, size_t bytes)

Gets basic information about the database without opening it.

Typedef Documentation

◆ MDBX_chk_user_table_cookie_t

typedef struct MDBX_chk_user_table_cookie MDBX_chk_user_table_cookie_t

A custom type for binding additional data associated with a certain key-value table during a database integrity check.

See also: mdbx_env_chk()

Enumeration Type Documentation

◆ MDBX_chk_flags_t

enum MDBX_chk_flags_t

Flags/options for checking the integrity of a database.

Note: This API has not been frozen yet, there may be improvements and changes in subsequent versions.

See also: mdbx_env_chk()

Enumerator
MDBX_CHK_DEFAULTS	The check mode by default, including read-only mode.
MDBX_CHK_READWRITE	Checking in read-write mode, with locking and suspending writing transactions.
MDBX_CHK_SKIP_BTREE_TRAVERSAL	Skip the page tree crawl.
MDBX_CHK_SKIP_KV_TRAVERSAL	Skip iterating and viewing key-value records.
MDBX_CHK_IGNORE_ORDER	Ignore the order of keys and values. Note This options is required when checking databases created using non-standard (custom) key and/or value comparison functions.

◆ MDBX_chk_severity_t

enum MDBX_chk_severity_t

Levels of logging/detailing of information supplied via callbacks during a database integrity check.

See also: mdbx_env_chk()

Enumerator
MDBX_chk_severity_prio_shift
MDBX_chk_severity_kind_mask
MDBX_chk_fatal
MDBX_chk_error
MDBX_chk_warning
MDBX_chk_notice
MDBX_chk_result
MDBX_chk_resolution
MDBX_chk_processing
MDBX_chk_info
MDBX_chk_verbose
MDBX_chk_details
MDBX_chk_extra

◆ MDBX_chk_stage_t

enum MDBX_chk_stage_t

The verification stages reported via callbacks during a database integrity check.

See also: mdbx_env_chk()

Enumerator
MDBX_chk_none
MDBX_chk_init
MDBX_chk_lock
MDBX_chk_meta
MDBX_chk_tree
MDBX_chk_gc
MDBX_chk_space
MDBX_chk_maindb
MDBX_chk_tables
MDBX_chk_conclude
MDBX_chk_unlock
MDBX_chk_finalize

Function Documentation

◆ mdbx_env_chk()

LIBMDBX_API int mdbx_env_chk	(	MDBX_env *	env,
		const MDBX_chk_callbacks_t *	cb,
		MDBX_chk_context_t *	ctx,
		const MDBX_chk_flags_t	flags,
		MDBX_chk_severity_t	verbosity,
		unsigned	timeout_seconds_16dot16 )

Checks the integrity of a database.

Interaction with the application code is implemented through callback functions provided by the application using the 'cb parameter. During such interaction, the application can monitor the verification process, including skipping/filtering the processing of individual elements, as well as implement additional verification of the structure and/or information, taking into account the purpose and semantic significance for an application. For example, an application can check its own indexes and the correctness of database entries. It is for this purpose that the integrity check functionality has been improved for intensive use of callbacks and moved from the mdbx_chk` utility to the main library.

Verification is performed in several stages, starting with initialization and ending with finalization. For more details, see MDBX_chk_stage_t. The application code is notified about the beginning and end of each stage through the corresponding callback functions. For more details, see MDBX_chk_callbacks_t.

Parameters

[in]	env	A pointer to an instance of environment.
[in]	cb	A set of callback functions.
[in,out]	ctx	The context of a database integrity check, where the results of the check will be generated.
[in]	flags	Flags/options for checking database integrity.
[in]	verbosity	The required level of detail of information about the progress and results of the checking.
[in]	timeout_seconds_16dot16	The duration limit for performing the check in 1/65536 fractions of a second, either 0 means no limit.

Returns: A non-zero error value on failure and 0 on success.

◆ mdbx_env_chk_encount_problem()

LIBMDBX_API int mdbx_env_chk_encount_problem ( MDBX_chk_context_t * ctx )

An auxiliary function to account issues detected by an application, including those coming to an application through logging.

An application should call this function to account for detected issues, or vice versa, do not make these calls to ignore discovered issues.

See also: mdbx_env_chk(); MDBX_debug_func

Returns: A non-zero error value on failure and 0 on success.

◆ mdbx_env_open_for_recovery()

LIBMDBX_API int mdbx_env_open_for_recovery	(	MDBX_env *	env,
		const char *	pathname,
		unsigned	target_meta,
		bool	writeable )

Open an environment instance using specific meta-page for checking and recovery.

This function mostly of internal API for mdbx_chk utility and subject to change at any time. Do not use this function to avoid shooting your own leg(s).

Note: On Windows the mdbx_env_open_for_recoveryW() is recommended to use.

◆ mdbx_env_turn_for_recovery()

LIBMDBX_API int mdbx_env_turn_for_recovery	(	MDBX_env *	env,
		unsigned	target_meta )

Turn database to the specified meta-page.