@ohos-ports/lmdb 2.8.6-beta.0

package/dependencies/lmdb/libraries/liblmdb/LICENSE

@@ -0,0 +1,47 @@
+The OpenLDAP Public License
+  Version 2.8, 17 August 2003
+
+Redistribution and use of this software and associated documentation
+("Software"), with or without modification, are permitted provided
+that the following conditions are met:
+
+1. Redistributions in source form must retain copyright statements
+   and notices,
+
+2. Redistributions in binary form must reproduce applicable copyright
+   statements and notices, this list of conditions, and the following
+   disclaimer in the documentation and/or other materials provided
+   with the distribution, and
+
+3. Redistributions must contain a verbatim copy of this document.
+
+The OpenLDAP Foundation may revise this license from time to time.
+Each revision is distinguished by a version number.  You may use
+this Software under terms of this license revision or under the
+terms of any subsequent revision of the license.
+
+THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND ITS
+CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT
+SHALL THE OPENLDAP FOUNDATION, ITS CONTRIBUTORS, OR THE AUTHOR(S)
+OR OWNER(S) OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+The names of the authors and copyright holders must not be used in
+advertising or otherwise to promote the sale, use or other dealing
+in this Software without specific, written prior permission.  Title
+to copyright in this Software shall at all times remain with copyright
+holders.
+
+OpenLDAP is a registered trademark of the OpenLDAP Foundation.
+
+Copyright 1999-2003 The OpenLDAP Foundation, Redwood City,
+California, USA.  All Rights Reserved.  Permission to copy and
+distribute verbatim copies of this document is granted.

package/dependencies/lmdb/libraries/liblmdb/Makefile

@@ -0,0 +1,136 @@
+# Makefile for liblmdb (Lightning memory-mapped database library).
+
+########################################################################
+# Configuration. The compiler options must enable threaded compilation.
+#
+# Preprocessor macros (for CPPFLAGS) of interest...
+# Note that the defaults should already be correct for most
+# platforms; you should not need to change any of these.
+# Read their descriptions in mdb.c if you do:
+#
+# - MDB_USE_POSIX_MUTEX, MDB_USE_POSIX_SEM, MDB_USE_SYSV_SEM
+# - MDB_DSYNC
+# - MDB_FDATASYNC
+# - MDB_FDATASYNC_WORKS
+# - MDB_USE_PWRITEV
+# - MDB_USE_ROBUST
+#
+# There may be other macros in mdb.c of interest. You should
+# read mdb.c before changing any of them.
+#
+CC	= gcc
+AR	= ar
+W	= -W -Wall -Wno-unused-parameter -Wbad-function-cast -Wuninitialized
+THREADS = -pthread
+OPT = -O2 -g
+CFLAGS	= $(THREADS) $(OPT) $(W) $(XCFLAGS)
+LDFLAGS = $(THREADS)
+LDLIBS	= 
+SOLIBS	= 
+SOEXT	= .so
+LDL		= -ldl
+prefix	= /usr/local
+exec_prefix = $(prefix)
+bindir = $(exec_prefix)/bin
+libdir = $(exec_prefix)/lib
+includedir = $(prefix)/include
+datarootdir = $(prefix)/share
+mandir = $(datarootdir)/man
+
+########################################################################
+
+IHDRS	= lmdb.h
+ILIBS	= liblmdb.a liblmdb$(SOEXT)
+IPROGS	= mdb_stat mdb_copy mdb_dump mdb_load mdb_drop
+IDOCS	= mdb_stat.1 mdb_copy.1 mdb_dump.1 mdb_load.1 mdb_drop.1
+PROGS	= $(IPROGS) mtest mtest2 mtest3 mtest4 mtest5
+RPROGS	= mtest_remap mtest_enc mtest_enc2
+
+all:	$(ILIBS) $(PROGS)
+# Requires CPPFLAGS=-DMDB_VL32 and/or -DMDB_RPAGE_CACHE
+rall:	all $(RPROGS)
+
+install: $(ILIBS) $(IPROGS) $(IHDRS)
+	mkdir -p $(DESTDIR)$(bindir)
+	mkdir -p $(DESTDIR)$(libdir)
+	mkdir -p $(DESTDIR)$(includedir)
+	mkdir -p $(DESTDIR)$(mandir)/man1
+	for f in $(IPROGS); do cp $$f $(DESTDIR)$(bindir); done
+	for f in $(ILIBS); do cp $$f $(DESTDIR)$(libdir); done
+	for f in $(IHDRS); do cp $$f $(DESTDIR)$(includedir); done
+	for f in $(IDOCS); do cp $$f $(DESTDIR)$(mandir)/man1; done
+
+clean:
+	rm -rf $(PROGS) $(RPROGS) *.[ao] *.[ls]o *~ testdb
+
+test:	all
+	rm -rf testdb && mkdir testdb
+	./mtest && ./mdb_stat testdb
+
+liblmdb.a:	mdb.o midl.o
+	$(AR) rs $@ mdb.o midl.o
+
+liblmdb$(SOEXT):	mdb.lo midl.lo
+#	$(CC) $(LDFLAGS) -pthread -shared -Wl,-Bsymbolic -o $@ mdb.o midl.o $(SOLIBS)
+	$(CC) $(LDFLAGS) -pthread -shared -o $@ mdb.lo midl.lo $(SOLIBS)
+
+mdb_stat: mdb_stat.o module.o liblmdb.a
+	$(CC) $(LDFLAGS) -o $@ $^ $(LDL)
+mdb_copy: mdb_copy.o module.o liblmdb.a
+	$(CC) $(LDFLAGS) -o $@ $^ $(LDL)
+mdb_dump: mdb_dump.o module.o liblmdb.a
+	$(CC) $(LDFLAGS) -o $@ $^ $(LDL)
+mdb_load: mdb_load.o module.o liblmdb.a
+	$(CC) $(LDFLAGS) -o $@ $^ $(LDL)
+mdb_drop: mdb_drop.o module.o liblmdb.a
+	$(CC) $(LDFLAGS) -o $@ $^ $(LDL)
+mtest:    mtest.o    liblmdb.a
+mtest2:	mtest2.o liblmdb.a
+mtest3:	mtest3.o liblmdb.a
+mtest4:	mtest4.o liblmdb.a
+mtest5:	mtest5.o liblmdb.a
+mtest6:	mtest6.o liblmdb.a
+mtest_remap:  mtest_remap.o liblmdb.a
+mtest_enc:    mtest_enc.o chacha8.o liblmdb.a
+mtest_enc2:	  mtest_enc2.o module.o liblmdb.a crypto.lm
+	$(CC) $(LDFLAGS) -pthread -o $@ mtest_enc2.o module.o liblmdb.a $(LDL)
+
+crypto.lm:	crypto.c
+	$(CC) -shared -o $@ -lcrypto
+
+mdb.o: mdb.c lmdb.h midl.h
+	$(CC) $(CFLAGS) $(CPPFLAGS) -c mdb.c
+
+midl.o: midl.c midl.h
+	$(CC) $(CFLAGS) $(CPPFLAGS) -c midl.c
+
+mdb.lo: mdb.c lmdb.h midl.h
+	$(CC) $(CFLAGS) -fPIC $(CPPFLAGS) -c mdb.c -o $@
+
+midl.lo: midl.c midl.h
+	$(CC) $(CFLAGS) -fPIC $(CPPFLAGS) -c midl.c -o $@
+
+%:	%.o
+	$(CC) $(CFLAGS) $(LDFLAGS) $^ $(LDLIBS) -o $@
+
+%.o:	%.c lmdb.h
+	$(CC) $(CFLAGS) $(CPPFLAGS) -c $<
+
+COV_FLAGS=-fprofile-arcs -ftest-coverage
+COV_OBJS=xmdb.o xmidl.o
+
+coverage: xmtest
+	for i in mtest*.c [0-9]*.c; do j=`basename \$$i .c`; $(MAKE) $$j.o; \
+		gcc -o x$$j $$j.o $(COV_OBJS) -pthread $(COV_FLAGS); \
+		rm -rf testdb; mkdir testdb; ./x$$j; done
+	gcov xmdb.c
+	gcov xmidl.c
+
+xmtest:	mtest.o xmdb.o xmidl.o
+	gcc -o xmtest mtest.o xmdb.o xmidl.o -pthread $(COV_FLAGS)
+
+xmdb.o: mdb.c lmdb.h midl.h
+	$(CC) $(CFLAGS) -fPIC $(CPPFLAGS) -O0 $(COV_FLAGS) -c mdb.c -o $@
+
+xmidl.o: midl.c midl.h
+	$(CC) $(CFLAGS) -fPIC $(CPPFLAGS) -O0 $(COV_FLAGS) -c midl.c -o $@

package/dependencies/lmdb/libraries/liblmdb/chacha8.c

@@ -0,0 +1,183 @@
+/*
+chacha-merged.c version 20080118
+D. J. Bernstein
+Public domain.
+*/
+
+#include <memory.h>
+#include <stdio.h>
+//#include <sys/param.h>
+
+#include "chacha8.h"
+#if 0
+#include "common/int-util.h"
+#include "warnings.h"
+#endif
+
+#if BYTE_ORDER == LITTLE_ENDIAN
+#define SWAP32LE(x)	(x)
+#else
+#define SWAP32LE(x)  ((((uint32_t) (x) & 0x000000ff) << 24) | \
+  (((uint32_t) (x) & 0x0000ff00) <<  8) | \
+  (((uint32_t) (x) & 0x00ff0000) >>  8) | \
+  (((uint32_t) (x) & 0xff000000) >> 24))
+#endif
+
+/*
+ * The following macros are used to obtain exact-width results.
+ */
+#define U8V(v) ((uint8_t)(v) & UINT8_C(0xFF))
+#define U32V(v) ((uint32_t)(v) & UINT32_C(0xFFFFFFFF))
+
+/*
+ * The following macros load words from an array of bytes with
+ * different types of endianness, and vice versa.
+ */
+#define U8TO32_LITTLE(p) SWAP32LE(((uint32_t*)(p))[0])
+#define U32TO8_LITTLE(p, v) (((uint32_t*)(p))[0] = SWAP32LE(v))
+
+#define ROTATE(v,c) (rol32(v,c))
+#define XOR(v,w) ((v) ^ (w))
+#define PLUS(v,w) (U32V((v) + (w)))
+#define PLUSONE(v) (PLUS((v),1))
+
+#define QUARTERROUND(a,b,c,d) \
+  a = PLUS(a,b); d = ROTATE(XOR(d,a),16); \
+  c = PLUS(c,d); b = ROTATE(XOR(b,c),12); \
+  a = PLUS(a,b); d = ROTATE(XOR(d,a), 8); \
+  c = PLUS(c,d); b = ROTATE(XOR(b,c), 7);
+
+static const char sigma[] = "expand 32-byte k";
+
+static uint32_t rol32(uint32_t x, int r) {
+	return (x << (r & 31)) | (x >> (-r & 31));
+}
+
+void chacha8(const void* data, size_t length, const uint8_t* key, const uint8_t* iv, char* cipher) {
+  uint32_t x0, x1, x2, x3, x4, x5, x6, x7, x8, x9, x10, x11, x12, x13, x14, x15;
+  uint32_t j0, j1, j2, j3, j4, j5, j6, j7, j8, j9, j10, j11, j12, j13, j14, j15;
+  char* ctarget = 0;
+  char tmp[64];
+  int i;
+
+  if (!length) return;
+
+  j0  = U8TO32_LITTLE(sigma + 0);
+  j1  = U8TO32_LITTLE(sigma + 4);
+  j2  = U8TO32_LITTLE(sigma + 8);
+  j3  = U8TO32_LITTLE(sigma + 12);
+  j4  = U8TO32_LITTLE(key + 0);
+  j5  = U8TO32_LITTLE(key + 4);
+  j6  = U8TO32_LITTLE(key + 8);
+  j7  = U8TO32_LITTLE(key + 12);
+  j8  = U8TO32_LITTLE(key + 16);
+  j9  = U8TO32_LITTLE(key + 20);
+  j10 = U8TO32_LITTLE(key + 24);
+  j11 = U8TO32_LITTLE(key + 28);
+  j12 = 0;
+  j13 = 0;
+  j14 = U8TO32_LITTLE(iv + 0);
+  j15 = U8TO32_LITTLE(iv + 4);
+
+  for (;;) {
+    if (length < 64) {
+      memcpy(tmp, data, length);
+      data = tmp;
+      ctarget = cipher;
+      cipher = tmp;
+    }
+    x0  = j0;
+    x1  = j1;
+    x2  = j2;
+    x3  = j3;
+    x4  = j4;
+    x5  = j5;
+    x6  = j6;
+    x7  = j7;
+    x8  = j8;
+    x9  = j9;
+    x10 = j10;
+    x11 = j11;
+    x12 = j12;
+    x13 = j13;
+    x14 = j14;
+    x15 = j15;
+    for (i = 8;i > 0;i -= 2) {
+      QUARTERROUND( x0, x4, x8,x12)
+      QUARTERROUND( x1, x5, x9,x13)
+      QUARTERROUND( x2, x6,x10,x14)
+      QUARTERROUND( x3, x7,x11,x15)
+      QUARTERROUND( x0, x5,x10,x15)
+      QUARTERROUND( x1, x6,x11,x12)
+      QUARTERROUND( x2, x7, x8,x13)
+      QUARTERROUND( x3, x4, x9,x14)
+    }
+    x0  = PLUS( x0, j0);
+    x1  = PLUS( x1, j1);
+    x2  = PLUS( x2, j2);
+    x3  = PLUS( x3, j3);
+    x4  = PLUS( x4, j4);
+    x5  = PLUS( x5, j5);
+    x6  = PLUS( x6, j6);
+    x7  = PLUS( x7, j7);
+    x8  = PLUS( x8, j8);
+    x9  = PLUS( x9, j9);
+    x10 = PLUS(x10,j10);
+    x11 = PLUS(x11,j11);
+    x12 = PLUS(x12,j12);
+    x13 = PLUS(x13,j13);
+    x14 = PLUS(x14,j14);
+    x15 = PLUS(x15,j15);
+
+    x0  = XOR( x0,U8TO32_LITTLE((uint8_t*)data +  0));
+    x1  = XOR( x1,U8TO32_LITTLE((uint8_t*)data +  4));
+    x2  = XOR( x2,U8TO32_LITTLE((uint8_t*)data +  8));
+    x3  = XOR( x3,U8TO32_LITTLE((uint8_t*)data + 12));
+    x4  = XOR( x4,U8TO32_LITTLE((uint8_t*)data + 16));
+    x5  = XOR( x5,U8TO32_LITTLE((uint8_t*)data + 20));
+    x6  = XOR( x6,U8TO32_LITTLE((uint8_t*)data + 24));
+    x7  = XOR( x7,U8TO32_LITTLE((uint8_t*)data + 28));
+    x8  = XOR( x8,U8TO32_LITTLE((uint8_t*)data + 32));
+    x9  = XOR( x9,U8TO32_LITTLE((uint8_t*)data + 36));
+    x10 = XOR(x10,U8TO32_LITTLE((uint8_t*)data + 40));
+    x11 = XOR(x11,U8TO32_LITTLE((uint8_t*)data + 44));
+    x12 = XOR(x12,U8TO32_LITTLE((uint8_t*)data + 48));
+    x13 = XOR(x13,U8TO32_LITTLE((uint8_t*)data + 52));
+    x14 = XOR(x14,U8TO32_LITTLE((uint8_t*)data + 56));
+    x15 = XOR(x15,U8TO32_LITTLE((uint8_t*)data + 60));
+
+    j12 = PLUSONE(j12);
+    if (!j12)
+    {
+      j13 = PLUSONE(j13);
+      /* stopping at 2^70 bytes per iv is user's responsibility */
+    }
+
+    U32TO8_LITTLE(cipher +  0,x0);
+    U32TO8_LITTLE(cipher +  4,x1);
+    U32TO8_LITTLE(cipher +  8,x2);
+    U32TO8_LITTLE(cipher + 12,x3);
+    U32TO8_LITTLE(cipher + 16,x4);
+    U32TO8_LITTLE(cipher + 20,x5);
+    U32TO8_LITTLE(cipher + 24,x6);
+    U32TO8_LITTLE(cipher + 28,x7);
+    U32TO8_LITTLE(cipher + 32,x8);
+    U32TO8_LITTLE(cipher + 36,x9);
+    U32TO8_LITTLE(cipher + 40,x10);
+    U32TO8_LITTLE(cipher + 44,x11);
+    U32TO8_LITTLE(cipher + 48,x12);
+    U32TO8_LITTLE(cipher + 52,x13);
+    U32TO8_LITTLE(cipher + 56,x14);
+    U32TO8_LITTLE(cipher + 60,x15);
+
+    if (length <= 64) {
+      if (length < 64) {
+        memcpy(ctarget, cipher, length);
+      }
+      return;
+    }
+    length -= 64;
+    cipher += 64;
+    data = (uint8_t*)data + 64;
+  }
+}

package/dependencies/lmdb/libraries/liblmdb/chacha8.h

@@ -0,0 +1,14 @@
+#include <stdint.h>
+#include <stddef.h>
+#ifdef __cplusplus
+extern "C" {
+#endif
+void chacha8(const void* data, size_t length, const uint8_t* key, const uint8_t* iv, char* cipher);
+
+#define CHACHA8_KEY_SIZE 32
+#define CHACHA8_IV_SIZE 8
+
+#ifdef __cplusplus
+}
+#endif
+

package/dependencies/lmdb/libraries/liblmdb/crypto.c

@@ -0,0 +1,121 @@
+/* crypto.c - LMDB encryption helper module */
+/*
+ * Copyright 2020-2021 Howard Chu, Symas Corp.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted only as authorized by the Symas
+ * Dual-Use License.
+ *
+ * A copy of this license is available in the file LICENSE in the
+ * source distribution.
+ */
+#include <string.h>
+
+#include <openssl/engine.h>
+
+#include "lmdb.h"
+
+MDB_crypto_hooks MDB_crypto;
+
+static EVP_CIPHER *cipher;
+
+static int mcf_str2key(const char *passwd, MDB_val *key)
+{
+	unsigned int size;
+	EVP_MD_CTX *mdctx = EVP_MD_CTX_new();
+	EVP_DigestInit_ex(mdctx, EVP_sha256(), NULL);
+	EVP_DigestUpdate(mdctx, "Just a Constant", sizeof("Just a Constant"));
+	EVP_DigestUpdate(mdctx, passwd, strlen(passwd));
+	EVP_DigestFinal_ex(mdctx, key->mv_data, &size);
+	EVP_MD_CTX_free(mdctx);
+	return 0;
+}
+
+/* cheats - internal OpenSSL 1.1 structures */
+typedef struct evp_cipher_ctx_st {
+    const EVP_CIPHER *cipher;
+    ENGINE *engine;             /* functional reference if 'cipher' is
+                                 * ENGINE-provided */
+    int encrypt;                /* encrypt or decrypt */
+    int buf_len;                /* number we have left */
+    unsigned char oiv[EVP_MAX_IV_LENGTH]; /* original iv */
+    unsigned char iv[EVP_MAX_IV_LENGTH]; /* working iv */
+    unsigned char buf[EVP_MAX_BLOCK_LENGTH]; /* saved partial block */
+    int num;                    /* used by cfb/ofb/ctr mode */
+    /* FIXME: Should this even exist? It appears unused */
+    void *app_data;             /* application stuff */
+    int key_len;                /* May change for variable length cipher */
+    unsigned long flags;        /* Various flags */
+    void *cipher_data;          /* per EVP data */
+    int final_used;
+    int block_mask;
+    unsigned char final[EVP_MAX_BLOCK_LENGTH]; /* possible final block */
+} EVP_CIPHER_CTX;
+
+#define	CHACHA_KEY_SIZE	32
+#define CHACHA_CTR_SIZE	16
+#define CHACHA_BLK_SIZE	64
+#define POLY1305_BLOCK_SIZE	16
+
+typedef struct {
+    union {
+        double align;   /* this ensures even sizeof(EVP_CHACHA_KEY)%8==0 */
+        unsigned int d[CHACHA_KEY_SIZE / 4];
+    } key;
+    unsigned int  counter[CHACHA_CTR_SIZE / 4];
+    unsigned char buf[CHACHA_BLK_SIZE];
+    unsigned int  partial_len;
+} EVP_CHACHA_KEY;
+
+typedef struct {
+    EVP_CHACHA_KEY key;
+    unsigned int nonce[12/4];
+    unsigned char tag[POLY1305_BLOCK_SIZE];
+    unsigned char tls_aad[POLY1305_BLOCK_SIZE];
+    struct { uint64_t aad, text; } len;
+    int aad, mac_inited, tag_len, nonce_len;
+    size_t tls_payload_length;
+} EVP_CHACHA_AEAD_CTX;
+
+static int mcf_encfunc(const MDB_val *src, MDB_val *dst, const MDB_val *key, int encdec)
+{
+	unsigned char iv[12];
+	int ivl, outl, rc;
+	mdb_size_t *ptr;
+	EVP_CIPHER_CTX ctx = {0};
+	EVP_CHACHA_AEAD_CTX cactx;
+
+	ctx.cipher_data = &cactx;
+	ptr = key[1].mv_data;
+	ivl = ptr[0] & 0xffffffff;
+	memcpy(iv, &ivl, 4);
+	memcpy(iv+4, ptr+1, sizeof(mdb_size_t));
+	EVP_CipherInit_ex(&ctx, cipher, NULL, key[0].mv_data, iv, encdec);
+	EVP_CIPHER_CTX_set_padding(&ctx, 0);
+	if (!encdec) {
+		EVP_CIPHER_CTX_ctrl(&ctx, EVP_CTRL_AEAD_SET_TAG, key[2].mv_size, key[2].mv_data);
+	}
+	rc = EVP_CipherUpdate(&ctx, dst->mv_data, &outl, src->mv_data, src->mv_size);
+	if (rc)
+		rc = EVP_CipherFinal_ex(&ctx, key[2].mv_data, &outl);
+	if (rc && encdec) {
+		EVP_CIPHER_CTX_ctrl(&ctx, EVP_CTRL_AEAD_GET_TAG, key[2].mv_size, key[2].mv_data);
+	}
+	return rc == 0;
+}
+
+static const MDB_crypto_funcs mcf_table = {
+	mcf_str2key,
+	mcf_encfunc,
+	NULL,
+	CHACHA_KEY_SIZE,
+	POLY1305_BLOCK_SIZE,
+	0
+};
+
+MDB_crypto_funcs *MDB_crypto()
+{
+	cipher = (EVP_CIPHER *)EVP_chacha20_poly1305();
+	return (MDB_crypto_funcs *)&mcf_table;
+}

package/dependencies/lmdb/libraries/liblmdb/intro.doc

@@ -0,0 +1,192 @@
+/*
+ * Copyright 2015-2021 Howard Chu, Symas Corp.
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted only as authorized by the OpenLDAP
+ * Public License.
+ *
+ * A copy of this license is available in the file LICENSE in the
+ * top-level directory of the distribution or, alternatively, at
+ * <http://www.OpenLDAP.org/license.html>.
+ */
+/** @page starting 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
+\ref mdb documentation should make sense. Thanks to Bert Hubert
+for creating the
+<a href="https://github.com/ahupowerdns/ahutils/blob/master/lmdb-semantics.md">
+initial version</a> 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 \ref Cursors
+below if you want to do more).
+
+A key/value pair is expressed as two #MDB_val structures. This struct
+has two fields, \c mv_size and \c mv_data. The data is a \c void pointer to
+an array of \c 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 <b>look but do not touch</b> (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.
+
+@section Cursors Cursors
+
+To do more powerful things, we must use a cursor.
+
+Within the transaction, a cursor can be created with #mdb_cursor_open().
+With this cursor we can store/retrieve/delete (multiple) values using
+#mdb_cursor_get(), #mdb_cursor_put(), and #mdb_cursor_del().
+
+#mdb_cursor_get() positions itself depending on the cursor operation
+requested, and for some operations, on the supplied key. For example,
+to list all key/value pairs in a database, use operation #MDB_FIRST for
+the first call to #mdb_cursor_get(), and #MDB_NEXT on subsequent calls,
+until the end is hit.
+
+To retrieve all keys starting from a specified key value, use #MDB_SET.
+For more cursor operations, see the \ref mdb docs.
+
+When using #mdb_cursor_put(), either the function will position the
+cursor for you based on the \b key, or you can use operation
+#MDB_CURRENT to use the current position of the cursor. Note that
+\b key must then match the current position's key.
+
+@subsection summary Summarizing the Opening
+
+So we have a cursor in a transaction which opened a database in an
+environment which is opened from a filesystem after it was
+separately created.
+
+Or, we create an environment, open it from a filesystem, create a
+transaction within it, open a database within that transaction,
+and create a cursor within all of the above.
+
+Got it?
+
+@section thrproc Threads and Processes
+
+LMDB uses POSIX locks on files, and these locks have issues if one
+process opens a file multiple times. Because of this, do not
+#mdb_env_open() a file multiple times from a single process. Instead,
+share the LMDB environment that has opened the file across all threads.
+Otherwise, if a single process opens the same environment multiple times,
+closing it once will remove all the locks held on it, and the other
+instances will be vulnerable to corruption from other processes.
+
+Also note that a transaction is tied to one thread by default using
+Thread Local Storage. If you want to pass read-only transactions across
+threads, you can use the #MDB_NOTLS option on the environment.
+
+@section txns Transactions, Rollbacks, etc.
+
+To actually get anything done, a transaction must be committed using
+#mdb_txn_commit(). Alternatively, all of a transaction's operations
+can be discarded using #mdb_txn_abort(). In a read-only transaction,
+any cursors will \b not automatically be freed. In a read-write
+transaction, all cursors will be freed and must not be used again.
+
+For read-only transactions, obviously there is nothing to commit to
+storage. The transaction still must eventually be aborted to close
+any database handle(s) opened in it, or committed to keep the
+database handles around for reuse in new transactions.
+
+In addition, as long as a transaction is open, a consistent view of
+the database is kept alive, which requires storage. A read-only
+transaction that no longer requires this consistent view should
+be terminated (committed or aborted) when the view is no longer
+needed (but see below for an optimization).
+
+There can be multiple simultaneously active read-only transactions
+but only one that can write. Once a single read-write transaction
+is opened, all further attempts to begin one will block until the
+first one is committed or aborted. This has no effect on read-only
+transactions, however, and they may continue to be opened at any time.
+
+@section dupkeys Duplicate Keys
+
+#mdb_get() and #mdb_put() respectively have no and only some support
+for multiple key/value pairs with identical keys. If there are multiple
+values for a key, #mdb_get() will only return the first value.
+
+When multiple values for one key are required, pass the #MDB_DUPSORT
+flag to #mdb_dbi_open(). In an #MDB_DUPSORT database, by default
+#mdb_put() will not replace the value for a key if the key existed
+already. Instead it will add the new value to the key. In addition,
+#mdb_del() will pay attention to the value field too, allowing for
+specific values of a key to be deleted.
+
+Finally, additional cursor operations become available for
+traversing through and retrieving duplicate values.
+
+@section optim Some Optimization
+
+If you frequently begin and abort read-only transactions, as an
+optimization, it is possible to only reset and renew a transaction.
+
+#mdb_txn_reset() releases any old copies of data kept around for
+a read-only transaction. To reuse this reset transaction, call
+#mdb_txn_renew() on it. Any cursors in this transaction must also
+be renewed using #mdb_cursor_renew().
+
+Note that #mdb_txn_reset() is similar to #mdb_txn_abort() and will
+close any databases you opened within the transaction.
+
+To permanently free a transaction, reset or not, use #mdb_txn_abort().
+
+@section cleanup Cleaning Up
+
+For read-only transactions, any cursors created within it must
+be closed using #mdb_cursor_close().
+
+It is very rarely necessary to close a database handle, and in
+general they should just be left open.
+
+@section onward The Full API
+
+The full \ref mdb documentation lists further details, like how to:
+
+  \li size a database (the default limits are intentionally small)
+  \li drop and clean a database
+  \li detect and report errors
+  \li optimize (bulk) loading speed
+  \li (temporarily) reduce robustness to gain even more speed
+  \li gather statistics about the database
+  \li define custom sort orders
+
+*/