nostrdb

an unfairly fast embedded nostr database backed by lmdb
git clone git://jb55.com/nostrdb
Log | Files | Refs | Submodules | README | LICENSE

lmdb.h (74013B)


      1 /** @file lmdb.h
      2  *	@brief Lightning memory-mapped database library
      3  *
      4  *	@mainpage	Lightning Memory-Mapped Database Manager (LMDB)
      5  *
      6  *	@section intro_sec Introduction
      7  *	LMDB is a Btree-based database management library modeled loosely on the
      8  *	BerkeleyDB API, but much simplified. The entire database is exposed
      9  *	in a memory map, and all data fetches return data directly
     10  *	from the mapped memory, so no malloc's or memcpy's occur during
     11  *	data fetches. As such, the library is extremely simple because it
     12  *	requires no page caching layer of its own, and it is extremely high
     13  *	performance and memory-efficient. It is also fully transactional with
     14  *	full ACID semantics, and when the memory map is read-only, the
     15  *	database integrity cannot be corrupted by stray pointer writes from
     16  *	application code.
     17  *
     18  *	The library is fully thread-aware and supports concurrent read/write
     19  *	access from multiple processes and threads. Data pages use a copy-on-
     20  *	write strategy so no active data pages are ever overwritten, which
     21  *	also provides resistance to corruption and eliminates the need of any
     22  *	special recovery procedures after a system crash. Writes are fully
     23  *	serialized; only one write transaction may be active at a time, which
     24  *	guarantees that writers can never deadlock. The database structure is
     25  *	multi-versioned so readers run with no locks; writers cannot block
     26  *	readers, and readers don't block writers.
     27  *
     28  *	Unlike other well-known database mechanisms which use either write-ahead
     29  *	transaction logs or append-only data writes, LMDB requires no maintenance
     30  *	during operation. Both write-ahead loggers and append-only databases
     31  *	require periodic checkpointing and/or compaction of their log or database
     32  *	files otherwise they grow without bound. LMDB tracks free pages within
     33  *	the database and re-uses them for new write operations, so the database
     34  *	size does not grow without bound in normal use.
     35  *
     36  *	The memory map can be used as a read-only or read-write map. It is
     37  *	read-only by default as this provides total immunity to corruption.
     38  *	Using read-write mode offers much higher write performance, but adds
     39  *	the possibility for stray application writes thru pointers to silently
     40  *	corrupt the database. Of course if your application code is known to
     41  *	be bug-free (...) then this is not an issue.
     42  *
     43  *	If this is your first time using a transactional embedded key/value
     44  *	store, you may find the \ref starting page to be helpful.
     45  *
     46  *	@section caveats_sec Caveats
     47  *	Troubleshooting the lock file, plus semaphores on BSD systems:
     48  *
     49  *	- A broken lockfile can cause sync issues.
     50  *	  Stale reader transactions left behind by an aborted program
     51  *	  cause further writes to grow the database quickly, and
     52  *	  stale locks can block further operation.
     53  *
     54  *	  Fix: Check for stale readers periodically, using the
     55  *	  #mdb_reader_check function or the \ref mdb_stat_1 "mdb_stat" tool.
     56  *	  Stale writers will be cleared automatically on some systems:
     57  *	  - Windows - automatic
     58  *	  - Linux, systems using POSIX mutexes with Robust option - automatic
     59  *	  - not on BSD, systems using POSIX semaphores.
     60  *	  Otherwise just make all programs using the database close it;
     61  *	  the lockfile is always reset on first open of the environment.
     62  *
     63  *	- On BSD systems or others configured with MDB_USE_POSIX_SEM,
     64  *	  startup can fail due to semaphores owned by another userid.
     65  *
     66  *	  Fix: Open and close the database as the user which owns the
     67  *	  semaphores (likely last user) or as root, while no other
     68  *	  process is using the database.
     69  *
     70  *	Restrictions/caveats (in addition to those listed for some functions):
     71  *
     72  *	- Only the database owner should normally use the database on
     73  *	  BSD systems or when otherwise configured with MDB_USE_POSIX_SEM.
     74  *	  Multiple users can cause startup to fail later, as noted above.
     75  *
     76  *	- There is normally no pure read-only mode, since readers need write
     77  *	  access to locks and lock file. Exceptions: On read-only filesystems
     78  *	  or with the #MDB_NOLOCK flag described under #mdb_env_open().
     79  *
     80  *	- An LMDB configuration will often reserve considerable \b unused
     81  *	  memory address space and maybe file size for future growth.
     82  *	  This does not use actual memory or disk space, but users may need
     83  *	  to understand the difference so they won't be scared off.
     84  *
     85  *	- By default, in versions before 0.9.10, unused portions of the data
     86  *	  file might receive garbage data from memory freed by other code.
     87  *	  (This does not happen when using the #MDB_WRITEMAP flag.) As of
     88  *	  0.9.10 the default behavior is to initialize such memory before
     89  *	  writing to the data file. Since there may be a slight performance
     90  *	  cost due to this initialization, applications may disable it using
     91  *	  the #MDB_NOMEMINIT flag. Applications handling sensitive data
     92  *	  which must not be written should not use this flag. This flag is
     93  *	  irrelevant when using #MDB_WRITEMAP.
     94  *
     95  *	- A thread can only use one transaction at a time, plus any child
     96  *	  transactions.  Each transaction belongs to one thread.  See below.
     97  *	  The #MDB_NOTLS flag changes this for read-only transactions.
     98  *
     99  *	- Use an MDB_env* in the process which opened it, not after fork().
    100  *
    101  *	- Do not have open an LMDB database twice in the same process at
    102  *	  the same time.  Not even from a plain open() call - close()ing it
    103  *	  breaks fcntl() advisory locking.  (It is OK to reopen it after
    104  *	  fork() - exec*(), since the lockfile has FD_CLOEXEC set.)
    105  *
    106  *	- Avoid long-lived transactions.  Read transactions prevent
    107  *	  reuse of pages freed by newer write transactions, thus the
    108  *	  database can grow quickly.  Write transactions prevent
    109  *	  other write transactions, since writes are serialized.
    110  *
    111  *	- Avoid suspending a process with active transactions.  These
    112  *	  would then be "long-lived" as above.  Also read transactions
    113  *	  suspended when writers commit could sometimes see wrong data.
    114  *
    115  *	...when several processes can use a database concurrently:
    116  *
    117  *	- Avoid aborting a process with an active transaction.
    118  *	  The transaction becomes "long-lived" as above until a check
    119  *	  for stale readers is performed or the lockfile is reset,
    120  *	  since the process may not remove it from the lockfile.
    121  *
    122  *	  This does not apply to write transactions if the system clears
    123  *	  stale writers, see above.
    124  *
    125  *	- If you do that anyway, do a periodic check for stale readers. Or
    126  *	  close the environment once in a while, so the lockfile can get reset.
    127  *
    128  *	- Do not use LMDB databases on remote filesystems, even between
    129  *	  processes on the same host.  This breaks flock() on some OSes,
    130  *	  possibly memory map sync, and certainly sync between programs
    131  *	  on different hosts.
    132  *
    133  *	- Opening a database can fail if another process is opening or
    134  *	  closing it at exactly the same time.
    135  *
    136  *	@author	Howard Chu, Symas Corporation.
    137  *
    138  *	@copyright Copyright 2011-2021 Howard Chu, Symas Corp. All rights reserved.
    139  *
    140  * Redistribution and use in source and binary forms, with or without
    141  * modification, are permitted only as authorized by the OpenLDAP
    142  * Public License.
    143  *
    144  * A copy of this license is available in the file LICENSE in the
    145  * top-level directory of the distribution or, alternatively, at
    146  * <http://www.OpenLDAP.org/license.html>.
    147  *
    148  *	@par Derived From:
    149  * This code is derived from btree.c written by Martin Hedenfalk.
    150  *
    151  * Copyright (c) 2009, 2010 Martin Hedenfalk <martin@bzero.se>
    152  *
    153  * Permission to use, copy, modify, and distribute this software for any
    154  * purpose with or without fee is hereby granted, provided that the above
    155  * copyright notice and this permission notice appear in all copies.
    156  *
    157  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
    158  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
    159  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
    160  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
    161  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
    162  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
    163  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
    164  */
    165 #ifndef _LMDB_H_
    166 #define _LMDB_H_
    167 
    168 #include <sys/types.h>
    169 
    170 #ifdef __cplusplus
    171 extern "C" {
    172 #endif
    173 
    174 /** Unix permissions for creating files, or dummy definition for Windows */
    175 #ifdef _MSC_VER
    176 typedef	int	mdb_mode_t;
    177 #else
    178 typedef	mode_t	mdb_mode_t;
    179 #endif
    180 
    181 /** An abstraction for a file handle.
    182  *	On POSIX systems file handles are small integers. On Windows
    183  *	they're opaque pointers.
    184  */
    185 #ifdef _WIN32
    186 typedef	void *mdb_filehandle_t;
    187 #else
    188 typedef int mdb_filehandle_t;
    189 #endif
    190 
    191 /** @defgroup mdb LMDB API
    192  *	@{
    193  *	@brief OpenLDAP Lightning Memory-Mapped Database Manager
    194  */
    195 /** @defgroup Version Version Macros
    196  *	@{
    197  */
    198 /** Library major version */
    199 #define MDB_VERSION_MAJOR	0
    200 /** Library minor version */
    201 #define MDB_VERSION_MINOR	9
    202 /** Library patch version */
    203 #define MDB_VERSION_PATCH	31
    204 
    205 /** Combine args a,b,c into a single integer for easy version comparisons */
    206 #define MDB_VERINT(a,b,c)	(((a) << 24) | ((b) << 16) | (c))
    207 
    208 /** The full library version as a single integer */
    209 #define MDB_VERSION_FULL	\
    210 	MDB_VERINT(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH)
    211 
    212 /** The release date of this library version */
    213 #define MDB_VERSION_DATE	"July 10, 2023"
    214 
    215 /** A stringifier for the version info */
    216 #define MDB_VERSTR(a,b,c,d)	"LMDB " #a "." #b "." #c ": (" d ")"
    217 
    218 /** A helper for the stringifier macro */
    219 #define MDB_VERFOO(a,b,c,d)	MDB_VERSTR(a,b,c,d)
    220 
    221 /** The full library version as a C string */
    222 #define	MDB_VERSION_STRING	\
    223 	MDB_VERFOO(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH,MDB_VERSION_DATE)
    224 /**	@} */
    225 
    226 /** @brief Opaque structure for a database environment.
    227  *
    228  * A DB environment supports multiple databases, all residing in the same
    229  * shared-memory map.
    230  */
    231 typedef struct MDB_env MDB_env;
    232 
    233 /** @brief Opaque structure for a transaction handle.
    234  *
    235  * All database operations require a transaction handle. Transactions may be
    236  * read-only or read-write.
    237  */
    238 typedef struct MDB_txn MDB_txn;
    239 
    240 /** @brief A handle for an individual database in the DB environment. */
    241 typedef unsigned int	MDB_dbi;
    242 
    243 /** @brief Opaque structure for navigating through a database */
    244 typedef struct MDB_cursor MDB_cursor;
    245 
    246 /** @brief Generic structure used for passing keys and data in and out
    247  * of the database.
    248  *
    249  * Values returned from the database are valid only until a subsequent
    250  * update operation, or the end of the transaction. Do not modify or
    251  * free them, they commonly point into the database itself.
    252  *
    253  * Key sizes must be between 1 and #mdb_env_get_maxkeysize() inclusive.
    254  * The same applies to data sizes in databases with the #MDB_DUPSORT flag.
    255  * Other data items can in theory be from 0 to 0xffffffff bytes long.
    256  */
    257 typedef struct MDB_val {
    258 	size_t		 mv_size;	/**< size of the data item */
    259 	void		*mv_data;	/**< address of the data item */
    260 } MDB_val;
    261 
    262 /** @brief A callback function used to compare two keys in a database */
    263 typedef int  (MDB_cmp_func)(const MDB_val *a, const MDB_val *b);
    264 
    265 /** @brief A callback function used to relocate a position-dependent data item
    266  * in a fixed-address database.
    267  *
    268  * The \b newptr gives the item's desired address in
    269  * the memory map, and \b oldptr gives its previous address. The item's actual
    270  * data resides at the address in \b item.  This callback is expected to walk
    271  * through the fields of the record in \b item and modify any
    272  * values based at the \b oldptr address to be relative to the \b newptr address.
    273  * @param[in,out] item The item that is to be relocated.
    274  * @param[in] oldptr The previous address.
    275  * @param[in] newptr The new address to relocate to.
    276  * @param[in] relctx An application-provided context, set by #mdb_set_relctx().
    277  * @todo This feature is currently unimplemented.
    278  */
    279 typedef void (MDB_rel_func)(MDB_val *item, void *oldptr, void *newptr, void *relctx);
    280 
    281 /** @defgroup	mdb_env	Environment Flags
    282  *	@{
    283  */
    284 	/** mmap at a fixed address (experimental) */
    285 #define MDB_FIXEDMAP	0x01
    286 	/** no environment directory */
    287 #define MDB_NOSUBDIR	0x4000
    288 	/** don't fsync after commit */
    289 #define MDB_NOSYNC		0x10000
    290 	/** read only */
    291 #define MDB_RDONLY		0x20000
    292 	/** don't fsync metapage after commit */
    293 #define MDB_NOMETASYNC		0x40000
    294 	/** use writable mmap */
    295 #define MDB_WRITEMAP		0x80000
    296 	/** use asynchronous msync when #MDB_WRITEMAP is used */
    297 #define MDB_MAPASYNC		0x100000
    298 	/** tie reader locktable slots to #MDB_txn objects instead of to threads */
    299 #define MDB_NOTLS		0x200000
    300 	/** don't do any locking, caller must manage their own locks */
    301 #define MDB_NOLOCK		0x400000
    302 	/** don't do readahead (no effect on Windows) */
    303 #define MDB_NORDAHEAD	0x800000
    304 	/** don't initialize malloc'd memory before writing to datafile */
    305 #define MDB_NOMEMINIT	0x1000000
    306 /** @} */
    307 
    308 /**	@defgroup	mdb_dbi_open	Database Flags
    309  *	@{
    310  */
    311 	/** use reverse string keys */
    312 #define MDB_REVERSEKEY	0x02
    313 	/** use sorted duplicates */
    314 #define MDB_DUPSORT		0x04
    315 	/** numeric keys in native byte order: either unsigned int or size_t.
    316 	 *  The keys must all be of the same size. */
    317 #define MDB_INTEGERKEY	0x08
    318 	/** with #MDB_DUPSORT, sorted dup items have fixed size */
    319 #define MDB_DUPFIXED	0x10
    320 	/** with #MDB_DUPSORT, dups are #MDB_INTEGERKEY-style integers */
    321 #define MDB_INTEGERDUP	0x20
    322 	/** with #MDB_DUPSORT, use reverse string dups */
    323 #define MDB_REVERSEDUP	0x40
    324 	/** create DB if not already existing */
    325 #define MDB_CREATE		0x40000
    326 /** @} */
    327 
    328 /**	@defgroup mdb_put	Write Flags
    329  *	@{
    330  */
    331 /** For put: Don't write if the key already exists. */
    332 #define MDB_NOOVERWRITE	0x10
    333 /** Only for #MDB_DUPSORT<br>
    334  * For put: don't write if the key and data pair already exist.<br>
    335  * For mdb_cursor_del: remove all duplicate data items.
    336  */
    337 #define MDB_NODUPDATA	0x20
    338 /** For mdb_cursor_put: overwrite the current key/data pair */
    339 #define MDB_CURRENT	0x40
    340 /** For put: Just reserve space for data, don't copy it. Return a
    341  * pointer to the reserved space.
    342  */
    343 #define MDB_RESERVE	0x10000
    344 /** Data is being appended, don't split full pages. */
    345 #define MDB_APPEND	0x20000
    346 /** Duplicate data is being appended, don't split full pages. */
    347 #define MDB_APPENDDUP	0x40000
    348 /** Store multiple data items in one call. Only for #MDB_DUPFIXED. */
    349 #define MDB_MULTIPLE	0x80000
    350 /*	@} */
    351 
    352 /**	@defgroup mdb_copy	Copy Flags
    353  *	@{
    354  */
    355 /** Compacting copy: Omit free space from copy, and renumber all
    356  * pages sequentially.
    357  */
    358 #define MDB_CP_COMPACT	0x01
    359 /*	@} */
    360 
    361 /** @brief Cursor Get operations.
    362  *
    363  *	This is the set of all operations for retrieving data
    364  *	using a cursor.
    365  */
    366 typedef enum MDB_cursor_op {
    367 	MDB_FIRST,				/**< Position at first key/data item */
    368 	MDB_FIRST_DUP,			/**< Position at first data item of current key.
    369 								Only for #MDB_DUPSORT */
    370 	MDB_GET_BOTH,			/**< Position at key/data pair. Only for #MDB_DUPSORT */
    371 	MDB_GET_BOTH_RANGE,		/**< position at key, nearest data. Only for #MDB_DUPSORT */
    372 	MDB_GET_CURRENT,		/**< Return key/data at current cursor position */
    373 	MDB_GET_MULTIPLE,		/**< Return up to a page of duplicate data items
    374 								from current cursor position. Move cursor to prepare
    375 								for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */
    376 	MDB_LAST,				/**< Position at last key/data item */
    377 	MDB_LAST_DUP,			/**< Position at last data item of current key.
    378 								Only for #MDB_DUPSORT */
    379 	MDB_NEXT,				/**< Position at next data item */
    380 	MDB_NEXT_DUP,			/**< Position at next data item of current key.
    381 								Only for #MDB_DUPSORT */
    382 	MDB_NEXT_MULTIPLE,		/**< Return up to a page of duplicate data items
    383 								from next cursor position. Move cursor to prepare
    384 								for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */
    385 	MDB_NEXT_NODUP,			/**< Position at first data item of next key */
    386 	MDB_PREV,				/**< Position at previous data item */
    387 	MDB_PREV_DUP,			/**< Position at previous data item of current key.
    388 								Only for #MDB_DUPSORT */
    389 	MDB_PREV_NODUP,			/**< Position at last data item of previous key */
    390 	MDB_SET,				/**< Position at specified key */
    391 	MDB_SET_KEY,			/**< Position at specified key, return key + data */
    392 	MDB_SET_RANGE,			/**< Position at first key greater than or equal to specified key. */
    393 	MDB_PREV_MULTIPLE		/**< Position at previous page and return up to
    394 								a page of duplicate data items. Only for #MDB_DUPFIXED */
    395 } MDB_cursor_op;
    396 
    397 /** @defgroup  errors	Return Codes
    398  *
    399  *	BerkeleyDB uses -30800 to -30999, we'll go under them
    400  *	@{
    401  */
    402 	/**	Successful result */
    403 #define MDB_SUCCESS	 0
    404 	/** key/data pair already exists */
    405 #define MDB_KEYEXIST	(-30799)
    406 	/** key/data pair not found (EOF) */
    407 #define MDB_NOTFOUND	(-30798)
    408 	/** Requested page not found - this usually indicates corruption */
    409 #define MDB_PAGE_NOTFOUND	(-30797)
    410 	/** Located page was wrong type */
    411 #define MDB_CORRUPTED	(-30796)
    412 	/** Update of meta page failed or environment had fatal error */
    413 #define MDB_PANIC		(-30795)
    414 	/** Environment version mismatch */
    415 #define MDB_VERSION_MISMATCH	(-30794)
    416 	/** File is not a valid LMDB file */
    417 #define MDB_INVALID	(-30793)
    418 	/** Environment mapsize reached */
    419 #define MDB_MAP_FULL	(-30792)
    420 	/** Environment maxdbs reached */
    421 #define MDB_DBS_FULL	(-30791)
    422 	/** Environment maxreaders reached */
    423 #define MDB_READERS_FULL	(-30790)
    424 	/** Too many TLS keys in use - Windows only */
    425 #define MDB_TLS_FULL	(-30789)
    426 	/** Txn has too many dirty pages */
    427 #define MDB_TXN_FULL	(-30788)
    428 	/** Cursor stack too deep - internal error */
    429 #define MDB_CURSOR_FULL	(-30787)
    430 	/** Page has not enough space - internal error */
    431 #define MDB_PAGE_FULL	(-30786)
    432 	/** Database contents grew beyond environment mapsize */
    433 #define MDB_MAP_RESIZED	(-30785)
    434 	/** Operation and DB incompatible, or DB type changed. This can mean:
    435 	 *	<ul>
    436 	 *	<li>The operation expects an #MDB_DUPSORT / #MDB_DUPFIXED database.
    437 	 *	<li>Opening a named DB when the unnamed DB has #MDB_DUPSORT / #MDB_INTEGERKEY.
    438 	 *	<li>Accessing a data record as a database, or vice versa.
    439 	 *	<li>The database was dropped and recreated with different flags.
    440 	 *	</ul>
    441 	 */
    442 #define MDB_INCOMPATIBLE	(-30784)
    443 	/** Invalid reuse of reader locktable slot */
    444 #define MDB_BAD_RSLOT		(-30783)
    445 	/** Transaction must abort, has a child, or is invalid */
    446 #define MDB_BAD_TXN			(-30782)
    447 	/** Unsupported size of key/DB name/data, or wrong DUPFIXED size */
    448 #define MDB_BAD_VALSIZE		(-30781)
    449 	/** The specified DBI was changed unexpectedly */
    450 #define MDB_BAD_DBI		(-30780)
    451 	/** The last defined error code */
    452 #define MDB_LAST_ERRCODE	MDB_BAD_DBI
    453 /** @} */
    454 
    455 /** @brief Statistics for a database in the environment */
    456 typedef struct MDB_stat {
    457 	unsigned int	ms_psize;			/**< Size of a database page.
    458 											This is currently the same for all databases. */
    459 	unsigned int	ms_depth;			/**< Depth (height) of the B-tree */
    460 	size_t		ms_branch_pages;	/**< Number of internal (non-leaf) pages */
    461 	size_t		ms_leaf_pages;		/**< Number of leaf pages */
    462 	size_t		ms_overflow_pages;	/**< Number of overflow pages */
    463 	size_t		ms_entries;			/**< Number of data items */
    464 } MDB_stat;
    465 
    466 /** @brief Information about the environment */
    467 typedef struct MDB_envinfo {
    468 	void	*me_mapaddr;			/**< Address of map, if fixed */
    469 	size_t	me_mapsize;				/**< Size of the data memory map */
    470 	size_t	me_last_pgno;			/**< ID of the last used page */
    471 	size_t	me_last_txnid;			/**< ID of the last committed transaction */
    472 	unsigned int me_maxreaders;		/**< max reader slots in the environment */
    473 	unsigned int me_numreaders;		/**< max reader slots used in the environment */
    474 } MDB_envinfo;
    475 
    476 	/** @brief Return the LMDB library version information.
    477 	 *
    478 	 * @param[out] major if non-NULL, the library major version number is copied here
    479 	 * @param[out] minor if non-NULL, the library minor version number is copied here
    480 	 * @param[out] patch if non-NULL, the library patch version number is copied here
    481 	 * @retval "version string" The library version as a string
    482 	 */
    483 char *mdb_version(int *major, int *minor, int *patch);
    484 
    485 	/** @brief Return a string describing a given error code.
    486 	 *
    487 	 * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3)
    488 	 * function. If the error code is greater than or equal to 0, then the string
    489 	 * returned by the system function strerror(3) is returned. If the error code
    490 	 * is less than 0, an error string corresponding to the LMDB library error is
    491 	 * returned. See @ref errors for a list of LMDB-specific error codes.
    492 	 * @param[in] err The error code
    493 	 * @retval "error message" The description of the error
    494 	 */
    495 char *mdb_strerror(int err);
    496 
    497 	/** @brief Create an LMDB environment handle.
    498 	 *
    499 	 * This function allocates memory for a #MDB_env structure. To release
    500 	 * the allocated memory and discard the handle, call #mdb_env_close().
    501 	 * Before the handle may be used, it must be opened using #mdb_env_open().
    502 	 * Various other options may also need to be set before opening the handle,
    503 	 * e.g. #mdb_env_set_mapsize(), #mdb_env_set_maxreaders(), #mdb_env_set_maxdbs(),
    504 	 * depending on usage requirements.
    505 	 * @param[out] env The address where the new handle will be stored
    506 	 * @return A non-zero error value on failure and 0 on success.
    507 	 */
    508 int  mdb_env_create(MDB_env **env);
    509 
    510 	/** @brief Open an environment handle.
    511 	 *
    512 	 * If this function fails, #mdb_env_close() must be called to discard the #MDB_env handle.
    513 	 * @param[in] env An environment handle returned by #mdb_env_create()
    514 	 * @param[in] path The directory in which the database files reside. This
    515 	 * directory must already exist and be writable.
    516 	 * @param[in] flags Special options for this environment. This parameter
    517 	 * must be set to 0 or by bitwise OR'ing together one or more of the
    518 	 * values described here.
    519 	 * Flags set by mdb_env_set_flags() are also used.
    520 	 * <ul>
    521 	 *	<li>#MDB_FIXEDMAP
    522 	 *      use a fixed address for the mmap region. This flag must be specified
    523 	 *      when creating the environment, and is stored persistently in the environment.
    524 	 *		If successful, the memory map will always reside at the same virtual address
    525 	 *		and pointers used to reference data items in the database will be constant
    526 	 *		across multiple invocations. This option may not always work, depending on
    527 	 *		how the operating system has allocated memory to shared libraries and other uses.
    528 	 *		The feature is highly experimental.
    529 	 *	<li>#MDB_NOSUBDIR
    530 	 *		By default, LMDB creates its environment in a directory whose
    531 	 *		pathname is given in \b path, and creates its data and lock files
    532 	 *		under that directory. With this option, \b path is used as-is for
    533 	 *		the database main data file. The database lock file is the \b path
    534 	 *		with "-lock" appended.
    535 	 *	<li>#MDB_RDONLY
    536 	 *		Open the environment in read-only mode. No write operations will be
    537 	 *		allowed. LMDB will still modify the lock file - except on read-only
    538 	 *		filesystems, where LMDB does not use locks.
    539 	 *	<li>#MDB_WRITEMAP
    540 	 *		Use a writeable memory map unless MDB_RDONLY is set. This uses
    541 	 *		fewer mallocs but loses protection from application bugs
    542 	 *		like wild pointer writes and other bad updates into the database.
    543 	 *		This may be slightly faster for DBs that fit entirely in RAM, but
    544 	 *		is slower for DBs larger than RAM.
    545 	 *		Incompatible with nested transactions.
    546 	 *		Do not mix processes with and without MDB_WRITEMAP on the same
    547 	 *		environment.  This can defeat durability (#mdb_env_sync etc).
    548 	 *	<li>#MDB_NOMETASYNC
    549 	 *		Flush system buffers to disk only once per transaction, omit the
    550 	 *		metadata flush. Defer that until the system flushes files to disk,
    551 	 *		or next non-MDB_RDONLY commit or #mdb_env_sync(). This optimization
    552 	 *		maintains database integrity, but a system crash may undo the last
    553 	 *		committed transaction. I.e. it preserves the ACI (atomicity,
    554 	 *		consistency, isolation) but not D (durability) database property.
    555 	 *		This flag may be changed at any time using #mdb_env_set_flags().
    556 	 *	<li>#MDB_NOSYNC
    557 	 *		Don't flush system buffers to disk when committing a transaction.
    558 	 *		This optimization means a system crash can corrupt the database or
    559 	 *		lose the last transactions if buffers are not yet flushed to disk.
    560 	 *		The risk is governed by how often the system flushes dirty buffers
    561 	 *		to disk and how often #mdb_env_sync() is called.  However, if the
    562 	 *		filesystem preserves write order and the #MDB_WRITEMAP flag is not
    563 	 *		used, transactions exhibit ACI (atomicity, consistency, isolation)
    564 	 *		properties and only lose D (durability).  I.e. database integrity
    565 	 *		is maintained, but a system crash may undo the final transactions.
    566 	 *		Note that (#MDB_NOSYNC | #MDB_WRITEMAP) leaves the system with no
    567 	 *		hint for when to write transactions to disk, unless #mdb_env_sync()
    568 	 *		is called. (#MDB_MAPASYNC | #MDB_WRITEMAP) may be preferable.
    569 	 *		This flag may be changed at any time using #mdb_env_set_flags().
    570 	 *	<li>#MDB_MAPASYNC
    571 	 *		When using #MDB_WRITEMAP, use asynchronous flushes to disk.
    572 	 *		As with #MDB_NOSYNC, a system crash can then corrupt the
    573 	 *		database or lose the last transactions. Calling #mdb_env_sync()
    574 	 *		ensures on-disk database integrity until next commit.
    575 	 *		This flag may be changed at any time using #mdb_env_set_flags().
    576 	 *	<li>#MDB_NOTLS
    577 	 *		Don't use Thread-Local Storage. Tie reader locktable slots to
    578 	 *		#MDB_txn objects instead of to threads. I.e. #mdb_txn_reset() keeps
    579 	 *		the slot reserved for the #MDB_txn object. A thread may use parallel
    580 	 *		read-only transactions. A read-only transaction may span threads if
    581 	 *		the user synchronizes its use. Applications that multiplex many
    582 	 *		user threads over individual OS threads need this option. Such an
    583 	 *		application must also serialize the write transactions in an OS
    584 	 *		thread, since LMDB's write locking is unaware of the user threads.
    585 	 *	<li>#MDB_NOLOCK
    586 	 *		Don't do any locking. If concurrent access is anticipated, the
    587 	 *		caller must manage all concurrency itself. For proper operation
    588 	 *		the caller must enforce single-writer semantics, and must ensure
    589 	 *		that no readers are using old transactions while a writer is
    590 	 *		active. The simplest approach is to use an exclusive lock so that
    591 	 *		no readers may be active at all when a writer begins.
    592 	 *	<li>#MDB_NORDAHEAD
    593 	 *		Turn off readahead. Most operating systems perform readahead on
    594 	 *		read requests by default. This option turns it off if the OS
    595 	 *		supports it. Turning it off may help random read performance
    596 	 *		when the DB is larger than RAM and system RAM is full.
    597 	 *		The option is not implemented on Windows.
    598 	 *	<li>#MDB_NOMEMINIT
    599 	 *		Don't initialize malloc'd memory before writing to unused spaces
    600 	 *		in the data file. By default, memory for pages written to the data
    601 	 *		file is obtained using malloc. While these pages may be reused in
    602 	 *		subsequent transactions, freshly malloc'd pages will be initialized
    603 	 *		to zeroes before use. This avoids persisting leftover data from other
    604 	 *		code (that used the heap and subsequently freed the memory) into the
    605 	 *		data file. Note that many other system libraries may allocate
    606 	 *		and free memory from the heap for arbitrary uses. E.g., stdio may
    607 	 *		use the heap for file I/O buffers. This initialization step has a
    608 	 *		modest performance cost so some applications may want to disable
    609 	 *		it using this flag. This option can be a problem for applications
    610 	 *		which handle sensitive data like passwords, and it makes memory
    611 	 *		checkers like Valgrind noisy. This flag is not needed with #MDB_WRITEMAP,
    612 	 *		which writes directly to the mmap instead of using malloc for pages. The
    613 	 *		initialization is also skipped if #MDB_RESERVE is used; the
    614 	 *		caller is expected to overwrite all of the memory that was
    615 	 *		reserved in that case.
    616 	 *		This flag may be changed at any time using #mdb_env_set_flags().
    617 	 * </ul>
    618 	 * @param[in] mode The UNIX permissions to set on created files and semaphores.
    619 	 * This parameter is ignored on Windows.
    620 	 * @return A non-zero error value on failure and 0 on success. Some possible
    621 	 * errors are:
    622 	 * <ul>
    623 	 *	<li>#MDB_VERSION_MISMATCH - the version of the LMDB library doesn't match the
    624 	 *	version that created the database environment.
    625 	 *	<li>#MDB_INVALID - the environment file headers are corrupted.
    626 	 *	<li>ENOENT - the directory specified by the path parameter doesn't exist.
    627 	 *	<li>EACCES - the user didn't have permission to access the environment files.
    628 	 *	<li>EAGAIN - the environment was locked by another process.
    629 	 * </ul>
    630 	 */
    631 int  mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mdb_mode_t mode);
    632 
    633 	/** @brief Copy an LMDB environment to the specified path.
    634 	 *
    635 	 * This function may be used to make a backup of an existing environment.
    636 	 * No lockfile is created, since it gets recreated at need.
    637 	 * @note This call can trigger significant file size growth if run in
    638 	 * parallel with write transactions, because it employs a read-only
    639 	 * transaction. See long-lived transactions under @ref caveats_sec.
    640 	 * @param[in] env An environment handle returned by #mdb_env_create(). It
    641 	 * must have already been opened successfully.
    642 	 * @param[in] path The directory in which the copy will reside. This
    643 	 * directory must already exist and be writable but must otherwise be
    644 	 * empty.
    645 	 * @return A non-zero error value on failure and 0 on success.
    646 	 */
    647 int  mdb_env_copy(MDB_env *env, const char *path);
    648 
    649 	/** @brief Copy an LMDB environment to the specified file descriptor.
    650 	 *
    651 	 * This function may be used to make a backup of an existing environment.
    652 	 * No lockfile is created, since it gets recreated at need.
    653 	 * @note This call can trigger significant file size growth if run in
    654 	 * parallel with write transactions, because it employs a read-only
    655 	 * transaction. See long-lived transactions under @ref caveats_sec.
    656 	 * @param[in] env An environment handle returned by #mdb_env_create(). It
    657 	 * must have already been opened successfully.
    658 	 * @param[in] fd The filedescriptor to write the copy to. It must
    659 	 * have already been opened for Write access.
    660 	 * @return A non-zero error value on failure and 0 on success.
    661 	 */
    662 int  mdb_env_copyfd(MDB_env *env, mdb_filehandle_t fd);
    663 
    664 	/** @brief Copy an LMDB environment to the specified path, with options.
    665 	 *
    666 	 * This function may be used to make a backup of an existing environment.
    667 	 * No lockfile is created, since it gets recreated at need.
    668 	 * @note This call can trigger significant file size growth if run in
    669 	 * parallel with write transactions, because it employs a read-only
    670 	 * transaction. See long-lived transactions under @ref caveats_sec.
    671 	 * @param[in] env An environment handle returned by #mdb_env_create(). It
    672 	 * must have already been opened successfully.
    673 	 * @param[in] path The directory in which the copy will reside. This
    674 	 * directory must already exist and be writable but must otherwise be
    675 	 * empty.
    676 	 * @param[in] flags Special options for this operation. This parameter
    677 	 * must be set to 0 or by bitwise OR'ing together one or more of the
    678 	 * values described here.
    679 	 * <ul>
    680 	 *	<li>#MDB_CP_COMPACT - Perform compaction while copying: omit free
    681 	 *		pages and sequentially renumber all pages in output. This option
    682 	 *		consumes more CPU and runs more slowly than the default.
    683 	 *		Currently it fails if the environment has suffered a page leak.
    684 	 * </ul>
    685 	 * @return A non-zero error value on failure and 0 on success.
    686 	 */
    687 int  mdb_env_copy2(MDB_env *env, const char *path, unsigned int flags);
    688 
    689 	/** @brief Copy an LMDB environment to the specified file descriptor,
    690 	 *	with options.
    691 	 *
    692 	 * This function may be used to make a backup of an existing environment.
    693 	 * No lockfile is created, since it gets recreated at need. See
    694 	 * #mdb_env_copy2() for further details.
    695 	 * @note This call can trigger significant file size growth if run in
    696 	 * parallel with write transactions, because it employs a read-only
    697 	 * transaction. See long-lived transactions under @ref caveats_sec.
    698 	 * @param[in] env An environment handle returned by #mdb_env_create(). It
    699 	 * must have already been opened successfully.
    700 	 * @param[in] fd The filedescriptor to write the copy to. It must
    701 	 * have already been opened for Write access.
    702 	 * @param[in] flags Special options for this operation.
    703 	 * See #mdb_env_copy2() for options.
    704 	 * @return A non-zero error value on failure and 0 on success.
    705 	 */
    706 int  mdb_env_copyfd2(MDB_env *env, mdb_filehandle_t fd, unsigned int flags);
    707 
    708 	/** @brief Return statistics about the LMDB environment.
    709 	 *
    710 	 * @param[in] env An environment handle returned by #mdb_env_create()
    711 	 * @param[out] stat The address of an #MDB_stat structure
    712 	 * 	where the statistics will be copied
    713 	 */
    714 int  mdb_env_stat(MDB_env *env, MDB_stat *stat);
    715 
    716 	/** @brief Return information about the LMDB environment.
    717 	 *
    718 	 * @param[in] env An environment handle returned by #mdb_env_create()
    719 	 * @param[out] stat The address of an #MDB_envinfo structure
    720 	 * 	where the information will be copied
    721 	 */
    722 int  mdb_env_info(MDB_env *env, MDB_envinfo *stat);
    723 
    724 	/** @brief Flush the data buffers to disk.
    725 	 *
    726 	 * Data is always written to disk when #mdb_txn_commit() is called,
    727 	 * but the operating system may keep it buffered. LMDB always flushes
    728 	 * the OS buffers upon commit as well, unless the environment was
    729 	 * opened with #MDB_NOSYNC or in part #MDB_NOMETASYNC. This call is
    730 	 * not valid if the environment was opened with #MDB_RDONLY.
    731 	 * @param[in] env An environment handle returned by #mdb_env_create()
    732 	 * @param[in] force If non-zero, force a synchronous flush.  Otherwise
    733 	 *  if the environment has the #MDB_NOSYNC flag set the flushes
    734 	 *	will be omitted, and with #MDB_MAPASYNC they will be asynchronous.
    735 	 * @return A non-zero error value on failure and 0 on success. Some possible
    736 	 * errors are:
    737 	 * <ul>
    738 	 *	<li>EACCES - the environment is read-only.
    739 	 *	<li>EINVAL - an invalid parameter was specified.
    740 	 *	<li>EIO - an error occurred during synchronization.
    741 	 * </ul>
    742 	 */
    743 int  mdb_env_sync(MDB_env *env, int force);
    744 
    745 	/** @brief Close the environment and release the memory map.
    746 	 *
    747 	 * Only a single thread may call this function. All transactions, databases,
    748 	 * and cursors must already be closed before calling this function. Attempts to
    749 	 * use any such handles after calling this function will cause a SIGSEGV.
    750 	 * The environment handle will be freed and must not be used again after this call.
    751 	 * @param[in] env An environment handle returned by #mdb_env_create()
    752 	 */
    753 void mdb_env_close(MDB_env *env);
    754 
    755 	/** @brief Set environment flags.
    756 	 *
    757 	 * This may be used to set some flags in addition to those from
    758 	 * #mdb_env_open(), or to unset these flags.  If several threads
    759 	 * change the flags at the same time, the result is undefined.
    760 	 * @param[in] env An environment handle returned by #mdb_env_create()
    761 	 * @param[in] flags The flags to change, bitwise OR'ed together
    762 	 * @param[in] onoff A non-zero value sets the flags, zero clears them.
    763 	 * @return A non-zero error value on failure and 0 on success. Some possible
    764 	 * errors are:
    765 	 * <ul>
    766 	 *	<li>EINVAL - an invalid parameter was specified.
    767 	 * </ul>
    768 	 */
    769 int  mdb_env_set_flags(MDB_env *env, unsigned int flags, int onoff);
    770 
    771 	/** @brief Get environment flags.
    772 	 *
    773 	 * @param[in] env An environment handle returned by #mdb_env_create()
    774 	 * @param[out] flags The address of an integer to store the flags
    775 	 * @return A non-zero error value on failure and 0 on success. Some possible
    776 	 * errors are:
    777 	 * <ul>
    778 	 *	<li>EINVAL - an invalid parameter was specified.
    779 	 * </ul>
    780 	 */
    781 int  mdb_env_get_flags(MDB_env *env, unsigned int *flags);
    782 
    783 	/** @brief Return the path that was used in #mdb_env_open().
    784 	 *
    785 	 * @param[in] env An environment handle returned by #mdb_env_create()
    786 	 * @param[out] path Address of a string pointer to contain the path. This
    787 	 * is the actual string in the environment, not a copy. It should not be
    788 	 * altered in any way.
    789 	 * @return A non-zero error value on failure and 0 on success. Some possible
    790 	 * errors are:
    791 	 * <ul>
    792 	 *	<li>EINVAL - an invalid parameter was specified.
    793 	 * </ul>
    794 	 */
    795 int  mdb_env_get_path(MDB_env *env, const char **path);
    796 
    797 	/** @brief Return the filedescriptor for the given environment.
    798 	 *
    799 	 * This function may be called after fork(), so the descriptor can be
    800 	 * closed before exec*().  Other LMDB file descriptors have FD_CLOEXEC.
    801 	 * (Until LMDB 0.9.18, only the lockfile had that.)
    802 	 *
    803 	 * @param[in] env An environment handle returned by #mdb_env_create()
    804 	 * @param[out] fd Address of a mdb_filehandle_t to contain the descriptor.
    805 	 * @return A non-zero error value on failure and 0 on success. Some possible
    806 	 * errors are:
    807 	 * <ul>
    808 	 *	<li>EINVAL - an invalid parameter was specified.
    809 	 * </ul>
    810 	 */
    811 int  mdb_env_get_fd(MDB_env *env, mdb_filehandle_t *fd);
    812 
    813 	/** @brief Set the size of the memory map to use for this environment.
    814 	 *
    815 	 * The size should be a multiple of the OS page size. The default is
    816 	 * 10485760 bytes. The size of the memory map is also the maximum size
    817 	 * of the database. The value should be chosen as large as possible,
    818 	 * to accommodate future growth of the database.
    819 	 * This function should be called after #mdb_env_create() and before #mdb_env_open().
    820 	 * It may be called at later times if no transactions are active in
    821 	 * this process. Note that the library does not check for this condition,
    822 	 * the caller must ensure it explicitly.
    823 	 *
    824 	 * The new size takes effect immediately for the current process but
    825 	 * will not be persisted to any others until a write transaction has been
    826 	 * committed by the current process. Also, only mapsize increases are
    827 	 * persisted into the environment.
    828 	 *
    829 	 * If the mapsize is increased by another process, and data has grown
    830 	 * beyond the range of the current mapsize, #mdb_txn_begin() will
    831 	 * return #MDB_MAP_RESIZED. This function may be called with a size
    832 	 * of zero to adopt the new size.
    833 	 *
    834 	 * Any attempt to set a size smaller than the space already consumed
    835 	 * by the environment will be silently changed to the current size of the used space.
    836 	 * @param[in] env An environment handle returned by #mdb_env_create()
    837 	 * @param[in] size The size in bytes
    838 	 * @return A non-zero error value on failure and 0 on success. Some possible
    839 	 * errors are:
    840 	 * <ul>
    841 	 *	<li>EINVAL - an invalid parameter was specified, or the environment has
    842 	 *   	an active write transaction.
    843 	 * </ul>
    844 	 */
    845 int  mdb_env_set_mapsize(MDB_env *env, size_t size);
    846 
    847 	/** @brief Set the maximum number of threads/reader slots for the environment.
    848 	 *
    849 	 * This defines the number of slots in the lock table that is used to track readers in the
    850 	 * the environment. The default is 126.
    851 	 * Starting a read-only transaction normally ties a lock table slot to the
    852 	 * current thread until the environment closes or the thread exits. If
    853 	 * MDB_NOTLS is in use, #mdb_txn_begin() instead ties the slot to the
    854 	 * MDB_txn object until it or the #MDB_env object is destroyed.
    855 	 * This function may only be called after #mdb_env_create() and before #mdb_env_open().
    856 	 * @param[in] env An environment handle returned by #mdb_env_create()
    857 	 * @param[in] readers The maximum number of reader lock table slots
    858 	 * @return A non-zero error value on failure and 0 on success. Some possible
    859 	 * errors are:
    860 	 * <ul>
    861 	 *	<li>EINVAL - an invalid parameter was specified, or the environment is already open.
    862 	 * </ul>
    863 	 */
    864 int  mdb_env_set_maxreaders(MDB_env *env, unsigned int readers);
    865 
    866 	/** @brief Get the maximum number of threads/reader slots for the environment.
    867 	 *
    868 	 * @param[in] env An environment handle returned by #mdb_env_create()
    869 	 * @param[out] readers Address of an integer to store the number of readers
    870 	 * @return A non-zero error value on failure and 0 on success. Some possible
    871 	 * errors are:
    872 	 * <ul>
    873 	 *	<li>EINVAL - an invalid parameter was specified.
    874 	 * </ul>
    875 	 */
    876 int  mdb_env_get_maxreaders(MDB_env *env, unsigned int *readers);
    877 
    878 	/** @brief Set the maximum number of named databases for the environment.
    879 	 *
    880 	 * This function is only needed if multiple databases will be used in the
    881 	 * environment. Simpler applications that use the environment as a single
    882 	 * unnamed database can ignore this option.
    883 	 * This function may only be called after #mdb_env_create() and before #mdb_env_open().
    884 	 *
    885 	 * Currently a moderate number of slots are cheap but a huge number gets
    886 	 * expensive: 7-120 words per transaction, and every #mdb_dbi_open()
    887 	 * does a linear search of the opened slots.
    888 	 * @param[in] env An environment handle returned by #mdb_env_create()
    889 	 * @param[in] dbs The maximum number of databases
    890 	 * @return A non-zero error value on failure and 0 on success. Some possible
    891 	 * errors are:
    892 	 * <ul>
    893 	 *	<li>EINVAL - an invalid parameter was specified, or the environment is already open.
    894 	 * </ul>
    895 	 */
    896 int  mdb_env_set_maxdbs(MDB_env *env, MDB_dbi dbs);
    897 
    898 	/** @brief Get the maximum size of keys and #MDB_DUPSORT data we can write.
    899 	 *
    900 	 * Depends on the compile-time constant #MDB_MAXKEYSIZE. Default 511.
    901 	 * See @ref MDB_val.
    902 	 * @param[in] env An environment handle returned by #mdb_env_create()
    903 	 * @return The maximum size of a key we can write
    904 	 */
    905 int  mdb_env_get_maxkeysize(MDB_env *env);
    906 
    907 	/** @brief Set application information associated with the #MDB_env.
    908 	 *
    909 	 * @param[in] env An environment handle returned by #mdb_env_create()
    910 	 * @param[in] ctx An arbitrary pointer for whatever the application needs.
    911 	 * @return A non-zero error value on failure and 0 on success.
    912 	 */
    913 int  mdb_env_set_userctx(MDB_env *env, void *ctx);
    914 
    915 	/** @brief Get the application information associated with the #MDB_env.
    916 	 *
    917 	 * @param[in] env An environment handle returned by #mdb_env_create()
    918 	 * @return The pointer set by #mdb_env_set_userctx().
    919 	 */
    920 void *mdb_env_get_userctx(MDB_env *env);
    921 
    922 	/** @brief A callback function for most LMDB assert() failures,
    923 	 * called before printing the message and aborting.
    924 	 *
    925 	 * @param[in] env An environment handle returned by #mdb_env_create().
    926 	 * @param[in] msg The assertion message, not including newline.
    927 	 */
    928 typedef void MDB_assert_func(MDB_env *env, const char *msg);
    929 
    930 	/** Set or reset the assert() callback of the environment.
    931 	 * Disabled if liblmdb is built with NDEBUG.
    932 	 * @note This hack should become obsolete as lmdb's error handling matures.
    933 	 * @param[in] env An environment handle returned by #mdb_env_create().
    934 	 * @param[in] func An #MDB_assert_func function, or 0.
    935 	 * @return A non-zero error value on failure and 0 on success.
    936 	 */
    937 int  mdb_env_set_assert(MDB_env *env, MDB_assert_func *func);
    938 
    939 	/** @brief Create a transaction for use with the environment.
    940 	 *
    941 	 * The transaction handle may be discarded using #mdb_txn_abort() or #mdb_txn_commit().
    942 	 * @note A transaction and its cursors must only be used by a single
    943 	 * thread, and a thread may only have a single transaction at a time.
    944 	 * If #MDB_NOTLS is in use, this does not apply to read-only transactions.
    945 	 * @note Cursors may not span transactions.
    946 	 * @param[in] env An environment handle returned by #mdb_env_create()
    947 	 * @param[in] parent If this parameter is non-NULL, the new transaction
    948 	 * will be a nested transaction, with the transaction indicated by \b parent
    949 	 * as its parent. Transactions may be nested to any level. A parent
    950 	 * transaction and its cursors may not issue any other operations than
    951 	 * mdb_txn_commit and mdb_txn_abort while it has active child transactions.
    952 	 * @param[in] flags Special options for this transaction. This parameter
    953 	 * must be set to 0 or by bitwise OR'ing together one or more of the
    954 	 * values described here.
    955 	 * <ul>
    956 	 *	<li>#MDB_RDONLY
    957 	 *		This transaction will not perform any write operations.
    958 	 * </ul>
    959 	 * @param[out] txn Address where the new #MDB_txn handle will be stored
    960 	 * @return A non-zero error value on failure and 0 on success. Some possible
    961 	 * errors are:
    962 	 * <ul>
    963 	 *	<li>#MDB_PANIC - a fatal error occurred earlier and the environment
    964 	 *		must be shut down.
    965 	 *	<li>#MDB_MAP_RESIZED - another process wrote data beyond this MDB_env's
    966 	 *		mapsize and this environment's map must be resized as well.
    967 	 *		See #mdb_env_set_mapsize().
    968 	 *	<li>#MDB_READERS_FULL - a read-only transaction was requested and
    969 	 *		the reader lock table is full. See #mdb_env_set_maxreaders().
    970 	 *	<li>ENOMEM - out of memory.
    971 	 * </ul>
    972 	 */
    973 int  mdb_txn_begin(MDB_env *env, MDB_txn *parent, unsigned int flags, MDB_txn **txn);
    974 
    975 	/** @brief Returns the transaction's #MDB_env
    976 	 *
    977 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
    978 	 */
    979 MDB_env *mdb_txn_env(MDB_txn *txn);
    980 
    981 	/** @brief Return the transaction's ID.
    982 	 *
    983 	 * This returns the identifier associated with this transaction. For a
    984 	 * read-only transaction, this corresponds to the snapshot being read;
    985 	 * concurrent readers will frequently have the same transaction ID.
    986 	 *
    987 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
    988 	 * @return A transaction ID, valid if input is an active transaction.
    989 	 */
    990 size_t mdb_txn_id(MDB_txn *txn);
    991 
    992 	/** @brief Commit all the operations of a transaction into the database.
    993 	 *
    994 	 * The transaction handle is freed. It and its cursors must not be used
    995 	 * again after this call, except with #mdb_cursor_renew().
    996 	 * @note Earlier documentation incorrectly said all cursors would be freed.
    997 	 * Only write-transactions free cursors.
    998 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
    999 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1000 	 * errors are:
   1001 	 * <ul>
   1002 	 *	<li>EINVAL - an invalid parameter was specified.
   1003 	 *	<li>ENOSPC - no more disk space.
   1004 	 *	<li>EIO - a low-level I/O error occurred while writing.
   1005 	 *	<li>ENOMEM - out of memory.
   1006 	 * </ul>
   1007 	 */
   1008 int  mdb_txn_commit(MDB_txn *txn);
   1009 
   1010 	/** @brief Abandon all the operations of the transaction instead of saving them.
   1011 	 *
   1012 	 * The transaction handle is freed. It and its cursors must not be used
   1013 	 * again after this call, except with #mdb_cursor_renew().
   1014 	 * @note Earlier documentation incorrectly said all cursors would be freed.
   1015 	 * Only write-transactions free cursors.
   1016 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1017 	 */
   1018 void mdb_txn_abort(MDB_txn *txn);
   1019 
   1020 	/** @brief Reset a read-only transaction.
   1021 	 *
   1022 	 * Abort the transaction like #mdb_txn_abort(), but keep the transaction
   1023 	 * handle. #mdb_txn_renew() may reuse the handle. This saves allocation
   1024 	 * overhead if the process will start a new read-only transaction soon,
   1025 	 * and also locking overhead if #MDB_NOTLS is in use. The reader table
   1026 	 * lock is released, but the table slot stays tied to its thread or
   1027 	 * #MDB_txn. Use mdb_txn_abort() to discard a reset handle, and to free
   1028 	 * its lock table slot if MDB_NOTLS is in use.
   1029 	 * Cursors opened within the transaction must not be used
   1030 	 * again after this call, except with #mdb_cursor_renew().
   1031 	 * Reader locks generally don't interfere with writers, but they keep old
   1032 	 * versions of database pages allocated. Thus they prevent the old pages
   1033 	 * from being reused when writers commit new data, and so under heavy load
   1034 	 * the database size may grow much more rapidly than otherwise.
   1035 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1036 	 */
   1037 void mdb_txn_reset(MDB_txn *txn);
   1038 
   1039 	/** @brief Renew a read-only transaction.
   1040 	 *
   1041 	 * This acquires a new reader lock for a transaction handle that had been
   1042 	 * released by #mdb_txn_reset(). It must be called before a reset transaction
   1043 	 * may be used again.
   1044 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1045 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1046 	 * errors are:
   1047 	 * <ul>
   1048 	 *	<li>#MDB_PANIC - a fatal error occurred earlier and the environment
   1049 	 *		must be shut down.
   1050 	 *	<li>EINVAL - an invalid parameter was specified.
   1051 	 * </ul>
   1052 	 */
   1053 int  mdb_txn_renew(MDB_txn *txn);
   1054 
   1055 /** Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project */
   1056 #define mdb_open(txn,name,flags,dbi)	mdb_dbi_open(txn,name,flags,dbi)
   1057 /** Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project */
   1058 #define mdb_close(env,dbi)				mdb_dbi_close(env,dbi)
   1059 
   1060 	/** @brief Open a database in the environment.
   1061 	 *
   1062 	 * A database handle denotes the name and parameters of a database,
   1063 	 * independently of whether such a database exists.
   1064 	 * The database handle may be discarded by calling #mdb_dbi_close().
   1065 	 * The old database handle is returned if the database was already open.
   1066 	 * The handle may only be closed once.
   1067 	 *
   1068 	 * The database handle will be private to the current transaction until
   1069 	 * the transaction is successfully committed. If the transaction is
   1070 	 * aborted the handle will be closed automatically.
   1071 	 * After a successful commit the handle will reside in the shared
   1072 	 * environment, and may be used by other transactions.
   1073 	 *
   1074 	 * This function must not be called from multiple concurrent
   1075 	 * transactions in the same process. A transaction that uses
   1076 	 * this function must finish (either commit or abort) before
   1077 	 * any other transaction in the process may use this function.
   1078 	 *
   1079 	 * To use named databases (with name != NULL), #mdb_env_set_maxdbs()
   1080 	 * must be called before opening the environment.  Database names are
   1081 	 * keys in the unnamed database, and may be read but not written.
   1082 	 *
   1083 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1084 	 * @param[in] name The name of the database to open. If only a single
   1085 	 * 	database is needed in the environment, this value may be NULL.
   1086 	 * @param[in] flags Special options for this database. This parameter
   1087 	 * must be set to 0 or by bitwise OR'ing together one or more of the
   1088 	 * values described here.
   1089 	 * <ul>
   1090 	 *	<li>#MDB_REVERSEKEY
   1091 	 *		Keys are strings to be compared in reverse order, from the end
   1092 	 *		of the strings to the beginning. By default, Keys are treated as strings and
   1093 	 *		compared from beginning to end.
   1094 	 *	<li>#MDB_DUPSORT
   1095 	 *		Duplicate keys may be used in the database. (Or, from another perspective,
   1096 	 *		keys may have multiple data items, stored in sorted order.) By default
   1097 	 *		keys must be unique and may have only a single data item.
   1098 	 *	<li>#MDB_INTEGERKEY
   1099 	 *		Keys are binary integers in native byte order, either unsigned int
   1100 	 *		or size_t, and will be sorted as such.
   1101 	 *		The keys must all be of the same size.
   1102 	 *	<li>#MDB_DUPFIXED
   1103 	 *		This flag may only be used in combination with #MDB_DUPSORT. This option
   1104 	 *		tells the library that the data items for this database are all the same
   1105 	 *		size, which allows further optimizations in storage and retrieval. When
   1106 	 *		all data items are the same size, the #MDB_GET_MULTIPLE, #MDB_NEXT_MULTIPLE
   1107 	 *		and #MDB_PREV_MULTIPLE cursor operations may be used to retrieve multiple
   1108 	 *		items at once.
   1109 	 *	<li>#MDB_INTEGERDUP
   1110 	 *		This option specifies that duplicate data items are binary integers,
   1111 	 *		similar to #MDB_INTEGERKEY keys.
   1112 	 *	<li>#MDB_REVERSEDUP
   1113 	 *		This option specifies that duplicate data items should be compared as
   1114 	 *		strings in reverse order.
   1115 	 *	<li>#MDB_CREATE
   1116 	 *		Create the named database if it doesn't exist. This option is not
   1117 	 *		allowed in a read-only transaction or a read-only environment.
   1118 	 * </ul>
   1119 	 * @param[out] dbi Address where the new #MDB_dbi handle will be stored
   1120 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1121 	 * errors are:
   1122 	 * <ul>
   1123 	 *	<li>#MDB_NOTFOUND - the specified database doesn't exist in the environment
   1124 	 *		and #MDB_CREATE was not specified.
   1125 	 *	<li>#MDB_DBS_FULL - too many databases have been opened. See #mdb_env_set_maxdbs().
   1126 	 * </ul>
   1127 	 */
   1128 int  mdb_dbi_open(MDB_txn *txn, const char *name, unsigned int flags, MDB_dbi *dbi);
   1129 
   1130 	/** @brief Retrieve statistics for a database.
   1131 	 *
   1132 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1133 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1134 	 * @param[out] stat The address of an #MDB_stat structure
   1135 	 * 	where the statistics will be copied
   1136 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1137 	 * errors are:
   1138 	 * <ul>
   1139 	 *	<li>EINVAL - an invalid parameter was specified.
   1140 	 * </ul>
   1141 	 */
   1142 int  mdb_stat(MDB_txn *txn, MDB_dbi dbi, MDB_stat *stat);
   1143 
   1144 	/** @brief Retrieve the DB flags for a database handle.
   1145 	 *
   1146 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1147 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1148 	 * @param[out] flags Address where the flags will be returned.
   1149 	 * @return A non-zero error value on failure and 0 on success.
   1150 	 */
   1151 int mdb_dbi_flags(MDB_txn *txn, MDB_dbi dbi, unsigned int *flags);
   1152 
   1153 	/** @brief Close a database handle. Normally unnecessary. Use with care:
   1154 	 *
   1155 	 * This call is not mutex protected. Handles should only be closed by
   1156 	 * a single thread, and only if no other threads are going to reference
   1157 	 * the database handle or one of its cursors any further. Do not close
   1158 	 * a handle if an existing transaction has modified its database.
   1159 	 * Doing so can cause misbehavior from database corruption to errors
   1160 	 * like MDB_BAD_VALSIZE (since the DB name is gone).
   1161 	 *
   1162 	 * Closing a database handle is not necessary, but lets #mdb_dbi_open()
   1163 	 * reuse the handle value.  Usually it's better to set a bigger
   1164 	 * #mdb_env_set_maxdbs(), unless that value would be large.
   1165 	 *
   1166 	 * @param[in] env An environment handle returned by #mdb_env_create()
   1167 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1168 	 */
   1169 void mdb_dbi_close(MDB_env *env, MDB_dbi dbi);
   1170 
   1171 	/** @brief Empty or delete+close a database.
   1172 	 *
   1173 	 * See #mdb_dbi_close() for restrictions about closing the DB handle.
   1174 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1175 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1176 	 * @param[in] del 0 to empty the DB, 1 to delete it from the
   1177 	 * environment and close the DB handle.
   1178 	 * @return A non-zero error value on failure and 0 on success.
   1179 	 */
   1180 int  mdb_drop(MDB_txn *txn, MDB_dbi dbi, int del);
   1181 
   1182 	/** @brief Set a custom key comparison function for a database.
   1183 	 *
   1184 	 * The comparison function is called whenever it is necessary to compare a
   1185 	 * key specified by the application with a key currently stored in the database.
   1186 	 * If no comparison function is specified, and no special key flags were specified
   1187 	 * with #mdb_dbi_open(), the keys are compared lexically, with shorter keys collating
   1188 	 * before longer keys.
   1189 	 * @warning This function must be called before any data access functions are used,
   1190 	 * otherwise data corruption may occur. The same comparison function must be used by every
   1191 	 * program accessing the database, every time the database is used.
   1192 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1193 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1194 	 * @param[in] cmp A #MDB_cmp_func function
   1195 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1196 	 * errors are:
   1197 	 * <ul>
   1198 	 *	<li>EINVAL - an invalid parameter was specified.
   1199 	 * </ul>
   1200 	 */
   1201 int  mdb_set_compare(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp);
   1202 
   1203 	/** @brief Set a custom data comparison function for a #MDB_DUPSORT database.
   1204 	 *
   1205 	 * This comparison function is called whenever it is necessary to compare a data
   1206 	 * item specified by the application with a data item currently stored in the database.
   1207 	 * This function only takes effect if the database was opened with the #MDB_DUPSORT
   1208 	 * flag.
   1209 	 * If no comparison function is specified, and no special key flags were specified
   1210 	 * with #mdb_dbi_open(), the data items are compared lexically, with shorter items collating
   1211 	 * before longer items.
   1212 	 * @warning This function must be called before any data access functions are used,
   1213 	 * otherwise data corruption may occur. The same comparison function must be used by every
   1214 	 * program accessing the database, every time the database is used.
   1215 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1216 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1217 	 * @param[in] cmp A #MDB_cmp_func function
   1218 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1219 	 * errors are:
   1220 	 * <ul>
   1221 	 *	<li>EINVAL - an invalid parameter was specified.
   1222 	 * </ul>
   1223 	 */
   1224 int  mdb_set_dupsort(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp);
   1225 
   1226 	/** @brief Set a relocation function for a #MDB_FIXEDMAP database.
   1227 	 *
   1228 	 * @todo The relocation function is called whenever it is necessary to move the data
   1229 	 * of an item to a different position in the database (e.g. through tree
   1230 	 * balancing operations, shifts as a result of adds or deletes, etc.). It is
   1231 	 * intended to allow address/position-dependent data items to be stored in
   1232 	 * a database in an environment opened with the #MDB_FIXEDMAP option.
   1233 	 * Currently the relocation feature is unimplemented and setting
   1234 	 * this function has no effect.
   1235 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1236 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1237 	 * @param[in] rel A #MDB_rel_func function
   1238 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1239 	 * errors are:
   1240 	 * <ul>
   1241 	 *	<li>EINVAL - an invalid parameter was specified.
   1242 	 * </ul>
   1243 	 */
   1244 int  mdb_set_relfunc(MDB_txn *txn, MDB_dbi dbi, MDB_rel_func *rel);
   1245 
   1246 	/** @brief Set a context pointer for a #MDB_FIXEDMAP database's relocation function.
   1247 	 *
   1248 	 * See #mdb_set_relfunc and #MDB_rel_func for more details.
   1249 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1250 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1251 	 * @param[in] ctx An arbitrary pointer for whatever the application needs.
   1252 	 * It will be passed to the callback function set by #mdb_set_relfunc
   1253 	 * as its \b relctx parameter whenever the callback is invoked.
   1254 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1255 	 * errors are:
   1256 	 * <ul>
   1257 	 *	<li>EINVAL - an invalid parameter was specified.
   1258 	 * </ul>
   1259 	 */
   1260 int  mdb_set_relctx(MDB_txn *txn, MDB_dbi dbi, void *ctx);
   1261 
   1262 	/** @brief Get items from a database.
   1263 	 *
   1264 	 * This function retrieves key/data pairs from the database. The address
   1265 	 * and length of the data associated with the specified \b key are returned
   1266 	 * in the structure to which \b data refers.
   1267 	 * If the database supports duplicate keys (#MDB_DUPSORT) then the
   1268 	 * first data item for the key will be returned. Retrieval of other
   1269 	 * items requires the use of #mdb_cursor_get().
   1270 	 *
   1271 	 * @note The memory pointed to by the returned values is owned by the
   1272 	 * database. The caller need not dispose of the memory, and may not
   1273 	 * modify it in any way. For values returned in a read-only transaction
   1274 	 * any modification attempts will cause a SIGSEGV.
   1275 	 * @note Values returned from the database are valid only until a
   1276 	 * subsequent update operation, or the end of the transaction.
   1277 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1278 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1279 	 * @param[in] key The key to search for in the database
   1280 	 * @param[out] data The data corresponding to the key
   1281 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1282 	 * errors are:
   1283 	 * <ul>
   1284 	 *	<li>#MDB_NOTFOUND - the key was not in the database.
   1285 	 *	<li>EINVAL - an invalid parameter was specified.
   1286 	 * </ul>
   1287 	 */
   1288 int  mdb_get(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data);
   1289 
   1290 	/** @brief Store items into a database.
   1291 	 *
   1292 	 * This function stores key/data pairs in the database. The default behavior
   1293 	 * is to enter the new key/data pair, replacing any previously existing key
   1294 	 * if duplicates are disallowed, or adding a duplicate data item if
   1295 	 * duplicates are allowed (#MDB_DUPSORT).
   1296 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1297 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1298 	 * @param[in] key The key to store in the database
   1299 	 * @param[in,out] data The data to store
   1300 	 * @param[in] flags Special options for this operation. This parameter
   1301 	 * must be set to 0 or by bitwise OR'ing together one or more of the
   1302 	 * values described here.
   1303 	 * <ul>
   1304 	 *	<li>#MDB_NODUPDATA - enter the new key/data pair only if it does not
   1305 	 *		already appear in the database. This flag may only be specified
   1306 	 *		if the database was opened with #MDB_DUPSORT. The function will
   1307 	 *		return #MDB_KEYEXIST if the key/data pair already appears in the
   1308 	 *		database.
   1309 	 *	<li>#MDB_NOOVERWRITE - enter the new key/data pair only if the key
   1310 	 *		does not already appear in the database. The function will return
   1311 	 *		#MDB_KEYEXIST if the key already appears in the database, even if
   1312 	 *		the database supports duplicates (#MDB_DUPSORT). The \b data
   1313 	 *		parameter will be set to point to the existing item.
   1314 	 *	<li>#MDB_RESERVE - reserve space for data of the given size, but
   1315 	 *		don't copy the given data. Instead, return a pointer to the
   1316 	 *		reserved space, which the caller can fill in later - before
   1317 	 *		the next update operation or the transaction ends. This saves
   1318 	 *		an extra memcpy if the data is being generated later.
   1319 	 *		LMDB does nothing else with this memory, the caller is expected
   1320 	 *		to modify all of the space requested. This flag must not be
   1321 	 *		specified if the database was opened with #MDB_DUPSORT.
   1322 	 *	<li>#MDB_APPEND - append the given key/data pair to the end of the
   1323 	 *		database. This option allows fast bulk loading when keys are
   1324 	 *		already known to be in the correct order. Loading unsorted keys
   1325 	 *		with this flag will cause a #MDB_KEYEXIST error.
   1326 	 *	<li>#MDB_APPENDDUP - as above, but for sorted dup data.
   1327 	 * </ul>
   1328 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1329 	 * errors are:
   1330 	 * <ul>
   1331 	 *	<li>#MDB_MAP_FULL - the database is full, see #mdb_env_set_mapsize().
   1332 	 *	<li>#MDB_TXN_FULL - the transaction has too many dirty pages.
   1333 	 *	<li>EACCES - an attempt was made to write in a read-only transaction.
   1334 	 *	<li>EINVAL - an invalid parameter was specified.
   1335 	 * </ul>
   1336 	 */
   1337 int  mdb_put(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data,
   1338 			    unsigned int flags);
   1339 
   1340 	/** @brief Delete items from a database.
   1341 	 *
   1342 	 * This function removes key/data pairs from the database.
   1343 	 * If the database does not support sorted duplicate data items
   1344 	 * (#MDB_DUPSORT) the data parameter is ignored.
   1345 	 * If the database supports sorted duplicates and the data parameter
   1346 	 * is NULL, all of the duplicate data items for the key will be
   1347 	 * deleted. Otherwise, if the data parameter is non-NULL
   1348 	 * only the matching data item will be deleted.
   1349 	 * This function will return #MDB_NOTFOUND if the specified key/data
   1350 	 * pair is not in the database.
   1351 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1352 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1353 	 * @param[in] key The key to delete from the database
   1354 	 * @param[in] data The data to delete
   1355 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1356 	 * errors are:
   1357 	 * <ul>
   1358 	 *	<li>EACCES - an attempt was made to write in a read-only transaction.
   1359 	 *	<li>EINVAL - an invalid parameter was specified.
   1360 	 * </ul>
   1361 	 */
   1362 int  mdb_del(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data);
   1363 
   1364 	/** @brief Create a cursor handle.
   1365 	 *
   1366 	 * A cursor is associated with a specific transaction and database.
   1367 	 * A cursor cannot be used when its database handle is closed.  Nor
   1368 	 * when its transaction has ended, except with #mdb_cursor_renew().
   1369 	 * It can be discarded with #mdb_cursor_close().
   1370 	 * A cursor in a write-transaction can be closed before its transaction
   1371 	 * ends, and will otherwise be closed when its transaction ends.
   1372 	 * A cursor in a read-only transaction must be closed explicitly, before
   1373 	 * or after its transaction ends. It can be reused with
   1374 	 * #mdb_cursor_renew() before finally closing it.
   1375 	 * @note Earlier documentation said that cursors in every transaction
   1376 	 * were closed when the transaction committed or aborted.
   1377 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1378 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1379 	 * @param[out] cursor Address where the new #MDB_cursor handle will be stored
   1380 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1381 	 * errors are:
   1382 	 * <ul>
   1383 	 *	<li>EINVAL - an invalid parameter was specified.
   1384 	 * </ul>
   1385 	 */
   1386 int  mdb_cursor_open(MDB_txn *txn, MDB_dbi dbi, MDB_cursor **cursor);
   1387 
   1388 	/** @brief Close a cursor handle.
   1389 	 *
   1390 	 * The cursor handle will be freed and must not be used again after this call.
   1391 	 * Its transaction must still be live if it is a write-transaction.
   1392 	 * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
   1393 	 */
   1394 void mdb_cursor_close(MDB_cursor *cursor);
   1395 
   1396 	/** @brief Renew a cursor handle.
   1397 	 *
   1398 	 * A cursor is associated with a specific transaction and database.
   1399 	 * Cursors that are only used in read-only
   1400 	 * transactions may be re-used, to avoid unnecessary malloc/free overhead.
   1401 	 * The cursor may be associated with a new read-only transaction, and
   1402 	 * referencing the same database handle as it was created with.
   1403 	 * This may be done whether the previous transaction is live or dead.
   1404 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1405 	 * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
   1406 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1407 	 * errors are:
   1408 	 * <ul>
   1409 	 *	<li>EINVAL - an invalid parameter was specified.
   1410 	 * </ul>
   1411 	 */
   1412 int  mdb_cursor_renew(MDB_txn *txn, MDB_cursor *cursor);
   1413 
   1414 	/** @brief Return the cursor's transaction handle.
   1415 	 *
   1416 	 * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
   1417 	 */
   1418 MDB_txn *mdb_cursor_txn(MDB_cursor *cursor);
   1419 
   1420 	/** @brief Return the cursor's database handle.
   1421 	 *
   1422 	 * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
   1423 	 */
   1424 MDB_dbi mdb_cursor_dbi(MDB_cursor *cursor);
   1425 
   1426 	/** @brief Retrieve by cursor.
   1427 	 *
   1428 	 * This function retrieves key/data pairs from the database. The address and length
   1429 	 * of the key are returned in the object to which \b key refers (except for the
   1430 	 * case of the #MDB_SET option, in which the \b key object is unchanged), and
   1431 	 * the address and length of the data are returned in the object to which \b data
   1432 	 * refers.
   1433 	 * See #mdb_get() for restrictions on using the output values.
   1434 	 * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
   1435 	 * @param[in,out] key The key for a retrieved item
   1436 	 * @param[in,out] data The data of a retrieved item
   1437 	 * @param[in] op A cursor operation #MDB_cursor_op
   1438 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1439 	 * errors are:
   1440 	 * <ul>
   1441 	 *	<li>#MDB_NOTFOUND - no matching key found.
   1442 	 *	<li>EINVAL - an invalid parameter was specified.
   1443 	 * </ul>
   1444 	 */
   1445 int  mdb_cursor_get(MDB_cursor *cursor, MDB_val *key, MDB_val *data,
   1446 			    MDB_cursor_op op);
   1447 
   1448 	/** @brief Store by cursor.
   1449 	 *
   1450 	 * This function stores key/data pairs into the database.
   1451 	 * The cursor is positioned at the new item, or on failure usually near it.
   1452 	 * @note Earlier documentation incorrectly said errors would leave the
   1453 	 * state of the cursor unchanged.
   1454 	 * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
   1455 	 * @param[in] key The key operated on.
   1456 	 * @param[in] data The data operated on.
   1457 	 * @param[in] flags Options for this operation. This parameter
   1458 	 * must be set to 0 or one of the values described here.
   1459 	 * <ul>
   1460 	 *	<li>#MDB_CURRENT - replace the item at the current cursor position.
   1461 	 *		The \b key parameter must still be provided, and must match it.
   1462 	 *		If using sorted duplicates (#MDB_DUPSORT) the data item must still
   1463 	 *		sort into the same place. This is intended to be used when the
   1464 	 *		new data is the same size as the old. Otherwise it will simply
   1465 	 *		perform a delete of the old record followed by an insert.
   1466 	 *	<li>#MDB_NODUPDATA - enter the new key/data pair only if it does not
   1467 	 *		already appear in the database. This flag may only be specified
   1468 	 *		if the database was opened with #MDB_DUPSORT. The function will
   1469 	 *		return #MDB_KEYEXIST if the key/data pair already appears in the
   1470 	 *		database.
   1471 	 *	<li>#MDB_NOOVERWRITE - enter the new key/data pair only if the key
   1472 	 *		does not already appear in the database. The function will return
   1473 	 *		#MDB_KEYEXIST if the key already appears in the database, even if
   1474 	 *		the database supports duplicates (#MDB_DUPSORT).
   1475 	 *	<li>#MDB_RESERVE - reserve space for data of the given size, but
   1476 	 *		don't copy the given data. Instead, return a pointer to the
   1477 	 *		reserved space, which the caller can fill in later - before
   1478 	 *		the next update operation or the transaction ends. This saves
   1479 	 *		an extra memcpy if the data is being generated later. This flag
   1480 	 *		must not be specified if the database was opened with #MDB_DUPSORT.
   1481 	 *	<li>#MDB_APPEND - append the given key/data pair to the end of the
   1482 	 *		database. No key comparisons are performed. This option allows
   1483 	 *		fast bulk loading when keys are already known to be in the
   1484 	 *		correct order. Loading unsorted keys with this flag will cause
   1485 	 *		a #MDB_KEYEXIST error.
   1486 	 *	<li>#MDB_APPENDDUP - as above, but for sorted dup data.
   1487 	 *	<li>#MDB_MULTIPLE - store multiple contiguous data elements in a
   1488 	 *		single request. This flag may only be specified if the database
   1489 	 *		was opened with #MDB_DUPFIXED. The \b data argument must be an
   1490 	 *		array of two MDB_vals. The mv_size of the first MDB_val must be
   1491 	 *		the size of a single data element. The mv_data of the first MDB_val
   1492 	 *		must point to the beginning of the array of contiguous data elements.
   1493 	 *		The mv_size of the second MDB_val must be the count of the number
   1494 	 *		of data elements to store. On return this field will be set to
   1495 	 *		the count of the number of elements actually written. The mv_data
   1496 	 *		of the second MDB_val is unused.
   1497 	 * </ul>
   1498 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1499 	 * errors are:
   1500 	 * <ul>
   1501 	 *	<li>#MDB_MAP_FULL - the database is full, see #mdb_env_set_mapsize().
   1502 	 *	<li>#MDB_TXN_FULL - the transaction has too many dirty pages.
   1503 	 *	<li>EACCES - an attempt was made to write in a read-only transaction.
   1504 	 *	<li>EINVAL - an invalid parameter was specified.
   1505 	 * </ul>
   1506 	 */
   1507 int  mdb_cursor_put(MDB_cursor *cursor, MDB_val *key, MDB_val *data,
   1508 				unsigned int flags);
   1509 
   1510 	/** @brief Delete current key/data pair
   1511 	 *
   1512 	 * This function deletes the key/data pair to which the cursor refers.
   1513 	 * This does not invalidate the cursor, so operations such as MDB_NEXT
   1514 	 * can still be used on it.
   1515 	 * Both MDB_NEXT and MDB_GET_CURRENT will return the same record after
   1516 	 * this operation.
   1517 	 * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
   1518 	 * @param[in] flags Options for this operation. This parameter
   1519 	 * must be set to 0 or one of the values described here.
   1520 	 * <ul>
   1521 	 *	<li>#MDB_NODUPDATA - delete all of the data items for the current key.
   1522 	 *		This flag may only be specified if the database was opened with #MDB_DUPSORT.
   1523 	 * </ul>
   1524 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1525 	 * errors are:
   1526 	 * <ul>
   1527 	 *	<li>EACCES - an attempt was made to write in a read-only transaction.
   1528 	 *	<li>EINVAL - an invalid parameter was specified.
   1529 	 * </ul>
   1530 	 */
   1531 int  mdb_cursor_del(MDB_cursor *cursor, unsigned int flags);
   1532 
   1533 	/** @brief Return count of duplicates for current key.
   1534 	 *
   1535 	 * This call is only valid on databases that support sorted duplicate
   1536 	 * data items #MDB_DUPSORT.
   1537 	 * @param[in] cursor A cursor handle returned by #mdb_cursor_open()
   1538 	 * @param[out] countp Address where the count will be stored
   1539 	 * @return A non-zero error value on failure and 0 on success. Some possible
   1540 	 * errors are:
   1541 	 * <ul>
   1542 	 *	<li>EINVAL - cursor is not initialized, or an invalid parameter was specified.
   1543 	 * </ul>
   1544 	 */
   1545 int  mdb_cursor_count(MDB_cursor *cursor, size_t *countp);
   1546 
   1547 	/** @brief Compare two data items according to a particular database.
   1548 	 *
   1549 	 * This returns a comparison as if the two data items were keys in the
   1550 	 * specified database.
   1551 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1552 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1553 	 * @param[in] a The first item to compare
   1554 	 * @param[in] b The second item to compare
   1555 	 * @return < 0 if a < b, 0 if a == b, > 0 if a > b
   1556 	 */
   1557 int  mdb_cmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b);
   1558 
   1559 	/** @brief Compare two data items according to a particular database.
   1560 	 *
   1561 	 * This returns a comparison as if the two items were data items of
   1562 	 * the specified database. The database must have the #MDB_DUPSORT flag.
   1563 	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
   1564 	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
   1565 	 * @param[in] a The first item to compare
   1566 	 * @param[in] b The second item to compare
   1567 	 * @return < 0 if a < b, 0 if a == b, > 0 if a > b
   1568 	 */
   1569 int  mdb_dcmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b);
   1570 
   1571 	/** @brief A callback function used to print a message from the library.
   1572 	 *
   1573 	 * @param[in] msg The string to be printed.
   1574 	 * @param[in] ctx An arbitrary context pointer for the callback.
   1575 	 * @return < 0 on failure, >= 0 on success.
   1576 	 */
   1577 typedef int (MDB_msg_func)(const char *msg, void *ctx);
   1578 
   1579 	/** @brief Dump the entries in the reader lock table.
   1580 	 *
   1581 	 * @param[in] env An environment handle returned by #mdb_env_create()
   1582 	 * @param[in] func A #MDB_msg_func function
   1583 	 * @param[in] ctx Anything the message function needs
   1584 	 * @return < 0 on failure, >= 0 on success.
   1585 	 */
   1586 int	mdb_reader_list(MDB_env *env, MDB_msg_func *func, void *ctx);
   1587 
   1588 	/** @brief Check for stale entries in the reader lock table.
   1589 	 *
   1590 	 * @param[in] env An environment handle returned by #mdb_env_create()
   1591 	 * @param[out] dead Number of stale slots that were cleared
   1592 	 * @return 0 on success, non-zero on failure.
   1593 	 */
   1594 int	mdb_reader_check(MDB_env *env, int *dead);
   1595 /**	@} */
   1596 
   1597 #ifdef __cplusplus
   1598 }
   1599 #endif
   1600 /** @page tools LMDB Command Line Tools
   1601 	The following describes the command line tools that are available for LMDB.
   1602 	\li \ref mdb_copy_1
   1603 	\li \ref mdb_dump_1
   1604 	\li \ref mdb_load_1
   1605 	\li \ref mdb_stat_1
   1606 */
   1607 
   1608 #endif /* _LMDB_H_ */