starting(3) on Linux
The text b73edb8a1826, as Debian 9 (Stretch) shipped it.
Getting Started LMDB is compact, fast, powerful, and robust and implements a simplified variant of the BerkeleyDB (BDB) API. (BDB is also very powerful, and verbosely documented in its own right.) After reading this page, the main LMDB API documentation should make sense. Thanks to Bert Hubert for creating the initial version of this writeup. Everything starts with an environment, created by mdb_env_create(). Once created, this environment must also be opened with mdb_env_open(). mdb_env_open() gets passed a name which is interpreted as a directory path. Note that this directory must exist already, it is not created for you. Within that directory, a lock file and a storage file will be generated. If you don't want to use a directory, you can pass the MDB_NOSUBDIR option, in which case the path you provided is used directly as the data file, and another file with a '-lock' suffix added will be used for the lock file. Once the environment is open, a transaction can be created within it using mdb_txn_begin(). Transactions may be read-write or read-only, and read-write transactions may be nested. A transaction must only be used by one thread at a time. Transactions are always required, even for read-only access. The transaction provides a consistent view of the data. Once a transaction has been created, a database can be opened within it using mdb_dbi_open(). If only one database will ever be used in the environment, a NULL can be passed as the database name. For named databases, the MDB_CREATE flag must be used to create the database if it doesn't already exist. Also, mdb_env_set_maxdbs() must be called after mdb_env_create() and before mdb_env_open() to set the maximum number of named databases you want to support. Note: a single transaction can open multiple databases. Generally databases should only be opened once, by the first transaction in the process. After the first transaction completes, the database handles can freely be used by all subsequent transactions. Within a transaction, mdb_get() and mdb_put() can store single key/value pairs if that is all you need to do (but see Cursors below if you want to do more). A key/value pair is expressed as two MDB_val structures. This struct has two fields, mv_size and mv_data. The data is a void pointer to an array of mv_size bytes. Because LMDB is very efficient (and usually zero-copy), the data returned in an MDB_val structure may be memory-mapped straight from disk. In other words look but do not touch (or free() for that matter). Once a transaction is closed, the values can no longer be used, so make a copy if you need to keep them after that.