mdb_cursor_put function

int mdb_cursor_put(
  1. Pointer<MDB_cursor> cursor,
  2. Pointer<MDB_val> key,
  3. Pointer<MDB_val> data,
  4. int flags,
)

@brief 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. @paramin cursor A cursor handle returned by #mdb_cursor_open() @paramin key The key operated on. @paramin data The data operated on. @paramin flags 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 \b 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 \b 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.
@return 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.

Implementation

@ffi.FfiNative<
    ffi.Int Function(ffi.Pointer<MDB_cursor>, ffi.Pointer<MDB_val>,
        ffi.Pointer<MDB_val>, ffi.UnsignedInt)>('mdb_cursor_put')
external int mdb_cursor_put(
  ffi.Pointer<MDB_cursor> cursor,
  ffi.Pointer<MDB_val> key,
  ffi.Pointer<MDB_val> data,
  int flags,
);