--- name: "mdb_copy" section: "3" platform: "linux" package: "lmdb-doc" version: "0.9.31-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/mdb_copy/3" --- # mdb\_copy(3) Copy Flags ## NAME mdb\_copy - Copy Flags ## SYNOPSIS ### Modules **Return Codes**\ ### 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\ \#define **mdb\_open**(txn, name, flags, dbi) **mdb\_dbi\_open**(txn,name,flags,dbi)\ \#define **mdb\_close**(env, dbi) **mdb\_dbi\_close**(env,dbi)\ ### 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. typedef int() **MDB\_msg\_func**(const char \*msg, void \*ctx)\ A callback function used to print a message from the library. ### 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. ### Functions char \* **mdb\_version** (int \*major, int \*minor, int \*patch)\ Return the LMDB library version information. char \* **mdb\_strerror** (int err)\ Return a string describing a given error code. int **mdb\_env\_create** (**MDB\_env** \*\*env)\ Create an LMDB environment handle. int **mdb\_env\_open** (**MDB\_env** \*env, const char \*path, unsigned int flags, **mdb\_mode\_t** mode)\ Open an environment handle. int **mdb\_env\_copy** (**MDB\_env** \*env, const char \*path)\ Copy an LMDB environment to the specified path. int **mdb\_env\_copyfd** (**MDB\_env** \*env, **mdb\_filehandle\_t** fd)\ Copy an LMDB environment to the specified file descriptor. int **mdb\_env\_copy2** (**MDB\_env** \*env, const char \*path, unsigned int flags)\ Copy an LMDB environment to the specified path, with options. int **mdb\_env\_copyfd2** (**MDB\_env** \*env, **mdb\_filehandle\_t** fd, unsigned int flags)\ Copy an LMDB environment to the specified file descriptor, with options. int **mdb\_env\_stat** (**MDB\_env** \*env, **MDB\_stat** \*stat)\ Return statistics about the LMDB environment. int **mdb\_env\_info** (**MDB\_env** \*env, **MDB\_envinfo** \*stat)\ Return information about the LMDB environment. int **mdb\_env\_sync** (**MDB\_env** \*env, int force)\ Flush the data buffers to disk. void **mdb\_env\_close** (**MDB\_env** \*env)\ Close the environment and release the memory map. int **mdb\_env\_set\_flags** (**MDB\_env** \*env, unsigned int flags, int onoff)\ Set environment flags. int **mdb\_env\_get\_flags** (**MDB\_env** \*env, unsigned int \*flags)\ Get environment flags. int **mdb\_env\_get\_path** (**MDB\_env** \*env, const char \*\*path)\ Return the path that was used in **mdb\_env\_open()**. int **mdb\_env\_get\_fd** (**MDB\_env** \*env, **mdb\_filehandle\_t** \*fd)\ Return the filedescriptor for the given environment. int **mdb\_env\_set\_mapsize** (**MDB\_env** \*env, size\_t size)\ Set the size of the memory map to use for this environment. int **mdb\_env\_set\_maxreaders** (**MDB\_env** \*env, unsigned int readers)\ Set the maximum number of threads/reader slots for the environment. int **mdb\_env\_get\_maxreaders** (**MDB\_env** \*env, unsigned int \*readers)\ Get the maximum number of threads/reader slots for the environment. int **mdb\_env\_set\_maxdbs** (**MDB\_env** \*env, **MDB\_dbi** dbs)\ Set the maximum number of named databases for the environment. int **mdb\_env\_get\_maxkeysize** (**MDB\_env** \*env)\ Get the maximum size of keys and **MDB\_DUPSORT** data we can write. int **mdb\_env\_set\_userctx** (**MDB\_env** \*env, void \*ctx)\ Set application information associated with the **MDB\_env**. void \* **mdb\_env\_get\_userctx** (**MDB\_env** \*env)\ Get the application information associated with the **MDB\_env**. int **mdb\_env\_set\_assert** (**MDB\_env** \*env, **MDB\_assert\_func** \*func)\ int **mdb\_txn\_begin** (**MDB\_env** \*env, **MDB\_txn** \*parent, unsigned int flags, **MDB\_txn** \*\*txn)\ Create 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)\ Return the transaction's ID. int **mdb\_txn\_commit** (**MDB\_txn** \*txn)\ Commit all the operations of a transaction into the database. void **mdb\_txn\_abort** (**MDB\_txn** \*txn)\ Abandon all the operations of the transaction instead of saving them. void **mdb\_txn\_reset** (**MDB\_txn** \*txn)\ Reset a read-only transaction. int **mdb\_txn\_renew** (**MDB\_txn** \*txn)\ Renew a read-only transaction. int **mdb\_dbi\_open** (**MDB\_txn** \*txn, const char \*name, unsigned int flags, **MDB\_dbi** \*dbi)\ Open a database in the environment. int **mdb\_stat** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, **MDB\_stat** \*stat)\ Retrieve statistics for a database. int **mdb\_dbi\_flags** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, unsigned int \*flags)\ Retrieve the DB flags for a database handle. void **mdb\_dbi\_close** (**MDB\_env** \*env, **MDB\_dbi** dbi)\ Close a database handle. Normally unnecessary. Use with care: int **mdb\_drop** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, int del)\ Empty or delete+close a database. int **mdb\_set\_compare** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, **MDB\_cmp\_func** \*cmp)\ Set a custom key comparison function for a database. int **mdb\_set\_dupsort** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, **MDB\_cmp\_func** \*cmp)\ Set a custom data comparison function for a **MDB\_DUPSORT** database. int **mdb\_set\_relfunc** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, **MDB\_rel\_func** \*rel)\ Set a relocation function for a **MDB\_FIXEDMAP** database. int **mdb\_set\_relctx** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, void \*ctx)\ Set 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)\ Get items from a database. int **mdb\_put** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, **MDB\_val** \*key, **MDB\_val** \*data, unsigned int flags)\ Store items into a database. int **mdb\_del** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, **MDB\_val** \*key, **MDB\_val** \*data)\ Delete items from a database. int **mdb\_cursor\_open** (**MDB\_txn** \*txn, **MDB\_dbi** dbi, **MDB\_cursor** \*\*cursor)\ Create a cursor handle. void **mdb\_cursor\_close** (**MDB\_cursor** \*cursor)\ Close a cursor handle. int **mdb\_cursor\_renew** (**MDB\_txn** \*txn, **MDB\_cursor** \*cursor)\ Renew a cursor handle. **MDB\_txn** \* **mdb\_cursor\_txn** (**MDB\_cursor** \*cursor)\ Return the cursor's transaction handle. **MDB\_dbi** **mdb\_cursor\_dbi** (**MDB\_cursor** \*cursor)\ Return the cursor's database handle. int **mdb\_cursor\_get** (**MDB\_cursor** \*cursor, **MDB\_val** \*key, **MDB\_val** \*data, **MDB\_cursor\_op** op)\ Retrieve by cursor. int **mdb\_cursor\_put** (**MDB\_cursor** \*cursor, **MDB\_val** \*key, **MDB\_val** \*data, unsigned int flags)\ Store by cursor. int **mdb\_cursor\_del** (**MDB\_cursor** \*cursor, unsigned int flags)\ Delete current key/data pair. int **mdb\_cursor\_count** (**MDB\_cursor** \*cursor, size\_t \*countp)\ Return count of duplicates for current key. 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. 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. int **mdb\_reader\_list** (**MDB\_env** \*env, **MDB\_msg\_func** \*func, void \*ctx)\ Dump the entries in the reader lock table. int **mdb\_reader\_check** (**MDB\_env** \*env, int \*dead)\ Check 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) 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) 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.* **Parameters** *major if non-NULL, the library major version number is copied here* \ *minor if non-NULL, the library minor version number is copied here* \ *patch if non-NULL, the library patch version number is copied here* **Return values** *version string The library version as a string* *Return the library version info.* ### char \* mdb\_strerror (int err) *Return a string describing a given error code. This function is a superset of the ANSI C X3.159-1989 (ANSI C) [strerror(3)](/strerror/3.md) function. If the error code is greater than or equal to 0, then the string returned by the system function [strerror(3)](/strerror/3.md) is returned. If the error code is less than 0, an error string corresponding to the LMDB library error is returned. See* **Return Codes** *for a list of LMDB-specific error codes.* **Parameters** *err The error code* **Return values** *error message The description of the error* ### int mdb\_env\_create (MDB\_env \*\* env) *Create an LMDB environment handle. This function allocates memory for a* **MDB\_env** *structure. To release the allocated memory and discard the handle, call* **mdb\_env\_close()***. Before the handle may be used, it must be opened using* **mdb\_env\_open()***. Various other options may also need to be set before opening the handle, e.g.* **mdb\_env\_set\_mapsize()***,* **mdb\_env\_set\_maxreaders()***,* **mdb\_env\_set\_maxdbs()***, depending on usage requirements.* **Parameters** *env The address where the new handle will be stored* **Returns** *A non-zero error value on failure and 0 on success.* ### int mdb\_env\_open (MDB\_env \* env, const char \* path, unsigned int flags, mdb\_mode\_t mode) *Open an environment handle. If this function fails,* **mdb\_env\_close()** *must be called to discard the* **MDB\_env** *handle.* **Parameters** *env An environment handle returned by* **mdb\_env\_create()** \ *path The directory in which the database files reside. This directory must already exist and be writable.* \ *flags Special options for this environment. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here. Flags set by* **mdb\_env\_set\_flags()** *are also used.* - • **MDB\_FIXEDMAP** *use a fixed address for the mmap region. This flag must be specified when creating the environment, and is stored persistently in the environment. If successful, the memory map will always reside at the same virtual address and pointers used to reference data items in the database will be constant across multiple invocations. This option may not always work, depending on how the operating system has allocated memory to shared libraries and other uses. The feature is highly experimental.* - • **MDB\_NOSUBDIR** *By default, LMDB creates its environment in a directory whose pathname is given in* **path***, and creates its data and lock files under that directory. With this option,* **path** *is used as-is for the database main data file. The database lock file is the* **path** *with '-lock' appended.* - • **MDB\_RDONLY** *Open the environment in read-only mode. No write operations will be allowed. LMDB will still modify the lock file - except on read-only filesystems, where LMDB does not use locks.* - • **MDB\_WRITEMAP** *Use a writeable memory map unless MDB\_RDONLY is set. This uses fewer mallocs but loses protection from application bugs like wild pointer writes and other bad updates into the database. This may be slightly faster for DBs that fit entirely in RAM, but is 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, omit the metadata flush. Defer that until the system flushes files to disk, or next non-MDB\_RDONLY commit or* **mdb\_env\_sync()***. This optimization maintains database integrity, but a system crash may undo the last committed transaction. I.e. 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 buffers are not yet flushed to disk. The risk is governed by how often the system flushes dirty buffers to disk and how often* **mdb\_env\_sync()** *is called. However, if the filesystem preserves write order and the* **MDB\_WRITEMAP** *flag is not 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 concurrent access is anticipated, the caller must manage all concurrency itself. For proper operation the caller must enforce single-writer semantics, and must ensure that no readers are using old transactions while a writer is active. The simplest approach is to use 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. The option is 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 will be 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 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 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.* **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. 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.* \ *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) *Copy an LMDB environment to the specified file descriptor, 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. See* **mdb\_env\_copy2()** *for further details.* **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.* \ *flags Special options for this operation. See* **mdb\_env\_copy2()** *for options.* **Returns** *A non-zero error value on failure and 0 on success.* ### int mdb\_env\_stat (MDB\_env \* env, MDB\_stat \* stat) *Return statistics about the LMDB environment.* **Parameters** *env An environment handle returned by* **mdb\_env\_create()** \ *stat The address of an* **MDB\_stat** *structure where the statistics will be copied* ### int mdb\_env\_info (MDB\_env \* env, MDB\_envinfo \* stat) *Return information about the LMDB environment.* **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. Data is always written to disk when* **mdb\_txn\_commit()** *is called, but the operating system may keep it buffered. LMDB always flushes the OS buffers upon commit as well, 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***.* **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 will 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. Only a single thread may call this function. All transactions, databases, and cursors must already be closed before calling this function. Attempts to use any such handles after calling this function will cause a SIGSEGV. The environment handle will be freed and must not be used again after this call.* **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. This may be used to set some flags in addition to those from* **mdb\_env\_open()***, or to unset these flags. If several threads change the flags at the same time, the result is undefined.* **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.* **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. This is the actual string in the environment, not a copy. It should not be altered in any way.* **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. This function 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. The size should be a multiple of the OS page size. The default is 10485760 bytes. The size of the memory map is also the maximum size of the database. The value should be chosen as large as possible, to accommodate future growth of the database. This function should be called after* **mdb\_env\_create()** *and before* **mdb\_env\_open()***. It may be called at later times if no transactions are active in this process. Note that the library does not check for this condition, the caller must ensure it explicitly.* *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.* **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 that is used to track readers in the the environment. 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. This function is only needed if multiple databases will be used in the environment. Simpler applications that use the environment as a single unnamed database can ignore this option. This function may only be called after* **mdb\_env\_create()** *and before* **mdb\_env\_open()***.* *Currently a moderate number of slots are 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.* **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***.* **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***.* **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.* **Note** *This hack should become obsolete as lmdb's error handling matures.* **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()***.* **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 returned by* **mdb\_env\_create()** \ *dbi A database handle returned by* **mdb\_dbi\_open()** ### int mdb\_drop (MDB\_txn \* txn, MDB\_dbi dbi, int del) *Empty or delete+close a database. See* **mdb\_dbi\_close()** *for restrictions about closing the DB handle.* **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.* **Returns** *A non-zero error value on failure and 0 on success.* ### int mdb\_set\_compare (MDB\_txn \* txn, MDB\_dbi dbi, MDB\_cmp\_func \* cmp) *Set a custom key comparison function for a database. The comparison function is called whenever it is necessary to compare a key specified by the application with a key currently stored in the database. If no comparison function is specified, and no special key flags were specified with* **mdb\_dbi\_open()***, the keys are compared lexically, with shorter keys collating before longer keys.* **Warning** *This function must be called before any data access functions are used, otherwise data corruption may occur. The same comparison function must be used by every program accessing the database, every time the database is used.* **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) *Set a custom data comparison function for a* **MDB\_DUPSORT** *database. This comparison function is called whenever it is necessary to compare a data item specified by the application with a data item currently stored in the database. This function only takes effect if the database was opened with the* **MDB\_DUPSORT** *flag. If no comparison function is specified, and no special key flags were specified with* **mdb\_dbi\_open()***, the data items are compared lexically, with shorter items collating before longer items.* **Warning** *This function must be called before any data access functions are used, otherwise data corruption may occur. The same comparison function must be used by every program accessing the database, every time the database is used.* **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) *Set a relocation function for a* **MDB\_FIXEDMAP** *database.* **Todo** *The relocation function is called whenever it is necessary to move the data of an item to a different position in the database (e.g. through tree balancing operations, shifts as a result of adds or deletes, etc.). It is intended to allow address/position-dependent data items to be stored in a database in an environment opened with the* **MDB\_FIXEDMAP** *option. Currently the relocation feature is unimplemented and setting this function has no effect.* **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) *Set a context pointer for a* **MDB\_FIXEDMAP** *database's relocation function. See* **mdb\_set\_relfunc** *and* **MDB\_rel\_func** *for more details.* **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 will be passed to the callback function set by* **mdb\_set\_relfunc** *as its* **relctx** *parameter whenever the callback is invoked.* **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 from a database. This function retrieves key/data pairs from the database. The address and length of the data associated with the specified* **key** *are returned in the structure to which* **data** *refers. If the database supports duplicate keys (***MDB\_DUPSORT***) then the first data item for the key will be returned. Retrieval of other items requires the use of* **mdb\_cursor\_get()***.* **Note** *The memory pointed to by the returned values is owned by the database. The caller need not dispose of the memory, and may not modify it in any way. For values returned in a read-only transaction any modification attempts will cause a SIGSEGV.* *Values returned from the database are valid only until a subsequent update operation, or the end of the transaction.* **Parameters** *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 are:* - • **MDB\_NOTFOUND** *- the key was not in the database.* - • *EINVAL - an invalid parameter was specified.* ### int mdb\_put (MDB\_txn \* txn, MDB\_dbi dbi, MDB\_val \* key, MDB\_val \* data, unsigned int flags) *Store items into a database. This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed (***MDB\_DUPSORT***).* **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 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.* ### int mdb\_del (MDB\_txn \* txn, MDB\_dbi dbi, MDB\_val \* key, MDB\_val \* data) *Delete items from a database. This function removes key/data pairs from the database. If the database does not support sorted duplicate data items (***MDB\_DUPSORT***) the data parameter is ignored. If the database supports 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 are:* - • *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) *Create a cursor handle. A cursor is associated with a specific transaction and database. 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.* **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 are:* - • *EINVAL - an invalid parameter was specified.* ### 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. 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) *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. 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 are:* - • *EINVAL - an invalid parameter was specified.* ### MDB\_txn \* mdb\_cursor\_txn (MDB\_cursor \* cursor) *Return the cursor's transaction handle.* **Parameters** *cursor A cursor handle returned by* **mdb\_cursor\_open()** ### MDB\_dbi mdb\_cursor\_dbi (MDB\_cursor \* cursor) *Return the cursor's database handle.* **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) *Retrieve by cursor. This function retrieves key/data pairs from the database. The address and length of the key are returned in the object to which* **key** *refers (except for the case of the* **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.* **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 are:* - • **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) *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.* **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 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.* ### int mdb\_cursor\_del (MDB\_cursor \* cursor, unsigned int flags) *Delete current key/data pair. This function deletes the key/data pair to which the cursor refers. This does not invalidate the cursor, so operations such as MDB\_NEXT can still be used on it. Both MDB\_NEXT and MDB\_GET\_CURRENT will return the same record after this operation.* **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.* - • *EINVAL - an invalid parameter was specified.* ### int mdb\_cursor\_count (MDB\_cursor \* cursor, size\_t \* countp) *Return count of duplicates for current key. This call is only valid on databases that support sorted duplicate data items* **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. This returns a comparison as if the two data items were keys in the specified database.* **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. This returns a comparison as if the two items were data items of the specified database. The database must have the* **MDB\_DUPSORT** *flag.* **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.* **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.* **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.*