staticintmdb_page_alloc(MDB_cursor*mc,intnum,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.
Parametersmc cursor A cursor handle identifying the transaction and database for which we are allocating.
num the number of pages to allocate.
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.
staticintmdb_page_new(MDB_cursor*mc,uint32_tflags,intnum,MDB_page**mp)[static]
Allocate and initialize new pages for a database. Set MDB_TXN_ERROR on failure.
Parametersmc a cursor on the database being added to.
flags flags defining what type of page is being allocated.
num the number of pages to allocate. This is usually 1, unless allocating overflow pages for a large
record.
mp Address of a page, or NULL on failure.
Returns
0 on success, non-zero on failure.
staticintmdb_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.
Parametersmc cursor pointing to the page to be touched
Returns
0 on success, non-zero on failure.
staticvoidmdb_txn_end(MDB_txn*txn,unsignedmode)[static]
End a transaction, except successful commit of a nested transaction. May be called twice for readonly
txns: First reset it, then abort.
Parameterstxn the transaction handle to end
mode why and how to end the transaction
staticintmdb_page_get(MDB_cursor*mc,pgno_tpgno,MDB_page**ret,int*lvl)[static]
Find the address of the page corresponding to a given page number. Set MDB_TXN_ERROR on failure.
Parametersmc the cursor accessing the page.
pgno the page number for the page to retrieve.
ret address of a pointer where the page's address will be stored.
lvl dirty_list inheritance level of found page. 1=current txn, 0=mapped page.
Returns
0 on success, non-zero on failure.
staticintmdb_page_search_root(MDB_cursor*mc,MDB_val*key,intflags)[static]
Finish mdb_page_search() / mdb_page_search_lowest(). The cursor is at the root page, set up the rest of
it.
staticintmdb_page_search(MDB_cursor*mc,MDB_val*key,intflags)[static]
Search for the page a given key should be in. Push it and its parent pages on the cursor stack.
Parametersmc the cursor for this operation.
key the key to search for, or NULL for first/last page.
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.
staticintmdb_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.
Parameterscsrc Cursor pointing to the source page.
cdst Cursor pointing to the destination page.
Returns
0 on success, non-zero on failure.
staticintmdb_page_split(MDB_cursor*mc,MDB_val*newkey,MDB_val*newdata,pgno_tnewpgno,unsignedintnflags)[static]
Split a page and insert a new node. Set MDB_TXN_ERROR on failure.
Parametersmc 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.
newkey The key for the newly inserted node.
newdata The data for the newly inserted node.
newpgno The page number, if the new node is a branch node.
nflags The NODE_ADD_FLAGS for the new node.
Returns
0 on success, non-zero on failure.
staticintESECTmdb_env_read_header(MDB_env*env,MDB_meta*meta)[static]
Read the environment parameters of a DB environment before mapping it into memory.
Parametersenv the environment handle
meta address of where to store the meta information
Returns
0 on success, non-zero on failure.
staticMDB_meta*mdb_env_pick_meta(constMDB_env*env)[static]
Check both meta pages to see which one is newer.
Parametersenv the environment handle
Returns
newest MDB_meta.
staticintmdb_env_write_meta(MDB_txn*txn)[static]
Update the environment info to commit a transaction.
Parameterstxn the transaction that's being committed
Returns
0 on success, non-zero on failure.
staticvoidESECTmdb_env_close0(MDB_env*env,intexcl)[static]
Destroy resources from mdb_env_open(), clear our readers & DBIs
staticMDB_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.
staticintmdb_node_add(MDB_cursor*mc,indx_tindx,MDB_val*key,MDB_val*data,pgno_tpgno,unsignedintflags)[static]
Add a node to the page pointed to by the cursor. Set MDB_TXN_ERROR on failure.
Parametersmc The cursor for this operation.
indx The index on the page where the new node should be added.
key The key for the new node.
data The data for the new node, if any.
pgno The page number, if adding a branch node.
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.
staticvoidmdb_node_del(MDB_cursor*mc,intksize)[static]
Delete the specified node from a page.
Parametersmc Cursor pointing to the node to delete.
ksize The size of a node. Only used if the page is part of a MDB_DUPFIXED database.
staticvoidmdb_node_shrink(MDB_page*mp,indx_tindx)[static]
Compact the main page after deleting a node on a subpage.
Parametersmp The main page to operate on.
indx The index of the subpage on the main page.
staticintmdb_node_move(MDB_cursor*csrc,MDB_cursor*cdst,intfromleft)[static]
Move a node from csrc to cdst.
staticintmdb_node_read(MDB_cursor*mc,MDB_node*leaf,MDB_val*data)[static]
Return the data associated with a given node.
Parametersmc The cursor for this operation.
leaf The node being read.
data Updated to point to the node's data.
Returns
0 on success, non-zero on failure.
staticsize_tmdb_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.
Parametersenv The environment handle.
key The key for the node.
data The data for the node.
Returns
The number of bytes needed to store the node.
staticsize_tmdb_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.
Parametersenv The environment handle.
key The key for the node.
Returns
The number of bytes needed to store the node.
staticintmdb_rebalance(MDB_cursor*mc)[static]
Rebalance the tree after a delete operation.
Parametersmc Cursor pointing to the page where rebalancing should begin.
Returns
0 on success, non-zero on failure.
staticintmdb_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.
Parametersmc Cursor pointing to the node to operate on.
key The new key to use.
Returns
0 on success, non-zero on failure.
staticvoidmdb_cursor_pop(MDB_cursor*mc)[static]
Pop a page off the top of the cursor's stack.
staticintmdb_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.
staticintmdb_cursor_del0(MDB_cursor*mc)[static]
Complete a delete operation started by mdb_cursor_del().
staticintmdb_cursor_sibling(MDB_cursor*mc,intmove_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.
Parametersmc The cursor for this operation.
move_right Non-zero if the right sibling is requested, otherwise the left sibling.
Returns
0 on success, non-zero on failure.
staticintmdb_cursor_next(MDB_cursor*mc,MDB_val*key,MDB_val*data,MDB_cursor_opop)[static]
Move the cursor to the next data item.
staticintmdb_cursor_prev(MDB_cursor*mc,MDB_val*key,MDB_val*data,MDB_cursor_opop)[static]
Move the cursor to the previous data item.
staticintmdb_cursor_set(MDB_cursor*mc,MDB_val*key,MDB_val*data,MDB_cursor_opop,int*exactp)[static]
Set the cursor on a specific data item.
staticintmdb_cursor_first(MDB_cursor*mc,MDB_val*key,MDB_val*data)[static]
Move the cursor to the first item in the database.
staticintmdb_cursor_last(MDB_cursor*mc,MDB_val*key,MDB_val*data)[static]
Move the cursor to the last item in the database.
staticvoidmdb_cursor_init(MDB_cursor*mc,MDB_txn*txn,MDB_dbidbi,MDB_xcursor*mx)[static]
Initialize a cursor for a given transaction and database.
staticvoidmdb_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.
Parametersmc The main cursor whose sorted-dups cursor is to be initialized.
staticvoidmdb_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.
Parametersmc The main cursor whose sorted-dups cursor is to be initialized.
node The data containing the MDB_db record for the sorted-dup database.
staticvoidmdb_xcursor_init2(MDB_cursor*mc,MDB_xcursor*src_mx,intnew_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.
Parametersmc The main cursor whose sorted-dups cursor is to be fixed up.
src_mx The xcursor of an up-to-date cursor.
new_dupdata True if converting from a non-F_DUPDATA item.
staticintmdb_drop0(MDB_cursor*mc,intsubs)[static]
Add all the DB's pages to the free list.
Parametersmc Cursor on the DB to free.
subs non-Zero to check for sub-DBs in this DB.
Returns
0 on success, non-zero on failure.
staticvoidmdb_default_cmp(MDB_txn*txn,MDB_dbidbi)[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().
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()staticintESECTmdb_reader_check0(MDB_env*env,intrlocked,int*dead)[static]
As mdb_reader_check(). rlocked is set if caller locked me_rmutex.
char*ESECTmdb_version(int*major,int*minor,int*patch)
Return the LMDB library version information. Return the library version info.
char*mdb_strerror(interr)
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 ReturnCodes for a list of LMDB-specific error
codes.
Parameterserr The error code
Returnvalueserrormessage The description of the error
intmdb_cmp(MDB_txn*txn,MDB_dbidbi,constMDB_val*a,constMDB_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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()a The first item to compare
b The second item to compare
Returns
< 0 if a < b, 0 if a == b, > 0 if a > b
intmdb_dcmp(MDB_txn*txn,MDB_dbidbi,constMDB_val*a,constMDB_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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()a The first item to compare
b The second item to compare
Returns
< 0 if a < b, 0 if a == b, > 0 if a > b
staticMDB_page*mdb_page_malloc(MDB_txn*txn,unsignednum)[static]
Allocate memory for a page. Re-use old malloc'd pages first for singletons, otherwise just malloc. Set
MDB_TXN_ERROR on failure.
staticvoidmdb_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.)
staticvoidmdb_dpage_free(MDB_env*env,MDB_page*dp)[static]
Free a dirty page
staticvoidmdb_dlist_free(MDB_txn*txn)[static]
Return all dirty pages to dpage list
staticintmdb_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.
staticintmdb_pages_xkeep(MDB_cursor*mc,unsignedpflags,intall)[static]
Set or clear P_KEEP in dirty, non-overflow, non-sub pages watched by txn.
Parametersmc A cursor handle for the current operation.
pflags Flags of the pages to update: P_DIRTY to set P_KEEP, P_DIRTY|P_KEEP to clear it.
all No shortcuts. Needed except after a full mdb_page_flush().
Returns
0 on success, non-zero on failure.
staticintmdb_page_flush(MDB_txn*txn,intkeep)[static]
Flush (some) dirty pages to the map, after clearing their dirty flag.
Parameterstxn the transaction that's being committed
keep number of initial pages in dirty_list to keep dirty.
Returns
0 on success, non-zero on failure.
staticintmdb_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.
Parametersm0 cursor A cursor handle identifying the transaction and database for which we are checking space.
key For a put operation, the key being stored.
data For a put operation, the data being stored.
Returns
0 on success, non-zero on failure.
statictxnid_tmdb_find_oldest(MDB_txn*txn)[static]
Find oldest txnid still referenced. Expects txn->mt_txnid > 0.
staticvoidmdb_page_dirty(MDB_txn*txn,MDB_page*mp)[static]
Add a page to the txn's dirty list
staticvoidmdb_page_copy(MDB_page*dst,MDB_page*src,unsignedintpsize)[static]
Copy the used portions of a non-overflow page.
Parametersdst page to copy into
src page to copy from
psize size of a page
staticintmdb_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.
Parameterstxn the transaction handle.
mp the page being referenced. It must not be dirty.
ret the writable page, if any. ret is unchanged if mp wasn't spilled.
intmdb_env_sync(MDB_env*env,intforce)
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.
Parametersenv An environment handle returned by mdb_env_create()force If non-zero, force a synchronous flush. Otherwise if the environment has the MDB_NOSYNC flag
set the flushes will be omitted, and with MDB_MAPASYNC they will be asynchronous.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EACCES - the environment is read-only.
• EINVAL - an invalid parameter was specified.
• EIO - an error occurred during synchronization.
staticintmdb_cursor_shadow(MDB_txn*src,MDB_txn*dst)[static]
Back up parent txn's cursors, then grab the originals for tracking
staticvoidmdb_cursors_close(MDB_txn*txn,unsignedmerge)[static]
Close this write txn's cursors, give parent txn's cursors back to parent.
Parameterstxn the transaction handle.
merge true to keep changes to parent cursors, false to revert.
Returns
0 on success, non-zero on failure.
staticintmdb_reader_pid(MDB_env*env,enumPidlock_opop,MDB_PID_Tpid)[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.
staticintmdb_txn_renew0(MDB_txn*txn)[static]
Common code for mdb_txn_begin() and mdb_txn_renew().
Parameterstxn the transaction handle to initialize
Returns
0 on success, non-zero on failure.
intmdb_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.
Parameterstxn 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.
intmdb_txn_begin(MDB_env*env,MDB_txn*parent,unsignedintflags,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.
Parametersenv An environment handle returned by mdb_env_create()parent If this parameter is non-NULL, the new transaction will be a nested transaction, with the
transaction indicated by parent as its parent. Transactions may be nested to any level. A parent
transaction and its cursors may not issue any other operations than mdb_txn_commit and mdb_txn_abort
while it has active child transactions.
flags Special options for this transaction. This parameter must be set to 0 or by bitwise OR'ing
together one or more of the values described here.
• MDB_RDONLY This transaction will not perform any write operations.
txn Address where the new MDB_txn handle will be stored
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• MDB_PANIC - a fatal error occurred earlier and the environment must be shut down.
• MDB_MAP_RESIZED - another process wrote data beyond this MDB_env's mapsize and this environment's
map must be resized as well. See mdb_env_set_mapsize().
• MDB_READERS_FULL - a read-only transaction was requested and the reader lock table is full. See
mdb_env_set_maxreaders().
• ENOMEM - out of memory.
MDB_env*mdb_txn_env(MDB_txn*txn)
Returns the transaction's MDB_env.
Parameterstxn A transaction handle returned by mdb_txn_begin()size_tmdb_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.
Parameterstxn A transaction handle returned by mdb_txn_begin()Returns
A transaction ID, valid if input is an active transaction.
staticvoidmdb_dbis_update(MDB_txn*txn,intkeep)[static]
Export or close DBI handles opened in this txn.
voidmdb_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.
Parameterstxn A transaction handle returned by mdb_txn_begin()voidmdb_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.
Parameterstxn A transaction handle returned by mdb_txn_begin()staticintmdb_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.
intmdb_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.
Parameterstxn 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.
staticvoidESECTmdb_env_init_meta0(MDB_env*env,MDB_meta*meta)[static]
Fill in most of the zeroed MDB_meta for an empty database environment
staticintESECTmdb_env_init_meta(MDB_env*env,MDB_meta*meta)[static]
Write the environment parameters of a freshly created DB environment.
Parametersenv the environment handle
meta the MDB_meta to write
Returns
0 on success, non-zero on failure.
intESECTmdb_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.
Parametersenv The address where the new handle will be stored
Returns
A non-zero error value on failure and 0 on success.
intESECTmdb_env_set_mapsize(MDB_env*env,size_tsize)
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.
Parametersenv An environment handle returned by mdb_env_create()size The size in bytes
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified, or the environment has an active write transaction.
intESECTmdb_env_set_maxdbs(MDB_env*env,MDB_dbidbs)
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.
Parametersenv An environment handle returned by mdb_env_create()dbs The maximum number of databases
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified, or the environment is already open.
intESECTmdb_env_set_maxreaders(MDB_env*env,unsignedintreaders)
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().
Parametersenv An environment handle returned by mdb_env_create()readers The maximum number of reader lock table slots
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified, or the environment is already open.
intESECTmdb_env_get_maxreaders(MDB_env*env,unsignedint*readers)
Get the maximum number of threads/reader slots for the environment.
Parametersenv An environment handle returned by mdb_env_create()readers Address of an integer to store the number of readers
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
staticintESECTmdb_fname_init(constchar*path,unsignedenvflags,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.
Parameterspath Pathname for mdb_env_open().
envflags Whether a subdir and/or lockfile will be used.
fname Resulting filename, with room for a suffix if necessary.
staticintESECTmdb_fopen(constMDB_env*env,MDB_name*fname,enummdb_fopen_typewhich,mdb_mode_tmode,HANDLE*res)[static]
Open an LMDB file.
Parametersenv The LMDB environment.
fname Path from from mdb_fname_init(). A suffix is appended if necessary to create the filename,
without changing mn_len.
which Determines file type, access mode, etc.
mode The Unix permissions for the file, if we create it.
res Resulting file handle.
Returns
0 on success, non-zero on failure.
staticintESECTmdb_env_open2(MDB_env*env)[static]
Further setup required for opening an LMDB environment
staticvoidmdb_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.
Parametersptr This points to the slot in the reader lock table.
staticintESECTmdb_env_share_locks(MDB_env*env,int*excl)[static]
Downgrade the exclusive lock on the region back to shared
staticintESECTmdb_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.
staticintESECTmdb_env_setup_locks(MDB_env*env,MDB_name*fname,intmode,int*excl)[static]
Open and/or initialize the lock region for the environment.
Parametersenv The LMDB environment.
fname Filename + scratch area, from mdb_fname_init().
mode The Unix permissions for the file, if we create it.
excl In -1, out lock type: -1 none, 0 shared, 1 exclusive
Returns
0 on success, non-zero on failure.
intESECTmdb_env_open(MDB_env*env,constchar*path,unsignedintflags,mdb_mode_tmode)
Open an environment handle. If this function fails, mdb_env_close() must be called to discard the MDB_env
handle.
Parametersenv An environment handle returned by mdb_env_create()path The directory in which the database files reside. This directory must already exist and be
writable.
flags Special options for this environment. This parameter must be set to 0 or by bitwise OR'ing
together one or more of the values described here. Flags set by mdb_env_set_flags() are also used.
• MDB_FIXEDMAP use a fixed address for the mmap region. This flag must be specified when creating the
environment, and is stored persistently in the environment. If successful, the memory map will
always reside at the same virtual address and pointers used to reference data items in the database
will be constant across multiple invocations. This option may not always work, depending on how the
operating system has allocated memory to shared libraries and other uses. The feature is highly
experimental.
• MDB_NOSUBDIR By default, LMDB creates its environment in a directory whose pathname is given in
path, and creates its data and lock files under that directory. With this option, path is used as-
is for the database main data file. The database lock file is the path with '-lock' appended.
• MDB_RDONLY Open the environment in read-only mode. No write operations will be allowed. LMDB will
still modify the lock file - except on read-only filesystems, where LMDB does not use locks.
• MDB_WRITEMAP Use a writeable memory map unless MDB_RDONLY is set. This uses fewer mallocs but loses
protection from application bugs like wild pointer writes and other bad updates into the database.
This may be slightly faster for DBs that fit entirely in RAM, but is slower for DBs larger than
RAM. Incompatible with nested transactions. Do not mix processes with and without MDB_WRITEMAP on
the same environment. This can defeat durability (mdb_env_sync etc).
• MDB_NOMETASYNC Flush system buffers to disk only once per transaction, omit the metadata flush.
Defer that until the system flushes files to disk, or next non-MDB_RDONLY commit or mdb_env_sync().
This optimization maintains database integrity, but a system crash may undo the last committed
transaction. I.e. it preserves the ACI (atomicity, consistency, isolation) but not D (durability)
database property. This flag may be changed at any time using mdb_env_set_flags().
• MDB_NOSYNC Don't flush system buffers to disk when committing a transaction. This optimization
means a system crash can corrupt the database or lose the last transactions if buffers are not yet
flushed to disk. The risk is governed by how often the system flushes dirty buffers to disk and how
often mdb_env_sync() is called. However, if the filesystem preserves write order and the
MDB_WRITEMAP flag is not used, transactions exhibit ACI (atomicity, consistency, isolation)
properties and only lose D (durability). I.e. database integrity is maintained, but a system crash
may undo the final transactions. Note that (MDB_NOSYNC | MDB_WRITEMAP) leaves the system with no
hint for when to write transactions to disk, unless mdb_env_sync() is called. (MDB_MAPASYNC |
MDB_WRITEMAP) may be preferable. This flag may be changed at any time using mdb_env_set_flags().
• MDB_MAPASYNC When using MDB_WRITEMAP, use asynchronous flushes to disk. As with MDB_NOSYNC, a
system crash can then corrupt the database or lose the last transactions. Calling mdb_env_sync()
ensures on-disk database integrity until next commit. This flag may be changed at any time using
mdb_env_set_flags().
• MDB_NOTLS Don't use Thread-Local Storage. Tie reader locktable slots to MDB_txn objects instead of
to threads. I.e. mdb_txn_reset() keeps the slot reserved for the MDB_txn object. A thread may use
parallel read-only transactions. A read-only transaction may span threads if the user synchronizes
its use. Applications that multiplex many user threads over individual OS threads need this option.
Such an application must also serialize the write transactions in an OS thread, since LMDB's write
locking is unaware of the user threads.
• MDB_NOLOCK Don't do any locking. If concurrent access is anticipated, the caller must manage all
concurrency itself. For proper operation the caller must enforce single-writer semantics, and must
ensure that no readers are using old transactions while a writer is active. The simplest approach
is to use an exclusive lock so that no readers may be active at all when a writer begins.
• MDB_NORDAHEAD Turn off readahead. Most operating systems perform readahead on read requests by
default. This option turns it off if the OS supports it. Turning it off may help random read
performance when the DB is larger than RAM and system RAM is full. The option is not implemented on
Windows.
• MDB_NOMEMINIT Don't initialize malloc'd memory before writing to unused spaces in the data file. By
default, memory for pages written to the data file is obtained using malloc. While these pages may
be reused in subsequent transactions, freshly malloc'd pages will be initialized to zeroes before
use. This avoids persisting leftover data from other code (that used the heap and subsequently
freed the memory) into the data file. Note that many other system libraries may allocate and free
memory from the heap for arbitrary uses. E.g., stdio may use the heap for file I/O buffers. This
initialization step has a modest performance cost so some applications may want to disable it using
this flag. This option can be a problem for applications which handle sensitive data like
passwords, and it makes memory checkers like Valgrind noisy. This flag is not needed with
MDB_WRITEMAP, which writes directly to the mmap instead of using malloc for pages. The
initialization is also skipped if MDB_RESERVE is used; the caller is expected to overwrite all of
the memory that was reserved in that case. This flag may be changed at any time using
mdb_env_set_flags().
mode The UNIX permissions to set on created files and semaphores. This parameter is ignored on
Windows.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• MDB_VERSION_MISMATCH - the version of the LMDB library doesn't match the version that created the
database environment.
• MDB_INVALID - the environment file headers are corrupted.
• ENOENT - the directory specified by the path parameter doesn't exist.
• EACCES - the user didn't have permission to access the environment files.
• EAGAIN - the environment was locked by another process.
voidESECTmdb_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.
Parametersenv An environment handle returned by mdb_env_create()staticintmdb_cmp_long(constMDB_val*a,constMDB_val*b)[static]
Compare two items pointing at aligned size_t's
staticintmdb_cmp_int(constMDB_val*a,constMDB_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 size_t.
staticintmdb_cmp_cint(constMDB_val*a,constMDB_val*b)[static]
Compare two items pointing at unsigned ints of unknown alignment. Nodes and keys are guaranteed to be
2-byte aligned.
staticintmdb_cmp_memn(constMDB_val*a,constMDB_val*b)[static]
Compare two items lexically
staticintmdb_cmp_memnr(constMDB_val*a,constMDB_val*b)[static]
Compare two items in reverse byte order
staticintmdb_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.
intmdb_get(MDB_txn*txn,MDB_dbidbi,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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()key The key to search for in the database
data The data corresponding to the key
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• MDB_NOTFOUND - the key was not in the database.
• EINVAL - an invalid parameter was specified.
intmdb_cursor_get(MDB_cursor*cursor,MDB_val*key,MDB_val*data,MDB_cursor_opop)
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.
Parameterscursor A cursor handle returned by mdb_cursor_open()key The key for a retrieved item
data The data of a retrieved item
op A cursor operation MDB_cursor_opReturns
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.
staticintmdb_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.
Parametersmc The cursor to operate on.
intmdb_cursor_put(MDB_cursor*cursor,MDB_val*key,MDB_val*data,unsignedintflags)
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.
Parameterscursor A cursor handle returned by mdb_cursor_open()key The key operated on.
data The data operated on.
flags Options for this operation. This parameter must be set to 0 or one of the values described
here.
• MDB_CURRENT - replace the item at the current cursor position. The key parameter must still be
provided, and must match it. If using sorted duplicates (MDB_DUPSORT) the data item must still sort
into the same place. This is intended to be used when the new data is the same size as the old.
Otherwise it will simply perform a delete of the old record followed by an insert.
• MDB_NODUPDATA - enter the new key/data pair only if it does not already appear in the database.
This flag may only be specified if the database was opened with MDB_DUPSORT. The function will
return MDB_KEYEXIST if the key/data pair already appears in the database.
• MDB_NOOVERWRITE - enter the new key/data pair only if the key does not already appear in the
database. The function will return MDB_KEYEXIST if the key already appears in the database, even if
the database supports duplicates (MDB_DUPSORT).
• MDB_RESERVE - reserve space for data of the given size, but don't copy the given data. Instead,
return a pointer to the reserved space, which the caller can fill in later - before the next update
operation or the transaction ends. This saves an extra memcpy if the data is being generated later.
This flag must not be specified if the database was opened with MDB_DUPSORT.
• MDB_APPEND - append the given key/data pair to the end of the database. No key comparisons are
performed. This option allows fast bulk loading when keys are already known to be in the correct
order. Loading unsorted keys with this flag will cause a MDB_KEYEXIST error.
• MDB_APPENDDUP - as above, but for sorted dup data.
• MDB_MULTIPLE - store multiple contiguous data elements in a single request. This flag may only be
specified if the database was opened with MDB_DUPFIXED. The data argument must be an array of two
MDB_vals. The mv_size of the first MDB_val must be the size of a single data element. The mv_data
of the first MDB_val must point to the beginning of the array of contiguous data elements. The
mv_size of the second MDB_val must be the count of the number of data elements to store. On return
this field will be set to the count of the number of elements actually written. The mv_data of the
second MDB_val is unused.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• MDB_MAP_FULL - the database is full, see mdb_env_set_mapsize().
• MDB_TXN_FULL - the transaction has too many dirty pages.
• EACCES - an attempt was made to write in a read-only transaction.
• EINVAL - an invalid parameter was specified.
intmdb_cursor_del(MDB_cursor*cursor,unsignedintflags)
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.
Parameterscursor A cursor handle returned by mdb_cursor_open()flags Options for this operation. This parameter must be set to 0 or one of the values described
here.
• MDB_NODUPDATA - delete all of the data items for the current key. This flag may only be specified
if the database was opened with MDB_DUPSORT.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EACCES - an attempt was made to write in a read-only transaction.
• EINVAL - an invalid parameter was specified.
intmdb_cursor_open(MDB_txn*txn,MDB_dbidbi,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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()cursor Address where the new MDB_cursor handle will be stored
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intmdb_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.
Parameterstxn A transaction handle returned by mdb_txn_begin()cursor A cursor handle returned by mdb_cursor_open()Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intmdb_cursor_count(MDB_cursor*cursor,size_t*countp)
Return count of duplicates for current key. This call is only valid on databases that support sorted
duplicate data items MDB_DUPSORT.
Parameterscursor A cursor handle returned by mdb_cursor_open()countp Address where the count will be stored
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - cursor is not initialized, or an invalid parameter was specified.
voidmdb_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.
Parameterscursor A cursor handle returned by mdb_cursor_open()MDB_txn*mdb_cursor_txn(MDB_cursor*cursor)
Return the cursor's transaction handle.
Parameterscursor A cursor handle returned by mdb_cursor_open()MDB_dbimdb_cursor_dbi(MDB_cursor*cursor)
Return the cursor's database handle.
Parameterscursor A cursor handle returned by mdb_cursor_open()staticvoidmdb_cursor_copy(constMDB_cursor*csrc,MDB_cursor*cdst)[static]
Copy the contents of a cursor.
Parameterscsrc The cursor to copy from.
cdst The cursor to copy to.
intmdb_del(MDB_txn*txn,MDB_dbidbi,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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()key The key to delete from the database
data The data to delete
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EACCES - an attempt was made to write in a read-only transaction.
• EINVAL - an invalid parameter was specified.
intmdb_put(MDB_txn*txn,MDB_dbidbi,MDB_val*key,MDB_val*data,unsignedintflags)
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).
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()key The key to store in the database
data The data to store
flags Special options for this operation. This parameter must be set to 0 or by bitwise OR'ing
together one or more of the values described here.
• MDB_NODUPDATA - enter the new key/data pair only if it does not already appear in the database.
This flag may only be specified if the database was opened with MDB_DUPSORT. The function will
return MDB_KEYEXIST if the key/data pair already appears in the database.
• MDB_NOOVERWRITE - enter the new key/data pair only if the key does not already appear in the
database. The function will return MDB_KEYEXIST if the key already appears in the database, even if
the database supports duplicates (MDB_DUPSORT). The data parameter will be set to point to the
existing item.
• MDB_RESERVE - reserve space for data of the given size, but don't copy the given data. Instead,
return a pointer to the reserved space, which the caller can fill in later - before the next update
operation or the transaction ends. This saves an extra memcpy if the data is being generated later.
LMDB does nothing else with this memory, the caller is expected to modify all of the space
requested. This flag must not be specified if the database was opened with MDB_DUPSORT.
• MDB_APPEND - append the given key/data pair to the end of the database. This option allows fast
bulk loading when keys are already known to be in the correct order. Loading unsorted keys with
this flag will cause a MDB_KEYEXIST error.
• MDB_APPENDDUP - as above, but for sorted dup data.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• MDB_MAP_FULL - the database is full, see mdb_env_set_mapsize().
• MDB_TXN_FULL - the transaction has too many dirty pages.
• EACCES - an attempt was made to write in a read-only transaction.
• EINVAL - an invalid parameter was specified.
staticTHREAD_RETESECTCALL_CONVmdb_env_copythr(void*arg)[static]
Dedicated writer thread for compacting copy.
staticintESECTmdb_env_cthr_toggle(mdb_copy*my,intadjust)[static]
Give buffer and/or MDB_EOF to writer thread, await unused buffer.
Parametersmy control structure.
adjust (1 to hand off 1 buffer) | (MDB_EOF when ending).
staticintESECTmdb_env_cwalk(mdb_copy*my,pgno_t*pg,intflags)[static]
Depth-first tree traversal for compacting copy.
Parametersmy control structure.
pg database root.
flags includes F_DUPDATA if it is a sorted-duplicate sub-DB.
staticintESECTmdb_env_copyfd1(MDB_env*env,HANDLEfd)[static]
Copy environment with compaction.
staticintESECTmdb_env_copyfd0(MDB_env*env,HANDLEfd)[static]
Copy environment as-is.
intESECTmdb_env_copy2(MDB_env*env,constchar*path,unsignedintflags)
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.
Parametersenv An environment handle returned by mdb_env_create(). It must have already been opened
successfully.
path The directory in which the copy will reside. This directory must already exist and be writable
but must otherwise be empty.
flags Special options for this operation. This parameter must be set to 0 or by bitwise OR'ing
together one or more of the values described here.
• MDB_CP_COMPACT - Perform compaction while copying: omit free pages and sequentially renumber all
pages in output. This option consumes more CPU and runs more slowly than the default. Currently it
fails if the environment has suffered a page leak.
Returns
A non-zero error value on failure and 0 on success.
intESECTmdb_env_copy(MDB_env*env,constchar*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.
Parametersenv An environment handle returned by mdb_env_create(). It must have already been opened
successfully.
path The directory in which the copy will reside. This directory must already exist and be writable
but must otherwise be empty.
Returns
A non-zero error value on failure and 0 on success.
intESECTmdb_env_set_flags(MDB_env*env,unsignedintflags,intonoff)
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.
Parametersenv An environment handle returned by mdb_env_create()flags The flags to change, bitwise OR'ed together
onoff A non-zero value sets the flags, zero clears them.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intESECTmdb_env_get_flags(MDB_env*env,unsignedint*flags)
Get environment flags.
Parametersenv An environment handle returned by mdb_env_create()flags The address of an integer to store the flags
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intESECTmdb_env_set_userctx(MDB_env*env,void*ctx)
Set application information associated with the MDB_env.
Parametersenv An environment handle returned by mdb_env_create()ctx An arbitrary pointer for whatever the application needs.
Returns
A non-zero error value on failure and 0 on success.
void*ESECTmdb_env_get_userctx(MDB_env*env)
Get the application information associated with the MDB_env.
Parametersenv An environment handle returned by mdb_env_create()Returns
The pointer set by mdb_env_set_userctx().
intESECTmdb_env_set_assert(MDB_env*env,MDB_assert_func*func)
Set or reset the assert() callback of the environment. Disabled if liblmdb is built with NDEBUG.
Note
This hack should become obsolete as lmdb's error handling matures.
Parametersenv An environment handle returned by mdb_env_create().
func An MDB_assert_func function, or 0.
Returns
A non-zero error value on failure and 0 on success.
intESECTmdb_env_get_path(MDB_env*env,constchar**path)
Return the path that was used in mdb_env_open().
Parametersenv An environment handle returned by mdb_env_create()path Address of a string pointer to contain the path. This is the actual string in the environment,
not a copy. It should not be altered in any way.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intESECTmdb_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.)
Parametersenv An environment handle returned by mdb_env_create()fd Address of a mdb_filehandle_t to contain the descriptor.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
staticintESECTmdb_stat0(MDB_env*env,MDB_db*db,MDB_stat*arg)[static]
Common code for mdb_stat() and mdb_env_stat().
Parametersenv the environment to operate in.
db the MDB_db record containing the stats to return.
arg the address of an MDB_stat structure to receive the stats.
Returns
0, this function always succeeds.
intESECTmdb_env_stat(MDB_env*env,MDB_stat*stat)
Return statistics about the LMDB environment.
Parametersenv An environment handle returned by mdb_env_create()stat The address of an MDB_stat structure where the statistics will be copied
intESECTmdb_env_info(MDB_env*env,MDB_envinfo*stat)
Return information about the LMDB environment.
Parametersenv An environment handle returned by mdb_env_create()stat The address of an MDB_envinfo structure where the information will be copied
intmdb_dbi_open(MDB_txn*txn,constchar*name,unsignedintflags,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.
Parameterstxn A transaction handle returned by mdb_txn_begin()name The name of the database to open. If only a single database is needed in the environment, this
value may be NULL.
flags Special options for this database. This parameter must be set to 0 or by bitwise OR'ing
together one or more of the values described here.
• MDB_REVERSEKEY Keys are strings to be compared in reverse order, from the end of the strings to the
beginning. By default, Keys are treated as strings and compared from beginning to end.
• MDB_DUPSORT Duplicate keys may be used in the database. (Or, from another perspective, keys may
have multiple data items, stored in sorted order.) By default keys must be unique and may have only
a single data item.
• MDB_INTEGERKEY Keys are binary integers in native byte order, either unsigned int or size_t, and
will be sorted as such. The keys must all be of the same size.
• MDB_DUPFIXED This flag may only be used in combination with MDB_DUPSORT. This option tells the
library that the data items for this database are all the same size, which allows further
optimizations in storage and retrieval. When all data items are the same size, the
MDB_GET_MULTIPLE, MDB_NEXT_MULTIPLE and MDB_PREV_MULTIPLE cursor operations may be used to retrieve
multiple items at once.
• MDB_INTEGERDUP This option specifies that duplicate data items are binary integers, similar to
MDB_INTEGERKEY keys.
• MDB_REVERSEDUP This option specifies that duplicate data items should be compared as strings in
reverse order.
• MDB_CREATE Create the named database if it doesn't exist. This option is not allowed in a read-only
transaction or a read-only environment.
dbi Address where the new MDB_dbi handle will be stored
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• MDB_NOTFOUND - the specified database doesn't exist in the environment and MDB_CREATE was not
specified.
• MDB_DBS_FULL - too many databases have been opened. See mdb_env_set_maxdbs().
intESECTmdb_stat(MDB_txn*txn,MDB_dbidbi,MDB_stat*stat)
Retrieve statistics for a database.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()stat The address of an MDB_stat structure where the statistics will be copied
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
voidmdb_dbi_close(MDB_env*env,MDB_dbidbi)
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.
Parametersenv An environment handle returned by mdb_env_create()dbi A database handle returned by mdb_dbi_open()intmdb_dbi_flags(MDB_txn*txn,MDB_dbidbi,unsignedint*flags)
Retrieve the DB flags for a database handle.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()flags Address where the flags will be returned.
Returns
A non-zero error value on failure and 0 on success.
intmdb_drop(MDB_txn*txn,MDB_dbidbi,intdel)
Empty or delete+close a database. See mdb_dbi_close() for restrictions about closing the DB handle.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()del 0 to empty the DB, 1 to delete it from the environment and close the DB handle.
Returns
A non-zero error value on failure and 0 on success.
intmdb_set_compare(MDB_txn*txn,MDB_dbidbi,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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()cmp A MDB_cmp_func function
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intmdb_set_dupsort(MDB_txn*txn,MDB_dbidbi,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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()cmp A MDB_cmp_func function
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intmdb_set_relfunc(MDB_txn*txn,MDB_dbidbi,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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()rel A MDB_rel_func function
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intmdb_set_relctx(MDB_txn*txn,MDB_dbidbi,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.
Parameterstxn A transaction handle returned by mdb_txn_begin()dbi A database handle returned by mdb_dbi_open()ctx An arbitrary pointer for whatever the application needs. It will be passed to the callback
function set by mdb_set_relfunc as its relctx parameter whenever the callback is invoked.
Returns
A non-zero error value on failure and 0 on success. Some possible errors are:
• EINVAL - an invalid parameter was specified.
intESECTmdb_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.
Parametersenv An environment handle returned by mdb_env_create()Returns
The maximum size of a key we can write
intESECTmdb_reader_list(MDB_env*env,MDB_msg_func*func,void*ctx)
Dump the entries in the reader lock table.
Parametersenv An environment handle returned by mdb_env_create()func A MDB_msg_func function
ctx Anything the message function needs
Returns
< 0 on failure, >= 0 on success.
staticintESECTmdb_pid_insert(MDB_PID_T*ids,MDB_PID_Tpid)[static]
Insert pid into list if not already present. return -1 if already present.
intESECTmdb_reader_check(MDB_env*env,int*dead)
Check for stale entries in the reader lock table.
Parametersenv An environment handle returned by mdb_env_create()dead Number of stale slots that were cleared
Returns
0 on success, non-zero on failure.
Install Now
PNG Icons
