libmdbx  0.12.10.0 (2024-03-13T14:57:38+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
Cursors

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 operationsThis is the set of all operations for retrieving data using a cursor. More...
 

Functions

LIBMDBX_API MDBX_cursormdbx_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 cursor. More...
 
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 (const MDBX_txn *txn, MDBX_cursor *cursor, MDBX_dbi dbi)
 Bind cursor to specified transaction and DBI-handle. More...
 
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. More...
 
LIBMDBX_API void mdbx_cursor_close (MDBX_cursor *cursor)
 Close a cursor handle. More...
 
LIBMDBX_API int mdbx_cursor_renew (const MDBX_txn *txn, MDBX_cursor *cursor)
 Renew a cursor handle for use within the given transaction. More...
 
LIBMDBX_API MDBX_txnmdbx_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...
 
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...
 
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...
 
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

Enumeration Type Documentation

◆ 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 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 ( 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 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]txnA transaction handle returned by mdbx_txn_begin().
[in]dbiA database handle returned by mdbx_dbi_open().
[in]cursorA 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_MISMATCHGiven transaction is not owned by current thread.
MDBX_EINVALAn 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]cursorA 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]srcA source cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().
[in,out]destA 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]contextA 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]cursorA 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]cursorA 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_TRUENo more data available or cursor not positioned
MDBX_RESULT_FALSEA data is available
Otherwisethe 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]cursorAn 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]cursorA 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_TRUECursor positioned to the first key-value pair
MDBX_RESULT_FALSECursor NOT positioned to the first key-value pair
Otherwisethe error code

◆ 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]cursorA 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_TRUECursor positioned to the last key-value pair
MDBX_RESULT_FALSECursor NOT positioned to the last key-value pair
Otherwisethe error code

◆ 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 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]txnA transaction handle returned by mdbx_txn_begin().
[in]dbiA database handle returned by mdbx_dbi_open().
[out]cursorAddress 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_MISMATCHGiven transaction is not owned by current thread.
MDBX_EINVALAn 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]txnA transaction handle returned by mdbx_txn_begin().
[in]cursorA 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_MISMATCHGiven transaction is not owned by current thread.
MDBX_EINVALAn invalid parameter was specified.
MDBX_BAD_DBIThe cursor was not bound to a DBI-handle or such a handle became invalid.

◆ 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]cursorAn cursor handle returned by mdbx_cursor_create() or mdbx_cursor_open().
[in]ctxAn 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]cursorA cursor handle returned by mdbx_cursor_open().