Group c_extra

Modules

Type	Name
module	Checking and Recovery

Classes

Type	Name
struct	MDBX_chk_callbacks_t A set of callback functions used for checking the integrity of a database.
struct	MDBX_chk_context_t The context for checking the integrity of a database.
struct	MDBX_chk_context_t.result
struct	MDBX_chk_histogram A histogram with some statistical information collected during a database integrity check.
struct	MDBX_chk_histogram.ranges
struct	MDBX_chk_issue_t An issue was discovered during a database integrity check.
struct	MDBX_chk_line_t A virtual row of the report generated during a database integrity check.
struct	MDBX_chk_scope_t A hierarchical context during a database integrity check.
struct	MDBX_chk_table_t Information about a certain key-value table during a database integrity check.
struct	MDBX_chk_table_t.histogram
struct	MDBX_chk_table_t.pages
struct	MDBX_defrag_result_t The numerical metrics of progress and result of database defragmentation.

Public Types

Type	Name
enum	MDBX_chk_flags_t Flags/options for checking the integrity of a database.
union	MDBX_chk_scope_t.usr_o
union	MDBX_chk_scope_t.usr_v
union	MDBX_chk_scope_t.usr_z
enum	MDBX_chk_severity_t Levels of logging/detailing of information supplied via callbacks during a database integrity check.
enum	MDBX_chk_stage_t The verification stages reported via callbacks during a database integrity check.
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.
enum	MDBX_copy_flags_t Environment copy flags.
typedef int(*	MDBX_defrag_notify_func A callback function to notify an application about the progress of defragmentation.
enum	MDBX_defrag_stopping_reasons_t The returned reasons for stopping database defragmentation.
enum	MDBX_env_delete_mode_t Deletion modes for mdbx_env_delete() .

Public Functions

Type	Name
LIBMDBX_API int	mdbx_cursor_ignord (MDBX_cursor * cursor) An auxiliary function for use in tools.
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 int	mdbx_env_copy (MDBX_env * env, const char * dest, MDBX_copy_flags_t flags) Copy an MDBX environment to the specified path, with options.
LIBMDBX_API int	mdbx_env_copy2fd (MDBX_env * env, mdbx_filehandle_t fd, MDBX_copy_flags_t flags) Copy an environment to the specified file descriptor, with options.
LIBMDBX_API int	mdbx_env_copyW (MDBX_env * env, const wchar_t * dest, MDBX_copy_flags_t flags) Copy an MDBX environment to the specified path, with options.
LIBMDBX_API int	mdbx_env_defrag (MDBX_env * env, size_t defrag_atleast, size_t time_atleast_dot16, size_t defrag_enough, size_t time_limit_dot16, intptr_t acceptable_backlash, intptr_t preferred_batch, MDBX_defrag_notify_func progress_callback, void * ctx, MDBX_defrag_result_t * result) Performs database defragmentation.
LIBMDBX_API int	mdbx_env_delete (const char * pathname, MDBX_env_delete_mode_t mode) Delete the environment's files in a proper and multiprocess-safe way.
LIBMDBX_API int	mdbx_env_deleteW (const wchar_t * pathname, MDBX_env_delete_mode_t mode) Delete the environment's files in a proper and multiprocess-safe way.
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_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.
LIBMDBX_API int	mdbx_env_resurrect_after_fork (MDBX_env * env) Restores an instance of the environment in a child process after forking the parent process using `fork()` or similar system calls.
int	mdbx_env_sync (MDBX_env * env) The shortcut to calling mdbx_env_sync_ex() with the`force=true` and`nonblock=false` arguments.
LIBMDBX_API int	mdbx_env_sync_ex (MDBX_env * env, bool force, bool nonblock) Flush the environment data buffers to disk.
int	mdbx_env_sync_poll (MDBX_env * env) The shortcut to calling mdbx_env_sync_ex() with the`force=false` and`nonblock=true` arguments.
LIBMDBX_API MDBX_cmp_func	mdbx_get_datacmp (MDBX_db_flags_t flags) Returns default internal data's comparator for given table flags.
LIBMDBX_API MDBX_cmp_func	mdbx_get_keycmp (MDBX_db_flags_t flags) Returns default internal key's comparator for given table flags.
LIBMDBX_API int	mdbx_is_readahead_reasonable (size_t volume, intptr_t redundancy) Find out whether to use readahead or not, based on the given database size and the amount of available memory.
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.
LIBMDBX_API int	mdbx_reader_check (MDBX_env * env, int * dead) Check for stale entries in the reader lock table.
LIBMDBX_API int	mdbx_thread_register (const MDBX_env * env) Registers the current thread as a reader for the environment.
LIBMDBX_API int	mdbx_thread_unregister (const MDBX_env * env) Unregisters the current thread as a reader for the environment.
LIBMDBX_API int	mdbx_txn_copy2fd (MDBX_txn * txn, mdbx_filehandle_t fd, MDBX_copy_flags_t flags) Copy an environment by given read transaction to the specified file descriptor, with options.
LIBMDBX_API int	mdbx_txn_copy2pathname (MDBX_txn * txn, const char * dest, MDBX_copy_flags_t flags) Copy an MDBX environment by given read transaction to the specified path, with options.
LIBMDBX_API int	mdbx_txn_copy2pathnameW (MDBX_txn * txn, const wchar_t * dest, MDBX_copy_flags_t flags) Copy an MDBX environment by given read transaction to the specified path, with options.
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.

Public Types Documentation

enum MDBX_chk_flags_t

Flags/options for checking the integrity of a database.

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
};

Note:

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

See also: mdbx_env_chk()

union MDBX_chk_scope_t.usr_o

union MDBX_chk_scope_t.usr_v

union MDBX_chk_scope_t.usr_z

enum MDBX_chk_severity_t

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

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
};

See also: mdbx_env_chk()

enum MDBX_chk_stage_t

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

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
};

See also: mdbx_env_chk()

typedef 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.

typedef struct MDBX_chk_user_table_cookie MDBX_chk_user_table_cookie_t;

See also: mdbx_env_chk()

enum MDBX_copy_flags_t

Environment copy flags.

enum MDBX_copy_flags_t {
    MDBX_CP_DEFAULTS = 0,
    MDBX_CP_COMPACT = 1u,
    MDBX_CP_FORCE_DYNAMIC_SIZE = 2u,
    MDBX_CP_DONT_FLUSH = 4u,
    MDBX_CP_THROTTLE_MVCC = 8u,
    MDBX_CP_DISPOSE_TXN = 16u,
    MDBX_CP_RENEW_TXN = 32u,
    MDBX_CP_OVERWRITE = 64u
};

See also: mdbx_env_copy()

See also: mdbx_env_copy2fd()

See also: mdbx_txn_copy2pathname()

typedef MDBX_defrag_notify_func

A callback function to notify an application about the progress of defragmentation.

typedef int(* MDBX_defrag_notify_func) (void *ctx, const MDBX_defrag_result_t *progress) noexcept;

See also: mdbx_env_defrag() If provided such callback will be called time-to-time to notify about the progress of defragmentation. The rate of such notification calls is not explicitly defined, but it is guaranteed that it will be called at the beginning and end of each defragmentation cycle, as well as often will be enough to track progress in a percentages sharp.

Parameters:

ctx A pointer to the context passed by a similar parameter in mdbx_env_defrag().
progress A pointer to the MDBX_defrag_result_t structure filled in to reflects the current state of database defragmentation.

Returns:

A signed integer value that allows you to control the continuation of defragmentation:

Return value:

0 To continue defragmentation.
-1 To abort defragmentation immediately, see MDBX_defrag_aborted.
1 To discontinue defragmentation with completion scheduled operations, see MDBX_defrag_discontinued.

enum MDBX_defrag_stopping_reasons_t

The returned reasons for stopping database defragmentation.

enum MDBX_defrag_stopping_reasons_t {
    MDBX_defrag_noobstacles = 0,
    MDBX_defrag_step_size = 1,
    MDBX_defrag_large_chunk = 2,
    MDBX_defrag_discontinued = 4,
    MDBX_defrag_laggard_reader = 8,
    MDBX_defrag_enough_threshold = 16,
    MDBX_defrag_time_limit = 32,
    MDBX_defrag_aborted = 64,
    MDBX_defrag_error = 128
};

Any number of individual values could be OR'ed together while returning actual set of reasons.

See also: MDBX_defrag_result_t

See also: mdbx_env_defrag()

enum MDBX_env_delete_mode_t

Deletion modes for mdbx_env_delete() .

enum MDBX_env_delete_mode_t {
    MDBX_ENV_JUST_DELETE = 0,
    MDBX_ENV_ENSURE_UNUSED = 1,
    MDBX_ENV_WAIT_FOR_UNUSED = 2
};

See also: mdbx_env_delete()

Public Functions Documentation

function mdbx_cursor_ignord

An auxiliary function for use in tools.

LIBMDBX_API int mdbx_cursor_ignord (
    MDBX_cursor * cursor
)

When using user-defined comparison functions, checking the order of keys or values will lead to incorrect results and return the error MDBX_CORRUPTED.

This function disables the control of the order of keys when reading database pages for this cursor, and thus allows to access data in the absence/unavailability of the comparison functions used.

See also: avoid_custom_comparators

Returns:

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

function mdbx_env_chk

Checks the integrity of a database.

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
)

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:

env A pointer to an instance of environment.
cb A set of callback functions.
ctx The context of a database integrity check, where the results of the check will be generated.
flags Flags/options for checking database integrity.
verbosity The required level of detail of information about the progress and results of the checking.
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.

function mdbx_env_chk_encount_problem

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

LIBMDBX_API int mdbx_env_chk_encount_problem (
    MDBX_chk_context_t * ctx
)

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()

See also: MDBX_debug_func

Returns:

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

function mdbx_env_copy

Copy an MDBX environment to the specified path, with options.

LIBMDBX_API int mdbx_env_copy (
    MDBX_env * env,
    const char * dest,
    MDBX_copy_flags_t flags
)

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note:

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

Note:

On Windows the mdbx_env_copyW() is recommended to use.

See also: mdbx_env_copy2fd()

See also: mdbx_txn_copy2pathname()

Parameters:

env An environment handle returned by mdbx_env_create(). It must have already been opened successfully.
dest The pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
flags Specifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:
MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizable copy, i.e. dynamic size instead of fixed.
MDBX_CP_DONT_FLUSH Don't explicitly flush the written data to an output media to reduce the time of the operation and the duration of the transaction.
MDBX_CP_THROTTLE_MVCC Use read transaction parking during copying MVCC-snapshot to avoid stopping recycling and overflowing the database. This allows the writing transaction to oust the read transaction used to copy the database if copying takes so long that it will interfere with the recycling old MVCC snapshots and may lead to an overflow of the database. However, if the reading transaction is ousted the copy will be aborted until successful completion. Thus, this option allows copy the database without interfering with write transactions and a threat of database overflow, but at the cost that copying will be aborted to prevent such conditions.

See also: mdbx_txn_park()

Returns:

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

function mdbx_env_copy2fd

Copy an environment to the specified file descriptor, with options.

LIBMDBX_API int mdbx_env_copy2fd (
    MDBX_env * env,
    mdbx_filehandle_t fd,
    MDBX_copy_flags_t flags
)

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

See also: mdbx_env_copy()

See also: mdbx_txn_copy2fd()

Note:

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

Note:

Fails if the environment has suffered a page leak and the destination file descriptor is associated with a pipe, socket, or FIFO.

Parameters:

env An environment handle returned by mdbx_env_create(). It must have already been opened successfully.
fd The file descriptor to write the copy to. It must have already been opened for Write access.
flags Special options for this operation.

See also: mdbx_env_copy()

Returns:

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

function mdbx_env_copyW

Copy an MDBX environment to the specified path, with options.

LIBMDBX_API int mdbx_env_copyW (
    MDBX_env * env,
    const wchar_t * dest,
    MDBX_copy_flags_t flags
)

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note:

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

Note:

On Windows the mdbx_env_copyW() is recommended to use.

See also: mdbx_env_copy2fd()

See also: mdbx_txn_copy2pathname()

Parameters:

env An environment handle returned by mdbx_env_create(). It must have already been opened successfully.
dest The pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
flags Specifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:
MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizable copy, i.e. dynamic size instead of fixed.
MDBX_CP_DONT_FLUSH Don't explicitly flush the written data to an output media to reduce the time of the operation and the duration of the transaction.
MDBX_CP_THROTTLE_MVCC Use read transaction parking during copying MVCC-snapshot to avoid stopping recycling and overflowing the database. This allows the writing transaction to oust the read transaction used to copy the database if copying takes so long that it will interfere with the recycling old MVCC snapshots and may lead to an overflow of the database. However, if the reading transaction is ousted the copy will be aborted until successful completion. Thus, this option allows copy the database without interfering with write transactions and a threat of database overflow, but at the cost that copying will be aborted to prevent such conditions.

See also: mdbx_txn_park()

Returns:

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

Note:

Available only on Windows.

See also: mdbx_env_copy()

function mdbx_env_defrag

Performs database defragmentation.

LIBMDBX_API int mdbx_env_defrag (
    MDBX_env * env,
    size_t defrag_atleast,
    size_t time_atleast_dot16,
    size_t defrag_enough,
    size_t time_limit_dot16,
    intptr_t acceptable_backlash,
    intptr_t preferred_batch,
    MDBX_defrag_notify_func progress_callback,
    void * ctx,
    MDBX_defrag_result_t * result
)

See also: MDBX_defrag_notify_func

See also: MDBX_defrag_result_t Defragmentation is the transfer of data from pages located at the end of the database to free pages closer to the beginning. After that, the pages that have become unused at the end of the database can be cut off while reducing the size of the database file. This function performs all the described actions in comply with ACID, trying to minimize the number of operations for moving data and writing to media.

The function accepts an extended set of parameters that allow you to fully control the goals and progress of defragmentation, including as to quickly get a minimum result by small steps and as to perform a fairly complete defragmentation in the least number of large cycles.

Note:

Any parallel reading transactions do not make defragmentation impossible, but ones limit it to single cycle and will definitely disallow to be performed completely.

During the movement of data in the b-tree structure, it is necessary to adjust the links in the parent pages to the new moved child pages. According to the MVCC concept, this requires creating copies of altered parent pages along the entire chain from leaves to the root of the b-tree, inclusive. In addition, to move large/overflow pages, it may be necessary to form sequences of adjacent free pages, which will require moving other pages with data and correcting links to ones. Defragmentation almost always cannot be completely completed in one pass, as there are always fewer free pages than necessary to move due to the need to copy all the parent pages. In addition, if there are not enough sequences to move large/overflow pages, an additional commit step is required and a new transaction is started to continue.

Thus, defragmentation is almost always performed in several cycles, each of which ends with the transaction being committed and can be interrupted in any way while ensuring the durability of the database specified when it was opened.

Parameters:

env A pointer to an instance of environment.
defrag_atleast The required at least number of pages by which the database must be reduced as a result of defragmentation. Defragmentation will not be completed and its goals will not be considered achieved until the database is shrinked by the specified amount. Must be less or equal to defrag_enough. Specify zero if in doubt or not known, this will mean no lower bound.
time_atleast_dot16 The time by a wall clock in 1/65536 unit of second that should be spent to defragment more, even if the goals given via other parameters have already been reached. Must be less or equal to time_limit_16dot16. Specify zero if in doubt or not known, this will mean no lower bound.
defrag_enough The number of pages by which it will be enough to shrink the database during a defragmentation process to finish it rather than dig more. Must be greater or equal to defrag_atleast. Specify zero if in doubt or not known, this will mean no limit.
time_limit_dot16 The time limit by a wall clock in 1/65536 unit of second that could be spent to defragment. When the specified limit is reached, defragmentation will not continue, but the stage of writing the moved pages that has already begun will be completed. Must be greater or equal to time_atleast_dot16. Specify zero if in doubt or not known, this will mean no limit.
acceptable_backlash Defragmentation stops if a next cycle will unable to shrink database by the number of pages more than the specified value. This avoids the last few defragmentation cycles, which do not significantly reduce the size of the database. Specify -1 if in doubt or not known, this will mean autopilot.
preferred_batch The preferred maximum number of pages to be moved per defragmentation cycle. Small batches take less time, so if necessary, defragmentation could be stopped faster without losing the intermediate result. On the other hand, smaller batches will require more transaction commits and more page rewrites to achieve a similar result. Specify 0 if in doubt or not known, this will mean no limit.
progress_callback An optional custom progress notification callback function with the signature MDBX_defrag_notify_func, which will be called time-to-time to notify about the progress of defragmentation. The rate of calls to the provided function is not explicitly defined, but it is guaranteed that it will be called at the beginning and end of each defragmentation cycle, as well as often enough to track progress. Specify nullptr if in doubt or not known, this will mean unused.
ctx An optional pointer to some context that will be passed to the progress_callback() function as it is. Specify nullptr if in doubt or not known, this will mean unused.
result An optional address of a MDBX_defrag_result_t structure where the information of defragmentation results will be provided. Specify nullptr if in doubt or not known, this will mean a result is not needed.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_EINVAL An invalid parameter was specified.
MDBX_LAGGARD_READER One or more readers use old MVCC-snapshots of data and thus do not allow defragmentation to be completed.
MDBX_RESULT_TRUE It was not possible to complete defragmentation or achieve the goals specified by the parameters due to the given limits or other obstacles, that can be knew from the MDBX_defrag_result_t structure.

function mdbx_env_delete

Delete the environment's files in a proper and multiprocess-safe way.

LIBMDBX_API int mdbx_env_delete (
    const char * pathname,
    MDBX_env_delete_mode_t mode
)

Note:

On Windows the mdbx_env_deleteW() is recommended to use.

Parameters:

pathname The pathname for the database or the directory in which the database files reside.
mode Specifies deletion mode for the environment. This parameter must be set to one of the constants described above in the MDBX_env_delete_mode_t section.

Note:

The MDBX_ENV_JUST_DELETE don't supported on Windows since system unable to delete a memory-mapped files.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_RESULT_TRUE No corresponding files or directories were found, so no deletion was performed.

function mdbx_env_deleteW

Delete the environment's files in a proper and multiprocess-safe way.

LIBMDBX_API int mdbx_env_deleteW (
    const wchar_t * pathname,
    MDBX_env_delete_mode_t mode
)

Note:

On Windows the mdbx_env_deleteW() is recommended to use.

Parameters:

pathname The pathname for the database or the directory in which the database files reside.
mode Specifies deletion mode for the environment. This parameter must be set to one of the constants described above in the MDBX_env_delete_mode_t section.

Note:

The MDBX_ENV_JUST_DELETE don't supported on Windows since system unable to delete a memory-mapped files.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_RESULT_TRUE No corresponding files or directories were found, so no deletion was performed.

Note:

Available only on Windows.

See also: mdbx_env_delete()

function mdbx_env_open_for_recovery

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

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

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.

function mdbx_env_open_for_recoveryW

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

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

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.

Note:

Available only on Windows.

See also: mdbx_env_open_for_recovery()

function mdbx_env_resurrect_after_fork

Restores an instance of the environment in a child process after forking the parent process using fork() or similar system calls.

LIBMDBX_API int mdbx_env_resurrect_after_fork (
    MDBX_env * env
)

Without calling mdbx_env_resurrect_after_fork(), it is not possible to use an open instance of the environment in a child process, including all transactions running at the moment of forking.

The actions performed by the function can be considered as reopening the database in a child process, while preserving the set options and addresses of already created instances of most objects accesible via the API.

Note:

This function is not available in the Windows OS family due to the lack of process forking functionality in the operating system API.

Forking does not affect the state of the MDBX environment in the parent process. All transactions that were in the parent process at the moment of forking will continue to be performed without interference after forking in the parent process. However, in a child process, all relevant transactions are no longer valid, and an attempt to use ones will result in an error being returned or sending the SIGSEGV signal by the OS kernel.

Using an instance of the environment in a child process is not possible until calling mdbx_env_resurrect_after_fork(), because as a result of forking, the process's PID changes, the value of which is used to organize collaboration with the database, including to track processes/threads performing reading transactions related to the corresponding MVCC-snapshots. All transactions active at the moment of forking cannot continue in the child process, as ones do not own any locks or any MVCC-snapshot and do not keep it from being recycled during garbage collection.

The mdbx_env_resurrect_after_fork() function restores the transferred instance of the environment in the child process after forking, namely: updates the system identifiers used, reopens file descriptors, acquires the necessary locks associated with LCK and DXB database files, restores the memory mappings of the database file, reader tables and auxiliary data to memory. However, transactions inherited from the parent process are not restored, and writing and reading transactions are handled differently:

The writing transaction, if there was one at the moment of forking, is aborted in the child process with the release of its associated resources, including all nested transactions.
The reading transactions, if any in the parent process, are logically aborted in the child process, but without releasing resources. Therefore, it is necessary to provide a call to mdbx_txn_abort() for each such reading transaction in the child process, or accept resource leakage until the child process is termitaned.

The reason for not releasing the resources of reading transactions is that historically MDBX does not maintain any general list of reading transaction instances, as this is not required for normal operation, but requires using of atomic operations or additional synchronization objects when creating/destroying instances MDBX_txn.

Calling mdbx_env_resurrect_after_fork() without forking, or not in a child process, or repeated calls do not lead to any actions or changes.

Parameters:

env An instance of the environment created by the mdbx_env_create() function.

Returns:

A non-zero error value on failure and 0 on success, some possible errors are:

Return value:

MDBX_BUSY The database was opened in MDBX_EXCLUSIVE mode.
MDBX_EBADSIGN If the signature of an object instance is corrupted, as well as if mdbx_env_resurrect_after_fork() is called simultaneously from different threads.
MDBX_PANIC A critical error occurred when restoring an instance of the environment, or there was already such an error before calling the function.

function mdbx_env_sync

The shortcut to calling mdbx_env_sync_ex() with theforce=true andnonblock=false arguments.

inline int mdbx_env_sync (
    MDBX_env * env
)

function mdbx_env_sync_ex

Flush the environment data buffers to disk.

LIBMDBX_API int mdbx_env_sync_ex (
    MDBX_env * env,
    bool force,
    bool nonblock
)

Unless the environment was opened with no-sync flags (MDBX_NOMETASYNC, MDBX_SAFE_NOSYNC and MDBX_UTTERLY_NOSYNC), then data is always written and flushed to disk when mdbx_txn_commit() is called. Otherwise mdbx_env_sync() may be called to manually write and flush unsynced data to disk.

Besides, mdbx_env_sync_ex() with argument force=false may be used to provide polling mode for lazy/asynchronous sync in conjunction with mdbx_env_set_syncbytes() and/or mdbx_env_set_syncperiod().

Note:

This call is not valid if the environment was opened with MDBX_RDONLY.

Parameters:

env An environment handle returned by mdbx_env_create()
force If non-zero, force a flush. Otherwise, If force is zero, then will run in polling mode, i.e. it will check the thresholds that were set mdbx_env_set_syncbytes() and/or mdbx_env_set_syncperiod() and perform flush if at least one of the thresholds is reached.
nonblock Don't wait if write transaction is running by other thread.

Returns:

A non-zero error value on failure and MDBX_RESULT_TRUE or 0 on success. The MDBX_RESULT_TRUE means no data pending for flush to disk, and 0 otherwise. Some possible errors are:

Return value:

MDBX_EACCES The environment is read-only.
MDBX_BUSY The environment is used by other thread and nonblock=true.
MDBX_EINVAL An invalid parameter was specified.
MDBX_EIO An error occurred during the flushing/writing data to a storage medium/disk.

function mdbx_env_sync_poll

The shortcut to calling mdbx_env_sync_ex() with theforce=false andnonblock=true arguments.

inline int mdbx_env_sync_poll (
    MDBX_env * env
)

function mdbx_get_datacmp

Returns default internal data's comparator for given table flags.

LIBMDBX_API  MDBX_cmp_func mdbx_get_datacmp (
    MDBX_db_flags_t flags
)

function mdbx_get_keycmp

Returns default internal key's comparator for given table flags.

LIBMDBX_API  MDBX_cmp_func mdbx_get_keycmp (
    MDBX_db_flags_t flags
)

function mdbx_is_readahead_reasonable

Find out whether to use readahead or not, based on the given database size and the amount of available memory.

LIBMDBX_API int mdbx_is_readahead_reasonable (
    size_t volume,
    intptr_t redundancy
)

Parameters:

volume The expected database size in bytes.
redundancy Additional reserve or overload in case of negative value.

Returns:

A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return value:

MDBX_RESULT_TRUE Readahead is reasonable.
MDBX_RESULT_FALSE Readahead is NOT reasonable, i.e. MDBX_NORDAHEAD is useful to open environment by mdbx_env_open().
OTHERWISE the error code.

function mdbx_ratio2digits

An auxiliary function for converting fractions to string of decimal digits without using floating-point operations.

LIBMDBX_API const char * mdbx_ratio2digits (
    uint64_t numerator,
    uint64_t denominator,
    int precision,
    char * buffer,
    size_t buffer_size
)

Note:

The accuracy of the conversion result is limited both by the simplicity of the algorithms and by 64-bit arithmetic.

Returns:

A pointer to the beginning of the string with the result of conversion.

function mdbx_ratio2percents

An auxiliary function for converting fractions to percentage string without using floating-point operations.

LIBMDBX_API const char * mdbx_ratio2percents (
    uint64_t value,
    uint64_t whole,
    char * buffer,
    size_t buffer_size
)

Note:

The accuracy of the conversion result is limited both by the simplicity of the algorithms and by 64-bit arithmetic.

Returns:

A pointer to the beginning of the string with the result of conversion.

function mdbx_reader_check

Check for stale entries in the reader lock table.

LIBMDBX_API int mdbx_reader_check (
    MDBX_env * env,
    int * dead
)

Parameters:

env An environment handle returned by mdbx_env_create().
dead Number of stale slots that were cleared.

Returns:

A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if a dead reader(s) found or mutex was recovered.

function mdbx_thread_register

Registers the current thread as a reader for the environment.

LIBMDBX_API int mdbx_thread_register (
    const MDBX_env * env
)

To perform read operations without blocking, a reader slot must be assigned for each thread. However, this assignment requires a short-term lock acquisition which is performed automatically. This function allows you to assign the reader slot in advance and thus avoid acquiring a lock when the reading transaction starts firstly from the current thread.

See also: mdbx_thread_unregister()

Note:

Threads are registered automatically the first time a read transaction starts. Therefore, there is no need to use this function, except in special cases.

Parameters:

env An environment handle returned by mdbx_env_create().

Returns:

A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if thread is already registered.

function mdbx_thread_unregister

Unregisters the current thread as a reader for the environment.

LIBMDBX_API int mdbx_thread_unregister (
    const MDBX_env * env
)

To perform read operations without blocking, a reader slot must be assigned for each thread. However, the assigned reader slot will remain occupied until the thread ends or the environment closes. This function allows you to explicitly release the assigned reader slot.

See also: mdbx_thread_register()

Parameters:

env An environment handle returned by mdbx_env_create().

Returns:

A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if thread is not registered or already unregistered.

function mdbx_txn_copy2fd

Copy an environment by given read transaction to the specified file descriptor, with options.

LIBMDBX_API int mdbx_txn_copy2fd (
    MDBX_txn * txn,
    mdbx_filehandle_t fd,
    MDBX_copy_flags_t flags
)

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

See also: mdbx_txn_copy2pathname()

See also: mdbx_env_copy2fd()

Note:

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

Note:

Fails if the environment has suffered a page leak and the destination file descriptor is associated with a pipe, socket, or FIFO.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
fd The file descriptor to write the copy to. It must have already been opened for Write access.
flags Special options for this operation.

See also: mdbx_env_copy()

Returns:

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

function mdbx_txn_copy2pathname

Copy an MDBX environment by given read transaction to the specified path, with options.

LIBMDBX_API int mdbx_txn_copy2pathname (
    MDBX_txn * txn,
    const char * dest,
    MDBX_copy_flags_t flags
)

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note:

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

Note:

On Windows the mdbx_txn_copy2pathnameW() is recommended to use.

See also: mdbx_txn_copy2fd()

See also: mdbx_env_copy()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dest The pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
flags Specifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:
MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizable copy, i.e. dynamic size instead of fixed.
MDBX_CP_DONT_FLUSH Don't explicitly flush the written data to an output media to reduce the time of the operation and the duration of the transaction.
MDBX_CP_THROTTLE_MVCC Use read transaction parking during copying MVCC-snapshot to avoid stopping recycling and overflowing the database. This allows the writing transaction to oust the read transaction used to copy the database if copying takes so long that it will interfere with the recycling old MVCC snapshots and may lead to an overflow of the database. However, if the reading transaction is ousted the copy will be aborted until successful completion. Thus, this option allows copy the database without interfering with write transactions and a threat of database overflow, but at the cost that copying will be aborted to prevent such conditions.

See also: mdbx_txn_park()

Returns:

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

function mdbx_txn_copy2pathnameW

Copy an MDBX environment by given read transaction to the specified path, with options.

LIBMDBX_API int mdbx_txn_copy2pathnameW (
    MDBX_txn * txn,
    const wchar_t * dest,
    MDBX_copy_flags_t flags
)

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note:

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Restrictions & Caveats section.

Note:

On Windows the mdbx_txn_copy2pathnameW() is recommended to use.

See also: mdbx_txn_copy2fd()

See also: mdbx_env_copy()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dest The pathname of a file in which the copy will reside. This file must not be already exist, but parent directory must be writable.
flags Specifies options for this operation. This parameter must be bitwise OR'ing together any of the constants described here:
MDBX_CP_DEFAULTS Perform copy as-is without compaction, etc.
MDBX_CP_COMPACT Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes little bit more CPU for processing, but may running quickly than the default, on account skipping free pages.
MDBX_CP_FORCE_DYNAMIC_SIZE Force to make resizable copy, i.e. dynamic size instead of fixed.
MDBX_CP_DONT_FLUSH Don't explicitly flush the written data to an output media to reduce the time of the operation and the duration of the transaction.
MDBX_CP_THROTTLE_MVCC Use read transaction parking during copying MVCC-snapshot to avoid stopping recycling and overflowing the database. This allows the writing transaction to oust the read transaction used to copy the database if copying takes so long that it will interfere with the recycling old MVCC snapshots and may lead to an overflow of the database. However, if the reading transaction is ousted the copy will be aborted until successful completion. Thus, this option allows copy the database without interfering with write transactions and a threat of database overflow, but at the cost that copying will be aborted to prevent such conditions.

See also: mdbx_txn_park()

Returns:

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

Note:

Available only on Windows.

See also: mdbx_txn_copy2pathname()

function mdbx_txn_lock

Acquires write-transaction lock. Provided for custom and/or complex locking scenarios.

LIBMDBX_API int mdbx_txn_lock (
    MDBX_env * env,
    bool dont_wait
)

Returns:

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

function mdbx_txn_unlock

Releases write-transaction lock. Provided for custom and/or complex locking scenarios.

LIBMDBX_API int mdbx_txn_unlock (
    MDBX_env * env
)

Returns:

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