Return Codes
BerkeleyDB uses -30800 to -30999, we'll go under them.
struct MDB_stat
Statistics for a database in the environment. struct MDB_envinfo
Information about the environment.
#define MDB_CP_COMPACT 0x01
#define mdb_open(txn, name, flags, dbi)
mdb_dbi_open(txn,name,flags,dbi)
#define mdb_close(env, dbi) mdb_dbi_close(env,dbi)
typedef void MDB_assert_func(MDB_env *env, const
char *msg)
A callback function for most LMDB assert() failures, called before printing
the message and aborting. typedef int() MDB_msg_func(const char *msg,
void *ctx)
A callback function used to print a message from the library.
enum MDB_cursor_op { MDB_FIRST,
MDB_FIRST_DUP, MDB_GET_BOTH, MDB_GET_BOTH_RANGE,
MDB_GET_CURRENT, MDB_GET_MULTIPLE, MDB_LAST,
MDB_LAST_DUP, MDB_NEXT, MDB_NEXT_DUP,
MDB_NEXT_MULTIPLE, MDB_NEXT_NODUP, MDB_PREV,
MDB_PREV_DUP, MDB_PREV_NODUP, MDB_SET,
MDB_SET_KEY, MDB_SET_RANGE, MDB_PREV_MULTIPLE }
Cursor Get operations.
char * mdb_version (int *major, int *minor, int *patch)
Return the LMDB library version information. char * mdb_strerror (int
err)
Return a string describing a given error code. int mdb_env_create
(MDB_env **env)
Create an LMDB environment handle. int mdb_env_open (MDB_env
*env, const char *path, unsigned int flags, mdb_mode_t mode)
Open an environment handle. int mdb_env_copy (MDB_env *env,
const char *path)
Copy an LMDB environment to the specified path. int mdb_env_copyfd
(MDB_env *env, mdb_filehandle_t fd)
Copy an LMDB environment to the specified file descriptor. int
mdb_env_copy2 (MDB_env *env, const char *path, unsigned int
flags)
Copy an LMDB environment to the specified path, with options. int
mdb_env_copyfd2 (MDB_env *env, mdb_filehandle_t fd, unsigned
int flags)
Copy an LMDB environment to the specified file descriptor, with options. int
mdb_env_stat (MDB_env *env, MDB_stat *stat)
Return statistics about the LMDB environment. int mdb_env_info
(MDB_env *env, MDB_envinfo *stat)
Return information about the LMDB environment. int mdb_env_sync
(MDB_env *env, int force)
Flush the data buffers to disk. void mdb_env_close (MDB_env
*env)
Close the environment and release the memory map. int mdb_env_set_flags
(MDB_env *env, unsigned int flags, int onoff)
Set environment flags. int mdb_env_get_flags (MDB_env *env,
unsigned int *flags)
Get environment flags. int mdb_env_get_path (MDB_env *env, const
char **path)
Return the path that was used in mdb_env_open(). int
mdb_env_get_fd (MDB_env *env, mdb_filehandle_t *fd)
Return the filedescriptor for the given environment. int
mdb_env_set_mapsize (MDB_env *env, size_t size)
Set the size of the memory map to use for this environment. int
mdb_env_set_maxreaders (MDB_env *env, unsigned int readers)
Set the maximum number of threads/reader slots for the environment. int
mdb_env_get_maxreaders (MDB_env *env, unsigned int *readers)
Get the maximum number of threads/reader slots for the environment. int
mdb_env_set_maxdbs (MDB_env *env, MDB_dbi dbs)
Set the maximum number of named databases for the environment. int
mdb_env_get_maxkeysize (MDB_env *env)
Get the maximum size of keys and MDB_DUPSORT data we can write. int
mdb_env_set_userctx (MDB_env *env, void *ctx)
Set application information associated with the MDB_env. void *
mdb_env_get_userctx (MDB_env *env)
Get the application information associated with the MDB_env. int
mdb_env_set_assert (MDB_env *env, MDB_assert_func
*func)
int mdb_txn_begin (MDB_env *env, MDB_txn *parent,
unsigned int flags, MDB_txn **txn)
Create a transaction for use with the environment. MDB_env *
mdb_txn_env (MDB_txn *txn)
Returns the transaction's MDB_env. size_t mdb_txn_id
(MDB_txn *txn)
Return the transaction's ID. int mdb_txn_commit (MDB_txn *txn)
Commit all the operations of a transaction into the database. void
mdb_txn_abort (MDB_txn *txn)
Abandon all the operations of the transaction instead of saving them. void
mdb_txn_reset (MDB_txn *txn)
Reset a read-only transaction. int mdb_txn_renew (MDB_txn *txn)
Renew a read-only transaction. int mdb_dbi_open (MDB_txn *txn,
const char *name, unsigned int flags, MDB_dbi *dbi)
Open a database in the environment. int mdb_stat (MDB_txn *txn,
MDB_dbi dbi, MDB_stat *stat)
Retrieve statistics for a database. int mdb_dbi_flags (MDB_txn
*txn, MDB_dbi dbi, unsigned int *flags)
Retrieve the DB flags for a database handle. void mdb_dbi_close
(MDB_env *env, MDB_dbi dbi)
Close a database handle. Normally unnecessary. Use with care: int
mdb_drop (MDB_txn *txn, MDB_dbi dbi, int del)
Empty or delete+close a database. int mdb_set_compare (MDB_txn
*txn, MDB_dbi dbi, MDB_cmp_func *cmp)
Set a custom key comparison function for a database. int
mdb_set_dupsort (MDB_txn *txn, MDB_dbi dbi,
MDB_cmp_func *cmp)
Set a custom data comparison function for a MDB_DUPSORT database. int
mdb_set_relfunc (MDB_txn *txn, MDB_dbi dbi,
MDB_rel_func *rel)
Set a relocation function for a MDB_FIXEDMAP database. int
mdb_set_relctx (MDB_txn *txn, MDB_dbi dbi, void *ctx)
Set a context pointer for a MDB_FIXEDMAP database's relocation
function. int mdb_get (MDB_txn *txn, MDB_dbi dbi,
MDB_val *key, MDB_val *data)
Get items from a database. int mdb_put (MDB_txn *txn,
MDB_dbi dbi, MDB_val *key, MDB_val *data, unsigned int
flags)
Store items into a database. int mdb_del (MDB_txn *txn,
MDB_dbi dbi, MDB_val *key, MDB_val *data)
Delete items from a database. int mdb_cursor_open (MDB_txn *txn,
MDB_dbi dbi, MDB_cursor **cursor)
Create a cursor handle. void mdb_cursor_close (MDB_cursor
*cursor)
Close a cursor handle. int mdb_cursor_renew (MDB_txn *txn,
MDB_cursor *cursor)
Renew a cursor handle. MDB_txn * mdb_cursor_txn
(MDB_cursor *cursor)
Return the cursor's transaction handle. MDB_dbi mdb_cursor_dbi
(MDB_cursor *cursor)
Return the cursor's database handle. int mdb_cursor_get
(MDB_cursor *cursor, MDB_val *key, MDB_val *data,
MDB_cursor_op op)
Retrieve by cursor. int mdb_cursor_put (MDB_cursor *cursor,
MDB_val *key, MDB_val *data, unsigned int flags)
Store by cursor. int mdb_cursor_del (MDB_cursor *cursor,
unsigned int flags)
Delete current key/data pair. int mdb_cursor_count (MDB_cursor
*cursor, size_t *countp)
Return count of duplicates for current key. int mdb_cmp (MDB_txn
*txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b)
Compare two data items according to a particular database. int mdb_dcmp
(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const
MDB_val *b)
Compare two data items according to a particular database. int
mdb_reader_list (MDB_env *env, MDB_msg_func *func, void
*ctx)
Dump the entries in the reader lock table. int mdb_reader_check
(MDB_env *env, int *dead)
Check for stale entries in the reader lock table.
Return the LMDB library version information.
Parameters
major if non-NULL, the library major version
number is copied here
minor if non-NULL, the library minor version number is copied here
patch if non-NULL, the library patch version number is copied here
Return values
version string The library version as a
string
Return the library version info.
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
err The error code
Return values
error message The description of the error
Create an LMDB environment handle. This function allocates memory
for a MDB_env structure. To release the allocated memory and discard
the handle, call mdb_env_close(). Before the handle may be used, it
must be opened using mdb_env_open(). Various other options may also
need to be set before opening the handle, e.g. mdb_env_set_mapsize(),
mdb_env_set_maxreaders(), mdb_env_set_maxdbs(), depending on
usage requirements.
Parameters
env The address where the new handle will be
stored
Returns
A non-zero error value on failure and 0 on success.
Open an environment handle. If this function fails,
mdb_env_close() must be called to discard the MDB_env
handle.
Parameters
env An environment handle returned by
mdb_env_create()
path The directory in which the database files reside. This directory
must already exist and be writable.
flags Special options for this environment. This parameter must be set to
0 or by bitwise OR'ing together one or more of the values described here.
Flags set by
mdb_env_set_flags() are also used.
- MDB_FIXEDMAP use a fixed address for the mmap region. This flag
must be specified when creating the environment, and is stored
persistently in the environment. If successful, the memory map will always
reside at the same virtual address and pointers used to reference data
items in the database will be constant across multiple invocations. This
option may not always work, depending on how the operating system has
allocated memory to shared libraries and other uses. The feature is highly
experimental.
- MDB_NOSUBDIR By default, LMDB creates its environment in a
directory whose pathname is given in path, and creates its data and
lock files under that directory. With this option, path is used
as-is for the database main data file. The database lock file is the
path with '-lock' appended.
- MDB_RDONLY Open the environment in read-only mode. No write
operations will be allowed. LMDB will still modify the lock file - except
on read-only filesystems, where LMDB does not use locks.
- MDB_WRITEMAP Use a writeable memory map unless MDB_RDONLY is set.
This uses fewer mallocs but loses protection from application bugs like
wild pointer writes and other bad updates into the database. This may be
slightly faster for DBs that fit entirely in RAM, but is slower for DBs
larger than RAM. Incompatible with nested transactions. Do not mix
processes with and without MDB_WRITEMAP on the same environment. This can
defeat durability (mdb_env_sync etc).
- MDB_NOMETASYNC Flush system buffers to disk only once per
transaction, omit the metadata flush. Defer that until the system flushes
files to disk, or next non-MDB_RDONLY commit or mdb_env_sync().
This optimization maintains database integrity, but a system crash may
undo the last committed transaction. I.e. it preserves the ACI (atomicity,
consistency, isolation) but not D (durability) database property. This
flag may be changed at any time using mdb_env_set_flags().
- MDB_NOSYNC Don't flush system buffers to disk when committing a
transaction. This optimization means a system crash can corrupt the
database or lose the last transactions if buffers are not yet flushed to
disk. The risk is governed by how often the system flushes dirty buffers
to disk and how often mdb_env_sync() is called. However, if the
filesystem preserves write order and the MDB_WRITEMAP flag is not
used, transactions exhibit ACI (atomicity, consistency, isolation)
properties and only lose D (durability). I.e. database integrity is
maintained, but a system crash may undo the final transactions. Note that
(MDB_NOSYNC | MDB_WRITEMAP) leaves the system with no hint
for when to write transactions to disk, unless mdb_env_sync() is
called. (MDB_MAPASYNC | MDB_WRITEMAP) may be preferable.
This flag may be changed at any time using
mdb_env_set_flags().
- MDB_MAPASYNC When using MDB_WRITEMAP, use asynchronous
flushes to disk. As with MDB_NOSYNC, a system crash can then
corrupt the database or lose the last transactions. Calling
mdb_env_sync() ensures on-disk database integrity until next
commit. This flag may be changed at any time using
mdb_env_set_flags().
- MDB_NOTLS Don't use Thread-Local Storage. Tie reader locktable
slots to MDB_txn objects instead of to threads. I.e.
mdb_txn_reset() keeps the slot 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().
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.
Copy an LMDB environment to the specified path. This function may
be used to make a backup of an existing environment. No lockfile is created,
since it gets recreated at need.
Note
This call can trigger significant file size growth if run
in parallel with write transactions, because it employs a read-only
transaction. See long-lived transactions under Caveats.
Parameters
env An environment handle returned by
mdb_env_create(). It must have already been opened successfully.
path The directory in which the copy will reside. This directory must
already exist and be writable but must otherwise be empty.
Returns
A non-zero error value on failure and 0 on success.
Copy an LMDB environment to the specified file descriptor. This
function may be used to make a backup of an existing environment. No
lockfile is created, since it gets recreated at need.
Note
This call can trigger significant file size growth if run
in parallel with write transactions, because it employs a read-only
transaction. See long-lived transactions under Caveats.
Parameters
env An environment handle returned by
mdb_env_create(). It must have already been opened successfully.
fd The filedescriptor to write the copy to. It must have already been
opened for Write access.
Returns
A non-zero error value on failure and 0 on success.
Copy an LMDB environment to the specified path, with options. This
function may be used to make a backup of an existing environment. No
lockfile is created, since it gets recreated at need.
Note
This call can trigger significant file size growth if run
in parallel with write transactions, because it employs a read-only
transaction. See long-lived transactions under Caveats.
Parameters
env An environment handle returned by
mdb_env_create(). It must have already been opened successfully.
path The directory in which the copy will reside. This directory must
already exist and be writable but must otherwise be empty.
flags Special options for this operation. This parameter must be set to 0
or by bitwise OR'ing together one or more of the values described here.
- •
- MDB_CP_COMPACT - Perform compaction while copying: omit free pages
and sequentially renumber all pages in output. This option consumes more
CPU and runs more slowly than the default. Currently it fails if the
environment has suffered a page leak.
Returns
A non-zero error value on failure and 0 on success.
Copy an LMDB environment to the specified file descriptor, with
options. This function may be used to make a backup of an existing
environment. No lockfile is created, since it gets recreated at need. See
mdb_env_copy2() for further details.
Note
This call can trigger significant file size growth if run
in parallel with write transactions, because it employs a read-only
transaction. See long-lived transactions under Caveats.
Parameters
env An environment handle returned by
mdb_env_create(). It must have already been opened successfully.
fd The filedescriptor to write the copy to. It must have already been
opened for Write access.
flags Special options for this operation. See mdb_env_copy2() for
options.
Returns
A non-zero error value on failure and 0 on success.
Return statistics about the LMDB environment.
Parameters
env An environment handle returned by
mdb_env_create()
stat The address of an MDB_stat structure where the statistics
will be copied
Return information about the LMDB environment.
Parameters
env An environment handle returned by
mdb_env_create()
stat The address of an MDB_envinfo structure where the information
will be copied
Flush the data buffers to disk. Data is always written to disk
when mdb_txn_commit() is called, but the operating system may keep it
buffered. LMDB always flushes the OS buffers upon commit as well, unless the
environment was opened with MDB_NOSYNC or in part
MDB_NOMETASYNC. This call is not valid if the environment was opened
with MDB_RDONLY.
Parameters
env An environment handle returned by
mdb_env_create()
force If non-zero, force a synchronous flush. Otherwise if the
environment has the MDB_NOSYNC flag set the flushes will be omitted,
and with MDB_MAPASYNC they will be asynchronous.
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- EACCES - the environment is read-only.
- EINVAL - an invalid parameter was specified.
- EIO - an error occurred during synchronization.
Close the environment and release the memory map. Only a single
thread may call this function. All transactions, databases, and cursors must
already be closed before calling this function. Attempts to use any such
handles after calling this function will cause a SIGSEGV. The environment
handle will be freed and must not be used again after this call.
Parameters
env An environment handle returned by
mdb_env_create()
Set environment flags. This may be used to set some flags in
addition to those from mdb_env_open(), or to unset these flags. If
several threads change the flags at the same time, the result is
undefined.
Parameters
env An environment handle returned by
mdb_env_create()
flags The flags to change, bitwise OR'ed together
onoff A non-zero value sets the flags, zero clears them.
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Get environment flags.
Parameters
env An environment handle returned by
mdb_env_create()
flags The address of an integer to store the flags
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Return the path that was used in mdb_env_open().
Parameters
env An environment handle returned by
mdb_env_create()
path Address of a string pointer to contain the path. This is the actual
string in the environment, not a copy. It should not be altered in any
way.
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Return the filedescriptor for the given environment. This function
may be called after fork(), so the descriptor can be closed before exec*().
Other LMDB file descriptors have FD_CLOEXEC. (Until LMDB 0.9.18, only the
lockfile had that.)
Parameters
env An environment handle returned by
mdb_env_create()
fd Address of a mdb_filehandle_t to contain the descriptor.
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Set the size of the memory map to use for this environment. The
size should be a multiple of the OS page size. The default is 10485760
bytes. The size of the memory map is also the maximum size of the database.
The value should be chosen as large as possible, to accommodate future
growth of the database. This function should be called after
mdb_env_create() and before mdb_env_open(). It may be called
at later times if no transactions are active in this process. Note that the
library does not check for this condition, the caller must ensure it
explicitly.
The new size takes effect immediately for the current process but
will not be persisted to any others until a write transaction has been
committed by the current process. Also, only mapsize increases are persisted
into the environment.
If the mapsize is increased by another process, and data has grown
beyond the range of the current mapsize, mdb_txn_begin() will return
MDB_MAP_RESIZED. This function may be called with a size of zero to
adopt the new size.
Any attempt to set a size smaller than the space already consumed
by the environment will be silently changed to the current size of the used
space.
Parameters
env An environment handle returned by
mdb_env_create()
size The size in bytes
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified, or the environment has an
active write transaction.
Set the maximum number of threads/reader slots for the
environment. This defines the number of slots in the lock table that is used
to track readers in the the environment. The default is 126. Starting a
read-only transaction normally ties a lock table slot to the current thread
until the environment closes or the thread exits. If MDB_NOTLS is in use,
mdb_txn_begin() instead ties the slot to the MDB_txn object
until it or the MDB_env object is destroyed. This function may only
be called after mdb_env_create() and before
mdb_env_open().
Parameters
env An environment handle returned by
mdb_env_create()
readers The maximum number of reader lock table slots
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified, or the environment is already
open.
Get the maximum number of threads/reader slots for the
environment.
Parameters
env An environment handle returned by
mdb_env_create()
readers Address of an integer to store the number of readers
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Set the maximum number of named databases for the environment.
This function is only needed if multiple databases will be used in the
environment. Simpler applications that use the environment as a single
unnamed database can ignore this option. This function may only be called
after mdb_env_create() and before mdb_env_open().
Currently a moderate number of slots are cheap but a huge number
gets expensive: 7-120 words per transaction, and every mdb_dbi_open()
does a linear search of the opened slots.
Parameters
env An environment handle returned by
mdb_env_create()
dbs The maximum number of databases
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified, or the environment is already
open.
Get the maximum size of keys and MDB_DUPSORT data we can
write. Depends on the compile-time constant MDB_MAXKEYSIZE. Default
511. See MDB_val.
Parameters
env An environment handle returned by
mdb_env_create()
Returns
The maximum size of a key we can write
Set application information associated with the
MDB_env.
Parameters
env An environment handle returned by
mdb_env_create()
ctx An arbitrary pointer for whatever the application needs.
Returns
A non-zero error value on failure and 0 on success.
Get the application information associated with the
MDB_env.
Parameters
env An environment handle returned by
mdb_env_create()
Returns
The pointer set by mdb_env_set_userctx().
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
env An environment handle returned by
mdb_env_create().
func An MDB_assert_func function, or 0.
Returns
A non-zero error value on failure and 0 on success.
Create a transaction for use with the environment. The transaction
handle may be discarded using mdb_txn_abort() or
mdb_txn_commit().
Note
A transaction and its cursors must only be used by a
single thread, and a thread may only have a single transaction at a time. If
MDB_NOTLS is in use, this does not apply to read-only transactions.
Cursors may not span transactions.
Parameters
env An environment handle returned by
mdb_env_create()
parent If this parameter is non-NULL, the new transaction will be a
nested transaction, with the transaction indicated by
parent as its
parent. Transactions may be nested to any level. A parent transaction and its
cursors may not issue any other operations than mdb_txn_commit and
mdb_txn_abort while it has active child transactions.
flags Special options for this transaction. This parameter must be set to
0 or by bitwise OR'ing together one or more of the values described here.
- •
- MDB_RDONLY This transaction will not perform any write
operations.
txn Address where the new MDB_txn handle will be
stored
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- MDB_PANIC - a fatal error occurred earlier and the environment must
be shut down.
- MDB_MAP_RESIZED - another process wrote data beyond this
MDB_env's mapsize and this environment's map must be resized as
well. See mdb_env_set_mapsize().
- MDB_READERS_FULL - a read-only transaction was requested and the
reader lock table is full. See mdb_env_set_maxreaders().
- ENOMEM - out of memory.
MDB_env* mdb_txn_env (MDB_txn * txn)
Returns the transaction's MDB_env.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
Return the transaction's ID. This returns the identifier
associated with this transaction. For a read-only transaction, this
corresponds to the snapshot being read; concurrent readers will frequently
have the same transaction ID.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
Returns
A transaction ID, valid if input is an active
transaction.
Commit all the operations of a transaction into the database. The
transaction handle is freed. It and its cursors must not be used again after
this call, except with mdb_cursor_renew().
Note
Earlier documentation incorrectly said all cursors would
be freed. Only write-transactions free cursors.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- EINVAL - an invalid parameter was specified.
- ENOSPC - no more disk space.
- EIO - a low-level I/O error occurred while writing.
- ENOMEM - out of memory.
Abandon all the operations of the transaction instead of saving
them. The transaction handle is freed. It and its cursors must not be used
again after this call, except with mdb_cursor_renew().
Note
Earlier documentation incorrectly said all cursors would
be freed. Only write-transactions free cursors.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
Reset a read-only transaction. Abort the transaction like
mdb_txn_abort(), but keep the transaction handle.
mdb_txn_renew() may reuse the handle. This saves allocation overhead
if the process will start a new read-only transaction soon, and also locking
overhead if MDB_NOTLS is in use. The reader table lock is released,
but the table slot stays tied to its thread or MDB_txn. Use
mdb_txn_abort() to discard a reset handle, and to free its lock table
slot if MDB_NOTLS is in use. Cursors opened within the transaction must not
be used again after this call, except with mdb_cursor_renew(). Reader
locks generally don't interfere with writers, but they keep old versions of
database pages allocated. Thus they prevent the old pages from being reused
when writers commit new data, and so under heavy load the database size may
grow much more rapidly than otherwise.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
Renew a read-only transaction. This acquires a new reader lock for
a transaction handle that had been released by mdb_txn_reset(). It
must be called before a reset transaction may be used again.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- MDB_PANIC - a fatal error occurred earlier and the environment must
be shut down.
- EINVAL - an invalid parameter was specified.
Open a database in the environment. A database handle denotes the
name and parameters of a database, independently of whether such a database
exists. The database handle may be discarded by calling
mdb_dbi_close(). The old database handle is returned if the database
was already open. The handle may only be closed once.
The database handle will be private to the current transaction
until the transaction is successfully committed. If the transaction is
aborted the handle will be closed automatically. After a successful commit
the handle will reside in the shared environment, and may be used by other
transactions.
This function must not be called from multiple concurrent
transactions in the same process. A transaction that uses this function must
finish (either commit or abort) before any other transaction in the process
may use this function.
To use named databases (with name != NULL),
mdb_env_set_maxdbs() must be called before opening the environment.
Database names are keys in the unnamed database, and may be read but not
written.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
name The name of the database to open. If only a single database is
needed in the environment, this value may be NULL.
flags Special options for this database. This parameter must be set to 0
or by bitwise OR'ing together one or more of the values described here.
- MDB_REVERSEKEY Keys are strings to be compared in reverse order,
from the end of the strings to the beginning. By default, Keys are treated
as strings and compared from beginning to end.
- MDB_DUPSORT Duplicate keys may be used in the database. (Or, from
another perspective, keys may have multiple data items, stored in sorted
order.) By default keys must be unique and may have only a single data
item.
- MDB_INTEGERKEY Keys are binary integers in native byte order,
either unsigned int or size_t, and will be sorted as such. The keys must
all be of the same size.
- MDB_DUPFIXED This flag may only be used in combination with
MDB_DUPSORT. This option tells the library that the data items for
this database are all the same size, which allows further optimizations in
storage and retrieval. When all data items are the same size, the
MDB_GET_MULTIPLE, MDB_NEXT_MULTIPLE and
MDB_PREV_MULTIPLE cursor operations may be used to retrieve
multiple items at once.
- MDB_INTEGERDUP This option specifies that duplicate data items are
binary integers, similar to MDB_INTEGERKEY keys.
- MDB_REVERSEDUP This option specifies that duplicate data items
should be compared as strings in reverse order.
- MDB_CREATE Create the named database if it doesn't exist. This
option is not allowed in a read-only transaction or a read-only
environment.
dbi Address where the new MDB_dbi handle will be
stored
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- MDB_NOTFOUND - the specified database doesn't exist in the
environment and MDB_CREATE was not specified.
- MDB_DBS_FULL - too many databases have been opened. See
mdb_env_set_maxdbs().
Retrieve statistics for a database.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
stat The address of an MDB_stat structure where the statistics
will be copied
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Retrieve the DB flags for a database handle.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
flags Address where the flags will be returned.
Returns
A non-zero error value on failure and 0 on success.
Close a database handle. Normally unnecessary. Use with care: This
call is not mutex protected. Handles should only be closed by a single
thread, and only if no other threads are going to reference the database
handle or one of its cursors any further. Do not close a handle if an
existing transaction has modified its database. Doing so can cause
misbehavior from database corruption to errors like MDB_BAD_VALSIZE (since
the DB name is gone).
Closing a database handle is not necessary, but lets
mdb_dbi_open() reuse the handle value. Usually it's better to set a
bigger mdb_env_set_maxdbs(), unless that value would be large.
Parameters
env An environment handle returned by
mdb_env_create()
dbi A database handle returned by mdb_dbi_open()
Empty or delete+close a database. See mdb_dbi_close() for
restrictions about closing the DB handle.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
del 0 to empty the DB, 1 to delete it from the environment and close the
DB handle.
Returns
A non-zero error value on failure and 0 on success.
Set a custom key comparison function for a database. The
comparison function is called whenever it is necessary to compare a key
specified by the application with a key currently stored in the database. If
no comparison function is specified, and no special key flags were specified
with mdb_dbi_open(), the keys are compared lexically, with shorter
keys collating before longer keys.
Warning
This function must be called before any data access
functions are used, otherwise data corruption may occur. The same comparison
function must be used by every program accessing the database, every time the
database is used.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
cmp A MDB_cmp_func function
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Set a custom data comparison function for a MDB_DUPSORT
database. This comparison function is called whenever it is necessary to
compare a data item specified by the application with a data item currently
stored in the database. This function only takes effect if the database was
opened with the MDB_DUPSORT flag. If no comparison function is
specified, and no special key flags were specified with
mdb_dbi_open(), the data items are compared lexically, with shorter
items collating before longer items.
Warning
This function must be called before any data access
functions are used, otherwise data corruption may occur. The same comparison
function must be used by every program accessing the database, every time the
database is used.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
cmp A MDB_cmp_func function
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Set a relocation function for a MDB_FIXEDMAP database.
Todo
The relocation function is called whenever it is
necessary to move the data of an item to a different position in the database
(e.g. through tree balancing operations, shifts as a result of adds or
deletes, etc.). It is intended to allow address/position-dependent data items
to be stored in a database in an environment opened with the
MDB_FIXEDMAP option. Currently the relocation feature is unimplemented
and setting this function has no effect.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
rel A MDB_rel_func function
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Set a context pointer for a MDB_FIXEDMAP database's
relocation function. See mdb_set_relfunc and MDB_rel_func for
more details.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
ctx An arbitrary pointer for whatever the application needs. It will be
passed to the callback function set by mdb_set_relfunc as its
relctx parameter whenever the callback is invoked.
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Get items from a database. This function retrieves key/data pairs
from the database. The address and length of the data associated with the
specified key are returned in the structure to which data
refers. If the database supports duplicate keys (MDB_DUPSORT) then
the first data item for the key will be returned. Retrieval of other items
requires the use of mdb_cursor_get().
Note
The memory pointed to by the returned values is owned by
the database. The caller need not dispose of the memory, and may not modify it
in any way. For values returned in a read-only transaction any modification
attempts will cause a SIGSEGV.
Values returned from the database are valid only until a
subsequent update operation, or the end of the transaction.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
key The key to search for in the database
data The data corresponding to the key
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- MDB_NOTFOUND - the key was not in the database.
- EINVAL - an invalid parameter was specified.
Store items into a database. This function stores key/data pairs
in the database. The default behavior is to enter the new key/data pair,
replacing any previously existing key if duplicates are disallowed, or
adding a duplicate data item if duplicates are allowed
(MDB_DUPSORT).
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by
mdb_dbi_open()
key The key to store in the database
data The data to store
flags Special options for this operation. This parameter must be set to 0
or by bitwise OR'ing together one or more of the values described here.
- MDB_NODUPDATA - enter the new key/data pair only if it does not
already appear in the database. This flag may only be specified if the
database was opened with MDB_DUPSORT. The function will return
MDB_KEYEXIST if the key/data pair already appears in the
database.
- MDB_NOOVERWRITE - enter the new key/data pair only if the key does
not already appear in the database. The function will return
MDB_KEYEXIST if the key already appears in the database, even if
the database supports duplicates (MDB_DUPSORT). The data
parameter will be set to point to the existing item.
- MDB_RESERVE - reserve space for data of the given size, but don't
copy the given data. Instead, return a pointer to the reserved space,
which the caller can fill in later - before the next update operation or
the transaction ends. This saves an extra memcpy if the data is being
generated later. LMDB does nothing else with this memory, the caller is
expected to modify all of the space requested. This flag must not be
specified if the database was opened with MDB_DUPSORT.
- MDB_APPEND - append the given key/data pair to the end of the
database. This option allows fast bulk loading when keys are already known
to be in the correct order. Loading unsorted keys with this flag will
cause a MDB_KEYEXIST error.
- MDB_APPENDDUP - as above, but for sorted dup data.
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- MDB_MAP_FULL - the database is full, see
mdb_env_set_mapsize().
- MDB_TXN_FULL - the transaction has too many dirty pages.
- EACCES - an attempt was made to write in a read-only transaction.
- EINVAL - an invalid parameter was specified.
Delete items from a database. This function removes key/data pairs
from the database. If the database does not support sorted duplicate data
items (MDB_DUPSORT) the data parameter is ignored. If the database
supports sorted duplicates and the data parameter is NULL, all of the
duplicate data items for the key will be deleted. Otherwise, if the data
parameter is non-NULL only the matching data item will be deleted. This
function will return MDB_NOTFOUND if the specified key/data pair is
not in the database.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
key The key to delete from the database
data The data to delete
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- EACCES - an attempt was made to write in a read-only transaction.
- EINVAL - an invalid parameter was specified.
Create a cursor handle. A cursor is associated with a specific
transaction and database. A cursor cannot be used when its database handle
is closed. Nor when its transaction has ended, except with
mdb_cursor_renew(). It can be discarded with
mdb_cursor_close(). A cursor in a write-transaction can be closed
before its transaction ends, and will otherwise be closed when its
transaction ends. A cursor in a read-only transaction must be closed
explicitly, before or after its transaction ends. It can be reused with
mdb_cursor_renew() before finally closing it.
Note
Earlier documentation said that cursors in every
transaction were closed when the transaction committed or aborted.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
cursor Address where the new MDB_cursor handle will be
stored
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
Close a cursor handle. The cursor handle will be freed and must
not be used again after this call. Its transaction must still be live if it
is a write-transaction.
Parameters
cursor A cursor handle returned by
mdb_cursor_open()
Renew a cursor handle. A cursor is associated with a specific
transaction and database. Cursors that are only used in read-only
transactions may be re-used, to avoid unnecessary malloc/free overhead. The
cursor may be associated with a new read-only transaction, and referencing
the same database handle as it was created with. This may be done whether
the previous transaction is live or dead.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
cursor A cursor handle returned by mdb_cursor_open()
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - an invalid parameter was specified.
MDB_txn* mdb_cursor_txn (MDB_cursor * cursor)
Return the cursor's transaction handle.
Parameters
cursor A cursor handle returned by
mdb_cursor_open()
MDB_dbi mdb_cursor_dbi (MDB_cursor * cursor)
Return the cursor's database handle.
Parameters
cursor A cursor handle returned by
mdb_cursor_open()
Retrieve by cursor. This function retrieves key/data pairs from
the database. The address and length of the key are returned in the object
to which key refers (except for the case of the MDB_SET
option, in which the key object is unchanged), and the address and
length of the data are returned in the object to which data refers.
See mdb_get() for restrictions on using the output values.
Parameters
cursor A cursor handle returned by
mdb_cursor_open()
key The key for a retrieved item
data The data of a retrieved item
op A cursor operation MDB_cursor_op
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- MDB_NOTFOUND - no matching key found.
- EINVAL - an invalid parameter was specified.
Store by cursor. This function stores key/data pairs into the
database. The cursor is positioned at the new item, or on failure usually
near it.
Note
Earlier documentation incorrectly said errors would leave
the state of the cursor unchanged.
Parameters
cursor A cursor handle returned by
mdb_cursor_open()
key The key operated on.
data The data operated on.
flags Options for this operation. This parameter must be set to 0 or one
of the values described here.
- MDB_CURRENT - replace the item at the current cursor position. The
key parameter must still be provided, and must match it. If using
sorted duplicates (MDB_DUPSORT) the data item must still sort into
the same place. This is intended to be used when the new data is the same
size as the old. Otherwise it will simply perform a delete of the old
record followed by an insert.
- MDB_NODUPDATA - enter the new key/data pair only if it does not
already appear in the database. This flag may only be specified if the
database was opened with MDB_DUPSORT. The function will return
MDB_KEYEXIST if the key/data pair already appears in the
database.
- MDB_NOOVERWRITE - enter the new key/data pair only if the key does
not already appear in the database. The function will return
MDB_KEYEXIST if the key already appears in the database, even if
the database supports duplicates (MDB_DUPSORT).
- MDB_RESERVE - reserve space for data of the given size, but don't
copy the given data. Instead, return a pointer to the reserved space,
which the caller can fill in later - before the next update operation or
the transaction ends. This saves an extra memcpy if the data is being
generated later. This flag must not be specified if the database was
opened with MDB_DUPSORT.
- MDB_APPEND - append the given key/data pair to the end of the
database. No key comparisons are performed. This option allows fast bulk
loading when keys are already known to be in the correct order. Loading
unsorted keys with this flag will cause a MDB_KEYEXIST error.
- MDB_APPENDDUP - as above, but for sorted dup data.
- MDB_MULTIPLE - store multiple contiguous data elements in a single
request. This flag may only be specified if the database was opened with
MDB_DUPFIXED. The data argument must be an array of two
MDB_vals. The mv_size of the first MDB_val must be the size of a
single data element. The mv_data of the first MDB_val must point to
the beginning of the array of contiguous data elements. The mv_size of the
second MDB_val must be the count of the number of data elements to
store. On return this field will be set to the count of the number of
elements actually written. The mv_data of the second MDB_val is
unused.
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- MDB_MAP_FULL - the database is full, see
mdb_env_set_mapsize().
- MDB_TXN_FULL - the transaction has too many dirty pages.
- EACCES - an attempt was made to write in a read-only transaction.
- EINVAL - an invalid parameter was specified.
Delete current key/data pair. This function deletes the key/data
pair to which the cursor refers. This does not invalidate the cursor, so
operations such as MDB_NEXT can still be used on it. Both MDB_NEXT and
MDB_GET_CURRENT will return the same record after this operation.
Parameters
cursor A cursor handle returned by
mdb_cursor_open()
flags Options for this operation. This parameter must be set to 0 or one
of the values described here.
- •
- MDB_NODUPDATA - delete all of the data items for the current key.
This flag may only be specified if the database was opened with
MDB_DUPSORT.
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- EACCES - an attempt was made to write in a read-only transaction.
- EINVAL - an invalid parameter was specified.
Return count of duplicates for current key. This call is only
valid on databases that support sorted duplicate data items
MDB_DUPSORT.
Parameters
cursor A cursor handle returned by
mdb_cursor_open()
countp Address where the count will be stored
Returns
A non-zero error value on failure and 0 on success. Some
possible errors are:
- •
- EINVAL - cursor is not initialized, or an invalid parameter was
specified.
Compare two data items according to a particular database. This
returns a comparison as if the two data items were keys in the specified
database.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
a The first item to compare
b The second item to compare
Returns
< 0 if a < b, 0 if a == b, > 0 if a > b
Compare two data items according to a particular database. This
returns a comparison as if the two items were data items of the specified
database. The database must have the MDB_DUPSORT flag.
Parameters
txn A transaction handle returned by
mdb_txn_begin()
dbi A database handle returned by mdb_dbi_open()
a The first item to compare
b The second item to compare
Returns
< 0 if a < b, 0 if a == b, > 0 if a > b
Dump the entries in the reader lock table.
Parameters
env An environment handle returned by
mdb_env_create()
func A MDB_msg_func function
ctx Anything the message function needs
Returns
< 0 on failure, >= 0 on success.
Check for stale entries in the reader lock table.
Parameters
env An environment handle returned by
mdb_env_create()
dead Number of stale slots that were cleared
Returns
0 on success, non-zero on failure.