Modules
	Attribute support functions for Nexenta

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

Typedefs
typedef enum MDBX_put_flags_t	MDBX_put_flags_t

typedef int()	MDBX_cmp_func(const MDBX_val a, const MDBX_val b) MDBX_CXX17_NOEXCEPT
	A callback function used to compare two keys in a database. More...

Enumerations
enum	MDBX_put_flags_t { MDBX_UPSERT = 0, MDBX_NOOVERWRITE = UINT32_C(0x10), MDBX_NODUPDATA = UINT32_C(0x20), MDBX_CURRENT = UINT32_C(0x40), MDBX_ALLDUPS = UINT32_C(0x80), MDBX_RESERVE = UINT32_C(0x10000), MDBX_APPEND = UINT32_C(0x20000), MDBX_APPENDDUP = UINT32_C(0x40000), MDBX_MULTIPLE = UINT32_C(0x80000) }
	Data changing flags. More...

Functions
LIBMDBX_API int	mdbx_canary_put (MDBX_txn txn, const MDBX_canary canary)
	Set integers markers (aka "canary") associated with the environment. More...

LIBMDBX_API int	mdbx_canary_get (const MDBX_txn txn, MDBX_canary canary)
	Returns fours integers markers (aka "canary") associated with the environment. More...

LIBMDBX_API int	mdbx_drop (MDBX_txn *txn, MDBX_dbi dbi, bool del)
	Empty or delete and close a database. More...

LIBMDBX_API int	mdbx_get (MDBX_txn txn, MDBX_dbi dbi, const MDBX_val key, MDBX_val *data)
	Get items from a database. More...

LIBMDBX_API int	mdbx_get_ex (MDBX_txn txn, MDBX_dbi dbi, MDBX_val key, MDBX_val data, size_t values_count)
	Get items from a database and optionally number of data items for a given key. More...

LIBMDBX_API int	mdbx_get_equal_or_great (MDBX_txn txn, MDBX_dbi dbi, MDBX_val key, MDBX_val *data)
	Get equal or great item from a database. More...

LIBMDBX_API int	mdbx_put (MDBX_txn txn, MDBX_dbi dbi, const MDBX_val key, MDBX_val *data, MDBX_put_flags_t flags)
	Store items into a database. More...

LIBMDBX_API int	mdbx_replace (MDBX_txn txn, MDBX_dbi dbi, const MDBX_val key, MDBX_val new_data, MDBX_val old_data, MDBX_put_flags_t flags)
	Replace items in a database. More...

LIBMDBX_API int	mdbx_del (MDBX_txn txn, MDBX_dbi dbi, const MDBX_val key, const MDBX_val *data)
	Delete items from a database. More...

LIBMDBX_API int	mdbx_cursor_get (MDBX_cursor cursor, MDBX_val key, MDBX_val *data, MDBX_cursor_op op)
	Retrieve by cursor. More...

LIBMDBX_API int	mdbx_cursor_get_batch (MDBX_cursor cursor, size_t count, MDBX_val *pairs, size_t limit, MDBX_cursor_op op)
	Retrieve multiple non-dupsort key/value pairs by cursor. More...

LIBMDBX_API int	mdbx_cursor_put (MDBX_cursor cursor, const MDBX_val key, MDBX_val *data, MDBX_put_flags_t flags)
	Store by cursor. More...

LIBMDBX_API int	mdbx_cursor_del (MDBX_cursor *cursor, MDBX_put_flags_t flags)
	Delete current key/data pair. More...

LIBMDBX_API int	mdbx_cursor_count (const MDBX_cursor cursor, size_t pcount)
	Return count of duplicates for current key. More...

LIBMDBX_API int	mdbx_dbi_sequence (MDBX_txn txn, MDBX_dbi dbi, uint64_t result, uint64_t increment)
	Sequence generation for a database. More...

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int	mdbx_cmp (const MDBX_txn txn, MDBX_dbi dbi, const MDBX_val a, const MDBX_val *b)
	Compare two keys according to a particular database. More...

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int	mdbx_dcmp (const MDBX_txn txn, MDBX_dbi dbi, const MDBX_val a, const MDBX_val *b)
	Compare two data items according to a particular database. More...

Detailed Description

Quick Reference for Insert/Update/Delete operations

Historically, libmdbx inherits the API basis from LMDB, where it is often difficult to select flags/options and functions for the desired operation. So it is recommend using this hints.

Databases with UNIQUE keys

In databases created without the MDBX_DUPSORT option, keys are always unique. Thus always a single value corresponds to the each key, and so there are only a few cases of changing data.

Case	Flags to use	Result
INSERTING
Key is absent → Insertion	MDBX_NOOVERWRITE	Insertion
Key exist → Error since key present	MDBX_NOOVERWRITE	Error MDBX_KEYEXIST and return Present value
UPSERTING
Key is absent → Insertion	MDBX_UPSERT	Insertion
Key exist → Update	MDBX_UPSERT	Update
UPDATING
Key is absent → Error since no such key	MDBX_CURRENT	Error MDBX_NOTFOUND
Key exist → Update	MDBX_CURRENT	Update value
DELETING
Key is absent → Error since no such key	mdbx_del() or mdbx_replace()	Error MDBX_NOTFOUND
Key exist → Delete by key	mdbx_del() with the parameter `data = NULL`	Deletion
Key exist → Delete by key with with data matching check	mdbx_del() with the parameter `data` filled with the value which should be match for deletion	Deletion or MDBX_NOTFOUND if the value does not match
Delete at the current cursor position	mdbx_cursor_del() with MDBX_CURRENT flag	Deletion
Extract (read & delete) value by the key	mdbx_replace() with zero flag and parameter `new_data = NULL`	Returning a deleted value

Databases with NON-UNIQUE keys

In databases created with the MDBX_DUPSORT (Sorted Duplicates) option, keys may be non unique. Such non-unique keys in a key-value database may be treated as a duplicates or as like a multiple values corresponds to keys.

Case	Flags to use	Result
INSERTING
Key is absent → Insertion	MDBX_NOOVERWRITE	Insertion
Key exist → Needn't to add new values	MDBX_NOOVERWRITE	Error MDBX_KEYEXIST with returning the first value from those already present
UPSERTING
Key is absent → Insertion	MDBX_UPSERT	Insertion
Key exist → Wanna to add new values	MDBX_UPSERT	Add one more value to the key
Key exist → Replace all values with a new one	MDBX_UPSERT + MDBX_ALLDUPS	Overwrite by single new value
UPDATING
Key is absent → Error since no such key	MDBX_CURRENT	Error MDBX_NOTFOUND
Key exist, Single value → Update	MDBX_CURRENT	Update single value
Key exist, Multiple values → Replace all values with a new one	MDBX_CURRENT + MDBX_ALLDUPS	Overwrite by single new value
Key exist, Multiple values → Error since it is unclear which of the values should be updated	mdbx_put() with MDBX_CURRENT	Error MDBX_EMULTIVAL
Key exist, Multiple values → Update particular entry of multi-value	mdbx_replace() with MDBX_CURRENT + MDBX_NOOVERWRITE and the parameter `old_value` filled with the value that wanna to update	Update one multi-value entry
Key exist, Multiple values → Update the current entry of multi-value	mdbx_cursor_put() with MDBX_CURRENT	Update one multi-value entry
DELETING
Key is absent → Error since no such key	mdbx_del() or mdbx_replace()	Error MDBX_NOTFOUND
Key exist → Delete all values corresponds given key	mdbx_del() with the parameter `data = NULL`	Deletion
Key exist → Delete particular value corresponds given key	mdbx_del() with the parameter `data` filled with the value that wanna to delete, or mdbx_replace() with MDBX_CURRENT + MDBX_NOOVERWRITE and the `old_value` parameter filled with the value that wanna to delete and `new_data = NULL`	Deletion or MDBX_NOTFOUND if no such key-value pair
Delete one value at the current cursor position	mdbx_cursor_del() with MDBX_CURRENT flag	Deletion only the current entry
Delete all values of key at the current cursor position	mdbx_cursor_del() with with MDBX_ALLDUPS flag	Deletion all duplicates of key (all multi-values) at the current cursor position

Typedef Documentation

◆ MDBX_cmp_func

typedef int() MDBX_cmp_func(const MDBX_val *a, const MDBX_val *b) MDBX_CXX17_NOEXCEPT

A callback function used to compare two keys in a database.

See also: mdbx_cmp(); mdbx_get_keycmp(); mdbx_get_datacmp; mdbx_dcmp()

It is recommend not using custom comparison functions, but instead converting the keys to one of the forms that are suitable for built-in comparators (for instance take look to the Value-to-Key functions). The reasons to not using custom comparators are:

The order of records could not be validated without your code. So mdbx_chk utility will reports "wrong order" errors and the -i option is required to suppress ones.
A records could not be ordered or sorted without your code. So mdbx_load utility should be used with -a option to preserve input data order.
However, the custom comparators feature will never be removed. You have been warned but still can use custom comparators knowing about the issues noted above. In this case you should ignore deprecated warnings or define MDBX_DEPRECATED macro to empty to avoid ones.

◆ MDBX_put_flags_t

typedef enum MDBX_put_flags_t MDBX_put_flags_t

Enumeration Type Documentation

◆ MDBX_put_flags_t

enum MDBX_put_flags_t

Data changing flags.

See also: Quick reference for Insert/Update/Delete operations; mdbx_put(); mdbx_cursor_put(); mdbx_replace()

Enumerator
MDBX_UPSERT	Upsertion by default (without any other flags)
MDBX_NOOVERWRITE	For insertion: Don't write if the key already exists.
MDBX_NODUPDATA	Has effect only for MDBX_DUPSORT databases. For upsertion: don't write if the key-value pair already exist. For deletion: remove all values for key.
MDBX_CURRENT	For upsertion: overwrite the current key/data pair. MDBX allows this flag for mdbx_put() for explicit overwrite/update without insertion. For deletion: remove only single entry at the current cursor position.
MDBX_ALLDUPS	Has effect only for MDBX_DUPSORT databases. For deletion: remove all multi-values (aka duplicates) for given key. For upsertion: replace all multi-values for given key with a new one.
MDBX_RESERVE	For upsertion: Just reserve space for data, don't copy it. Return a pointer to the reserved space.
MDBX_APPEND	Data is being appended. Don't split full pages, continue on a new instead.
MDBX_APPENDDUP	Has effect only for MDBX_DUPSORT databases. Duplicate data is being appended. Don't split full pages, continue on a new instead.
MDBX_MULTIPLE	Only for MDBX_DUPFIXED. Store multiple data items in one call.

Function Documentation

◆ mdbx_canary_get()

LIBMDBX_API int mdbx_canary_get	(	const MDBX_txn *	txn,
		MDBX_canary *	canary
	)

Returns fours integers markers (aka "canary") associated with the environment.

See also: mdbx_canary_set()

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	canary	The address of an MDBX_canary structure where the information will be copied.

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

◆ mdbx_canary_put()

LIBMDBX_API int mdbx_canary_put	(	MDBX_txn *	txn,
		const MDBX_canary *	canary
	)

Set integers markers (aka "canary") associated with the environment.

See also: mdbx_canary_get()

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin()
[in]	canary	A optional pointer to MDBX_canary structure for `x`, `y` and `z` values from. If canary is NOT NULL then the `x`, `y` and `z` values will be updated from given canary argument, but the 'v' be always set to the current transaction number if at least one `x`, `y` or `z` values have changed (i.e. if `x`, `y` and `z` have the same values as currently present then nothing will be changes or updated). if canary is NULL then the `v` value will be explicitly update to the current transaction number without changes `x`, `y` nor `z`.

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

◆ mdbx_cmp()

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_cmp	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const MDBX_val *	a,
		const MDBX_val *	b
	)

Compare two keys according to a particular database.

See also: MDBX_cmp_func

This returns a comparison as if the two data items were keys in the specified database.

Warning: There ss a Undefined behavior if one of arguments is invalid.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in]	a	The first item to compare.
[in]	b	The second item to compare.

Returns: < 0 if a < b, 0 if a == b, > 0 if a > b

◆ mdbx_cursor_count()

LIBMDBX_API int mdbx_cursor_count	(	const MDBX_cursor *	cursor,
		size_t *	pcount
	)

Return count of duplicates for current key.

This call is valid for all databases, but reasonable only for that support sorted duplicate data items MDBX_DUPSORT.

Parameters

[in]	cursor	A cursor handle returned by mdbx_cursor_open().
[out]	pcount	Address where the count 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	Cursor is not initialized, or an invalid parameter was specified.

◆ mdbx_cursor_del()

LIBMDBX_API int mdbx_cursor_del	(	MDBX_cursor *	cursor,
		MDBX_put_flags_t	flags
	)

Delete current key/data pair.

This function deletes the key/data pair to which the cursor refers. This does not invalidate the cursor, so operations such as MDBX_NEXT can still be used on it. Both MDBX_NEXT and MDBX_GET_CURRENT will return the same record after this operation.

Parameters

[in]	cursor	A cursor handle returned by mdbx_cursor_open().
[in]	flags	Options for this operation. This parameter must be set to one of the values described here.

MDBX_CURRENT Delete only single entry at current cursor position.
MDBX_ALLDUPS or MDBX_NODUPDATA (supported for compatibility) Delete all of the data items for the current key. This flag has effect only for database(s) was created with MDBX_DUPSORT.

See also: Quick reference for Insert/Update/Delete operations

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_MAP_FULL	The database is full, see mdbx_env_set_mapsize().
MDBX_TXN_FULL	The transaction has too many dirty pages.
MDBX_EACCES	An attempt was made to write in a read-only transaction.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_cursor_get()

LIBMDBX_API int mdbx_cursor_get	(	MDBX_cursor *	cursor,
		MDBX_val *	key,
		MDBX_val *	data,
		MDBX_cursor_op	op
	)

Retrieve by cursor.

This function retrieves key/data pairs from the database. The address and length of the key are returned in the object to which key refers (except for the case of the MDBX_SET option, in which the key object is unchanged), and the address and length of the data are returned in the object to which data refers.

See also: mdbx_get()

Parameters

[in]	cursor	A cursor handle returned by mdbx_cursor_open().
[in,out]	key	The key for a retrieved item.
[in,out]	data	The data of a retrieved item.
[in]	op	A cursor operation MDBX_cursor_op.

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_NOTFOUND	No matching key found.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_cursor_get_batch()

LIBMDBX_API int mdbx_cursor_get_batch	(	MDBX_cursor *	cursor,
		size_t *	count,
		MDBX_val *	pairs,
		size_t	limit,
		MDBX_cursor_op	op
	)

Retrieve multiple non-dupsort key/value pairs by cursor.

This function retrieves multiple key/data pairs from the database without MDBX_DUPSORT option. For MDBX_DUPSORT databases please use MDBX_GET_MULTIPLE and MDBX_NEXT_MULTIPLE.

The number of key and value items is returned in the size_t count refers. The addresses and lengths of the keys and values are returned in the array to which pairs refers.

See also: mdbx_cursor_get()

Parameters

[in]	cursor	A cursor handle returned by mdbx_cursor_open().
[out]	count	The number of key and value item returned, on success it always be the even because the key-value pairs are returned.
[in,out]	pairs	A pointer to the array of key value pairs.
[in]	limit	The size of pairs buffer as the number of items, but not a pairs.
[in]	op	A cursor operation MDBX_cursor_op (only MDBX_FIRST, MDBX_NEXT, MDBX_GET_CURRENT are supported).

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_NOTFOUND	No more key-value pairs are available.
MDBX_ENODATA	The cursor is already at the end of data.
MDBX_RESULT_TRUE	The specified limit is less than the available key-value pairs on the current page/position that the cursor points to.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_cursor_put()

LIBMDBX_API int mdbx_cursor_put	(	MDBX_cursor *	cursor,
		const MDBX_val *	key,
		MDBX_val *	data,
		MDBX_put_flags_t	flags
	)

Store by cursor.

This function stores key/data pairs into the database. The cursor is positioned at the new item, or on failure usually near it.

Parameters

[in]	cursor	A cursor handle returned by mdbx_cursor_open().
[in]	key	The key operated on.
[in,out]	data	The data operated on.
[in]	flags	Options for this operation. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here: MDBX_CURRENT Replace the item at the current cursor position. The key parameter must still be provided, and must match it, otherwise the function return MDBX_EKEYMISMATCH. With combination the MDBX_ALLDUPS will replace all multi-values.

Note: MDBX allows (unlike LMDB) you to change the size of the data and automatically handles reordering for sorted duplicates (see MDBX_DUPSORT).

MDBX_NODUPDATA Enter the new key-value pair only if it does not already appear in the database. This flag may only be specified if the database was opened with MDBX_DUPSORT. The function will return MDBX_KEYEXIST if the key/data pair already appears in the database.
MDBX_NOOVERWRITE Enter the new key/data pair only if the key does not already appear in the database. The function will return MDBX_KEYEXIST if the key already appears in the database, even if the database supports duplicates (MDBX_DUPSORT).
MDBX_RESERVE Reserve space for data of the given size, but don't copy the given data. Instead, return a pointer to the reserved space, which the caller can fill in later - before the next update operation or the transaction ends. This saves an extra memcpy if the data is being generated later. This flag must not be specified if the database was opened with MDBX_DUPSORT.
MDBX_APPEND Append the given key/data pair to the end of the database. No key comparisons are performed. This option allows fast bulk loading when keys are already known to be in the correct order. Loading unsorted keys with this flag will cause a MDBX_KEYEXIST error.
MDBX_APPENDDUP As above, but for sorted dup data.
MDBX_MULTIPLE Store multiple contiguous data elements in a single request. This flag may only be specified if the database was opened with MDBX_DUPFIXED. With combination the MDBX_ALLDUPS will replace all multi-values. The data argument must be an array of two MDBX_val. The iov_len of the first MDBX_val must be the size of a single data element. The iov_base of the first MDBX_val must point to the beginning of the array of contiguous data elements which must be properly aligned in case of database with MDBX_INTEGERDUP flag. The iov_len of the second MDBX_val must be the count of the number of data elements to store. On return this field will be set to the count of the number of elements actually written. The iov_base of the second MDBX_val is unused.

See also: Quick reference for Insert/Update/Delete operations

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_EKEYMISMATCH	The given key value is mismatched to the current cursor position
MDBX_MAP_FULL	The database is full, see mdbx_env_set_mapsize().
MDBX_TXN_FULL	The transaction has too many dirty pages.
MDBX_EACCES	An attempt was made to write in a read-only transaction.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_dbi_sequence()

LIBMDBX_API int mdbx_dbi_sequence	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		uint64_t *	result,
		uint64_t	increment
	)

Sequence generation for a database.

The function allows to create a linear sequence of unique positive integers for each database. The function can be called for a read transaction to retrieve the current sequence value, and the increment must be zero. Sequence changes become visible outside the current write transaction after it is committed, and discarded on abort.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[out]	result	The optional address where the value of sequence before the change will be stored.
[in]	increment	Value to increase the sequence, must be 0 for read-only transactions.

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

Return values

MDBX_RESULT_TRUE Increasing the sequence has resulted in an overflow and therefore cannot be executed.

◆ mdbx_dcmp()

MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int mdbx_dcmp	(	const MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const MDBX_val *	a,
		const MDBX_val *	b
	)

Compare two data items according to a particular database.

See also: MDBX_cmp_func

This returns a comparison as if the two items were data items of the specified database.

Warning: There ss a Undefined behavior if one of arguments is invalid.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in]	a	The first item to compare.
[in]	b	The second item to compare.

Returns: < 0 if a < b, 0 if a == b, > 0 if a > b

◆ mdbx_del()

LIBMDBX_API int mdbx_del	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const MDBX_val *	key,
		const MDBX_val *	data
	)

Delete items from a database.

This function removes key/data pairs from the database.

Note: The data parameter is NOT ignored regardless the database does support sorted duplicate data items or not. If the data parameter is non-NULL only the matching data item will be deleted. Otherwise, if data parameter is NULL, any/all value(s) for specified key will be deleted.

This function will return MDBX_NOTFOUND if the specified key/data pair is not in the database.

See also: Quick reference for Insert/Update/Delete operations

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in]	key	The key to delete from the database.
[in]	data	The data to delete.

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

Return values

MDBX_EACCES	An attempt was made to write in a read-only transaction.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_drop()

LIBMDBX_API int mdbx_drop	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		bool	del
	)

Empty or delete and close a database.

See also: mdbx_dbi_close(); mdbx_dbi_open()

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in]	del	`false` to empty the DB, `true` to delete it from the environment and close the DB handle.

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

◆ mdbx_get()

LIBMDBX_API int mdbx_get	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const MDBX_val *	key,
		MDBX_val *	data
	)

Get items from a database.

This function retrieves key/data pairs from the database. The address and length of the data associated with the specified key are returned in the structure to which data refers. If the database supports duplicate keys (MDBX_DUPSORT) then the first data item for the key will be returned. Retrieval of other items requires the use of mdbx_cursor_get().

Note: The memory pointed to by the returned values is owned by the database. The caller need not dispose of the memory, and may not modify it in any way. For values returned in a read-only transaction any modification attempts will cause a SIGSEGV.; Values returned from the database are valid only until a subsequent update operation, or the end of the transaction.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in]	key	The key to search for in the database.
[in,out]	data	The data corresponding to the key.

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_NOTFOUND	The key was not in the database.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_get_equal_or_great()

LIBMDBX_API int mdbx_get_equal_or_great	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		MDBX_val *	key,
		MDBX_val *	data
	)

Get equal or great item from a database.

Briefly this function does the same as mdbx_get() with a few differences:

Return equal or great (due comparison function) key-value pair, but not only exactly matching with the key.
On success return MDBX_SUCCESS if key found exactly, and MDBX_RESULT_TRUE otherwise. Moreover, for databases with MDBX_DUPSORT flag the data argument also will be used to match over multi-value/duplicates, and MDBX_SUCCESS will be returned only when BOTH the key and the data match exactly.
Updates BOTH the key and the data for pointing to the actual key-value pair inside the database.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in,out]	key	The key to search for in the database.
[in,out]	data	The data corresponding to the key.

Returns: A non-zero error value on failure and MDBX_RESULT_FALSE or MDBX_RESULT_TRUE on success (as described above). Some possible errors are:

Return values

MDBX_THREAD_MISMATCH	Given transaction is not owned by current thread.
MDBX_NOTFOUND	The key was not in the database.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_get_ex()

LIBMDBX_API int mdbx_get_ex	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		MDBX_val *	key,
		MDBX_val *	data,
		size_t *	values_count
	)

Get items from a database and optionally number of data items for a given key.

Briefly this function does the same as mdbx_get() with a few differences:

If values_count is NOT NULL, then returns the count of multi-values/duplicates for a given key.
Updates BOTH the key and the data for pointing to the actual key-value pair inside the database.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in,out]	key	The key to search for in the database.
[in,out]	data	The data corresponding to the key.
[out]	values_count	The optional address to return number of values associated with given key: = 0 - in case MDBX_NOTFOUND error; = 1 - exactly for databases WITHOUT MDBX_DUPSORT; >= 1 for databases WITH MDBX_DUPSORT.

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_NOTFOUND	The key was not in the database.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_put()

LIBMDBX_API int mdbx_put	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const MDBX_val *	key,
		MDBX_val *	data,
		MDBX_put_flags_t	flags
	)

Store items into a database.

This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed (see MDBX_DUPSORT).

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in]	key	The key to store in the database.
[in,out]	data	The data to store.
[in]	flags	Special options for this operation. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here: MDBX_NODUPDATA Enter the new key-value pair only if it does not already appear in the database. This flag may only be specified if the database was opened with MDBX_DUPSORT. The function will return MDBX_KEYEXIST if the key/data pair already appears in the database.

MDBX_NOOVERWRITE Enter the new key/data pair only if the key does not already appear in the database. The function will return MDBX_KEYEXIST if the key already appears in the database, even if the database supports duplicates (see MDBX_DUPSORT). The data parameter will be set to point to the existing item.
MDBX_CURRENT Update an single existing entry, but not add new ones. The function will return MDBX_NOTFOUND if the given key not exist in the database. In case multi-values for the given key, with combination of the MDBX_ALLDUPS will replace all multi-values, otherwise return the MDBX_EMULTIVAL.
MDBX_RESERVE Reserve space for data of the given size, but don't copy the given data. Instead, return a pointer to the reserved space, which the caller can fill in later - before the next update operation or the transaction ends. This saves an extra memcpy if the data is being generated later. MDBX does nothing else with this memory, the caller is expected to modify all of the space requested. This flag must not be specified if the database was opened with MDBX_DUPSORT.
MDBX_APPEND Append the given key/data pair to the end of the database. This option allows fast bulk loading when keys are already known to be in the correct order. Loading unsorted keys with this flag will cause a MDBX_EKEYMISMATCH error.
MDBX_APPENDDUP As above, but for sorted dup data.
MDBX_MULTIPLE Store multiple contiguous data elements in a single request. This flag may only be specified if the database was opened with MDBX_DUPFIXED. With combination the MDBX_ALLDUPS will replace all multi-values. The data argument must be an array of two MDBX_val. The iov_len of the first MDBX_val must be the size of a single data element. The iov_base of the first MDBX_val must point to the beginning of the array of contiguous data elements which must be properly aligned in case of database with MDBX_INTEGERDUP flag. The iov_len of the second MDBX_val must be the count of the number of data elements to store. On return this field will be set to the count of the number of elements actually written. The iov_base of the second MDBX_val is unused.

See also: Quick reference for Insert/Update/Delete operations

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_KEYEXIST	The key/value pair already exists in the database.
MDBX_MAP_FULL	The database is full, see mdbx_env_set_mapsize().
MDBX_TXN_FULL	The transaction has too many dirty pages.
MDBX_EACCES	An attempt was made to write in a read-only transaction.
MDBX_EINVAL	An invalid parameter was specified.

◆ mdbx_replace()

LIBMDBX_API int mdbx_replace	(	MDBX_txn *	txn,
		MDBX_dbi	dbi,
		const MDBX_val *	key,
		MDBX_val *	new_data,
		MDBX_val *	old_data,
		MDBX_put_flags_t	flags
	)

Replace items in a database.

This function allows to update or delete an existing value at the same time as the previous value is retrieved. If the argument new_data equal is NULL zero, the removal is performed, otherwise the update/insert.

The current value may be in an already changed (aka dirty) page. In this case, the page will be overwritten during the update, and the old value will be lost. Therefore, an additional buffer must be passed via old_data argument initially to copy the old value. If the buffer passed in is too small, the function will return MDBX_RESULT_TRUE by setting iov_len field pointed by old_data argument to the appropriate value, without performing any changes.

For databases with non-unique keys (i.e. with MDBX_DUPSORT flag), another use case is also possible, when by old_data argument selects a specific item from multi-value/duplicates with the same key for deletion or update. To select this scenario in flags should simultaneously specify MDBX_CURRENT and MDBX_NOOVERWRITE. This combination is chosen because it makes no sense, and thus allows you to identify the request of such a scenario.

Parameters

[in]	txn	A transaction handle returned by mdbx_txn_begin().
[in]	dbi	A database handle returned by mdbx_dbi_open().
[in]	key	The key to store in the database.
[in]	new_data	The data to store, if NULL then deletion will be performed.
[in,out]	old_data	The buffer for retrieve previous value as describe above.
[in]	flags	Special options for this operation. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described in mdbx_put() description above, and additionally (MDBX_CURRENT \| MDBX_NOOVERWRITE) combination for selection particular item from multi-value/duplicates.

See also: Quick reference for Insert/Update/Delete operations

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

Modules

Classes

Typedefs

Enumerations

Functions

Detailed Description

Quick Reference for Insert/Update/Delete operations

Databases with UNIQUE keys

Databases with NON-UNIQUE keys

Typedef Documentation

◆ MDBX_cmp_func

◆ MDBX_put_flags_t

Enumeration Type Documentation

◆ MDBX_put_flags_t

Function Documentation

◆ mdbx_canary_get()

◆ mdbx_canary_put()

◆ mdbx_cmp()

◆ mdbx_cursor_count()

◆ mdbx_cursor_del()

◆ mdbx_cursor_get()

◆ mdbx_cursor_get_batch()

◆ mdbx_cursor_put()

◆ mdbx_dbi_sequence()

◆ mdbx_dcmp()

◆ mdbx_del()

◆ mdbx_drop()

◆ mdbx_get()

◆ mdbx_get_equal_or_great()

◆ mdbx_get_ex()

◆ mdbx_put()

◆ mdbx_replace()