LMDB Internals

Collaboration diagram for LMDB Internals:

Topics
	Compatibility Macros
	Debug Macros
	Reader Lock Table
	Page Flags
	Node Flags
	Transaction DB Flags
	Transaction Flags
	Cursor Flags
	ID List Management

Classes
struct	MDB_page
struct	MDB_node
struct	MDB_db
struct	MDB_meta
union	MDB_metabuf
struct	MDB_dbx
struct	MDB_txn
struct	MDB_cursor
struct	MDB_xcursor
struct	MDB_pgstate
struct	MDB_env
struct	MDB_ntxn
struct	MDB_name
struct	mdb_copy

Macros
#define	LOCK_MUTEX(rc, env, mutex)
#define	mdb_mutex_failed(env, mutex, rc)
#define	MDB_DSYNC   O_SYNC
#define	MDB_FDATASYNC   fdatasync
#define	MDB_MSYNC(addr, len, flags)
#define	MS_SYNC   1
#define	MS_ASYNC   0
#define	MAX_PAGESIZE   (PAGEBASE ? 0x10000 : 0x8000)
	The maximum size of a database page.
#define	MDB_MINKEYS   2
#define	MDB_MAGIC   0xBEEFC0DE
#define	MDB_DATA_VERSION   ((MDB_DEVEL) ? 999 : 1)
#define	MDB_LOCK_VERSION   ((MDB_DEVEL) ? 999 : 2)
#define	MDB_LOCK_VERSION_BITS   12
#define	MDB_MAXKEYSIZE   ((MDB_DEVEL) ? 0 : 511)
	The max size of a key we can write, or 0 for computed max.
#define	ENV_MAXKEY(env)
#define	MAXDATASIZE   0xffffffffUL
	The maximum size of a data item.
#define	DKBUF
#define	DKEY(x)
#define	P_INVALID   (~(pgno_t)0)
#define	F_ISSET(w, f)
#define	EVEN(n)
#define	LOW_BIT(n)
#define	LOG2_MOD(p2, n)
#define	ALIGNOF2(type)
#define	DEFAULT_MAPSIZE   1048576
#define	PAGEHDRSZ   ((unsigned) offsetof(MDB_page, mp_ptrs))
#define	METADATA(p)
#define	PAGEBASE   ((MDB_DEVEL) ? PAGEHDRSZ : 0)
#define	NUMKEYS(p)
#define	SIZELEFT(p)
#define	PAGEFILL(env, p)
#define	FILL_THRESHOLD   250
#define	IS_LEAF(p)
#define	IS_LEAF2(p)
#define	IS_BRANCH(p)
#define	IS_OVERFLOW(p)
#define	IS_SUBP(p)
#define	OVPAGES(size, psize)
#define	NEXT_LOOSE_PAGE(p)
#define	NODESIZE   offsetof(MDB_node, mn_data)
#define	PGNO_TOPWORD   ((pgno_t)-1 > 0xffffffffu ? 32 : 0)
#define	INDXSIZE(k)
#define	LEAFSIZE(k, d)
#define	NODEPTR(p, i)
#define	NODEKEY(node)
#define	NODEDATA(node)
#define	NODEPGNO(node)
#define	SETPGNO(node, pgno)
#define	NODEDSZ(node)
#define	SETDSZ(node, size)
#define	NODEKSZ(node)
#define	COPY_PGNO(dst, src)
#define	LEAF2KEY(p, i, ks)
#define	MDB_GET_KEY(node, keyptr)
#define	MDB_GET_KEY2(node, key)
#define	MDB_VALID   0x8000
#define	PERSISTENT_FLAGS   (0xffff & ~(MDB_VALID))
#define	VALID_FLAGS
#define	FREE_DBI   0
#define	MAIN_DBI   1
#define	CORE_DBS   2
#define	NUM_METAS   2
#define	CURSOR_STACK   32
#define	XCURSOR_INITED(mc)
#define	XCURSOR_REFRESH(mc, top, mp)
#define	MDB_COMMIT_PAGES   64
#define	MAX_WRITE   (0x40000000U >> (sizeof(ssize_t) == 4))
#define	TXN_DBI_EXIST(txn, dbi, validity)
#define	TXN_DBI_CHANGED(txn, dbi)
#define	MDB_END_NAMES
#define	MDB_END_OPMASK   0x0F
#define	MDB_END_UPDATE   0x10
#define	MDB_END_FREE   0x20
#define	MDB_END_SLOT   MDB_NOTLS
#define	MDB_PS_MODIFY   1
#define	MDB_PS_ROOTONLY   2
#define	MDB_PS_FIRST   4
#define	MDB_PS_LAST   8
#define	MDB_SPLIT_REPLACE   MDB_APPENDDUP
#define	mdb_env_close0(env, excl)
#define	mdb_cmp_clong   mdb_cmp_cint
#define	NEED_CMP_CLONG(cmp, ksize)
#define	mdb_cassert(mc, expr)
#define	mdb_tassert(txn, expr)
#define	mdb_eassert(env, expr)
#define	mdb_assert0(env, expr, expr_txt)
#define	MDB_PAGE_UNREF(txn, mp)
#define	MDB_CURSOR_UNREF(mc, force)
#define	MDB_NAME(str)
#define	mdb_name_cpy   strcpy
#define	MDB_SUFFLEN   9
#define	mdb_fname_destroy(fname)
#define	MDB_CLOEXEC   0
#define	CHANGEABLE   (MDB_NOSYNC|MDB_NOMETASYNC|MDB_MAPASYNC|MDB_NOMEMINIT)
#define	CHANGELESS
#define	MDB_NOSPILL   0x8000
#define	WITH_CURSOR_TRACKING(mn, act)
#define	MDB_WBUF   (1024*1024)
#define	MDB_EOF   0x10

Typedefs
typedef MDB_ID	pgno_t
typedef MDB_ID	txnid_t
typedef uint16_t	indx_t
typedef unsigned long long	mdb_hash_t
typedef struct MDB_page	MDB_page
typedef struct MDB_node	MDB_node
typedef struct MDB_db	MDB_db
typedef struct MDB_meta	MDB_meta
typedef union MDB_metabuf	MDB_metabuf
typedef struct MDB_dbx	MDB_dbx
typedef struct MDB_xcursor	MDB_xcursor
typedef struct MDB_pgstate	MDB_pgstate
typedef struct MDB_ntxn	MDB_ntxn
typedef char	mdb_nchar_t
typedef struct MDB_name	MDB_name
typedef struct mdb_copy	mdb_copy

Enumerations
enum	{   MDB_END_COMMITTED , MDB_END_EMPTY_COMMIT , MDB_END_ABORT , MDB_END_RESET ,   MDB_END_RESET_TMP , MDB_END_FAIL_BEGIN , MDB_END_FAIL_BEGINCHILD }
enum	Pidlock_op { Pidset , Pidcheck }
enum	mdb_fopen_type {   MDB_O_RDONLY = O_RDONLY , MDB_O_RDWR = O_RDWR |O_CREAT , MDB_O_META = O_WRONLY|MDB_DSYNC |MDB_CLOEXEC , MDB_O_COPY = O_WRONLY|O_CREAT|O_EXCL|MDB_CLOEXEC ,   MDB_O_MASK = MDB_O_RDWR|MDB_CLOEXEC | MDB_O_RDONLY|MDB_O_META|MDB_O_COPY , MDB_O_LOCKS = MDB_O_RDWR|MDB_CLOEXEC | ((MDB_O_MASK+1) & ~MDB_O_MASK) }

Functions
static int	mdb_page_alloc (MDB_cursor *mc, int num, MDB_page **mp)
static int	mdb_page_new (MDB_cursor *mc, uint32_t flags, int num, MDB_page **mp)
static int	mdb_page_touch (MDB_cursor *mc)
static void	mdb_txn_end (MDB_txn *txn, unsigned mode)
static int	mdb_page_get (MDB_cursor *mc, pgno_t pgno, MDB_page **mp, int *lvl)
static int	mdb_page_search_root (MDB_cursor *mc, MDB_val *key, int modify)
static int	mdb_page_search (MDB_cursor *mc, MDB_val *key, int flags)
static int	mdb_page_merge (MDB_cursor *csrc, MDB_cursor *cdst)
static int	mdb_page_split (MDB_cursor *mc, MDB_val *newkey, MDB_val *newdata, pgno_t newpgno, unsigned int nflags)
static int	mdb_env_read_header (MDB_env *env, int prev, MDB_meta *meta)
static MDB_meta *	mdb_env_pick_meta (const MDB_env *env)
static int	mdb_env_write_meta (MDB_txn *txn)
static void	mdb_env_close0 (MDB_env *env, int excl)
static MDB_node *	mdb_node_search (MDB_cursor *mc, MDB_val *key, int *exactp)
static int	mdb_node_add (MDB_cursor *mc, indx_t indx, MDB_val *key, MDB_val *data, pgno_t pgno, unsigned int flags)
static void	mdb_node_del (MDB_cursor *mc, int ksize)
static void	mdb_node_shrink (MDB_page *mp, indx_t indx)
static int	mdb_node_move (MDB_cursor *csrc, MDB_cursor *cdst, int fromleft)
static int	mdb_node_read (MDB_cursor *mc, MDB_node *leaf, MDB_val *data)
static size_t	mdb_leaf_size (MDB_env *env, MDB_val *key, MDB_val *data)
static size_t	mdb_branch_size (MDB_env *env, MDB_val *key)
static int	mdb_rebalance (MDB_cursor *mc)
static int	mdb_update_key (MDB_cursor *mc, MDB_val *key)
static void	mdb_cursor_pop (MDB_cursor *mc)
static int	mdb_cursor_push (MDB_cursor *mc, MDB_page *mp)
static int	mdb_cursor_del0 (MDB_cursor *mc)
static int	mdb_del0 (MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data, unsigned flags)
static int	mdb_cursor_sibling (MDB_cursor *mc, int move_right)
static int	mdb_cursor_next (MDB_cursor *mc, MDB_val *key, MDB_val *data, MDB_cursor_op op)
static int	mdb_cursor_prev (MDB_cursor *mc, MDB_val *key, MDB_val *data, MDB_cursor_op op)
static int	mdb_cursor_set (MDB_cursor *mc, MDB_val *key, MDB_val *data, MDB_cursor_op op, int *exactp)
static int	mdb_cursor_first (MDB_cursor *mc, MDB_val *key, MDB_val *data)
static int	mdb_cursor_last (MDB_cursor *mc, MDB_val *key, MDB_val *data)
static void	mdb_cursor_init (MDB_cursor *mc, MDB_txn *txn, MDB_dbi dbi, MDB_xcursor *mx)
static void	mdb_xcursor_init0 (MDB_cursor *mc)
static void	mdb_xcursor_init1 (MDB_cursor *mc, MDB_node *node)
static void	mdb_xcursor_init2 (MDB_cursor *mc, MDB_xcursor *src_mx, int force)
static int	mdb_drop0 (MDB_cursor *mc, int subs)
static void	mdb_default_cmp (MDB_txn *txn, MDB_dbi dbi)
static int	mdb_reader_check0 (MDB_env *env, int rlocked, int *dead)
char *ESECT	mdb_version (int *major, int *minor, int *patch)
	Return the LMDB library version information.
char *	mdb_strerror (int err)
	Return a string describing a given error code.
static void ESECT	mdb_assert_fail (MDB_env *env, const char *expr_txt, const char *func, const char *file, int line)
int	mdb_cmp (MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b)
	Compare two data items according to a particular database.
int	mdb_dcmp (MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b)
	Compare two data items according to a particular database.
static MDB_page *	mdb_page_malloc (MDB_txn *txn, unsigned num)
static void	mdb_page_free (MDB_env *env, MDB_page *mp)
static void	mdb_dpage_free (MDB_env *env, MDB_page *dp)
static void	mdb_dlist_free (MDB_txn *txn)
static int	mdb_page_loose (MDB_cursor *mc, MDB_page *mp)
static int	mdb_pages_xkeep (MDB_cursor *mc, unsigned pflags, int all)
static int	mdb_page_flush (MDB_txn *txn, int keep)
static int	mdb_page_spill (MDB_cursor *m0, MDB_val *key, MDB_val *data)
static txnid_t	mdb_find_oldest (MDB_txn *txn)
static void	mdb_page_dirty (MDB_txn *txn, MDB_page *mp)
static void	mdb_page_copy (MDB_page *dst, MDB_page *src, unsigned int psize)
static int	mdb_page_unspill (MDB_txn *txn, MDB_page *mp, MDB_page **ret)
int	mdb_env_sync0 (MDB_env *env, int force, pgno_t numpgs)
int	mdb_env_sync (MDB_env *env, int force)
	Flush the data buffers to disk.
static int	mdb_cursor_shadow (MDB_txn *src, MDB_txn *dst)
static void	mdb_cursors_close (MDB_txn *txn, unsigned merge)
static int	mdb_reader_pid (MDB_env *env, enum Pidlock_op op, MDB_PID_T pid)
static int	mdb_txn_renew0 (MDB_txn *txn)
int	mdb_txn_renew (MDB_txn *txn)
	Renew a read-only transaction.
int	mdb_txn_begin (MDB_env *env, MDB_txn *parent, unsigned int flags, MDB_txn **ret)
	Create a transaction for use with the environment.
MDB_env *	mdb_txn_env (MDB_txn *txn)
	Returns the transaction's MDB_env.
mdb_size_t	mdb_txn_id (MDB_txn *txn)
	Return the transaction's ID.
static void	mdb_dbis_update (MDB_txn *txn, int keep)
void	mdb_txn_reset (MDB_txn *txn)
	Reset a read-only transaction.
void	mdb_txn_abort (MDB_txn *txn)
	Abandon all the operations of the transaction instead of saving them.
static int	mdb_freelist_save (MDB_txn *txn)
static int ESECT	mdb_env_share_locks (MDB_env *env, int *excl)
int	mdb_txn_commit (MDB_txn *txn)
	Commit all the operations of a transaction into the database.
static int ESECT	mdb_env_map (MDB_env *env, void *addr)
static void ESECT	mdb_env_init_meta0 (MDB_env *env, MDB_meta *meta)
static int ESECT	mdb_env_init_meta (MDB_env *env, MDB_meta *meta)
int ESECT	mdb_env_create (MDB_env **env)
	Create an LMDB environment handle.
int ESECT	mdb_env_set_mapsize (MDB_env *env, mdb_size_t size)
	Set the size of the memory map to use for this environment.
int ESECT	mdb_env_set_maxdbs (MDB_env *env, MDB_dbi dbs)
	Set the maximum number of named databases for the environment.
int ESECT	mdb_env_set_maxreaders (MDB_env *env, unsigned int readers)
	Set the maximum number of threads/reader slots for the environment.
int ESECT	mdb_env_get_maxreaders (MDB_env *env, unsigned int *readers)
	Get the maximum number of threads/reader slots for the environment.
static int ESECT	mdb_fsize (HANDLE fd, mdb_size_t *size)
static int ESECT	mdb_fname_init (const char *path, unsigned envflags, MDB_name *fname)
static int ESECT	mdb_fopen (const MDB_env *env, MDB_name *fname, enum mdb_fopen_type which, mdb_mode_t mode, HANDLE *res)
static int ESECT	mdb_env_open2 (MDB_env *env, int prev)
static void	mdb_env_reader_dest (void *ptr)
static int ESECT	mdb_env_excl_lock (MDB_env *env, int *excl)
static int ESECT	mdb_env_setup_locks (MDB_env *env, MDB_name *fname, int mode, int *excl)
int ESECT	mdb_env_open (MDB_env *env, const char *path, unsigned int flags, mdb_mode_t mode)
	Open an environment handle.
void ESECT	mdb_env_close (MDB_env *env)
	Close the environment and release the memory map.
static int	mdb_cmp_long (const MDB_val *a, const MDB_val *b)
static int	mdb_cmp_int (const MDB_val *a, const MDB_val *b)
static int	mdb_cmp_cint (const MDB_val *a, const MDB_val *b)
static int	mdb_cmp_memn (const MDB_val *a, const MDB_val *b)
static int	mdb_cmp_memnr (const MDB_val *a, const MDB_val *b)
static int	mdb_page_search_lowest (MDB_cursor *mc)
static int	mdb_ovpage_free (MDB_cursor *mc, MDB_page *mp)
int	mdb_get (MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data)
	Get items from a database.
int	mdb_cursor_get (MDB_cursor *mc, MDB_val *key, MDB_val *data, MDB_cursor_op op)
	Retrieve by cursor.
static int	mdb_cursor_touch (MDB_cursor *mc)
int	mdb_cursor_put (MDB_cursor *mc, MDB_val *key, MDB_val *data, unsigned int flags)
	Store by cursor.
int	mdb_cursor_del (MDB_cursor *mc, unsigned int flags)
	Delete current key/data pair.
int	mdb_cursor_open (MDB_txn *txn, MDB_dbi dbi, MDB_cursor **ret)
	Create a cursor handle.
int	mdb_cursor_renew (MDB_txn *txn, MDB_cursor *mc)
	Renew a cursor handle.
int	mdb_cursor_count (MDB_cursor *mc, mdb_size_t *countp)
	Return count of duplicates for current key.
void	mdb_cursor_close (MDB_cursor *mc)
	Close a cursor handle.
MDB_txn *	mdb_cursor_txn (MDB_cursor *mc)
	Return the cursor's transaction handle.
MDB_dbi	mdb_cursor_dbi (MDB_cursor *mc)
	Return the cursor's database handle.
static void	mdb_cursor_copy (const MDB_cursor *csrc, MDB_cursor *cdst)
int	mdb_del (MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data)
	Delete items from a database.
int	mdb_put (MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data, unsigned int flags)
	Store items into a database.
static THREAD_RET ESECT CALL_CONV	mdb_env_copythr (void *arg)
static int ESECT	mdb_env_cthr_toggle (mdb_copy *my, int adjust)
static int ESECT	mdb_env_cwalk (mdb_copy *my, pgno_t *pg, int flags)
static int ESECT	mdb_env_copyfd1 (MDB_env *env, HANDLE fd)
static int ESECT	mdb_env_copyfd0 (MDB_env *env, HANDLE fd)
int ESECT	mdb_env_copyfd2 (MDB_env *env, HANDLE fd, unsigned int flags)
int ESECT	mdb_env_copyfd (MDB_env *env, HANDLE fd)
int ESECT	mdb_env_copy2 (MDB_env *env, const char *path, unsigned int flags)
	Copy an LMDB environment to the specified path, with options.
int ESECT	mdb_env_copy (MDB_env *env, const char *path)
	Copy an LMDB environment to the specified path.
int ESECT	mdb_env_set_flags (MDB_env *env, unsigned int flag, int onoff)
	Set environment flags.
int ESECT	mdb_env_get_flags (MDB_env *env, unsigned int *arg)
	Get environment flags.
int ESECT	mdb_env_set_userctx (MDB_env *env, void *ctx)
	Set application information associated with the MDB_env.
void *ESECT	mdb_env_get_userctx (MDB_env *env)
	Get the application information associated with the MDB_env.
int ESECT	mdb_env_set_assert (MDB_env *env, MDB_assert_func *func)
int ESECT	mdb_env_get_path (MDB_env *env, const char **arg)
	Return the path that was used in mdb_env_open().
int ESECT	mdb_env_get_fd (MDB_env *env, mdb_filehandle_t *arg)
	Return the filedescriptor for the given environment.
static int ESECT	mdb_stat0 (MDB_env *env, MDB_db *db, MDB_stat *arg)
int ESECT	mdb_env_stat (MDB_env *env, MDB_stat *arg)
	Return statistics about the LMDB environment.
int ESECT	mdb_env_info (MDB_env *env, MDB_envinfo *arg)
	Return information about the LMDB environment.
int	mdb_dbi_open (MDB_txn *txn, const char *name, unsigned int flags, MDB_dbi *dbi)
	Open a database in the environment.
int ESECT	mdb_stat (MDB_txn *txn, MDB_dbi dbi, MDB_stat *arg)
	Retrieve statistics for a database.
void	mdb_dbi_close (MDB_env *env, MDB_dbi dbi)
	Close a database handle. Normally unnecessary. Use with care:
int	mdb_dbi_flags (MDB_txn *txn, MDB_dbi dbi, unsigned int *flags)
	Retrieve the DB flags for a database handle.
int	mdb_drop (MDB_txn *txn, MDB_dbi dbi, int del)
	Empty or delete+close a database.
int	mdb_set_compare (MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp)
	Set a custom key comparison function for a database.
int	mdb_set_dupsort (MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp)
	Set a custom data comparison function for a MDB_DUPSORT database.
int	mdb_set_relfunc (MDB_txn *txn, MDB_dbi dbi, MDB_rel_func *rel)
	Set a relocation function for a MDB_FIXEDMAP database.
int	mdb_set_relctx (MDB_txn *txn, MDB_dbi dbi, void *ctx)
	Set a context pointer for a MDB_FIXEDMAP database's relocation function.
int ESECT	mdb_env_get_maxkeysize (MDB_env *env)
	Get the maximum size of keys and MDB_DUPSORT data we can write.
int ESECT	mdb_reader_list (MDB_env *env, MDB_msg_func *func, void *ctx)
	Dump the entries in the reader lock table.
static int ESECT	mdb_pid_insert (MDB_PID_T *ids, MDB_PID_T pid)
int ESECT	mdb_reader_check (MDB_env *env, int *dead)
	Check for stale entries in the reader lock table.

Variables
static char *const	mdb_errstr []
static const mdb_nchar_t *const	mdb_suffixes [2][2]

Detailed Description

Macro Definition Documentation

ALIGNOF2

#define ALIGNOF2

(

type

)

Value:

LOW_BIT(offsetof(struct { char ch_; type align_; }, align_))

Should be alignment of type. Ensure it is a power of 2.

CHANGEABLE

#define CHANGEABLE   (MDB_NOSYNC|MDB_NOMETASYNC|MDB_MAPASYNC|MDB_NOMEMINIT)

Only a subset of the Environment Flags flags can be changed at runtime. Changing other flags requires closing the environment and re-opening it with the new flags.

CHANGELESS

#define CHANGELESS

Value:

(MDB_FIXEDMAP|MDB_NOSUBDIR|MDB_RDONLY| \
MDB_WRITEMAP|MDB_NOTLS|MDB_NOLOCK|MDB_NORDAHEAD|MDB_PREVSNAPSHOT)

COPY_PGNO

#define COPY_PGNO	(		dst,
			src )

Value:

    do { \
    unsigned short *s, *d;  \
    s = (unsigned short *)&(src);   \
    d = (unsigned short *)&(dst);   \
    *d++ = *s++;    \
    *d = *s;    \
} while (0)

Copy a page number from src to dst

CORE_DBS

#define CORE_DBS   2

Number of DBs in metapage (free and main) - also hardcoded elsewhere

CURSOR_STACK

#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.

DEFAULT_MAPSIZE

#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 mdb_env_set_mapsize().

DKBUF

#define DKBUF

DKEY

#define DKEY

(

x

)

Value:

0

ENV_MAXKEY

#define ENV_MAXKEY

(

env

)

Value:

((env)->me_maxkey)

The maximum size of a key we can write to the environment.

EVEN

#define EVEN

(

n

)

Value:

(((n) + 1U) & -2) /* sign-extending -2 to match n+1U */

Round n up to an even number.

F_ISSET

#define F_ISSET	(		w,
			f )

Value:

(((w) & (f)) == (f))

Test if the flags f are set in a flag word w.

FILL_THRESHOLD

#define FILL_THRESHOLD   250

The minimum page fill factor, in tenths of a percent. Pages emptier than this are candidates for merging.

FREE_DBI

#define FREE_DBI   0

Handle for the DB used to track free pages.

INDXSIZE

#define INDXSIZE

(

k

)

Value:

(NODESIZE + ((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.

IS_BRANCH

#define IS_BRANCH

(

p

)

Value:

F_ISSET((p)->mp_flags, P_BRANCH)

Test if a page is a branch page

IS_LEAF

#define IS_LEAF

(

p

)

Value:

F_ISSET((p)->mp_flags, P_LEAF)

Test if a page is a leaf page

IS_LEAF2

#define IS_LEAF2

(

p

)

Value:

F_ISSET((p)->mp_flags, P_LEAF2)

Test if a page is a LEAF2 page

IS_OVERFLOW

#define IS_OVERFLOW

(

p

)

Value:

F_ISSET((p)->mp_flags, P_OVERFLOW)

Test if a page is an overflow page

IS_SUBP

#define IS_SUBP

(

p

)

Value:

F_ISSET((p)->mp_flags, P_SUBP)

Test if a page is a sub page

LEAF2KEY

#define LEAF2KEY	(		p,
			i,
			ks )

Value:

((char *)(p) + PAGEHDRSZ + ((i)*(ks)))

The address of a key in a LEAF2 page. LEAF2 pages are used for MDB_DUPFIXED sorted-duplicate sub-DBs. There are no node headers, keys are stored contiguously.

LEAFSIZE

#define LEAFSIZE	(		k,
			d )

Value:

(NODESIZE + (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.

LOCK_MUTEX

#define LOCK_MUTEX	(		rc,
			env,
			mutex )

Value:

((rc) = LOCK_MUTEX0(mutex))

Initial part of #MDB_env.me_mutexname[]. Changes to this code must be reflected in MDB_LOCK_FORMAT.

LOG2_MOD

#define LOG2_MOD	(		p2,
			n )

Value:

(7 - 86 / ((p2) % ((1U<<(n))-1) + 11))

(log2(p2) % n), for p2 = power of 2 and 0 < n < 8.

LOW_BIT

#define LOW_BIT

(

n

)

Value:

((n) & (-(n)))

Least significant 1-bit of n. n must be of an unsigned type.

MAIN_DBI

#define MAIN_DBI   1

Handle for the default DB.

MAX_PAGESIZE

#define MAX_PAGESIZE   (PAGEBASE ? 0x10000 : 0x8000)

The maximum size of a database page.

It is 32k or 64k, since value-PAGEBASE must fit in MDB_page.mp_upper.

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.

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.

MAX_WRITE

#define MAX_WRITE   (0x40000000U >> (sizeof(ssize_t) == 4))

max bytes to write in one call

MAXDATASIZE

#define MAXDATASIZE   0xffffffffUL

The maximum size of a data item.

We only store a 32 bit value for node sizes.

mdb_assert0

#define mdb_assert0	(		env,
			expr,
			expr_txt )

Value:

((expr) ? (void)0 : \
mdb_assert_fail(env, expr_txt, mdb_func_, __FILE__, __LINE__))

mdb_cassert

#define mdb_cassert	(		mc,
			expr )

Value:

mdb_assert0((mc)->mc_txn->mt_env, expr, #expr)

assert(3) variant in cursor context

MDB_CLOEXEC

#define MDB_CLOEXEC   0

mdb_cmp_clong

#define mdb_cmp_clong   mdb_cmp_cint

Compare two items pointing at 'mdb_size_t's of unknown alignment.

MDB_COMMIT_PAGES

#define MDB_COMMIT_PAGES   64

max number of pages to commit in one writev() call

MDB_CURSOR_UNREF

#define MDB_CURSOR_UNREF	(		mc,
			force )

Value:

((void)0)

MDB_DATA_VERSION

#define MDB_DATA_VERSION   ((MDB_DEVEL) ? 999 : 1)

The version number for a database's datafile format.

MDB_DSYNC

#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.

Note

If O_DSYNC is undefined but exists in /usr/include, preferably set some compiler flag to get the definition.

mdb_eassert

#define mdb_eassert	(		env,
			expr )

Value:

mdb_assert0(env, expr, #expr)

assert(3) variant in environment context

MDB_END_FREE

#define MDB_END_FREE   0x20

free txn unless it is MDB_env.me_txn0

MDB_END_NAMES

#define MDB_END_NAMES

Value:

{"committed", "empty-commit", "abort", "reset", \
"reset-tmp", "fail-begin", "fail-beginchild"}

MDB_END_OPMASK

#define MDB_END_OPMASK   0x0F

mask for mdb_txn_end() operation number

MDB_END_SLOT

#define MDB_END_SLOT   MDB_NOTLS

release any reader slot if MDB_NOTLS

MDB_END_UPDATE

#define MDB_END_UPDATE   0x10

update env state (DBIs)

mdb_env_close0

#define mdb_env_close0	(		env,
			excl )

Value:

mdb_env_close1(env)

MDB_EOF

#define MDB_EOF   0x10

mdb_env_copyfd1() is done reading

MDB_FDATASYNC

#define MDB_FDATASYNC   fdatasync

Function for flushing the data of a file. Define this to fsync if fdatasync() is not supported.

mdb_fname_destroy

#define mdb_fname_destroy

(

fname

)

Value:

do { if ((fname).mn_alloced) free((fname).mn_val); } while (0)

Destroy fname from mdb_fname_init()

MDB_GET_KEY

#define MDB_GET_KEY	(		node,
			keyptr )

Value:

{ if ((keyptr) != NULL) { \
(keyptr)->mv_size = NODEKSZ(node); (keyptr)->mv_data = NODEKEY(node); } }

Set the node's key into keyptr, if requested.

MDB_GET_KEY2

#define MDB_GET_KEY2	(		node,
			key )

Value:

{ key.mv_size = NODEKSZ(node); key.mv_data = NODEKEY(node); }

Set the node's key into key.

MDB_LOCK_VERSION

#define MDB_LOCK_VERSION   ((MDB_DEVEL) ? 999 : 2)

The version number for a database's lockfile format.

MDB_LOCK_VERSION_BITS

#define MDB_LOCK_VERSION_BITS   12

Number of bits representing MDB_LOCK_VERSION in MDB_LOCK_FORMAT. The remaining bits must leave room for MDB_lock_desc.

MDB_MAGIC

#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.

MDB_MAXKEYSIZE

#define MDB_MAXKEYSIZE   ((MDB_DEVEL) ? 0 : 511)

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 MDB_DEVEL.

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.

Data items in an MDB_DUPSORT database are also limited to this size, since they're actually keys of a sub-DB. Keys and MDB_DUPSORT data items must fit on a node in a regular page.

MDB_MINKEYS

#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.

MDB_MSYNC

#define MDB_MSYNC	(		addr,
			len,
			flags )

Value:

msync(addr,len,flags)

mdb_mutex_failed

#define mdb_mutex_failed	(		env,
			mutex,
			rc )

Value:

(rc)

MDB_NAME

#define MDB_NAME

(

str

)

Value:

str

mdb_nchar_t[] string literal

mdb_name_cpy

#define mdb_name_cpy   strcpy

Copy name (mdb_nchar_t string)

MDB_NOSPILL

#define MDB_NOSPILL   0x8000

Do not spill pages to disk if txn is getting full, may fail instead

MDB_PAGE_UNREF

#define MDB_PAGE_UNREF	(		txn,
			mp )

MDB_PS_FIRST

#define MDB_PS_FIRST   4

MDB_PS_LAST

#define MDB_PS_LAST   8

MDB_PS_MODIFY

#define MDB_PS_MODIFY   1

MDB_PS_ROOTONLY

#define MDB_PS_ROOTONLY   2

MDB_SPLIT_REPLACE

#define MDB_SPLIT_REPLACE   MDB_APPENDDUP

newkey is not new

MDB_SUFFLEN

#define MDB_SUFFLEN   9

Max string length in mdb_suffixes[]

mdb_tassert

#define mdb_tassert	(		txn,
			expr )

Value:

mdb_assert0((txn)->mt_env, expr, #expr)

assert(3) variant in transaction context

MDB_VALID

#define MDB_VALID   0x8000

DB handle is valid, for me_dbflags

MDB_WBUF

#define MDB_WBUF   (1024*1024)

METADATA

#define METADATA

(

p

)

Value:

((void *)((char *)(p) + PAGEHDRSZ))

Address of first usable data byte in a page, after the header

MS_ASYNC

#define MS_ASYNC   0

MS_SYNC

#define MS_SYNC   1

NEED_CMP_CLONG

#define NEED_CMP_CLONG	(		cmp,
			ksize )

Value:

(UINT_MAX < MDB_SIZE_MAX && \
 (cmp) == mdb_cmp_int && (ksize) == sizeof(mdb_size_t))

True if we need mdb_cmp_clong() instead of cmp for MDB_INTEGERDUP

NEXT_LOOSE_PAGE

#define NEXT_LOOSE_PAGE

(

p

)

Value:

(*(MDB_page **)((p) + 2))

Link in MDB_txn.mt_loose_pgs list. Kept outside the page header, which is needed when reusing the page.

NODEDATA

#define NODEDATA

(

node

)

Value:

(void *)((char *)(node)->mn_data + (node)->mn_ksize)

Address of the data for a node

NODEDSZ

#define NODEDSZ

(

node

)

Value:

((node)->mn_lo | ((unsigned)(node)->mn_hi << 16))

Get the size of the data in a leaf node

NODEKEY

#define NODEKEY

(

node

)

Value:

(void *)((node)->mn_data)

Address of the key for the node

NODEKSZ

#define NODEKSZ

(

node

)

Value:

((node)->mn_ksize)

The size of a key in a node

NODEPGNO

#define NODEPGNO

(

node

)

Value:

((node)->mn_lo | ((pgno_t) (node)->mn_hi << 16) | \
 (PGNO_TOPWORD ? ((pgno_t) (node)->mn_flags << PGNO_TOPWORD) : 0))

Get the page number pointed to by a branch node

NODEPTR

#define NODEPTR	(		p,
			i )

Value:

((MDB_node *)((char *)(p) + (p)->mp_ptrs[i] + PAGEBASE))

Address of node i in page p

NODESIZE

#define NODESIZE   offsetof(MDB_node, mn_data)

Size of the node header, excluding dynamic data at the end

NUM_METAS

#define NUM_METAS   2

Number of meta pages - also hardcoded elsewhere

NUMKEYS

#define NUMKEYS

(

p

)

Value:

(((p)->mp_lower - (PAGEHDRSZ-PAGEBASE)) >> 1)

Number of nodes on a page

OVPAGES

#define OVPAGES	(		size,
			psize )

Value:

((PAGEHDRSZ-1 + (size)) / (psize) + 1)

The number of overflow pages needed to store the given size.

P_INVALID

#define P_INVALID   (~(pgno_t)0)

An invalid page number. Mainly used to denote an empty tree.

PAGEBASE

#define PAGEBASE   ((MDB_DEVEL) ? PAGEHDRSZ : 0)

ITS#7713, change PAGEBASE to handle 65536 byte pages

PAGEFILL

#define PAGEFILL	(		env,
			p )

Value:

(1000L * ((env)->me_psize - PAGEHDRSZ - SIZELEFT(p)) / \
((env)->me_psize - PAGEHDRSZ))

The percentage of space used in the page, in tenths of a percent.

PAGEHDRSZ

#define PAGEHDRSZ   ((unsigned) offsetof(MDB_page, mp_ptrs))

Size of the page header, excluding dynamic data at the end

PERSISTENT_FLAGS

#define PERSISTENT_FLAGS   (0xffff & ~(MDB_VALID))

PGNO_TOPWORD

#define PGNO_TOPWORD   ((pgno_t)-1 > 0xffffffffu ? 32 : 0)

Bit position of top word in page number, for shifting mn_flags

SETDSZ

#define SETDSZ	(		node,
			size )

Value:

do { \
(node)->mn_lo = (size) & 0xffff; (node)->mn_hi = (size) >> 16;} while(0)

Set the size of the data for a leaf node

SETPGNO

#define SETPGNO	(		node,
			pgno )

Value:

do { \
(node)->mn_lo = (pgno) & 0xffff; (node)->mn_hi = (pgno) >> 16; \
if (PGNO_TOPWORD) (node)->mn_flags = (pgno) >> PGNO_TOPWORD; } while(0)

Set the page number in a branch node

SIZELEFT

#define SIZELEFT

(

p

)

Value:

(indx_t)((p)->mp_upper - (p)->mp_lower)

The amount of space remaining in the page

TXN_DBI_CHANGED

#define TXN_DBI_CHANGED	(		txn,
			dbi )

Value:

((txn)->mt_dbiseqs[dbi] != (txn)->mt_env->me_dbiseqs[dbi])

Check for misused dbi handles

TXN_DBI_EXIST

#define TXN_DBI_EXIST	(		txn,
			dbi,
			validity )

Value:

((txn) && (dbi)<(txn)->mt_numdbs && ((txn)->mt_dbflags[dbi] & (validity)))

Check txn and dbi arguments to a function

VALID_FLAGS

#define VALID_FLAGS

Value:

(MDB_REVERSEKEY|MDB_DUPSORT|MDB_INTEGERKEY|MDB_DUPFIXED|\
MDB_INTEGERDUP|MDB_REVERSEDUP|MDB_CREATE)

mdb_dbi_open() flags

WITH_CURSOR_TRACKING

#define WITH_CURSOR_TRACKING	(		mn,
			act )

Value:

    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)

Perform act while tracking temporary cursor mn

XCURSOR_INITED

#define XCURSOR_INITED

(

mc

)

Value:

((mc)->mc_xcursor && ((mc)->mc_xcursor->mx_cursor.mc_flags & C_INITIALIZED))

Check if there is an inited xcursor

XCURSOR_REFRESH

#define XCURSOR_REFRESH	(		mc,
			top,
			mp )

Value:

    do { \
    MDB_page *xr_pg = (mp); \
    MDB_node *xr_node; \
    if (!XCURSOR_INITED(mc) || (mc)->mc_ki[top] >= NUMKEYS(xr_pg)) break; \
    xr_node = NODEPTR(xr_pg, (mc)->mc_ki[top]); \
    if ((xr_node->mn_flags & (F_DUPDATA|F_SUBDATA)) == F_DUPDATA) \
        (mc)->mc_xcursor->mx_cursor.mc_pg[0] = NODEDATA(xr_node); \
} while (0)

Update the xcursor's sub-page pointer, if any, in mc. Needed when the node which contains the sub-page may have moved. Called with leaf page mp = mc->mc_pg[top].

Typedef Documentation

indx_t

typedef uint16_t indx_t

Used for offsets within a single page. Since memory pages are typically 4 or 8KB in size, 12-13 bits, this is plenty.

mdb_copy

typedef struct mdb_copy mdb_copy

State needed for a double-buffering compacting copy.

MDB_db

typedef struct MDB_db MDB_db

Information about a single database in the environment.

MDB_dbx

typedef struct MDB_dbx MDB_dbx

Auxiliary DB info. The information here is mostly static/read-only. There is only a single copy of this record in the environment.

mdb_hash_t

typedef unsigned long long mdb_hash_t

MDB_meta

typedef struct MDB_meta MDB_meta

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).

MDB_metabuf

typedef union MDB_metabuf MDB_metabuf

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.

MDB_name

typedef struct MDB_name MDB_name

Filename - string of mdb_nchar_t[]

mdb_nchar_t

typedef char mdb_nchar_t

Character type for file names: char on Unix, wchar_t on Windows

MDB_node

typedef struct MDB_node MDB_node

Header for a single key/data pair within a page. Used in pages of type P_BRANCH and P_LEAF without P_LEAF2. We guarantee 2-byte alignment for 'MDB_node's.

#mn_lo and #mn_hi are used for data size on leaf nodes, and for child pgno on branch nodes. On 64 bit platforms, #mn_flags is also used for pgno. (Branch nodes have no flags). Lo and hi are in host byte order in case some accesses can be optimized to 32-bit word access.

Leaf node flags describe node contents. F_BIGDATA says the node's data part is the page number of an overflow page with actual data. F_DUPDATA and F_SUBDATA can be combined giving duplicate data in a sub-page/sub-database, and named databases (just F_SUBDATA).

MDB_ntxn

typedef struct MDB_ntxn MDB_ntxn

Nested transaction

MDB_page

typedef struct MDB_page MDB_page

Common header for all page types. The page type depends on #mp_flags.

P_BRANCH and P_LEAF pages have unsorted 'MDB_node's at the end, with sorted #mp_ptrs[] entries referring to them. Exception: P_LEAF2 pages omit mp_ptrs and pack sorted MDB_DUPFIXED values after the page header.

P_OVERFLOW records occupy one or more contiguous pages where only the first has a page header. They hold the real data of F_BIGDATA nodes.

P_SUBP sub-pages are small leaf "pages" with duplicate data. A node with flag F_DUPDATA but not F_SUBDATA contains a sub-page. (Duplicate data can also go in sub-databases, which use normal pages.)

P_META pages contain MDB_meta, the start point of an LMDB snapshot.

Each non-metapage up to MDB_meta.mm_last_pg is reachable exactly once in the snapshot: Either used by a database or listed in a freeDB record.

MDB_pgstate

typedef struct MDB_pgstate MDB_pgstate

State of FreeDB old pages, stored in the MDB_env

MDB_xcursor

typedef struct MDB_xcursor MDB_xcursor

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.

pgno_t

typedef MDB_ID pgno_t

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.

Note

In the MDB_node structure, we only store 48 bits of this value, which thus limits us to only 60 bits of addressable data.

txnid_t

typedef MDB_ID txnid_t

A transaction ID. See struct MDB_txn.mt_txnid for details.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
MDB_END_COMMITTED
MDB_END_EMPTY_COMMIT
MDB_END_ABORT
MDB_END_RESET
MDB_END_RESET_TMP
MDB_END_FAIL_BEGIN
MDB_END_FAIL_BEGINCHILD

mdb_fopen_type

enum mdb_fopen_type

File type, access mode etc. for mdb_fopen()

Enumerator
MDB_O_RDONLY	for RDONLY me_fd
MDB_O_RDWR	for me_fd
MDB_O_META	for me_mfd
MDB_O_COPY	for mdb_env_copy()
MDB_O_MASK	Bitmask for open() flags in enum mdb_fopen_type. The other bits distinguish otherwise-equal MDB_O_* constants from each other.
MDB_O_LOCKS	for me_lfd

Pidlock_op

enum Pidlock_op

Enumerator
Pidset
Pidcheck

Function Documentation

mdb_assert_fail()

void ESECT mdb_assert_fail ( MDB_env * env, const char * expr_txt, const char * func, const char * file, int line )

static

mdb_branch_size()

size_t mdb_branch_size ( MDB_env * env, MDB_val * key )

static

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 MDB_node 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 MDB_node headers.

Parameters

[in]	env	The environment handle.
[in]	key	The key for the node.

Returns

The number of bytes needed to store the node.

mdb_cmp()

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

Compare two data items according to a particular database.

This returns a comparison as if the two data items were keys in the specified database.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	a	The first item to compare
[in]	b	The second item to compare

Returns

< 0 if a < b, 0 if a == b, > 0 if a > b

mdb_cmp_cint()

int mdb_cmp_cint ( const MDB_val * a, const MDB_val * b )

static

Compare two items pointing at unsigned ints of unknown alignment. Nodes and keys are guaranteed to be 2-byte aligned.

mdb_cmp_int()

int mdb_cmp_int ( const MDB_val * a, const MDB_val * b )

static

Compare two items pointing at aligned unsigned int's.

This is also set as MDB_INTEGERDUP|MDB_DUPFIXED's MDB_dbx.md_dcmp, but mdb_cmp_clong() is called instead if the data type is mdb_size_t.

mdb_cmp_long()

int mdb_cmp_long ( const MDB_val * a, const MDB_val * b )

static

Compare two items pointing at aligned mdb_size_t's

mdb_cmp_memn()

int mdb_cmp_memn ( const MDB_val * a, const MDB_val * b )

static

Compare two items lexically

mdb_cmp_memnr()

int mdb_cmp_memnr ( const MDB_val * a, const MDB_val * b )

static

Compare two items in reverse byte order

mdb_cursor_close()

void mdb_cursor_close

(

MDB_cursor *

cursor

)

Close a cursor handle.

The cursor handle will be freed and must not be used again after this call. Its transaction must still be live if it is a write-transaction.

Parameters

[in]

cursor

A cursor handle returned by mdb_cursor_open()

mdb_cursor_copy()

void mdb_cursor_copy ( const MDB_cursor * csrc, MDB_cursor * cdst )

static

Copy the contents of a cursor.

Parameters

[in]	csrc	The cursor to copy from.
[out]	cdst	The cursor to copy to.

mdb_cursor_count()

int mdb_cursor_count	(	MDB_cursor *	cursor,
		mdb_size_t *	countp )

Return count of duplicates for current key.

This call is only valid on databases that support sorted duplicate data items MDB_DUPSORT.

Parameters

[in]	cursor	A cursor handle returned by mdb_cursor_open()
[out]	countp	Address where the count will be stored

Returns

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

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

mdb_cursor_dbi()

MDB_dbi mdb_cursor_dbi

(

MDB_cursor *

cursor

)

Return the cursor's database handle.

Parameters

[in]

cursor

A cursor handle returned by mdb_cursor_open()

mdb_cursor_del()

int mdb_cursor_del	(	MDB_cursor *	cursor,
		unsigned int	flags )

Delete current key/data pair.

This function deletes the key/data pair to which the cursor refers. This does not invalidate the cursor, so operations such as MDB_NEXT can still be used on it. Both MDB_NEXT and MDB_GET_CURRENT will return the same record after this operation.

Parameters

[in]	cursor	A cursor handle returned by mdb_cursor_open()
[in]	flags	Options for this operation. This parameter must be set to 0 or one of the values described here. MDB_NODUPDATA - delete all of the data items for the current key. This flag may only be specified if the database was opened with MDB_DUPSORT.

Returns

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

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

mdb_cursor_del0()

int mdb_cursor_del0 ( MDB_cursor * mc )

static

Complete a delete operation started by mdb_cursor_del().

mdb_cursor_first()

int mdb_cursor_first ( MDB_cursor * mc, MDB_val * key, MDB_val * data )

static

Move the cursor to the first item in the database.

mdb_cursor_get()

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

Retrieve by cursor.

This function retrieves key/data pairs from the database. The address and length of the key are returned in the object to which key refers (except for the case of the MDB_SET option, in which the key object is unchanged), and the address and length of the data are returned in the object to which data refers. See mdb_get() for restrictions on using the output values.

Parameters

[in]	cursor	A cursor handle returned by mdb_cursor_open()
[in,out]	key	The key for a retrieved item
[in,out]	data	The data of a retrieved item
[in]	op	A cursor operation MDB_cursor_op

Returns

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

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

mdb_cursor_init()

void mdb_cursor_init ( MDB_cursor * mc, MDB_txn * txn, MDB_dbi dbi, MDB_xcursor * mx )

static

Initialize a cursor for a given transaction and database.

mdb_cursor_last()

int mdb_cursor_last ( MDB_cursor * mc, MDB_val * key, MDB_val * data )

static

Move the cursor to the last item in the database.

mdb_cursor_next()

int mdb_cursor_next ( MDB_cursor * mc, MDB_val * key, MDB_val * data, MDB_cursor_op op )

static

Move the cursor to the next data item.

mdb_cursor_open()

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

Create a cursor handle.

A cursor is associated with a specific transaction and database. A cursor cannot be used when its database handle is closed. Nor when its transaction has ended, except with mdb_cursor_renew(). It can be discarded with mdb_cursor_close(). A cursor in a write-transaction can be closed before its transaction ends, and will otherwise be closed when its transaction ends. A cursor in a read-only transaction must be closed explicitly, before or after its transaction ends. It can be reused with mdb_cursor_renew() before finally closing it.

Note

Earlier documentation said that cursors in every transaction were closed when the transaction committed or aborted.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[out]	cursor	Address where the new MDB_cursor handle will be stored

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_cursor_pop()

void mdb_cursor_pop ( MDB_cursor * mc )

static

Pop a page off the top of the cursor's stack.

mdb_cursor_prev()

int mdb_cursor_prev ( MDB_cursor * mc, MDB_val * key, MDB_val * data, MDB_cursor_op op )

static

Move the cursor to the previous data item.

mdb_cursor_push()

int mdb_cursor_push ( MDB_cursor * mc, MDB_page * mp )

static

Push a page onto the top of the cursor's stack. Set MDB_TXN_ERROR on failure.

mdb_cursor_put()

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

Store by cursor.

This function stores key/data pairs into the database. The cursor is positioned at the new item, or on failure usually near it.

Note

Earlier documentation incorrectly said errors would leave the state of the cursor unchanged.

Parameters

[in]	cursor	A cursor handle returned by mdb_cursor_open()
[in]	key	The key operated on.
[in]	data	The data operated on.
[in]	flags	Options for this operation. This parameter must be set to 0 or one of the values described here. MDB_CURRENT - replace the item at the current cursor position. The key parameter must still be provided, and must match it. If using sorted duplicates (MDB_DUPSORT) the data item must still sort into the same place. This is intended to be used when the new data is the same size as the old. Otherwise it will simply perform a delete of the old record followed by an insert. MDB_NODUPDATA - enter the new key/data pair only if it does not already appear in the database. This flag may only be specified if the database was opened with MDB_DUPSORT. The function will return MDB_KEYEXIST if the key/data pair already appears in the database. MDB_NOOVERWRITE - enter the new key/data pair only if the key does not already appear in the database. The function will return MDB_KEYEXIST if the key already appears in the database, even if the database supports duplicates (MDB_DUPSORT). MDB_RESERVE - reserve space for data of the given size, but don't copy the given data. Instead, return a pointer to the reserved space, which the caller can fill in later - before the next update operation or the transaction ends. This saves an extra memcpy if the data is being generated later. This flag must not be specified if the database was opened with MDB_DUPSORT. MDB_APPEND - append the given key/data pair to the end of the database. No key comparisons are performed. This option allows fast bulk loading when keys are already known to be in the correct order. Loading unsorted keys with this flag will cause a MDB_KEYEXIST error. MDB_APPENDDUP - as above, but for sorted dup data. MDB_MULTIPLE - store multiple contiguous data elements in a single request. This flag may only be specified if the database was opened with MDB_DUPFIXED. The data argument must be an array of two MDB_vals. The mv_size of the first MDB_val must be the size of a single data element. The mv_data of the first MDB_val must point to the beginning of the array of contiguous data elements. The mv_size of the second MDB_val must be the count of the number of data elements to store. On return this field will be set to the count of the number of elements actually written. The mv_data of the second MDB_val is unused.

Returns

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

• MDB_MAP_FULL - the database is full, see mdb_env_set_mapsize().
• MDB_TXN_FULL - the transaction has too many dirty pages.
• EACCES - an attempt was made to write in a read-only transaction.
• EINVAL - an invalid parameter was specified.

mdb_cursor_renew()

int mdb_cursor_renew	(	MDB_txn *	txn,
		MDB_cursor *	cursor )

Renew a cursor handle.

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

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	cursor	A cursor handle returned by mdb_cursor_open()

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_cursor_set()

int mdb_cursor_set ( MDB_cursor * mc, MDB_val * key, MDB_val * data, MDB_cursor_op op, int * exactp )

static

Set the cursor on a specific data item.

mdb_cursor_shadow()

int mdb_cursor_shadow ( MDB_txn * src, MDB_txn * dst )

static

Back up parent txn's cursors, then grab the originals for tracking

mdb_cursor_sibling()

int mdb_cursor_sibling ( MDB_cursor * mc, int move_right )

static

Find a sibling for a page. Replaces the page at the top of the cursor's stack with the specified sibling, if one exists.

Parameters

[in]	mc	The cursor for this operation.
[in]	move_right	Non-zero if the right sibling is requested, otherwise the left sibling.

Returns

0 on success, non-zero on failure.

mdb_cursor_touch()

int mdb_cursor_touch ( MDB_cursor * mc )

static

Touch all the pages in the cursor stack. Set mc_top. Makes sure all the pages are writable, before attempting a write operation.

Parameters

[in]

mc

The cursor to operate on.

mdb_cursor_txn()

MDB_txn * mdb_cursor_txn

(

MDB_cursor *

cursor

)

Return the cursor's transaction handle.

Parameters

[in]

cursor

A cursor handle returned by mdb_cursor_open()

mdb_cursors_close()

void mdb_cursors_close ( MDB_txn * txn, unsigned merge )

static

Close this write txn's cursors, give parent txn's cursors back to parent.

Parameters

[in]	txn	the transaction handle.
[in]	merge	true to keep changes to parent cursors, false to revert.

Returns

0 on success, non-zero on failure.

mdb_dbi_close()

void mdb_dbi_close	(	MDB_env *	env,
		MDB_dbi	dbi )

Close a database handle. Normally unnecessary. Use with care:

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

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

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	dbi	A database handle returned by mdb_dbi_open()

mdb_dbi_flags()

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

Retrieve the DB flags for a database handle.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[out]	flags	Address where the flags will be returned.

Returns

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

mdb_dbi_open()

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

Open a database in the environment.

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

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

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

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

Parameters

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

Returns

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

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

mdb_dbis_update()

void mdb_dbis_update ( MDB_txn * txn, int keep )

static

Export or close DBI handles opened in this txn.

mdb_dcmp()

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

Compare two data items according to a particular database.

This returns a comparison as if the two items were data items of the specified database. The database must have the MDB_DUPSORT flag.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	a	The first item to compare
[in]	b	The second item to compare

Returns

< 0 if a < b, 0 if a == b, > 0 if a > b

mdb_default_cmp()

void mdb_default_cmp ( MDB_txn * txn, MDB_dbi dbi )

static

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 mdb_set_compare() or mdb_set_dupsort().

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()

mdb_del()

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

Delete items from a database.

This function removes key/data pairs from the database. If the database does not support sorted duplicate data items (MDB_DUPSORT) the data parameter is ignored. If the database supports sorted duplicates and the data parameter is NULL, all of the duplicate data items for the key will be deleted. Otherwise, if the data parameter is non-NULL only the matching data item will be deleted. This function will return MDB_NOTFOUND if the specified key/data pair is not in the database.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	key	The key to delete from the database
[in]	data	The data to delete

Returns

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

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

mdb_del0()

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

static

mdb_dlist_free()

void mdb_dlist_free ( MDB_txn * txn )

static

Return all dirty pages to dpage list

mdb_dpage_free()

void mdb_dpage_free ( MDB_env * env, MDB_page * dp )

static

Free a dirty page

mdb_drop()

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

Empty or delete+close a database.

See mdb_dbi_close() for restrictions about closing the DB handle.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	del	0 to empty the DB, 1 to delete it from the environment and close the DB handle.

Returns

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

mdb_drop0()

int mdb_drop0 ( MDB_cursor * mc, int subs )

static

Add all the DB's pages to the free list.

Parameters

[in]	mc	Cursor on the DB to free.
[in]	subs	non-Zero to check for sub-DBs in this DB.

Returns

0 on success, non-zero on failure.

mdb_env_close()

void ESECT mdb_env_close

(

MDB_env *

env

)

Close the environment and release the memory map.

Only a single thread may call this function. All transactions, databases, and cursors must already be closed before calling this function. Attempts to use any such handles after calling this function will cause a SIGSEGV. The environment handle will be freed and must not be used again after this call.

Parameters

[in]

env

An environment handle returned by mdb_env_create()

mdb_env_close0()

void ESECT mdb_env_close0 ( MDB_env * env, int excl )

static

Destroy resources from mdb_env_open(), clear our readers & DBIs

mdb_env_copy()

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

Copy an LMDB environment to the specified path.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note

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

Parameters

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

Returns

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

mdb_env_copy2()

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

Copy an LMDB environment to the specified path, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Note

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

Parameters

[in]	env	An environment handle returned by mdb_env_create(). It must have already been opened successfully.
[in]	path	The directory in which the copy will reside. This directory must already exist and be writable but must otherwise be empty.
[in]	flags	Special options for this operation. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here. MDB_CP_COMPACT - Perform compaction while copying: omit free pages and sequentially renumber all pages in output. This option consumes more CPU and runs more slowly than the default. Currently it fails if the environment has suffered a page leak.

Returns

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

mdb_env_copyfd()

int ESECT mdb_env_copyfd	(	MDB_env *	env,
		HANDLE	fd )

mdb_env_copyfd0()

int ESECT mdb_env_copyfd0 ( MDB_env * env, HANDLE fd )

static

Copy environment as-is.

mdb_env_copyfd1()

int ESECT mdb_env_copyfd1 ( MDB_env * env, HANDLE fd )

static

Copy environment with compaction.

mdb_env_copyfd2()

int ESECT mdb_env_copyfd2	(	MDB_env *	env,
		HANDLE	fd,
		unsigned int	flags )

mdb_env_copythr()

THREAD_RET ESECT CALL_CONV mdb_env_copythr ( void * arg )

static

Dedicated writer thread for compacting copy.

mdb_env_create()

int ESECT mdb_env_create

(

MDB_env **

env

)

Create an LMDB environment handle.

This function allocates memory for a MDB_env structure. To release the allocated memory and discard the handle, call mdb_env_close(). Before the handle may be used, it must be opened using mdb_env_open(). Various other options may also need to be set before opening the handle, e.g. mdb_env_set_mapsize(), mdb_env_set_maxreaders(), mdb_env_set_maxdbs(), depending on usage requirements.

Parameters

[out]

env

The address where the new handle will be stored

Returns

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

mdb_env_cthr_toggle()

int ESECT mdb_env_cthr_toggle ( mdb_copy * my, int adjust )

static

Give buffer and/or MDB_EOF to writer thread, await unused buffer.

Parameters

[in]	my	control structure.
[in]	adjust	(1 to hand off 1 buffer) | (MDB_EOF when ending).

mdb_env_cwalk()

int ESECT mdb_env_cwalk ( mdb_copy * my, pgno_t * pg, int flags )

static

Depth-first tree traversal for compacting copy.

Parameters

[in]	my	control structure.
[in,out]	pg	database root.
[in]	flags	includes F_DUPDATA if it is a sorted-duplicate sub-DB.

mdb_env_excl_lock()

int ESECT mdb_env_excl_lock ( MDB_env * env, int * excl )

static

Try to get exclusive lock, otherwise shared. Maintain *excl = -1: no/unknown lock, 0: shared, 1: exclusive.

mdb_env_get_fd()

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

Return the filedescriptor for the given environment.

This function may be called after fork(), so the descriptor can be closed before exec*(). Other LMDB file descriptors have FD_CLOEXEC. (Until LMDB 0.9.18, only the lockfile had that.)

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[out]	fd	Address of a mdb_filehandle_t to contain the descriptor.

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_env_get_flags()

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

Get environment flags.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[out]	flags	The address of an integer to store the flags

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_env_get_maxkeysize()

int ESECT mdb_env_get_maxkeysize

(

MDB_env *

env

)

Get the maximum size of keys and MDB_DUPSORT data we can write.

Depends on the compile-time constant MDB_MAXKEYSIZE. Default 511. See MDB_val.

Parameters

[in]

env

An environment handle returned by mdb_env_create()

Returns

The maximum size of a key we can write

mdb_env_get_maxreaders()

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

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

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[out]	Reader Lock Table	Address of an integer to store the number of readers

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_env_get_path()

int ESECT mdb_env_get_path	(	MDB_env *	env,
		const char **	path )

Return the path that was used in mdb_env_open().

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[out]	path	Address of a string pointer to contain the path. This is the actual string in the environment, not a copy. It should not be altered in any way.

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_env_get_userctx()

void *ESECT mdb_env_get_userctx

(

MDB_env *

env

)

Get the application information associated with the MDB_env.

Parameters

[in]

env

An environment handle returned by mdb_env_create()

Returns

The pointer set by mdb_env_set_userctx().

mdb_env_info()

int ESECT mdb_env_info	(	MDB_env *	env,
		MDB_envinfo *	stat )

Return information about the LMDB environment.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[out]	stat	The address of an MDB_envinfo structure where the information will be copied

mdb_env_init_meta()

int ESECT mdb_env_init_meta ( MDB_env * env, MDB_meta * meta )

static

Write the environment parameters of a freshly created DB environment.

Parameters

[in]	env	the environment handle
[in]	meta	the MDB_meta to write

Returns

0 on success, non-zero on failure.

mdb_env_init_meta0()

void ESECT mdb_env_init_meta0 ( MDB_env * env, MDB_meta * meta )

static

Fill in most of the zeroed MDB_meta for an empty database environment

mdb_env_map()

int ESECT mdb_env_map ( MDB_env * env, void * addr )

static

mdb_env_open()

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

Open an environment handle.

If this function fails, mdb_env_close() must be called to discard the MDB_env handle.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	path	The directory in which the database files reside. This directory must already exist and be writable.
[in]	flags	Special options for this environment. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here. Flags set by mdb_env_set_flags() are also used. MDB_FIXEDMAP use a fixed address for the mmap region. This flag must be specified when creating the environment, and is stored persistently in the environment. If successful, the memory map will always reside at the same virtual address and pointers used to reference data items in the database will be constant across multiple invocations. This option may not always work, depending on how the operating system has allocated memory to shared libraries and other uses. The feature is highly experimental. MDB_NOSUBDIR By default, LMDB creates its environment in a directory whose pathname is given in path, and creates its data and lock files under that directory. With this option, path is used as-is for the database main data file. The database lock file is the path with "-lock" appended. MDB_RDONLY Open the environment in read-only mode. No write operations will be allowed. LMDB will still modify the lock file - except on read-only filesystems, where LMDB does not use locks. MDB_WRITEMAP Use a writeable memory map unless MDB_RDONLY is set. This uses fewer mallocs but loses protection from application bugs like wild pointer writes and other bad updates into the database. This may be slightly faster for DBs that fit entirely in RAM, but is slower for DBs larger than RAM. Incompatible with nested transactions. Do not mix processes with and without MDB_WRITEMAP on the same environment. This can defeat durability (mdb_env_sync etc). MDB_NOMETASYNC Flush system buffers to disk only once per transaction, omit the metadata flush. Defer that until the system flushes files to disk, or next non-MDB_RDONLY commit or mdb_env_sync(). This optimization maintains database integrity, but a system crash may undo the last committed transaction. I.e. it preserves the ACI (atomicity, consistency, isolation) but not D (durability) database property. This flag may be changed at any time using mdb_env_set_flags(). MDB_NOSYNC Don't flush system buffers to disk when committing a transaction. This optimization means a system crash can corrupt the database or lose the last transactions if buffers are not yet flushed to disk. The risk is governed by how often the system flushes dirty buffers to disk and how often mdb_env_sync() is called. However, if the filesystem preserves write order and the MDB_WRITEMAP flag is not used, transactions exhibit ACI (atomicity, consistency, isolation) properties and only lose D (durability). I.e. database integrity is maintained, but a system crash may undo the final transactions. Note that (MDB_NOSYNC | MDB_WRITEMAP) leaves the system with no hint for when to write transactions to disk, unless mdb_env_sync() is called. (MDB_MAPASYNC | MDB_WRITEMAP) may be preferable. This flag may be changed at any time using mdb_env_set_flags(). MDB_MAPASYNC When using MDB_WRITEMAP, use asynchronous flushes to disk. As with MDB_NOSYNC, a system crash can then corrupt the database or lose the last transactions. Calling mdb_env_sync() ensures on-disk database integrity until next commit. This flag may be changed at any time using mdb_env_set_flags(). MDB_NOTLS Don't use Thread-Local Storage. Tie reader locktable slots to MDB_txn objects instead of to threads. I.e. mdb_txn_reset() keeps the slot reseved for the MDB_txn object. A thread may use parallel read-only transactions. A read-only transaction may span threads if the user synchronizes its use. Applications that multiplex many user threads over individual OS threads need this option. Such an application must also serialize the write transactions in an OS thread, since LMDB's write locking is unaware of the user threads. MDB_NOLOCK Don't do any locking. If concurrent access is anticipated, the caller must manage all concurrency itself. For proper operation the caller must enforce single-writer semantics, and must ensure that no readers are using old transactions while a writer is active. The simplest approach is to use an exclusive lock so that no readers may be active at all when a writer begins. MDB_NORDAHEAD Turn off readahead. Most operating systems perform readahead on read requests by default. This option turns it off if the OS supports it. Turning it off may help random read performance when the DB is larger than RAM and system RAM is full. The option is not implemented on Windows. MDB_NOMEMINIT Don't initialize malloc'd memory before writing to unused spaces in the data file. By default, memory for pages written to the data file is obtained using malloc. While these pages may be reused in subsequent transactions, freshly malloc'd pages will be initialized to zeroes before use. This avoids persisting leftover data from other code (that used the heap and subsequently freed the memory) into the data file. Note that many other system libraries may allocate and free memory from the heap for arbitrary uses. E.g., stdio may use the heap for file I/O buffers. This initialization step has a modest performance cost so some applications may want to disable it using this flag. This option can be a problem for applications which handle sensitive data like passwords, and it makes memory checkers like Valgrind noisy. This flag is not needed with MDB_WRITEMAP, which writes directly to the mmap instead of using malloc for pages. The initialization is also skipped if MDB_RESERVE is used; the caller is expected to overwrite all of the memory that was reserved in that case. This flag may be changed at any time using mdb_env_set_flags(). MDB_PREVSNAPSHOT Open the environment with the previous snapshot rather than the latest one. This loses the latest transaction, but may help work around some types of corruption. If opened with write access, this must be the only process using the environment. This flag is automatically reset after a write transaction is successfully committed.
[in]	mode	The UNIX permissions to set on created files and semaphores. This parameter is ignored on Windows.

Returns

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

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

mdb_env_open2()

int ESECT mdb_env_open2 ( MDB_env * env, int prev )

static

Further setup required for opening an LMDB environment

mdb_env_pick_meta()

MDB_meta * mdb_env_pick_meta ( const MDB_env * env )

static

Check both meta pages to see which one is newer.

Parameters

[in]

env

the environment handle

Returns

newest MDB_meta.

mdb_env_read_header()

int ESECT mdb_env_read_header ( MDB_env * env, int prev, MDB_meta * meta )

static

Read the environment parameters of a DB environment before mapping it into memory.

Parameters

[in]	env	the environment handle
[in]	prev	whether to read the backup meta page
[out]	meta	address of where to store the meta information

Returns

0 on success, non-zero on failure.

mdb_env_reader_dest()

void mdb_env_reader_dest ( void * ptr )

static

Release a reader thread's slot in the reader lock table. This function is called automatically when a thread exits.

Parameters

[in]

ptr

This points to the slot in the reader lock table.

mdb_env_set_assert()

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

Set or reset the assert() callback of the environment. Disabled if liblmdb is buillt with NDEBUG.

Note

This hack should become obsolete as lmdb's error handling matures.

Parameters

[in]	env	An environment handle returned by mdb_env_create().
[in]	func	An MDB_assert_func function, or 0.

Returns

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

mdb_env_set_flags()

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

Set environment flags.

This may be used to set some flags in addition to those from mdb_env_open(), or to unset these flags. If several threads change the flags at the same time, the result is undefined.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	flags	The flags to change, bitwise OR'ed together
[in]	onoff	A non-zero value sets the flags, zero clears them.

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_env_set_mapsize()

int ESECT mdb_env_set_mapsize	(	MDB_env *	env,
		mdb_size_t	size )

Set the size of the memory map to use for this environment.

The size should be a multiple of the OS page size. The default is 10485760 bytes. The size of the memory map is also the maximum size of the database. The value should be chosen as large as possible, to accommodate future growth of the database. This function should be called after mdb_env_create() and before mdb_env_open(). It may be called at later times if no transactions are active in this process. Note that the library does not check for this condition, the caller must ensure it explicitly.

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

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

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

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	size	The size in bytes

Returns

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

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

mdb_env_set_maxdbs()

int ESECT mdb_env_set_maxdbs	(	MDB_env *	env,
		MDB_dbi	dbs )

Set the maximum number of named databases for the environment.

This function is only needed if multiple databases will be used in the environment. Simpler applications that use the environment as a single unnamed database can ignore this option. This function may only be called after mdb_env_create() and before mdb_env_open().

Currently a moderate number of slots are cheap but a huge number gets expensive: 7-120 words per transaction, and every mdb_dbi_open() does a linear search of the opened slots.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	dbs	The maximum number of databases

Returns

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

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

mdb_env_set_maxreaders()

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

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

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

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	Reader Lock Table	The maximum number of reader lock table slots

Returns

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

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

mdb_env_set_userctx()

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

Set application information associated with the MDB_env.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	ctx	An arbitrary pointer for whatever the application needs.

Returns

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

mdb_env_setup_locks()

int ESECT mdb_env_setup_locks ( MDB_env * env, MDB_name * fname, int mode, int * excl )

static

Open and/or initialize the lock region for the environment.

Parameters

[in]	env	The LMDB environment.
[in]	fname	Filename + scratch area, from mdb_fname_init().
[in]	mode	The Unix permissions for the file, if we create it.
[in,out]	excl	In -1, out lock type: -1 none, 0 shared, 1 exclusive

Returns

0 on success, non-zero on failure.

mdb_env_share_locks()

int ESECT mdb_env_share_locks ( MDB_env * env, int * excl )

static

Downgrade the exclusive lock on the region back to shared

mdb_env_stat()

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

Return statistics about the LMDB environment.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[out]	stat	The address of an MDB_stat structure where the statistics will be copied

mdb_env_sync()

int mdb_env_sync	(	MDB_env *	env,
		int	force )

Flush the data buffers to disk.

Data is always written to disk when mdb_txn_commit() is called, but the operating system may keep it buffered. LMDB always flushes the OS buffers upon commit as well, unless the environment was opened with MDB_NOSYNC or in part MDB_NOMETASYNC. This call is not valid if the environment was opened with MDB_RDONLY.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	force	If non-zero, force a synchronous flush. Otherwise if the environment has the MDB_NOSYNC flag set the flushes will be omitted, and with MDB_MAPASYNC they will be asynchronous.

Returns

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

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

mdb_env_sync0()

int mdb_env_sync0	(	MDB_env *	env,
		int	force,
		pgno_t	numpgs )

mdb_env_write_meta()

int mdb_env_write_meta ( MDB_txn * txn )

static

Update the environment info to commit a transaction.

Parameters

[in]

txn

the transaction that's being committed

Returns

0 on success, non-zero on failure.

mdb_find_oldest()

txnid_t mdb_find_oldest ( MDB_txn * txn )

static

Find oldest txnid still referenced. Expects txn->mt_txnid > 0.

mdb_fname_init()

int ESECT mdb_fname_init ( const char * path, unsigned envflags, MDB_name * fname )

static

Set up filename + scratch area for filename suffix, for opening files. It should be freed with mdb_fname_destroy(). On Windows, paths are converted from char *UTF-8 to wchar_t *UTF-16.

Parameters

[in]	path	Pathname for mdb_env_open().
[in]	envflags	Whether a subdir and/or lockfile will be used.
[out]	fname	Resulting filename, with room for a suffix if necessary.

mdb_fopen()

int ESECT mdb_fopen ( const MDB_env * env, MDB_name * fname, enum mdb_fopen_type which, mdb_mode_t mode, HANDLE * res )

static

Open an LMDB file.

Parameters

[in]	env	The LMDB environment.
[in,out]	fname	Path from from mdb_fname_init(). A suffix is appended if necessary to create the filename, without changing mn_len.
[in]	which	Determines file type, access mode, etc.
[in]	mode	The Unix permissions for the file, if we create it.
[out]	res	Resulting file handle.

Returns

0 on success, non-zero on failure.

mdb_freelist_save()

int mdb_freelist_save ( MDB_txn * txn )

static

Save the freelist as of this transaction to the freeDB. This changes the freelist. Keep trying until it stabilizes.

When (MDB_DEVEL) & 2, the changes do not affect mdb_page_alloc(), it then uses the transaction's original snapshot of the freeDB.

mdb_fsize()

int ESECT mdb_fsize ( HANDLE fd, mdb_size_t * size )

static

mdb_get()

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

Get items from a database.

This function retrieves key/data pairs from the database. The address and length of the data associated with the specified key are returned in the structure to which data refers. If the database supports duplicate keys (MDB_DUPSORT) then the first data item for the key will be returned. Retrieval of other items requires the use of mdb_cursor_get().

Note

The memory pointed to by the returned values is owned by the database. The caller need not dispose of the memory, and may not modify it in any way. For values returned in a read-only transaction any modification attempts will cause a SIGSEGV.

Values returned from the database are valid only until a subsequent update operation, or the end of the transaction.

Parameters

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

Returns

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

• MDB_NOTFOUND - the key was not in the database.
• EINVAL - an invalid parameter was specified.

mdb_leaf_size()

size_t mdb_leaf_size ( MDB_env * env, MDB_val * key, MDB_val * data )

static

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 MDB_node headers.

Parameters

[in]	env	The environment handle.
[in]	key	The key for the node.
[in]	data	The data for the node.

Returns

The number of bytes needed to store the node.

mdb_node_add()

int mdb_node_add ( MDB_cursor * mc, indx_t indx, MDB_val * key, MDB_val * data, pgno_t pgno, unsigned int flags )

static

Add a node to the page pointed to by the cursor. Set MDB_TXN_ERROR on failure.

Parameters

[in]	mc	The cursor for this operation.
[in]	indx	The index on the page where the new node should be added.
[in]	key	The key for the new node.
[in]	data	The data for the new node, if any.
[in]	pgno	The page number, if adding a branch node.
[in]	flags	Flags for the node.

Returns

0 on success, non-zero on failure. Possible errors are:

• ENOMEM - failed to allocate overflow pages for the node.
• 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.

mdb_node_del()

void mdb_node_del ( MDB_cursor * mc, int ksize )

static

Delete the specified node from a page.

Parameters

[in]	mc	Cursor pointing to the node to delete.
[in]	ksize	The size of a node. Only used if the page is part of a MDB_DUPFIXED database.

mdb_node_move()

int mdb_node_move ( MDB_cursor * csrc, MDB_cursor * cdst, int fromleft )

static

Move a node from csrc to cdst.

mdb_node_read()

int mdb_node_read ( MDB_cursor * mc, MDB_node * leaf, MDB_val * data )

static

Return the data associated with a given node.

Parameters

[in]	mc	The cursor for this operation.
[in]	leaf	The node being read.
[out]	data	Updated to point to the node's data.

Returns

0 on success, non-zero on failure.

mdb_node_search()

MDB_node * mdb_node_search ( MDB_cursor * mc, MDB_val * key, int * exactp )

static

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.

mdb_node_shrink()

void mdb_node_shrink ( MDB_page * mp, indx_t indx )

static

Compact the main page after deleting a node on a subpage.

Parameters

[in]	mp	The main page to operate on.
[in]	indx	The index of the subpage on the main page.

mdb_ovpage_free()

int mdb_ovpage_free ( MDB_cursor * mc, MDB_page * mp )

static

mdb_page_alloc()

int mdb_page_alloc ( MDB_cursor * mc, int num, MDB_page ** mp )

static

Allocate page numbers and memory for writing. Maintain me_pglast, me_pghead and mt_next_pgno. Set MDB_TXN_ERROR on failure.

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. When MDB_DEVEL & 2, it is not affected by mdb_freelist_save(): it then uses the transaction's original snapshot of the freeDB.

Parameters

[in]	mc	cursor A cursor handle identifying the transaction and database for which we are allocating.
[in]	num	the number of pages to allocate.
[out]	mp	Address of the allocated page(s). Requests for multiple pages will always be satisfied by a single contiguous chunk of memory.

Returns

0 on success, non-zero on failure.

mdb_page_copy()

void mdb_page_copy ( MDB_page * dst, MDB_page * src, unsigned int psize )

static

Copy the used portions of a non-overflow page.

Parameters

[in]	dst	page to copy into
[in]	src	page to copy from
[in]	psize	size of a page

mdb_page_dirty()

void mdb_page_dirty ( MDB_txn * txn, MDB_page * mp )

static

Add a page to the txn's dirty list

mdb_page_flush()

int mdb_page_flush ( MDB_txn * txn, int keep )

static

Flush (some) dirty pages to the map, after clearing their dirty flag.

Parameters

[in]	txn	the transaction that's being committed
[in]	keep	number of initial pages in dirty_list to keep dirty.

Returns

0 on success, non-zero on failure.

mdb_page_free()

void mdb_page_free ( MDB_env * env, MDB_page * mp )

static

Free a single page. Saves single pages to a list, for future reuse. (This is not used for multi-page overflow pages.)

mdb_page_get()

int mdb_page_get ( MDB_cursor * mc, pgno_t pgno, MDB_page ** ret, int * lvl )

static

Find the address of the page corresponding to a given page number. Set MDB_TXN_ERROR on failure.

Parameters

[in]	mc	the cursor accessing the page.
[in]	pgno	the page number for the page to retrieve.
[out]	ret	address of a pointer where the page's address will be stored.
[out]	lvl	dirty_list inheritance level of found page. 1=current txn, 0=mapped page.

Returns

0 on success, non-zero on failure.

mdb_page_loose()

int mdb_page_loose ( MDB_cursor * mc, MDB_page * mp )

static

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.

If the page wasn't dirtied in this txn, just add it to this txn's free list.

mdb_page_malloc()

MDB_page * mdb_page_malloc ( MDB_txn * txn, unsigned num )

static

Allocate memory for a page. Re-use old malloc'd pages first for singletons, otherwise just malloc. Set MDB_TXN_ERROR on failure.

mdb_page_merge()

int mdb_page_merge ( MDB_cursor * csrc, MDB_cursor * cdst )

static

Merge one page into another. The nodes from the page pointed to by csrc will be copied to the page pointed to by cdst and then the csrc page will be freed.

Parameters

[in]	csrc	Cursor pointing to the source page.
[in]	cdst	Cursor pointing to the destination page.

Returns

0 on success, non-zero on failure.

mdb_page_new()

int mdb_page_new ( MDB_cursor * mc, uint32_t flags, int num, MDB_page ** mp )

static

Allocate and initialize new pages for a database. Set MDB_TXN_ERROR on failure.

Parameters

[in]	mc	a cursor on the database being added to.
[in]	flags	flags defining what type of page is being allocated.
[in]	num	the number of pages to allocate. This is usually 1, unless allocating overflow pages for a large record.
[out]	mp	Address of a page, or NULL on failure.

Returns

0 on success, non-zero on failure.

mdb_page_search()

int mdb_page_search ( MDB_cursor * mc, MDB_val * key, int flags )

static

Search for the page a given key should be in. Push it and its parent pages on the cursor stack.

Parameters

[in,out]	mc	the cursor for this operation.
[in]	key	the key to search for, or NULL for first/last page.
[in]	flags	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 mdb_cursor_first() and mdb_cursor_last(). If MDB_PS_ROOTONLY set, just fetch root node, no further lookups.

Returns

0 on success, non-zero on failure.

mdb_page_search_lowest()

int mdb_page_search_lowest ( MDB_cursor * mc )

static

Search for the lowest key under the current branch page. This just bypasses a NUMKEYS check in the current page before calling mdb_page_search_root(), because the callers are all in situations where the current page is known to be underfilled.

mdb_page_search_root()

int mdb_page_search_root ( MDB_cursor * mc, MDB_val * key, int flags )

static

Finish mdb_page_search() / mdb_page_search_lowest(). The cursor is at the root page, set up the rest of it.

mdb_page_spill()

int mdb_page_spill ( MDB_cursor * m0, MDB_val * key, MDB_val * data )

static

Spill pages from the dirty list back to disk. This is intended to prevent running into MDB_TXN_FULL 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 MDB_MULTIPLE 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 mdb_txn_begin() of a child txn, if the parent's dirty_room is below a given threshold.

Otherwise, if not using nested txns, it is expected that apps will not run into MDB_TXN_FULL 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 mdb_page_touch(). Such references are handled by mdb_page_unspill().

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.

Parameters

[in]	m0	cursor A cursor handle identifying the transaction and database for which we are checking space.
[in]	key	For a put operation, the key being stored.
[in]	data	For a put operation, the data being stored.

Returns

0 on success, non-zero on failure.

mdb_page_split()

int mdb_page_split ( MDB_cursor * mc, MDB_val * newkey, MDB_val * newdata, pgno_t newpgno, unsigned int nflags )

static

Split a page and insert a new node. Set MDB_TXN_ERROR on failure.

Parameters

[in,out]	mc	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.
[in]	newkey	The key for the newly inserted node.
[in]	newdata	The data for the newly inserted node.
[in]	newpgno	The page number, if the new node is a branch node.
[in]	nflags	The NODE_ADD_FLAGS for the new node.

Returns

0 on success, non-zero on failure.

mdb_page_touch()

int mdb_page_touch ( MDB_cursor * mc )

static

Touch a page: make it dirty and re-insert into tree with updated pgno. Set MDB_TXN_ERROR on failure.

Parameters

[in]

mc

cursor pointing to the page to be touched

Returns

0 on success, non-zero on failure.

mdb_page_unspill()

int mdb_page_unspill ( MDB_txn * txn, MDB_page * mp, MDB_page ** ret )

static

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.

Parameters

[in]	txn	the transaction handle.
[in]	mp	the page being referenced. It must not be dirty.
[out]	ret	the writable page, if any. ret is unchanged if mp wasn't spilled.

mdb_pages_xkeep()

int mdb_pages_xkeep ( MDB_cursor * mc, unsigned pflags, int all )

static

Set or clear P_KEEP in dirty, non-overflow, non-sub pages watched by txn.

Parameters

[in]	mc	A cursor handle for the current operation.
[in]	pflags	Flags of the pages to update: P_DIRTY to set P_KEEP, P_DIRTY|P_KEEP to clear it.
[in]	all	No shortcuts. Needed except after a full mdb_page_flush().

Returns

0 on success, non-zero on failure.

mdb_pid_insert()

int ESECT mdb_pid_insert ( MDB_PID_T * ids, MDB_PID_T pid )

static

Insert pid into list if not already present. return -1 if already present.

mdb_put()

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

Store items into a database.

This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed (MDB_DUPSORT).

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	key	The key to store in the database
[in,out]	data	The data to store
[in]	flags	Special options for this operation. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here. MDB_NODUPDATA - enter the new key/data pair only if it does not already appear in the database. This flag may only be specified if the database was opened with MDB_DUPSORT. The function will return MDB_KEYEXIST if the key/data pair already appears in the database. MDB_NOOVERWRITE - enter the new key/data pair only if the key does not already appear in the database. The function will return MDB_KEYEXIST if the key already appears in the database, even if the database supports duplicates (MDB_DUPSORT). The data parameter will be set to point to the existing item. MDB_RESERVE - reserve space for data of the given size, but don't copy the given data. Instead, return a pointer to the reserved space, which the caller can fill in later - before the next update operation or the transaction ends. This saves an extra memcpy if the data is being generated later. LMDB does nothing else with this memory, the caller is expected to modify all of the space requested. This flag must not be specified if the database was opened with MDB_DUPSORT. MDB_APPEND - append the given key/data pair to the end of the database. This option allows fast bulk loading when keys are already known to be in the correct order. Loading unsorted keys with this flag will cause a MDB_KEYEXIST error. MDB_APPENDDUP - as above, but for sorted dup data.

Returns

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

• MDB_MAP_FULL - the database is full, see mdb_env_set_mapsize().
• MDB_TXN_FULL - the transaction has too many dirty pages.
• EACCES - an attempt was made to write in a read-only transaction.
• EINVAL - an invalid parameter was specified.

mdb_reader_check()

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

Check for stale entries in the reader lock table.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[out]	dead	Number of stale slots that were cleared

Returns

0 on success, non-zero on failure.

mdb_reader_check0()

int ESECT mdb_reader_check0 ( MDB_env * env, int rlocked, int * dead )

static

As mdb_reader_check(). rlocked is set if caller locked me_rmutex.

mdb_reader_list()

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

Dump the entries in the reader lock table.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	func	A MDB_msg_func function
[in]	ctx	Anything the message function needs

Returns

< 0 on failure, >= 0 on success.

mdb_reader_pid()

int mdb_reader_pid ( MDB_env * env, enum Pidlock_op op, MDB_PID_T pid )

static

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).

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.

mdb_rebalance()

int mdb_rebalance ( MDB_cursor * mc )

static

Rebalance the tree after a delete operation.

Parameters

[in]

mc

Cursor pointing to the page where rebalancing should begin.

Returns

0 on success, non-zero on failure.

mdb_set_compare()

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

Set a custom key comparison function for a database.

The comparison function is called whenever it is necessary to compare a key specified by the application with a key currently stored in the database. If no comparison function is specified, and no special key flags were specified with mdb_dbi_open(), the keys are compared lexically, with shorter keys collating before longer keys.

Warning

This function must be called before any data access functions are used, otherwise data corruption may occur. The same comparison function must be used by every program accessing the database, every time the database is used.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	cmp	A MDB_cmp_func function

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_set_dupsort()

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

Set a custom data comparison function for a MDB_DUPSORT database.

This comparison function is called whenever it is necessary to compare a data item specified by the application with a data item currently stored in the database. This function only takes effect if the database was opened with the MDB_DUPSORT flag. If no comparison function is specified, and no special key flags were specified with mdb_dbi_open(), the data items are compared lexically, with shorter items collating before longer items.

Warning

This function must be called before any data access functions are used, otherwise data corruption may occur. The same comparison function must be used by every program accessing the database, every time the database is used.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	cmp	A MDB_cmp_func function

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_set_relctx()

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

Set a context pointer for a MDB_FIXEDMAP database's relocation function.

See mdb_set_relfunc and MDB_rel_func for more details.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	ctx	An arbitrary pointer for whatever the application needs. It will be passed to the callback function set by mdb_set_relfunc as its relctx parameter whenever the callback is invoked.

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_set_relfunc()

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

Set a relocation function for a MDB_FIXEDMAP database.

Todo

The relocation function is called whenever it is necessary to move the data of an item to a different position in the database (e.g. through tree balancing operations, shifts as a result of adds or deletes, etc.). It is intended to allow address/position-dependent data items to be stored in a database in an environment opened with the MDB_FIXEDMAP option. Currently the relocation feature is unimplemented and setting this function has no effect.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[in]	rel	A MDB_rel_func function

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_stat()

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

Retrieve statistics for a database.

Parameters

[in]	txn	A transaction handle returned by mdb_txn_begin()
[in]	dbi	A database handle returned by mdb_dbi_open()
[out]	stat	The address of an MDB_stat structure where the statistics will be copied

Returns

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

• EINVAL - an invalid parameter was specified.

mdb_stat0()

int ESECT mdb_stat0 ( MDB_env * env, MDB_db * db, MDB_stat * arg )

static

Common code for mdb_stat() and mdb_env_stat().

Parameters

[in]	env	the environment to operate in.
[in]	db	the MDB_db record containing the stats to return.
[out]	arg	the address of an MDB_stat structure to receive the stats.

Returns

0, this function always succeeds.

mdb_strerror()

char * mdb_strerror

(

int

err

)

Return a string describing a given error code.

This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) 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 Return Codes for a list of LMDB-specific error codes.

Parameters

[in]

err

The error code

Return values

error message

The description of the error

mdb_txn_abort()

void mdb_txn_abort

(

MDB_txn *

txn

)

Abandon all the operations of the transaction instead of saving them.

The transaction handle is freed. It and its cursors must not be used again after this call, except with mdb_cursor_renew().

Note

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

Parameters

[in]

txn

A transaction handle returned by mdb_txn_begin()

mdb_txn_begin()

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

Create a transaction for use with the environment.

The transaction handle may be discarded using mdb_txn_abort() or mdb_txn_commit().

Note

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

Cursors may not span transactions.

Parameters

[in]	env	An environment handle returned by mdb_env_create()
[in]	parent	If this parameter is non-NULL, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level. A parent transaction and its cursors may not issue any other operations than mdb_txn_commit and mdb_txn_abort while it has active child transactions.
[in]	flags	Special options for this transaction. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here. MDB_RDONLY This transaction will not perform any write operations. MDB_NOSYNC Don't flush system buffers to disk when committing this transaction. MDB_NOMETASYNC Flush system buffers but omit metadata flush when committing this transaction.
[out]	txn	Address where the new MDB_txn handle will be stored

Returns

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

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

mdb_txn_commit()

int mdb_txn_commit

(

MDB_txn *

txn

)

Commit all the operations of a transaction into the database.

The transaction handle is freed. It and its cursors must not be used again after this call, except with mdb_cursor_renew().

Note

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

Parameters

[in]

txn

A transaction handle returned by mdb_txn_begin()

Returns

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

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

mdb_txn_end()

void mdb_txn_end ( MDB_txn * txn, unsigned mode )

static

End a transaction, except successful commit of a nested transaction. May be called twice for readonly txns: First reset it, then abort.

Parameters

[in]	txn	the transaction handle to end
[in]	mode	why and how to end the transaction

mdb_txn_env()

MDB_env * mdb_txn_env

(

MDB_txn *

txn

)

Returns the transaction's MDB_env.

Parameters

[in]

txn

A transaction handle returned by mdb_txn_begin()

mdb_txn_id()

mdb_size_t mdb_txn_id

(

MDB_txn *

txn

)

Return the transaction's ID.

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

Parameters

[in]

txn

A transaction handle returned by mdb_txn_begin()

Returns

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

mdb_txn_renew()

int mdb_txn_renew

(

MDB_txn *

txn

)

Renew a read-only transaction.

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

Parameters

[in]

txn

A transaction handle returned by mdb_txn_begin()

Returns

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

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

mdb_txn_renew0()

int mdb_txn_renew0 ( MDB_txn * txn )

static

Common code for mdb_txn_begin() and mdb_txn_renew().

Parameters

[in]

txn

the transaction handle to initialize

Returns

0 on success, non-zero on failure.

mdb_txn_reset()

void mdb_txn_reset

(

MDB_txn *

txn

)

Reset a read-only transaction.

Abort the transaction like mdb_txn_abort(), but keep the transaction handle. mdb_txn_renew() may reuse the handle. This saves allocation overhead if the process will start a new read-only transaction soon, and also locking overhead if MDB_NOTLS is in use. The reader table lock is released, but the table slot stays tied to its thread or MDB_txn. Use mdb_txn_abort() to discard a reset handle, and to free its lock table slot if MDB_NOTLS is in use. Cursors opened within the transaction must not be used again after this call, except with mdb_cursor_renew(). Reader locks generally don't interfere with writers, but they keep old versions of database pages allocated. Thus they prevent the old pages from being reused when writers commit new data, and so under heavy load the database size may grow much more rapidly than otherwise.

Parameters

[in]

txn

A transaction handle returned by mdb_txn_begin()

mdb_update_key()

int mdb_update_key ( MDB_cursor * mc, MDB_val * key )

static

Replace the key for a branch node with a new key. Set MDB_TXN_ERROR on failure.

Parameters

[in]	mc	Cursor pointing to the node to operate on.
[in]	key	The new key to use.

Returns

0 on success, non-zero on failure.

mdb_version()

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

Return the LMDB library version information.

Return the library version info.

mdb_xcursor_init0()

void mdb_xcursor_init0 ( MDB_cursor * mc )

static

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.

Parameters

[in]

mc

The main cursor whose sorted-dups cursor is to be initialized.

mdb_xcursor_init1()

void mdb_xcursor_init1 ( MDB_cursor * mc, MDB_node * node )

static

Final setup of a sorted-dups cursor. Sets up the fields that depend on the data from the main cursor.

Parameters

[in]	mc	The main cursor whose sorted-dups cursor is to be initialized.
[in]	node	The data containing the MDB_db record for the sorted-dup database.

mdb_xcursor_init2()

void mdb_xcursor_init2 ( MDB_cursor * mc, MDB_xcursor * src_mx, int new_dupdata )

static

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.

Parameters

[in]	mc	The main cursor whose sorted-dups cursor is to be fixed up.
[in]	src_mx	The xcursor of an up-to-date cursor.
[in]	new_dupdata	True if converting from a non-F_DUPDATA item.

Variable Documentation

mdb_errstr

char* const mdb_errstr[]

static

Initial value:

                             = {
    "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",
    "MDB_PROBLEM: Unexpected problem - txn should abort",
}

Table of descriptions for LMDB Return Codes

mdb_suffixes

const mdb_nchar_t* const mdb_suffixes[2][2]

static

Initial value:

                                            = {
    { MDB_NAME("/data.mdb"), MDB_NAME("")      },
    { MDB_NAME("/lock.mdb"), MDB_NAME("-lock") }
}

Filename suffixes [datafile,lockfile][without,with MDB_NOSUBDIR]