Classes
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_envinfo.mi_geo

struct	MDBX_envinfo.mi_bootid
	A mostly unique ID that is regenerated on each boot. More...

struct	MDBX_envinfo.mi_bootid.current

struct	MDBX_envinfo.mi_bootid.meta

struct	MDBX_envinfo.mi_pgop_stat

struct	MDBX_commit_latency.gc_prof
	Информация для профилирования работы GC. More...

Typedefs
typedef enum MDBX_dbi_state_t	MDBX_dbi_state_t

typedef int()	MDBX_reader_list_func(void *ctx, int num, int slot, mdbx_pid_t pid, mdbx_tid_t thread, uint64_t txnid, uint64_t lag, size_t bytes_used, size_t bytes_retained) noexcept
	A callback function used to enumerate the reader lock table. More...

Enumerations
enum	MDBX_dbi_state_t { MDBX_DBI_DIRTY = 0x01 , MDBX_DBI_STALE = 0x02 , MDBX_DBI_FRESH = 0x04 , MDBX_DBI_CREAT = 0x08 }
	DBI state bits returted by mdbx_dbi_flags_ex() More...

Functions
LIBMDBX_API int	mdbx_env_stat_ex (const MDBX_env env, const MDBX_txn txn, MDBX_stat *stat, size_t bytes)
	Return statistics about the MDBX environment. More...

int	mdbx_env_stat (const MDBX_env env, MDBX_stat stat, size_t bytes)
	Return statistics about the MDBX environment. More...

LIBMDBX_API int	mdbx_env_info_ex (const MDBX_env env, const MDBX_txn txn, MDBX_envinfo *info, size_t bytes)
	Return information about the MDBX environment. More...

int	mdbx_env_info (const MDBX_env env, MDBX_envinfo info, size_t bytes)
	Return information about the MDBX environment. More...

int	mdbx_env_get_syncbytes (const MDBX_env env, size_t threshold)
	Get threshold to force flush the data buffers to disk, even any of MDBX_SAFE_NOSYNC flag in the environment. More...

int	mdbx_env_get_syncperiod (const MDBX_env env, unsigned period_seconds_16dot16)
	Get relative period since the last unsteady commit to force flush the data buffers to disk, even of MDBX_SAFE_NOSYNC flag in the environment. More...

LIBMDBX_API int	mdbx_env_get_flags (const MDBX_env env, unsigned flags)
	Get environment flags. More...

LIBMDBX_API int	mdbx_env_get_path (const MDBX_env env, const char *dest)
	Return the path that was used in mdbx_env_open(). More...

LIBMDBX_API int	mdbx_env_get_fd (const MDBX_env env, mdbx_filehandle_t fd)
	Return the file descriptor for the given environment. More...

intptr_t	mdbx_limits_pgsize_min (void)
	Returns the minimal database page size in bytes. More...

intptr_t	mdbx_limits_pgsize_max (void)
	Returns the maximal database page size in bytes. More...

LIBMDBX_API intptr_t	mdbx_limits_dbsize_min (intptr_t pagesize)
	Returns minimal database size in bytes for given page size, or -1 if pagesize is invalid. More...

LIBMDBX_API intptr_t	mdbx_limits_dbsize_max (intptr_t pagesize)
	Returns maximal database size in bytes for given page size, or -1 if pagesize is invalid. More...

LIBMDBX_API intptr_t	mdbx_limits_keysize_max (intptr_t pagesize, MDBX_db_flags_t flags)
	Returns maximal key size in bytes for given page size and database flags, or -1 if pagesize is invalid. More...

LIBMDBX_API intptr_t	mdbx_limits_keysize_min (MDBX_db_flags_t flags)
	Returns minimal key size in bytes for given database flags. More...

LIBMDBX_API intptr_t	mdbx_limits_valsize_max (intptr_t pagesize, MDBX_db_flags_t flags)
	Returns maximal data size in bytes for given page size and database flags, or -1 if pagesize is invalid. More...

LIBMDBX_API intptr_t	mdbx_limits_valsize_min (MDBX_db_flags_t flags)
	Returns minimal data size in bytes for given database flags. More...

LIBMDBX_API intptr_t	mdbx_limits_pairsize4page_max (intptr_t pagesize, MDBX_db_flags_t flags)
	Returns maximal size of key-value pair to fit in a single page with the given size and database flags, or -1 if pagesize is invalid. More...

LIBMDBX_API intptr_t	mdbx_limits_valsize4page_max (intptr_t pagesize, MDBX_db_flags_t flags)
	Returns maximal data size in bytes to fit in a leaf-page or single overflow/large-page with the given page size and database flags, or -1 if pagesize is invalid. More...

LIBMDBX_API intptr_t	mdbx_limits_txnsize_max (intptr_t pagesize)
	Returns maximal write transaction size (i.e. limit for summary volume of dirty pages) in bytes for given page size, or -1 if pagesize is invalid. More...

int	mdbx_env_get_maxreaders (const MDBX_env env, unsigned readers)
	Get the maximum number of threads/reader slots for the environment. More...

int	mdbx_env_get_maxdbs (const MDBX_env env, MDBX_dbi dbs)
	Get the maximum number of named databases for the environment. More...

LIBMDBX_API size_t	mdbx_default_pagesize (void)
	Returns the default size of database page for the current system. More...

LIBMDBX_API int	mdbx_get_sysraminfo (intptr_t page_size, intptr_t total_pages, intptr_t *avail_pages)
	Returns basic information about system RAM. This function provides a portable way to get information about available RAM and can be useful in that it returns the same information that libmdbx uses internally to adjust various options and control readahead. More...

LIBMDBX_API int	mdbx_env_get_maxkeysize_ex (const MDBX_env *env, MDBX_db_flags_t flags)
	Returns the maximum size of keys can put. More...

LIBMDBX_API int	mdbx_env_get_maxvalsize_ex (const MDBX_env *env, MDBX_db_flags_t flags)
	Returns the maximum size of data we can put. More...

LIBMDBX_API int	mdbx_env_get_maxkeysize (const MDBX_env *env)

LIBMDBX_API int	mdbx_env_get_pairsize4page_max (const MDBX_env *env, MDBX_db_flags_t flags)
	Returns maximal size of key-value pair to fit in a single page for specified database flags. More...

LIBMDBX_API int	mdbx_env_get_valsize4page_max (const MDBX_env *env, MDBX_db_flags_t flags)
	Returns maximal data size in bytes to fit in a leaf-page or single overflow/large-page for specified database flags. More...

LIBMDBX_API void *	mdbx_env_get_userctx (const MDBX_env *env)
	Returns an application information (a context pointer) associated with the environment. More...

LIBMDBX_API int	mdbx_txn_info (const MDBX_txn txn, MDBX_txn_info info, bool scan_rlt)
	Return information about the MDBX transaction. More...

LIBMDBX_API uint64_t	mdbx_txn_id (const MDBX_txn *txn)
	Return the transaction's ID. More...

LIBMDBX_API int	mdbx_dbi_stat (const MDBX_txn txn, MDBX_dbi dbi, MDBX_stat stat, size_t bytes)
	Retrieve statistics for a database. More...

LIBMDBX_API int	mdbx_dbi_dupsort_depthmask (const MDBX_txn txn, MDBX_dbi dbi, uint32_t mask)
	Retrieve depth (bitmask) information of nested dupsort (multi-value) B+trees for given database. More...

LIBMDBX_API int	mdbx_dbi_flags_ex (const MDBX_txn txn, MDBX_dbi dbi, unsigned flags, unsigned *state)
	Retrieve the DB flags and status for a database handle. More...

int	mdbx_dbi_flags (const MDBX_txn txn, MDBX_dbi dbi, unsigned flags)
	The shortcut to calling mdbx_dbi_flags_ex() with `state=NULL` for discarding it result. More...

LIBMDBX_API int	mdbx_is_dirty (const MDBX_txn txn, const void ptr)
	Determines whether the given address is on a dirty database page of the transaction or not. More...

LIBMDBX_API int	mdbx_reader_list (const MDBX_env env, MDBX_reader_list_func func, void *ctx)
	Enumerate the entries in the reader lock table. More...

LIBMDBX_API int	mdbx_txn_straggler (const MDBX_txn txn, int percent)
	Returns a lag of the reading for the given transaction. More...

Detailed Description

Class Documentation

◆ MDBX_stat

struct MDBX_stat

Statistics for a database in the environment.

See also: mdbx_env_stat_ex(); mdbx_dbi_stat()

Class Members
uint64_t	ms_branch_pages	Number of internal (non-leaf) pages
uint32_t	ms_depth	Depth (height) of the B-tree
uint64_t	ms_entries	Number of data items
uint64_t	ms_leaf_pages	Number of leaf pages
uint64_t	ms_mod_txnid	Transaction ID of committed last modification
uint64_t	ms_overflow_pages	Number of overflow pages
uint32_t	ms_psize	Size of a database page. This is the same for all databases.

◆ MDBX_envinfo

struct MDBX_envinfo

Information about the environment.

See also: mdbx_env_info_ex()

Class Members
uint32_t	mi_autosync_period_seconds16dot16	Current auto-sync period in 1/65536 of second, see mdbx_env_set_syncperiod().
uint64_t	mi_autosync_threshold	Current auto-sync threshold, see mdbx_env_set_syncbytes().
struct MDBX_envinfo	mi_bootid	A mostly unique ID that is regenerated on each boot. As such it can be used to identify the local machine's current boot. MDBX uses such when open the database to determine whether rollback required to the last steady sync point or not. I.e. if current bootid is differ from the value within a database then the system was rebooted and all changes since last steady sync must be reverted for data integrity. Zeros mean that no relevant information is available from the system.
uint32_t	mi_dxb_pagesize	Database pagesize
struct MDBX_envinfo	mi_geo
uint64_t	mi_last_pgno	Number of the last used page
uint64_t	mi_latter_reader_txnid	ID of the last reader transaction
uint64_t	mi_mapsize	Size of the data memory map
uint32_t	mi_maxreaders	Total reader slots in the environment
uint64_t	mi_meta_sign[3]
uint64_t	mi_meta_txnid[3]
uint32_t	mi_mode	Current environment mode. The same as mdbx_env_get_flags() returns.
uint32_t	mi_numreaders	Max reader slots used in the environment
struct MDBX_envinfo	mi_pgop_stat	Statistics of page operations. Overall statistics of page operations of all (running, completed and aborted) transactions in the current multi-process session (since the first process opened the database after everyone had previously closed it).
uint64_t	mi_recent_txnid	ID of the last committed transaction
uint64_t	mi_self_latter_reader_txnid	ID of the last reader transaction of caller process
uint32_t	mi_since_reader_check_seconds16dot16	Time since the last readers check in 1/65536 of second, see mdbx_reader_check().
uint32_t	mi_since_sync_seconds16dot16	Time since entering to a "dirty" out-of-sync state in units of 1/65536 of second. In other words, this is the time since the last non-steady commit or zero if it was steady.
uint32_t	mi_sys_pagesize	System pagesize
uint64_t	mi_unsync_volume	Bytes not explicitly synchronized to disk

◆ MDBX_txn_info

struct MDBX_txn_info

Information about the transaction.

See also: mdbx_txn_info

Class Members
uint64_t	txn_id	The ID of the transaction. For a READ-ONLY transaction, this corresponds to the snapshot being read.
uint64_t	txn_reader_lag	For READ-ONLY transaction: the lag from a recent MVCC-snapshot, i.e. the number of committed transaction since read transaction started. For WRITE transaction (provided if `scan_rlt=true`): the lag of the oldest reader from current transaction (i.e. at least 1 if any reader running).
uint64_t	txn_space_dirty	For READ-ONLY transaction (provided if `scan_rlt=true`): The space that actually become available for reuse when only this transaction will be finished. For WRITE transaction: The summarized size of the dirty database pages that generated during this transaction.
uint64_t	txn_space_leftover	For READ-ONLY transaction: the space available for writer(s) and that must be exhausted for reason to call the Handle-Slow-Readers callback for this read transaction. For WRITE transaction: the space inside transaction that left to `MDBX_TXN_FULL` error.
uint64_t	txn_space_limit_hard	Upper bound for size the database file, i.e. the value `size_upper` argument of the appropriate call of mdbx_env_set_geometry().
uint64_t	txn_space_limit_soft	Current size of database file.
uint64_t	txn_space_retired	For READ-ONLY transaction: The total size of the database pages that were retired by committed write transactions after the reader's MVCC-snapshot, i.e. the space which would be freed after the Reader releases the MVCC-snapshot for reuse by completion read transaction. For WRITE transaction: The summarized size of the database pages that were retired for now due Copy-On-Write during this transaction.
uint64_t	txn_space_used	Used space by this transaction, i.e. corresponding to the last used database page.

◆ MDBX_commit_latency

struct MDBX_commit_latency

Latency of commit stages in 1/65536 of seconds units.

Warning: This structure may be changed in future releases.

See also: mdbx_txn_commit_ex()

Class Members
uint32_t	audit	Duration of internal audit if enabled.
uint32_t	ending	Duration of transaction ending (releasing resources).
uint32_t	gc_cputime	User-mode CPU time spent on GC update.
struct MDBX_commit_latency	gc_prof	Информация для профилирования работы GC. Note Статистика является общей для всех процессов работающих с одним файлом БД и хранится в LCK-файле. Данные аккумулируются при фиксации всех транзакций, но только в сборках libmdbx c установленной опцией MDBX_ENABLE_PROFGC. Собранная статистика возвращаются любому процессу при использовании mdbx_txn_commit_ex() и одновременно обнуляется при завершении транзакций верхнего уровня (не вложенных).
uint32_t	gc_wallclock	Duration of GC update by wall clock.
uint32_t	preparation	Duration of preparation (commit child transactions, update sub-databases records and cursors destroying).
uint32_t	sync	Duration of syncing written data to the disk/storage, i.e. the duration of a `fdatasync()` or a `msync()` syscall during commit.
uint32_t	whole	The total duration of a commit.
uint32_t	write	Duration of writing dirty/modified data pages to a filesystem, i.e. the summary duration of a `write()` syscalls during commit.

◆ MDBX_envinfo.mi_geo

struct MDBX_envinfo.mi_geo

Class Members
uint64_t	current	Current datafile size
uint64_t	grow	Growth step for datafile
uint64_t	lower	Lower limit for datafile size
uint64_t	shrink	Shrink threshold for datafile
uint64_t	upper	Upper limit for datafile size

◆ MDBX_envinfo.mi_bootid

struct MDBX_envinfo.mi_bootid

A mostly unique ID that is regenerated on each boot.

As such it can be used to identify the local machine's current boot. MDBX uses such when open the database to determine whether rollback required to the last steady sync point or not. I.e. if current bootid is differ from the value within a database then the system was rebooted and all changes since last steady sync must be reverted for data integrity. Zeros mean that no relevant information is available from the system.

Class Members
mi_bootid	current
mi_bootid	meta[3]

◆ MDBX_envinfo.mi_bootid.current

struct MDBX_envinfo.mi_bootid.current

Class Members
uint64_t	x
uint64_t	y

◆ MDBX_envinfo.mi_bootid.meta

struct MDBX_envinfo.mi_bootid.meta

Class Members
uint64_t	x
uint64_t	y

◆ MDBX_envinfo.mi_pgop_stat

struct MDBX_envinfo.mi_pgop_stat

Statistics of page operations.

Overall statistics of page operations of all (running, completed and aborted) transactions in the current multi-process session (since the first process opened the database after everyone had previously closed it).

Class Members
uint64_t	clone	Quantity of parent's dirty pages clones for nested transactions
uint64_t	cow	Quantity of pages copied for update
uint64_t	fsync	Number of explicit fsync-to-disk operations (not a pages)
uint64_t	merge	Page merges
uint64_t	mincore	Number of mincore() calls
uint64_t	msync	Number of explicit msync-to-disk operations (not a pages)
uint64_t	newly	Quantity of a new pages added
uint64_t	prefault	Number of prefault write operations (not a pages)
uint64_t	spill	Quantity of spilled dirty pages
uint64_t	split	Page splits
uint64_t	unspill	Quantity of unspilled/reloaded pages
uint64_t	wops	Number of explicit write operations (not a pages) to a disk

◆ MDBX_commit_latency.gc_prof

struct MDBX_commit_latency.gc_prof

Информация для профилирования работы GC.

Note: Статистика является общей для всех процессов работающих с одним файлом БД и хранится в LCK-файле. Данные аккумулируются при фиксации всех транзакций, но только в сборках libmdbx c установленной опцией MDBX_ENABLE_PROFGC. Собранная статистика возвращаются любому процессу при использовании mdbx_txn_commit_ex() и одновременно обнуляется при завершении транзакций верхнего уровня (не вложенных).

Class Members
uint32_t	coalescences	Количество итераций слияния записей GC.
uint32_t	flushes	Количество принудительных фиксаций на диск во избежания приращения БД при работе вне режима MDBX_UTTERLY_NOSYNC.
uint32_t	kicks	Количество обращений к механизму Handle-Slow-Readers во избежания приращения БД. See also MDBX_hsr_func
uint32_t	self_counter	Счетчик выполнения по медленному пути (slow path execution count) GC для целей поддержки и обновления самой GC.
uint32_t	self_majflt	Количество страничных промахов (page faults) внутри GC при выделении и подготовки страниц для самой GC.
uint32_t	self_rsteps	Количество итераций поиска внутри GC при выделении страниц для целей поддержки и обновления самой GC.
uint32_t	self_rtime_monotonic	Время "по настенным часам" затраченное на чтение и поиск внутри GC для целей поддержки и обновления самой GC.
uint32_t	self_xpages	Количество запросов на выделение последовательностей страниц для самой GC.
uint32_t	self_xtime_cpu	Время ЦПУ в режиме пользователе затраченное на подготовку страниц извлекаемых из GC для целей поддержки и обновления самой GC, включая подкачку с диска.
uint32_t	wipes	Количество уничтожений предыдущих надежных/устойчивых точек фиксации при работе в режиме MDBX_UTTERLY_NOSYNC.
uint32_t	wloops	Количество итераций обновления GC, больше 1 если были повторы/перезапуски.
uint32_t	work_counter	Счетчик выполнения по медленному пути (slow path execution count) GC ради данных пользователя.
uint32_t	work_majflt	Количество страничных промахов (page faults) внутри GC при выделении и подготовки страниц для данных пользователя.
uint32_t	work_rsteps	Количество итераций поиска внутри GC при выделении страниц ради данных пользователя.
uint32_t	work_rtime_monotonic	Время "по настенным часам" затраченное на чтение и поиск внутри GC ради данных пользователя.
uint32_t	work_xpages	Количество запросов на выделение последовательностей страниц ради данных пользователя.
uint32_t	work_xtime_cpu	Время ЦПУ в режиме пользователе затраченное на подготовку страниц извлекаемых из GC для данных пользователя, включая подкачку с диска.

Typedef Documentation

◆ MDBX_dbi_state_t

typedef enum MDBX_dbi_state_t MDBX_dbi_state_t

◆ MDBX_reader_list_func

typedef int() MDBX_reader_list_func(void *ctx, int num, int slot, mdbx_pid_t pid, mdbx_tid_t thread, uint64_t txnid, uint64_t lag, size_t bytes_used, size_t bytes_retained) noexcept

noexcept

A callback function used to enumerate the reader lock table.

Parameters

[in]	ctx	An arbitrary context pointer for the callback.
[in]	num	The serial number during enumeration, starting from 1.
[in]	slot	The reader lock table slot number.
[in]	txnid	The ID of the transaction being read, i.e. the MVCC-snapshot number.
[in]	lag	The lag from a recent MVCC-snapshot, i.e. the number of committed write transactions since the current read transaction started.
[in]	pid	The reader process ID.
[in]	thread	The reader thread ID.
[in]	bytes_used	The number of last used page in the MVCC-snapshot which being read, i.e. database file can't be shrunk beyond this.
[in]	bytes_retained	The total size of the database pages that were retired by committed write transactions after the reader's MVCC-snapshot, i.e. the space which would be freed after the Reader releases the MVCC-snapshot for reuse by completion read transaction.

Returns: < 0 on failure, >= 0 on success.

See also: mdbx_reader_list()

Enumeration Type Documentation

◆ MDBX_dbi_state_t

enum MDBX_dbi_state_t

DBI state bits returted by mdbx_dbi_flags_ex()

See also: mdbx_dbi_flags_ex()

Enumerator
MDBX_DBI_DIRTY	DB was written in this txn
MDBX_DBI_STALE	Cached Named-DB record is older than txnID
MDBX_DBI_FRESH	Named-DB handle opened in this txn
MDBX_DBI_CREAT	Named-DB handle created in this txn

Function Documentation

◆ mdbx_dbi_dupsort_depthmask()

LIBMDBX_API int mdbx_dbi_dupsort_depthmask	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		uint32_t *	mask
	)

Retrieve depth (bitmask) information of nested dupsort (multi-value) B+trees for given database.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[out]	mask	The address of an uint32_t value where the bitmask will be stored.

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

Return values

MDBX_THREAD_MISMATCH	Given transaction is not owned by current thread.
MDBX_EINVAL	An invalid parameter was specified.
MDBX_RESULT_TRUE	The dbi isn't a dupsort (multi-value) database.

◆ mdbx_dbi_flags()

int mdbx_dbi_flags	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		unsigned *	flags
	)

inline

The shortcut to calling mdbx_dbi_flags_ex() with state=NULL for discarding it result.

◆ mdbx_dbi_flags_ex()

LIBMDBX_API int mdbx_dbi_flags_ex	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		unsigned *	flags,
		unsigned *	state
	)

Retrieve the DB flags and status for a database handle.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[out]	flags	Address where the flags will be returned.
[out]	state	Address where the state will be returned.

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

◆ mdbx_dbi_stat()

LIBMDBX_API int mdbx_dbi_stat	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		MDBX_stat *	stat,
		size_t	bytes
	)

Retrieve statistics for a database.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[out]	stat	The address of an MDBX_stat structure where the statistics will be copied.
[in]	bytes	The size of MDBX_stat.

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

Return values

MDBX_THREAD_MISMATCH	Given transaction is not owned by current thread.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_default_pagesize()

LIBMDBX_API size_t mdbx_default_pagesize ( void )

Returns the default size of database page for the current system.

Default size of database page depends on the size of the system page and usually exactly match it.

◆ mdbx_env_get_fd()

LIBMDBX_API int mdbx_env_get_fd	(	const MDBX_env *	env,
		mdbx_filehandle_t *	fd
	)

Return the file descriptor for the given environment.

Note: All MDBX file descriptors have FD_CLOEXEC and couldn't be used after exec() and or fork().

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	fd	Address of a int to contain the descriptor.

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

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_flags()

LIBMDBX_API int mdbx_env_get_flags	(	const MDBX_env *	env,
		unsigned *	flags
	)

Get environment flags.

See also: mdbx_env_set_flags()

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	flags	The address of an integer to store the flags.

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

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_maxdbs()

int mdbx_env_get_maxdbs	(	const MDBX_env *	env,
		MDBX_dbi *	dbs
	)

inline

Get the maximum number of named databases for the environment.

See also: mdbx_env_set_maxdbs()

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	dbs	Address to store the maximum number of databases.

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

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_maxkeysize()

LIBMDBX_API int mdbx_env_get_maxkeysize ( const MDBX_env * env )

Deprecated:: Please use mdbx_env_get_maxkeysize_ex() and/or mdbx_env_get_maxvalsize_ex()

◆ mdbx_env_get_maxkeysize_ex()

LIBMDBX_API int mdbx_env_get_maxkeysize_ex	(	const MDBX_env *	env,
		MDBX_db_flags_t	flags
	)

Returns the maximum size of keys can put.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	flags	Database options (MDBX_DUPSORT, MDBX_INTEGERKEY and so on).

See also: db_flags

Returns: The maximum size of a key can write, or -1 if something is wrong.

◆ mdbx_env_get_maxreaders()

int mdbx_env_get_maxreaders	(	const MDBX_env *	env,
		unsigned *	readers
	)

inline

Get the maximum number of threads/reader slots for the environment.

See also: mdbx_env_set_maxreaders()

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	readers	Address of an integer to store the number of readers.

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

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_maxvalsize_ex()

LIBMDBX_API int mdbx_env_get_maxvalsize_ex	(	const MDBX_env *	env,
		MDBX_db_flags_t	flags
	)

Returns the maximum size of data we can put.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	flags	Database options (MDBX_DUPSORT, MDBX_INTEGERKEY and so on).

See also: db_flags

Returns: The maximum size of a data can write, or -1 if something is wrong.

◆ mdbx_env_get_pairsize4page_max()

LIBMDBX_API int mdbx_env_get_pairsize4page_max	(	const MDBX_env *	env,
		MDBX_db_flags_t	flags
	)

Returns maximal size of key-value pair to fit in a single page for specified database flags.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	flags	Database options (MDBX_DUPSORT, MDBX_INTEGERKEY and so on).

See also: db_flags

Returns: The maximum size of a data can write, or -1 if something is wrong.

◆ mdbx_env_get_path()

LIBMDBX_API int mdbx_env_get_path	(	const MDBX_env *	env,
		const char **	dest
	)

Return the path that was used in mdbx_env_open().

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

Parameters

[in]	env	An environment handle returned by mdbx_env_create()
[out]	dest	Address of a string pointer to contain the path. This is the actual string in the environment, not a copy. It should not be altered in any way.

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

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_syncbytes()

int mdbx_env_get_syncbytes	(	const MDBX_env *	env,
		size_t *	threshold
	)

inline

Get threshold to force flush the data buffers to disk, even any of MDBX_SAFE_NOSYNC flag in the environment.

See also: mdbx_env_set_syncbytes(); MDBX_opt_sync_bytes

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	threshold	Address of an size_t to store the number of bytes of summary changes when a synchronous flush would be made.

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

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_syncperiod()

int mdbx_env_get_syncperiod	(	const MDBX_env *	env,
		unsigned *	period_seconds_16dot16
	)

inline

Get relative period since the last unsteady commit to force flush the data buffers to disk, even of MDBX_SAFE_NOSYNC flag in the environment.

See also: mdbx_env_set_syncperiod(); MDBX_opt_sync_period

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[out]	period_seconds_16dot16	Address of an size_t to store the period in 1/65536 of second when a synchronous flush would be made since the last unsteady commit.

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

Return values

MDBX_EINVAL An invalid parameter was specified.

◆ mdbx_env_get_userctx()

LIBMDBX_API void* mdbx_env_get_userctx ( const MDBX_env * env )

Returns an application information (a context pointer) associated with the environment.

See also: mdbx_env_set_userctx()

Parameters

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

Returns: The pointer set by mdbx_env_set_userctx() or NULL if something wrong.

◆ mdbx_env_get_valsize4page_max()

LIBMDBX_API int mdbx_env_get_valsize4page_max	(	const MDBX_env *	env,
		MDBX_db_flags_t	flags
	)

Returns maximal data size in bytes to fit in a leaf-page or single overflow/large-page for specified database flags.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	flags	Database options (MDBX_DUPSORT, MDBX_INTEGERKEY and so on).

See also: db_flags

Returns: The maximum size of a data can write, or -1 if something is wrong.

◆ mdbx_env_info()

int mdbx_env_info	(	const MDBX_env *	env,
		MDBX_envinfo *	info,
		size_t	bytes
	)

inline

Return information about the MDBX environment.

Deprecated:: Please use mdbx_env_info_ex() instead.

◆ mdbx_env_info_ex()

LIBMDBX_API int mdbx_env_info_ex	(	const MDBX_env *	env,
		const MDBX_txn *	txn,
		MDBX_envinfo *	info,
		size_t	bytes
	)

Return information about the MDBX environment.

At least one of env or txn argument must be non-null. If txn is passed non-null then stat will be filled accordingly to the given transaction. Otherwise, if txn is null, then stat will be populated by a snapshot from the last committed write transaction, and at next time, other information can be returned.

Legacy mdbx_env_info() correspond to calling mdbx_env_info_ex() with the null txn argument.

Parameters

[in]	env	An environment handle returned by mdbx_env_create()
[in]	txn	A transaction handle returned by mdbx_txn_begin()
[out]	info	The address of an MDBX_envinfo structure where the information will be copied
[in]	bytes	The actual size of MDBX_envinfo, this value is used to provide ABI compatibility.

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

◆ mdbx_env_stat()

int mdbx_env_stat	(	const MDBX_env *	env,
		MDBX_stat *	stat,
		size_t	bytes
	)

inline

Return statistics about the MDBX environment.

Deprecated:: Please use mdbx_env_stat_ex() instead.

◆ mdbx_env_stat_ex()

LIBMDBX_API int mdbx_env_stat_ex	(	const MDBX_env *	env,
		const MDBX_txn *	txn,
		MDBX_stat *	stat,
		size_t	bytes
	)

Return statistics about the MDBX environment.

At least one of env or txn argument must be non-null. If txn is passed non-null then stat will be filled accordingly to the given transaction. Otherwise, if txn is null, then stat will be populated by a snapshot from the last committed write transaction, and at next time, other information can be returned.

Legacy mdbx_env_stat() correspond to calling mdbx_env_stat_ex() with the null txn argument.

Parameters

[in]	env	An environment handle returned by mdbx_env_create()
[in]	txn	A transaction handle returned by mdbx_txn_begin()
[out]	stat	The address of an MDBX_stat structure where the statistics will be copied
[in]	bytes	The size of MDBX_stat.

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

◆ mdbx_get_sysraminfo()

LIBMDBX_API int mdbx_get_sysraminfo	(	intptr_t *	page_size,
		intptr_t *	total_pages,
		intptr_t *	avail_pages
	)

Returns basic information about system RAM. This function provides a portable way to get information about available RAM and can be useful in that it returns the same information that libmdbx uses internally to adjust various options and control readahead.

Parameters

[out]	page_size	Optional address where the system page size will be stored.
[out]	total_pages	Optional address where the number of total RAM pages will be stored.
[out]	avail_pages	Optional address where the number of available/free RAM pages will be stored.

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

◆ mdbx_is_dirty()

LIBMDBX_API int mdbx_is_dirty	(	const MDBX_txn *	txn,
		const void *	ptr
	)

Determines whether the given address is on a dirty database page of the transaction or not.

Ultimately, this allows to avoid copy data from non-dirty pages.

"Dirty" pages are those that have already been changed during a write transaction. Accordingly, any further changes may result in such pages being overwritten. Therefore, all functions libmdbx performing changes inside the database as arguments should NOT get pointers to data in those pages. In turn, "not dirty" pages before modification will be copied.

In other words, data from dirty pages must either be copied before being passed as arguments for further processing or rejected at the argument validation stage. Thus, mdbx_is_dirty() allows you to get rid of unnecessary copying, and perform a more complete check of the arguments.

Note: The address passed must point to the beginning of the data. This is the only way to ensure that the actual page header is physically located in the same memory page, including for multi-pages with long data.; In rare cases the function may return a false positive answer (MDBX_RESULT_TRUE when data is NOT on a dirty page), but never a false negative if the arguments are correct.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	ptr	The address of data to check.

Returns: A MDBX_RESULT_TRUE or MDBX_RESULT_FALSE value, otherwise the error code.

Return values

MDBX_RESULT_TRUE	Given address is on the dirty page.
MDBX_RESULT_FALSE	Given address is NOT on the dirty page.
Otherwise	the error code.

◆ mdbx_limits_dbsize_max()

LIBMDBX_API intptr_t mdbx_limits_dbsize_max ( intptr_t pagesize )

Returns maximal database size in bytes for given page size, or -1 if pagesize is invalid.

◆ mdbx_limits_dbsize_min()

LIBMDBX_API intptr_t mdbx_limits_dbsize_min ( intptr_t pagesize )

Returns minimal database size in bytes for given page size, or -1 if pagesize is invalid.

◆ mdbx_limits_keysize_max()

LIBMDBX_API intptr_t mdbx_limits_keysize_max	(	intptr_t	pagesize,
		MDBX_db_flags_t	flags
	)

Returns maximal key size in bytes for given page size and database flags, or -1 if pagesize is invalid.

See also: db_flags

◆ mdbx_limits_keysize_min()

LIBMDBX_API intptr_t mdbx_limits_keysize_min ( MDBX_db_flags_t flags )

Returns minimal key size in bytes for given database flags.

See also: db_flags

◆ mdbx_limits_pairsize4page_max()

LIBMDBX_API intptr_t mdbx_limits_pairsize4page_max	(	intptr_t	pagesize,
		MDBX_db_flags_t	flags
	)

Returns maximal size of key-value pair to fit in a single page with the given size and database flags, or -1 if pagesize is invalid.

See also: db_flags

◆ mdbx_limits_pgsize_max()

intptr_t mdbx_limits_pgsize_max ( void )

inline

Returns the maximal database page size in bytes.

◆ mdbx_limits_pgsize_min()

intptr_t mdbx_limits_pgsize_min ( void )

inline

Returns the minimal database page size in bytes.

◆ mdbx_limits_txnsize_max()

LIBMDBX_API intptr_t mdbx_limits_txnsize_max ( intptr_t pagesize )

Returns maximal write transaction size (i.e. limit for summary volume of dirty pages) in bytes for given page size, or -1 if pagesize is invalid.

◆ mdbx_limits_valsize4page_max()

LIBMDBX_API intptr_t mdbx_limits_valsize4page_max	(	intptr_t	pagesize,
		MDBX_db_flags_t	flags
	)

Returns maximal data size in bytes to fit in a leaf-page or single overflow/large-page with the given page size and database flags, or -1 if pagesize is invalid.

See also: db_flags

◆ mdbx_limits_valsize_max()

LIBMDBX_API intptr_t mdbx_limits_valsize_max	(	intptr_t	pagesize,
		MDBX_db_flags_t	flags
	)

Returns maximal data size in bytes for given page size and database flags, or -1 if pagesize is invalid.

See also: db_flags

◆ mdbx_limits_valsize_min()

LIBMDBX_API intptr_t mdbx_limits_valsize_min ( MDBX_db_flags_t flags )

Returns minimal data size in bytes for given database flags.

See also: db_flags

◆ mdbx_reader_list()

LIBMDBX_API int mdbx_reader_list	(	const MDBX_env *	env,
		MDBX_reader_list_func *	func,
		void *	ctx
	)

Enumerate the entries in the reader lock table.

Parameters

[in]	env	An environment handle returned by mdbx_env_create().
[in]	func	A MDBX_reader_list_func function.
[in]	ctx	An arbitrary context pointer for the enumeration function.

Returns: A non-zero error value on failure and 0 on success, or MDBX_RESULT_TRUE if the reader lock table is empty.

◆ mdbx_txn_id()

LIBMDBX_API uint64_t mdbx_txn_id ( const MDBX_txn * txn )

Return the transaction's ID.

This returns the identifier associated with this transaction. For a read-only transaction, this corresponds to the snapshot being read; concurrent readers will frequently have the same transaction ID.

Parameters

[in] txn A transaction handle returned by mdbx_txn_begin().

Returns: A transaction ID, valid if input is an active transaction, otherwise 0.

◆ mdbx_txn_info()

LIBMDBX_API int mdbx_txn_info	(	const MDBX_txn *	txn,
		MDBX_txn_info *	info,
		bool	scan_rlt
	)

Return information about the MDBX transaction.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin()
[out]	info	The address of an MDBX_txn_info structure where the information will be copied.
[in]	scan_rlt	The boolean flag controls the scan of the read lock table to provide complete information. Such scan is relatively expensive and you can avoid it if corresponding fields are not needed. See description of MDBX_txn_info.

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

◆ mdbx_txn_straggler()

LIBMDBX_API int mdbx_txn_straggler	(	const MDBX_txn *	txn,
		int *	percent
	)

Returns a lag of the reading for the given transaction.

Returns an information for estimate how much given read-only transaction is lagging relative the to actual head.

Deprecated:: Please use mdbx_txn_info() instead.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[out]	percent	Percentage of page allocation in the database.

Returns: Number of transactions committed after the given was started for read, or negative value on failure.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Class Documentation

◆ MDBX_stat

◆ MDBX_envinfo

◆ MDBX_txn_info

◆ MDBX_commit_latency

◆ MDBX_envinfo.mi_geo

◆ MDBX_envinfo.mi_bootid

◆ MDBX_envinfo.mi_bootid.current

◆ MDBX_envinfo.mi_bootid.meta

◆ MDBX_envinfo.mi_pgop_stat

◆ MDBX_commit_latency.gc_prof

Typedef Documentation

◆ MDBX_dbi_state_t

◆ MDBX_reader_list_func

Enumeration Type Documentation

◆ MDBX_dbi_state_t

Function Documentation

◆ mdbx_dbi_dupsort_depthmask()

◆ mdbx_dbi_flags()

◆ mdbx_dbi_flags_ex()

◆ mdbx_dbi_stat()

◆ mdbx_default_pagesize()

◆ mdbx_env_get_fd()

◆ mdbx_env_get_flags()

◆ mdbx_env_get_maxdbs()

◆ mdbx_env_get_maxkeysize()

◆ mdbx_env_get_maxkeysize_ex()

◆ mdbx_env_get_maxreaders()

◆ mdbx_env_get_maxvalsize_ex()

◆ mdbx_env_get_pairsize4page_max()

◆ mdbx_env_get_path()

◆ mdbx_env_get_syncbytes()

◆ mdbx_env_get_syncperiod()

◆ mdbx_env_get_userctx()

◆ mdbx_env_get_valsize4page_max()

◆ mdbx_env_info()

◆ mdbx_env_info_ex()

◆ mdbx_env_stat()

◆ mdbx_env_stat_ex()

◆ mdbx_get_sysraminfo()

◆ mdbx_is_dirty()

◆ mdbx_limits_dbsize_max()

◆ mdbx_limits_dbsize_min()

◆ mdbx_limits_keysize_max()

◆ mdbx_limits_keysize_min()

◆ mdbx_limits_pairsize4page_max()

◆ mdbx_limits_pgsize_max()

◆ mdbx_limits_pgsize_min()

◆ mdbx_limits_txnsize_max()

◆ mdbx_limits_valsize4page_max()

◆ mdbx_limits_valsize_max()

◆ mdbx_limits_valsize_min()

◆ mdbx_reader_list()

◆ mdbx_txn_id()

◆ mdbx_txn_info()

◆ mdbx_txn_straggler()