Group c_crud

Classes

Type	Name
struct	MDBX_cache_entry_t Lightweight transparent cache entry structure used by mdbx_cache_get() .
struct	MDBX_cache_result_t Pair of error code and cache status as a result of mdbx_cache_get() .
struct	MDBX_canary The four integer markers (aka "canary") associated with the environment.

Public Types

Type	Name
enum	MDBX_bunch_action_t Modes for deleting bunches of neighboring items with self-documenting names.
enum	MDBX_cache_status_t Cache entry status returned by mdbx_cache_get() .
typedef int(*	MDBX_cmp_func A callback function used to compare two keys in a table.
typedef int(*	MDBX_predicate_func The type of predicative callback functions used by mdbx_cursor_scan() andmdbx_cursor_scan_from() to probing key-value pairs.
typedef int(*	MDBX_preserve_func A data preservation callback for using within mdbx_replace_ex() .
enum	MDBX_put_flags_t Data changing flags.

Public Functions

Type	Name
LIBMDBX_API MDBX_cache_result_t	mdbx_cache_get (const MDBX_txn * txn, MDBX_dbi dbi, const MDBX_val * key, MDBX_val * data, volatile MDBX_cache_entry_t * entry) Gets items from a table using cache including multithreaded cases.
LIBMDBX_API MDBX_cache_result_t	mdbx_cache_get_SingleThreaded (const MDBX_txn * txn, MDBX_dbi dbi, const MDBX_val * key, MDBX_val * data, MDBX_cache_entry_t * entry) Gets items from a table using cache within single-thread cases only.
void	mdbx_cache_init (MDBX_cache_entry_t * entry) Initializes the cache entry before the first use.
LIBMDBX_API int	mdbx_canary_get (const MDBX_txn * txn, MDBX_canary * canary) Returns four integer markers (aka "canary") associated with the environment.
LIBMDBX_API int	mdbx_canary_put (MDBX_txn * txn, const MDBX_canary * canary) Set integers markers (aka "canary") associated with the environment.
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 table.
LIBMDBX_API int	mdbx_cursor_bunch_delete (MDBX_cursor * cursor, MDBX_bunch_action_t action, uint64_t * number_of_affected) Quickly removes bunches of neighboring items.
LIBMDBX_API int	mdbx_cursor_count (const MDBX_cursor * cursor, size_t * count) Return count values (aka duplicates) for current key.
LIBMDBX_API int	mdbx_cursor_count_ex (const MDBX_cursor * cursor, size_t * count, MDBX_stat * stat, size_t bytes) Return count values (aka duplicates) and nested b-tree statistics for current key.
LIBMDBX_API int	mdbx_cursor_del (MDBX_cursor * cursor, MDBX_put_flags_t flags) Delete current key/data pair.
LIBMDBX_API int	mdbx_cursor_delete_range (MDBX_cursor * begin, MDBX_cursor * end, bool end_including, uint64_t * number_of_affected) Quickly removes given range of items.
LIBMDBX_API int	mdbx_cursor_get (MDBX_cursor * cursor, MDBX_val * key, MDBX_val * data, MDBX_cursor_op op) Retrieve by cursor.
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.
LIBMDBX_API int	mdbx_cursor_put (MDBX_cursor * cursor, const MDBX_val * key, MDBX_val * data, MDBX_put_flags_t flags) Store by cursor.
LIBMDBX_API int	mdbx_cursor_scan (MDBX_cursor * cursor, MDBX_predicate_func predicate, void * context, MDBX_cursor_op start_op, MDBX_cursor_op turn_op, void * arg) Scans the table using the passed predicate, reducing the associated overhead.
LIBMDBX_API int	mdbx_cursor_scan_from (MDBX_cursor * cursor, MDBX_predicate_func predicate, void * context, MDBX_cursor_op from_op, MDBX_val * from_key, MDBX_val * from_value, MDBX_cursor_op turn_op, void * arg) Scans a table using the given predicate, starting with the given key-value pair, and reduces an associated overhead.
LIBMDBX_API int	mdbx_dbi_sequence (MDBX_txn * txn, MDBX_dbi dbi, uint64_t * result, uint64_t increment) Sequence generation for a table.
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 table.
LIBMDBX_API int	mdbx_del (MDBX_txn * txn, MDBX_dbi dbi, const MDBX_val * key, const MDBX_val * data) Delete items from a table.
LIBMDBX_API int	mdbx_drop (MDBX_txn * txn, MDBX_dbi dbi, bool del) Empty or delete and close a table.
LIBMDBX_API int	mdbx_get (const MDBX_txn * txn, MDBX_dbi dbi, const MDBX_val * key, MDBX_val * data) Get items from a table.
LIBMDBX_API int	mdbx_get_equal_or_great (const MDBX_txn * txn, MDBX_dbi dbi, MDBX_val * key, MDBX_val * data) Get equal or greater item from a table.
LIBMDBX_API int	mdbx_get_ex (const MDBX_txn * txn, MDBX_dbi dbi, MDBX_val * key, MDBX_val * data, size_t * values_count) Get items from a table and optionally number of data items for a given key.
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 table.
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) Replaces item in a table.
LIBMDBX_API int	mdbx_replace_ex (MDBX_txn * txn, MDBX_dbi dbi, const MDBX_val * key, MDBX_val * new_data, MDBX_val * old_data, MDBX_put_flags_t flags, MDBX_preserve_func preserver, void * preserver_context) Replaces item in a table using preservation callback for an original data.

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.

Tables with UNIQUE keys

In tables 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 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

Tables with NON-UNIQUE keys

In tables created with the MDBX_DUPSORT (Sorted Duplicates) option, keys may be non unique. Such non-unique keys in a key-value table 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 MDBX_ALLDUPS flag	Deletion all duplicates of key (all multi-values) at the current cursor position

Public Types Documentation

enum MDBX_bunch_action_t

Modes for deleting bunches of neighboring items with self-documenting names.

enum MDBX_bunch_action_t {
    MDBX_DELETE_CURRENT_VALUE,
    MDBX_DELETE_CURRENT_MULTIVAL_BEFORE_EXCLUDING,
    MDBX_DELETE_CURRENT_MULTIVAL_BEFORE_INCLUDING,
    MDBX_DELETE_CURRENT_MULTIVAL_AFTER_INCLUDING,
    MDBX_DELETE_CURRENT_MULTIVAL_AFTER_EXCLUDING,
    MDBX_DELETE_CURRENT_MULTIVAL_ALL,
    MDBX_DELETE_BEFORE_EXCLUDING,
    MDBX_DELETE_BEFORE_INCLUDING,
    MDBX_DELETE_AFTER_INCLUDING,
    MDBX_DELETE_AFTER_EXCLUDING,
    MDBX_DELETE_WHOLE
};

The EXCLUDING and INCLUDING suffixes mean correspondingly excluding and including deletion items in the current cursor position, and so forth.

See also: mdbx_cursor_bunch_delete()

enum MDBX_cache_status_t

Cache entry status returned by mdbx_cache_get() .

enum MDBX_cache_status_t {
    MDBX_CACHE_ERROR = -3,
    MDBX_CACHE_BEHIND = -2,
    MDBX_CACHE_UNABLE = -1,
    MDBX_CACHE_RACE = 0,
    MDBX_CACHE_DIRTY = 1,
    MDBX_CACHE_HIT = 2,
    MDBX_CACHE_CONFIRMED = 3,
    MDBX_CACHE_REFRESHED = 4
};

See also: MDBX_cache_entry

See also: mdbx_cache_init()

typedef MDBX_cmp_func

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

typedef int(* MDBX_cmp_func) (const MDBX_val *a, const MDBX_val *b) noexcept;

See also: mdbx_cmp()

See also: mdbx_get_keycmp()

See also: mdbx_get_datacmp

See also: mdbx_dcmp()

Deprecated

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.

typedef MDBX_predicate_func

The type of predicative callback functions used by mdbx_cursor_scan() andmdbx_cursor_scan_from() to probing key-value pairs.

typedef int(* MDBX_predicate_func) (void *context, MDBX_val *key, MDBX_val *value, void *arg) noexcept;

Parameters:

context A pointer to the context with the necessary information for evaluation, which is fully prepared and controlled by you.
key The key for evaluation by a callback function.
value The value for evaluation by a callback function.
arg An auxiliary argument to the predicative function, which is fully prepared and controlled by you.

Returns:

The result of checking whether the transmitted key-value pair matches the desired goal. Either, an error code that interrupts the scan and is returned unchanged as a result from the mdbx_cursor_scan() or mdbx_cursor_scan_from() functions.

Return value:

MDBX_RESULT_TRUE if the given key-value pair matches the one you are looking for, andthe scan should be completed.
MDBX_RESULT_FALSE if the given key-value pair does NOT match the one you are looking for, and scanning should continue.
OTHERWISE any other value other than MDBX_RESULT_TRUE and MDBX_RESULT_FALSE is considered an error indicator and is returned unchanged as a scan result.

See also: mdbx_cursor_scan()

See also: mdbx_cursor_scan_from()

typedef MDBX_preserve_func

A data preservation callback for using within mdbx_replace_ex() .

typedef int(* MDBX_preserve_func) (void *context, MDBX_val *target, const void *src, size_t bytes);

enum MDBX_put_flags_t

Data changing flags.

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)
};

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

See also: mdbx_put()

See also: mdbx_cursor_put()

See also: mdbx_replace()

Public Functions Documentation

function mdbx_cache_get

Gets items from a table using cache including multithreaded cases.

LIBMDBX_API  MDBX_cache_result_t mdbx_cache_get (
    const MDBX_txn * txn,
    MDBX_dbi dbi,
    const MDBX_val * key,
    MDBX_val * data,
    volatile MDBX_cache_entry_t * entry
)

The essence of this "caching" is using a cached information to check as quickly as possible whether the data has changed or not, with early exit when searching though a DB. For this a petty version information is stored in a MDBX_cache_entry_t structure, along with the offset to the "cached" data inside the memory-mapped database file. Instead of a full B-tree search it stops when reaches a DB page that has not been modified after the last check. Thus a minimum number of steps are performed which provides dramatic acceleration in many cases.

Note:

This function is supports multi-threaded cases and automatically resolves collisions using lockfree approach, nonetheless MDBX_NOSTICKYTHREADS mode is required to use it within a different threads.

See also: MDBX_cache_entry_t

See also: mdbx_cache_init()

See also: mdbx_get()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
key The key to search for in the table.
data The data corresponding to the key.
entry The cache entry corresponding to the key.

Returns:

The MDBX_cache_result_t with a pair of the error codes for getting a data and the cache entry processing both.

function mdbx_cache_get_SingleThreaded

Gets items from a table using cache within single-thread cases only.

LIBMDBX_API  MDBX_cache_result_t mdbx_cache_get_SingleThreaded (
    const MDBX_txn * txn,
    MDBX_dbi dbi,
    const MDBX_val * key,
    MDBX_val * data,
    MDBX_cache_entry_t * entry
)

The essence of this "caching" is using a cached information to check as quickly as possible whether the data has changed or not, with early exit when searching though a DB. For this a petty version information is stored in a MDBX_cache_entry_t structure, along with the offset to the "cached" data inside the memory-mapped database file. Instead of a full B-tree search it stops when reaches a DB page that has not been modified after the last check. Thus a minimum number of steps are performed which provides dramatic acceleration in many cases.

Note:

This function is intended to be used with a given cache entry only in single-threaded cases, otherwise behaviour is undefined.

See also: mdbx_cache_get()

See also: MDBX_cache_entry_t

See also: mdbx_cache_init()

See also: mdbx_get()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
key The key to search for in the table.
data The data corresponding to the key.
entry The cache entry corresponding to the key.

Returns:

The MDBX_cache_result_t with a pair of the error codes for getting a data and the cache entry processing both.

function mdbx_cache_init

Initializes the cache entry before the first use.

inline void mdbx_cache_init (
    MDBX_cache_entry_t * entry
)

See also: MDBX_cache_entry

See also: mdbx_cache_get()

function mdbx_canary_get

Returns four integer markers (aka "canary") associated with the environment.

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

See also: mdbx_canary_put()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
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.

function mdbx_canary_put

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

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

See also: mdbx_canary_get()

Parameters:

txn A transaction handle returned by mdbx_txn_begin()
canary An optional pointer to a 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.

function mdbx_cmp

Compare two keys according to a particular table.

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

See also: MDBX_cmp_func This returns a comparison as if the two data items were keys in the specified table.

Warning:

There is a Undefined behavior if one of arguments is invalid.

Parameters:

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

Returns:

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

function mdbx_cursor_bunch_delete

Quickly removes bunches of neighboring items.

LIBMDBX_API int mdbx_cursor_bunch_delete (
    MDBX_cursor * cursor,
    MDBX_bunch_action_t action,
    uint64_t * number_of_affected
)

Performs massive deletion much faster by cutting whole pages and branches with will deleted elements from the B+tree structure.

See also: mdbx_cursor_delete_range()

See also: MDBX_bunch_action_t

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().
action The requested deletion action as the one value of MDBX_bunch_action_t.
number_of_affected Address to store the result number of removed items.

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_ENODATA The given cursor is not positioned to a data.
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.

function mdbx_cursor_count

Return count values (aka duplicates) for current key.

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

See also: mdbx_cursor_count_ex() This call is valid for all tables, but reasonable only for that support sorted duplicate data items MDBX_DUPSORT.

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().
count Address where the count will be stored.

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Cursor is not initialized, or an invalid parameter was specified.

function mdbx_cursor_count_ex

Return count values (aka duplicates) and nested b-tree statistics for current key.

LIBMDBX_API int mdbx_cursor_count_ex (
    const MDBX_cursor * cursor,
    size_t * count,
    MDBX_stat * stat,
    size_t bytes
)

See also: mdbx_dbi_stat

See also: mdbx_dbi_dupsort_depthmask

See also: mdbx_cursor_count This call is valid for all tables, but reasonable only for that support sorted duplicate data items MDBX_DUPSORT.

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().
count Address where the count will be stored.
stat The address of an MDBX_stat structure where the statistics of a nested b-tree will be copied.
bytes The size of MDBX_stat.

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_EINVAL Cursor is not initialized, or an invalid parameter was specified.

function mdbx_cursor_del

Delete current key/data pair.

LIBMDBX_API int mdbx_cursor_del (
    MDBX_cursor * cursor,
    MDBX_put_flags_t flags
)

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:

cursor A cursor handle returned by mdbx_cursor_open().
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 table(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 value:

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.

function mdbx_cursor_delete_range

Quickly removes given range of items.

LIBMDBX_API int mdbx_cursor_delete_range (
    MDBX_cursor * begin,
    MDBX_cursor * end,
    bool end_including,
    uint64_t * number_of_affected
)

Performs mass deletion of elements between positions of given cursors pair much faster, cutting out entire pages and branches from the B+ tree structure.

Parameters:

begin Defines the beginning of the range to delete, or can be NULL to delete starting the first item.
end Defines the ending of the range to delete, or can be NULL to delete up to the last item.
end_including The boolean flag determines whether the end of the given interval should be included in the range to be deleted.
number_of_affected Address to store the result number of removed items.

See also: mdbx_cursor_bunch_delete()

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_ENODATA One or both of the given cursor(s) is not positioned to a data, or position of begin cursor is after the end cursor.
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.

function mdbx_cursor_get

Retrieve by cursor.

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

This function retrieves key/data pairs from the table. 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()

Note:

The memory pointed to by the returned values is owned by the database. The caller MUST not dispose of the memory, and MUST not modify it in any way regardless in a read-only nor read-write transactions! For case a database opened without the MDBX_WRITEMAP modification attempts likely will cause a SIGSEGV. However, when a database opened with the MDBX_WRITEMAP or in case values returned inside read-write transaction are located on a "dirty" (modified and pending to commit) pages, such modification will silently accepted and likely will lead to DB and/or data corruption.

Parameters:

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

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_NOTFOUND No matching key found.
MDBX_EINVAL An invalid parameter was specified.

function mdbx_cursor_get_batch

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

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

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

The number of key and value items is returned in the 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()

See also: mdbx_cursor_scan()

See also: mdbx_cursor_scan_from()

Note:

The memory pointed to by the returned values is owned by the database. The caller MUST not dispose of the memory, and MUST not modify it in any way regardless in a read-only nor read-write transactions! For case a database opened without the MDBX_WRITEMAP modification attempts likely will cause a SIGSEGV. However, when a database opened with the MDBX_WRITEMAP or in case values returned inside read-write transaction are located on a "dirty" (modified and pending to commit) pages, such modification will silently accepted and likely will lead to DB and/or data corruption.

Parameters:

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

Returns:

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

Return value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_NOTFOUND No any key-value pairs are available.
MDBX_ENODATA The cursor is already at the end of data.
MDBX_RESULT_TRUE The returned chunk is the last one, and there are no pairs left.
MDBX_EINVAL An invalid parameter was specified.

function mdbx_cursor_put

Store by cursor.

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

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

Parameters:

cursor A cursor handle returned by mdbx_cursor_open().
key The key operated on.
data The data operated on.
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 table. This flag may only be specified if the table was opened with MDBX_DUPSORT. The function will return MDBX_KEYEXIST if the key/data pair already appears in the table.
MDBX_NOOVERWRITE Enter the new key/data pair only if the key does not already appear in the table. The function will return MDBX_KEYEXIST if the key already appears in the table, even if the table 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 table was opened with MDBX_DUPSORT.
MDBX_APPEND Append the given key/data pair to the end of the table. 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 table 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 table 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 value:

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.

function mdbx_cursor_scan

Scans the table using the passed predicate, reducing the associated overhead.

LIBMDBX_API int mdbx_cursor_scan (
    MDBX_cursor * cursor,
    MDBX_predicate_func predicate,
    void * context,
    MDBX_cursor_op start_op,
    MDBX_cursor_op turn_op,
    void * arg
)

Implements functionality similar to the std::find_if<>() template using a cursor and a custom predicative function, while reducing on related overhead costs, including not performing some checks inside the record iteration cycle and potentially reducing the number of DSO cross-border calls.

The function accepts a cursor, which should be bound to some transaction and a table DBI-descriptor, performs the initial cursor positioning determined by the start_op argument. Next, each key-value pair is probed using the predicate function provided by you, and then, if necessary, move on to the next using the turn_op operation, until one of the four events occurs: * the end of data is reached; * an error occurs when positioning the cursor; * the probing function returns MDBX_RESULT_TRUE, signaling the need to stop further scanning.; * the probing function returns a value other than MDBX_RESULT_FALSE or MDBX_RESULT_TRUE, signaling an error.

Parameters:

cursor The cursor for performing the scan operation associated with the active transaction and the table's DBI descriptor. For instance, a cursor created using mdbx_cursor_open().
predicate A predicative function for probing key-value pairs, see MDBX_predicate_func for more details.
context A pointer to the context with an auxiliary information for probing, which is fully prepared and controlled by you.
start_op The initial cursor positioning operation, see MDBX_cursor_op for more details. To scan without changing the initial cursor position, use MDBX_GET_CURRENT. Acceptable values are MDBX_FIRST, MDBX_FIRST_DUP, MDBX_LAST, MDBX_LAST_DUP, MDBX_GET_CURRENT, and also MDBX_GET_MULTIPLE.
turn_op The operation of positioning the cursor to move to the next element. Acceptable values are MDBX_NEXT, MDBX_NEXT_DUP, MDBX_NEXT_NODUP, MDBX_PREV, MDBX_PREV_DUP, MDBX_PREV_NODUP, and also MDBX_NEXT_MULTIPLE and MDBX_PREV_MULTIPLE.
arg An auxiliary argument to the predicative function, which is fully prepared and controlled by you.

Note:

When using MDBX_GET_MULTIPLE, MDBX_NEXT_MULTIPLE, or MDBX_PREV_MULTIPLE, carefully consider the batch specifics of passing values through the parameters of the predicative function.

See also: MDBX_predicate_func

See also: mdbx_cursor_scan_from()

See also: mdbx_cursor_get_batch()

Returns:

The result of the scan operation, or an error code.

Return value:

MDBX_RESULT_TRUE if a key-value pair is found for which the predicative function returned MDBX_RESULT_TRUE.
MDBX_RESULT_FALSE if a suitable key-value pair is NOT found, the end of the data has been reached during the search, or there is no data to search for.
OTHERWISE any other value other than MDBX_RESULT_TRUE and MDBX_RESULT_FALSE is an error code during positioning the cursor or a user-defined code for stopping the search or an user-defined error.

function mdbx_cursor_scan_from

Scans a table using the given predicate, starting with the given key-value pair, and reduces an associated overhead.

LIBMDBX_API int mdbx_cursor_scan_from (
    MDBX_cursor * cursor,
    MDBX_predicate_func predicate,
    void * context,
    MDBX_cursor_op from_op,
    MDBX_val * from_key,
    MDBX_val * from_value,
    MDBX_cursor_op turn_op,
    void * arg
)

The function accepts a cursor, which should be bound to some transaction and a table DBI-descriptor, performs the initial cursor positioning determined by the from_op argument, as well as the arguments from_key and from_value. Next, each key-value pair is probed using the given predicative function predict, and then, if necessary, move on to the next using the turn_op operation, until one of the four events occurs:

the end of data is reached;
an error occurs when positioning the cursor;
the probing function returns MDBX_RESULT_TRUE, signaling the need to stop further scanning;
the probing function returns a value other than MDBX_RESULT_FALSE or MDBX_RESULT_TRUE, signaling an error.

Parameters:

cursor The cursor for performing the scan operation associated with the active transaction and the table's DBI descriptor. For instance, a cursor created using mdbx_cursor_open().
predicate A predicative function for probing key-value pairs, see MDBX_predicate_func for more details.
context A pointer to the context with an auxiliary information for probing, which is fully prepared and controlled by you.
from_op The operation of positioning the cursor to the initial position, for more details, see MDBX_cursor_op. Acceptable values are MDBX_GET_BOTH, MDBX_GET_BOTH_RANGE, MDBX_SET_KEY, 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, and also MDBX_GET_MULTIPLE.
from_key A pointer to the key used both for initial positioning and for subsequent steps.
from_value A pointer to the value used both for initial positioning and for subsequent steps.
turn_op The operation of positioning the cursor to move to the next element. Acceptable values are MDBX_NEXT, MDBX_NEXT_DUP, MDBX_NEXT_NODUP, MDBX_PREV, MDBX_PREV_DUP, MDBX_PREV_NODUP, and also MDBX_NEXT_MULTIPLE and MDBX_PREV_MULTIPLE.
arg An auxiliary argument to the predicative function, which is fully prepared and controlled by you.

Note:

When using MDBX_GET_MULTIPLE, MDBX_NEXT_MULTIPLE, or MDBX_PREV_MULTIPLE, carefully consider the batch specifics of passing values through the parameters of the predicative function.

See also: MDBX_predicate_func

See also: mdbx_cursor_scan()

See also: mdbx_cursor_get_batch()

Returns:

The result of the scan operation, or an error code.

Return value:

MDBX_RESULT_TRUE if a key-value pair is found for which the predicative function returned MDBX_RESULT_TRUE.
MDBX_RESULT_FALSE if a suitable key-value pair is NOT found, the end of the data has been reached during the search, or there is no data to search for.
OTHERWISE any other value other than MDBX_RESULT_TRUE and MDBX_RESULT_FALSE is an error code during positioning the cursor or a user-defined code for stopping the search or an user-defined error.

function mdbx_dbi_sequence

Sequence generation for a table.

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

The function provides a linear sequence of unique positive integers for each table with acquire/allocate semantics. The function can be called for a read transaction to retrieve the current sequence value while the increment must be zero. Sequence changes become visible outside the current write transaction after it is committed, and discarded on abort.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
result The optional address where the value of sequence before the change will be stored.
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 value:

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

function mdbx_dcmp

Compare two data items according to a particular table.

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

See also: MDBX_cmp_func This returns a comparison as if the two items were data items of the specified table.

Warning:

There is a Undefined behavior if one of arguments is invalid.

Parameters:

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

Returns:

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

function mdbx_del

Delete items from a table.

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

This function removes key/data pairs from the table.

Note:

The data parameter is NOT ignored regardless the table 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 table.

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

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
key The key to delete from the table.
data The data to delete.

Returns:

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

Return value:

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

function mdbx_drop

Empty or delete and close a table.

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

See also: mdbx_dbi_close()

See also: mdbx_dbi_open()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
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.

function mdbx_get

Get items from a table.

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

This function retrieves key/data pairs from the table. The address and length of the data associated with the specified key are returned in the structure to which data refers. If the table 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 table. The caller MUST not dispose of the memory, and MUST not modify it in any way regardless in a read-only nor read-write transactions! For case a table opened without the MDBX_WRITEMAP modification attempts likely will cause a SIGSEGV. However, when a table opened with the MDBX_WRITEMAP or in case values returned inside read-write transaction are located on a "dirty" (modified and pending to commit) pages, such modification will silently accepted and likely will lead to DB and/or data corruption.

Note:

Values returned from the table are valid only until a subsequent update operation, or the end of the transaction.

See also: mdbx_cache_get()

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
key The key to search for in the table.
data The data corresponding to the key.

Returns:

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

Return value:

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

function mdbx_get_equal_or_great

Get equal or greater item from a table.

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

Briefly this function does the same as mdbx_get() with a few differences: * Return an equal-or-great (by the 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 tables 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 table.

Parameters:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
key The key to search for in the table.
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 value:

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

function mdbx_get_ex

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

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

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 table.

Parameters:

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

Returns:

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

Return value:

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

function mdbx_put

Store items into a table.

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

This function stores key/data pairs in the table. 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:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
key The key to store in the table.
data The data to store.
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 table. This flag may only be specified if the table was opened with MDBX_DUPSORT. The function will return MDBX_KEYEXIST if the key/data pair already appears in the table.
MDBX_NOOVERWRITE Enter the new key/data pair only if the key does not already appear in the table. The function will return MDBX_KEYEXIST if the key already appears in the table, even if the table 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 table. 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 table was opened with MDBX_DUPSORT.
MDBX_APPEND Append the given key/data pair to the end of the table. 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 table 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 table 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 value:

MDBX_THREAD_MISMATCH Given transaction is not owned by current thread.
MDBX_KEYEXIST The key/value pair already exists in the table.
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.

function mdbx_replace

Replaces item in a table.

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
)

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 tables 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:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
key The key to store in the table.
new_data The data to store, if NULL then deletion will be performed.
old_data The buffer for retrieve previous value as describe above.
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: mdbx_replace_ex()

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

Returns:

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

function mdbx_replace_ex

Replaces item in a table using preservation callback for an original data.

LIBMDBX_API int mdbx_replace_ex (
    MDBX_txn * txn,
    MDBX_dbi dbi,
    const MDBX_val * key,
    MDBX_val * new_data,
    MDBX_val * old_data,
    MDBX_put_flags_t flags,
    MDBX_preserve_func preserver,
    void * preserver_context
)

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. In such cases, the given preservation callback will be used to save the source data, that, at your discretion, can perform copying, other necessary actions, or return a special error code.

If an original data needs to be saved then the passed preservation callback will be called with old_data as a target parameter, and src with bytes for original data. Such callback should check necessary conditions, perform appropriate action and return corresponding error code, which will be returned from function as is. For example, for behavior similar to mdbx_replace(), the callback should check if there provided buffer size is enough, then either copy the data or return MDBX_RESULT_TRUE.

For tables 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:

txn A transaction handle returned by mdbx_txn_begin().
dbi A table handle returned by mdbx_dbi_open().
key The key to store in the table.
new_data The data to store, if NULL then deletion will be performed.
old_data The buffer for retrieve previous value as describe above.
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.
preserver The callback to preserve an original data in case it is on a dirty page and could be overwritten.
preserver_context The optional context pointer for use within the preserving callback.

See also: mdbx_replace_ex()

See also: MDBX_preserve_func

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

Returns:

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