Function mdb_cursor_put

pub unsafe extern "C" fn mdb_cursor_put(
    cursor: *mut MDB_cursor,
    key: *mut MDB_val,
    data: *mut MDB_val,
    flags: c_uint,
) -> c_int

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.

Note: Earlier documentation incorrectly said errors would leave the state of the cursor unchanged.

Arguments

• cursor (direction in) - A cursor handle returned by #mdb_cursor_open()
• key (direction in) - The key operated on.
• data (direction in) - The data operated on.
• flags (direction in) - Options for this operation. This parameter must be set to 0 or one of the values described here.

• #MDB_CURRENT - replace the item at the current cursor position. The **key** parameter must still be provided, and must match it. If using sorted duplicates (#MDB_DUPSORT) the data item must still sort into the same place. This is intended to be used when the new data is the same size as the old. Otherwise it will simply perform a delete of the old record followed by an insert.
• #MDB_NODUPDATA - enter the new key/data pair only if it does not already appear in the database. This flag may only be specified if the database was opened with #MDB_DUPSORT. The function will return #MDB_KEYEXIST if the key/data pair already appears in the database.
• #MDB_NOOVERWRITE - enter the new key/data pair only if the key does not already appear in the database. The function will return #MDB_KEYEXIST if the key already appears in the database, even if the database supports duplicates (#MDB_DUPSORT).
• #MDB_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 #MDB_DUPSORT.
• #MDB_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 #MDB_KEYEXIST error.
• #MDB_APPENDDUP - as above, but for sorted dup data.
• #MDB_MULTIPLE - store multiple contiguous data elements in a single request. This flag may only be specified if the database was opened with #MDB_DUPFIXED. The **data** argument must be an array of two MDB_vals. The mv_size of the first MDB_val must be the size of a single data element. The mv_data of the first MDB_val must point to the beginning of the array of contiguous data elements. The mv_size of the second MDB_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 mv_data of the second MDB_val is unused.

# Returns

A non-zero error value on failure and 0 on success. Some possible errors are:

• #MDB_MAP_FULL - the database is full, see #mdb_env_set_mapsize().
• #MDB_TXN_FULL - the transaction has too many dirty pages.
• EACCES - an attempt was made to write in a read-only transaction.
• EINVAL - an invalid parameter was specified.