.TH "LMDB Internals" 3 "Wed May 18 2016" "LMDB" \" -*- nroff -*- .ad l .nh .SH NAME LMDB Internals \- .SS "Modules" .in +1c .ti -1c .RI "\fBID List Management\fP" .br .ti -1c .RI "\fBCompatibility Macros\fP" .br .ti -1c .RI "\fBDebug Macros\fP" .br .ti -1c .RI "\fBReader Lock Table\fP" .br .ti -1c .RI "\fBPage Flags\fP" .br .ti -1c .RI "\fBNode Flags\fP" .br .ti -1c .RI "\fBTransaction DB Flags\fP" .br .ti -1c .RI "\fBTransaction Flags\fP" .br .ti -1c .RI "\fBCursor Flags\fP" .br .in -1c .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBMDB_page\fP" .br .ti -1c .RI "struct \fBMDB_node\fP" .br .ti -1c .RI "struct \fBMDB_db\fP" .br .ti -1c .RI "struct \fBMDB_meta\fP" .br .ti -1c .RI "union \fBMDB_metabuf\fP" .br .ti -1c .RI "struct \fBMDB_dbx\fP" .br .ti -1c .RI "struct \fBMDB_txn\fP" .br .RI "\fIOpaque structure for a transaction handle\&. \fP" .ti -1c .RI "struct \fBMDB_cursor\fP" .br .RI "\fIOpaque structure for navigating through a database\&. \fP" .ti -1c .RI "struct \fBMDB_xcursor\fP" .br .ti -1c .RI "struct \fBMDB_pgstate\fP" .br .ti -1c .RI "struct \fBMDB_env\fP" .br .RI "\fIOpaque structure for a database environment\&. \fP" .ti -1c .RI "struct \fBMDB_ntxn\fP" .br .ti -1c .RI "struct \fBmdb_copy\fP" .br .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBLOCK_MUTEX\fP(rc, env, mutex) ((rc) = \fBLOCK_MUTEX0\fP(mutex))" .br .ti -1c .RI "#define \fBmdb_mutex_failed\fP(env, mutex, rc) (rc)" .br .ti -1c .RI "#define \fBMDB_DSYNC\fP O_SYNC" .br .ti -1c .RI "#define \fBMDB_FDATASYNC\fP fdatasync" .br .ti -1c .RI "#define \fBMDB_MSYNC\fP(addr, len, flags) msync(addr,len,flags)" .br .ti -1c .RI "#define \fBMS_SYNC\fP 1" .br .ti -1c .RI "#define \fBMS_ASYNC\fP 0" .br .ti -1c .RI "#define \fBMAX_PAGESIZE\fP (\fBPAGEBASE\fP ? 0x10000 : 0x8000)" .br .RI "\fIThe maximum size of a database page\&. \fP" .ti -1c .RI "#define \fBMDB_MINKEYS\fP 2" .br .ti -1c .RI "#define \fBMDB_MAGIC\fP 0xBEEFC0DE" .br .ti -1c .RI "#define \fBMDB_DATA_VERSION\fP ((\fBMDB_DEVEL\fP) ? 999 : 1)" .br .ti -1c .RI "#define \fBMDB_LOCK_VERSION\fP 1" .br .ti -1c .RI "#define \fBMDB_MAXKEYSIZE\fP ((\fBMDB_DEVEL\fP) ? 0 : 511)" .br .RI "\fIThe max size of a key we can write, or 0 for computed max\&. \fP" .ti -1c .RI "#define \fBENV_MAXKEY\fP(env) (\fBMDB_MAXKEYSIZE\fP)" .br .ti -1c .RI "#define \fBMAXDATASIZE\fP 0xffffffffUL" .br .RI "\fIThe maximum size of a data item\&. \fP" .ti -1c .RI "#define \fBDKBUF\fP" .br .ti -1c .RI "#define \fBDKEY\fP(x) 0" .br .ti -1c .RI "#define \fBP_INVALID\fP (~(\fBpgno_t\fP)0)" .br .ti -1c .RI "#define \fBF_ISSET\fP(w, f) (((w) & (f)) == (f))" .br .ti -1c .RI "#define \fBEVEN\fP(n) (((n) + 1U) & -2) /* sign-extending -2 to match n+1U */" .br .ti -1c .RI "#define \fBDEFAULT_MAPSIZE\fP 1048576" .br .ti -1c .RI "#define \fBPAGEHDRSZ\fP ((unsigned) offsetof(\fBMDB_page\fP, mp_ptrs))" .br .ti -1c .RI "#define \fBMETADATA\fP(p) ((void *)((char *)(p) + \fBPAGEHDRSZ\fP))" .br .ti -1c .RI "#define \fBPAGEBASE\fP ((\fBMDB_DEVEL\fP) ? \fBPAGEHDRSZ\fP : 0)" .br .ti -1c .RI "#define \fBNUMKEYS\fP(p) (((p)->mp_lower - (\fBPAGEHDRSZ\fP-\fBPAGEBASE\fP)) >> 1)" .br .ti -1c .RI "#define \fBSIZELEFT\fP(p) (\fBindx_t\fP)((p)->mp_upper - (p)->mp_lower)" .br .ti -1c .RI "#define \fBPAGEFILL\fP(env, p)" .br .ti -1c .RI "#define \fBFILL_THRESHOLD\fP 250" .br .ti -1c .RI "#define \fBIS_LEAF\fP(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_LEAF\fP)" .br .ti -1c .RI "#define \fBIS_LEAF2\fP(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_LEAF2\fP)" .br .ti -1c .RI "#define \fBIS_BRANCH\fP(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_BRANCH\fP)" .br .ti -1c .RI "#define \fBIS_OVERFLOW\fP(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_OVERFLOW\fP)" .br .ti -1c .RI "#define \fBIS_SUBP\fP(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_SUBP\fP)" .br .ti -1c .RI "#define \fBOVPAGES\fP(size, psize) ((\fBPAGEHDRSZ\fP-1 + (size)) / (psize) + 1)" .br .ti -1c .RI "#define \fBNEXT_LOOSE_PAGE\fP(p) (*(\fBMDB_page\fP **)((p) + 2))" .br .ti -1c .RI "#define \fBNODESIZE\fP offsetof(\fBMDB_node\fP, mn_data)" .br .ti -1c .RI "#define \fBPGNO_TOPWORD\fP ((\fBpgno_t\fP)-1 > 0xffffffffu ? 32 : 0)" .br .ti -1c .RI "#define \fBINDXSIZE\fP(k) (\fBNODESIZE\fP + ((k) == NULL ? 0 : (k)->mv_size))" .br .ti -1c .RI "#define \fBLEAFSIZE\fP(k, d) (\fBNODESIZE\fP + (k)->mv_size + (d)->mv_size)" .br .ti -1c .RI "#define \fBNODEPTR\fP(p, i) ((\fBMDB_node\fP *)((char *)(p) + (p)->mp_ptrs[i] + \fBPAGEBASE\fP))" .br .ti -1c .RI "#define \fBNODEKEY\fP(node) (void *)((node)->mn_data)" .br .ti -1c .RI "#define \fBNODEDATA\fP(node) (void *)((char *)(node)->mn_data + (node)->mn_ksize)" .br .ti -1c .RI "#define \fBNODEPGNO\fP(node)" .br .ti -1c .RI "#define \fBSETPGNO\fP(node, pgno)" .br .ti -1c .RI "#define \fBNODEDSZ\fP(node) ((node)->mn_lo | ((unsigned)(node)->mn_hi << 16))" .br .ti -1c .RI "#define \fBSETDSZ\fP(node, size)" .br .ti -1c .RI "#define \fBNODEKSZ\fP(node) ((node)->mn_ksize)" .br .ti -1c .RI "#define \fBCOPY_PGNO\fP(dst, src)" .br .ti -1c .RI "#define \fBLEAF2KEY\fP(p, i, ks) ((char *)(p) + \fBPAGEHDRSZ\fP + ((i)*(ks)))" .br .ti -1c .RI "#define \fBMDB_GET_KEY\fP(node, keyptr)" .br .ti -1c .RI "#define \fBMDB_GET_KEY2\fP(node, key) { key\&.mv_size = \fBNODEKSZ\fP(node); key\&.mv_data = \fBNODEKEY\fP(node); }" .br .ti -1c .RI "#define \fBMDB_VALID\fP 0x8000" .br .ti -1c .RI "#define \fBPERSISTENT_FLAGS\fP (0xffff & ~(MDB_VALID))" .br .ti -1c .RI "#define \fBVALID_FLAGS\fP" .br .ti -1c .RI "#define \fBFREE_DBI\fP 0" .br .ti -1c .RI "#define \fBMAIN_DBI\fP 1" .br .ti -1c .RI "#define \fBCORE_DBS\fP 2" .br .ti -1c .RI "#define \fBNUM_METAS\fP 2" .br .ti -1c .RI "#define \fBCURSOR_STACK\fP 32" .br .ti -1c .RI "#define \fBMDB_COMMIT_PAGES\fP 64" .br .ti -1c .RI "#define \fBMAX_WRITE\fP (0x40000000U >> (sizeof(ssize_t) == 4))" .br .ti -1c .RI "#define \fBTXN_DBI_EXIST\fP(txn, dbi, validity) ((txn) && (dbi)<(txn)->mt_numdbs && ((txn)->mt_dbflags[dbi] & (validity)))" .br .ti -1c .RI "#define \fBTXN_DBI_CHANGED\fP(txn, dbi) ((txn)->mt_dbiseqs[dbi] != (txn)->mt_env->me_dbiseqs[dbi])" .br .ti -1c .RI "#define \fBMDB_END_NAMES\fP" .br .ti -1c .RI "#define \fBMDB_END_OPMASK\fP 0x0F" .br .ti -1c .RI "#define \fBMDB_END_UPDATE\fP 0x10" .br .ti -1c .RI "#define \fBMDB_END_FREE\fP 0x20" .br .ti -1c .RI "#define \fBMDB_END_SLOT\fP \fBMDB_NOTLS\fP" .br .ti -1c .RI "#define \fBMDB_PS_MODIFY\fP 1" .br .ti -1c .RI "#define \fBMDB_PS_ROOTONLY\fP 2" .br .ti -1c .RI "#define \fBMDB_PS_FIRST\fP 4" .br .ti -1c .RI "#define \fBMDB_PS_LAST\fP 8" .br .ti -1c .RI "#define \fBMDB_SPLIT_REPLACE\fP \fBMDB_APPENDDUP\fP" .br .ti -1c .RI "#define \fBmdb_env_close0\fP(env, excl) mdb_env_close1(env)" .br .ti -1c .RI "#define \fBmdb_cmp_clong\fP \fBmdb_cmp_cint\fP" .br .ti -1c .RI "#define \fBmdb_cassert\fP(mc, expr) mdb_assert0((mc)->mc_txn->mt_env, expr, #expr)" .br .ti -1c .RI "#define \fBmdb_tassert\fP(txn, expr) mdb_assert0((txn)->mt_env, expr, #expr)" .br .ti -1c .RI "#define \fBmdb_eassert\fP(env, expr) mdb_assert0(env, expr, #expr)" .br .ti -1c .RI "#define \fBmdb_assert0\fP(env, expr, expr_txt)" .br .ti -1c .RI "#define \fBLOCKNAME\fP '/lock\&.mdb'" .br .ti -1c .RI "#define \fBDATANAME\fP '/data\&.mdb'" .br .ti -1c .RI "#define \fBLOCKSUFF\fP '-lock'" .br .ti -1c .RI "#define \fBCHANGEABLE\fP (\fBMDB_NOSYNC\fP|\fBMDB_NOMETASYNC\fP|\fBMDB_MAPASYNC\fP|\fBMDB_NOMEMINIT\fP)" .br .ti -1c .RI "#define \fBCHANGELESS\fP" .br .ti -1c .RI "#define \fBMDB_NOSPILL\fP 0x8000" .br .ti -1c .RI "#define \fBWITH_CURSOR_TRACKING\fP(mn, act)" .br .ti -1c .RI "#define \fBMDB_WBUF\fP (1024*1024)" .br .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef \fBMDB_ID\fP \fBpgno_t\fP" .br .ti -1c .RI "typedef \fBMDB_ID\fP \fBtxnid_t\fP" .br .ti -1c .RI "typedef uint16_t \fBindx_t\fP" .br .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum { \fBMDB_END_COMMITTED\fP, \fBMDB_END_EMPTY_COMMIT\fP, \fBMDB_END_ABORT\fP, \fBMDB_END_RESET\fP, \fBMDB_END_RESET_TMP\fP, \fBMDB_END_FAIL_BEGIN\fP, \fBMDB_END_FAIL_BEGINCHILD\fP }" .br .ti -1c .RI "enum \fBPidlock_op\fP { \fBPidset\fP = F_SETLK, \fBPidcheck\fP = F_GETLK }" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "static int \fBmdb_page_alloc\fP (\fBMDB_cursor\fP *mc, int num, \fBMDB_page\fP **mp)" .br .ti -1c .RI "static int \fBmdb_page_new\fP (\fBMDB_cursor\fP *mc, uint32_t flags, int num, \fBMDB_page\fP **mp)" .br .ti -1c .RI "static int \fBmdb_page_touch\fP (\fBMDB_cursor\fP *mc)" .br .ti -1c .RI "static void \fBmdb_txn_end\fP (\fBMDB_txn\fP *txn, unsigned mode)" .br .ti -1c .RI "static int \fBmdb_page_get\fP (\fBMDB_txn\fP *txn, \fBpgno_t\fP pgno, \fBMDB_page\fP **mp, int *lvl)" .br .ti -1c .RI "static int \fBmdb_page_search_root\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, int modify)" .br .ti -1c .RI "static int \fBmdb_page_search\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, int flags)" .br .ti -1c .RI "static int \fBmdb_page_merge\fP (\fBMDB_cursor\fP *csrc, \fBMDB_cursor\fP *cdst)" .br .ti -1c .RI "static int \fBmdb_page_split\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *newkey, \fBMDB_val\fP *newdata, \fBpgno_t\fP newpgno, unsigned int nflags)" .br .ti -1c .RI "static int \fBmdb_env_read_header\fP (\fBMDB_env\fP *env, \fBMDB_meta\fP *meta)" .br .ti -1c .RI "static \fBMDB_meta\fP * \fBmdb_env_pick_meta\fP (const \fBMDB_env\fP *env)" .br .ti -1c .RI "static int \fBmdb_env_write_meta\fP (\fBMDB_txn\fP *txn)" .br .ti -1c .RI "static void \fBmdb_env_close0\fP (\fBMDB_env\fP *env, int excl)" .br .ti -1c .RI "static \fBMDB_node\fP * \fBmdb_node_search\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, int *exactp)" .br .ti -1c .RI "static int \fBmdb_node_add\fP (\fBMDB_cursor\fP *mc, \fBindx_t\fP indx, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBpgno_t\fP pgno, unsigned int flags)" .br .ti -1c .RI "static void \fBmdb_node_del\fP (\fBMDB_cursor\fP *mc, int ksize)" .br .ti -1c .RI "static void \fBmdb_node_shrink\fP (\fBMDB_page\fP *mp, \fBindx_t\fP indx)" .br .ti -1c .RI "static int \fBmdb_node_move\fP (\fBMDB_cursor\fP *csrc, \fBMDB_cursor\fP *cdst, int fromleft)" .br .ti -1c .RI "static int \fBmdb_node_read\fP (\fBMDB_txn\fP *txn, \fBMDB_node\fP *leaf, \fBMDB_val\fP *data)" .br .ti -1c .RI "static size_t \fBmdb_leaf_size\fP (\fBMDB_env\fP *env, \fBMDB_val\fP *key, \fBMDB_val\fP *data)" .br .ti -1c .RI "static size_t \fBmdb_branch_size\fP (\fBMDB_env\fP *env, \fBMDB_val\fP *key)" .br .ti -1c .RI "static int \fBmdb_rebalance\fP (\fBMDB_cursor\fP *mc)" .br .ti -1c .RI "static int \fBmdb_update_key\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key)" .br .ti -1c .RI "static void \fBmdb_cursor_pop\fP (\fBMDB_cursor\fP *mc)" .br .ti -1c .RI "static int \fBmdb_cursor_push\fP (\fBMDB_cursor\fP *mc, \fBMDB_page\fP *mp)" .br .ti -1c .RI "static int \fBmdb_cursor_del0\fP (\fBMDB_cursor\fP *mc)" .br .ti -1c .RI "static int \fBmdb_del0\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_val\fP *key, \fBMDB_val\fP *data, unsigned flags)" .br .ti -1c .RI "static int \fBmdb_cursor_sibling\fP (\fBMDB_cursor\fP *mc, int move_right)" .br .ti -1c .RI "static int \fBmdb_cursor_next\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fP op)" .br .ti -1c .RI "static int \fBmdb_cursor_prev\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fP op)" .br .ti -1c .RI "static int \fBmdb_cursor_set\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fP op, int *exactp)" .br .ti -1c .RI "static int \fBmdb_cursor_first\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data)" .br .ti -1c .RI "static int \fBmdb_cursor_last\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data)" .br .ti -1c .RI "static void \fBmdb_cursor_init\fP (\fBMDB_cursor\fP *mc, \fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_xcursor\fP *mx)" .br .ti -1c .RI "static void \fBmdb_xcursor_init0\fP (\fBMDB_cursor\fP *mc)" .br .ti -1c .RI "static void \fBmdb_xcursor_init1\fP (\fBMDB_cursor\fP *mc, \fBMDB_node\fP *node)" .br .ti -1c .RI "static void \fBmdb_xcursor_init2\fP (\fBMDB_cursor\fP *mc, \fBMDB_xcursor\fP *src_mx, int force)" .br .ti -1c .RI "static int \fBmdb_drop0\fP (\fBMDB_cursor\fP *mc, int subs)" .br .ti -1c .RI "static void \fBmdb_default_cmp\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi)" .br .ti -1c .RI "static int \fBmdb_reader_check0\fP (\fBMDB_env\fP *env, int rlocked, int *dead)" .br .ti -1c .RI "char *\fBESECT\fP \fBmdb_version\fP (int *major, int *minor, int *patch)" .br .RI "\fIReturn the LMDB library version information\&. \fP" .ti -1c .RI "char * \fBmdb_strerror\fP (int err)" .br .RI "\fIReturn a string describing a given error code\&. \fP" .ti -1c .RI "static void \fBESECT\fP \fBmdb_assert_fail\fP (\fBMDB_env\fP *env, const char *expr_txt, const char *func, const char *file, int line)" .br .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 "\fICompare two data items according to a particular database\&. \fP" .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 "\fICompare two data items according to a particular database\&. \fP" .ti -1c .RI "static \fBMDB_page\fP * \fBmdb_page_malloc\fP (\fBMDB_txn\fP *txn, unsigned num)" .br .ti -1c .RI "static void \fBmdb_page_free\fP (\fBMDB_env\fP *env, \fBMDB_page\fP *mp)" .br .ti -1c .RI "static void \fBmdb_dpage_free\fP (\fBMDB_env\fP *env, \fBMDB_page\fP *dp)" .br .ti -1c .RI "static void \fBmdb_dlist_free\fP (\fBMDB_txn\fP *txn)" .br .ti -1c .RI "static int \fBmdb_page_loose\fP (\fBMDB_cursor\fP *mc, \fBMDB_page\fP *mp)" .br .ti -1c .RI "static int \fBmdb_pages_xkeep\fP (\fBMDB_cursor\fP *mc, unsigned pflags, int all)" .br .ti -1c .RI "static int \fBmdb_page_flush\fP (\fBMDB_txn\fP *txn, int keep)" .br .ti -1c .RI "static int \fBmdb_page_spill\fP (\fBMDB_cursor\fP *m0, \fBMDB_val\fP *key, \fBMDB_val\fP *data)" .br .ti -1c .RI "static \fBtxnid_t\fP \fBmdb_find_oldest\fP (\fBMDB_txn\fP *txn)" .br .ti -1c .RI "static void \fBmdb_page_dirty\fP (\fBMDB_txn\fP *txn, \fBMDB_page\fP *mp)" .br .ti -1c .RI "static void \fBmdb_page_copy\fP (\fBMDB_page\fP *dst, \fBMDB_page\fP *src, unsigned int psize)" .br .ti -1c .RI "static int \fBmdb_page_unspill\fP (\fBMDB_txn\fP *txn, \fBMDB_page\fP *mp, \fBMDB_page\fP **ret)" .br .ti -1c .RI "int \fBmdb_env_sync\fP (\fBMDB_env\fP *env, int force)" .br .RI "\fIFlush the data buffers to disk\&. \fP" .ti -1c .RI "static int \fBmdb_cursor_shadow\fP (\fBMDB_txn\fP *src, \fBMDB_txn\fP *dst)" .br .ti -1c .RI "static void \fBmdb_cursors_close\fP (\fBMDB_txn\fP *txn, unsigned merge)" .br .ti -1c .RI "static int \fBmdb_reader_pid\fP (\fBMDB_env\fP *env, enum Pidlock_op op, MDB_PID_T pid)" .br .ti -1c .RI "static int \fBmdb_txn_renew0\fP (\fBMDB_txn\fP *txn)" .br .ti -1c .RI "int \fBmdb_txn_renew\fP (\fBMDB_txn\fP *txn)" .br .RI "\fIRenew a read-only transaction\&. \fP" .ti -1c .RI "int \fBmdb_txn_begin\fP (\fBMDB_env\fP *env, \fBMDB_txn\fP *parent, unsigned int flags, \fBMDB_txn\fP **ret)" .br .RI "\fICreate a transaction for use with the environment\&. \fP" .ti -1c .RI "\fBMDB_env\fP * \fBmdb_txn_env\fP (\fBMDB_txn\fP *txn)" .br .RI "\fIReturns the transaction's \fBMDB_env\fP\&. \fP" .ti -1c .RI "size_t \fBmdb_txn_id\fP (\fBMDB_txn\fP *txn)" .br .RI "\fIReturn the transaction's ID\&. \fP" .ti -1c .RI "static void \fBmdb_dbis_update\fP (\fBMDB_txn\fP *txn, int keep)" .br .ti -1c .RI "void \fBmdb_txn_reset\fP (\fBMDB_txn\fP *txn)" .br .RI "\fIReset a read-only transaction\&. \fP" .ti -1c .RI "void \fBmdb_txn_abort\fP (\fBMDB_txn\fP *txn)" .br .RI "\fIAbandon all the operations of the transaction instead of saving them\&. \fP" .ti -1c .RI "static int \fBmdb_freelist_save\fP (\fBMDB_txn\fP *txn)" .br .ti -1c .RI "int \fBmdb_txn_commit\fP (\fBMDB_txn\fP *txn)" .br .RI "\fICommit all the operations of a transaction into the database\&. \fP" .ti -1c .RI "static void \fBESECT\fP \fBmdb_env_init_meta0\fP (\fBMDB_env\fP *env, \fBMDB_meta\fP *meta)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_init_meta\fP (\fBMDB_env\fP *env, \fBMDB_meta\fP *meta)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_env_create\fP (\fBMDB_env\fP **env)" .br .RI "\fICreate an LMDB environment handle\&. \fP" .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_map\fP (\fBMDB_env\fP *env, void *addr)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_env_set_mapsize\fP (\fBMDB_env\fP *env, size_t size)" .br .RI "\fISet the size of the memory map to use for this environment\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_set_maxdbs\fP (\fBMDB_env\fP *env, \fBMDB_dbi\fP dbs)" .br .RI "\fISet the maximum number of named databases for the environment\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_set_maxreaders\fP (\fBMDB_env\fP *env, unsigned int readers)" .br .RI "\fISet the maximum number of threads/reader slots for the environment\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_get_maxreaders\fP (\fBMDB_env\fP *env, unsigned int *readers)" .br .RI "\fIGet the maximum number of threads/reader slots for the environment\&. \fP" .ti -1c .RI "static int \fBESECT\fP \fBmdb_fsize\fP (\fBHANDLE\fP fd, size_t *size)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_open2\fP (\fBMDB_env\fP *env)" .br .ti -1c .RI "static void \fBmdb_env_reader_dest\fP (void *ptr)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_share_locks\fP (\fBMDB_env\fP *env, int *excl)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_excl_lock\fP (\fBMDB_env\fP *env, int *excl)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_setup_locks\fP (\fBMDB_env\fP *env, char *lpath, int mode, int *excl)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_env_open\fP (\fBMDB_env\fP *env, const char *path, unsigned int flags, \fBmdb_mode_t\fP mode)" .br .RI "\fIOpen an environment handle\&. \fP" .ti -1c .RI "void \fBESECT\fP \fBmdb_env_close\fP (\fBMDB_env\fP *env)" .br .RI "\fIClose the environment and release the memory map\&. \fP" .ti -1c .RI "static int \fBmdb_cmp_long\fP (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)" .br .ti -1c .RI "static int \fBmdb_cmp_int\fP (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)" .br .ti -1c .RI "static int \fBmdb_cmp_cint\fP (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)" .br .ti -1c .RI "static int \fBmdb_cmp_memn\fP (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)" .br .ti -1c .RI "static int \fBmdb_cmp_memnr\fP (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)" .br .ti -1c .RI "static int \fBmdb_page_search_lowest\fP (\fBMDB_cursor\fP *mc)" .br .ti -1c .RI "static int \fBmdb_ovpage_free\fP (\fBMDB_cursor\fP *mc, \fBMDB_page\fP *mp)" .br .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 "\fIGet items from a database\&. \fP" .ti -1c .RI "int \fBmdb_cursor_get\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fP op)" .br .RI "\fIRetrieve by cursor\&. \fP" .ti -1c .RI "static int \fBmdb_cursor_touch\fP (\fBMDB_cursor\fP *mc)" .br .ti -1c .RI "int \fBmdb_cursor_put\fP (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data, unsigned int flags)" .br .RI "\fIStore by cursor\&. \fP" .ti -1c .RI "int \fBmdb_cursor_del\fP (\fBMDB_cursor\fP *mc, unsigned int flags)" .br .RI "\fIDelete current key/data pair\&. \fP" .ti -1c .RI "int \fBmdb_cursor_open\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_cursor\fP **ret)" .br .RI "\fICreate a cursor handle\&. \fP" .ti -1c .RI "int \fBmdb_cursor_renew\fP (\fBMDB_txn\fP *txn, \fBMDB_cursor\fP *mc)" .br .RI "\fIRenew a cursor handle\&. \fP" .ti -1c .RI "int \fBmdb_cursor_count\fP (\fBMDB_cursor\fP *mc, size_t *countp)" .br .RI "\fIReturn count of duplicates for current key\&. \fP" .ti -1c .RI "void \fBmdb_cursor_close\fP (\fBMDB_cursor\fP *mc)" .br .RI "\fIClose a cursor handle\&. \fP" .ti -1c .RI "\fBMDB_txn\fP * \fBmdb_cursor_txn\fP (\fBMDB_cursor\fP *mc)" .br .RI "\fIReturn the cursor's transaction handle\&. \fP" .ti -1c .RI "\fBMDB_dbi\fP \fBmdb_cursor_dbi\fP (\fBMDB_cursor\fP *mc)" .br .RI "\fIReturn the cursor's database handle\&. \fP" .ti -1c .RI "static void \fBmdb_cursor_copy\fP (const \fBMDB_cursor\fP *csrc, \fBMDB_cursor\fP *cdst)" .br .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 "\fIDelete items from a database\&. \fP" .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 "\fIStore items into a database\&. \fP" .ti -1c .RI "static THREAD_RET \fBESECT\fP CALL_CONV \fBmdb_env_copythr\fP (void *arg)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_cthr_toggle\fP (\fBmdb_copy\fP *my, int st)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_cwalk\fP (\fBmdb_copy\fP *my, \fBpgno_t\fP *pg, int flags)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_copyfd1\fP (\fBMDB_env\fP *env, \fBHANDLE\fP fd)" .br .ti -1c .RI "static int \fBESECT\fP \fBmdb_env_copyfd0\fP (\fBMDB_env\fP *env, \fBHANDLE\fP fd)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_env_copyfd2\fP (\fBMDB_env\fP *env, \fBHANDLE\fP fd, unsigned int flags)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_env_copyfd\fP (\fBMDB_env\fP *env, \fBHANDLE\fP fd)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_env_copy2\fP (\fBMDB_env\fP *env, const char *path, unsigned int flags)" .br .RI "\fICopy an LMDB environment to the specified path, with options\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_copy\fP (\fBMDB_env\fP *env, const char *path)" .br .RI "\fICopy an LMDB environment to the specified path\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_set_flags\fP (\fBMDB_env\fP *env, unsigned int flag, int onoff)" .br .RI "\fISet environment flags\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_get_flags\fP (\fBMDB_env\fP *env, unsigned int *arg)" .br .RI "\fIGet environment flags\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_set_userctx\fP (\fBMDB_env\fP *env, void *ctx)" .br .RI "\fISet application information associated with the \fBMDB_env\fP\&. \fP" .ti -1c .RI "void *\fBESECT\fP \fBmdb_env_get_userctx\fP (\fBMDB_env\fP *env)" .br .RI "\fIGet the application information associated with the \fBMDB_env\fP\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_set_assert\fP (\fBMDB_env\fP *env, \fBMDB_assert_func\fP *func)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_env_get_path\fP (\fBMDB_env\fP *env, const char **arg)" .br .RI "\fIReturn the path that was used in \fBmdb_env_open()\fP\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_get_fd\fP (\fBMDB_env\fP *env, \fBmdb_filehandle_t\fP *arg)" .br .RI "\fIReturn the filedescriptor for the given environment\&. \fP" .ti -1c .RI "static int \fBESECT\fP \fBmdb_stat0\fP (\fBMDB_env\fP *env, \fBMDB_db\fP *db, \fBMDB_stat\fP *arg)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_env_stat\fP (\fBMDB_env\fP *env, \fBMDB_stat\fP *arg)" .br .RI "\fIReturn statistics about the LMDB environment\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_info\fP (\fBMDB_env\fP *env, \fBMDB_envinfo\fP *arg)" .br .RI "\fIReturn information about the LMDB environment\&. \fP" .ti -1c .RI "int \fBmdb_dbi_open\fP (\fBMDB_txn\fP *txn, const char *name, unsigned int flags, \fBMDB_dbi\fP *dbi)" .br .RI "\fIOpen a database in the environment\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_stat\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_stat\fP *arg)" .br .RI "\fIRetrieve statistics for a database\&. \fP" .ti -1c .RI "void \fBmdb_dbi_close\fP (\fBMDB_env\fP *env, \fBMDB_dbi\fP dbi)" .br .RI "\fIClose a database handle\&. Normally unnecessary\&. Use with care: \fP" .ti -1c .RI "int \fBmdb_dbi_flags\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, unsigned int *flags)" .br .RI "\fIRetrieve the DB flags for a database handle\&. \fP" .ti -1c .RI "int \fBmdb_drop\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, int del)" .br .RI "\fIEmpty or delete+close a database\&. \fP" .ti -1c .RI "int \fBmdb_set_compare\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_cmp_func\fP *cmp)" .br .RI "\fISet a custom key comparison function for a database\&. \fP" .ti -1c .RI "int \fBmdb_set_dupsort\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_cmp_func\fP *cmp)" .br .RI "\fISet a custom data comparison function for a \fBMDB_DUPSORT\fP database\&. \fP" .ti -1c .RI "int \fBmdb_set_relfunc\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, \fBMDB_rel_func\fP *rel)" .br .RI "\fISet a relocation function for a \fBMDB_FIXEDMAP\fP database\&. \fP" .ti -1c .RI "int \fBmdb_set_relctx\fP (\fBMDB_txn\fP *txn, \fBMDB_dbi\fP dbi, void *ctx)" .br .RI "\fISet a context pointer for a \fBMDB_FIXEDMAP\fP database's relocation function\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_env_get_maxkeysize\fP (\fBMDB_env\fP *env)" .br .RI "\fIGet the maximum size of keys and \fBMDB_DUPSORT\fP data we can write\&. \fP" .ti -1c .RI "int \fBESECT\fP \fBmdb_reader_list\fP (\fBMDB_env\fP *env, \fBMDB_msg_func\fP *func, void *ctx)" .br .RI "\fIDump the entries in the reader lock table\&. \fP" .ti -1c .RI "static int \fBESECT\fP \fBmdb_pid_insert\fP (MDB_PID_T *ids, MDB_PID_T pid)" .br .ti -1c .RI "int \fBESECT\fP \fBmdb_reader_check\fP (\fBMDB_env\fP *env, int *dead)" .br .RI "\fICheck for stale entries in the reader lock table\&. \fP" .in -1c .SS "Variables" .in +1c .ti -1c .RI "static char *const \fBmdb_errstr\fP []" .br .in -1c .SH "Detailed Description" .PP .SH "Data Structure Documentation" .PP .SH "struct MDB_page" .PP Common header for all page types\&. Overflow records occupy a number of contiguous pages with no headers on any page after the first\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "union {" .br .ti -1c .RI " \fBpgno_t\fP \fBp_pgno\fP" .br .ti -1c .RI " struct \fBMDB_page\fP * \fBp_next\fP" .br .ti -1c .RI "} \fBmp_p\fP" .br .ti -1c .RI "uint16_t \fBmp_pad\fP" .br .ti -1c .RI "uint16_t \fBmp_flags\fP" .br .ti -1c .RI "union {" .br .ti -1c .RI " struct {" .br .ti -1c .RI " \fBindx_t\fP \fBpb_lower\fP" .br .ti -1c .RI " \fBindx_t\fP \fBpb_upper\fP" .br .ti -1c .RI " } \fBpb\fP" .br .ti -1c .RI " uint32_t \fBpb_pages\fP" .br .ti -1c .RI "} \fBmp_pb\fP" .br .ti -1c .RI "\fBindx_t\fP \fBmp_ptrs\fP [1]" .br .in -1c .SH "Field Documentation" .PP .SS "\fBpgno_t\fP MDB_page::p_pgno" page number .SS "struct \fBMDB_page\fP* MDB_page::p_next" for in-memory list of freed pages .SS "uint16_t MDB_page::mp_flags" \fBPage Flags\fP .SS "\fBindx_t\fP MDB_page::pb_lower" lower bound of free space .SS "\fBindx_t\fP MDB_page::pb_upper" upper bound of free space .SS "uint32_t MDB_page::pb_pages" number of overflow pages .SS "\fBindx_t\fP MDB_page::mp_ptrs[1]" dynamic size .SH "struct MDB_node" .PP Header for a single key/data pair within a page\&. Used in pages of type \fBP_BRANCH\fP and \fBP_LEAF\fP without \fBP_LEAF2\fP\&. We guarantee 2-byte alignment for '\fBMDB_node\fP's\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "unsigned short \fBmn_lo\fP" .br .ti -1c .RI "unsigned short \fBmn_hi\fP" .br .ti -1c .RI "unsigned short \fBmn_flags\fP" .br .ti -1c .RI "unsigned short \fBmn_ksize\fP" .br .ti -1c .RI "char \fBmn_data\fP [1]" .br .in -1c .SH "Field Documentation" .PP .SS "unsigned short MDB_node::mn_lo" lo and hi are used for data size on leaf nodes and for child pgno on branch nodes\&. On 64 bit platforms, flags is also used for pgno\&. (Branch nodes have no flags)\&. They are in host byte order in case that lets some accesses be optimized into a 32-bit word access\&. .SS "unsigned short MDB_node::mn_hi" part of data size or pgno .SS "unsigned short MDB_node::mn_flags" \fBNode Flags\fP .SS "unsigned short MDB_node::mn_ksize" key size .SS "char MDB_node::mn_data[1]" key and data are appended here .SH "struct MDB_db" .PP Information about a single database in the environment\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "uint32_t \fBmd_pad\fP" .br .ti -1c .RI "uint16_t \fBmd_flags\fP" .br .ti -1c .RI "uint16_t \fBmd_depth\fP" .br .ti -1c .RI "\fBpgno_t\fP \fBmd_branch_pages\fP" .br .ti -1c .RI "\fBpgno_t\fP \fBmd_leaf_pages\fP" .br .ti -1c .RI "\fBpgno_t\fP \fBmd_overflow_pages\fP" .br .ti -1c .RI "size_t \fBmd_entries\fP" .br .ti -1c .RI "\fBpgno_t\fP \fBmd_root\fP" .br .in -1c .SH "Field Documentation" .PP .SS "uint32_t MDB_db::md_pad" also ksize for LEAF2 pages .SS "uint16_t MDB_db::md_flags" \fBDatabase Flags\fP .SS "uint16_t MDB_db::md_depth" depth of this tree .SS "\fBpgno_t\fP MDB_db::md_branch_pages" number of internal pages .SS "\fBpgno_t\fP MDB_db::md_leaf_pages" number of leaf pages .SS "\fBpgno_t\fP MDB_db::md_overflow_pages" number of overflow pages .SS "size_t MDB_db::md_entries" number of data items .SS "\fBpgno_t\fP MDB_db::md_root" the root page of this tree .SH "struct MDB_meta" .PP Meta page content\&. A meta page is the start point for accessing a database snapshot\&. Pages 0-1 are meta pages\&. Transaction N writes meta page #(N % 2)\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "uint32_t \fBmm_magic\fP" .br .ti -1c .RI "uint32_t \fBmm_version\fP" .br .ti -1c .RI "void * \fBmm_address\fP" .br .ti -1c .RI "size_t \fBmm_mapsize\fP" .br .ti -1c .RI "\fBMDB_db\fP \fBmm_dbs\fP [\fBCORE_DBS\fP]" .br .ti -1c .RI "\fBpgno_t\fP \fBmm_last_pg\fP" .br .ti -1c .RI "volatile \fBtxnid_t\fP \fBmm_txnid\fP" .br .in -1c .SH "Field Documentation" .PP .SS "uint32_t MDB_meta::mm_magic" Stamp identifying this as an LMDB file\&. It must be set to \fBMDB_MAGIC\fP\&. .SS "uint32_t MDB_meta::mm_version" Version number of this file\&. Must be set to \fBMDB_DATA_VERSION\fP\&. .SS "void* MDB_meta::mm_address" address for fixed mapping .SS "size_t MDB_meta::mm_mapsize" size of mmap region .SS "\fBMDB_db\fP MDB_meta::mm_dbs[\fBCORE_DBS\fP]" first is free space, 2nd is main db .SS "\fBpgno_t\fP MDB_meta::mm_last_pg" last used page in file .SS "volatile \fBtxnid_t\fP MDB_meta::mm_txnid" txnid that committed this page .SH "union MDB_metabuf" .PP Buffer for a stack-allocated meta page\&. The members define size and alignment, and silence type aliasing warnings\&. They are not used directly; that could mean incorrectly using several union members in parallel\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "\fBMDB_page\fP \fBmb_page\fP" .br .ti -1c .RI "struct {" .br .ti -1c .RI " char \fBmm_pad\fP [\fBPAGEHDRSZ\fP]" .br .ti -1c .RI " \fBMDB_meta\fP \fBmm_meta\fP" .br .ti -1c .RI "} \fBmb_metabuf\fP" .br .in -1c .SH "struct MDB_dbx" .PP Auxiliary DB info\&. The information here is mostly static/read-only\&. There is only a single copy of this record in the environment\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "\fBMDB_val\fP \fBmd_name\fP" .br .ti -1c .RI "\fBMDB_cmp_func\fP * \fBmd_cmp\fP" .br .ti -1c .RI "\fBMDB_cmp_func\fP * \fBmd_dcmp\fP" .br .ti -1c .RI "\fBMDB_rel_func\fP * \fBmd_rel\fP" .br .ti -1c .RI "void * \fBmd_relctx\fP" .br .in -1c .SH "Field Documentation" .PP .SS "\fBMDB_val\fP MDB_dbx::md_name" name of the database .SS "\fBMDB_cmp_func\fP* MDB_dbx::md_cmp" function for comparing keys .SS "\fBMDB_cmp_func\fP* MDB_dbx::md_dcmp" function for comparing data items .SS "\fBMDB_rel_func\fP* MDB_dbx::md_rel" user relocate function .SS "void* MDB_dbx::md_relctx" user-provided context for md_rel .SH "struct MDB_txn" .PP Opaque structure for a transaction handle\&. A database transaction\&. Every operation requires a transaction handle\&. .PP All database operations require a transaction handle\&. Transactions may be read-only or read-write\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "\fBMDB_txn\fP * \fBmt_parent\fP" .br .ti -1c .RI "\fBMDB_txn\fP * \fBmt_child\fP" .br .ti -1c .RI "\fBpgno_t\fP \fBmt_next_pgno\fP" .br .ti -1c .RI "\fBtxnid_t\fP \fBmt_txnid\fP" .br .ti -1c .RI "\fBMDB_env\fP * \fBmt_env\fP" .br .ti -1c .RI "\fBMDB_IDL\fP \fBmt_free_pgs\fP" .br .ti -1c .RI "\fBMDB_page\fP * \fBmt_loose_pgs\fP" .br .ti -1c .RI "int \fBmt_loose_count\fP" .br .ti -1c .RI "\fBMDB_IDL\fP \fBmt_spill_pgs\fP" .br .ti -1c .RI "union {" .br .ti -1c .RI " \fBMDB_ID2L\fP \fBdirty_list\fP" .br .ti -1c .RI " \fBMDB_reader\fP * \fBreader\fP" .br .ti -1c .RI "} \fBmt_u\fP" .br .ti -1c .RI "\fBMDB_dbx\fP * \fBmt_dbxs\fP" .br .ti -1c .RI "\fBMDB_db\fP * \fBmt_dbs\fP" .br .ti -1c .RI "unsigned int * \fBmt_dbiseqs\fP" .br .ti -1c .RI "\fBMDB_cursor\fP ** \fBmt_cursors\fP" .br .ti -1c .RI "unsigned char * \fBmt_dbflags\fP" .br .ti -1c .RI "\fBMDB_dbi\fP \fBmt_numdbs\fP" .br .ti -1c .RI "unsigned int \fBmt_flags\fP" .br .ti -1c .RI "unsigned int \fBmt_dirty_room\fP" .br .in -1c .SH "Field Documentation" .PP .SS "\fBMDB_txn\fP* MDB_txn::mt_parent" parent of a nested txn .SS "\fBMDB_txn\fP* MDB_txn::mt_child" Nested txn under this txn, set together with flag \fBMDB_TXN_HAS_CHILD\fP .SS "\fBpgno_t\fP MDB_txn::mt_next_pgno" next unallocated page .SS "\fBtxnid_t\fP MDB_txn::mt_txnid" The ID of this transaction\&. IDs are integers incrementing from 1\&. Only committed write transactions increment the ID\&. If a transaction aborts, the ID may be re-used by the next writer\&. .SS "\fBMDB_env\fP* MDB_txn::mt_env" the DB environment .SS "\fBMDB_IDL\fP MDB_txn::mt_free_pgs" The list of pages that became unused during this transaction\&. .SS "\fBMDB_page\fP* MDB_txn::mt_loose_pgs" The list of loose pages that became unused and may be reused in this transaction, linked through \fBNEXT_LOOSE_PAGE(page)\fP\&. .SS "\fBMDB_IDL\fP MDB_txn::mt_spill_pgs" The sorted list of dirty pages we temporarily wrote to disk because the dirty list was full\&. page numbers in here are shifted left by 1, deleted slots have the LSB set\&. .SS "\fBMDB_ID2L\fP MDB_txn::dirty_list" For write txns: Modified pages\&. Sorted when not MDB_WRITEMAP\&. .SS "\fBMDB_reader\fP* MDB_txn::reader" For read txns: This thread/txn's reader table slot, or NULL\&. .SS "\fBMDB_dbx\fP* MDB_txn::mt_dbxs" Array of records for each DB known in the environment\&. .SS "\fBMDB_db\fP* MDB_txn::mt_dbs" Array of \fBMDB_db\fP records for each known DB .SS "unsigned int* MDB_txn::mt_dbiseqs" Array of sequence numbers for each DB handle .SS "\fBMDB_cursor\fP** MDB_txn::mt_cursors" In write txns, array of cursors for each DB .SS "unsigned char* MDB_txn::mt_dbflags" Array of flags for each DB .SS "\fBMDB_dbi\fP MDB_txn::mt_numdbs" Number of DB records in use, or 0 when the txn is finished\&. This number only ever increments until the txn finishes; we don't decrement it when individual DB handles are closed\&. .SS "unsigned int MDB_txn::mt_flags" \fBTransaction Flags\fP .SS "unsigned int MDB_txn::mt_dirty_room" \fBdirty_list\fP room: Array size - #dirty pages visible to this txn\&. Includes ancestor txns' dirty pages not hidden by other txns' dirty/spilled pages\&. Thus commit(nested txn) has room to merge dirty_list into mt_parent after freeing hidden mt_parent pages\&. .SH "struct MDB_cursor" .PP Opaque structure for navigating through a database\&. Cursors are used for all DB operations\&. A cursor holds a path of (page pointer, key index) from the DB root to a position in the DB, plus other state\&. \fBMDB_DUPSORT\fP cursors include an xcursor to the current data item\&. Write txns track their cursors and keep them up to date when data moves\&. Exception: An xcursor's pointer to a \fBP_SUBP\fP page can be stale\&. (A node with \fBF_DUPDATA\fP but no \fBF_SUBDATA\fP contains a subpage)\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "\fBMDB_cursor\fP * \fBmc_next\fP" .br .ti -1c .RI "\fBMDB_cursor\fP * \fBmc_backup\fP" .br .ti -1c .RI "struct \fBMDB_xcursor\fP * \fBmc_xcursor\fP" .br .ti -1c .RI "\fBMDB_txn\fP * \fBmc_txn\fP" .br .ti -1c .RI "\fBMDB_dbi\fP \fBmc_dbi\fP" .br .ti -1c .RI "\fBMDB_db\fP * \fBmc_db\fP" .br .ti -1c .RI "\fBMDB_dbx\fP * \fBmc_dbx\fP" .br .ti -1c .RI "unsigned char * \fBmc_dbflag\fP" .br .ti -1c .RI "unsigned short \fBmc_snum\fP" .br .ti -1c .RI "unsigned short \fBmc_top\fP" .br .ti -1c .RI "unsigned int \fBmc_flags\fP" .br .ti -1c .RI "\fBMDB_page\fP * \fBmc_pg\fP [\fBCURSOR_STACK\fP]" .br .ti -1c .RI "\fBindx_t\fP \fBmc_ki\fP [\fBCURSOR_STACK\fP]" .br .in -1c .SH "Field Documentation" .PP .SS "\fBMDB_cursor\fP* MDB_cursor::mc_next" Next cursor on this DB in this txn .SS "\fBMDB_cursor\fP* MDB_cursor::mc_backup" Backup of the original cursor if this cursor is a shadow .SS "struct \fBMDB_xcursor\fP* MDB_cursor::mc_xcursor" Context used for databases with \fBMDB_DUPSORT\fP, otherwise NULL .SS "\fBMDB_txn\fP* MDB_cursor::mc_txn" The transaction that owns this cursor .SS "\fBMDB_dbi\fP MDB_cursor::mc_dbi" The database handle this cursor operates on .SS "\fBMDB_db\fP* MDB_cursor::mc_db" The database record for this cursor .SS "\fBMDB_dbx\fP* MDB_cursor::mc_dbx" The database auxiliary record for this cursor .SS "unsigned char* MDB_cursor::mc_dbflag" The \fBTransaction DB Flags\fP for this database .SS "unsigned short MDB_cursor::mc_snum" number of pushed pages .SS "unsigned short MDB_cursor::mc_top" index of top page, normally mc_snum-1 .SS "unsigned int MDB_cursor::mc_flags" \fBCursor Flags\fP .SS "\fBMDB_page\fP* MDB_cursor::mc_pg[\fBCURSOR_STACK\fP]" stack of pushed pages .SS "\fBindx_t\fP MDB_cursor::mc_ki[\fBCURSOR_STACK\fP]" stack of page indices .SH "struct MDB_xcursor" .PP Context for sorted-dup records\&. We could have gone to a fully recursive design, with arbitrarily deep nesting of sub-databases\&. But for now we only handle these levels - main DB, optional sub-DB, sorted-duplicate DB\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "\fBMDB_cursor\fP \fBmx_cursor\fP" .br .ti -1c .RI "\fBMDB_db\fP \fBmx_db\fP" .br .ti -1c .RI "\fBMDB_dbx\fP \fBmx_dbx\fP" .br .ti -1c .RI "unsigned char \fBmx_dbflag\fP" .br .in -1c .SH "Field Documentation" .PP .SS "\fBMDB_cursor\fP MDB_xcursor::mx_cursor" A sub-cursor for traversing the Dup DB .SS "\fBMDB_db\fP MDB_xcursor::mx_db" The database record for this Dup DB .SS "\fBMDB_dbx\fP MDB_xcursor::mx_dbx" The auxiliary DB record for this Dup DB .SS "unsigned char MDB_xcursor::mx_dbflag" The \fBTransaction DB Flags\fP for this Dup DB .SH "struct MDB_pgstate" .PP State of FreeDB old pages, stored in the \fBMDB_env\fP .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "\fBpgno_t\fP * \fBmf_pghead\fP" .br .ti -1c .RI "\fBtxnid_t\fP \fBmf_pglast\fP" .br .in -1c .SH "Field Documentation" .PP .SS "\fBpgno_t\fP* MDB_pgstate::mf_pghead" Reclaimed freeDB pages, or NULL before use .SS "\fBtxnid_t\fP MDB_pgstate::mf_pglast" ID of last used record, or 0 if !mf_pghead .SH "struct MDB_env" .PP Opaque structure for a database environment\&. The database environment\&. .PP A DB environment supports multiple databases, all residing in the same shared-memory map\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "\fBHANDLE\fP \fBme_fd\fP" .br .ti -1c .RI "\fBHANDLE\fP \fBme_lfd\fP" .br .ti -1c .RI "\fBHANDLE\fP \fBme_mfd\fP" .br .ti -1c .RI "uint32_t \fBme_flags\fP" .br .ti -1c .RI "unsigned int \fBme_psize\fP" .br .ti -1c .RI "unsigned int \fBme_os_psize\fP" .br .ti -1c .RI "unsigned int \fBme_maxreaders\fP" .br .ti -1c .RI "volatile int \fBme_close_readers\fP" .br .ti -1c .RI "\fBMDB_dbi\fP \fBme_numdbs\fP" .br .ti -1c .RI "\fBMDB_dbi\fP \fBme_maxdbs\fP" .br .ti -1c .RI "MDB_PID_T \fBme_pid\fP" .br .ti -1c .RI "char * \fBme_path\fP" .br .ti -1c .RI "char * \fBme_map\fP" .br .ti -1c .RI "\fBMDB_txninfo\fP * \fBme_txns\fP" .br .ti -1c .RI "\fBMDB_meta\fP * \fBme_metas\fP [\fBNUM_METAS\fP]" .br .ti -1c .RI "void * \fBme_pbuf\fP" .br .ti -1c .RI "\fBMDB_txn\fP * \fBme_txn\fP" .br .ti -1c .RI "\fBMDB_txn\fP * \fBme_txn0\fP" .br .ti -1c .RI "size_t \fBme_mapsize\fP" .br .ti -1c .RI "off_t \fBme_size\fP" .br .ti -1c .RI "\fBpgno_t\fP \fBme_maxpg\fP" .br .ti -1c .RI "\fBMDB_dbx\fP * \fBme_dbxs\fP" .br .ti -1c .RI "uint16_t * \fBme_dbflags\fP" .br .ti -1c .RI "unsigned int * \fBme_dbiseqs\fP" .br .ti -1c .RI "pthread_key_t \fBme_txkey\fP" .br .ti -1c .RI "\fBtxnid_t\fP \fBme_pgoldest\fP" .br .ti -1c .RI "\fBMDB_pgstate\fP \fBme_pgstate\fP" .br .ti -1c .RI "\fBMDB_page\fP * \fBme_dpages\fP" .br .ti -1c .RI "\fBMDB_IDL\fP \fBme_free_pgs\fP" .br .ti -1c .RI "\fBMDB_ID2L\fP \fBme_dirty_list\fP" .br .ti -1c .RI "int \fBme_maxfree_1pg\fP" .br .ti -1c .RI "unsigned int \fBme_nodemax\fP" .br .ti -1c .RI "int \fBme_live_reader\fP" .br .ti -1c .RI "void * \fBme_userctx\fP" .br .ti -1c .RI "\fBMDB_assert_func\fP * \fBme_assert_func\fP" .br .in -1c .SH "Field Documentation" .PP .SS "\fBHANDLE\fP MDB_env::me_fd" The main data file .SS "\fBHANDLE\fP MDB_env::me_lfd" The lock file .SS "\fBHANDLE\fP MDB_env::me_mfd" just for writing the meta pages .SS "uint32_t MDB_env::me_flags" \fBEnvironment Flags\fP .SS "unsigned int MDB_env::me_psize" DB page size, inited from me_os_psize .SS "unsigned int MDB_env::me_os_psize" OS page size, from \fBGET_PAGESIZE\fP .SS "unsigned int MDB_env::me_maxreaders" size of the reader table .SS "volatile int MDB_env::me_close_readers" Max \fBMDB_txninfo\fP\&.mti_numreaders of interest to \fBmdb_env_close()\fP .SS "\fBMDB_dbi\fP MDB_env::me_numdbs" number of DBs opened .SS "\fBMDB_dbi\fP MDB_env::me_maxdbs" size of the DB table .SS "MDB_PID_T MDB_env::me_pid" process ID of this env .SS "char* MDB_env::me_path" path to the DB files .SS "char* MDB_env::me_map" the memory map of the data file .SS "\fBMDB_txninfo\fP* MDB_env::me_txns" the memory map of the lock file or NULL .SS "\fBMDB_meta\fP* MDB_env::me_metas[\fBNUM_METAS\fP]" pointers to the two meta pages .SS "void* MDB_env::me_pbuf" scratch area for DUPSORT put() .SS "\fBMDB_txn\fP* MDB_env::me_txn" current write transaction .SS "\fBMDB_txn\fP* MDB_env::me_txn0" prealloc'd write transaction .SS "size_t MDB_env::me_mapsize" size of the data memory map .SS "off_t MDB_env::me_size" current file size .SS "\fBpgno_t\fP MDB_env::me_maxpg" me_mapsize / me_psize .SS "\fBMDB_dbx\fP* MDB_env::me_dbxs" array of static DB info .SS "uint16_t* MDB_env::me_dbflags" array of flags from \fBMDB_db\&.md_flags\fP .SS "unsigned int* MDB_env::me_dbiseqs" array of dbi sequence numbers .SS "pthread_key_t MDB_env::me_txkey" thread-key for readers .SS "\fBtxnid_t\fP MDB_env::me_pgoldest" ID of oldest reader last time we looked .SS "\fBMDB_pgstate\fP MDB_env::me_pgstate" state of old pages from freeDB .SS "\fBMDB_page\fP* MDB_env::me_dpages" list of malloc'd blocks for re-use .SS "\fBMDB_IDL\fP MDB_env::me_free_pgs" IDL of pages that became unused in a write txn .SS "\fBMDB_ID2L\fP MDB_env::me_dirty_list" ID2L of pages written during a write txn\&. Length MDB_IDL_UM_SIZE\&. .SS "int MDB_env::me_maxfree_1pg" Max number of freelist items that can fit in a single overflow page .SS "unsigned int MDB_env::me_nodemax" Max size of a node on a page .SS "int MDB_env::me_live_reader" have liveness lock in reader table .SS "void* MDB_env::me_userctx" User-settable context .SS "\fBMDB_assert_func\fP* MDB_env::me_assert_func" Callback for assertion failures .SH "struct MDB_ntxn" .PP Nested transaction .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "\fBMDB_txn\fP \fBmnt_txn\fP" .br .ti -1c .RI "\fBMDB_pgstate\fP \fBmnt_pgstate\fP" .br .in -1c .SH "Field Documentation" .PP .SS "\fBMDB_txn\fP MDB_ntxn::mnt_txn" the transaction .SS "\fBMDB_pgstate\fP MDB_ntxn::mnt_pgstate" parent transaction's saved freestate .SH "struct mdb_copy" .PP State needed for a compacting copy\&. .PP .in -1c .RI "\fBData Fields\fP" .in +1c .in +1c .ti -1c .RI "pthread_mutex_t \fBmc_mutex\fP" .br .ti -1c .RI "pthread_cond_t \fBmc_cond\fP" .br .ti -1c .RI "char * \fBmc_wbuf\fP [2]" .br .ti -1c .RI "char * \fBmc_over\fP [2]" .br .ti -1c .RI "\fBMDB_env\fP * \fBmc_env\fP" .br .ti -1c .RI "\fBMDB_txn\fP * \fBmc_txn\fP" .br .ti -1c .RI "int \fBmc_wlen\fP [2]" .br .ti -1c .RI "int \fBmc_olen\fP [2]" .br .ti -1c .RI "\fBpgno_t\fP \fBmc_next_pgno\fP" .br .ti -1c .RI "\fBHANDLE\fP \fBmc_fd\fP" .br .ti -1c .RI "int \fBmc_status\fP" .br .ti -1c .RI "volatile int \fBmc_new\fP" .br .ti -1c .RI "int \fBmc_toggle\fP" .br .in -1c .SH "Macro Definition Documentation" .PP .SS "#define MDB_DSYNC O_SYNC" A flag for opening a file and requesting synchronous data writes\&. This is only used when writing a meta page\&. It's not strictly needed; we could just do a normal write and then immediately perform a flush\&. But if this flag is available it saves us an extra system call\&. .PP \fBNote:\fP .RS 4 If O_DSYNC is undefined but exists in /usr/include, preferably set some compiler flag to get the definition\&. .RE .PP .SS "#define MDB_FDATASYNC fdatasync" Function for flushing the data of a file\&. Define this to fsync if fdatasync() is not supported\&. .SS "#define MAX_PAGESIZE (\fBPAGEBASE\fP ? 0x10000 : 0x8000)" .PP The maximum size of a database page\&. It is 32k or 64k, since value-PAGEBASE must fit in \fBMDB_page\fP\&.mp_upper\&. .PP LMDB will use database pages < OS pages if needed\&. That causes more I/O in write transactions: The OS must know (read) the whole page before writing a partial page\&. .PP Note that we don't currently support Huge pages\&. On Linux, regular data files cannot use Huge pages, and in general Huge pages aren't actually pageable\&. We rely on the OS demand-pager to read our data and page it out when memory pressure from other processes is high\&. So until OSs have actual paging support for Huge pages, they're not viable\&. .SS "#define MDB_MINKEYS 2" The minimum number of keys required in a database page\&. Setting this to a larger value will place a smaller bound on the maximum size of a data item\&. Data items larger than this size will be pushed into overflow pages instead of being stored directly in the B-tree node\&. This value used to default to 4\&. With a page size of 4096 bytes that meant that any item larger than 1024 bytes would go into an overflow page\&. That also meant that on average 2-3KB of each overflow page was wasted space\&. The value cannot be lower than 2 because then there would no longer be a tree structure\&. With this value, items larger than 2KB will go into overflow pages, and on average only 1KB will be wasted\&. .SS "#define MDB_MAGIC 0xBEEFC0DE" A stamp that identifies a file as an LMDB file\&. There's nothing special about this value other than that it is easily recognizable, and it will reflect any byte order mismatches\&. .SS "#define MDB_DATA_VERSION ((\fBMDB_DEVEL\fP) ? 999 : 1)" The version number for a database's datafile format\&. .SS "#define MDB_LOCK_VERSION 1" The version number for a database's lockfile format\&. .SS "#define MDB_MAXKEYSIZE ((\fBMDB_DEVEL\fP) ? 0 : 511)" .PP The max size of a key we can write, or 0 for computed max\&. This macro should normally be left alone or set to 0\&. Note that a database with big keys or dupsort data cannot be reliably modified by a liblmdb which uses a smaller max\&. The default is 511 for backwards compat, or 0 when \fBMDB_DEVEL\fP\&. .PP Other values are allowed, for backwards compat\&. However: A value bigger than the computed max can break if you do not know what you are doing, and liblmdb <= 0\&.9\&.10 can break when modifying a DB with keys/dupsort data bigger than its max\&. .PP Data items in an \fBMDB_DUPSORT\fP database are also limited to this size, since they're actually keys of a sub-DB\&. Keys and \fBMDB_DUPSORT\fP data items must fit on a node in a regular page\&. .SS "#define ENV_MAXKEY(env) (\fBMDB_MAXKEYSIZE\fP)" The maximum size of a key we can write to the environment\&. .SS "#define MAXDATASIZE 0xffffffffUL" .PP The maximum size of a data item\&. We only store a 32 bit value for node sizes\&. .SS "#define P_INVALID (~(\fBpgno_t\fP)0)" An invalid page number\&. Mainly used to denote an empty tree\&. .SS "#define F_ISSET(w, f) (((w) & (f)) == (f))" Test if the flags \fBf\fP are set in a flag word \fBw\fP\&. .SS "#define EVEN(n) (((n) + 1U) & -2) /* sign-extending -2 to match n+1U */" Round \fBn\fP up to an even number\&. .SS "#define DEFAULT_MAPSIZE 1048576" Default size of memory map\&. This is certainly too small for any actual applications\&. Apps should always set the size explicitly using \fBmdb_env_set_mapsize()\fP\&. .SS "#define PAGEHDRSZ ((unsigned) offsetof(\fBMDB_page\fP, mp_ptrs))" Size of the page header, excluding dynamic data at the end .SS "#define METADATA(p) ((void *)((char *)(p) + \fBPAGEHDRSZ\fP))" Address of first usable data byte in a page, after the header .SS "#define PAGEBASE ((\fBMDB_DEVEL\fP) ? \fBPAGEHDRSZ\fP : 0)" ITS#7713, change PAGEBASE to handle 65536 byte pages .SS "#define NUMKEYS(p) (((p)->mp_lower - (\fBPAGEHDRSZ\fP-\fBPAGEBASE\fP)) >> 1)" Number of nodes on a page .SS "#define SIZELEFT(p) (\fBindx_t\fP)((p)->mp_upper - (p)->mp_lower)" The amount of space remaining in the page .SS "#define PAGEFILL(env, p)" \fBValue:\fP .PP .nf (1000L * ((env)->me_psize - PAGEHDRSZ - SIZELEFT(p)) / \ ((env)->me_psize - PAGEHDRSZ)) .fi The percentage of space used in the page, in tenths of a percent\&. .SS "#define FILL_THRESHOLD 250" The minimum page fill factor, in tenths of a percent\&. Pages emptier than this are candidates for merging\&. .SS "#define IS_LEAF(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_LEAF\fP)" Test if a page is a leaf page .SS "#define IS_LEAF2(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_LEAF2\fP)" Test if a page is a LEAF2 page .SS "#define IS_BRANCH(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_BRANCH\fP)" Test if a page is a branch page .SS "#define IS_OVERFLOW(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_OVERFLOW\fP)" Test if a page is an overflow page .SS "#define IS_SUBP(p) \fBF_ISSET\fP((p)->mp_flags, \fBP_SUBP\fP)" Test if a page is a sub page .SS "#define OVPAGES(size, psize) ((\fBPAGEHDRSZ\fP-1 + (size)) / (psize) + 1)" The number of overflow pages needed to store the given size\&. .SS "#define NEXT_LOOSE_PAGE(p) (*(\fBMDB_page\fP **)((p) + 2))" Link in \fBMDB_txn\fP\&.mt_loose_pgs list .SS "#define NODESIZE offsetof(\fBMDB_node\fP, mn_data)" Size of the node header, excluding dynamic data at the end .SS "#define PGNO_TOPWORD ((\fBpgno_t\fP)-1 > 0xffffffffu ? 32 : 0)" Bit position of top word in page number, for shifting mn_flags .SS "#define INDXSIZE(k) (\fBNODESIZE\fP + ((k) == NULL ? 0 : (k)->mv_size))" Size of a node in a branch page with a given key\&. This is just the node header plus the key, there is no data\&. .SS "#define LEAFSIZE(k, d) (\fBNODESIZE\fP + (k)->mv_size + (d)->mv_size)" Size of a node in a leaf page with a given key and data\&. This is node header plus key plus data size\&. .SS "#define NODEPTR(p, i) ((\fBMDB_node\fP *)((char *)(p) + (p)->mp_ptrs[i] + \fBPAGEBASE\fP))" Address of node \fBi\fP in page \fBp\fP .SS "#define NODEKEY(node) (void *)((node)->mn_data)" Address of the key for the node .SS "#define NODEDATA(node) (void *)((char *)(node)->mn_data + (node)->mn_ksize)" Address of the data for a node .SS "#define NODEPGNO(node)" \fBValue:\fP .PP .nf ((node)->mn_lo | ((pgno_t) (node)->mn_hi << 16) | \ (PGNO_TOPWORD ? ((pgno_t) (node)->mn_flags << PGNO_TOPWORD) : 0)) .fi Get the page number pointed to by a branch node .SS "#define SETPGNO(node, pgno)" \fBValue:\fP .PP .nf do { \ (node)->mn_lo = (pgno) & 0xffff; (node)->mn_hi = (pgno) >> 16; \ if (PGNO_TOPWORD) (node)->mn_flags = (pgno) >> PGNO_TOPWORD; } while(0) .fi Set the page number in a branch node .SS "#define NODEDSZ(node) ((node)->mn_lo | ((unsigned)(node)->mn_hi << 16))" Get the size of the data in a leaf node .SS "#define SETDSZ(node, size)" \fBValue:\fP .PP .nf do { \ (node)->mn_lo = (size) & 0xffff; (node)->mn_hi = (size) >> 16;} while(0) .fi Set the size of the data for a leaf node .SS "#define NODEKSZ(node) ((node)->mn_ksize)" The size of a key in a node .SS "#define COPY_PGNO(dst, src)" \fBValue:\fP .PP .nf do { \ unsigned short *s, *d; \ s = (unsigned short *)&(src); \ d = (unsigned short *)&(dst); \ *d++ = *s++; \ *d = *s; \ } while (0) .fi Copy a page number from src to dst .SS "#define LEAF2KEY(p, i, ks) ((char *)(p) + \fBPAGEHDRSZ\fP + ((i)*(ks)))" The address of a key in a LEAF2 page\&. LEAF2 pages are used for \fBMDB_DUPFIXED\fP sorted-duplicate sub-DBs\&. There are no node headers, keys are stored contiguously\&. .SS "#define MDB_GET_KEY(node, keyptr)" \fBValue:\fP .PP .nf { if ((keyptr) != NULL) { \ (keyptr)->mv_size = NODEKSZ(node); (keyptr)->mv_data = NODEKEY(node); } } .fi Set the \fBnode's\fP key into \fBkeyptr\fP, if requested\&. .SS "#define MDB_GET_KEY2(node, key) { key\&.mv_size = \fBNODEKSZ\fP(node); key\&.mv_data = \fBNODEKEY\fP(node); }" Set the \fBnode's\fP key into \fBkey\fP\&. .SS "#define MDB_VALID 0x8000" mdb_dbi_open flags DB handle is valid, for me_dbflags .SS "#define VALID_FLAGS" \fBValue:\fP .PP .nf (MDB_REVERSEKEY|MDB_DUPSORT|MDB_INTEGERKEY|MDB_DUPFIXED|\\ MDB_INTEGERDUP|MDB_REVERSEDUP|MDB_CREATE) .fi .SS "#define FREE_DBI 0" Handle for the DB used to track free pages\&. .SS "#define MAIN_DBI 1" Handle for the default DB\&. .SS "#define CORE_DBS 2" Number of DBs in metapage (free and main) - also hardcoded elsewhere .SS "#define NUM_METAS 2" Number of meta pages - also hardcoded elsewhere .SS "#define CURSOR_STACK 32" Enough space for 2^32 nodes with minimum of 2 keys per node\&. I\&.e\&., plenty\&. At 4 keys per node, enough for 2^64 nodes, so there's probably no need to raise this on a 64 bit machine\&. .SS "#define MDB_COMMIT_PAGES 64" max number of pages to commit in one writev() call .SS "#define MAX_WRITE (0x40000000U >> (sizeof(ssize_t) == 4))" max bytes to write in one call .SS "#define TXN_DBI_EXIST(txn, dbi, validity) ((txn) && (dbi)<(txn)->mt_numdbs && ((txn)->mt_dbflags[dbi] & (validity)))" Check \fBtxn\fP and \fBdbi\fP arguments to a function .SS "#define TXN_DBI_CHANGED(txn, dbi) ((txn)->mt_dbiseqs[dbi] != (txn)->mt_env->me_dbiseqs[dbi])" Check for misused \fBdbi\fP handles .SS "#define MDB_END_NAMES" \fBValue:\fP .PP .nf {"committed", "empty-commit", "abort", "reset", \ "reset-tmp", "fail-begin", "fail-beginchild"} .fi .SS "#define MDB_END_OPMASK 0x0F" mask for \fBmdb_txn_end()\fP operation number .SS "#define MDB_END_UPDATE 0x10" update env state (DBIs) .SS "#define MDB_END_FREE 0x20" free txn unless it is \fBMDB_env\fP\&.me_txn0 .SS "#define MDB_END_SLOT \fBMDB_NOTLS\fP" release any reader slot if \fBMDB_NOTLS\fP .SS "#define MDB_SPLIT_REPLACE \fBMDB_APPENDDUP\fP" newkey is not new .SS "#define mdb_cmp_clong \fBmdb_cmp_cint\fP" Compare two items pointing at size_t's of unknown alignment\&. .SS "#define mdb_cassert(mc, expr) mdb_assert0((mc)->mc_txn->mt_env, expr, #expr)" assert(3) variant in cursor context .SS "#define mdb_tassert(txn, expr) mdb_assert0((txn)->mt_env, expr, #expr)" assert(3) variant in transaction context .SS "#define mdb_eassert(env, expr) mdb_assert0(env, expr, #expr)" assert(3) variant in environment context .SS "#define mdb_assert0(env, expr, expr_txt)" \fBValue:\fP .PP .nf ((expr) ? (void)0 : \ mdb_assert_fail(env, expr_txt, mdb_func_, __FILE__, __LINE__)) .fi .SS "#define LOCKNAME '/lock\&.mdb'" The name of the lock file in the DB environment .SS "#define DATANAME '/data\&.mdb'" The name of the data file in the DB environment .SS "#define LOCKSUFF '-lock'" The suffix of the lock file when no subdir is used .SS "#define CHANGEABLE (\fBMDB_NOSYNC\fP|\fBMDB_NOMETASYNC\fP|\fBMDB_MAPASYNC\fP|\fBMDB_NOMEMINIT\fP)" Only a subset of the \fBEnvironment Flags\fP flags can be changed at runtime\&. Changing other flags requires closing the environment and re-opening it with the new flags\&. .SS "#define CHANGELESS" \fBValue:\fP .PP .nf (MDB_FIXEDMAP|MDB_NOSUBDIR|MDB_RDONLY| \\ MDB_WRITEMAP|MDB_NOTLS|MDB_NOLOCK|MDB_NORDAHEAD) .fi .SS "#define MDB_NOSPILL 0x8000" Do not spill pages to disk if txn is getting full, may fail instead .SS "#define WITH_CURSOR_TRACKING(mn, act)" \fBValue:\fP .PP .nf do { \ MDB_cursor dummy, *tracked, **tp = &(mn)\&.mc_txn->mt_cursors[mn\&.mc_dbi]; \ if ((mn)\&.mc_flags & C_SUB) { \ dummy\&.mc_flags = C_INITIALIZED; \ dummy\&.mc_xcursor = (MDB_xcursor *)&(mn); \ tracked = &dummy; \ } else { \ tracked = &(mn); \ } \ tracked->mc_next = *tp; \ *tp = tracked; \ { act; } \ *tp = tracked->mc_next; \ } while (0) .fi Perform \fBact\fP while tracking temporary cursor \fBmn\fP .SH "Typedef Documentation" .PP .SS "typedef \fBMDB_ID\fP \fBpgno_t\fP" A page number in the database\&. Note that 64 bit page numbers are overkill, since pages themselves already represent 12-13 bits of addressable memory, and the OS will always limit applications to a maximum of 63 bits of address space\&. .PP \fBNote:\fP .RS 4 In the \fBMDB_node\fP structure, we only store 48 bits of this value, which thus limits us to only 60 bits of addressable data\&. .RE .PP .SS "typedef \fBMDB_ID\fP \fBtxnid_t\fP" A transaction ID\&. See struct \fBMDB_txn\&.mt_txnid\fP for details\&. .SS "typedef uint16_t \fBindx_t\fP" Used for offsets within a single page\&. Since memory pages are typically 4 or 8KB in size, 12-13 bits, this is plenty\&. .SH "Function Documentation" .PP .SS "static int mdb_page_alloc (\fBMDB_cursor\fP *mc, intnum, \fBMDB_page\fP **mp)\fC [static]\fP" Allocate page numbers and memory for writing\&. Maintain me_pglast, me_pghead and mt_next_pgno\&. .PP If there are free pages available from older transactions, they are re-used first\&. Otherwise allocate a new page at mt_next_pgno\&. Do not modify the freedB, just merge freeDB records into me_pghead[] and move me_pglast to say which records were consumed\&. Only this function can create me_pghead and move me_pglast/mt_next_pgno\&. .PP \fBParameters:\fP .RS 4 \fImc\fP cursor A cursor handle identifying the transaction and database for which we are allocating\&. .br \fInum\fP the number of pages to allocate\&. .br \fImp\fP Address of the allocated page(s)\&. Requests for multiple pages will always be satisfied by a single contiguous chunk of memory\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_page_new (\fBMDB_cursor\fP *mc, uint32_tflags, intnum, \fBMDB_page\fP **mp)\fC [static]\fP" Allocate and initialize new pages for a database\&. .PP \fBParameters:\fP .RS 4 \fImc\fP a cursor on the database being added to\&. .br \fIflags\fP flags defining what type of page is being allocated\&. .br \fInum\fP the number of pages to allocate\&. This is usually 1, unless allocating overflow pages for a large record\&. .br \fImp\fP Address of a page, or NULL on failure\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_page_touch (\fBMDB_cursor\fP *mc)\fC [static]\fP" Touch a page: make it dirty and re-insert into tree with updated pgno\&. .PP \fBParameters:\fP .RS 4 \fImc\fP cursor pointing to the page to be touched .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static void mdb_txn_end (\fBMDB_txn\fP *txn, unsignedmode)\fC [static]\fP" End a transaction, except successful commit of a nested transaction\&. May be called twice for readonly txns: First reset it, then abort\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP the transaction handle to end .br \fImode\fP why and how to end the transaction .RE .PP .SS "static int mdb_page_get (\fBMDB_txn\fP *txn, \fBpgno_t\fPpgno, \fBMDB_page\fP **ret, int *lvl)\fC [static]\fP" Find the address of the page corresponding to a given page number\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP the transaction for this access\&. .br \fIpgno\fP the page number for the page to retrieve\&. .br \fIret\fP address of a pointer where the page's address will be stored\&. .br \fIlvl\fP dirty_list inheritance level of found page\&. 1=current txn, 0=mapped page\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_page_search_root (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, intflags)\fC [static]\fP" Finish \fBmdb_page_search()\fP / \fBmdb_page_search_lowest()\fP\&. The cursor is at the root page, set up the rest of it\&. .SS "static int mdb_page_search (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, intflags)\fC [static]\fP" Search for the page a given key should be in\&. Push it and its parent pages on the cursor stack\&. .PP \fBParameters:\fP .RS 4 \fImc\fP the cursor for this operation\&. .br \fIkey\fP the key to search for, or NULL for first/last page\&. .br \fIflags\fP If MDB_PS_MODIFY is set, visited pages in the DB are touched (updated with new page numbers)\&. If MDB_PS_FIRST or MDB_PS_LAST is set, find first or last leaf\&. This is used by \fBmdb_cursor_first()\fP and \fBmdb_cursor_last()\fP\&. If MDB_PS_ROOTONLY set, just fetch root node, no further lookups\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_page_merge (\fBMDB_cursor\fP *csrc, \fBMDB_cursor\fP *cdst)\fC [static]\fP" Merge one page into another\&. The nodes from the page pointed to by \fBcsrc\fP will be copied to the page pointed to by \fBcdst\fP and then the \fBcsrc\fP page will be freed\&. .PP \fBParameters:\fP .RS 4 \fIcsrc\fP Cursor pointing to the source page\&. .br \fIcdst\fP Cursor pointing to the destination page\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_page_split (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *newkey, \fBMDB_val\fP *newdata, \fBpgno_t\fPnewpgno, unsigned intnflags)\fC [static]\fP" Split a page and insert a new node\&. .PP \fBParameters:\fP .RS 4 \fImc\fP Cursor pointing to the page and desired insertion index\&. The cursor will be updated to point to the actual page and index where the node got inserted after the split\&. .br \fInewkey\fP The key for the newly inserted node\&. .br \fInewdata\fP The data for the newly inserted node\&. .br \fInewpgno\fP The page number, if the new node is a branch node\&. .br \fInflags\fP The \fBNODE_ADD_FLAGS\fP for the new node\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int \fBESECT\fP mdb_env_read_header (\fBMDB_env\fP *env, \fBMDB_meta\fP *meta)\fC [static]\fP" Read the environment parameters of a DB environment before mapping it into memory\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP the environment handle .br \fImeta\fP address of where to store the meta information .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static \fBMDB_meta\fP * mdb_env_pick_meta (const \fBMDB_env\fP *env)\fC [static]\fP" Check both meta pages to see which one is newer\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP the environment handle .RE .PP \fBReturns:\fP .RS 4 newest \fBMDB_meta\fP\&. .RE .PP .SS "static int mdb_env_write_meta (\fBMDB_txn\fP *txn)\fC [static]\fP" Update the environment info to commit a transaction\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP the transaction that's being committed .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static void \fBESECT\fP mdb_env_close0 (\fBMDB_env\fP *env, intexcl)\fC [static]\fP" Destroy resources from \fBmdb_env_open()\fP, clear our readers & DBIs .SS "static \fBMDB_node\fP * mdb_node_search (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, int *exactp)\fC [static]\fP" Search for key within a page, using binary search\&. Returns the smallest entry larger or equal to the key\&. If exactp is non-null, stores whether the found entry was an exact match in *exactp (1 or 0)\&. Updates the cursor index with the index of the found entry\&. If no entry larger or equal to the key is found, returns NULL\&. .SS "static int mdb_node_add (\fBMDB_cursor\fP *mc, \fBindx_t\fPindx, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBpgno_t\fPpgno, unsigned intflags)\fC [static]\fP" Add a node to the page pointed to by the cursor\&. .PP \fBParameters:\fP .RS 4 \fImc\fP The cursor for this operation\&. .br \fIindx\fP The index on the page where the new node should be added\&. .br \fIkey\fP The key for the new node\&. .br \fIdata\fP The data for the new node, if any\&. .br \fIpgno\fP The page number, if adding a branch node\&. .br \fIflags\fP Flags for the node\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. Possible errors are: .PD 0 .IP "\(bu" 2 ENOMEM - failed to allocate overflow pages for the node\&. .IP "\(bu" 2 MDB_PAGE_FULL - there is insufficient room in the page\&. This error should never happen since all callers already calculate the page's free space before calling this function\&. .PP .RE .PP .SS "static void mdb_node_del (\fBMDB_cursor\fP *mc, intksize)\fC [static]\fP" Delete the specified node from a page\&. .PP \fBParameters:\fP .RS 4 \fImc\fP Cursor pointing to the node to delete\&. .br \fIksize\fP The size of a node\&. Only used if the page is part of a \fBMDB_DUPFIXED\fP database\&. .RE .PP .SS "static void mdb_node_shrink (\fBMDB_page\fP *mp, \fBindx_t\fPindx)\fC [static]\fP" Compact the main page after deleting a node on a subpage\&. .PP \fBParameters:\fP .RS 4 \fImp\fP The main page to operate on\&. .br \fIindx\fP The index of the subpage on the main page\&. .RE .PP .SS "static int mdb_node_move (\fBMDB_cursor\fP *csrc, \fBMDB_cursor\fP *cdst, intfromleft)\fC [static]\fP" Move a node from csrc to cdst\&. .SS "static int mdb_node_read (\fBMDB_txn\fP *txn, \fBMDB_node\fP *leaf, \fBMDB_val\fP *data)\fC [static]\fP" Return the data associated with a given node\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP The transaction for this operation\&. .br \fIleaf\fP The node being read\&. .br \fIdata\fP Updated to point to the node's data\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static size_t mdb_leaf_size (\fBMDB_env\fP *env, \fBMDB_val\fP *key, \fBMDB_val\fP *data)\fC [static]\fP" Calculate the size of a leaf node\&. The size depends on the environment's page size; if a data item is too large it will be put onto an overflow page and the node size will only include the key and not the data\&. Sizes are always rounded up to an even number of bytes, to guarantee 2-byte alignment of the \fBMDB_node\fP headers\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP The environment handle\&. .br \fIkey\fP The key for the node\&. .br \fIdata\fP The data for the node\&. .RE .PP \fBReturns:\fP .RS 4 The number of bytes needed to store the node\&. .RE .PP .SS "static size_t mdb_branch_size (\fBMDB_env\fP *env, \fBMDB_val\fP *key)\fC [static]\fP" Calculate the size of a branch node\&. The size should depend on the environment's page size but since we currently don't support spilling large keys onto overflow pages, it's simply the size of the \fBMDB_node\fP header plus the size of the key\&. Sizes are always rounded up to an even number of bytes, to guarantee 2-byte alignment of the \fBMDB_node\fP headers\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP The environment handle\&. .br \fIkey\fP The key for the node\&. .RE .PP \fBReturns:\fP .RS 4 The number of bytes needed to store the node\&. .RE .PP .SS "static int mdb_rebalance (\fBMDB_cursor\fP *mc)\fC [static]\fP" Rebalance the tree after a delete operation\&. .PP \fBParameters:\fP .RS 4 \fImc\fP Cursor pointing to the page where rebalancing should begin\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_update_key (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key)\fC [static]\fP" Replace the key for a branch node with a new key\&. .PP \fBParameters:\fP .RS 4 \fImc\fP Cursor pointing to the node to operate on\&. .br \fIkey\fP The new key to use\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static void mdb_cursor_pop (\fBMDB_cursor\fP *mc)\fC [static]\fP" Pop a page off the top of the cursor's stack\&. .SS "static int mdb_cursor_push (\fBMDB_cursor\fP *mc, \fBMDB_page\fP *mp)\fC [static]\fP" Push a page onto the top of the cursor's stack\&. .SS "static int mdb_cursor_del0 (\fBMDB_cursor\fP *mc)\fC [static]\fP" Complete a delete operation started by \fBmdb_cursor_del()\fP\&. .SS "static int mdb_cursor_sibling (\fBMDB_cursor\fP *mc, intmove_right)\fC [static]\fP" Find a sibling for a page\&. Replaces the page at the top of the cursor's stack with the specified sibling, if one exists\&. .PP \fBParameters:\fP .RS 4 \fImc\fP The cursor for this operation\&. .br \fImove_right\fP Non-zero if the right sibling is requested, otherwise the left sibling\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_cursor_next (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fPop)\fC [static]\fP" Move the cursor to the next data item\&. .SS "static int mdb_cursor_prev (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fPop)\fC [static]\fP" Move the cursor to the previous data item\&. .SS "static int mdb_cursor_set (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fPop, int *exactp)\fC [static]\fP" Set the cursor on a specific data item\&. .SS "static int mdb_cursor_first (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data)\fC [static]\fP" Move the cursor to the first item in the database\&. .SS "static int mdb_cursor_last (\fBMDB_cursor\fP *mc, \fBMDB_val\fP *key, \fBMDB_val\fP *data)\fC [static]\fP" Move the cursor to the last item in the database\&. .SS "static void mdb_cursor_init (\fBMDB_cursor\fP *mc, \fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, \fBMDB_xcursor\fP *mx)\fC [static]\fP" Initialize a cursor for a given transaction and database\&. .SS "static void mdb_xcursor_init0 (\fBMDB_cursor\fP *mc)\fC [static]\fP" Initial setup of a sorted-dups cursor\&. Sorted duplicates are implemented as a sub-database for the given key\&. The duplicate data items are actually keys of the sub-database\&. Operations on the duplicate data items are performed using a sub-cursor initialized when the sub-database is first accessed\&. This function does the preliminary setup of the sub-cursor, filling in the fields that depend only on the parent DB\&. .PP \fBParameters:\fP .RS 4 \fImc\fP The main cursor whose sorted-dups cursor is to be initialized\&. .RE .PP .SS "static void mdb_xcursor_init1 (\fBMDB_cursor\fP *mc, \fBMDB_node\fP *node)\fC [static]\fP" Final setup of a sorted-dups cursor\&. Sets up the fields that depend on the data from the main cursor\&. .PP \fBParameters:\fP .RS 4 \fImc\fP The main cursor whose sorted-dups cursor is to be initialized\&. .br \fInode\fP The data containing the \fBMDB_db\fP record for the sorted-dup database\&. .RE .PP .SS "static void mdb_xcursor_init2 (\fBMDB_cursor\fP *mc, \fBMDB_xcursor\fP *src_mx, intnew_dupdata)\fC [static]\fP" Fixup a sorted-dups cursor due to underlying update\&. Sets up some fields that depend on the data from the main cursor\&. Almost the same as init1, but skips initialization steps if the xcursor had already been used\&. .PP \fBParameters:\fP .RS 4 \fImc\fP The main cursor whose sorted-dups cursor is to be fixed up\&. .br \fIsrc_mx\fP The xcursor of an up-to-date cursor\&. .br \fInew_dupdata\fP True if converting from a non-\fBF_DUPDATA\fP item\&. .RE .PP .SS "static int mdb_drop0 (\fBMDB_cursor\fP *mc, intsubs)\fC [static]\fP" Add all the DB's pages to the free list\&. .PP \fBParameters:\fP .RS 4 \fImc\fP Cursor on the DB to free\&. .br \fIsubs\fP non-Zero to check for sub-DBs in this DB\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static void mdb_default_cmp (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi)\fC [static]\fP" Set the default comparison functions for a database\&. Called immediately after a database is opened to set the defaults\&. The user can then override them with \fBmdb_set_compare()\fP or \fBmdb_set_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 .RE .PP .SS "static int \fBESECT\fP mdb_reader_check0 (\fBMDB_env\fP *env, intrlocked, int *dead)\fC [static]\fP" As \fBmdb_reader_check()\fP\&. rlocked = =''>\&. .SS "char* \fBESECT\fP mdb_version (int *major, int *minor, int *patch)" .PP Return the LMDB library version information\&. Return the library version info\&. .SS "char* mdb_strerror (interr)" .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_cmp (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, 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\fPdbi, 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 "static \fBMDB_page\fP* mdb_page_malloc (\fBMDB_txn\fP *txn, unsignednum)\fC [static]\fP" Allocate memory for a page\&. Re-use old malloc'd pages first for singletons, otherwise just malloc\&. .SS "static void mdb_page_free (\fBMDB_env\fP *env, \fBMDB_page\fP *mp)\fC [static]\fP" Free a single page\&. Saves single pages to a list, for future reuse\&. (This is not used for multi-page overflow pages\&.) .SS "static void mdb_dpage_free (\fBMDB_env\fP *env, \fBMDB_page\fP *dp)\fC [static]\fP" Free a dirty page .SS "static void mdb_dlist_free (\fBMDB_txn\fP *txn)\fC [static]\fP" Return all dirty pages to dpage list .SS "static int mdb_page_loose (\fBMDB_cursor\fP *mc, \fBMDB_page\fP *mp)\fC [static]\fP" Loosen or free a single page\&. Saves single pages to a list for future reuse in this same txn\&. It has been pulled from the freeDB and already resides on the dirty list, but has been deleted\&. Use these pages first before pulling again from the freeDB\&. .PP If the page wasn't dirtied in this txn, just add it to this txn's free list\&. .SS "static int mdb_pages_xkeep (\fBMDB_cursor\fP *mc, unsignedpflags, intall)\fC [static]\fP" Set or clear P_KEEP in dirty, non-overflow, non-sub pages watched by txn\&. .PP \fBParameters:\fP .RS 4 \fImc\fP A cursor handle for the current operation\&. .br \fIpflags\fP Flags of the pages to update: P_DIRTY to set P_KEEP, P_DIRTY|P_KEEP to clear it\&. .br \fIall\fP No shortcuts\&. Needed except after a full \fBmdb_page_flush()\fP\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_page_flush (\fBMDB_txn\fP *txn, intkeep)\fC [static]\fP" Flush (some) dirty pages to the map, after clearing their dirty flag\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP the transaction that's being committed .br \fIkeep\fP number of initial pages in dirty_list to keep dirty\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_page_spill (\fBMDB_cursor\fP *m0, \fBMDB_val\fP *key, \fBMDB_val\fP *data)\fC [static]\fP" Spill pages from the dirty list back to disk\&. This is intended to prevent running into \fBMDB_TXN_FULL\fP situations, but note that they may still occur in a few cases: 1) our estimate of the txn size could be too small\&. Currently this seems unlikely, except with a large number of \fBMDB_MULTIPLE\fP items\&. 2) child txns may run out of space if their parents dirtied a lot of pages and never spilled them\&. TODO: we probably should do a preemptive spill during \fBmdb_txn_begin()\fP of a child txn, if the parent's dirty_room is below a given threshold\&. .PP Otherwise, if not using nested txns, it is expected that apps will not run into \fBMDB_TXN_FULL\fP any more\&. The pages are flushed to disk the same way as for a txn commit, e\&.g\&. their P_DIRTY flag is cleared\&. If the txn never references them again, they can be left alone\&. If the txn only reads them, they can be used without any fuss\&. If the txn writes them again, they can be dirtied immediately without going thru all of the work of \fBmdb_page_touch()\fP\&. Such references are handled by \fBmdb_page_unspill()\fP\&. .PP Also note, we never spill DB root pages, nor pages of active cursors, because we'll need these back again soon anyway\&. And in nested txns, we can't spill a page in a child txn if it was already spilled in a parent txn\&. That would alter the parent txns' data even though the child hasn't committed yet, and we'd have no way to undo it if the child aborted\&. .PP \fBParameters:\fP .RS 4 \fIm0\fP cursor A cursor handle identifying the transaction and database for which we are checking space\&. .br \fIkey\fP For a put operation, the key being stored\&. .br \fIdata\fP For a put operation, the data being stored\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static \fBtxnid_t\fP mdb_find_oldest (\fBMDB_txn\fP *txn)\fC [static]\fP" Find oldest txnid still referenced\&. Expects txn->mt_txnid > 0\&. .SS "static void mdb_page_dirty (\fBMDB_txn\fP *txn, \fBMDB_page\fP *mp)\fC [static]\fP" Add a page to the txn's dirty list .SS "static void mdb_page_copy (\fBMDB_page\fP *dst, \fBMDB_page\fP *src, unsigned intpsize)\fC [static]\fP" Copy the used portions of a non-overflow page\&. .PP \fBParameters:\fP .RS 4 \fIdst\fP page to copy into .br \fIsrc\fP page to copy from .br \fIpsize\fP size of a page .RE .PP .SS "static int mdb_page_unspill (\fBMDB_txn\fP *txn, \fBMDB_page\fP *mp, \fBMDB_page\fP **ret)\fC [static]\fP" Pull a page off the txn's spill list, if present\&. If a page being referenced was spilled to disk in this txn, bring it back and make it dirty/writable again\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP the transaction handle\&. .br \fImp\fP the page being referenced\&. It must not be dirty\&. .br \fIret\fP the writable page, if any\&. ret is unchanged if mp wasn't spilled\&. .RE .PP .SS "int mdb_env_sync (\fBMDB_env\fP *env, intforce)" .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 "static int mdb_cursor_shadow (\fBMDB_txn\fP *src, \fBMDB_txn\fP *dst)\fC [static]\fP" Back up parent txn's cursors, then grab the originals for tracking .SS "static void mdb_cursors_close (\fBMDB_txn\fP *txn, unsignedmerge)\fC [static]\fP" Close this write txn's cursors, give parent txn's cursors back to parent\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP the transaction handle\&. .br \fImerge\fP true to keep changes to parent cursors, false to revert\&. .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "static int mdb_reader_pid (\fBMDB_env\fP *env, enum Pidlock_opop, MDB_PID_Tpid)\fC [static]\fP" Set or check a pid lock\&. Set returns 0 on success\&. Check returns 0 if the process is certainly dead, nonzero if it may be alive (the lock exists or an error happened so we do not know)\&. .PP On Windows Pidset is a no-op, we merely check for the existence of the process with the given pid\&. On POSIX we use a single byte lock on the lockfile, set at an offset equal to the pid\&. .SS "static int mdb_txn_renew0 (\fBMDB_txn\fP *txn)\fC [static]\fP" Common code for \fBmdb_txn_begin()\fP and \fBmdb_txn_renew()\fP\&. .PP \fBParameters:\fP .RS 4 \fItxn\fP the transaction handle to initialize .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .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_txn_begin (\fBMDB_env\fP *env, \fBMDB_txn\fP *parent, unsigned intflags, \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 "static void mdb_dbis_update (\fBMDB_txn\fP *txn, intkeep)\fC [static]\fP" Export or close DBI handles opened in this txn\&. .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 "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 "static int mdb_freelist_save (\fBMDB_txn\fP *txn)\fC [static]\fP" Save the freelist as of this transaction to the freeDB\&. This changes the freelist\&. Keep trying until it stabilizes\&. .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 "static void \fBESECT\fP mdb_env_init_meta0 (\fBMDB_env\fP *env, \fBMDB_meta\fP *meta)\fC [static]\fP" Fill in most of the zeroed \fBMDB_meta\fP for an empty database environment .SS "static int \fBESECT\fP mdb_env_init_meta (\fBMDB_env\fP *env, \fBMDB_meta\fP *meta)\fC [static]\fP" Write the environment parameters of a freshly created DB environment\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP the environment handle .br \fImeta\fP the \fBMDB_meta\fP to write .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "int \fBESECT\fP 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 \fBESECT\fP mdb_env_set_mapsize (\fBMDB_env\fP *env, size_tsize)" .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 \fBESECT\fP mdb_env_set_maxdbs (\fBMDB_env\fP *env, \fBMDB_dbi\fPdbs)" .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 \fBESECT\fP mdb_env_set_maxreaders (\fBMDB_env\fP *env, unsigned intreaders)" .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 \fBESECT\fP 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 "static int \fBESECT\fP mdb_env_open2 (\fBMDB_env\fP *env)\fC [static]\fP" Further setup required for opening an LMDB environment .SS "static void mdb_env_reader_dest (void *ptr)\fC [static]\fP" Release a reader thread's slot in the reader lock table\&. This function is called automatically when a thread exits\&. .PP \fBParameters:\fP .RS 4 \fIptr\fP This points to the slot in the reader lock table\&. .RE .PP .SS "static int \fBESECT\fP mdb_env_share_locks (\fBMDB_env\fP *env, int *excl)\fC [static]\fP" Downgrade the exclusive lock on the region back to shared .SS "static int \fBESECT\fP mdb_env_excl_lock (\fBMDB_env\fP *env, int *excl)\fC [static]\fP" Try to get exclusive lock, otherwise shared\&. Maintain *excl = -1: no/unknown lock, 0: shared, 1: exclusive\&. .SS "static int \fBESECT\fP mdb_env_setup_locks (\fBMDB_env\fP *env, char *lpath, intmode, int *excl)\fC [static]\fP" Open and/or initialize the lock region for the environment\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP The LMDB environment\&. .br \fIlpath\fP The pathname of the file used for the lock region\&. .br \fImode\fP The Unix permissions for the file, if we create it\&. .br \fIexcl\fP In -1, out lock type: -1 none, 0 shared, 1 exclusive .RE .PP \fBReturns:\fP .RS 4 0 on success, non-zero on failure\&. .RE .PP .SS "int \fBESECT\fP mdb_env_open (\fBMDB_env\fP *env, const char *path, unsigned intflags, \fBmdb_mode_t\fPmode)" .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 "void \fBESECT\fP 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 "static int mdb_cmp_long (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)\fC [static]\fP" Compare two items pointing at aligned size_t's .SS "static int mdb_cmp_int (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)\fC [static]\fP" Compare two items pointing at aligned unsigned int's\&. .PP This is also set as \fBMDB_INTEGERDUP\fP|\fBMDB_DUPFIXED\fP's \fBMDB_dbx\fP\&.md_dcmp, but \fBmdb_cmp_clong()\fP is called instead if the data type is size_t\&. .SS "static int mdb_cmp_cint (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)\fC [static]\fP" Compare two items pointing at unsigned ints of unknown alignment\&. Nodes and keys are guaranteed to be 2-byte aligned\&. .SS "static int mdb_cmp_memn (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)\fC [static]\fP" Compare two items lexically .SS "static int mdb_cmp_memnr (const \fBMDB_val\fP *a, const \fBMDB_val\fP *b)\fC [static]\fP" Compare two items in reverse byte order .SS "static int mdb_page_search_lowest (\fBMDB_cursor\fP *mc)\fC [static]\fP" Search for the lowest key under the current branch page\&. This just bypasses a NUMKEYS check in the current page before calling \fBmdb_page_search_root()\fP, because the callers are all in situations where the current page is known to be underfilled\&. .SS "int mdb_get (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, \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_cursor_get (\fBMDB_cursor\fP *cursor, \fBMDB_val\fP *key, \fBMDB_val\fP *data, \fBMDB_cursor_op\fPop)" .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 "static int mdb_cursor_touch (\fBMDB_cursor\fP *mc)\fC [static]\fP" Touch all the pages in the cursor stack\&. Set mc_top\&. Makes sure all the pages are writable, before attempting a write operation\&. .PP \fBParameters:\fP .RS 4 \fImc\fP The cursor to operate on\&. .RE .PP .SS "int mdb_cursor_put (\fBMDB_cursor\fP *cursor, \fBMDB_val\fP *key, \fBMDB_val\fP *data, unsigned intflags)" .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 intflags)" .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_open (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, \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 "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 "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 "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 "\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 "static void mdb_cursor_copy (const \fBMDB_cursor\fP *csrc, \fBMDB_cursor\fP *cdst)\fC [static]\fP" Copy the contents of a cursor\&. .PP \fBParameters:\fP .RS 4 \fIcsrc\fP The cursor to copy from\&. .br \fIcdst\fP The cursor to copy to\&. .RE .PP .SS "int mdb_del (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, \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_put (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, \fBMDB_val\fP *key, \fBMDB_val\fP *data, unsigned intflags)" .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 "static THREAD_RET \fBESECT\fP CALL_CONV mdb_env_copythr (void *arg)\fC [static]\fP" Dedicated writer thread for compacting copy\&. .SS "static int \fBESECT\fP mdb_env_cthr_toggle (\fBmdb_copy\fP *my, intst)\fC [static]\fP" Tell the writer thread there's a buffer ready to write .SS "static int \fBESECT\fP mdb_env_cwalk (\fBmdb_copy\fP *my, \fBpgno_t\fP *pg, intflags)\fC [static]\fP" Depth-first tree traversal for compacting copy\&. .SS "static int \fBESECT\fP mdb_env_copyfd1 (\fBMDB_env\fP *env, \fBHANDLE\fPfd)\fC [static]\fP" Copy environment with compaction\&. .SS "static int \fBESECT\fP mdb_env_copyfd0 (\fBMDB_env\fP *env, \fBHANDLE\fPfd)\fC [static]\fP" Copy environment as-is\&. .SS "int \fBESECT\fP mdb_env_copy2 (\fBMDB_env\fP *env, const char *path, unsigned intflags)" .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\&. .PP .RE .PP \fBReturns:\fP .RS 4 A non-zero error value on failure and 0 on success\&. .RE .PP .SS "int \fBESECT\fP 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 \fBESECT\fP mdb_env_set_flags (\fBMDB_env\fP *env, unsigned intflags, intonoff)" .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 \fBESECT\fP 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 \fBESECT\fP 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* \fBESECT\fP 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 \fBESECT\fP 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 \fBESECT\fP 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 \fBESECT\fP mdb_env_get_fd (\fBMDB_env\fP *env, \fBmdb_filehandle_t\fP *fd)" .PP Return the filedescriptor for the given environment\&. .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 "static int \fBESECT\fP mdb_stat0 (\fBMDB_env\fP *env, \fBMDB_db\fP *db, \fBMDB_stat\fP *arg)\fC [static]\fP" Common code for \fBmdb_stat()\fP and \fBmdb_env_stat()\fP\&. .PP \fBParameters:\fP .RS 4 \fIenv\fP the environment to operate in\&. .br \fIdb\fP the \fBMDB_db\fP record containing the stats to return\&. .br \fIarg\fP the address of an \fBMDB_stat\fP structure to receive the stats\&. .RE .PP \fBReturns:\fP .RS 4 0, this function always succeeds\&. .RE .PP .SS "int \fBESECT\fP 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 \fBESECT\fP 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_dbi_open (\fBMDB_txn\fP *txn, const char *name, unsigned intflags, \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 and \fBMDB_NEXT_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 \fBESECT\fP mdb_stat (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, \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 "void mdb_dbi_close (\fBMDB_env\fP *env, \fBMDB_dbi\fPdbi)" .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_dbi_flags (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, 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 "int mdb_drop (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, intdel)" .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\fPdbi, \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\fPdbi, \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\fPdbi, \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\&. .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: .RE .PP .RE .PP .PD 0 .IP "\(bu" 2 EINVAL - an invalid parameter was specified\&. .PP .SS "int mdb_set_relctx (\fBMDB_txn\fP *txn, \fBMDB_dbi\fPdbi, 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 \fBESECT\fP 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 \fBESECT\fP 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 "static int \fBESECT\fP mdb_pid_insert (MDB_PID_T *ids, MDB_PID_Tpid)\fC [static]\fP" Insert pid into list if not already present\&. return -1 if already present\&. .SS "int \fBESECT\fP 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 "Variable Documentation" .PP .SS "char* const mdb_errstr[]\fC [static]\fP" \fBInitial value:\fP .PP .nf = { "MDB_KEYEXIST: Key/data pair already exists", "MDB_NOTFOUND: No matching key/data pair found", "MDB_PAGE_NOTFOUND: Requested page not found", "MDB_CORRUPTED: Located page was wrong type", "MDB_PANIC: Update of meta page failed or environment had fatal error", "MDB_VERSION_MISMATCH: Database environment version mismatch", "MDB_INVALID: File is not an LMDB file", "MDB_MAP_FULL: Environment mapsize limit reached", "MDB_DBS_FULL: Environment maxdbs limit reached", "MDB_READERS_FULL: Environment maxreaders limit reached", "MDB_TLS_FULL: Thread-local storage keys full - too many environments open", "MDB_TXN_FULL: Transaction has too many dirty pages - transaction too big", "MDB_CURSOR_FULL: Internal error - cursor stack limit reached", "MDB_PAGE_FULL: Internal error - page has no more space", "MDB_MAP_RESIZED: Database contents grew beyond environment mapsize", "MDB_INCOMPATIBLE: Operation and DB incompatible, or DB flags changed", "MDB_BAD_RSLOT: Invalid reuse of reader locktable slot", "MDB_BAD_TXN: Transaction must abort, has a child, or is invalid", "MDB_BAD_VALSIZE: Unsupported size of key/DB name/data, or wrong DUPFIXED size", "MDB_BAD_DBI: The specified DBI handle was closed/changed unexpectedly", } .fi Table of descriptions for LMDB \fBReturn Codes\fP .SH "Author" .PP Generated automatically by Doxygen for LMDB from the source code\&.