mdb_copy(3)

📦
version 0.9.35 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 mdb_copy(3) — Copy Flags 💖

okay bestie, this is the Library Functions Manual page for mdb_copy(3), and the vibe is Copy Flags. We're doing part one of eight, so hydrate and let's get into it. ✨

✨ NAME ✨

mdb_copy - Copy Flags

🌸 SYNOPSIS 🌸

📚 Topics 📚

  • Return Codes — yep, there's a whole topic list and it points at Return Codes. We'll get there, bestie. 💅

🏗️ Data Structures 🏗️

  • struct MDB_stat — Statistics for a database in the environment. 📊
  • struct MDB_envinfo — Information about the environment. 🌍

🪄 Macros 🪄

  • #define MDB_CP_COMPACT 0x01 — Compacting copy: Omit free space from copy, and renumber all pages sequentially. ✨
  • #define mdb_open(txn, name, flags, dbi) — Value:
mdb_dbi_open(txn,name,flags,dbi)

Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project. 🛠️

  • #define mdb_close(env, dbi) — Value:
mdb_dbi_close(env,dbi)

Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project. 🛠️

🧬 Typedefs 🧬

  • typedef void MDB_assert_func(MDB_env *env, const char *msg) — A callback function for most LMDB assert() failures, called before printing the message and aborting. 😭
    • Parameters:
      • env — An environment handle returned by mdb_env_create().
      • msg — The assertion message, not including newline.
  • typedef int MDB_msg_func(const char *msg, void *ctx) — A callback function used to print a message from the library. 📨
    • Parameters:
      • msg — The string to be printed.
      • ctx — An arbitrary context pointer for the callback.
    • Returns:
      • < 0 on failure, >= 0 on success. ✅

🔮 Enumerations 🔮

  • enum MDB_cursor_op { MDB_FIRST, MDB_FIRST_DUP, MDB_GET_BOTH, MDB_GET_BOTH_RANGE, MDB_GET_CURRENT, MDB_GET_MULTIPLE, MDB_LAST, MDB_LAST_DUP, MDB_NEXT, MDB_NEXT_DUP, MDB_NEXT_MULTIPLE, MDB_NEXT_NODUP, MDB_PREV, MDB_PREV_DUP, MDB_PREV_NODUP, MDB_SET, MDB_SET_KEY, MDB_SET_RANGE, MDB_PREV_MULTIPLE } — Cursor Get operations. This is the set of all operations for retrieving data using a cursor. 🎯

🛠️ Functions 🛠️

  • char * mdb_version (int *major, int *minor, int *patch) — Returns the LMDB library version information. 🏷️
  • char * mdb_strerror (int err) — Returns a string describing a given error code. 🚨
  • int mdb_env_create (MDB_env **env) — Creates an LMDB environment handle. 🌱
  • int mdb_env_open (MDB_env *env, const char *path, unsigned int flags, mdb_mode_t mode) — Opens an environment handle. 🚪
  • int mdb_env_copy (MDB_env *env, const char *path) — Copies an LMDB environment to the specified path. 📁
  • int mdb_env_copyfd (MDB_env *env, mdb_filehandle_t fd) — Copies an LMDB environment to the specified file descriptor. 📄
  • int mdb_env_copy2 (MDB_env *env, const char *path, unsigned int flags) — Copies an LMDB environment to the specified path, with options. 📁✨
  • int mdb_env_copyfd2 (MDB_env *env, mdb_filehandle_t fd, unsigned int flags) — Copies an LMDB environment to the specified file descriptor, with options. 📄✨
  • int mdb_env_stat (MDB_env *env, MDB_stat *stat) — Returns statistics about the LMDB environment. 📊
  • int mdb_env_info (MDB_env *env, MDB_envinfo *stat) — Returns information about the LMDB environment. ℹ️
  • int mdb_env_sync (MDB_env *env, int force) — Flushes the data buffers to disk. 💾
  • void mdb_env_close (MDB_env *env) — Closes the environment and releases the memory map. 🔒
  • int mdb_env_set_flags (MDB_env *env, unsigned int flags, int onoff) — Sets environment flags. 🚩
  • int mdb_env_get_flags (MDB_env *env, unsigned int *flags) — Gets environment flags. 🏁
  • int mdb_env_get_path (MDB_env *env, const char **path) — Returns the path that was used in mdb_env_open(). 🛤️
  • int mdb_env_get_fd (MDB_env *env, mdb_filehandle_t *fd) — Returns the filedescriptor for the given environment. 🗂️
  • int mdb_env_set_mapsize (MDB_env *env, size_t size) — Sets the size of the memory map to use for this environment. 🗺️
  • int mdb_env_set_maxreaders (MDB_env *env, unsigned int readers) — Sets the maximum number of threads/reader slots for the environment. 👥
  • int mdb_env_get_maxreaders (MDB_env *env, unsigned int *readers) — Gets the maximum number of threads/reader slots for the environment. 👀
  • int mdb_env_set_maxdbs (MDB_env *env, MDB_dbi dbs) — Sets the maximum number of named databases for the environment. 🗄️
  • int mdb_env_get_maxkeysize (MDB_env *env) — Gets the maximum size of keys and MDB_DUPSORT data we can write. 🔑
  • int mdb_env_set_userctx (MDB_env *env, void *ctx) — Sets application information associated with the MDB_env. 📎
  • void * mdb_env_get_userctx (MDB_env *env) — Gets the application information associated with the MDB_env. 📎
  • int mdb_env_set_assert (MDB_env *env, MDB_assert_func *func) — no one-liner in the original, just the signature, bestie. 💀
  • int mdb_txn_begin (MDB_env *env, MDB_txn *parent, unsigned int flags, MDB_txn **txn) — Creates a transaction for use with the environment. 🔄
  • MDB_env * mdb_txn_env (MDB_txn *txn) — Returns the transaction's MDB_env. 🌍
  • size_t mdb_txn_id (MDB_txn *txn) — Returns the transaction's ID. 🆔
  • int mdb_txn_commit (MDB_txn *txn) — Commits all the operations of a transaction into the database. ✅
  • void mdb_txn_abort (MDB_txn *txn) — Abandons all the operations of the transaction instead of saving them. ❌
  • void mdb_txn_reset (MDB_txn *txn) — Resets a read-only transaction. 🔁
  • int mdb_txn_renew (MDB_txn *txn) — Renews a read-only transaction. 🔄
  • int mdb_dbi_open (MDB_txn *txn, const char *name, unsigned int flags, MDB_dbi *dbi) — Opens a database in the environment. 📂
  • int mdb_stat (MDB_txn *txn, MDB_dbi dbi, MDB_stat *stat) — Retrieves statistics for a database. 📈
  • int mdb_dbi_flags (MDB_txn *txn, MDB_dbi dbi, unsigned int *flags) — Retrieves the DB flags for a database handle. 🚩
  • void mdb_dbi_close (MDB_env *env, MDB_dbi dbi) — Closes a database handle. Normally unnecessary. Use with care: ⚠️
  • int mdb_drop (MDB_txn *txn, MDB_dbi dbi, int del) — Empties or delete+close a database. 🗑️
  • int mdb_set_compare (MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp) — Sets a custom key comparison function for a database. 🧮
  • int mdb_set_dupsort (MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp) — Sets a custom data comparison function for a MDB_DUPSORT database. 🔀
  • int mdb_set_relfunc (MDB_txn *txn, MDB_dbi dbi, MDB_rel_func *rel) — Sets a relocation function for a MDB_FIXEDMAP database. 📌
  • int mdb_set_relctx (MDB_txn *txn, MDB_dbi dbi, void *ctx) — Sets a context pointer for a MDB_FIXEDMAP database's relocation function. 🧷
  • int mdb_get (MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data) — Gets items from a database. 📥
  • int mdb_put (MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data, unsigned int flags) — Stores items into a database. 📤
  • int mdb_del (MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data) — Deletes items from a database. 🗑️
  • int mdb_cursor_open (MDB_txn *txn, MDB_dbi dbi, MDB_cursor **cursor) — Creates a cursor handle. 🖱️
  • void mdb_cursor_close (MDB_cursor *cursor) — Closes a cursor handle. 🖱️🔒
  • int mdb_cursor_renew (MDB_txn *txn, MDB_cursor *cursor) — Renews a cursor handle. ♻️
  • MDB_txn * mdb_cursor_txn (MDB_cursor *cursor) — Returns the cursor's transaction handle. 🔄
  • MDB_dbi mdb_cursor_dbi (MDB_cursor *cursor) — Returns the cursor's database handle. 🗄️
  • int mdb_cursor_get (MDB_cursor *cursor, MDB_val *key, MDB_val *data, MDB_cursor_op op) — Retrieves by cursor. 🎯
  • int mdb_cursor_put (MDB_cursor *cursor, MDB_val *key, MDB_val *data, unsigned int flags) — Stores by cursor. ✍️
  • int mdb_cursor_del (MDB_cursor *cursor, unsigned int flags) — Deletes current key/data pair. ✂️
  • int mdb_cursor_count (MDB_cursor *cursor, size_t *countp) — Returns count of duplicates for current key. 🔢
  • int mdb_cmp (MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b) — Compares two data items according to a particular database. ⚖️
  • int mdb_dcmp (MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b) — Compares two data items according to a particular database. ⚖️
  • int mdb_reader_list (MDB_env *env, MDB_msg_func *func, void *ctx) — Dumps the entries in the reader lock table. 📋
  • int mdb_reader_check (MDB_env *env, int *dead) — Checks for stale entries in the reader lock table. 🕵️

🧐 Detailed Description 🧐

🏗️ Data Structure Documentation 🏗️

📊 struct MDB_stat 📊

Statistics for a database in the environment.

Data Fields

  • unsigned int ms_psize
  • unsigned int ms_depth
  • size_t ms_branch_pages
  • size_t ms_leaf_pages
  • size_t ms_overflow_pages
  • size_t ms_entries

🌍 struct MDB_envinfo 🌍

Information about the environment.

Data Fields

  • void * me_mapaddr
  • size_t me_mapsize
  • size_t me_last_pgno
  • size_t me_last_txnid
  • unsigned int me_maxreaders
  • unsigned int me_numreaders

🪄 Macro Definition Documentation 🪄

#define MDB_CP_COMPACT 0x01

Compacting copy: Omit free space from copy, and renumber all pages sequentially.

#define mdb_open( txn, name, flags, dbi)

Value:

mdb_dbi_open(txn,name,flags,dbi)

Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project

#define mdb_close( env, dbi)

Value:

mdb_dbi_close(env,dbi)

Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project

🧬 Typedef Documentation 🧬

typedef void MDB_assert_func(MDB_env *env, const char *msg)

A callback function for most LMDB assert() failures, called before printing the message and aborting.

Parameters

  • env — An environment handle returned by mdb_env_create().
  • msg — The assertion message, not including newline.

typedef int MDB_msg_func(const char *msg, void *ctx)

A callback function used to print a message from the library.

Parameters

  • msg — The string to be printed.
  • ctx — An arbitrary context pointer for the callback.

Returns

< 0 on failure, >= 0 on success.

🔮 Enumeration Type Documentation 🔮

enum MDB_cursor_op

Cursor Get operations. This is the set of all operations for retrieving data using a cursor.

Enumerator

  • MDB_FIRST — Position at first key/data item
  • MDB_FIRST_DUP — Position at first data item of current key. Only for MDB_DUPSORT
  • MDB_GET_BOTH — Position at key/data pair. Only for MDB_DUPSORT
  • MDB_GET_BOTH_RANGE — position at key, nearest data. Only for MDB_DUPSORT
  • MDB_GET_CURRENT — Return key/data at current cursor position
  • MDB_GET_MULTIPLE — Return up to a page of duplicate data items from current cursor position. Move cursor to prepare for MDB_NEXT_MULTIPLE. Only for MDB_DUPFIXED
  • MDB_LAST — Position at last key/data item
  • MDB_LAST_DUP — Position at last data item of current key. Only for MDB_DUPSORT
  • MDB_NEXT — Position at next data item
  • MDB_NEXT_DUP — Position at next data item of current key. Only for MDB_DUPSORT
  • MDB_NEXT_MULTIPLE — Return up to a page of duplicate data items from next cursor position. Move cursor to prepare for MDB_NEXT_MULTIPLE. Only for MDB_DUPFIXED
  • MDB_NEXT_NODUP — Position at first data item of next key
  • MDB_PREV — Position at previous data item
  • MDB_PREV_DUP — Position at previous data item of current key. Only for MDB_DUPSORT
  • MDB_PREV_NODUP — Position at last data item of previous key
  • MDB_SET — Position at specified key
  • MDB_SET_KEY — Position at specified key, return key + data
  • MDB_SET_RANGE — Position at first key greater than or equal to specified key.
  • MDB_PREV_MULTIPLE — Position at previous page and return up to a page of duplicate data items. Only for MDB_DUPFIXED

📚 Function Documentation 📚

char * mdb_version (int * major, int * minor, int * patch)

Return the LMDB library version information.

So for mdb_version the params/returns situation is:

Parameters

  • major — if it's not NULL, the library major version number gets copied in here 💖
  • minor — if it's not NULL, the library minor version number gets copied in here 💖
  • patch — if it's not NULL, the library patch version number gets copied in here 💖

Return values

  • version string — the library version, as a string, bestie ✨

And that's the whole vibe: it returns the library version info. Slay.

char * mdb_strerror (int err)

Okay so this one hands you back a string describing whatever error code you throw at it. And the way it's lowkey built different from your average error function is that it's a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) function. So:

  • If the error code is greater than or equal to 0, you just get back the plain old string from the system's strerror(3). No notes, that's the classic.
  • If the error code is less than 0, you get an error string that matches the LMDB library error instead. So negative = LMDB-specific stuff. And if you wanna see the full lineup of those LMDB-specific error codes, go peek at Return Codes. 👑

Parameters

  • err — the error code, obviously 💅

Return values

  • error message — the description of said error. Iconic, informative, everything.

int mdb_env_create (MDB_env ** env)

Not me introducing you to the literal main character: this one creates an LMDB environment handle 🎀 It allocates memory for an MDB_env structure. That's the handle, that's the baddie, that's the whole foundation.

Now the important part, no cap: when you're done with it and you want that allocated memory back, you call mdb_env_close(). Free it, discard the handle, move on with your life. ✨

And before the handle can even be used? It has to be opened first using mdb_env_open(). Yes bestie, creation and opening are two separate steps, we love a process.

There's also a whole lil' squad of other options you might need to set before opening the handle, depending on what you're doing, like:

  • mdb_env_set_mapsize()
  • mdb_env_set_maxreaders()
  • mdb_env_set_maxdbs()

…and whichever ones your specific usage requirements demand. Pick your fighters. 🦋

Parameters

  • env — the address where the brand new handle is gonna be stored 📍

Returns

  • A non-zero error value if it fails, and 0 on success. Zero means we ate. 💅

int mdb_env_open (MDB_env * env, const char * path, unsigned int flags, mdb_mode_t mode)

Okay so this is the one that opens an environment handle. Like, actually opens it. The glow-up from "exists" to "usable." 🌸

Big heads up though: if this function fails, you have to call mdb_env_close() to discard the MDB_env handle. Failing to clean up is giving chaos, and not the cute kind. 😭

(and yes, the rest of this one's story is still loading… 🧚)

Parameters

  • env — an environment handle that mdb_env_create() gave you 🫶
  • path — the directory where the database files live. Heads up: this directory has to already exist and be writable. No auto-mkdir, no coddling, it just has to be there 💅
  • flags — special options for this environment. Set it to 0, or bitwise-OR together one or more of the values we're about to list. Whatever you set with mdb_env_set_flags() counts too ✨
    • MDB_FIXEDMAP — use a fixed address for the mmap region. You have to pass this one when you create the environment, and it gets stored persistently in the environment. If it works, the memory map always lands at the same virtual address, so the pointers you use to reference data items in the db stay constant across multiple invocations. That said, it may not always work — it depends on how the OS has handed out memory to shared libraries and other stuff. This feature is highly experimental 🙈
    • MDB_NOSUBDIR — by default LMDB creates its environment in a directory whose pathname you gave in path, and puts its data and lock files under that directory. With this flag, path is used as-is for the database main data file, and the lock file is the path with "-lock" appended 🎀
    • MDB_RDONLY — opens the environment read-only, so no write operations are allowed. Lowkey important: LMDB will still modify the lock file — except on read-only filesystems, where LMDB doesn't use locks at all 🦋
    • MDB_WRITEMAP — use a writeable memory map, unless MDB_RDONLY is set. This uses fewer mallocs but loses the protection from application bugs like wild pointer writes and other bad updates going straight into the database. It may be slightly faster for DBs that fit entirely in RAM, but it's slower for DBs larger than RAM. Incompatible with nested transactions. Do not mix processes with and without MDB_WRITEMAP on the same environment — this can defeat durability (mdb_env_sync etc.) 😭
    • MDB_NOMETASYNC — flush system buffers to disk only once per transaction, i.e. omit the metadata flush. Defer that until the system flushes files to disk, or until the next non-MDB_RDONLY commit or mdb_env_sync(). This optimization keeps database integrity, but a system crash may undo the last committed transaction. Translation: it preserves the ACI (atomicity, consistency, isolation) but not D (durability) database property. This flag may be changed at any time using mdb_env_set_flags() ⭐
    • MDB_NOSYNC — don't flush system buffers to disk when committing a transaction. This optimization means a system crash can corrupt the database or lose the last transactions if the buffers aren't flushed to disk yet 😬 The risk is governed by how often the system flushes dirty buffers to disk and how often mdb_env_sync() gets called. However, if the filesystem preserves write order and the MDB_WRITEMAP flag isn't used, transactions exhibit ACI (atomicity, consistency, isolation) properties and only lose D (durability). I.e. database integrity is maintained, but a system crash may undo the final transactions. Note that (MDB_NOSYNC | MDB_WRITEMAP) leaves the system with no hint for when to write transactions to disk, unless mdb_env_sync() is called. (MDB_MAPASYNC | MDB_WRITEMAP) may be preferable. This flag may be changed at any time using mdb_env_set_flags()
    • MDB_MAPASYNC — when using MDB_WRITEMAP, use asynchronous flushes to disk. As with MDB_NOSYNC, a system crash can then corrupt the database or lose the last transactions 💀 Calling mdb_env_sync() ensures on-disk database integrity until next commit. This flag may be changed at any time using mdb_env_set_flags()
    • MDB_NOTLS — don't use Thread-Local Storage. Tie reader locktable slots to MDB_txn objects instead of to threads. I.e. mdb_txn_reset() keeps the slot reserved for the MDB_txn object. A thread may use parallel read-only transactions. A read-only transaction may span threads if the user synchronizes its use. Applications that multiplex many user threads over individual OS threads need this option 🔥 Such an application must also serialize the write transactions in an OS thread, since LMDB's write locking is unaware of the user threads
    • MDB_NOLOCK — don't do any locking. If you anticipate concurrent access, the caller has to manage all concurrency itself. For proper operation, the caller must enforce single-writer semantics, and must ensure no readers are using old transactions while a writer is active. The simplest approach is an exclusive lock, so that no readers may be active at all when a writer begins 👑
    • MDB_NORDAHEAD — turn off readahead. Most operating systems perform readahead on read requests by default; this option turns it off if the OS supports it. Turning it off may help random read performance when the DB is larger than RAM and system RAM is full. Not implemented on Windows 🌈
    • MDB_NOMEMINIT — don't initialize malloc'd memory before writing to unused spaces in the data file. By default, memory for pages written to the data file is obtained using malloc. While these pages may be reused in subsequent transactions, freshly malloc'd pages get initialized to zeroes before use. This avoids persisting leftover data from other code (that used the heap and subsequently freed the memory) into the data file. Note that many other system libraries may allocate and free memory from the heap for arbitrary uses — e.g., stdio may use the heap for file I/O buffers 🙈 This initialization step has a modest performance cost, so some applications may want to disable it using this flag. This option can also be a problem for applications which handle sensitive data like passwords, and it makes memory checkers like Valgrind noisy. This flag is not needed with MDB_WRITEMAP, which writes directly to the mmap instead of using malloc for pages. The initialization is also skipped if MDB_RESERVE is used; the caller is expected to overwrite all of the memory that was reserved in that case. This flag may be changed at any time using mdb_env_set_flags()
  • mode — the UNIX permissions to set on created files and semaphores. This parameter is ignored on Windows 🍓

Returns

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

  • MDB_VERSION_MISMATCH — the version of the LMDB library doesn't match the version that created the database environment
  • MDB_INVALID — the environment file headers are corrupted 💀
  • ENOENT — the directory specified by the path parameter doesn't exist
  • EACCES — the user didn't have permission to access the environment files
  • EAGAIN — the environment was locked by another process 🔒

int mdb_env_copy (MDB_env * env, const char * path)

Copy an LMDB environment to the specified path 💖 This is the function you call to make a backup of an existing environment. No lockfile gets created, since it gets recreated at need — iconic behavior honestly.

Note 🫶 This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Caveats.

Parameters

  • env — an environment handle returned by mdb_env_create(). It must have already been opened successfully.
  • path — the directory in which the copy will reside. This directory must already exist and be writable, but must otherwise be empty.

Returns

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

int mdb_env_copyfd (MDB_env * env, mdb_filehandle_t fd)

Copy an LMDB environment to the specified file descriptor 🌸 Same energy as above, this one's for making a backup of an existing environment. And again: no lockfile is created, since it gets recreated at need.

Note 😭 This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Caveats.

Parameters

  • env — an environment handle returned by mdb_env_create(). It must have already been opened successfully.
  • fd — the filedescriptor to write the copy to. It must have already been opened for Write access.

Returns

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

int mdb_env_copy2 (MDB_env * env, const char * path, unsigned int flags)

Copy an LMDB environment to the specified path, with options 💅 This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note 🔥 This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Caveats.

Parameters

  • env — an environment handle returned by mdb_env_create(). It must have already been opened successfully.
  • path — the directory in which the copy will reside. This directory must already exist and be writable, but must otherwise be empty.
  • 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.
    • MDB_CP_COMPACT — perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes more CPU and runs more slowly than the default. Currently it fails if the environment has suffered a page leak 🙈

Returns

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

int mdb_env_copyfd2 (MDB_env * env, mdb_filehandle_t fd, unsigned int flags)

Ok so picture this: you wanna back up a whole LMDB environment and just yeet it into a file descriptor. Say less 💅

Copy an LMDB environment to the specified file descriptor, with options. This is literally your backup button — use it to make a copy of an environment you already have. No lockfile gets made btw, because it just gets recreated whenever it's needed. Wanna know more? Peek at mdb_env_copy2() for further details. 🫶

Note, bestie, read this one 📢 — this call can trigger significant file size growth if you run it in parallel with write transactions, because it employs a read-only transaction. Go look up long-lived transactions under Caveats. Not me warning you twice 😭

Parameters

  • env — an environment handle that came out of mdb_env_create(). It's gotta have been opened successfully already, no shortcuts ✨
  • fd — the filedescriptor you're writing the copy to. It must already be opened for Write access, mkay?
  • flags — special options for this operation. Go see mdb_env_copy2() for the options themselves.

Returns

A non-zero error value on failure and 0 on success. Simple as that. 🌸

int mdb_env_stat (MDB_env * env, MDB_stat * stat) 📊

Spill the tea on your LMDB environment — this one returns statistics about it.

Parameters

  • env — an environment handle returned by mdb_env_create()
  • stat — the address of an MDB_stat structure where the statistics will be copied. She's the destination, not the source 💅

int mdb_env_info (MDB_env * env, MDB_envinfo * stat) ℹ️

Return information about the LMDB environment. Like, the vibes but make it structured data.

Parameters

  • env — an environment handle returned by mdb_env_create()
  • stat — the address of an MDB_envinfo structure where the information will be copied

int mdb_env_sync (MDB_env * env, int force) 🔄

Flush the data buffers to disk. Ok so important thing bestie: data is always written to disk when mdb_txn_commit() is called, but your operating system may be a little gremlin and keep it buffered. LMDB always flushes the OS buffers upon commit too, unless the environment was opened with MDB_NOSYNC or in part MDB_NOMETASYNC. 🙈

This call is not valid if the environment was opened with MDB_RDONLY. Read-only means read-only, periodt.

Parameters

  • env — an environment handle returned by mdb_env_create()
  • force — if non-zero, force a synchronous flush. Otherwise, if the environment has the MDB_NOSYNC flag set, the flushes will be omitted, and with MDB_MAPASYNC they'll be asynchronous.

Returns

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

  • EACCES — the environment is read-only.
  • EINVAL — an invalid parameter was specified.
  • EIO — an error occurred during synchronization. 😭

void mdb_env_close (MDB_env * env) 🚪

Close the environment and release the memory map. Big moment, iconic, but there are rules:

  • Only a single thread may call this function. One. Uno. ☝️
  • All transactions, databases, and cursors must already be closed before you call this.
  • Attempts to use any such handles after calling this function will cause a SIGSEGV. 💀 Not a vibe.
  • The environment handle will be freed and must not be used again after this call. She's gone, fr fr.

Parameters

  • env — an environment handle returned by mdb_env_create()

int mdb_env_set_flags (MDB_env * env, unsigned int flags, int onoff) 🚩

Set environment flags. You can use this to set some flags in addition to those from mdb_env_open(), or to unset these flags. But heads up: if several threads change the flags at the same time, the result is undefined. Chaos energy, we don't do that. 🙅‍♀️

Parameters

  • env — an environment handle returned by mdb_env_create()
  • flags — the flags to change, bitwise OR'ed together
  • onoff — a non-zero value sets the flags, zero clears them.

Returns

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

  • EINVAL — an invalid parameter was specified.

int mdb_env_get_flags (MDB_env * env, unsigned int * flags) 🎏

Get environment flags. Hand them over, we just wanna look 👀

Parameters

  • env — an environment handle returned by mdb_env_create()
  • flags — the address of an integer to store the flags

Returns

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

  • EINVAL — an invalid parameter was specified.

int mdb_env_get_path (MDB_env * env, const char ** path) 🛣️

Return the path that was used in mdb_env_open().

Parameters

  • env — an environment handle returned by mdb_env_create()
  • path — address of a string pointer to contain the path. Girl, this is the actual string in the environment, not a copy. So do not alter it in any way. Hands off 💅

Returns

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

  • EINVAL — an invalid parameter was specified.

int mdb_env_get_fd (MDB_env * env, mdb_filehandle_t * fd) 🔑

Return the filedescriptor for the given environment. The way that this one is special: it may be called after fork(), so the descriptor can be closed before exec*(). Other LMDB file descriptors have FD_CLOEXEC. (Until LMDB 0.9.18, only the lockfile had that.) ⭐

Parameters

  • env — an environment handle returned by mdb_env_create()
  • fd — Address of a mdb_filehandle_t to contain the descriptor.

Returns

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

  • EINVAL — an invalid parameter was specified.

int mdb_env_set_mapsize (MDB_env * env, size_t size) 📏

Set the size of the memory map to use for this environment. Let's break it down boo:

  • The size should be a multiple of the OS page size.
  • The default is 10485760 bytes. (Yes, exactly that number, keep it.)
  • The size of the memory map is also the maximum size of the database. So pick it as large as possible to accommodate future growth of the database. Future-you says thank you. 🫶
  • Call this after mdb_env_create() and before mdb_env_open(). It may also be called at later times if no transactions are active in this process. But ngl, the library does not check for this condition — the caller must ensure it explicitly. That's on you, bestie. 😭

The new size takes effect immediately for the current process but will not be persisted to any others until a write transaction has been committed by the current process. Also, only mapsize increases are persisted into the environment.

If the mapsize is increased by another process, and data has grown beyond the range of the current mapsize, mdb_txn_begin() will return MDB_MAP_RESIZED. This function may be called with a size of zero to adopt the new size. ✨

Any attempt to set a size smaller than the space already consumed by the environment will be silently changed to the current size of the used space. Sneaky but true.

Parameters

  • env — an environment handle returned by mdb_env_create()
  • size — the size in bytes

Returns

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

  • EINVAL — an invalid parameter was specified, or the environment has an active write transaction.

int mdb_env_set_maxreaders (MDB_env * env, unsigned int readers) 👥

Set the maximum number of threads/reader slots for the environment. This defines the number of slots in the lock table used to track readers in the the environment. (Yes, the original really does say "in the the" — we keep it, no cap 😌)

  • The default is 126.
  • Starting a read-only transaction normally ties a lock table slot to the current thread until the environment closes or the thread exits.
  • If MDB_NOTLS is in use, mdb_txn_begin() instead ties the slot to the MDB_txn object until it or the MDB_env object is destroyed.
  • This function may only be called after mdb_env_create() and before mdb_env_open().

Parameters

  • env — an environment handle returned by mdb_env_create()
  • readers — the maximum number of reader lock table slots

Returns

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

  • EINVAL — an invalid parameter was specified, or the environment is already open.

int mdb_env_get_maxreaders (MDB_env * env, unsigned int * readers) 🔍

Get the maximum number of threads/reader slots for the environment.

Parameters

  • env — an environment handle returned by mdb_env_create()
  • readers — address of an integer to store the number of readers

Returns

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

  • EINVAL — an invalid parameter was specified.

int mdb_env_set_maxdbs (MDB_env * env, MDB_dbi dbs) 🗂️

Set the maximum number of named databases for the environment. Only needed if multiple databases will be used in the environment — simpler apps that use the environment as a single unnamed database can just ignore this option entirely. Live your life. ✨ This function may only be called after mdb_env_create() and before mdb_env_open().

Currently a moderate number of slots is cheap but a huge number gets expensive: 7-120 words per transaction, and every mdb_dbi_open() does a linear search of the opened slots. So like... don't be greedy, ok? 🙈

Parameters

  • env — an environment handle returned by mdb_env_create()
  • dbs — the maximum number of databases

Returns

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

  • EINVAL — an invalid parameter was specified, or the environment is already open.

int mdb_env_get_maxkeysize (MDB_env * env) 🔑

Get the maximum size of keys and MDB_DUPSORT data we can write. Depends on the compile-time constant MDB_MAXKEYSIZE. Default 511. See MDB_val. 📐

Parameters

  • env — an environment handle returned by mdb_env_create()

Returns

The maximum size of a key we can write.

int mdb_env_set_userctx (MDB_env * env, void * ctx) 🎀

Set application information associated with the MDB_env. Your little secret pocket for whatever you need, bestie.

Parameters

  • env — an environment handle returned by mdb_env_create()
  • ctx — an arbitrary pointer for whatever the application needs.

Returns

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

void * mdb_env_get_userctx (MDB_env * env) 🫶

Get the application information associated with the MDB_env. Time to retrieve what you stashed.

Parameters

  • env — an environment handle returned by mdb_env_create()

Returns

The pointer set by mdb_env_set_userctx().

int mdb_env_set_assert (MDB_env * env, MDB_assert_func * func) 🚨

Set or reset the assert() callback of the environment. Disabled if liblmdb is built with NDEBUG. (Compile-time decisions, we love to see it.)

Note — this hack should become obsolete as lmdb's error handling matures. The source said it, not me 💀

Parameters

  • env — an environment handle returned by mdb_env_create().
  • func — An MDB_assert_func function, or 0.

Returns

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

int mdb_txn_begin (MDB_env * env, MDB_txn * parent, unsigned int flags, MDB_txn ** txn) 🎬

Create a transaction for use with the environment. The transaction handle may be discarded using mdb_txn_abort() or mdb_txn_commit(). Your main character moment starts here, bestie. 👑

Note — a transaction and its cursors must only be used by a single thread, and a thread may only have a single transaction at a time. If MDB_NOTLS is in use, this does not apply to read-only transactions.

Cursors may not span transactions.

Parameters

  • env — An environment handle returned by mdb_env_create() 💖
  • parent — If this parameter is non-NULL, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level. A parent transaction and its cursors may not issue any other operations than mdb_txn_commit and mdb_txn_abort while it has active child transactions. 👑
  • flags — Special options for this transaction. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here. 💅
    • MDB_RDONLY — This transaction will not perform any write operations. ✨
  • txn — Address where the new MDB_txn handle will be stored 🎀

Returns

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

  • MDB_PANIC — a fatal error occurred earlier and the environment must be shut down. 😭
  • MDB_MAP_RESIZED — another process wrote data beyond this MDB_env's mapsize and this environment's map must be resized as well. See mdb_env_set_mapsize(). 🦋
  • MDB_READERS_FULL — a read-only transaction was requested and the reader lock table is full. See mdb_env_set_maxreaders(). 💀
  • ENOMEM — out of memory. 🌸

MDB_env * mdb_txn_env (MDB_txn * txn)

Returns the transaction's MDB_env. 💜

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() ✨

size_t mdb_txn_id (MDB_txn * txn)

Return the transaction's ID. This returns the identifier associated with this transaction. For a read-only transaction, this corresponds to the snapshot being read; concurrent readers will frequently have the same transaction ID. 🔥

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() 💖

Returns

A transaction ID, valid if input is an active transaction. 👑

int mdb_txn_commit (MDB_txn * txn)

Commit all the operations of a transaction into the database. The transaction handle is freed. It and its cursors must not be used again after this call, except with mdb_cursor_renew(). 💅

Note — Earlier documentation incorrectly said all cursors would be freed. Only write-transactions free cursors. 🙈

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() 🎀

Returns

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

  • EINVAL — an invalid parameter was specified. 😭
  • ENOSPC — no more disk space. 💀
  • EIO — a low-level I/O error occurred while writing. 🦋
  • ENOMEM — out of memory. 🌸

void mdb_txn_abort (MDB_txn * txn)

Abandon all the operations of the transaction instead of saving them. The transaction handle is freed. It and its cursors must not be used again after this call, except with mdb_cursor_renew(). 🌈

Note — Earlier documentation incorrectly said all cursors would be freed. Only write-transactions free cursors. 🙈

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() ✨

void mdb_txn_reset (MDB_txn * txn)

Reset a read-only transaction. Abort the transaction like mdb_txn_abort(), but keep the transaction handle. mdb_txn_renew() may reuse the handle. This saves allocation overhead if the process will start a new read-only transaction soon, and also locking overhead if MDB_NOTLS is in use. The reader table lock is released, but the table slot stays tied to its thread or MDB_txn. Use mdb_txn_abort() to discard a reset handle, and to free its lock table slot if MDB_NOTLS is in use. 💖

Cursors opened within the transaction must not be used again after this call, except with mdb_cursor_renew(). Reader locks generally don't interfere with writers, but they keep old versions of database pages allocated. Thus they prevent the old pages from being reused when writers commit new data, and so under heavy load the database size may grow much more rapidly than otherwise. 😭

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() 👑

int mdb_txn_renew (MDB_txn * txn)

Renew a read-only transaction. This acquires a new reader lock for a transaction handle that had been released by mdb_txn_reset(). It must be called before a reset transaction may be used again. 🔥

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() 💅

Returns

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

  • MDB_PANIC — a fatal error occurred earlier and the environment must be shut down. 💀
  • EINVAL — an invalid parameter was specified. 😭

int mdb_dbi_open (MDB_txn * txn, const char * name, unsigned int flags, MDB_dbi * dbi)

Open a database in the environment. A database handle denotes the name and parameters of a database, independently of whether such a database exists. The database handle may be discarded by calling mdb_dbi_close(). The old database handle is returned if the database was already open. The handle may only be closed once. 🎀

The database handle will be private to the current transaction until the transaction is successfully committed. If the transaction is aborted the handle will be closed automatically. After a successful commit the handle will reside in the shared environment, and may be used by other transactions. ✨

This function must not be called from multiple concurrent transactions in the same process. A transaction that uses this function must finish (either commit or abort) before any other transaction in the process may use this function. 🦋

To use named databases (with name != NULL), mdb_env_set_maxdbs() must be called before opening the environment. Database names are keys in the unnamed database, and may be read but not written. 🌸

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() 💜
  • name — The name of the database to open. If only a single database is needed in the environment, this value may be NULL. 🌈
  • flags — Special options for this database. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here. 👑
    • MDB_REVERSEKEY — Keys are strings to be compared in reverse order, from the end of the strings to the beginning. By default, Keys are treated as strings and compared from beginning to end. 💅
    • MDB_DUPSORT — Duplicate keys may be used in the database. (Or, from another perspective, keys may have multiple data items, stored in sorted order.) By default keys must be unique and may have only a single data item. ✨
    • MDB_INTEGERKEY — Keys are binary integers in native byte order, either unsigned int or size_t, and will be sorted as such. The keys must all be of the same size. 🎀
    • MDB_DUPFIXED — This flag may only be used in combination with MDB_DUPSORT. This option tells the library that the data items for this database are all the same size, which allows further optimizations in storage and retrieval. When all data items are the same size, the MDB_GET_MULTIPLE, MDB_NEXT_MULTIPLE and MDB_PREV_MULTIPLE cursor operations may be used to retrieve multiple items at once. 🦋
    • MDB_INTEGERDUP — This option specifies that duplicate data items are binary integers, similar to MDB_INTEGERKEY keys. 🌸
    • MDB_REVERSEDUP — This option specifies that duplicate data items should be compared as strings in reverse order. 💖
    • MDB_CREATE — Create the named database if it doesn't exist. This option is not allowed in a read-only transaction or a read-only environment. 👑
  • dbi — Address where the new MDB_dbi handle will be stored 💅

Returns

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

  • MDB_NOTFOUND — the specified database doesn't exist in the environment and MDB_CREATE was not specified. 😭
  • MDB_DBS_FULL — too many databases have been opened. See mdb_env_set_maxdbs(). 💀

int mdb_stat (MDB_txn * txn, MDB_dbi dbi, MDB_stat * stat)

Retrieve statistics for a database. 🔥

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() ✨
  • dbi — A database handle returned by mdb_dbi_open() 🎀
  • stat — The address of an MDB_stat structure where the statistics will be copied 🦋

Returns

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

  • EINVAL — an invalid parameter was specified. 🌸

int mdb_dbi_flags (MDB_txn * txn, MDB_dbi dbi, unsigned int * flags)

Retrieve the DB flags for a database handle. 💜

Parameters

  • txn — A transaction handle returned by mdb_txn_begin() 👑
  • dbi — A database handle returned by mdb_dbi_open() 💅
  • flags — Address where the flags will be returned. ✨

Returns

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

void mdb_dbi_close (MDB_env * env, MDB_dbi dbi)

Close a database handle. Normally unnecessary. Use with care: This call is not mutex protected. Handles should only be closed by a single thread, and only if no other threads are going to reference the database handle or one of its cursors any further. Do not close a handle if an existing transaction has modified its database. Doing so can cause misbehavior from database corruption to errors like MDB_BAD_VALSIZE (since the DB name is gone). 😭

Closing a database handle is not necessary, but lets mdb_dbi_open() reuse the handle value. Usually it's better to set a bigger mdb_env_set_maxdbs(), unless that value would be large. 🌈

Parameters

  • env — an environment handle, the kind that comes back from mdb_env_create() 🫶
  • dbi — a database handle, courtesy of mdb_dbi_open() ✨

int mdb_drop (MDB_txn * txn, MDB_dbi dbi, int del)

Okay so this one empties a database or deletes it and closes it, depending on the vibes you're giving it. Heads up tho — if you're going the closing route, go read mdb_dbi_close() first, because there are restrictions about closing DB handles and you do NOT want to find out the hard way 💀

Parameters

  • txn — a transaction handle returned by mdb_txn_begin() 🌸
  • dbi — a database handle returned by mdb_dbi_open() 🦋
  • del — 0 to empty the DB, 1 to delete it from the environment and close the DB handle. That's it, that's the whole switch, choose your fighter 👑

Returns

A non-zero error value if it flops, and 0 on success. slay.

int mdb_set_compare (MDB_txn * txn, MDB_dbi dbi, MDB_cmp_func * cmp)

Set a custom key comparison function for a database 🎀 This function gets called whenever something needs to compare a key that the application handed over with a key that's currently sitting in the database. And if you don't specify a comparison function, and you didn't pass any special key flags to mdb_dbi_open(), then everything is compared lexically — shorter keys collate before longer keys. simple as that, lowkey elegant.

Warning ⚠️ This function has to be called before any data access functions get used, otherwise data corruption may occur. And the same comparison function must be used by every program accessing the database, every single time the database is used. no exceptions bestie, fr fr.

Parameters

  • txn — a transaction handle returned by mdb_txn_begin() 🌈
  • dbi — a database handle returned by mdb_dbi_open() 💜
  • cmp — a MDB_cmp_func function 🧚

Returns

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

  • EINVAL — an invalid parameter was specified. 🙈

int mdb_set_dupsort (MDB_txn * txn, MDB_dbi dbi, MDB_cmp_func * cmp)

The data-item twin of the last one 💅 This sets a custom data comparison function for a MDB_DUPSORT database. It gets called whenever something needs to compare a data item the application specified with a data item currently hanging out in the database. Important: this only actually takes effect if the database was opened with the MDB_DUPSORT flag. And if no comparison function is specified, and no special key flags were handed to mdb_dbi_open(), then the data items get compared lexically, with shorter items collating before longer items. ✨

Warning ⚠️ Same deal as before — call this before any data access functions are used, otherwise data corruption may occur. Every program touching the database, every time, must use the same comparison function. periodt.

Parameters

  • txn — a transaction handle returned by mdb_txn_begin() 🌸
  • dbi — a database handle returned by mdb_dbi_open() 🦋
  • cmp — a MDB_cmp_func function 🎀

Returns

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

  • EINVAL — an invalid parameter was specified. 💀

int mdb_set_relfunc (MDB_txn * txn, MDB_dbi dbi, MDB_rel_func * rel)

Sets a relocation function for a MDB_FIXEDMAP database 👑

Todo 📝 The relocation function is called whenever it's necessary to move the data of an item to a different position in the database (like through tree balancing operations, shifts as a result of adds or deletes, etc.). It's intended to let address- or position-dependent data items be stored in a database inside an environment opened with the MDB_FIXEDMAP option. Currently the relocation feature is unimplemented and setting this function has no effect. literally nothing happens, it's giving placeholder energy 😭

Parameters

  • txn — a transaction handle returned by mdb_txn_begin() 💜
  • dbi — a database handle returned by mdb_dbi_open() 🌈
  • rel — a MDB_rel_func function 🧚

Returns

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

  • EINVAL — an invalid parameter was specified. 🙈

int mdb_set_relctx (MDB_txn * txn, MDB_dbi dbi, void * ctx)

Sets a context pointer for a MDB_FIXEDMAP database's relocation function 🫶 For the full lore, go look at mdb_set_relfunc and MDB_rel_func.

Parameters

  • txn — a transaction handle returned by mdb_txn_begin() 🌸
  • dbi — a database handle returned by mdb_dbi_open() 🦋
  • ctx — an arbitrary pointer for whatever the application needs. It gets passed to the callback function set by mdb_set_relfunc as its relctx parameter whenever that callback is invoked. very "your data, your rules" 💅

Returns

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

  • EINVAL — an invalid parameter was specified. 💀

int mdb_get (MDB_txn * txn, MDB_dbi dbi, MDB_val * key, MDB_val * data)

Get items out of a database 🎀 This one retrieves key/data pairs. The address and length of the data associated with the key you specified get returned in the structure that data refers to. And if the database supports duplicate keys (MDB_DUPSORT), then the first data item for the key is what you get back. Want the other items? Then you gotta go use mdb_cursor_get(), no shortcuts bestie 🦋

Note 📌 The memory pointed to by the returned values is owned by the database. The caller doesn't need to dispose of that memory — and may not modify it in any way. For values returned in a read-only transaction, any modification attempts will cause a SIGSEGV. that's not a vibe, that's a crash 💀 don't do it.

The values that come back out of the database? valid only until a subsequent update operation, or the end of the transaction. That's it. That's the whole window 💀 so if you need them longer than that, copy them out now, bestie, don't come crying to me later.

Parameters

  • txn — A transaction handle returned by mdb_txn_begin()
  • dbi — A database handle returned by mdb_dbi_open()
  • key — The key to search for in the database
  • data — The data corresponding to the key

Returns 💖

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

  • MDB_NOTFOUND — the key was not in the database. 😭 it's just not there.
  • EINVAL — an invalid parameter was specified.

int mdb_put (MDB_txn * txn, MDB_dbi dbi, MDB_val * key, MDB_val * data, unsigned int flags)

int mdb_put (MDB_txn * txn, MDB_dbi dbi, MDB_val * key, MDB_val * data,
    unsigned int flags)

Store items into a database. She's the one who actually writes things down ✨ This function stores key/data pairs in the database. Default behavior? 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 (MDB_DUPSORT). Options, options, options, we love a flexible queen 👑

Parameters

  • txn — A transaction handle returned by mdb_txn_begin()
  • dbi — A database handle returned by mdb_dbi_open()
  • key — The key to store in the database
  • 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 👇
  • 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). The data parameter will be set to point to the existing item. 👀
  • 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. LMDB 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 MDB_DUPSORT.
  • MDB_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 MDB_KEYEXIST error. 🚨
  • MDB_APPENDDUP — as above, but for sorted dup data.

Returns 🌸

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

  • MDB_MAP_FULL — the database is full, see mdb_env_set_mapsize(). 💀 she's stuffed.
  • MDB_TXN_FULL — the transaction has too many dirty pages.
  • EACCES — an attempt was made to write in a read-only transaction. not you trying to write in a read-only txn 💅
  • EINVAL — an invalid parameter was specified.

int mdb_del (MDB_txn * txn, MDB_dbi dbi, MDB_val * key, MDB_val * data)

int mdb_del (MDB_txn * txn, MDB_dbi dbi, MDB_val * key, MDB_val * data)

Delete items from a database. Bye bestie 👋 This function removes key/data pairs from the database. Here's the vibe check on how much it nukes:

  • If the database does not support sorted duplicate data items (MDB_DUPSORT), the data parameter is ignored.
  • If the database does support sorted duplicates and the data parameter is NULL, all of the duplicate data items for the key will be deleted. 🔥
  • Otherwise, if the data parameter is non-NULL, only the matching data item will be deleted.

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

Parameters

  • txn — A transaction handle returned by mdb_txn_begin()
  • dbi — A database handle returned by mdb_dbi_open()
  • key — The key to delete from the database
  • data — The data to delete

Returns 💖

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

  • EACCES — an attempt was made to write in a read-only transaction.
  • EINVAL — an invalid parameter was specified.

int mdb_cursor_open (MDB_txn * txn, MDB_dbi dbi, MDB_cursor ** cursor)

int mdb_cursor_open (MDB_txn * txn, MDB_dbi dbi, MDB_cursor ** cursor)

Create a cursor handle. Cursor rights 🖱️✨ A cursor is associated with a specific transaction and database. And the rules, because there are rules:

  • A cursor cannot be used when its database handle is closed.
  • Nor when its transaction has ended — except with mdb_cursor_renew().
  • It can be discarded with mdb_cursor_close().
  • A cursor in a write-transaction can be closed before its transaction ends, and will otherwise be closed when its transaction ends.
  • A cursor in a read-only transaction must be closed explicitly, before or after its transaction ends.
  • It can be reused with mdb_cursor_renew() before finally closing it.
Note 📝 Earlier documentation said that cursors in every transaction were closed when the transaction committed or aborted. That was... not it, bestie. The note is the canon.

Parameters

  • txn — A transaction handle returned by mdb_txn_begin()
  • dbi — A database handle returned by mdb_dbi_open()
  • cursor — Address where the new MDB_cursor handle will be stored

Returns 🎀

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

  • EINVAL — an invalid parameter was specified.

void mdb_cursor_close (MDB_cursor * cursor)

void mdb_cursor_close (MDB_cursor * cursor)

Close a cursor handle. The cursor handle will be freed and must not be used again after this call — like, it's gone, don't text it back 🚫 Its transaction must still be live if it is a write-transaction.

Parameters

  • cursor — A cursor handle returned by mdb_cursor_open()

int mdb_cursor_renew (MDB_txn * txn, MDB_cursor * cursor)

int mdb_cursor_renew (MDB_txn * txn, MDB_cursor * cursor)

Renew a cursor handle. A cursor is associated with a specific transaction and database. Cursors that are only used in read-only transactions may be re-used, to avoid unnecessary malloc/free overhead — recycling is the moment 🧚 The cursor may be associated with a new read-only transaction, and referencing the same database handle as it was created with. This may be done whether the previous transaction is live or dead.

Parameters

  • txn — A transaction handle returned by mdb_txn_begin()
  • cursor — A cursor handle returned by mdb_cursor_open()

Returns 💜

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

  • EINVAL — an invalid parameter was specified.

MDB_txn * mdb_cursor_txn (MDB_cursor * cursor)

MDB_txn * mdb_cursor_txn (MDB_cursor * cursor)

Return the cursor's transaction handle. Who's your txn? 🫶

Parameters

  • cursor — A cursor handle returned by mdb_cursor_open()

MDB_dbi mdb_cursor_dbi (MDB_cursor * cursor)

MDB_dbi mdb_cursor_dbi (MDB_cursor * cursor)

Return the cursor's database handle. Who's your dbi? 💖

Parameters

  • cursor — A cursor handle returned by mdb_cursor_open()

int mdb_cursor_get (MDB_cursor * cursor, MDB_val * key, MDB_val * data, MDB_cursor_op op)

int mdb_cursor_get (MDB_cursor * cursor, MDB_val * key, MDB_val * data,
    MDB_cursor_op op)

Retrieve by cursor. The main character energy of reading data ✨ 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 MDB_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 mdb_get() for restrictions on using the output values 👀 (yes, that "valid only until a subsequent update operation or end of transaction" thing, it still applies).

Parameters

  • cursor — A cursor handle returned by mdb_cursor_open()
  • key — The key for a retrieved item
  • data — The data of a retrieved item
  • op — A cursor operation MDB_cursor_op

Returns 🌈

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

  • MDB_NOTFOUND — no matching key found. 😭
  • EINVAL — an invalid parameter was specified.

int mdb_cursor_put (MDB_cursor * cursor, MDB_val * key, MDB_val * data, unsigned int flags)

int mdb_cursor_put (MDB_cursor * cursor, MDB_val * key, MDB_val * data,
    unsigned int flags)

Store by cursor. Writing, but make it cursor-coded 💅 This function stores key/data pairs into the database. The cursor is positioned at the new item, or on failure usually near it. (Near. NEAR. We said what we said.)

Note 📝 Earlier documentation incorrectly said errors would leave the state of the cursor unchanged. Not true, bestie. Do not build your life around that.

Parameters

  • cursor — A cursor handle returned by mdb_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 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:

  • 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 — bestie, an invalid parameter was specified. that's it, that's the whole thing 💅

Function Documentation 🌸

int mdb_cursor_del (MDB_cursor * cursor, unsigned int flags) 💖

okay so this one deletes the current key/data pair — the exact pair your cursor is pointing at rn. and here's the slay part: it does not invalidate the cursor, so you can keep vibing with it, MDB_NEXT and everything. ✨ both MDB_NEXT and MDB_GET_CURRENT will return the same record after this operation, no cap.

Parameters

  • cursor — a cursor handle returned by mdb_cursor_open()
  • flags — options for this operation. this parameter must be set to 0 or one of the values described here:
    • MDB_NODUPDATA — delete all of the data items for the current key 🫶. this flag may only be specified if the database was opened with MDB_DUPSORT.

Returns

a non-zero error value on failure and 0 on success 😌. some possible errors are:

  • EACCES — an attempt was made to write in a read-only transaction. nope, can't do that babe 🔒
  • EINVAL — an invalid parameter was specified.

int mdb_cursor_count (MDB_cursor * cursor, size_t * countp) 🧮

returns the count of duplicates for the current key. this call is only valid on databases that support sorted duplicate data items — aka MDB_DUPSORT 🦋.

Parameters

  • cursor — a cursor handle returned by mdb_cursor_open()
  • countp — address where the count will be stored 📍

Returns

a non-zero error value on failure and 0 on success. some possible errors are:

  • EINVAL — cursor is not initialized, or an invalid parameter was specified. 💀

int mdb_cmp (MDB_txn * txn, MDB_dbi dbi, const MDB_val * a, const MDB_val * b) ⚖️

compare two data items according to a particular database. it returns a comparison as if the two data items were keys in the specified database. literally just "which one comes first" energy ✨

Parameters

  • txn — a transaction handle returned by mdb_txn_begin()
  • dbi — a database handle returned by mdb_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 🎀

int mdb_dcmp (MDB_txn * txn, MDB_dbi dbi, const MDB_val * a, const MDB_val * b) 🥞

compare two data items according to a particular database — but this time it returns a comparison as if the two items were data items of the specified database. the database must have the MDB_DUPSORT flag, periodt.

Parameters

  • txn — a transaction handle returned by mdb_txn_begin()
  • dbi — a database handle returned by mdb_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 💜

int mdb_reader_list (MDB_env * env, MDB_msg_func * func, void * ctx) 📜

dump the entries in the reader lock table. like a lil receipt of everyone currently holding a read slot 🧾✨

Parameters

  • env — an environment handle returned by mdb_env_create()
  • func — a MDB_msg_func function
  • ctx — anything the message function needs

Returns

< 0 on failure, >= 0 on success 🫶

int mdb_reader_check (MDB_env * env, int * dead) 🧹

check for stale entries in the reader lock table — the ghosts of readers past 👻

Parameters

  • env — an environment handle returned by mdb_env_create()
  • dead — number of stale slots that were cleared 🪦

Returns

0 on success, non-zero on failure.

Author 👑

generated automatically by Doxygen for LMDB from the source code. not a human, not a bestie, just a machine that really knows its stuff fr fr 🤖💖

and that's a wrap on mdb_copy(3), bestie!! 🎀 the whole thing was generated by Doxygen for LMDB, and it's filed under the classic footer name — LMDB, page mdb_copy(3) — so if you ever forget where you read all this, that's your 411. go forth and copy your databases with confidence, you're doing amazing sweetie 💅✨🦋

📦 where this page comes from