Typedefs
typedef struct MDBX_cursor	MDBX_cursor
	Opaque structure for navigating through a table.

Enumerations
enum	MDBX_cursor_op { MDBX_FIRST , MDBX_FIRST_DUP , MDBX_GET_BOTH , MDBX_GET_BOTH_RANGE , MDBX_GET_CURRENT , MDBX_GET_MULTIPLE , MDBX_LAST , MDBX_LAST_DUP , MDBX_NEXT , MDBX_NEXT_DUP , MDBX_NEXT_MULTIPLE , MDBX_NEXT_NODUP , MDBX_PREV , MDBX_PREV_DUP , MDBX_PREV_NODUP , MDBX_SET , MDBX_SET_KEY , MDBX_SET_RANGE , MDBX_PREV_MULTIPLE , MDBX_SET_LOWERBOUND , MDBX_SET_UPPERBOUND , MDBX_TO_KEY_LESSER_THAN , MDBX_TO_KEY_LESSER_OR_EQUAL , MDBX_TO_KEY_EQUAL , MDBX_TO_KEY_GREATER_OR_EQUAL , MDBX_TO_KEY_GREATER_THAN , MDBX_TO_EXACT_KEY_VALUE_LESSER_THAN , MDBX_TO_EXACT_KEY_VALUE_LESSER_OR_EQUAL , MDBX_TO_EXACT_KEY_VALUE_EQUAL , MDBX_TO_EXACT_KEY_VALUE_GREATER_OR_EQUAL , MDBX_TO_EXACT_KEY_VALUE_GREATER_THAN , MDBX_TO_PAIR_LESSER_THAN , MDBX_TO_PAIR_LESSER_OR_EQUAL , MDBX_TO_PAIR_EQUAL , MDBX_TO_PAIR_GREATER_OR_EQUAL , MDBX_TO_PAIR_GREATER_THAN }
	Cursor operationsThis is the set of all operations for retrieving data using a cursor. More...

Functions
LIBMDBX_API MDBX_cursor *	mdbx_cursor_create (void *context)
	Create a cursor handle but not bind it to transaction nor DBI-handle.

LIBMDBX_API int	mdbx_cursor_set_userctx (MDBX_cursor cursor, void ctx)
	Set application information associated with the cursor.

LIBMDBX_API void *	mdbx_cursor_get_userctx (const MDBX_cursor *cursor)
	Get the application information associated with the MDBX_cursor.

LIBMDBX_API int	mdbx_cursor_bind (const MDBX_txn txn, MDBX_cursor cursor, MDBX_dbi dbi)
	Bind cursor to specified transaction and DBI-handle.

LIBMDBX_API int	mdbx_cursor_unbind (MDBX_cursor *cursor)
	Unbind cursor from a transaction.

LIBMDBX_API int	mdbx_cursor_reset (MDBX_cursor *cursor)
	Сбрасывает состояние курсора.

LIBMDBX_API int	mdbx_cursor_open (const MDBX_txn txn, MDBX_dbi dbi, MDBX_cursor *cursor)
	Create a cursor handle for the specified transaction and DBI handle.

LIBMDBX_API void	mdbx_cursor_close (MDBX_cursor *cursor)
	Close a cursor handle.

LIBMDBX_API int	mdbx_txn_release_all_cursors (const MDBX_txn *txn, bool unbind)
	Unbind or closes all cursors of a given transaction.

LIBMDBX_API int	mdbx_cursor_renew (const MDBX_txn txn, MDBX_cursor cursor)
	Renew a cursor handle for use within the given transaction.

LIBMDBX_API MDBX_txn *	mdbx_cursor_txn (const MDBX_cursor *cursor)
	Return the cursor's transaction handle.

LIBMDBX_API MDBX_dbi	mdbx_cursor_dbi (const MDBX_cursor *cursor)
	Return the cursor's table handle.

LIBMDBX_API int	mdbx_cursor_copy (const MDBX_cursor src, MDBX_cursor dest)
	Copy cursor position and state.

LIBMDBX_API int	mdbx_cursor_compare (const MDBX_cursor left, const MDBX_cursor right, bool ignore_multival)
	Сравнивает позицию курсоров.

LIBMDBX_API int	mdbx_cursor_eof (const MDBX_cursor *cursor)
	Determines whether the cursor is pointed to a key-value pair or not, i.e. was not positioned or points to the end of data.

LIBMDBX_API int	mdbx_cursor_on_first (const MDBX_cursor *cursor)
	Determines whether the cursor is pointed to the first key-value pair or not.

LIBMDBX_API int	mdbx_cursor_on_first_dup (const MDBX_cursor *cursor)
	Определяет стоит ли курсор на первом или единственном мульти-значении соответствующем ключу.

LIBMDBX_API int	mdbx_cursor_on_last (const MDBX_cursor *cursor)
	Determines whether the cursor is pointed to the last key-value pair or not.

LIBMDBX_API int	mdbx_cursor_on_last_dup (const MDBX_cursor *cursor)
	Определяет стоит ли курсор на последнем или единственном мульти-значении соответствующем ключу.

Detailed Description

Typedef Documentation

◆ MDBX_cursor

typedef struct MDBX_cursor MDBX_cursor

Opaque structure for navigating through a table.

See also: mdbx_cursor_create(); mdbx_cursor_bind(); mdbx_cursor_close()

Enumeration Type Documentation

◆ MDBX_cursor_op

enum MDBX_cursor_op

Cursor operationsThis is the set of all operations for retrieving data using a cursor.

See also: mdbx_cursor_get()

Enumerator
MDBX_FIRST	Position at first key/data item
MDBX_FIRST_DUP	MDBX_DUPSORT -only: Position at first data item of current key.
MDBX_GET_BOTH	MDBX_DUPSORT -only: Position at key/data pair.
MDBX_GET_BOTH_RANGE	MDBX_DUPSORT -only: Position at given key and at first data greater than or equal to specified data.
MDBX_GET_CURRENT	Return key/data at current cursor position
MDBX_GET_MULTIPLE	MDBX_DUPFIXED -only: Return up to a page of duplicate data items from current cursor position. Move cursor to prepare for MDBX_NEXT_MULTIPLE.
MDBX_LAST	Position at last key/data item
MDBX_LAST_DUP	MDBX_DUPSORT -only: Position at last data item of current key.
MDBX_NEXT	Position at next data item
MDBX_NEXT_DUP	MDBX_DUPSORT -only: Position at next data item of current key.
MDBX_NEXT_MULTIPLE	MDBX_DUPFIXED -only: Return up to a page of duplicate data items from next cursor position. Move cursor to prepare for `MDBX_NEXT_MULTIPLE`.
MDBX_NEXT_NODUP	Position at first data item of next key
MDBX_PREV	Position at previous data item
MDBX_PREV_DUP	MDBX_DUPSORT -only: Position at previous data item of current key.
MDBX_PREV_NODUP	Position at last data item of previous key
MDBX_SET	Position at specified key
MDBX_SET_KEY	Position at specified key, return both key and data
MDBX_SET_RANGE	Position at first key greater than or equal to specified key.
MDBX_PREV_MULTIPLE	MDBX_DUPFIXED -only: Position at previous page and return up to a page of duplicate data items.
MDBX_SET_LOWERBOUND	Positions cursor at first key-value pair greater than or equal to specified, return both key and data, and the return code depends on whether a exact match. For non DUPSORT-ed collections this work the same to MDBX_SET_RANGE, but returns MDBX_SUCCESS if key found exactly or MDBX_RESULT_TRUE if greater key was found. For DUPSORT-ed a data value is taken into account for duplicates, i.e. for a pairs/tuples of a key and an each data value of duplicates. Returns MDBX_SUCCESS if key-value pair found exactly or MDBX_RESULT_TRUE if the next pair was returned.
MDBX_SET_UPPERBOUND	Positions cursor at first key-value pair greater than specified, return both key and data, and the return code depends on whether a upper-bound was found. For non DUPSORT-ed collections this work like MDBX_SET_RANGE, but returns MDBX_SUCCESS if the greater key was found or MDBX_NOTFOUND otherwise. For DUPSORT-ed a data value is taken into account for duplicates, i.e. for a pairs/tuples of a key and an each data value of duplicates. Returns MDBX_SUCCESS if the greater pair was returned or MDBX_NOTFOUND otherwise.
MDBX_TO_KEY_LESSER_THAN
MDBX_TO_KEY_LESSER_OR_EQUAL
MDBX_TO_KEY_EQUAL
MDBX_TO_KEY_GREATER_OR_EQUAL
MDBX_TO_KEY_GREATER_THAN
MDBX_TO_EXACT_KEY_VALUE_LESSER_THAN
MDBX_TO_EXACT_KEY_VALUE_LESSER_OR_EQUAL
MDBX_TO_EXACT_KEY_VALUE_EQUAL
MDBX_TO_EXACT_KEY_VALUE_GREATER_OR_EQUAL
MDBX_TO_EXACT_KEY_VALUE_GREATER_THAN
MDBX_TO_PAIR_LESSER_THAN
MDBX_TO_PAIR_LESSER_OR_EQUAL
MDBX_TO_PAIR_EQUAL
MDBX_TO_PAIR_GREATER_OR_EQUAL
MDBX_TO_PAIR_GREATER_THAN

Function Documentation

◆ mdbx_cursor_bind()

LIBMDBX_API int mdbx_cursor_bind	(	const MDBX_txn *	txn,
		MDBX_cursor *	cursor,
		MDBX_dbi	dbi
	)

Bind cursor to specified transaction and DBI-handle.

Using of the mdbx_cursor_bind() is equivalent to calling mdbx_cursor_renew() but with specifying an arbitrary DBI-handle.

A cursor may be associated with a new transaction, and referencing a new or the same table handle as it was created with. This may be done whether the previous transaction is live or dead.

Note: In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A table handle returned by mdbx_dbi_open().
[in]	cursor	A cursor handle returned by mdbx_cursor_create().

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

LIBMDBX_API void mdbx_cursor_close ( MDBX_cursor * cursor )

Close a cursor handle.

The cursor handle will be freed and must not be used again after this call, but its transaction may still be live.

Note: In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters

[in] cursor A cursor handle returned by mdbx_cursor_open() or mdbx_cursor_create().

◆ mdbx_cursor_compare()

LIBMDBX_API int mdbx_cursor_compare	(	const MDBX_cursor *	left,
		const MDBX_cursor *	right,
		bool	ignore_multival
	)

Сравнивает позицию курсоров.

Функция предназначена для сравнения позиций двух инициализированных/установленных курсоров, связанных с одной транзакцией и одной таблицей (DBI-дескриптором). Если же курсоры связаны с разными транзакциями, либо с разными таблицами, либо один из них не инициализирован, то результат сравнения не определен (поведением может быть изменено в последующих версиях).

Parameters

[in]	left	Левый курсор для сравнения позиций.
[in]	right	Правый курсор для сравнения позиций.
[in]	ignore_multival	Булевой флаг, влияющий на результат только при сравнении курсоров для таблиц с мульти-значениями, т.е. с флагом MDBX_DUPSORT. В случае `true`, позиции курсоров сравниваются только по ключам, без учета позиционирования среди мульти-значений. Иначе, в случае `false`, при совпадении позиций по ключам, сравниваются также позиции по мульти-значениям.

Return values

Значение со знаком в семантике оператора <=> (меньше нуля, ноль, либо больше нуля) как результат сравнения позиций курсоров.

◆ mdbx_cursor_copy()

LIBMDBX_API int mdbx_cursor_copy	(	const MDBX_cursor *	src,
		MDBX_cursor *	dest
	)

Copy cursor position and state.

Parameters

[in]	src	A source cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().
[in,out]	dest	A destination cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().

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

◆ mdbx_cursor_create()

LIBMDBX_API MDBX_cursor * mdbx_cursor_create ( void * context )

Create a cursor handle but not bind it to transaction nor DBI-handle.

A cursor cannot be used when its table handle is closed. Nor when its transaction has ended, except with mdbx_cursor_bind() and mdbx_cursor_renew(). Also it can be discarded with mdbx_cursor_close().

A cursor must be closed explicitly always, before or after its transaction ends. It can be reused with mdbx_cursor_bind() or mdbx_cursor_renew() before finally closing it.

Note: In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters

[in] context A pointer to application context to be associated with created cursor and could be retrieved by mdbx_cursor_get_userctx() until cursor closed.

Returns: Created cursor handle or NULL in case out of memory.

◆ mdbx_cursor_dbi()

LIBMDBX_API MDBX_dbi mdbx_cursor_dbi ( const MDBX_cursor * cursor )

Return the cursor's table handle.

Parameters

[in] cursor A cursor handle returned by mdbx_cursor_open().

◆ mdbx_cursor_eof()

LIBMDBX_API int mdbx_cursor_eof ( const MDBX_cursor * cursor )

Determines whether the cursor is pointed to a key-value pair or not, i.e. was not positioned or points to the end of data.

Parameters

[in] cursor A cursor handle returned by mdbx_cursor_open().

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

Return values

MDBX_RESULT_TRUE	No more data available or cursor not positioned
MDBX_RESULT_FALSE	A data is available
Otherwise	the error code

◆ mdbx_cursor_get_userctx()

LIBMDBX_API void * mdbx_cursor_get_userctx ( const MDBX_cursor * cursor )

Get the application information associated with the MDBX_cursor.

See also: mdbx_cursor_set_userctx()

Parameters

[in] cursor An cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().

Returns: The pointer which was passed via the context parameter of mdbx_cursor_create() or set by mdbx_cursor_set_userctx(), or NULL if something wrong.

◆ mdbx_cursor_on_first()

LIBMDBX_API int mdbx_cursor_on_first ( const MDBX_cursor * cursor )

Determines whether the cursor is pointed to the first key-value pair or not.

Parameters

[in] cursor A cursor handle returned by mdbx_cursor_open().

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

Return values

MDBX_RESULT_TRUE	Cursor positioned to the first key-value pair
MDBX_RESULT_FALSE	Cursor NOT positioned to the first key-value pair
Otherwise	the error code

◆ mdbx_cursor_on_first_dup()

LIBMDBX_API int mdbx_cursor_on_first_dup ( const MDBX_cursor * cursor )

Определяет стоит ли курсор на первом или единственном мульти-значении соответствующем ключу.

Parameters

[in] cursor Курсор созданный посредством mdbx_cursor_open().

Returns: Значание MDBX_RESULT_TRUE, либо MDBX_RESULT_FALSE, иначе код ошибки.

Return values

MDBX_RESULT_TRUE	курсор установлен на первом или единственном мульти-значении соответствующем ключу.
MDBX_RESULT_FALSE	курсор НЕ установлен на первом или единственном мульти-значении соответствующем ключу.
ИНАЧЕ	код ошибки.

◆ mdbx_cursor_on_last()

LIBMDBX_API int mdbx_cursor_on_last ( const MDBX_cursor * cursor )

Determines whether the cursor is pointed to the last key-value pair or not.

Parameters

[in] cursor A cursor handle returned by mdbx_cursor_open().

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

Return values

MDBX_RESULT_TRUE	Cursor positioned to the last key-value pair
MDBX_RESULT_FALSE	Cursor NOT positioned to the last key-value pair
Otherwise	the error code

◆ mdbx_cursor_on_last_dup()

LIBMDBX_API int mdbx_cursor_on_last_dup ( const MDBX_cursor * cursor )

Определяет стоит ли курсор на последнем или единственном мульти-значении соответствующем ключу.

Parameters

[in] cursor Курсор созданный посредством mdbx_cursor_open().

Returns: Значание MDBX_RESULT_TRUE, либо MDBX_RESULT_FALSE, иначе код ошибки.

Return values

MDBX_RESULT_TRUE	курсор установлен на последнем или единственном мульти-значении соответствующем ключу.
MDBX_RESULT_FALSE	курсор НЕ установлен на последнем или единственном мульти-значении соответствующем ключу.
ИНАЧЕ	код ошибки.

◆ mdbx_cursor_open()

LIBMDBX_API int mdbx_cursor_open	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		MDBX_cursor **	cursor
	)

Create a cursor handle for the specified transaction and DBI handle.

Using of the mdbx_cursor_open() is equivalent to calling mdbx_cursor_create() and then mdbx_cursor_bind() functions.

A cursor cannot be used when its table handle is closed. Nor when its transaction has ended, except with mdbx_cursor_bind() and mdbx_cursor_renew(). Also it can be discarded with mdbx_cursor_close().

A cursor must be closed explicitly always, before or after its transaction ends. It can be reused with mdbx_cursor_bind() or mdbx_cursor_renew() before finally closing it.

Note: In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A table handle returned by mdbx_dbi_open().
[out]	cursor	Address where the new MDBX_cursor handle 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_cursor_renew()

LIBMDBX_API int mdbx_cursor_renew	(	const MDBX_txn *	txn,
		MDBX_cursor *	cursor
	)

Renew a cursor handle for use within the given transaction.

A cursor may be associated with a new transaction whether the previous transaction is running or finished.

Using of the mdbx_cursor_renew() is equivalent to calling mdbx_cursor_bind() with the DBI-handle that previously the cursor was used with.

Note: In contrast to LMDB, the MDBX allow any cursor to be re-used by using mdbx_cursor_renew(), to avoid unnecessary malloc/free overhead until it freed by mdbx_cursor_close().

Parameters

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

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_BAD_DBI	The cursor was not bound to a DBI-handle or such a handle became invalid.

◆ mdbx_cursor_reset()

LIBMDBX_API int mdbx_cursor_reset ( MDBX_cursor * cursor )

Сбрасывает состояние курсора.

В результате сброса курсор становится неустановленным и не позволяет выполнять операции относительного позиционирования, получения или изменения данных, до установки на позицию не зависящую от текущей. Что позволяет приложению пресекать дальнейшие операции без предварительного позиционирования курсора.

Parameters

[in] cursor Указатель на курсор.

Returns: Результат операции сканирования, либо код ошибки.

◆ mdbx_cursor_set_userctx()

LIBMDBX_API int mdbx_cursor_set_userctx	(	MDBX_cursor *	cursor,
		void *	ctx
	)

Set application information associated with the cursor.

See also: mdbx_cursor_get_userctx()

Parameters

[in]	cursor	An cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().
[in]	ctx	An arbitrary pointer for whatever the application needs.

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

◆ mdbx_cursor_txn()

LIBMDBX_API MDBX_txn * mdbx_cursor_txn ( const MDBX_cursor * cursor )

Return the cursor's transaction handle.

Parameters

[in] cursor A cursor handle returned by mdbx_cursor_open().

◆ mdbx_cursor_unbind()

LIBMDBX_API int mdbx_cursor_unbind ( MDBX_cursor * cursor )

Unbind cursor from a transaction.

Unbinded cursor is disassociated with any transactions but still holds the original DBI-handle internally. Thus it could be renewed with any running transaction or closed.

See also: mdbx_cursor_renew(); mdbx_cursor_bind(); mdbx_cursor_close(); mdbx_cursor_reset()

Note: In contrast to LMDB, the MDBX required that any opened cursors can be reused and must be freed explicitly, regardless ones was opened in a read-only or write transaction. The REASON for this is eliminates ambiguity which helps to avoid errors such as: use-after-free, double-free, i.e. memory corruption and segfaults.

Parameters

[in] cursor A cursor handle returned by mdbx_cursor_open().

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

◆ mdbx_txn_release_all_cursors()

LIBMDBX_API int mdbx_txn_release_all_cursors	(	const MDBX_txn *	txn,
		bool	unbind
	)

Unbind or closes all cursors of a given transaction.

Unbinds either closes all cursors associated (opened or renewed) with a given transaction in a bulk with minimal overhead.

See also: mdbx_cursor_unbind(); mdbx_cursor_close()

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	unbind	If non-zero, unbinds cursors and leaves ones reusable. Otherwise close and dispose cursors.

Returns: A negative error value on failure or the number of closed cursors on success, some possible errors are:

Return values

MDBX_THREAD_MISMATCH	Given transaction is not owned by current thread.
MDBX_BAD_TXN	Given transaction is invalid or has a child/nested transaction transaction.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MDBX_cursor

Enumeration Type Documentation

◆ MDBX_cursor_op

Function Documentation

◆ mdbx_cursor_bind()

◆ mdbx_cursor_close()

◆ mdbx_cursor_compare()

◆ mdbx_cursor_copy()

◆ mdbx_cursor_create()

◆ mdbx_cursor_dbi()

◆ mdbx_cursor_eof()

◆ mdbx_cursor_get_userctx()

◆ mdbx_cursor_on_first()

◆ mdbx_cursor_on_first_dup()

◆ mdbx_cursor_on_last()

◆ mdbx_cursor_on_last_dup()

◆ mdbx_cursor_open()

◆ mdbx_cursor_renew()

◆ mdbx_cursor_reset()

◆ mdbx_cursor_set_userctx()

◆ mdbx_cursor_txn()

◆ mdbx_cursor_unbind()

◆ mdbx_txn_release_all_cursors()