Modules
	Error handling

	Opening & Closing

	Transactions

	Databases

	Create/Read/Update/Delete (see Quick Reference in details)

	Cursors

	Statistics & Information

	Settings

	Logging and runtime debug

	Range query estimation

	Extra operations

	Value-to-Key functions
	Value-to-Key functions to avoid using custom comparators.

	Key-to-Value functions
	Key-to-Value functions to avoid using custom comparators.

	B-tree Traversal
	This is internal API for mdbx_chk tool. You should avoid to use it, except some extremal special cases.

	Attribute support functions for Nexenta

Classes
struct	MDBX_version_info
	libmdbx version information More...

struct	MDBX_build_info
	libmdbx build information More...

struct	MDBX_stat
	Statistics for a database in the environment. More...

struct	MDBX_envinfo
	Information about the environment. More...

struct	MDBX_txn_info
	Information about the transaction. More...

struct	MDBX_commit_latency
	Latency of commit stages in 1/65536 of seconds units. More...

struct	MDBX_canary
	The fours integers markers (aka "canary") associated with the environment. More...

Macros
#define	HAVE_STRUCT_IOVEC 1

#define	MDBX_VERSION_MAJOR 0

#define	MDBX_VERSION_MINOR 11

#define	LIBMDBX_API

#define	LIBMDBX_API_TYPE

#define	LIBMDBX_VERINFO_API __dll_export

#define	MDBX_LOCKNAME "/mdbx.lck"
	The name of the lock file in the environment. More...

#define	MDBX_DATANAME "/mdbx.dat"
	The name of the data file in the environment. More...

#define	MDBX_LOCK_SUFFIX "-lck"
	The suffix of the lock file when MDBX_NOSUBDIR is used. More...

#define	MDBX_MAP_RESIZED MDBX_MAP_RESIZED_is_deprecated()

Typedefs
typedef int	mdbx_filehandle_t

typedef pid_t	mdbx_pid_t

typedef pthread_t	mdbx_tid_t

typedef mode_t	mdbx_mode_t

typedef struct MDBX_env	MDBX_env
	Opaque structure for a database environment. More...

typedef struct iovec	MDBX_val
	Generic structure used for passing keys and data in and out of the database. More...

typedef enum MDBX_txn_flags_t	MDBX_txn_flags_t

typedef int(*	MDBX_preserve_func) (void context, MDBX_val target, const void *src, size_t bytes)

Enumerations
enum	MDBX_constants { MDBX_MAX_DBI = UINT32_C(32765), MDBX_MAXDATASIZE = UINT32_C(0x7fff0000), MDBX_MIN_PAGESIZE = 256, MDBX_MAX_PAGESIZE = 65536 }

enum	MDBX_option_t { MDBX_opt_max_db, MDBX_opt_max_readers, MDBX_opt_sync_bytes, MDBX_opt_sync_period, MDBX_opt_rp_augment_limit, MDBX_opt_loose_limit, MDBX_opt_dp_reserve_limit, MDBX_opt_txn_dp_limit, MDBX_opt_txn_dp_initial, MDBX_opt_spill_max_denominator, MDBX_opt_spill_min_denominator, MDBX_opt_spill_parent4child_denominator, MDBX_opt_merge_threshold_16dot16_percent }
	MDBX environment options. More...

Functions
MDBX_NOTHROW_PURE_FUNCTION const LIBMDBX_API char *	mdbx_liberr2str (int errnum)

LIBMDBX_API int	mdbx_replace_ex (MDBX_txn txn, MDBX_dbi dbi, const MDBX_val key, MDBX_val new_data, MDBX_val old_data, MDBX_put_flags_t flags, MDBX_preserve_func preserver, void *preserver_context)

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_hsr_func *	mdbx_env_get_hsr (const MDBX_env *env)
	Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled. More...

Variables
LIBMDBX_VERINFO_API const struct MDBX_version_info	mdbx_version
	libmdbx version information More...

LIBMDBX_VERINFO_API const struct MDBX_build_info	mdbx_build
	libmdbx build information More...

Detailed Description

Macro Definition Documentation

◆ HAVE_STRUCT_IOVEC

#define HAVE_STRUCT_IOVEC 1

◆ LIBMDBX_API

#define LIBMDBX_API

◆ LIBMDBX_API_TYPE

#define LIBMDBX_API_TYPE

◆ LIBMDBX_VERINFO_API

#define LIBMDBX_VERINFO_API __dll_export

◆ MDBX_DATANAME

#define MDBX_DATANAME "/mdbx.dat"

The name of the data file in the environment.

◆ MDBX_LOCK_SUFFIX

#define MDBX_LOCK_SUFFIX "-lck"

The suffix of the lock file when MDBX_NOSUBDIR is used.

◆ MDBX_LOCKNAME

#define MDBX_LOCKNAME "/mdbx.lck"

The name of the lock file in the environment.

◆ MDBX_MAP_RESIZED

#define MDBX_MAP_RESIZED MDBX_MAP_RESIZED_is_deprecated()

◆ MDBX_VERSION_MAJOR

#define MDBX_VERSION_MAJOR 0

◆ MDBX_VERSION_MINOR

#define MDBX_VERSION_MINOR 11

Typedef Documentation

◆ MDBX_env

typedef struct MDBX_env MDBX_env

Opaque structure for a database environment.

An environment supports multiple key-value sub-databases (aka key-value spaces or tables), all residing in the same shared-memory map.

See also: mdbx_env_create(); mdbx_env_close()

◆ mdbx_filehandle_t

typedef int mdbx_filehandle_t

◆ mdbx_mode_t

typedef mode_t mdbx_mode_t

◆ mdbx_pid_t

typedef pid_t mdbx_pid_t

◆ MDBX_preserve_func

typedef int(* MDBX_preserve_func) (void *context, MDBX_val *target, const void *src, size_t bytes)

◆ mdbx_tid_t

typedef pthread_t mdbx_tid_t

◆ MDBX_txn_flags_t

typedef enum MDBX_txn_flags_t MDBX_txn_flags_t

◆ MDBX_val

typedef struct iovec MDBX_val

Generic structure used for passing keys and data in and out of the database.

See also: mdbx::slice; mdbx::buffer

Values returned from the database are valid only until a subsequent update operation, or the end of the transaction. Do not modify or free them, they commonly point into the database itself.

Key sizes must be between 0 and mdbx_env_get_maxkeysize() inclusive. The same applies to data sizes in databases with the MDBX_DUPSORT flag. Other data items can in theory be from 0 to MDBX_MAXDATASIZE bytes long.

Note: The notable difference between MDBX and LMDB is that MDBX support zero length keys.

Enumeration Type Documentation

◆ MDBX_constants

enum MDBX_constants

Enumerator
MDBX_MAX_DBI	The hard limit for DBI handles
MDBX_MAXDATASIZE	The maximum size of a data item.
MDBX_MIN_PAGESIZE	The minimal database page size in bytes.
MDBX_MAX_PAGESIZE	The maximal database page size in bytes.

◆ MDBX_option_t

enum MDBX_option_t

MDBX environment options.

Enumerator
MDBX_opt_max_db	Controls the maximum number of named databases for the environment. By default only unnamed key-value database could used and appropriate value should set by `MDBX_opt_max_db` to using any more named subDB(s). To reduce overhead, use the minimum sufficient value. This option may only set after mdbx_env_create() and before mdbx_env_open(). See also mdbx_env_set_maxdbs() mdbx_env_get_maxdbs()
MDBX_opt_max_readers	Defines the maximum number of threads/reader slots for all processes interacting with the database. This defines the number of slots in the lock table that is used to track readers in the the environment. The default is about 100 for 4K system page size. Starting a read-only transaction normally ties a lock table slot to the current thread until the environment closes or the thread exits. If MDBX_NOTLS is in use, mdbx_txn_begin() instead ties the slot to the MDBX_txn object until it or the MDBX_env object is destroyed. This option may only set after mdbx_env_create() and before mdbx_env_open(), and has an effect only when the database is opened by the first process interacts with the database. See also mdbx_env_set_maxreaders() mdbx_env_get_maxreaders()
MDBX_opt_sync_bytes	Controls interprocess/shared threshold to force flush the data buffers to disk, if MDBX_SAFE_NOSYNC is used. See also mdbx_env_set_syncbytes() mdbx_env_get_syncbytes()
MDBX_opt_sync_period	Controls interprocess/shared relative period since the last unsteady commit to force flush the data buffers to disk, if MDBX_SAFE_NOSYNC is used. See also mdbx_env_set_syncperiod() mdbx_env_get_syncperiod()
MDBX_opt_rp_augment_limit	Controls the in-process limit to grow a list of reclaimed/recycled page's numbers for finding a sequence of contiguous pages for large data items. A long values requires allocation of contiguous database pages. To find such sequences, it may be necessary to accumulate very large lists, especially when placing very long values (more than a megabyte) in a large databases (several tens of gigabytes), which is much expensive in extreme cases. This threshold allows you to avoid such costs by allocating new pages at the end of the database (with its possible growth on disk), instead of further accumulating/reclaiming Garbage Collection records. On the other hand, too small threshold will lead to unreasonable database growth, or/and to the inability of put long values. The `MDBX_opt_rp_augment_limit` controls described limit for the current process. Default is 262144, it is usually enough for most cases.
MDBX_opt_loose_limit	Controls the in-process limit to grow a cache of dirty pages for reuse in the current transaction. A 'dirty page' refers to a page that has been updated in memory only, the changes to a dirty page are not yet stored on disk. To reduce overhead, it is reasonable to release not all such pages immediately, but to leave some ones in cache for reuse in the current transaction. The `MDBX_opt_loose_limit` allows you to set a limit for such cache inside the current process. Should be in the range 0..255, default is 64.
MDBX_opt_dp_reserve_limit	Controls the in-process limit of a pre-allocated memory items for dirty pages. A 'dirty page' refers to a page that has been updated in memory only, the changes to a dirty page are not yet stored on disk. Without MDBX_WRITEMAP dirty pages are allocated from memory and released when a transaction is committed. To reduce overhead, it is reasonable to release not all ones, but to leave some allocations in reserve for reuse in the next transaction(s). The `MDBX_opt_dp_reserve_limit` allows you to set a limit for such reserve inside the current process. Default is 1024.
MDBX_opt_txn_dp_limit	Controls the in-process limit of dirty pages for a write transaction. A 'dirty page' refers to a page that has been updated in memory only, the changes to a dirty page are not yet stored on disk. Without MDBX_WRITEMAP dirty pages are allocated from memory and will be busy until are written to disk. Therefore for a large transactions is reasonable to limit dirty pages collecting above an some threshold but spill to disk instead. The `MDBX_opt_txn_dp_limit` controls described threshold for the current process. Default is 65536, it is usually enough for most cases.
MDBX_opt_txn_dp_initial	Controls the in-process initial allocation size for dirty pages list of a write transaction. Default is 1024.
MDBX_opt_spill_max_denominator	Controls the in-process how maximal part of the dirty pages may be spilled when necessary. The `MDBX_opt_spill_max_denominator` defines the denominator for limiting from the top for part of the current dirty pages may be spilled when the free room for a new dirty pages (i.e. distance to the `MDBX_opt_txn_dp_limit` threshold) is not enough to perform requested operation. Exactly `max_pages_to_spill = dirty_pages - dirty_pages / N`, where `N` is the value set by `MDBX_opt_spill_max_denominator`. Should be in the range 0..255, where zero means no limit, i.e. all dirty pages could be spilled. Default is 8, i.e. no more than 7/8 of the current dirty pages may be spilled when reached the condition described above.
MDBX_opt_spill_min_denominator	Controls the in-process how minimal part of the dirty pages should be spilled when necessary. The `MDBX_opt_spill_min_denominator` defines the denominator for limiting from the bottom for part of the current dirty pages should be spilled when the free room for a new dirty pages (i.e. distance to the `MDBX_opt_txn_dp_limit` threshold) is not enough to perform requested operation. Exactly `min_pages_to_spill = dirty_pages / N`, where `N` is the value set by `MDBX_opt_spill_min_denominator`. Should be in the range 0..255, where zero means no restriction at the bottom. Default is 8, i.e. at least the 1/8 of the current dirty pages should be spilled when reached the condition described above.
MDBX_opt_spill_parent4child_denominator	Controls the in-process how much of the parent transaction dirty pages will be spilled while start each child transaction. The `MDBX_opt_spill_parent4child_denominator` defines the denominator to determine how much of parent transaction dirty pages will be spilled explicitly while start each child transaction. Exactly `pages_to_spill = dirty_pages / N`, where `N` is the value set by `MDBX_opt_spill_parent4child_denominator`. For a stack of nested transactions each dirty page could be spilled only once, and parent's dirty pages couldn't be spilled while child transaction(s) are running. Therefore a child transaction could reach MDBX_TXN_FULL when parent(s) transaction has spilled too less (and child reach the limit of dirty pages), either when parent(s) has spilled too more (since child can't spill already spilled pages). So there is no universal golden ratio. Should be in the range 0..255, where zero means no explicit spilling will be performed during starting nested transactions. Default is 0, i.e. by default no spilling performed during starting nested transactions, that correspond historically behaviour.
MDBX_opt_merge_threshold_16dot16_percent	Controls the in-process threshold of semi-empty pages merge. Warning This is experimental option and subject for change or removal. This option controls the in-process threshold of minimum page fill, as used space of percentage of a page. Neighbour pages emptier than this value are candidates for merging. The threshold value is specified in 1/65536 of percent, which is equivalent to the 16-dot-16 fixed point format. The specified value must be in the range from 12.5% (almost empty) to 50% (half empty) which corresponds to the range from 8192 and to 32768 in units respectively.

Function Documentation

◆ mdbx_env_get_hsr()

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API MDBX_hsr_func* mdbx_env_get_hsr ( const MDBX_env * env )

Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled.

See also: MDBX_hsr_func; mdbx_env_set_hsr(); Long-lived read transactions

Parameters

[in] env An environment handle returned by mdbx_env_create().

Returns: A MDBX_hsr_func function or NULL if disabled or something wrong.

◆ mdbx_liberr2str()

MDBX_NOTHROW_PURE_FUNCTION const LIBMDBX_API char* mdbx_liberr2str ( int errnum )

◆ mdbx_replace_ex()

LIBMDBX_API int mdbx_replace_ex	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const MDBX_val *	key,
		MDBX_val *	new_data,
		MDBX_val *	old_data,
		MDBX_put_flags_t	flags,
		MDBX_preserve_func	preserver,
		void *	preserver_context
	)

Variable Documentation

◆ mdbx_build

LIBMDBX_VERINFO_API const struct MDBX_build_info mdbx_build

libmdbx build information

◆ mdbx_version

LIBMDBX_VERINFO_API const struct MDBX_version_info mdbx_version

libmdbx version information

Modules

Classes

Macros

Typedefs

Enumerations

Functions

Variables