LMDB
|
OpenLDAP Lightning Memory-Mapped Database Manager. More...
Modules | |
Version Macros | |
Environment Flags | |
Database Flags | |
Write Flags | |
Copy Flags | |
Return Codes | |
Data Structures | |
struct | MDB_val |
Generic structure used for passing keys and data in and out of the database. More... | |
struct | MDB_stat |
Statistics for a database in the environment. More... | |
struct | MDB_envinfo |
Information about the environment. More... | |
Macros | |
#define | mdb_open(txn, name, flags, dbi) mdb_dbi_open(txn,name,flags,dbi) |
#define | mdb_close(env, dbi) mdb_dbi_close(env,dbi) |
Typedefs | |
typedef unsigned int | MDB_dbi |
A handle for an individual database in the DB environment. | |
typedef int( | MDB_cmp_func )(const MDB_val *a, const MDB_val *b) |
A callback function used to compare two keys in a database. | |
typedef void( | MDB_rel_func )(MDB_val *item, void *oldptr, void *newptr, void *relctx) |
A callback function used to relocate a position-dependent data item in a fixed-address database. | |
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. | |
Enumerations | |
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 } |
Cursor Get operations. More... | |
Functions | |
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. | |
OpenLDAP Lightning Memory-Mapped Database Manager.
struct MDB_val |
Generic structure used for passing keys and data in and out of the database.
Values returned from the database are valid only until a subsequent update operation, or the end of the transaction. Do not modify or free them, they commonly point into the database itself.
Key sizes must be between 1 and mdb_env_get_maxkeysize() inclusive. The same applies to data sizes in databases with the MDB_DUPSORT flag. Other data items can in theory be from 0 to 0xffffffff bytes long.
Data Fields | |
size_t | mv_size |
void * | mv_data |
size_t MDB_val::mv_size |
size of the data item
void* MDB_val::mv_data |
address of the data item
struct MDB_stat |
Statistics for a database in the environment.
Data Fields | |
unsigned int | ms_psize |
unsigned int | ms_depth |
size_t | ms_branch_pages |
size_t | ms_leaf_pages |
size_t | ms_overflow_pages |
size_t | ms_entries |
unsigned int MDB_stat::ms_psize |
Size of a database page. This is currently the same for all databases.
unsigned int MDB_stat::ms_depth |
Depth (height) of the B-tree
size_t MDB_stat::ms_branch_pages |
Number of internal (non-leaf) pages
size_t MDB_stat::ms_leaf_pages |
Number of leaf pages
size_t MDB_stat::ms_overflow_pages |
Number of overflow pages
size_t MDB_stat::ms_entries |
Number of data items
struct MDB_envinfo |
Information about the environment.
Data Fields | |
void * | me_mapaddr |
size_t | me_mapsize |
size_t | me_last_pgno |
size_t | me_last_txnid |
unsigned int | me_maxreaders |
unsigned int | me_numreaders |
void* MDB_envinfo::me_mapaddr |
Address of map, if fixed
size_t MDB_envinfo::me_mapsize |
Size of the data memory map
size_t MDB_envinfo::me_last_pgno |
ID of the last used page
size_t MDB_envinfo::me_last_txnid |
ID of the last committed transaction
unsigned int MDB_envinfo::me_maxreaders |
max reader slots in the environment
unsigned int MDB_envinfo::me_numreaders |
max reader slots used in the environment
#define mdb_open | ( | txn, | |
name, | |||
flags, | |||
dbi | |||
) | mdb_dbi_open(txn,name,flags,dbi) |
Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project
#define mdb_close | ( | env, | |
dbi | |||
) | mdb_dbi_close(env,dbi) |
Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project
typedef void( MDB_rel_func)(MDB_val *item, void *oldptr, void *newptr, void *relctx) |
A callback function used to relocate a position-dependent data item in a fixed-address database.
The newptr gives the item's desired address in the memory map, and oldptr gives its previous address. The item's actual data resides at the address in item. This callback is expected to walk through the fields of the record in item and modify any values based at the oldptr address to be relative to the newptr address.
[in,out] | item | The item that is to be relocated. |
[in] | oldptr | The previous address. |
[in] | newptr | The new address to relocate to. |
[in] | relctx | An application-provided context, set by mdb_set_relctx(). |
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.
[in] | env | An environment handle returned by mdb_env_create(). |
[in] | msg | The assertion message, not including newline. |
typedef int( MDB_msg_func)(const char *msg, void *ctx) |
A callback function used to print a message from the library.
[in] | msg | The string to be printed. |
[in] | ctx | An arbitrary context pointer for the callback. |
enum MDB_cursor_op |
Cursor Get operations.
This is the set of all operations for retrieving data using a cursor.
Enumerator | |
---|---|
MDB_FIRST |
Position at first key/data item |
MDB_FIRST_DUP |
Position at first data item of current key. Only for MDB_DUPSORT |
MDB_GET_BOTH |
Position at key/data pair. Only for MDB_DUPSORT |
MDB_GET_BOTH_RANGE |
position at key, nearest data. Only for MDB_DUPSORT |
MDB_GET_CURRENT |
Return key/data at current cursor position |
MDB_GET_MULTIPLE |
Return key and up to a page of duplicate data items from current cursor position. Move cursor to prepare for MDB_NEXT_MULTIPLE. Only for MDB_DUPFIXED |
MDB_LAST |
Position at last key/data item |
MDB_LAST_DUP |
Position at last data item of current key. Only for MDB_DUPSORT |
MDB_NEXT |
Position at next data item |
MDB_NEXT_DUP |
Position at next data item of current key. Only for MDB_DUPSORT |
MDB_NEXT_MULTIPLE |
Return key and up to a page of duplicate data items from next cursor position. Move cursor to prepare for MDB_NEXT_MULTIPLE. Only for MDB_DUPFIXED |
MDB_NEXT_NODUP |
Position at first data item of next key |
MDB_PREV |
Position at previous data item |
MDB_PREV_DUP |
Position at previous data item of current key. Only for MDB_DUPSORT |
MDB_PREV_NODUP |
Position at last data item of previous key |
MDB_SET |
Position at specified key |
MDB_SET_KEY |
Position at specified key, return key + data |
MDB_SET_RANGE |
Position at first key greater than or equal to specified key. |
char* mdb_version | ( | int * | major, |
int * | minor, | ||
int * | patch | ||
) |
Return the LMDB library version information.
[out] | major | if non-NULL, the library major version number is copied here |
[out] | minor | if non-NULL, the library minor version number is copied here |
[out] | patch | if non-NULL, the library patch version number is copied here |
version string | The library version as a string |
Return the library version info.
char* mdb_strerror | ( | int | err | ) |
Return a string describing a given error code.
This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) function. If the error code is greater than or equal to 0, then the string returned by the system function strerror(3) is returned. If the error code is less than 0, an error string corresponding to the LMDB library error is returned. See Return Codes for a list of LMDB-specific error codes.
[in] | err | The error code |
error message | The description of the error |
int mdb_env_create | ( | MDB_env ** | env | ) |
Create an LMDB environment handle.
This function allocates memory for a MDB_env structure. To release the allocated memory and discard the handle, call mdb_env_close(). Before the handle may be used, it must be opened using mdb_env_open(). Various other options may also need to be set before opening the handle, e.g. mdb_env_set_mapsize(), mdb_env_set_maxreaders(), mdb_env_set_maxdbs(), depending on usage requirements.
[out] | env | The address where the new handle will be stored |
int mdb_env_open | ( | MDB_env * | env, |
const char * | path, | ||
unsigned int | flags, | ||
mdb_mode_t | mode | ||
) |
Open an environment handle.
If this function fails, mdb_env_close() must be called to discard the MDB_env handle.
[in] | env | An environment handle returned by mdb_env_create() |
[in] | path | The directory in which the database files reside. This directory must already exist and be writable. |
[in] | flags | Special options for this environment. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here. Flags set by mdb_env_set_flags() are also used.
|
[in] | mode | The UNIX permissions to set on created files and semaphores. This parameter is ignored on Windows. |
int mdb_env_copy | ( | MDB_env * | env, |
const char * | path | ||
) |
Copy an LMDB environment to the specified path.
This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.
[in] | env | An environment handle returned by mdb_env_create(). It must have already been opened successfully. |
[in] | path | The directory in which the copy will reside. This directory must already exist and be writable but must otherwise be empty. |
int mdb_env_copyfd | ( | MDB_env * | env, |
mdb_filehandle_t | fd | ||
) |
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.
[in] | env | An environment handle returned by mdb_env_create(). It must have already been opened successfully. |
[in] | fd | The filedescriptor to write the copy to. It must have already been opened for Write access. |
int mdb_env_copy2 | ( | MDB_env * | env, |
const char * | path, | ||
unsigned int | flags | ||
) |
Copy an LMDB environment to the specified path, with options.
This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.
[in] | env | An environment handle returned by mdb_env_create(). It must have already been opened successfully. |
[in] | path | The directory in which the copy will reside. This directory must already exist and be writable but must otherwise be empty. |
[in] | flags | Special options for this operation. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here.
|
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.
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.
[in] | env | An environment handle returned by mdb_env_create(). It must have already been opened successfully. |
[in] | fd | The filedescriptor to write the copy to. It must have already been opened for Write access. |
[in] | flags | Special options for this operation. See mdb_env_copy2() for options. |
Return statistics about the LMDB environment.
[in] | env | An environment handle returned by mdb_env_create() |
[out] | stat | The address of an MDB_stat structure where the statistics will be copied |
int mdb_env_info | ( | MDB_env * | env, |
MDB_envinfo * | stat | ||
) |
Return information about the LMDB environment.
[in] | env | An environment handle returned by mdb_env_create() |
[out] | stat | The address of an MDB_envinfo structure where the information will be copied |
int mdb_env_sync | ( | MDB_env * | env, |
int | force | ||
) |
Flush the data buffers to disk.
Data is always written to disk when mdb_txn_commit() is called, but the operating system may keep it buffered. LMDB always flushes the OS buffers upon commit as well, unless the environment was opened with MDB_NOSYNC or in part MDB_NOMETASYNC. This call is not valid if the environment was opened with MDB_RDONLY.
[in] | env | An environment handle returned by mdb_env_create() |
[in] | force | If non-zero, force a synchronous flush. Otherwise if the environment has the MDB_NOSYNC flag set the flushes will be omitted, and with MDB_MAPASYNC they will be asynchronous. |
void mdb_env_close | ( | MDB_env * | env | ) |
Close the environment and release the memory map.
Only a single thread may call this function. All transactions, databases, and cursors must already be closed before calling this function. Attempts to use any such handles after calling this function will cause a SIGSEGV. The environment handle will be freed and must not be used again after this call.
[in] | env | An environment handle returned by mdb_env_create() |
int mdb_env_set_flags | ( | MDB_env * | env, |
unsigned int | flags, | ||
int | onoff | ||
) |
Set environment flags.
This may be used to set some flags in addition to those from mdb_env_open(), or to unset these flags. If several threads change the flags at the same time, the result is undefined.
[in] | env | An environment handle returned by mdb_env_create() |
[in] | flags | The flags to change, bitwise OR'ed together |
[in] | onoff | A non-zero value sets the flags, zero clears them. |
int mdb_env_get_flags | ( | MDB_env * | env, |
unsigned int * | flags | ||
) |
Get environment flags.
[in] | env | An environment handle returned by mdb_env_create() |
[out] | flags | The address of an integer to store the flags |
int mdb_env_get_path | ( | MDB_env * | env, |
const char ** | path | ||
) |
Return the path that was used in mdb_env_open().
[in] | env | An environment handle returned by mdb_env_create() |
[out] | path | Address of a string pointer to contain the path. This is the actual string in the environment, not a copy. It should not be altered in any way. |
int mdb_env_get_fd | ( | MDB_env * | env, |
mdb_filehandle_t * | fd | ||
) |
Return the filedescriptor for the given environment.
[in] | env | An environment handle returned by mdb_env_create() |
[out] | fd | Address of a mdb_filehandle_t to contain the descriptor. |
int mdb_env_set_mapsize | ( | MDB_env * | env, |
size_t | size | ||
) |
Set the size of the memory map to use for this environment.
The size should be a multiple of the OS page size. The default is 10485760 bytes. The size of the memory map is also the maximum size of the database. The value should be chosen as large as possible, to accommodate future growth of the database. This function should be called after mdb_env_create() and before mdb_env_open(). It may be called at later times if no transactions are active in this process. Note that the library does not check for this condition, the caller must ensure it explicitly.
The new size takes effect immediately for the current process but will not be persisted to any others until a write transaction has been committed by the current process. Also, only mapsize increases are persisted into the environment.
If the mapsize is increased by another process, and data has grown beyond the range of the current mapsize, mdb_txn_begin() will return MDB_MAP_RESIZED. This function may be called with a size of zero to adopt the new size.
Any attempt to set a size smaller than the space already consumed by the environment will be silently changed to the current size of the used space.
[in] | env | An environment handle returned by mdb_env_create() |
[in] | size | The size in bytes |
int mdb_env_set_maxreaders | ( | MDB_env * | env, |
unsigned int | readers | ||
) |
Set the maximum number of threads/reader slots for the environment.
This defines the number of slots in the lock table that is used to track readers in the the environment. The default is 126. Starting a read-only transaction normally ties a lock table slot to the current thread until the environment closes or the thread exits. If MDB_NOTLS is in use, mdb_txn_begin() instead ties the slot to the MDB_txn object until it or the MDB_env object is destroyed. This function may only be called after mdb_env_create() and before mdb_env_open().
[in] | env | An environment handle returned by mdb_env_create() |
[in] | readers | The maximum number of reader lock table slots |
int mdb_env_get_maxreaders | ( | MDB_env * | env, |
unsigned int * | readers | ||
) |
Get the maximum number of threads/reader slots for the environment.
[in] | env | An environment handle returned by mdb_env_create() |
[out] | readers | Address of an integer to store the number of readers |
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.
[in] | env | An environment handle returned by mdb_env_create() |
[in] | dbs | The maximum number of databases |
int mdb_env_get_maxkeysize | ( | MDB_env * | env | ) |
Get the maximum size of keys and MDB_DUPSORT data we can write.
Depends on the compile-time constant MDB_MAXKEYSIZE. Default 511. See MDB_val.
[in] | env | An environment handle returned by mdb_env_create() |
int mdb_env_set_userctx | ( | MDB_env * | env, |
void * | ctx | ||
) |
Set application information associated with the MDB_env.
[in] | env | An environment handle returned by mdb_env_create() |
[in] | ctx | An arbitrary pointer for whatever the application needs. |
void* mdb_env_get_userctx | ( | MDB_env * | env | ) |
Get the application information associated with the MDB_env.
[in] | env | An environment handle returned by mdb_env_create() |
int mdb_env_set_assert | ( | MDB_env * | env, |
MDB_assert_func * | func | ||
) |
Set or reset the assert() callback of the environment. Disabled if liblmdb is buillt with NDEBUG.
[in] | env | An environment handle returned by mdb_env_create(). |
[in] | func | An MDB_assert_func function, or 0. |
Create a transaction for use with the environment.
The transaction handle may be discarded using mdb_txn_abort() or mdb_txn_commit().
[in] | env | An environment handle returned by mdb_env_create() |
[in] | parent | If this parameter is non-NULL, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level. A parent transaction and its cursors may not issue any other operations than mdb_txn_commit and mdb_txn_abort while it has active child transactions. |
[in] | flags | Special options for this transaction. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here.
|
[out] | txn | Address where the new MDB_txn handle will be stored |
Returns the transaction's MDB_env.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
size_t mdb_txn_id | ( | MDB_txn * | txn | ) |
Return the transaction's ID.
This returns the identifier associated with this transaction. For a read-only transaction, this corresponds to the snapshot being read; concurrent readers will frequently have the same transaction ID.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
int mdb_txn_commit | ( | MDB_txn * | txn | ) |
Commit all the operations of a transaction into the database.
The transaction handle is freed. It and its cursors must not be used again after this call, except with mdb_cursor_renew().
[in] | txn | A transaction handle returned by mdb_txn_begin() |
void mdb_txn_abort | ( | MDB_txn * | txn | ) |
Abandon all the operations of the transaction instead of saving them.
The transaction handle is freed. It and its cursors must not be used again after this call, except with mdb_cursor_renew().
[in] | txn | A transaction handle returned by mdb_txn_begin() |
void mdb_txn_reset | ( | MDB_txn * | txn | ) |
Reset a read-only transaction.
Abort the transaction like mdb_txn_abort(), but keep the transaction handle. mdb_txn_renew() may reuse the handle. This saves allocation overhead if the process will start a new read-only transaction soon, and also locking overhead if MDB_NOTLS is in use. The reader table lock is released, but the table slot stays tied to its thread or MDB_txn. Use mdb_txn_abort() to discard a reset handle, and to free its lock table slot if MDB_NOTLS is in use. Cursors opened within the transaction must not be used again after this call, except with mdb_cursor_renew(). Reader locks generally don't interfere with writers, but they keep old versions of database pages allocated. Thus they prevent the old pages from being reused when writers commit new data, and so under heavy load the database size may grow much more rapidly than otherwise.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
int mdb_txn_renew | ( | MDB_txn * | txn | ) |
Renew a read-only transaction.
This acquires a new reader lock for a transaction handle that had been released by mdb_txn_reset(). It must be called before a reset transaction may be used again.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
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.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | name | The name of the database to open. If only a single database is needed in the environment, this value may be NULL. |
[in] | flags | Special options for this database. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here.
|
[out] | dbi | Address where the new MDB_dbi handle will be stored |
Retrieve statistics for a database.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[out] | stat | The address of an MDB_stat structure where the statistics will be copied |
Retrieve the DB flags for a database handle.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[out] | flags | Address where the flags will be returned. |
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.
[in] | env | An environment handle returned by mdb_env_create() |
[in] | 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.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | del | 0 to empty the DB, 1 to delete it from the environment and close the DB handle. |
int mdb_set_compare | ( | MDB_txn * | txn, |
MDB_dbi | dbi, | ||
MDB_cmp_func * | cmp | ||
) |
Set a custom key comparison function for a database.
The comparison function is called whenever it is necessary to compare a key specified by the application with a key currently stored in the database. If no comparison function is specified, and no special key flags were specified with mdb_dbi_open(), the keys are compared lexically, with shorter keys collating before longer keys.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | cmp | A MDB_cmp_func function |
int mdb_set_dupsort | ( | MDB_txn * | txn, |
MDB_dbi | dbi, | ||
MDB_cmp_func * | cmp | ||
) |
Set a custom data comparison function for a MDB_DUPSORT database.
This comparison function is called whenever it is necessary to compare a data item specified by the application with a data item currently stored in the database. This function only takes effect if the database was opened with the MDB_DUPSORT flag. If no comparison function is specified, and no special key flags were specified with mdb_dbi_open(), the data items are compared lexically, with shorter items collating before longer items.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | cmp | A MDB_cmp_func function |
int mdb_set_relfunc | ( | MDB_txn * | txn, |
MDB_dbi | dbi, | ||
MDB_rel_func * | rel | ||
) |
Set a relocation function for a MDB_FIXEDMAP database.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | rel | A MDB_rel_func function |
Set a context pointer for a MDB_FIXEDMAP database's relocation function.
See mdb_set_relfunc and MDB_rel_func for more details.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | ctx | An arbitrary pointer for whatever the application needs. It will be passed to the callback function set by mdb_set_relfunc as its relctx parameter whenever the callback is invoked. |
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().
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | key | The key to search for in the database |
[out] | data | The data corresponding to the key |
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).
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | key | The key to store in the database |
[in,out] | data | The data to store |
[in] | flags | Special options for this operation. This parameter must be set to 0 or by bitwise OR'ing together one or more of the values described here.
|
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.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | key | The key to delete from the database |
[in] | data | The data to delete |
int mdb_cursor_open | ( | MDB_txn * | txn, |
MDB_dbi | dbi, | ||
MDB_cursor ** | cursor | ||
) |
Create a cursor handle.
A cursor is associated with a specific transaction and database. A cursor cannot be used when its database handle is closed. Nor when its transaction has ended, except with mdb_cursor_renew(). It can be discarded with mdb_cursor_close(). A cursor in a write-transaction can be closed before its transaction ends, and will otherwise be closed when its transaction ends. A cursor in a read-only transaction must be closed explicitly, before or after its transaction ends. It can be reused with mdb_cursor_renew() before finally closing it.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[out] | cursor | Address where the new MDB_cursor handle will be stored |
void mdb_cursor_close | ( | MDB_cursor * | cursor | ) |
Close a cursor handle.
The cursor handle will be freed and must not be used again after this call. Its transaction must still be live if it is a write-transaction.
[in] | cursor | A cursor handle returned by mdb_cursor_open() |
int mdb_cursor_renew | ( | MDB_txn * | txn, |
MDB_cursor * | cursor | ||
) |
Renew a cursor handle.
A cursor is associated with a specific transaction and database. Cursors that are only used in read-only transactions may be re-used, to avoid unnecessary malloc/free overhead. The cursor may be associated with a new read-only transaction, and referencing the same database handle as it was created with. This may be done whether the previous transaction is live or dead.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | cursor | A cursor handle returned by mdb_cursor_open() |
MDB_txn* mdb_cursor_txn | ( | MDB_cursor * | cursor | ) |
Return the cursor's transaction handle.
[in] | cursor | A cursor handle returned by mdb_cursor_open() |
MDB_dbi mdb_cursor_dbi | ( | MDB_cursor * | cursor | ) |
Return the cursor's database handle.
[in] | cursor | A cursor handle returned by mdb_cursor_open() |
int mdb_cursor_get | ( | MDB_cursor * | cursor, |
MDB_val * | key, | ||
MDB_val * | data, | ||
MDB_cursor_op | op | ||
) |
Retrieve by cursor.
This function retrieves key/data pairs from the database. The address and length of the key are returned in the object to which key refers (except for the case of the MDB_SET option, in which the key object is unchanged), and the address and length of the data are returned in the object to which data refers. See mdb_get() for restrictions on using the output values.
[in] | cursor | A cursor handle returned by mdb_cursor_open() |
[in,out] | key | The key for a retrieved item |
[in,out] | data | The data of a retrieved item |
[in] | op | A cursor operation MDB_cursor_op |
int mdb_cursor_put | ( | MDB_cursor * | cursor, |
MDB_val * | key, | ||
MDB_val * | data, | ||
unsigned int | flags | ||
) |
Store by cursor.
This function stores key/data pairs into the database. The cursor is positioned at the new item, or on failure usually near it.
[in] | cursor | A cursor handle returned by mdb_cursor_open() |
[in] | key | The key operated on. |
[in] | data | The data operated on. |
[in] | flags | Options for this operation. This parameter must be set to 0 or one of the values described here.
|
int mdb_cursor_del | ( | MDB_cursor * | cursor, |
unsigned int | flags | ||
) |
Delete current key/data pair.
This function deletes the key/data pair to which the cursor refers.
[in] | cursor | A cursor handle returned by mdb_cursor_open() |
[in] | flags | Options for this operation. This parameter must be set to 0 or one of the values described here.
|
int mdb_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.
[in] | cursor | A cursor handle returned by mdb_cursor_open() |
[out] | countp | Address where the count will be stored |
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.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | a | The first item to compare |
[in] | b | The second item to compare |
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.
[in] | txn | A transaction handle returned by mdb_txn_begin() |
[in] | dbi | A database handle returned by mdb_dbi_open() |
[in] | a | The first item to compare |
[in] | b | The second item to compare |
int mdb_reader_list | ( | MDB_env * | env, |
MDB_msg_func * | func, | ||
void * | ctx | ||
) |
Dump the entries in the reader lock table.
[in] | env | An environment handle returned by mdb_env_create() |
[in] | func | A MDB_msg_func function |
[in] | ctx | Anything the message function needs |
int mdb_reader_check | ( | MDB_env * | env, |
int * | dead | ||
) |
Check for stale entries in the reader lock table.
[in] | env | An environment handle returned by mdb_env_create() |
[out] | dead | Number of stale slots that were cleared |