lmdb.h 69.6 KB
Newer Older
Howard Chu's avatar
Howard Chu committed
1
2
/** @file lmdb.h
 *	@brief Lightning memory-mapped database library
3
 *
Howard Chu's avatar
Howard Chu committed
4
 *	@mainpage	Lightning Memory-Mapped Database Manager (LMDB)
Howard Chu's avatar
Howard Chu committed
5
6
 *
 *	@section intro_sec Introduction
Howard Chu's avatar
Howard Chu committed
7
 *	LMDB is a Btree-based database management library modeled loosely on the
8
 *	BerkeleyDB API, but much simplified. The entire database is exposed
Howard Chu's avatar
Howard Chu committed
9
 *	in a memory map, and all data fetches return data directly
10
11
12
13
 *	from the mapped memory, so no malloc's or memcpy's occur during
 *	data fetches. As such, the library is extremely simple because it
 *	requires no page caching layer of its own, and it is extremely high
 *	performance and memory-efficient. It is also fully transactional with
Howard Chu's avatar
Howard Chu committed
14
 *	full ACID semantics, and when the memory map is read-only, the
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 *	database integrity cannot be corrupted by stray pointer writes from
 *	application code.
 *
 *	The library is fully thread-aware and supports concurrent read/write
 *	access from multiple processes and threads. Data pages use a copy-on-
 *	write strategy so no active data pages are ever overwritten, which
 *	also provides resistance to corruption and eliminates the need of any
 *	special recovery procedures after a system crash. Writes are fully
 *	serialized; only one write transaction may be active at a time, which
 *	guarantees that writers can never deadlock. The database structure is
 *	multi-versioned so readers run with no locks; writers cannot block
 *	readers, and readers don't block writers.
 *
 *	Unlike other well-known database mechanisms which use either write-ahead
Howard Chu's avatar
Howard Chu committed
29
 *	transaction logs or append-only data writes, LMDB requires no maintenance
30
31
 *	during operation. Both write-ahead loggers and append-only databases
 *	require periodic checkpointing and/or compaction of their log or database
Howard Chu's avatar
Howard Chu committed
32
 *	files otherwise they grow without bound. LMDB tracks free pages within
33
34
35
 *	the database and re-uses them for new write operations, so the database
 *	size does not grow without bound in normal use.
 *
Howard Chu's avatar
Howard Chu committed
36
37
38
39
40
41
42
 *	The memory map can be used as a read-only or read-write map. It is
 *	read-only by default as this provides total immunity to corruption.
 *	Using read-write mode offers much higher write performance, but adds
 *	the possibility for stray application writes thru pointers to silently
 *	corrupt the database. Of course if your application code is known to
 *	be bug-free (...) then this is not an issue.
 *
Howard Chu's avatar
Howard Chu committed
43
 *	@section caveats_sec Caveats
44
45
46
47
48
49
50
 *	Troubleshooting the lock file, plus semaphores on BSD systems:
 *
 *	- A broken lockfile can cause sync issues.
 *	  Stale reader transactions left behind by an aborted program
 *	  cause further writes to grow the database quickly, and
 *	  stale locks can block further operation.
 *
51
 *	  Fix: Check for stale readers periodically, using the
Howard Chu's avatar
Howard Chu committed
52
 *	  #mdb_reader_check function or the \ref mdb_stat_1 "mdb_stat" tool. Or just
53
54
 *	  make all programs using the database close it; the lockfile
 *	  is always reset on first open of the environment.
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 *
 *	- On BSD systems or others configured with MDB_USE_POSIX_SEM,
 *	  startup can fail due to semaphores owned by another userid.
 *
 *	  Fix: Open and close the database as the user which owns the
 *	  semaphores (likely last user) or as root, while no other
 *	  process is using the database.
 *
 *	Restrictions/caveats (in addition to those listed for some functions):
 *
 *	- Only the database owner should normally use the database on
 *	  BSD systems or when otherwise configured with MDB_USE_POSIX_SEM.
 *	  Multiple users can cause startup to fail later, as noted above.
 *
69
70
71
72
 *	- There is normally no pure read-only mode, since readers need write
 *	  access to locks and lock file. Exceptions: On read-only filesystems
 *	  or with the #MDB_NOLOCK flag described under #mdb_env_open().
 *
Howard Chu's avatar
Howard Chu committed
73
74
 *	- By default, in versions before 0.9.10, unused portions of the data
 *	  file might receive garbage data from memory freed by other code.
Howard Chu's avatar
Howard Chu committed
75
 *	  (This does not happen when using the #MDB_WRITEMAP flag.) As of
Howard Chu's avatar
Howard Chu committed
76
77
78
79
 *	  0.9.10 the default behavior is to initialize such memory before
 *	  writing to the data file. Since there may be a slight performance
 *	  cost due to this initialization, applications may disable it using
 *	  the #MDB_NOMEMINIT flag. Applications handling sensitive data
Howard Chu's avatar
Howard Chu committed
80
81
 *	  which must not be written should not use this flag. This flag is
 *	  irrelevant when using #MDB_WRITEMAP.
Hallvard Furuseth's avatar
Hallvard Furuseth committed
82
 *
83
84
 *	- A thread can only use one transaction at a time, plus any child
 *	  transactions.  Each transaction belongs to one thread.  See below.
Howard Chu's avatar
Howard Chu committed
85
 *	  The #MDB_NOTLS flag changes this for read-only transactions.
86
87
88
 *
 *	- Use an MDB_env* in the process which opened it, without fork()ing.
 *
Howard Chu's avatar
Howard Chu committed
89
 *	- Do not have open an LMDB database twice in the same process at
90
91
92
93
94
95
96
97
98
 *	  the same time.  Not even from a plain open() call - close()ing it
 *	  breaks flock() advisory locking.
 *
 *	- Avoid long-lived transactions.  Read transactions prevent
 *	  reuse of pages freed by newer write transactions, thus the
 *	  database can grow quickly.  Write transactions prevent
 *	  other write transactions, since writes are serialized.
 *
 *	- Avoid suspending a process with active transactions.  These
99
100
101
102
 *	  would then be "long-lived" as above.  Also read transactions
 *	  suspended when writers commit could sometimes see wrong data.
 *
 *	...when several processes can use a database concurrently:
103
104
 *
 *	- Avoid aborting a process with an active transaction.
105
106
107
 *	  The transaction becomes "long-lived" as above until a check
 *	  for stale readers is performed or the lockfile is reset,
 *	  since the process may not remove it from the lockfile.
108
 *
109
110
 *	- If you do that anyway, do a periodic check for stale readers. Or
 *	  close the environment once in a while, so the lockfile can get reset.
111
 *
Howard Chu's avatar
Howard Chu committed
112
 *	- Do not use LMDB databases on remote filesystems, even between
Hallvard Furuseth's avatar
Hallvard Furuseth committed
113
114
115
 *	  processes on the same host.  This breaks flock() on some OSes,
 *	  possibly memory map sync, and certainly sync between programs
 *	  on different hosts.
116
117
118
119
 *
 *	- Opening a database can fail if another process is opening or
 *	  closing it at exactly the same time.
 *
120
121
 *	@author	Howard Chu, Symas Corporation.
 *
Howard Chu's avatar
Howard Chu committed
122
 *	@copyright Copyright 2011-2014 Howard Chu, Symas Corp. All rights reserved.
Howard Chu's avatar
Howard Chu committed
123
124
125
126
127
128
129
130
131
 *
 * 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>.
 *
Howard Chu's avatar
Howard Chu committed
132
 *	@par Derived From:
Howard Chu's avatar
Howard Chu committed
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 * This code is derived from btree.c written by Martin Hedenfalk.
 *
 * Copyright (c) 2009, 2010 Martin Hedenfalk <martin@bzero.se>
 *
 * Permission to use, copy, modify, and distribute this software for any
 * purpose with or without fee is hereby granted, provided that the above
 * copyright notice and this permission notice appear in all copies.
 *
 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 */
Howard Chu's avatar
Howard Chu committed
149
150
#ifndef _LMDB_H_
#define _LMDB_H_
Howard Chu's avatar
Howard Chu committed
151
152
153

#include <sys/types.h>

154
155
156
157
#ifdef __cplusplus
extern "C" {
#endif

158
/** Unix permissions for creating files, or dummy definition for Windows */
Howard Chu's avatar
Howard Chu committed
159
#ifdef _MSC_VER
160
161
162
typedef	int	mdb_mode_t;
#else
typedef	mode_t	mdb_mode_t;
Howard Chu's avatar
Howard Chu committed
163
164
#endif

165
166
167
168
169
170
171
172
/** An abstraction for a file handle.
 *	On POSIX systems file handles are small integers. On Windows
 *	they're opaque pointers.
 */
#ifdef _WIN32
typedef	void *mdb_filehandle_t;
#else
typedef int mdb_filehandle_t;
Howard Chu's avatar
Howard Chu committed
173
174
#endif

Howard Chu's avatar
Howard Chu committed
175
/** @defgroup mdb LMDB API
176
 *	@{
Howard Chu's avatar
Howard Chu committed
177
 *	@brief OpenLDAP Lightning Memory-Mapped Database Manager
178
 */
179
180
181
182
/** @defgroup Version Version Macros
 *	@{
 */
/** Library major version */
183
#define MDB_VERSION_MAJOR	0
184
/** Library minor version */
Howard Chu's avatar
Howard Chu committed
185
#define MDB_VERSION_MINOR	9
186
/** Library patch version */
Howard Chu's avatar
Howard Chu committed
187
#define MDB_VERSION_PATCH	14
188
189

/** Combine args a,b,c into a single integer for easy version comparisons */
190
#define MDB_VERINT(a,b,c)	(((a) << 24) | ((b) << 16) | (c))
191
192

/** The full library version as a single integer */
Howard Chu's avatar
Howard Chu committed
193
194
#define MDB_VERSION_FULL	\
	MDB_VERINT(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH)
195
196

/** The release date of this library version */
Howard Chu's avatar
Howard Chu committed
197
#define MDB_VERSION_DATE	"September 20, 2014"
198
199

/** A stringifier for the version info */
Howard Chu's avatar
Howard Chu committed
200
#define MDB_VERSTR(a,b,c,d)	"LMDB " #a "." #b "." #c ": (" d ")"
201
202

/** A helper for the stringifier macro */
Howard Chu's avatar
Howard Chu committed
203
#define MDB_VERFOO(a,b,c,d)	MDB_VERSTR(a,b,c,d)
204
205

/** The full library version as a C string */
Howard Chu's avatar
Howard Chu committed
206
207
#define	MDB_VERSION_STRING	\
	MDB_VERFOO(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH,MDB_VERSION_DATE)
208
/**	@} */
209

210
211
212
213
/** @brief Opaque structure for a database environment.
 *
 * A DB environment supports multiple databases, all residing in the same
 * shared-memory map.
Howard Chu's avatar
Howard Chu committed
214
215
 */
typedef struct MDB_env MDB_env;
216

217
218
219
220
/** @brief Opaque structure for a transaction handle.
 *
 * All database operations require a transaction handle. Transactions may be
 * read-only or read-write.
221
 */
Howard Chu's avatar
Howard Chu committed
222
typedef struct MDB_txn MDB_txn;
223

224
/** @brief A handle for an individual database in the DB environment. */
Howard Chu's avatar
Howard Chu committed
225
226
typedef unsigned int	MDB_dbi;

227
/** @brief Opaque structure for navigating through a database */
Howard Chu's avatar
Howard Chu committed
228
229
typedef struct MDB_cursor MDB_cursor;

230
231
232
/** @brief Generic structure used for passing keys and data in and out
 * of the database.
 *
233
 * Values returned from the database are valid only until a subsequent
234
235
236
237
238
239
 * update operation, or the end of the transaction. Do not modify or
 * free them, they commonly point into the database itself.
 *
 * Key sizes must be between 1 and #mdb_env_get_maxkeysize() inclusive.
 * The same applies to data sizes in databases with the #MDB_DUPSORT flag.
 * Other data items can in theory be from 0 to 0xffffffff bytes long.
240
 */
Howard Chu's avatar
Howard Chu committed
241
typedef struct MDB_val {
242
243
	size_t		 mv_size;	/**< size of the data item */
	void		*mv_data;	/**< address of the data item */
Howard Chu's avatar
Howard Chu committed
244
245
} MDB_val;

246
/** @brief A callback function used to compare two keys in a database */
Howard Chu's avatar
Howard Chu committed
247
typedef int  (MDB_cmp_func)(const MDB_val *a, const MDB_val *b);
248

249
250
251
252
/** @brief A callback function used to relocate a position-dependent data item
 * in a fixed-address database.
 *
 * The \b newptr gives the item's desired address in
253
254
255
 * the memory map, and \b oldptr gives its previous address. The item's actual
 * data resides at the address in \b item.  This callback is expected to walk
 * through the fields of the record in \b item and modify any
Howard Chu's avatar
Howard Chu committed
256
 * values based at the \b oldptr address to be relative to the \b newptr address.
257
258
259
260
 * @param[in,out] item The item that is to be relocated.
 * @param[in] oldptr The previous address.
 * @param[in] newptr The new address to relocate to.
 * @param[in] relctx An application-provided context, set by #mdb_set_relctx().
Howard Chu's avatar
Howard Chu committed
261
 * @todo This feature is currently unimplemented.
262
 */
263
typedef void (MDB_rel_func)(MDB_val *item, void *oldptr, void *newptr, void *relctx);
Howard Chu's avatar
Howard Chu committed
264

265
/** @defgroup	mdb_env	Environment Flags
Howard Chu's avatar
Howard Chu committed
266
267
 *	@{
 */
268
	/** mmap at a fixed address (experimental) */
Howard Chu's avatar
Howard Chu committed
269
#define MDB_FIXEDMAP	0x01
Howard Chu's avatar
Howard Chu committed
270
	/** no environment directory */
271
#define MDB_NOSUBDIR	0x4000
Howard Chu's avatar
Howard Chu committed
272
273
274
275
	/** don't fsync after commit */
#define MDB_NOSYNC		0x10000
	/** read only */
#define MDB_RDONLY		0x20000
Howard Chu's avatar
Howard Chu committed
276
277
	/** don't fsync metapage after commit */
#define MDB_NOMETASYNC		0x40000
278
279
	/** use writable mmap */
#define MDB_WRITEMAP		0x80000
Howard Chu's avatar
Howard Chu committed
280
	/** use asynchronous msync when #MDB_WRITEMAP is used */
281
#define MDB_MAPASYNC		0x100000
Howard Chu's avatar
Howard Chu committed
282
283
	/** tie reader locktable slots to #MDB_txn objects instead of to threads */
#define MDB_NOTLS		0x200000
Howard Chu's avatar
Howard Chu committed
284
285
	/** don't do any locking, caller must manage their own locks */
#define MDB_NOLOCK		0x400000
286
287
	/** don't do readahead (no effect on Windows) */
#define MDB_NORDAHEAD	0x800000
Howard Chu's avatar
Howard Chu committed
288
289
	/** don't initialize malloc'd memory before writing to datafile */
#define MDB_NOMEMINIT	0x1000000
Howard Chu's avatar
Howard Chu committed
290
291
/** @} */

292
/**	@defgroup	mdb_dbi_open	Database Flags
Howard Chu's avatar
Howard Chu committed
293
294
295
296
297
298
 *	@{
 */
	/** use reverse string keys */
#define MDB_REVERSEKEY	0x02
	/** use sorted duplicates */
#define MDB_DUPSORT		0x04
Howard Chu's avatar
Howard Chu committed
299
	/** numeric keys in native byte order.
300
	 *  The keys must all be of the same size. */
Howard Chu's avatar
Howard Chu committed
301
302
303
304
305
#define MDB_INTEGERKEY	0x08
	/** with #MDB_DUPSORT, sorted dup items have fixed size */
#define MDB_DUPFIXED	0x10
	/** with #MDB_DUPSORT, dups are numeric in native byte order */
#define MDB_INTEGERDUP	0x20
Howard Chu's avatar
Howard Chu committed
306
307
	/** with #MDB_DUPSORT, use reverse string dups */
#define MDB_REVERSEDUP	0x40
Howard Chu's avatar
Howard Chu committed
308
309
310
	/** create DB if not already existing */
#define MDB_CREATE		0x40000
/** @} */
Howard Chu's avatar
Howard Chu committed
311

312
/**	@defgroup mdb_put	Write Flags
313
314
 *	@{
 */
315
/** For put: Don't write if the key already exists. */
Howard Chu's avatar
Howard Chu committed
316
#define MDB_NOOVERWRITE	0x10
317
318
319
/** Only for #MDB_DUPSORT<br>
 * For put: don't write if the key and data pair already exist.<br>
 * For mdb_cursor_del: remove all duplicate data items.
320
 */
Howard Chu's avatar
Howard Chu committed
321
#define MDB_NODUPDATA	0x20
322
323
/** For mdb_cursor_put: overwrite the current key/data pair */
#define MDB_CURRENT	0x40
Howard Chu's avatar
Howard Chu committed
324
325
326
327
/** For put: Just reserve space for data, don't copy it. Return a
 * pointer to the reserved space.
 */
#define MDB_RESERVE	0x10000
328
329
/** Data is being appended, don't split full pages. */
#define MDB_APPEND	0x20000
Howard Chu's avatar
Howard Chu committed
330
331
/** Duplicate data is being appended, don't split full pages. */
#define MDB_APPENDDUP	0x40000
Howard Chu's avatar
Howard Chu committed
332
/** Store multiple data items in one call. Only for #MDB_DUPFIXED. */
Howard Chu's avatar
Howard Chu committed
333
#define MDB_MULTIPLE	0x80000
334
335
/*	@} */

Howard Chu's avatar
Howard Chu committed
336
337
338
339
340
341
342
343
344
/**	@defgroup mdb_copy	Copy Flags
 *	@{
 */
/** Compacting copy: Omit free space from copy, and renumber all
 * pages sequentially.
 */
#define MDB_CP_COMPACT	0x01
/*	@} */

345
346
/** @brief Cursor Get operations.
 *
347
348
349
 *	This is the set of all operations for retrieving data
 *	using a cursor.
 */
350
351
typedef enum MDB_cursor_op {
	MDB_FIRST,				/**< Position at first key/data item */
352
353
	MDB_FIRST_DUP,			/**< Position at first data item of current key.
								Only for #MDB_DUPSORT */
354
355
	MDB_GET_BOTH,			/**< Position at key/data pair. Only for #MDB_DUPSORT */
	MDB_GET_BOTH_RANGE,		/**< position at key, nearest data. Only for #MDB_DUPSORT */
Howard Chu's avatar
Howard Chu committed
356
	MDB_GET_CURRENT,		/**< Return key/data at current cursor position */
357
358
359
	MDB_GET_MULTIPLE,		/**< Return key and up to a page of duplicate data items
								from current cursor position. Move cursor to prepare
								for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */
360
	MDB_LAST,				/**< Position at last key/data item */
361
362
	MDB_LAST_DUP,			/**< Position at last data item of current key.
								Only for #MDB_DUPSORT */
363
364
365
	MDB_NEXT,				/**< Position at next data item */
	MDB_NEXT_DUP,			/**< Position at next data item of current key.
								Only for #MDB_DUPSORT */
366
367
368
	MDB_NEXT_MULTIPLE,		/**< Return key and up to a page of duplicate data items
								from next cursor position. Move cursor to prepare
								for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */
369
	MDB_NEXT_NODUP,			/**< Position at first data item of next key */
370
371
372
	MDB_PREV,				/**< Position at previous data item */
	MDB_PREV_DUP,			/**< Position at previous data item of current key.
								Only for #MDB_DUPSORT */
373
	MDB_PREV_NODUP,			/**< Position at last data item of previous key */
374
	MDB_SET,				/**< Position at specified key */
Howard Chu's avatar
Howard Chu committed
375
	MDB_SET_KEY,			/**< Position at specified key, return key + data */
376
	MDB_SET_RANGE			/**< Position at first key greater than or equal to specified key. */
Howard Chu's avatar
Howard Chu committed
377
378
} MDB_cursor_op;

379
380
381
382
383
384
/** @defgroup  errors	Return Codes
 *
 *	BerkeleyDB uses -30800 to -30999, we'll go under them
 *	@{
 */
	/**	Successful result */
Howard Chu's avatar
Howard Chu committed
385
#define MDB_SUCCESS	 0
386
387
388
389
390
391
392
393
	/** key/data pair already exists */
#define MDB_KEYEXIST	(-30799)
	/** key/data pair not found (EOF) */
#define MDB_NOTFOUND	(-30798)
	/** Requested page not found - this usually indicates corruption */
#define MDB_PAGE_NOTFOUND	(-30797)
	/** Located page was wrong type */
#define MDB_CORRUPTED	(-30796)
394
	/** Update of meta page failed, probably I/O error */
395
396
397
#define MDB_PANIC		(-30795)
	/** Environment version mismatch */
#define MDB_VERSION_MISMATCH	(-30794)
Howard Chu's avatar
Howard Chu committed
398
	/** File is not a valid LMDB file */
399
400
401
402
403
404
405
406
407
#define MDB_INVALID	(-30793)
	/** Environment mapsize reached */
#define MDB_MAP_FULL	(-30792)
	/** Environment maxdbs reached */
#define MDB_DBS_FULL	(-30791)
	/** Environment maxreaders reached */
#define MDB_READERS_FULL	(-30790)
	/** Too many TLS keys in use - Windows only */
#define MDB_TLS_FULL	(-30789)
408
	/** Txn has too many dirty pages */
409
410
411
412
413
#define MDB_TXN_FULL	(-30788)
	/** Cursor stack too deep - internal error */
#define MDB_CURSOR_FULL	(-30787)
	/** Page has not enough space - internal error */
#define MDB_PAGE_FULL	(-30786)
414
	/** Database contents grew beyond environment mapsize */
415
#define MDB_MAP_RESIZED	(-30785)
416
	/** MDB_INCOMPATIBLE: Operation and DB incompatible, or DB flags changed */
417
#define MDB_INCOMPATIBLE	(-30784)
418
419
	/** Invalid reuse of reader locktable slot */
#define MDB_BAD_RSLOT		(-30783)
420
421
	/** Transaction cannot recover - it must be aborted */
#define MDB_BAD_TXN			(-30782)
422
	/** Unsupported size of key/DB name/data, or wrong DUPFIXED size */
423
#define MDB_BAD_VALSIZE		(-30781)
424
425
426
427
	/** The specified DBI was changed unexpectedly */
#define MDB_BAD_DBI		(-30780)
	/** The last defined error code */
#define MDB_LAST_ERRCODE	MDB_BAD_DBI
428
429
/** @} */

430
/** @brief Statistics for a database in the environment */
Howard Chu's avatar
Howard Chu committed
431
typedef struct MDB_stat {
432
433
434
	unsigned int	ms_psize;			/**< Size of a database page.
											This is currently the same for all databases. */
	unsigned int	ms_depth;			/**< Depth (height) of the B-tree */
435
436
437
438
	size_t		ms_branch_pages;	/**< Number of internal (non-leaf) pages */
	size_t		ms_leaf_pages;		/**< Number of leaf pages */
	size_t		ms_overflow_pages;	/**< Number of overflow pages */
	size_t		ms_entries;			/**< Number of data items */
Howard Chu's avatar
Howard Chu committed
439
440
} MDB_stat;

441
442
/** @brief Information about the environment */
typedef struct MDB_envinfo {
Howard Chu's avatar
Howard Chu committed
443
	void	*me_mapaddr;			/**< Address of map, if fixed */
444
445
	size_t	me_mapsize;				/**< Size of the data memory map */
	size_t	me_last_pgno;			/**< ID of the last used page */
Howard Chu's avatar
Howard Chu committed
446
	size_t	me_last_txnid;			/**< ID of the last committed transaction */
Howard Chu's avatar
Howard Chu committed
447
448
	unsigned int me_maxreaders;		/**< max reader slots in the environment */
	unsigned int me_numreaders;		/**< max reader slots used in the environment */
449
450
} MDB_envinfo;

Howard Chu's avatar
Howard Chu committed
451
	/** @brief Return the LMDB library version information.
452
	 *
453
454
455
456
457
	 * @param[out] major if non-NULL, the library major version number is copied here
	 * @param[out] minor if non-NULL, the library minor version number is copied here
	 * @param[out] patch if non-NULL, the library patch version number is copied here
	 * @retval "version string" The library version as a string
	 */
Howard Chu's avatar
Howard Chu committed
458
char *mdb_version(int *major, int *minor, int *patch);
459

460
461
	/** @brief Return a string describing a given error code.
	 *
462
463
464
	 * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3)
	 * function. If the error code is greater than or equal to 0, then the string
	 * returned by the system function strerror(3) is returned. If the error code
Howard Chu's avatar
Howard Chu committed
465
466
	 * is less than 0, an error string corresponding to the LMDB library error is
	 * returned. See @ref errors for a list of LMDB-specific error codes.
467
468
469
	 * @param[in] err The error code
	 * @retval "error message" The description of the error
	 */
470
char *mdb_strerror(int err);
471

Howard Chu's avatar
Howard Chu committed
472
	/** @brief Create an LMDB environment handle.
473
	 *
474
475
476
477
478
479
480
481
482
	 * This function allocates memory for a #MDB_env structure. To release
	 * the allocated memory and discard the handle, call #mdb_env_close().
	 * Before the handle may be used, it must be opened using #mdb_env_open().
	 * Various other options may also need to be set before opening the handle,
	 * e.g. #mdb_env_set_mapsize(), #mdb_env_set_maxreaders(), #mdb_env_set_maxdbs(),
	 * depending on usage requirements.
	 * @param[out] env The address where the new handle will be stored
	 * @return A non-zero error value on failure and 0 on success.
	 */
Howard Chu's avatar
Howard Chu committed
483
int  mdb_env_create(MDB_env **env);
484

485
486
	/** @brief Open an environment handle.
	 *
487
488
	 * If this function fails, #mdb_env_close() must be called to discard the #MDB_env handle.
	 * @param[in] env An environment handle returned by #mdb_env_create()
Howard Chu's avatar
Howard Chu committed
489
490
	 * @param[in] path The directory in which the database files reside. This
	 * directory must already exist and be writable.
491
492
493
	 * @param[in] flags Special options for this environment. This parameter
	 * must be set to 0 or by bitwise OR'ing together one or more of the
	 * values described here.
494
	 * Flags set by mdb_env_set_flags() are also used.
495
496
497
498
499
500
501
502
503
	 * <ul>
	 *	<li>#MDB_FIXEDMAP
	 *      use a fixed address for the mmap region. This flag must be specified
	 *      when creating the environment, and is stored persistently in the environment.
	 *		If successful, the memory map will always reside at the same virtual address
	 *		and pointers used to reference data items in the database will be constant
	 *		across multiple invocations. This option may not always work, depending on
	 *		how the operating system has allocated memory to shared libraries and other uses.
	 *		The feature is highly experimental.
504
	 *	<li>#MDB_NOSUBDIR
Howard Chu's avatar
Howard Chu committed
505
	 *		By default, LMDB creates its environment in a directory whose
506
507
508
509
	 *		pathname is given in \b path, and creates its data and lock files
	 *		under that directory. With this option, \b path is used as-is for
	 *		the database main data file. The database lock file is the \b path
	 *		with "-lock" appended.
510
	 *	<li>#MDB_RDONLY
511
	 *		Open the environment in read-only mode. No write operations will be
Howard Chu's avatar
Howard Chu committed
512
513
	 *		allowed. LMDB will still modify the lock file - except on read-only
	 *		filesystems, where LMDB does not use locks.
514
515
516
517
518
	 *	<li>#MDB_WRITEMAP
	 *		Use a writeable memory map unless MDB_RDONLY is set. This is faster
	 *		and uses fewer mallocs, but loses protection from application bugs
	 *		like wild pointer writes and other bad updates into the database.
	 *		Incompatible with nested transactions.
519
	 *		Processes with and without MDB_WRITEMAP on the same environment do
520
	 *		not cooperate well.
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
	 *	<li>#MDB_NOMETASYNC
	 *		Flush system buffers to disk only once per transaction, omit the
	 *		metadata flush. Defer that until the system flushes files to disk,
	 *		or next non-MDB_RDONLY commit or #mdb_env_sync(). This optimization
	 *		maintains database integrity, but a system crash may undo the last
	 *		committed transaction. I.e. it preserves the ACI (atomicity,
	 *		consistency, isolation) but not D (durability) database property.
	 *		This flag may be changed at any time using #mdb_env_set_flags().
	 *	<li>#MDB_NOSYNC
	 *		Don't flush system buffers to disk when committing a transaction.
	 *		This optimization means a system crash can corrupt the database or
	 *		lose the last transactions if buffers are not yet flushed to disk.
	 *		The risk is governed by how often the system flushes dirty buffers
	 *		to disk and how often #mdb_env_sync() is called.  However, if the
	 *		filesystem preserves write order and the #MDB_WRITEMAP flag is not
	 *		used, transactions exhibit ACI (atomicity, consistency, isolation)
	 *		properties and only lose D (durability).  I.e. database integrity
	 *		is maintained, but a system crash may undo the final transactions.
	 *		Note that (#MDB_NOSYNC | #MDB_WRITEMAP) leaves the system with no
	 *		hint for when to write transactions to disk, unless #mdb_env_sync()
	 *		is called. (#MDB_MAPASYNC | #MDB_WRITEMAP) may be preferable.
	 *		This flag may be changed at any time using #mdb_env_set_flags().
	 *	<li>#MDB_MAPASYNC
	 *		When using #MDB_WRITEMAP, use asynchronous flushes to disk.
	 *		As with #MDB_NOSYNC, a system crash can then corrupt the
	 *		database or lose the last transactions. Calling #mdb_env_sync()
	 *		ensures on-disk database integrity until next commit.
	 *		This flag may be changed at any time using #mdb_env_set_flags().
Howard Chu's avatar
Howard Chu committed
549
550
551
552
553
554
555
556
	 *	<li>#MDB_NOTLS
	 *		Don't use Thread-Local Storage. Tie reader locktable slots to
	 *		#MDB_txn objects instead of to threads. I.e. #mdb_txn_reset() keeps
	 *		the slot reseved for the #MDB_txn object. A thread may use parallel
	 *		read-only transactions. A read-only transaction may span threads if
	 *		the user synchronizes its use. Applications that multiplex many
	 *		user threads over individual OS threads need this option. Such an
	 *		application must also serialize the write transactions in an OS
Howard Chu's avatar
Howard Chu committed
557
	 *		thread, since LMDB's write locking is unaware of the user threads.
Howard Chu's avatar
Howard Chu committed
558
559
560
561
562
563
564
	 *	<li>#MDB_NOLOCK
	 *		Don't do any locking. If concurrent access is anticipated, the
	 *		caller must manage all concurrency itself. For proper operation
	 *		the caller must enforce single-writer semantics, and must ensure
	 *		that no readers are using old transactions while a writer is
	 *		active. The simplest approach is to use an exclusive lock so that
	 *		no readers may be active at all when a writer begins.
565
566
567
568
569
570
	 *	<li>#MDB_NORDAHEAD
	 *		Turn off readahead. Most operating systems perform readahead on
	 *		read requests by default. This option turns it off if the OS
	 *		supports it. Turning it off may help random read performance
	 *		when the DB is larger than RAM and system RAM is full.
	 *		The option is not implemented on Windows.
Howard Chu's avatar
Howard Chu committed
571
572
573
574
575
576
577
578
579
	 *	<li>#MDB_NOMEMINIT
	 *		Don't initialize malloc'd memory before writing to unused spaces
	 *		in the data file. By default, memory for pages written to the data
	 *		file is obtained using malloc. While these pages may be reused in
	 *		subsequent transactions, freshly malloc'd pages will be initialized
	 *		to zeroes before use. This avoids persisting leftover data from other
	 *		code (that used the heap and subsequently freed the memory) into the
	 *		data file. Note that many other system libraries may allocate
	 *		and free memory from the heap for arbitrary uses. E.g., stdio may
Howard Chu's avatar
Howard Chu committed
580
581
	 *		use the heap for file I/O buffers. This initialization step has a
	 *		modest performance cost so some applications may want to disable
Howard Chu's avatar
Howard Chu committed
582
583
584
585
	 *		it using this flag. This option can be a problem for applications
	 *		which handle sensitive data like passwords, and it makes memory
	 *		checkers like Valgrind noisy. This flag is not needed with #MDB_WRITEMAP,
	 *		which writes directly to the mmap instead of using malloc for pages. The
Hallvard Furuseth's avatar
Hallvard Furuseth committed
586
587
588
589
	 *		initialization is also skipped if #MDB_RESERVE is used; the
	 *		caller is expected to overwrite all of the memory that was
	 *		reserved in that case.
	 *		This flag may be changed at any time using #mdb_env_set_flags().
590
	 * </ul>
Howard Chu's avatar
Howard Chu committed
591
592
	 * @param[in] mode The UNIX permissions to set on created files. This parameter
	 * is ignored on Windows.
593
594
595
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
Howard Chu's avatar
Howard Chu committed
596
	 *	<li>#MDB_VERSION_MISMATCH - the version of the LMDB library doesn't match the
597
	 *	version that created the database environment.
Howard Chu's avatar
Howard Chu committed
598
	 *	<li>#MDB_INVALID - the environment file headers are corrupted.
599
600
601
602
603
	 *	<li>ENOENT - the directory specified by the path parameter doesn't exist.
	 *	<li>EACCES - the user didn't have permission to access the environment files.
	 *	<li>EAGAIN - the environment was locked by another process.
	 * </ul>
	 */
604
int  mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mdb_mode_t mode);
605

Howard Chu's avatar
Howard Chu committed
606
	/** @brief Copy an LMDB environment to the specified path.
607
608
	 *
	 * This function may be used to make a backup of an existing environment.
609
610
611
612
	 * No lockfile is created, since it gets recreated at need.
	 * @note This call can trigger significant file size growth if run in
	 * parallel with write transactions, because it employs a read-only
	 * transaction. See long-lived transactions under @ref caveats_sec.
613
614
615
616
617
618
619
620
621
	 * @param[in] env An environment handle returned by #mdb_env_create(). It
	 * must have already been opened successfully.
	 * @param[in] path The directory in which the copy will reside. This
	 * directory must already exist and be writable but must otherwise be
	 * empty.
	 * @return A non-zero error value on failure and 0 on success.
	 */
int  mdb_env_copy(MDB_env *env, const char *path);

Howard Chu's avatar
Howard Chu committed
622
	/** @brief Copy an LMDB environment to the specified file descriptor.
Howard Chu's avatar
Howard Chu committed
623
624
	 *
	 * This function may be used to make a backup of an existing environment.
625
626
627
628
	 * No lockfile is created, since it gets recreated at need.
	 * @note This call can trigger significant file size growth if run in
	 * parallel with write transactions, because it employs a read-only
	 * transaction. See long-lived transactions under @ref caveats_sec.
Howard Chu's avatar
Howard Chu committed
629
630
631
632
633
634
	 * @param[in] env An environment handle returned by #mdb_env_create(). It
	 * must have already been opened successfully.
	 * @param[in] fd The filedescriptor to write the copy to. It must
	 * have already been opened for Write access.
	 * @return A non-zero error value on failure and 0 on success.
	 */
635
int  mdb_env_copyfd(MDB_env *env, mdb_filehandle_t fd);
Howard Chu's avatar
Howard Chu committed
636

Howard Chu's avatar
Howard Chu committed
637
	/** @brief Copy an LMDB environment to the specified path, with options.
Howard Chu's avatar
Howard Chu committed
638
639
	 *
	 * This function may be used to make a backup of an existing environment.
Howard Chu's avatar
Howard Chu committed
640
	 * No lockfile is created, since it gets recreated at need.
Howard Chu's avatar
Howard Chu committed
641
642
643
644
645
646
647
648
	 * @note This call can trigger significant file size growth if run in
	 * parallel with write transactions, because it employs a read-only
	 * transaction. See long-lived transactions under @ref caveats_sec.
	 * @param[in] env An environment handle returned by #mdb_env_create(). It
	 * must have already been opened successfully.
	 * @param[in] path The directory in which the copy will reside. This
	 * directory must already exist and be writable but must otherwise be
	 * empty.
Howard Chu's avatar
Howard Chu committed
649
650
651
652
653
654
655
656
	 * @param[in] flags Special options for this operation. This parameter
	 * must be set to 0 or by bitwise OR'ing together one or more of the
	 * values described here.
	 * <ul>
	 *	<li>#MDB_CP_COMPACT - Perform compaction while copying: omit free
	 *		pages and sequentially renumber all pages in output. This option
	 *		consumes more CPU and runs more slowly than the default.
	 * </ul>
Howard Chu's avatar
Howard Chu committed
657
658
	 * @return A non-zero error value on failure and 0 on success.
	 */
Howard Chu's avatar
Howard Chu committed
659
int  mdb_env_copy2(MDB_env *env, const char *path, unsigned int flags);
Howard Chu's avatar
Howard Chu committed
660
661

	/** @brief Copy an LMDB environment to the specified file descriptor,
Howard Chu's avatar
Howard Chu committed
662
	 *	with options.
Howard Chu's avatar
Howard Chu committed
663
664
665
666
667
668
669
670
671
672
673
	 *
	 * This function may be used to make a backup of an existing environment.
	 * No lockfile is created, since it gets recreated at need. See
	 * #mdb_env_copy2() for further details.
	 * @note This call can trigger significant file size growth if run in
	 * parallel with write transactions, because it employs a read-only
	 * transaction. See long-lived transactions under @ref caveats_sec.
	 * @param[in] env An environment handle returned by #mdb_env_create(). It
	 * must have already been opened successfully.
	 * @param[in] fd The filedescriptor to write the copy to. It must
	 * have already been opened for Write access.
Howard Chu's avatar
Howard Chu committed
674
675
	 * @param[in] flags Special options for this operation.
	 * See #mdb_env_copy2() for options.
Howard Chu's avatar
Howard Chu committed
676
677
	 * @return A non-zero error value on failure and 0 on success.
	 */
Howard Chu's avatar
Howard Chu committed
678
int  mdb_env_copyfd2(MDB_env *env, mdb_filehandle_t fd, unsigned int flags);
Howard Chu's avatar
Howard Chu committed
679

Howard Chu's avatar
Howard Chu committed
680
	/** @brief Return statistics about the LMDB environment.
681
	 *
682
683
684
685
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[out] stat The address of an #MDB_stat structure
	 * 	where the statistics will be copied
	 */
Howard Chu's avatar
Howard Chu committed
686
int  mdb_env_stat(MDB_env *env, MDB_stat *stat);
687

Howard Chu's avatar
Howard Chu committed
688
	/** @brief Return information about the LMDB environment.
689
690
691
692
693
694
695
	 *
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[out] stat The address of an #MDB_envinfo structure
	 * 	where the information will be copied
	 */
int  mdb_env_info(MDB_env *env, MDB_envinfo *stat);

696
697
	/** @brief Flush the data buffers to disk.
	 *
698
	 * Data is always written to disk when #mdb_txn_commit() is called,
Howard Chu's avatar
Howard Chu committed
699
	 * but the operating system may keep it buffered. LMDB always flushes
700
	 * the OS buffers upon commit as well, unless the environment was
701
	 * opened with #MDB_NOSYNC or in part #MDB_NOMETASYNC.
702
	 * @param[in] env An environment handle returned by #mdb_env_create()
703
	 * @param[in] force If non-zero, force a synchronous flush.  Otherwise
704
	 *  if the environment has the #MDB_NOSYNC flag set the flushes
705
	 *	will be omitted, and with #MDB_MAPASYNC they will be asynchronous.
706
707
708
709
710
711
712
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified.
	 *	<li>EIO - an error occurred during synchronization.
	 * </ul>
	 */
Howard Chu's avatar
Howard Chu committed
713
int  mdb_env_sync(MDB_env *env, int force);
714

715
716
	/** @brief Close the environment and release the memory map.
	 *
717
718
719
720
721
722
	 * Only a single thread may call this function. All transactions, databases,
	 * and cursors must already be closed before calling this function. Attempts to
	 * use any such handles after calling this function will cause a SIGSEGV.
	 * The environment handle will be freed and must not be used again after this call.
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 */
Howard Chu's avatar
Howard Chu committed
723
void mdb_env_close(MDB_env *env);
724

725
726
	/** @brief Set environment flags.
	 *
727
	 * This may be used to set some flags in addition to those from
728
729
	 * #mdb_env_open(), or to unset these flags.  If several threads
	 * change the flags at the same time, the result is undefined.
730
731
732
733
734
735
736
737
738
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[in] flags The flags to change, bitwise OR'ed together
	 * @param[in] onoff A non-zero value sets the flags, zero clears them.
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified.
	 * </ul>
	 */
739
int  mdb_env_set_flags(MDB_env *env, unsigned int flags, int onoff);
740

741
742
	/** @brief Get environment flags.
	 *
743
744
745
746
747
748
749
750
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[out] flags The address of an integer to store the flags
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified.
	 * </ul>
	 */
Howard Chu's avatar
Howard Chu committed
751
int  mdb_env_get_flags(MDB_env *env, unsigned int *flags);
752

753
754
	/** @brief Return the path that was used in #mdb_env_open().
	 *
755
756
757
758
759
760
761
762
763
764
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[out] path Address of a string pointer to contain the path. This
	 * is the actual string in the environment, not a copy. It should not be
	 * altered in any way.
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified.
	 * </ul>
	 */
Howard Chu's avatar
Howard Chu committed
765
int  mdb_env_get_path(MDB_env *env, const char **path);
766

Howard Chu's avatar
Howard Chu committed
767
768
769
770
771
772
773
774
775
776
777
778
	/** @brief Return the filedescriptor for the given environment.
	 *
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[out] fd Address of a mdb_filehandle_t to contain the descriptor.
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified.
	 * </ul>
	 */
int  mdb_env_get_fd(MDB_env *env, mdb_filehandle_t *fd);

779
780
	/** @brief Set the size of the memory map to use for this environment.
	 *
781
	 * The size should be a multiple of the OS page size. The default is
Howard Chu's avatar
Howard Chu committed
782
783
	 * 10485760 bytes. The size of the memory map is also the maximum size
	 * of the database. The value should be chosen as large as possible,
Hallvard Furuseth's avatar
Hallvard Furuseth committed
784
	 * to accommodate future growth of the database.
785
786
787
	 * This function should be called after #mdb_env_create() and before #mdb_env_open().
	 * It may be called at later times if no transactions are active in
	 * this process. Note that the library does not check for this condition,
788
	 * the caller must ensure it explicitly.
789
	 *
Howard Chu's avatar
Howard Chu committed
790
791
792
793
794
795
796
	 * The new size takes effect immediately for the current process but
	 * will not be persisted to any others until a write transaction has been
	 * committed by the current process. Also, only mapsize increases are
	 * persisted into the environment.
	 *
	 * If the mapsize is increased by another process, and data has grown
	 * beyond the range of the current mapsize, #mdb_txn_begin() will
797
798
799
	 * return #MDB_MAP_RESIZED. This function may be called with a size
	 * of zero to adopt the new size.
	 *
800
801
	 * Any attempt to set a size smaller than the space already consumed
	 * by the environment will be silently changed to the current size of the used space.
802
803
804
805
806
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[in] size The size in bytes
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
807
808
	 *	<li>EINVAL - an invalid parameter was specified, or the environment has
	 *   	an active write transaction.
809
810
	 * </ul>
	 */
Howard Chu's avatar
Howard Chu committed
811
int  mdb_env_set_mapsize(MDB_env *env, size_t size);
812

Howard Chu's avatar
Howard Chu committed
813
	/** @brief Set the maximum number of threads/reader slots for the environment.
814
	 *
815
816
	 * This defines the number of slots in the lock table that is used to track readers in the
	 * the environment. The default is 126.
Howard Chu's avatar
Howard Chu committed
817
818
819
820
	 * Starting a read-only transaction normally ties a lock table slot to the
	 * current thread until the environment closes or the thread exits. If
	 * MDB_NOTLS is in use, #mdb_txn_begin() instead ties the slot to the
	 * MDB_txn object until it or the #MDB_env object is destroyed.
821
822
	 * This function may only be called after #mdb_env_create() and before #mdb_env_open().
	 * @param[in] env An environment handle returned by #mdb_env_create()
Howard Chu's avatar
Howard Chu committed
823
	 * @param[in] readers The maximum number of reader lock table slots
824
825
826
827
828
829
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified, or the environment is already open.
	 * </ul>
	 */
830
int  mdb_env_set_maxreaders(MDB_env *env, unsigned int readers);
831

Howard Chu's avatar
Howard Chu committed
832
	/** @brief Get the maximum number of threads/reader slots for the environment.
833
	 *
834
835
836
837
838
839
840
841
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[out] readers Address of an integer to store the number of readers
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified.
	 * </ul>
	 */
842
int  mdb_env_get_maxreaders(MDB_env *env, unsigned int *readers);
843

844
	/** @brief Set the maximum number of named databases for the environment.
845
	 *
846
	 * This function is only needed if multiple databases will be used in the
847
848
	 * environment. Simpler applications that use the environment as a single
	 * unnamed database can ignore this option.
849
	 * This function may only be called after #mdb_env_create() and before #mdb_env_open().
850
851
852
853
	 *
	 * Currently a moderate number of slots are cheap but a huge number gets
	 * expensive: 7-120 words per transaction, and every #mdb_dbi_open()
	 * does a linear search of the opened slots.
854
855
856
857
858
859
860
861
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[in] dbs The maximum number of databases
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified, or the environment is already open.
	 * </ul>
	 */
862
int  mdb_env_set_maxdbs(MDB_env *env, MDB_dbi dbs);
Howard Chu's avatar
Howard Chu committed
863

864
	/** @brief Get the maximum size of keys and #MDB_DUPSORT data we can write.
Howard Chu's avatar
Howard Chu committed
865
	 *
866
	 * Depends on the compile-time constant #MDB_MAXKEYSIZE. Default 511.
867
	 * See @ref MDB_val.
Howard Chu's avatar
Howard Chu committed
868
	 * @param[in] env An environment handle returned by #mdb_env_create()
869
	 * @return The maximum size of a key we can write
Howard Chu's avatar
Howard Chu committed
870
871
872
	 */
int  mdb_env_get_maxkeysize(MDB_env *env);

873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
	/** @brief Set application information associated with the #MDB_env.
	 *
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @param[in] ctx An arbitrary pointer for whatever the application needs.
	 * @return A non-zero error value on failure and 0 on success.
	 */
int  mdb_env_set_userctx(MDB_env *env, void *ctx);

	/** @brief Get the application information associated with the #MDB_env.
	 *
	 * @param[in] env An environment handle returned by #mdb_env_create()
	 * @return The pointer set by #mdb_env_set_userctx().
	 */
void *mdb_env_get_userctx(MDB_env *env);

Howard Chu's avatar
Howard Chu committed
888
	/** @brief A callback function for most LMDB assert() failures,
889
890
891
892
893
894
895
896
897
898
899
	 * called before printing the message and aborting.
	 *
	 * @param[in] env An environment handle returned by #mdb_env_create().
	 * @param[in] msg The assertion message, not including newline.
	 */
typedef void MDB_assert_func(MDB_env *env, const char *msg);

	/** Set or reset the assert() callback of the environment.
	 * Disabled if liblmdb is buillt with NDEBUG.
	 * @note This hack should become obsolete as lmdb's error handling matures.
	 * @param[in] env An environment handle returned by #mdb_env_create().
Hallvard Furuseth's avatar
Hallvard Furuseth committed
900
	 * @param[in] func An #MDB_assert_func function, or 0.
901
902
903
904
	 * @return A non-zero error value on failure and 0 on success.
	 */
int  mdb_env_set_assert(MDB_env *env, MDB_assert_func *func);

905
906
	/** @brief Create a transaction for use with the environment.
	 *
907
	 * The transaction handle may be discarded using #mdb_txn_abort() or #mdb_txn_commit().
Howard Chu's avatar
Howard Chu committed
908
909
910
	 * @note A transaction and its cursors must only be used by a single
	 * thread, and a thread may only have a single transaction at a time.
	 * If #MDB_NOTLS is in use, this does not apply to read-only transactions.
911
	 * @note Cursors may not span transactions.
912
	 * @param[in] env An environment handle returned by #mdb_env_create()
913
914
915
	 * @param[in] parent If this parameter is non-NULL, the new transaction
	 * will be a nested transaction, with the transaction indicated by \b parent
	 * as its parent. Transactions may be nested to any level. A parent
916
917
	 * transaction and its cursors may not issue any other operations than
	 * mdb_txn_commit and mdb_txn_abort while it has active child transactions.
918
919
920
921
922
923
924
925
926
927
928
929
	 * @param[in] flags Special options for this transaction. This parameter
	 * must be set to 0 or by bitwise OR'ing together one or more of the
	 * values described here.
	 * <ul>
	 *	<li>#MDB_RDONLY
	 *		This transaction will not perform any write operations.
	 * </ul>
	 * @param[out] txn Address where the new #MDB_txn handle will be stored
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>#MDB_PANIC - a fatal error occurred earlier and the environment
930
	 *		must be shut down.
931
	 *	<li>#MDB_MAP_RESIZED - another process wrote data beyond this MDB_env's
932
933
	 *		mapsize and this environment's map must be resized as well.
	 *		See #mdb_env_set_mapsize().
Howard Chu's avatar
Howard Chu committed
934
	 *	<li>#MDB_READERS_FULL - a read-only transaction was requested and
935
	 *		the reader lock table is full. See #mdb_env_set_maxreaders().
Howard Chu's avatar
Howard Chu committed
936
	 *	<li>ENOMEM - out of memory.
937
938
	 * </ul>
	 */
939
int  mdb_txn_begin(MDB_env *env, MDB_txn *parent, unsigned int flags, MDB_txn **txn);
940

941
942
943
944
945
946
	/** @brief Returns the transaction's #MDB_env
	 *
	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
	 */
MDB_env *mdb_txn_env(MDB_txn *txn);

947
948
	/** @brief Commit all the operations of a transaction into the database.
	 *
949
950
951
952
	 * The transaction handle is freed. It and its cursors must not be used
	 * again after this call, except with #mdb_cursor_renew().
	 * @note Earlier documentation incorrectly said all cursors would be freed.
	 * Only write-transactions free cursors.
953
954
955
956
957
958
959
	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>EINVAL - an invalid parameter was specified.
	 *	<li>ENOSPC - no more disk space.
	 *	<li>EIO - a low-level I/O error occurred while writing.
Howard Chu's avatar
Howard Chu committed
960
	 *	<li>ENOMEM - out of memory.
961
962
	 * </ul>
	 */
Howard Chu's avatar
Howard Chu committed
963
int  mdb_txn_commit(MDB_txn *txn);
964

965
966
	/** @brief Abandon all the operations of the transaction instead of saving them.
	 *
967
968
969
970
	 * The transaction handle is freed. It and its cursors must not be used
	 * again after this call, except with #mdb_cursor_renew().
	 * @note Earlier documentation incorrectly said all cursors would be freed.
	 * Only write-transactions free cursors.
971
972
	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
	 */
Howard Chu's avatar
Howard Chu committed
973
974
void mdb_txn_abort(MDB_txn *txn);

975
976
	/** @brief Reset a read-only transaction.
	 *
Howard Chu's avatar
Howard Chu committed
977
978
979
980
981
982
983
	 * Abort the transaction like #mdb_txn_abort(), but keep the transaction
	 * handle. #mdb_txn_renew() may reuse the handle. This saves allocation
	 * overhead if the process will start a new read-only transaction soon,
	 * and also locking overhead if #MDB_NOTLS is in use. The reader table
	 * lock is released, but the table slot stays tied to its thread or
	 * #MDB_txn. Use mdb_txn_abort() to discard a reset handle, and to free
	 * its lock table slot if MDB_NOTLS is in use.
984
985
	 * Cursors opened within the transaction must not be used
	 * again after this call, except with #mdb_cursor_renew().
986
987
988
989
990
991
992
993
	 * Reader locks generally don't interfere with writers, but they keep old
	 * versions of database pages allocated. Thus they prevent the old pages
	 * from being reused when writers commit new data, and so under heavy load
	 * the database size may grow much more rapidly than otherwise.
	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
	 */
void mdb_txn_reset(MDB_txn *txn);

994
995
	/** @brief Renew a read-only transaction.
	 *
996
997
998
999
1000
	 * This acquires a new reader lock for a transaction handle that had been
	 * released by #mdb_txn_reset(). It must be called before a reset transaction
	 * may be used again.
	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
	 * @return A non-zero error value on failure and 0 on success. Some possible
For faster browsing, not all history is shown. View entire blame