Typedefs
typedef struct MDBX_cursor	MDBX_cursor
	Opaque structure for navigating through a database. More...

typedef enum MDBX_cursor_op	MDBX_cursor_op

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 }
	Cursor operations. More...

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

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

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

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

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

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

LIBMDBX_API int	mdbx_cursor_renew (MDBX_txn txn, MDBX_cursor cursor)
	Renew a cursor handle. More...

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

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

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

MDBX_NOTHROW_PURE_FUNCTION 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. More...

MDBX_NOTHROW_PURE_FUNCTION 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. More...

MDBX_NOTHROW_PURE_FUNCTION 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. More...

Detailed Description

Typedef Documentation

◆ MDBX_cursor

typedef struct MDBX_cursor MDBX_cursor

Opaque structure for navigating through a database.

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

◆ MDBX_cursor_op

typedef enum MDBX_cursor_op MDBX_cursor_op

Enumeration Type Documentation

◆ MDBX_cursor_op

enum MDBX_cursor_op

Cursor operations.

This 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 the same to 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.

Function Documentation

◆ mdbx_cursor_bind()

LIBMDBX_API int mdbx_cursor_bind	(	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 database 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 database handle returned by mdbx_dbi_open().
[out]	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_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 database 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 database handle.

Parameters

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

◆ mdbx_cursor_eof()

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

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

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

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

LIBMDBX_API int mdbx_cursor_open	(	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 database 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 database 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	(	MDBX_txn *	txn,
		MDBX_cursor *	cursor
	)

Renew a cursor handle.

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

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

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

Set application information associated with the MDBX_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()

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

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MDBX_cursor

◆ MDBX_cursor_op

Enumeration Type Documentation

◆ MDBX_cursor_op

Function Documentation

◆ mdbx_cursor_bind()

◆ mdbx_cursor_close()

◆ mdbx_cursor_copy()

◆ mdbx_cursor_create()

◆ mdbx_cursor_dbi()

◆ mdbx_cursor_eof()

◆ mdbx_cursor_get_userctx()

◆ mdbx_cursor_on_first()

◆ mdbx_cursor_on_last()

◆ mdbx_cursor_open()

◆ mdbx_cursor_renew()

◆ mdbx_cursor_set_userctx()

◆ mdbx_cursor_txn()