.TH "mdb" 3 "Mon Jul 16 2018" "LMDB" \" -*- nroff -*- .ad l .nh .SH NAME mdb \- OpenLDAP Lightning Memory-Mapped Database Manager\&. .SH SYNOPSIS .br .PP .SS "Modules" .in +1c .ti -1c .RI "\fBVersion Macros\fP" .br .ti -1c .RI "\fBEnvironment Flags\fP" .br .ti -1c .RI "\fBDatabase Flags\fP" .br .ti -1c .RI "\fBWrite Flags\fP" .br .ti -1c .RI "\fBCopy Flags\fP" .br .ti -1c .RI "\fBReturn Codes\fP" .br .in -1c .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBMDB_val\fP" .br .RI "Generic structure used for passing keys and data in and out of the database\&. " .ti -1c .RI "struct \fBMDB_stat\fP" .br .RI "Statistics for a database in the environment\&. " .ti -1c .RI "struct \fBMDB_envinfo\fP" .br .RI "Information about the environment\&. " .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBmdb_open\fP(txn, name, flags, dbi) \fBmdb_dbi_open\fP(txn,name,flags,dbi)" .br .ti -1c .RI "#define \fBmdb_close\fP(env, dbi) \fBmdb_dbi_close\fP(env,dbi)" .br .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef unsigned int \fBMDB_dbi\fP" .br .RI "A handle for an individual database in the DB environment\&. " .ti -1c .RI "typedef int() \fBMDB_cmp_func\fP(const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)" .br .RI "A callback function used to compare two keys in a database\&. " .ti -1c .RI "typedef void() \fBMDB_rel_func\fP(\fBMDB_val\fP *item, void *oldptr, void *newptr, void *relctx)" .br .RI "A callback function used to relocate a position-dependent data item in a fixed-address database\&. " .ti -1c .RI "typedef void \fBMDB_assert_func\fP(\fBMDB_env\fP *env, const char *msg)" .br .RI "A callback function for most LMDB assert() failures, called before printing the message and aborting\&. " .ti -1c .RI "typedef int() \fBMDB_msg_func\fP(const char *msg, void *ctx)" .br .RI "A callback function used to print a message from the library\&. " .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBMDB_cursor_op\fP { \fBMDB_FIRST\fP, \fBMDB_FIRST_DUP\fP, \fBMDB_GET_BOTH\fP, \fBMDB_GET_BOTH_RANGE\fP, \fBMDB_GET_CURRENT\fP, \fBMDB_GET_MULTIPLE\fP, \fBMDB_LAST\fP, \fBMDB_LAST_DUP\fP, \fBMDB_NEXT\fP, \fBMDB_NEXT_DUP\fP, \fBMDB_NEXT_MULTIPLE\fP, \fBMDB_NEXT_NODUP\fP, \fBMDB_PREV\fP, \fBMDB_PREV_DUP\fP, \fBMDB_PREV_NODUP\fP, \fBMDB_SET\fP, \fBMDB_SET_KEY\fP, \fBMDB_SET_RANGE\fP, \fBMDB_PREV_MULTIPLE\fP } .RI "Cursor Get operations\&. "" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "char * \fBmdb_version\fP (int *major, int *minor, int *patch)" .br .RI "Return the LMDB library version information\&. " .ti -1c .RI "char * \fBmdb_strerror\fP (int err)" .br .RI "Return a string describing a given error code\&. " .ti -1c .RI "int \fBmdb_env_create\fP (\fBMDB_env\fP **env)" .br .RI "Create an LMDB environment handle\&. " .ti -1c .RI "int \fBmdb_env_open\fP (\fBMDB_env\fP *env, const char *path, unsigned int flags, \fBmdb_mode_t\fP mode)" .br .RI "Open an environment handle\&. " .ti -1c .RI "int \fBmdb_env_copy\fP (\fBMDB_env\fP *env, const char *path)" .br .RI "Copy an LMDB environment to the specified path\&. " .ti -1c .RI "int \fBmdb_env_copyfd\fP (\fBMDB_env\fP *env, \fBmdb_filehandle_t\fP fd)" .br .RI "Copy an LMDB environment to the specified file descriptor\&. " .ti -1c .RI "int \fBmdb_env_copy2\fP (\fBMDB_env\fP *env, const char *path, unsigned int flags)" .br .RI "Copy an LMDB environment to the specified path, with options\&. " .ti -1c .RI "int \fBmdb_env_copyfd2\fP (\fBMDB_env\fP *env, \fBmdb_filehandle_t\fP fd, unsigned int flags)" .br .RI "Copy an LMDB environment to the specified file descriptor, with options\&. " .ti -1c .RI "int \fBmdb_env_stat\fP (\fBMDB_env\fP *env, \fBMDB_stat\fP *stat)" .br .RI "Return statistics about the LMDB environment\&. " .ti -1c .RI "int \fBmdb_env_info\fP (\fBMDB_env\fP *env, \fBMDB_envinfo\fP *stat)" .br .RI "Return information about the LMDB environment\&. " .ti -1c .RI "int \fBmdb_env_sync\fP (\fBMDB_env\fP *env, int force)" .br .RI "Flush the data buffers to disk\&. " .ti -1c .RI "void \fBmdb_env_close\fP (\fBMDB_env\fP *env)" .br .RI "Close the environment and release the memory map\&. " .ti -1c .RI "int \fBmdb_env_set_flags\fP (\fBMDB_env\fP *env, unsigned int flags, int onoff)" .br .RI "Set environment flags\&. " .ti -1c .RI "int \fBmdb_env_get_flags\fP (\fBMDB_env\fP *env, unsigned int *flags)" .br .RI "Get environment flags\&. " .ti -1c .RI "int \fBmdb_env_get_path\fP (\fBMDB_env\fP *env, const char **path)" .br .RI "Return the path that was used in \fBmdb_env_open()\fP\&. " .ti -1c .RI "int \fBmdb_env_get_fd\fP (\fBMDB_env\fP *env, \fBmdb_filehandle_t\fP *fd)" .br .RI "Return the filedescriptor for the given environment\&. " .ti -1c .RI "int \fBmdb_env_set_mapsize\fP (\fBMDB_env\fP *env, size_t size)" .br .RI "Set the size of the memory map to use for this environment\&. " .ti -1c .RI "int \fBmdb_env_set_maxreaders\fP (\fBMDB_env\fP *env, unsigned int readers)" .br .RI "Set the maximum number of threads/reader slots for the environment\&. " .ti -1c .RI "int \fBmdb_env_get_maxreaders\fP (\fBMDB_env\fP *env, unsigned int *readers)" .br .RI "Get the maximum number of threads/reader slots for the environment\&. " .ti -1c .RI "int \fBmdb_env_set_maxdbs\fP (\fBMDB_env\fP *env, \fBMDB_dbi\fP dbs)" .br .RI "Set the maximum number of named databases for the environment\&. " .ti -1c .RI "int \fBmdb_env_get_maxkeysize\fP (\fBMDB_env\fP *env)" .br .RI "Get the maximum size of keys and \fBMDB_DUPSORT\fP data we can write\&. " .ti -1c .RI "int \fBmdb_env_set_userctx\fP (\fBMDB_env\fP *env, void *ctx)" .br .RI "Set application information associated with the \fBMDB_env\fP\&. " .ti -1c .RI "void * \fBmdb_env_get_userctx\fP (\fBMDB_env\fP *env)" .br .RI "Get the application information associated with the \fBMDB_env\fP\&. " .ti -1c .RI "int \fBmdb_env_set_assert\fP (\fBMDB_env\fP *env, \fBMDB_assert_func\fP *func)" .br .ti -1c .RI "int \fBmdb_txn_begin\fP (\fBMDB_env\fP *env, \fBMDB_txn\fP *parent, unsigned int flags, \fBMDB_txn\fP **txn)" .br .RI "Create a transaction for use with the environment\&. " .ti -1c .RI "\fBMDB_env\fP * \fBmdb_txn_env\fP (\fBMDB_txn\fP *txn)" .br .RI "Returns the transaction's \fBMDB_env\fP\&. " .ti -1c .RI "size_t \fBmdb_txn_id\fP (\fBMDB_txn\fP *txn)" .br .RI "Return the transaction's ID\&. " .ti -1c .RI "int \fBmdb_txn_commit\fP (\fBMDB_txn\fP *txn)" .br .RI "Commit all the operations of a transaction into the database\&. " .ti -1c .RI "void \fBmdb_txn_abort\fP (\fBMDB_txn\fP *txn)" .br .RI "Abandon all the operations of the transaction instead of saving them\&. " .ti -1c .RI "void \fBmdb_txn_reset\fP (\fBMDB_txn\fP *txn)" .br .RI "Reset a read-only transaction\&. " .ti -1c .RI "int \fBmdb_txn_renew\fP (\fBMDB_txn\fP *txn)" .br .RI "Renew a read-only transaction\&. " .ti -1c .RI "int \fBmdb_dbi_open\fP (\fBMDB_txn\fP *txn, const char *name, unsigned int flags, \fBMDB_dbi\fP *dbi)" .br .RI "Open a database in the environment\&. " .ti -1c .RI "int \fBmdb_stat\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_stat\fP *stat)" .br .RI "Retrieve statistics for a database\&. " .ti -1c .RI "int \fBmdb_dbi_flags\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, unsigned int *flags)" .br .RI "Retrieve the DB flags for a database handle\&. " .ti -1c .RI "void \fBmdb_dbi_close\fP (\fBMDB_env\fP *env, \fBMDB_dbi\fP dbi)" .br .RI "Close a database handle\&. Normally unnecessary\&. Use with care: " .ti -1c .RI "int \fBmdb_drop\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, int del)" .br .RI "Empty or delete+close a database\&. " .ti -1c .RI "int \fBmdb_set_compare\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_cmp_func\fP *cmp)" .br .RI "Set a custom key comparison function for a database\&. " .ti -1c .RI "int \fBmdb_set_dupsort\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_cmp_func\fP *cmp)" .br .RI "Set a custom data comparison function for a \fBMDB_DUPSORT\fP database\&. " .ti -1c .RI "int \fBmdb_set_relfunc\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_rel_func\fP *rel)" .br .RI "Set a relocation function for a \fBMDB_FIXEDMAP\fP database\&. " .ti -1c .RI "int \fBmdb_set_relctx\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, void *ctx)" .br .RI "Set a context pointer for a \fBMDB_FIXEDMAP\fP database's relocation function\&. " .ti -1c .RI "int \fBmdb_get\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_val\fP *key, \fBMDB_val\fP *data)" .br .RI "Get items from a database\&. " .ti -1c .RI "int \fBmdb_put\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_val\fP *key, \fBMDB_val\fP *data, unsigned int flags)" .br .RI "Store items into a database\&. " .ti -1c .RI "int \fBmdb_del\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_val\fP *key, \fBMDB_val\fP *data)" .br .RI "Delete items from a database\&. " .ti -1c .RI "int \fBmdb_cursor_open\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_cursor\fP **cursor)" .br .RI "Create a cursor handle\&. " .ti -1c .RI "void \fBmdb_cursor_close\fP (\fBMDB_cursor\fP *cursor)" .br .RI "Close a cursor handle\&. " .ti -1c .RI "int \fBmdb_cursor_renew\fP (\fBMDB_txn\fP *txn, \fBMDB_cursor\fP *cursor)" .br .RI "Renew a cursor handle\&. " .ti -1c .RI "\fBMDB_txn\fP * \fBmdb_cursor_txn\fP (\fBMDB_cursor\fP *cursor)" .br .RI "Return the cursor's transaction handle\&. " .ti -1c .RI "\fBMDB_dbi\fP \fBmdb_cursor_dbi\fP (\fBMDB_cursor\fP *cursor)" .br .RI "Return the cursor's database handle\&. " .ti -1c .RI "int \fBmdb_cursor_get\fP (\fBMDB_cursor\fP *cursor, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fP op)" .br .RI "Retrieve by cursor\&. " .ti -1c .RI "int \fBmdb_cursor_put\fP (\fBMDB_cursor\fP *cursor, \fBMDB_val\fP *key, \fBMDB_val\fP *data, unsigned int flags)" .br .RI "Store by cursor\&. " .ti -1c .RI "int \fBmdb_cursor_del\fP (\fBMDB_cursor\fP *cursor, unsigned int flags)" .br .RI "Delete current key/data pair\&. " .ti -1c .RI "int \fBmdb_cursor_count\fP (\fBMDB_cursor\fP *cursor, size_t *countp)" .br .RI "Return count of duplicates for current key\&. " .ti -1c .RI "int \fBmdb_cmp\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)" .br .RI "Compare two data items according to a particular database\&. " .ti -1c .RI "int \fBmdb_dcmp\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)" .br .RI "Compare two data items according to a particular database\&. " .ti -1c .RI "int \fBmdb_reader_list\fP (\fBMDB_env\fP *env, \fBMDB_msg_func\fP *func, void *ctx)" .br .RI "Dump the entries in the reader lock table\&. " .ti -1c .RI "int \fBmdb_reader_check\fP (\fBMDB_env\fP *env, int *dead)" .br .RI "Check for stale entries in the reader lock table\&. " .in -1c .SH "Detailed Description" .PP OpenLDAP Lightning Memory-Mapped Database Manager\&. .SH "Data Structure Documentation" .PP .SH "struct MDB_val" .PP Generic structure used for passing keys and data in and out of the database\&. Values returned from the database are valid only until a subsequent update operation, or the end of the transaction\&. Do not modify or free them, they commonly point into the database itself\&. .PP Key sizes must be between 1 and \fBmdb_env_get_maxkeysize()\fP inclusive\&. The same applies to data sizes in databases with the \fBMDB_DUPSORT\fP flag\&. Other data items can in theory be from 0 to 0xffffffff bytes long\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "size_t \fBmv_size\fP" .br .ti -1c .RI "void * \fBmv_data\fP" .br .in -1c .SH "Field Documentation" .PP .SS "size_t MDB_val::mv_size" size of the data item .SS "void* MDB_val::mv_data" address of the data item .SH "struct MDB_stat" .PP Statistics for a database in the environment\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "unsigned int \fBms_psize\fP" .br .ti -1c .RI "unsigned int \fBms_depth\fP" .br .ti -1c .RI "size_t \fBms_branch_pages\fP" .br .ti -1c .RI "size_t \fBms_leaf_pages\fP" .br .ti -1c .RI "size_t \fBms_overflow_pages\fP" .br .ti -1c .RI "size_t \fBms_entries\fP" .br .in -1c .SH "Field Documentation" .PP .SS "unsigned int MDB_stat::ms_psize" Size of a database page\&. This is currently the same for all databases\&. .SS "unsigned int MDB_stat::ms_depth" Depth (height) of the B-tree .SS "size_t MDB_stat::ms_branch_pages" Number of internal (non-leaf) pages .SS "size_t MDB_stat::ms_leaf_pages" Number of leaf pages .SS "size_t MDB_stat::ms_overflow_pages" Number of overflow pages .SS "size_t MDB_stat::ms_entries" Number of data items .SH "struct MDB_envinfo" .PP Information about the environment\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "void * \fBme_mapaddr\fP" .br .ti -1c .RI "size_t \fBme_mapsize\fP" .br .ti -1c .RI "size_t \fBme_last_pgno\fP" .br .ti -1c .RI "size_t \fBme_last_txnid\fP" .br .ti -1c .RI "unsigned int \fBme_maxreaders\fP" .br .ti -1c .RI "unsigned int \fBme_numreaders\fP" .br .in -1c .SH "Field Documentation" .PP .SS "void* MDB_envinfo::me_mapaddr" Address of map, if fixed .SS "size_t MDB_envinfo::me_mapsize" Size of the data memory map .SS "size_t MDB_envinfo::me_last_pgno" ID of the last used page .SS "size_t MDB_envinfo::me_last_txnid" ID of the last committed transaction .SS "unsigned int MDB_envinfo::me_maxreaders" max reader slots in the environment .SS "unsigned int MDB_envinfo::me_numreaders" max reader slots used in the environment .SH "Macro Definition Documentation" .PP .SS "#define mdb_open(txn, name, flags, dbi) \fBmdb_dbi_open\fP(txn,name,flags,dbi)" Compat with version <= 0\&.9\&.4, avoid clash with libmdb from MDB Tools project .SS "#define mdb_close(env, dbi) \fBmdb_dbi_close\fP(env,dbi)" Compat with version <= 0\&.9\&.4, avoid clash with libmdb from MDB Tools project .SH "Typedef Documentation" .PP .SS "typedef void() MDB_rel_func(\fBMDB_val\fP *item, void *oldptr, void *newptr, void *relctx)" .PP A callback function used to relocate a position-dependent data item in a fixed-address database\&. The \fBnewptr\fP gives the item's desired address in the memory map, and \fBoldptr\fP gives its previous address\&. The item's actual data resides at the address in \fBitem\fP\&. This callback is expected to walk through the fields of the record in \fBitem\fP and modify any values based at the \fBoldptr\fP address to be relative to the \fBnewptr\fP address\&. .PP \fBParameters:\fP .RS 4 \fIitem\fP The item that is to be relocated\&. .br \fIoldptr\fP The previous address\&. .br \fInewptr\fP The new address to relocate to\&. .br \fIrelctx\fP An application-provided context, set by \fBmdb_set_relctx()\fP\&. .RE .PP \fBTodo\fP .RS 4 This feature is currently unimplemented\&. .RE .PP .SS "typedef void MDB_assert_func(\fBMDB_env\fP *env, const char *msg)" .PP A callback function for most LMDB assert() failures, called before printing the message and aborting\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP\&. .br \fImsg\fP The assertion message, not including newline\&. .RE .PP .SS "typedef int() MDB_msg_func(const char *msg, void *ctx)" .PP A callback function used to print a message from the library\&. .PP \fBParameters:\fP .RS 4 \fImsg\fP The string to be printed\&. .br \fIctx\fP An arbitrary context pointer for the callback\&. .RE .PP \fBReturns:\fP .RS 4 < 0 on failure, >= 0 on success\&. .RE .PP .SH "Enumeration Type Documentation" .PP .SS "enum \fBMDB_cursor_op\fP" .PP Cursor Get operations\&. This is the set of all operations for retrieving data using a cursor\&. .PP \fBEnumerator\fP .in +1c .TP \fB\fIMDB_FIRST \fP\fP Position at first key/data item .TP \fB\fIMDB_FIRST_DUP \fP\fP Position at first data item of current key\&. Only for \fBMDB_DUPSORT\fP .TP \fB\fIMDB_GET_BOTH \fP\fP Position at key/data pair\&. Only for \fBMDB_DUPSORT\fP .TP \fB\fIMDB_GET_BOTH_RANGE \fP\fP position at key, nearest data\&. Only for \fBMDB_DUPSORT\fP .TP \fB\fIMDB_GET_CURRENT \fP\fP Return key/data at current cursor position .TP \fB\fIMDB_GET_MULTIPLE \fP\fP Return key and up to a page of duplicate data items from current cursor position\&. Move cursor to prepare for \fBMDB_NEXT_MULTIPLE\fP\&. Only for \fBMDB_DUPFIXED\fP .TP \fB\fIMDB_LAST \fP\fP Position at last key/data item .TP \fB\fIMDB_LAST_DUP \fP\fP Position at last data item of current key\&. Only for \fBMDB_DUPSORT\fP .TP \fB\fIMDB_NEXT \fP\fP Position at next data item .TP \fB\fIMDB_NEXT_DUP \fP\fP Position at next data item of current key\&. Only for \fBMDB_DUPSORT\fP .TP \fB\fIMDB_NEXT_MULTIPLE \fP\fP Return key and up to a page of duplicate data items from next cursor position\&. Move cursor to prepare for \fBMDB_NEXT_MULTIPLE\fP\&. Only for \fBMDB_DUPFIXED\fP .TP \fB\fIMDB_NEXT_NODUP \fP\fP Position at first data item of next key .TP \fB\fIMDB_PREV \fP\fP Position at previous data item .TP \fB\fIMDB_PREV_DUP \fP\fP Position at previous data item of current key\&. Only for \fBMDB_DUPSORT\fP .TP \fB\fIMDB_PREV_NODUP \fP\fP Position at last data item of previous key .TP \fB\fIMDB_SET \fP\fP Position at specified key .TP \fB\fIMDB_SET_KEY \fP\fP Position at specified key, return key + data .TP \fB\fIMDB_SET_RANGE \fP\fP Position at first key greater than or equal to specified key\&. .TP \fB\fIMDB_PREV_MULTIPLE \fP\fP Position at previous page and return key and up to a page of duplicate data items\&. Only for \fBMDB_DUPFIXED\fP .SH "Function Documentation" .PP .SS "char* mdb_version (int * major, int * minor, int * patch)" .PP Return the LMDB library version information\&. .PP \fBParameters:\fP .RS 4 \fImajor\fP if non-NULL, the library major version number is copied here .br \fIminor\fP if non-NULL, the library minor version number is copied here .br \fIpatch\fP if non-NULL, the library patch version number is copied here .RE .PP \fBReturn values:\fP .RS 4 \fIversion string\fP The library version as a string .RE .PP Return the library version info\&. .SS "char* mdb_strerror (int err)" .PP Return a string describing a given error code\&. This function is a superset of the ANSI C X3\&.159-1989 (ANSI C) strerror(3) function\&. If the error code is greater than or equal to 0, then the string returned by the system function strerror(3) is returned\&. If the error code is less than 0, an error string corresponding to the LMDB library error is returned\&. See \fBReturn Codes\fP for a list of LMDB-specific error codes\&. .PP \fBParameters:\fP .RS 4 \fIerr\fP The error code .RE .PP \fBReturn values:\fP .RS 4 \fIerror message\fP The description of the error .RE .PP .SS "int mdb_env_create (\fBMDB_env\fP ** env)" .PP Create an LMDB environment handle\&. This function allocates memory for a \fBMDB_env\fP structure\&. To release the allocated memory and discard the handle, call \fBmdb_env_close()\fP\&. Before the handle may be used, it must be opened using \fBmdb_env_open()\fP\&. Various other options may also need to be set before opening the handle, e\&.g\&. \fBmdb_env_set_mapsize()\fP, \fBmdb_env_set_maxreaders()\fP, \fBmdb_env_set_maxdbs()\fP, depending on usage requirements\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP The address where the new handle will be stored .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "int mdb_env_open (\fBMDB_env\fP * env, const char * path, unsigned int flags, \fBmdb_mode_t\fP mode)" .PP Open an environment handle\&. If this function fails, \fBmdb_env_close()\fP must be called to discard the \fBMDB_env\fP handle\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIpath\fP The directory in which the database files reside\&. This directory must already exist and be writable\&. .br \fIflags\fP 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 \fBmdb_env_set_flags()\fP are also used\&. .PD 0 .IP "\(bu" 2 \fBMDB_FIXEDMAP\fP 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\&. .IP "\(bu" 2 \fBMDB_NOSUBDIR\fP By default, LMDB creates its environment in a directory whose pathname is given in \fBpath\fP, and creates its data and lock files under that directory\&. With this option, \fBpath\fP is used as-is for the database main data file\&. The database lock file is the \fBpath\fP with '-lock' appended\&. .IP "\(bu" 2 \fBMDB_RDONLY\fP 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\&. .IP "\(bu" 2 \fBMDB_WRITEMAP\fP 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 (\fBmdb_env_sync\fP etc)\&. .IP "\(bu" 2 \fBMDB_NOMETASYNC\fP 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 \fBmdb_env_sync()\fP\&. 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 \fBmdb_env_set_flags()\fP\&. .IP "\(bu" 2 \fBMDB_NOSYNC\fP 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 \fBmdb_env_sync()\fP is called\&. However, if the filesystem preserves write order and the \fBMDB_WRITEMAP\fP 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 (\fBMDB_NOSYNC\fP | \fBMDB_WRITEMAP\fP) leaves the system with no hint for when to write transactions to disk, unless \fBmdb_env_sync()\fP is called\&. (\fBMDB_MAPASYNC\fP | \fBMDB_WRITEMAP\fP) may be preferable\&. This flag may be changed at any time using \fBmdb_env_set_flags()\fP\&. .IP "\(bu" 2 \fBMDB_MAPASYNC\fP When using \fBMDB_WRITEMAP\fP, use asynchronous flushes to disk\&. As with \fBMDB_NOSYNC\fP, a system crash can then corrupt the database or lose the last transactions\&. Calling \fBmdb_env_sync()\fP ensures on-disk database integrity until next commit\&. This flag may be changed at any time using \fBmdb_env_set_flags()\fP\&. .IP "\(bu" 2 \fBMDB_NOTLS\fP Don't use Thread-Local Storage\&. Tie reader locktable slots to \fBMDB_txn\fP objects instead of to threads\&. I\&.e\&. \fBmdb_txn_reset()\fP keeps the slot reseved for the \fBMDB_txn\fP 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\&. .IP "\(bu" 2 \fBMDB_NOLOCK\fP 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\&. .IP "\(bu" 2 \fBMDB_NORDAHEAD\fP 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\&. .IP "\(bu" 2 \fBMDB_NOMEMINIT\fP 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 \fBMDB_WRITEMAP\fP, which writes directly to the mmap instead of using malloc for pages\&. The initialization is also skipped if \fBMDB_RESERVE\fP 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 \fBmdb_env_set_flags()\fP\&. .PP .br \fImode\fP The UNIX permissions to set on created files and semaphores\&. This parameter is ignored on Windows\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 \fBMDB_VERSION_MISMATCH\fP - the version of the LMDB library doesn't match the version that created the database environment\&. .IP "\(bu" 2 \fBMDB_INVALID\fP - the environment file headers are corrupted\&. .IP "\(bu" 2 ENOENT - the directory specified by the path parameter doesn't exist\&. .IP "\(bu" 2 EACCES - the user didn't have permission to access the environment files\&. .IP "\(bu" 2 EAGAIN - the environment was locked by another process\&. .PP .RE .PP .SS "int mdb_env_copy (\fBMDB_env\fP * env, const char * path)" .PP 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\&. .PP \fBNote:\fP .RS 4 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 \fBCaveats\fP\&. .RE .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP\&. It must have already been opened successfully\&. .br \fIpath\fP The directory in which the copy will reside\&. This directory must already exist and be writable but must otherwise be empty\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "int mdb_env_copyfd (\fBMDB_env\fP * env, \fBmdb_filehandle_t\fP fd)" .PP 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\&. .PP \fBNote:\fP .RS 4 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 \fBCaveats\fP\&. .RE .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP\&. It must have already been opened successfully\&. .br \fIfd\fP The filedescriptor to write the copy to\&. It must have already been opened for Write access\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "int mdb_env_copy2 (\fBMDB_env\fP * env, const char * path, unsigned int flags)" .PP 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\&. .PP \fBNote:\fP .RS 4 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 \fBCaveats\fP\&. .RE .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP\&. It must have already been opened successfully\&. .br \fIpath\fP The directory in which the copy will reside\&. This directory must already exist and be writable but must otherwise be empty\&. .br \fIflags\fP 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\&. .PD 0 .IP "\(bu" 2 \fBMDB_CP_COMPACT\fP - 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\&. .PP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "int mdb_env_copyfd2 (\fBMDB_env\fP * env, \fBmdb_filehandle_t\fP fd, unsigned int flags)" .PP 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 \fBmdb_env_copy2()\fP for further details\&. .PP \fBNote:\fP .RS 4 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 \fBCaveats\fP\&. .RE .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP\&. It must have already been opened successfully\&. .br \fIfd\fP The filedescriptor to write the copy to\&. It must have already been opened for Write access\&. .br \fIflags\fP Special options for this operation\&. See \fBmdb_env_copy2()\fP for options\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "int mdb_env_stat (\fBMDB_env\fP * env, \fBMDB_stat\fP * stat)" .PP Return statistics about the LMDB environment\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIstat\fP The address of an \fBMDB_stat\fP structure where the statistics will be copied .RE .PP .SS "int mdb_env_info (\fBMDB_env\fP * env, \fBMDB_envinfo\fP * stat)" .PP Return information about the LMDB environment\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIstat\fP The address of an \fBMDB_envinfo\fP structure where the information will be copied .RE .PP .SS "int mdb_env_sync (\fBMDB_env\fP * env, int force)" .PP Flush the data buffers to disk\&. Data is always written to disk when \fBmdb_txn_commit()\fP 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 \fBMDB_NOSYNC\fP or in part \fBMDB_NOMETASYNC\fP\&. This call is not valid if the environment was opened with \fBMDB_RDONLY\fP\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIforce\fP If non-zero, force a synchronous flush\&. Otherwise if the environment has the \fBMDB_NOSYNC\fP flag set the flushes will be omitted, and with \fBMDB_MAPASYNC\fP they will be asynchronous\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EACCES - the environment is read-only\&. .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .IP "\(bu" 2 EIO - an error occurred during synchronization\&. .PP .RE .PP .SS "void mdb_env_close (\fBMDB_env\fP * env)" .PP 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\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .RE .PP .SS "int mdb_env_set_flags (\fBMDB_env\fP * env, unsigned int flags, int onoff)" .PP Set environment flags\&. This may be used to set some flags in addition to those from \fBmdb_env_open()\fP, or to unset these flags\&. If several threads change the flags at the same time, the result is undefined\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIflags\fP The flags to change, bitwise OR'ed together .br \fIonoff\fP A non-zero value sets the flags, zero clears them\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_env_get_flags (\fBMDB_env\fP * env, unsigned int * flags)" .PP Get environment flags\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIflags\fP The address of an integer to store the flags .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_env_get_path (\fBMDB_env\fP * env, const char ** path)" .PP Return the path that was used in \fBmdb_env_open()\fP\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIpath\fP 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\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_env_get_fd (\fBMDB_env\fP * env, \fBmdb_filehandle_t\fP * fd)" .PP 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\&.) .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIfd\fP Address of a mdb_filehandle_t to contain the descriptor\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_env_set_mapsize (\fBMDB_env\fP * env, size_t size)" .PP 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 \fBmdb_env_create()\fP and before \fBmdb_env_open()\fP\&. 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\&. .PP 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\&. .PP If the mapsize is increased by another process, and data has grown beyond the range of the current mapsize, \fBmdb_txn_begin()\fP will return \fBMDB_MAP_RESIZED\fP\&. This function may be called with a size of zero to adopt the new size\&. .PP 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\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIsize\fP The size in bytes .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified, or the environment has an active write transaction\&. .PP .RE .PP .SS "int mdb_env_set_maxreaders (\fBMDB_env\fP * env, unsigned int readers)" .PP 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, \fBmdb_txn_begin()\fP instead ties the slot to the \fBMDB_txn\fP object until it or the \fBMDB_env\fP object is destroyed\&. This function may only be called after \fBmdb_env_create()\fP and before \fBmdb_env_open()\fP\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIreaders\fP The maximum number of reader lock table slots .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified, or the environment is already open\&. .PP .RE .PP .SS "int mdb_env_get_maxreaders (\fBMDB_env\fP * env, unsigned int * readers)" .PP Get the maximum number of threads/reader slots for the environment\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIreaders\fP Address of an integer to store the number of readers .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_env_set_maxdbs (\fBMDB_env\fP * env, \fBMDB_dbi\fP dbs)" .PP 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 \fBmdb_env_create()\fP and before \fBmdb_env_open()\fP\&. .PP Currently a moderate number of slots are cheap but a huge number gets expensive: 7-120 words per transaction, and every \fBmdb_dbi_open()\fP does a linear search of the opened slots\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIdbs\fP The maximum number of databases .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified, or the environment is already open\&. .PP .RE .PP .SS "int mdb_env_get_maxkeysize (\fBMDB_env\fP * env)" .PP Get the maximum size of keys and \fBMDB_DUPSORT\fP data we can write\&. Depends on the compile-time constant \fBMDB_MAXKEYSIZE\fP\&. Default 511\&. See \fBMDB_val\fP\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .RE .PP \fBReturns:\fP .RS 4 The maximum size of a key we can write .RE .PP .SS "int mdb_env_set_userctx (\fBMDB_env\fP * env, void * ctx)" .PP Set application information associated with the \fBMDB_env\fP\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIctx\fP An arbitrary pointer for whatever the application needs\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "void* mdb_env_get_userctx (\fBMDB_env\fP * env)" .PP Get the application information associated with the \fBMDB_env\fP\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .RE .PP \fBReturns:\fP .RS 4 The pointer set by \fBmdb_env_set_userctx()\fP\&. .RE .PP .SS "int mdb_env_set_assert (\fBMDB_env\fP * env, \fBMDB_assert_func\fP * func)" Set or reset the assert() callback of the environment\&. Disabled if liblmdb is buillt with NDEBUG\&. .PP \fBNote:\fP .RS 4 This hack should become obsolete as lmdb's error handling matures\&. .RE .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP\&. .br \fIfunc\fP An \fBMDB_assert_func\fP function, or 0\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "int mdb_txn_begin (\fBMDB_env\fP * env, \fBMDB_txn\fP * parent, unsigned int flags, \fBMDB_txn\fP ** txn)" .PP Create a transaction for use with the environment\&. The transaction handle may be discarded using \fBmdb_txn_abort()\fP or \fBmdb_txn_commit()\fP\&. .PP \fBNote:\fP .RS 4 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 \fBMDB_NOTLS\fP is in use, this does not apply to read-only transactions\&. .PP Cursors may not span transactions\&. .RE .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIparent\fP If this parameter is non-NULL, the new transaction will be a nested transaction, with the transaction indicated by \fBparent\fP 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\&. .br \fIflags\fP 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\&. .PD 0 .IP "\(bu" 2 \fBMDB_RDONLY\fP This transaction will not perform any write operations\&. .PP .br \fItxn\fP Address where the new \fBMDB_txn\fP handle will be stored .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 \fBMDB_PANIC\fP - a fatal error occurred earlier and the environment must be shut down\&. .IP "\(bu" 2 \fBMDB_MAP_RESIZED\fP - another process wrote data beyond this \fBMDB_env\fP's mapsize and this environment's map must be resized as well\&. See \fBmdb_env_set_mapsize()\fP\&. .IP "\(bu" 2 \fBMDB_READERS_FULL\fP - a read-only transaction was requested and the reader lock table is full\&. See \fBmdb_env_set_maxreaders()\fP\&. .IP "\(bu" 2 ENOMEM - out of memory\&. .PP .RE .PP .SS "\fBMDB_env\fP* mdb_txn_env (\fBMDB_txn\fP * txn)" .PP Returns the transaction's \fBMDB_env\fP\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .RE .PP .SS "size_t mdb_txn_id (\fBMDB_txn\fP * txn)" .PP 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\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .RE .PP \fBReturns:\fP .RS 4 A transaction ID, valid if input is an active transaction\&. .RE .PP .SS "int mdb_txn_commit (\fBMDB_txn\fP * txn)" .PP 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 \fBmdb_cursor_renew()\fP\&. .PP \fBNote:\fP .RS 4 Earlier documentation incorrectly said all cursors would be freed\&. Only write-transactions free cursors\&. .RE .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .IP "\(bu" 2 ENOSPC - no more disk space\&. .IP "\(bu" 2 EIO - a low-level I/O error occurred while writing\&. .IP "\(bu" 2 ENOMEM - out of memory\&. .PP .RE .PP .SS "void mdb_txn_abort (\fBMDB_txn\fP * txn)" .PP 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 \fBmdb_cursor_renew()\fP\&. .PP \fBNote:\fP .RS 4 Earlier documentation incorrectly said all cursors would be freed\&. Only write-transactions free cursors\&. .RE .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .RE .PP .SS "void mdb_txn_reset (\fBMDB_txn\fP * txn)" .PP Reset a read-only transaction\&. Abort the transaction like \fBmdb_txn_abort()\fP, but keep the transaction handle\&. \fBmdb_txn_renew()\fP may reuse the handle\&. This saves allocation overhead if the process will start a new read-only transaction soon, and also locking overhead if \fBMDB_NOTLS\fP is in use\&. The reader table lock is released, but the table slot stays tied to its thread or \fBMDB_txn\fP\&. Use \fBmdb_txn_abort()\fP 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 \fBmdb_cursor_renew()\fP\&. 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\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .RE .PP .SS "int mdb_txn_renew (\fBMDB_txn\fP * txn)" .PP Renew a read-only transaction\&. This acquires a new reader lock for a transaction handle that had been released by \fBmdb_txn_reset()\fP\&. It must be called before a reset transaction may be used again\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 \fBMDB_PANIC\fP - a fatal error occurred earlier and the environment must be shut down\&. .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_dbi_open (\fBMDB_txn\fP * txn, const char * name, unsigned int flags, \fBMDB_dbi\fP * dbi)" .PP 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 \fBmdb_dbi_close()\fP\&. The old database handle is returned if the database was already open\&. The handle may only be closed once\&. .PP 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\&. .PP 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\&. .PP To use named databases (with name != NULL), \fBmdb_env_set_maxdbs()\fP must be called before opening the environment\&. Database names are keys in the unnamed database, and may be read but not written\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIname\fP The name of the database to open\&. If only a single database is needed in the environment, this value may be NULL\&. .br \fIflags\fP 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\&. .PD 0 .IP "\(bu" 2 \fBMDB_REVERSEKEY\fP 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\&. .IP "\(bu" 2 \fBMDB_DUPSORT\fP 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\&. .IP "\(bu" 2 \fBMDB_INTEGERKEY\fP 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\&. .IP "\(bu" 2 \fBMDB_DUPFIXED\fP This flag may only be used in combination with \fBMDB_DUPSORT\fP\&. 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 \fBMDB_GET_MULTIPLE\fP, \fBMDB_NEXT_MULTIPLE\fP and \fBMDB_PREV_MULTIPLE\fP cursor operations may be used to retrieve multiple items at once\&. .IP "\(bu" 2 \fBMDB_INTEGERDUP\fP This option specifies that duplicate data items are binary integers, similar to \fBMDB_INTEGERKEY\fP keys\&. .IP "\(bu" 2 \fBMDB_REVERSEDUP\fP This option specifies that duplicate data items should be compared as strings in reverse order\&. .IP "\(bu" 2 \fBMDB_CREATE\fP Create the named database if it doesn't exist\&. This option is not allowed in a read-only transaction or a read-only environment\&. .PP .br \fIdbi\fP Address where the new \fBMDB_dbi\fP handle will be stored .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 \fBMDB_NOTFOUND\fP - the specified database doesn't exist in the environment and \fBMDB_CREATE\fP was not specified\&. .IP "\(bu" 2 \fBMDB_DBS_FULL\fP - too many databases have been opened\&. See \fBmdb_env_set_maxdbs()\fP\&. .PP .RE .PP .SS "int mdb_stat (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, \fBMDB_stat\fP * stat)" .PP Retrieve statistics for a database\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIstat\fP The address of an \fBMDB_stat\fP structure where the statistics will be copied .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_dbi_flags (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, unsigned int * flags)" .PP Retrieve the DB flags for a database handle\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIflags\fP Address where the flags will be returned\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "void mdb_dbi_close (\fBMDB_env\fP * env, \fBMDB_dbi\fP dbi)" .PP 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)\&. .PP Closing a database handle is not necessary, but lets \fBmdb_dbi_open()\fP reuse the handle value\&. Usually it's better to set a bigger \fBmdb_env_set_maxdbs()\fP, unless that value would be large\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .RE .PP .SS "int mdb_drop (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, int del)" .PP Empty or delete+close a database\&. See \fBmdb_dbi_close()\fP for restrictions about closing the DB handle\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIdel\fP 0 to empty the DB, 1 to delete it from the environment and close the DB handle\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "int mdb_set_compare (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, \fBMDB_cmp_func\fP * cmp)" .PP 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 \fBmdb_dbi_open()\fP, the keys are compared lexically, with shorter keys collating before longer keys\&. .PP \fBWarning:\fP .RS 4 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\&. .RE .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIcmp\fP A \fBMDB_cmp_func\fP function .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_set_dupsort (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, \fBMDB_cmp_func\fP * cmp)" .PP Set a custom data comparison function for a \fBMDB_DUPSORT\fP 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 \fBMDB_DUPSORT\fP flag\&. If no comparison function is specified, and no special key flags were specified with \fBmdb_dbi_open()\fP, the data items are compared lexically, with shorter items collating before longer items\&. .PP \fBWarning:\fP .RS 4 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\&. .RE .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIcmp\fP A \fBMDB_cmp_func\fP function .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_set_relfunc (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, \fBMDB_rel_func\fP * rel)" .PP Set a relocation function for a \fBMDB_FIXEDMAP\fP database\&. .PP \fBTodo\fP .RS 4 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 \fBMDB_FIXEDMAP\fP option\&. Currently the relocation feature is unimplemented and setting this function has no effect\&. .RE .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIrel\fP A \fBMDB_rel_func\fP function .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_set_relctx (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, void * ctx)" .PP Set a context pointer for a \fBMDB_FIXEDMAP\fP database's relocation function\&. See \fBmdb_set_relfunc\fP and \fBMDB_rel_func\fP for more details\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIctx\fP An arbitrary pointer for whatever the application needs\&. It will be passed to the callback function set by \fBmdb_set_relfunc\fP as its \fBrelctx\fP parameter whenever the callback is invoked\&. .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_get (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, \fBMDB_val\fP * key, \fBMDB_val\fP * data)" .PP 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 \fBkey\fP are returned in the structure to which \fBdata\fP refers\&. If the database supports duplicate keys (\fBMDB_DUPSORT\fP) then the first data item for the key will be returned\&. Retrieval of other items requires the use of \fBmdb_cursor_get()\fP\&. .PP \fBNote:\fP .RS 4 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\&. .PP Values returned from the database are valid only until a subsequent update operation, or the end of the transaction\&. .RE .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIkey\fP The key to search for in the database .br \fIdata\fP The data corresponding to the key .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 \fBMDB_NOTFOUND\fP - the key was not in the database\&. .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_put (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, \fBMDB_val\fP * key, \fBMDB_val\fP * data, unsigned int flags)" .PP 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 (\fBMDB_DUPSORT\fP)\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIkey\fP The key to store in the database .br \fIdata\fP The data to store .br \fIflags\fP 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\&. .PD 0 .IP "\(bu" 2 \fBMDB_NODUPDATA\fP - 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 \fBMDB_DUPSORT\fP\&. The function will return \fBMDB_KEYEXIST\fP if the key/data pair already appears in the database\&. .IP "\(bu" 2 \fBMDB_NOOVERWRITE\fP - enter the new key/data pair only if the key does not already appear in the database\&. The function will return \fBMDB_KEYEXIST\fP if the key already appears in the database, even if the database supports duplicates (\fBMDB_DUPSORT\fP)\&. The \fBdata\fP parameter will be set to point to the existing item\&. .IP "\(bu" 2 \fBMDB_RESERVE\fP - 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 \fBMDB_DUPSORT\fP\&. .IP "\(bu" 2 \fBMDB_APPEND\fP - 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 \fBMDB_KEYEXIST\fP error\&. .IP "\(bu" 2 \fBMDB_APPENDDUP\fP - as above, but for sorted dup data\&. .PP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 \fBMDB_MAP_FULL\fP - the database is full, see \fBmdb_env_set_mapsize()\fP\&. .IP "\(bu" 2 \fBMDB_TXN_FULL\fP - the transaction has too many dirty pages\&. .IP "\(bu" 2 EACCES - an attempt was made to write in a read-only transaction\&. .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_del (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, \fBMDB_val\fP * key, \fBMDB_val\fP * data)" .PP Delete items from a database\&. This function removes key/data pairs from the database\&. If the database does not support sorted duplicate data items (\fBMDB_DUPSORT\fP) 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 \fBMDB_NOTFOUND\fP if the specified key/data pair is not in the database\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIkey\fP The key to delete from the database .br \fIdata\fP The data to delete .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EACCES - an attempt was made to write in a read-only transaction\&. .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_cursor_open (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, \fBMDB_cursor\fP ** cursor)" .PP 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 \fBmdb_cursor_renew()\fP\&. It can be discarded with \fBmdb_cursor_close()\fP\&. 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 \fBmdb_cursor_renew()\fP before finally closing it\&. .PP \fBNote:\fP .RS 4 Earlier documentation said that cursors in every transaction were closed when the transaction committed or aborted\&. .RE .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIcursor\fP Address where the new \fBMDB_cursor\fP handle will be stored .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "void mdb_cursor_close (\fBMDB_cursor\fP * cursor)" .PP 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\&. .PP \fBParameters:\fP .RS 4 \fIcursor\fP A cursor handle returned by \fBmdb_cursor_open()\fP .RE .PP .SS "int mdb_cursor_renew (\fBMDB_txn\fP * txn, \fBMDB_cursor\fP * cursor)" .PP 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\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIcursor\fP A cursor handle returned by \fBmdb_cursor_open()\fP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "\fBMDB_txn\fP* mdb_cursor_txn (\fBMDB_cursor\fP * cursor)" .PP Return the cursor's transaction handle\&. .PP \fBParameters:\fP .RS 4 \fIcursor\fP A cursor handle returned by \fBmdb_cursor_open()\fP .RE .PP .SS "\fBMDB_dbi\fP mdb_cursor_dbi (\fBMDB_cursor\fP * cursor)" .PP Return the cursor's database handle\&. .PP \fBParameters:\fP .RS 4 \fIcursor\fP A cursor handle returned by \fBmdb_cursor_open()\fP .RE .PP .SS "int mdb_cursor_get (\fBMDB_cursor\fP * cursor, \fBMDB_val\fP * key, \fBMDB_val\fP * data, \fBMDB_cursor_op\fP op)" .PP 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 \fBkey\fP refers (except for the case of the \fBMDB_SET\fP option, in which the \fBkey\fP object is unchanged), and the address and length of the data are returned in the object to which \fBdata\fP refers\&. See \fBmdb_get()\fP for restrictions on using the output values\&. .PP \fBParameters:\fP .RS 4 \fIcursor\fP A cursor handle returned by \fBmdb_cursor_open()\fP .br \fIkey\fP The key for a retrieved item .br \fIdata\fP The data of a retrieved item .br \fIop\fP A cursor operation \fBMDB_cursor_op\fP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 \fBMDB_NOTFOUND\fP - no matching key found\&. .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_cursor_put (\fBMDB_cursor\fP * cursor, \fBMDB_val\fP * key, \fBMDB_val\fP * data, unsigned int flags)" .PP 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\&. .PP \fBNote:\fP .RS 4 Earlier documentation incorrectly said errors would leave the state of the cursor unchanged\&. .RE .PP \fBParameters:\fP .RS 4 \fIcursor\fP A cursor handle returned by \fBmdb_cursor_open()\fP .br \fIkey\fP The key operated on\&. .br \fIdata\fP The data operated on\&. .br \fIflags\fP Options for this operation\&. This parameter must be set to 0 or one of the values described here\&. .PD 0 .IP "\(bu" 2 \fBMDB_CURRENT\fP - replace the item at the current cursor position\&. The \fBkey\fP parameter must still be provided, and must match it\&. If using sorted duplicates (\fBMDB_DUPSORT\fP) 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\&. .IP "\(bu" 2 \fBMDB_NODUPDATA\fP - 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 \fBMDB_DUPSORT\fP\&. The function will return \fBMDB_KEYEXIST\fP if the key/data pair already appears in the database\&. .IP "\(bu" 2 \fBMDB_NOOVERWRITE\fP - enter the new key/data pair only if the key does not already appear in the database\&. The function will return \fBMDB_KEYEXIST\fP if the key already appears in the database, even if the database supports duplicates (\fBMDB_DUPSORT\fP)\&. .IP "\(bu" 2 \fBMDB_RESERVE\fP - 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 \fBMDB_DUPSORT\fP\&. .IP "\(bu" 2 \fBMDB_APPEND\fP - 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 \fBMDB_KEYEXIST\fP error\&. .IP "\(bu" 2 \fBMDB_APPENDDUP\fP - as above, but for sorted dup data\&. .IP "\(bu" 2 \fBMDB_MULTIPLE\fP - store multiple contiguous data elements in a single request\&. This flag may only be specified if the database was opened with \fBMDB_DUPFIXED\fP\&. The \fBdata\fP argument must be an array of two MDB_vals\&. The mv_size of the first \fBMDB_val\fP must be the size of a single data element\&. The mv_data of the first \fBMDB_val\fP must point to the beginning of the array of contiguous data elements\&. The mv_size of the second \fBMDB_val\fP 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 \fBMDB_val\fP is unused\&. .PP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 \fBMDB_MAP_FULL\fP - the database is full, see \fBmdb_env_set_mapsize()\fP\&. .IP "\(bu" 2 \fBMDB_TXN_FULL\fP - the transaction has too many dirty pages\&. .IP "\(bu" 2 EACCES - an attempt was made to write in a read-only transaction\&. .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_cursor_del (\fBMDB_cursor\fP * cursor, unsigned int flags)" .PP Delete current key/data pair\&. This function deletes the key/data pair to which the cursor refers\&. .PP \fBParameters:\fP .RS 4 \fIcursor\fP A cursor handle returned by \fBmdb_cursor_open()\fP .br \fIflags\fP Options for this operation\&. This parameter must be set to 0 or one of the values described here\&. .PD 0 .IP "\(bu" 2 \fBMDB_NODUPDATA\fP - delete all of the data items for the current key\&. This flag may only be specified if the database was opened with \fBMDB_DUPSORT\fP\&. .PP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EACCES - an attempt was made to write in a read-only transaction\&. .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_cursor_count (\fBMDB_cursor\fP * cursor, size_t * countp)" .PP Return count of duplicates for current key\&. This call is only valid on databases that support sorted duplicate data items \fBMDB_DUPSORT\fP\&. .PP \fBParameters:\fP .RS 4 \fIcursor\fP A cursor handle returned by \fBmdb_cursor_open()\fP .br \fIcountp\fP Address where the count will be stored .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. Some possible errors are: .PD 0 .IP "\(bu" 2 EINVAL - cursor is not initialized, or an invalid parameter was specified\&. .PP .RE .PP .SS "int mdb_cmp (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, const \fBMDB_val\fP * a, const \fBMDB_val\fP * b)" .PP 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\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIa\fP The first item to compare .br \fIb\fP The second item to compare .RE .PP \fBReturns:\fP .RS 4 < 0 if a < b, 0 if a == b, > 0 if a > b .RE .PP .SS "int mdb_dcmp (\fBMDB_txn\fP * txn, \fBMDB_dbi\fP dbi, const \fBMDB_val\fP * a, const \fBMDB_val\fP * b)" .PP 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 \fBMDB_DUPSORT\fP flag\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP A transaction handle returned by \fBmdb_txn_begin()\fP .br \fIdbi\fP A database handle returned by \fBmdb_dbi_open()\fP .br \fIa\fP The first item to compare .br \fIb\fP The second item to compare .RE .PP \fBReturns:\fP .RS 4 < 0 if a < b, 0 if a == b, > 0 if a > b .RE .PP .SS "int mdb_reader_list (\fBMDB_env\fP * env, \fBMDB_msg_func\fP * func, void * ctx)" .PP Dump the entries in the reader lock table\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIfunc\fP A \fBMDB_msg_func\fP function .br \fIctx\fP Anything the message function needs .RE .PP \fBReturns:\fP .RS 4 < 0 on failure, >= 0 on success\&. .RE .PP .SS "int mdb_reader_check (\fBMDB_env\fP * env, int * dead)" .PP Check for stale entries in the reader lock table\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP An environment handle returned by \fBmdb_env_create()\fP .br \fIdead\fP Number of stale slots that were cleared .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SH "Author" .PP Generated automatically by Doxygen for LMDB from the source code\&.