lmdb.h 64.7 KB
Newer Older
Howard Chu's avatar
Howard Chu committed
1
2
/** @file lmdb.h
 *	@brief Lightning memory-mapped database library
3
 *
4
 *	@mainpage	Lightning Memory-Mapped Database Manager (MDB)
Howard Chu's avatar
Howard Chu committed
5
6
 *
 *	@section intro_sec Introduction
7
8
 *	MDB is a Btree-based database management library modeled loosely on the
 *	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
29
30
31
32
33
34
35
 *	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
 *	transaction logs or append-only data writes, MDB requires no maintenance
 *	during operation. Both write-ahead loggers and append-only databases
 *	require periodic checkpointing and/or compaction of their log or database
 *	files otherwise they grow without bound. MDB tracks free pages within
 *	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
52
53
54
 *	  Fix: Check for stale readers periodically, using the
 *	  #mdb_reader_check function or the mdb_stat tool. Or just
 *	  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
89
90
91
92
93
94
95
96
97
98
 *
 *	- Use an MDB_env* in the process which opened it, without fork()ing.
 *
 *	- Do not have open an MDB database twice in the same process at
 *	  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
 *
Hallvard Furuseth's avatar
Hallvard Furuseth committed
112
113
114
115
 *	- Do not use MDB databases on remote filesystems, even between
 *	  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-2013 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 MDB 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	10
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	"November 11, 2013"
198
199

/** A stringifier for the version info */
Howard Chu's avatar
Howard Chu committed
200
#define MDB_VERSTR(a,b,c,d)	"MDB " #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
/*	@} */

336
337
/** @brief Cursor Get operations.
 *
338
339
340
 *	This is the set of all operations for retrieving data
 *	using a cursor.
 */
341
342
typedef enum MDB_cursor_op {
	MDB_FIRST,				/**< Position at first key/data item */
343
344
	MDB_FIRST_DUP,			/**< Position at first data item of current key.
								Only for #MDB_DUPSORT */
345
346
	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
347
	MDB_GET_CURRENT,		/**< Return key/data at current cursor position */
348
349
350
	MDB_GET_MULTIPLE,		/**< Return all the duplicate data items at the current
								 cursor position. Only for #MDB_DUPFIXED */
	MDB_LAST,				/**< Position at last key/data item */
351
352
	MDB_LAST_DUP,			/**< Position at last data item of current key.
								Only for #MDB_DUPSORT */
353
354
355
356
357
	MDB_NEXT,				/**< Position at next data item */
	MDB_NEXT_DUP,			/**< Position at next data item of current key.
								Only for #MDB_DUPSORT */
	MDB_NEXT_MULTIPLE,		/**< Return all duplicate data items at the next
								cursor position. Only for #MDB_DUPFIXED */
358
	MDB_NEXT_NODUP,			/**< Position at first data item of next key */
359
360
361
	MDB_PREV,				/**< Position at previous data item */
	MDB_PREV_DUP,			/**< Position at previous data item of current key.
								Only for #MDB_DUPSORT */
362
	MDB_PREV_NODUP,			/**< Position at last data item of previous key */
363
	MDB_SET,				/**< Position at specified key */
Howard Chu's avatar
Howard Chu committed
364
	MDB_SET_KEY,			/**< Position at specified key, return key + data */
365
	MDB_SET_RANGE			/**< Position at first key greater than or equal to specified key. */
Howard Chu's avatar
Howard Chu committed
366
367
} MDB_cursor_op;

368
369
370
371
372
373
/** @defgroup  errors	Return Codes
 *
 *	BerkeleyDB uses -30800 to -30999, we'll go under them
 *	@{
 */
	/**	Successful result */
Howard Chu's avatar
Howard Chu committed
374
#define MDB_SUCCESS	 0
375
376
377
378
379
380
381
382
383
384
385
386
	/** 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)
	/** Update of meta page failed, probably I/O error */
#define MDB_PANIC		(-30795)
	/** Environment version mismatch */
#define MDB_VERSION_MISMATCH	(-30794)
387
388
389
390
391
392
393
394
395
396
	/** File is not a valid MDB file */
#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)
397
	/** Txn has too many dirty pages */
398
399
400
401
402
#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)
403
404
	/** Database contents grew beyond environment mapsize */
#define MDB_MAP_RESIZED	(-30785)
405
	/** MDB_INCOMPATIBLE: Operation and DB incompatible, or DB flags changed */
406
#define MDB_INCOMPATIBLE	(-30784)
407
408
	/** Invalid reuse of reader locktable slot */
#define MDB_BAD_RSLOT		(-30783)
409
410
411
412
413
	/** Transaction cannot recover - it must be aborted */
#define MDB_BAD_TXN			(-30782)
	/** Too big key/data, key is empty, or wrong DUPFIXED size */
#define MDB_BAD_VALSIZE		(-30781)
#define MDB_LAST_ERRCODE	MDB_BAD_VALSIZE
414
415
/** @} */

416
/** @brief Statistics for a database in the environment */
Howard Chu's avatar
Howard Chu committed
417
typedef struct MDB_stat {
418
419
420
	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 */
421
422
423
424
	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
425
426
} MDB_stat;

427
428
/** @brief Information about the environment */
typedef struct MDB_envinfo {
Howard Chu's avatar
Howard Chu committed
429
	void	*me_mapaddr;			/**< Address of map, if fixed */
430
431
	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
432
	size_t	me_last_txnid;			/**< ID of the last committed transaction */
Howard Chu's avatar
Howard Chu committed
433
434
	unsigned int me_maxreaders;		/**< max reader slots in the environment */
	unsigned int me_numreaders;		/**< max reader slots used in the environment */
435
436
} MDB_envinfo;

437
438
	/** @brief Return the mdb library version information.
	 *
439
440
441
442
443
	 * @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
444
char *mdb_version(int *major, int *minor, int *patch);
445

446
447
	/** @brief Return a string describing a given error code.
	 *
448
449
450
451
452
453
454
455
	 * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3)
	 * function. If the error code is greater than or equal to 0, then the string
	 * returned by the system function strerror(3) is returned. If the error code
	 * is less than 0, an error string corresponding to the MDB library error is
	 * returned. See @ref errors for a list of MDB-specific error codes.
	 * @param[in] err The error code
	 * @retval "error message" The description of the error
	 */
456
char *mdb_strerror(int err);
457

458
459
	/** @brief Create an MDB environment handle.
	 *
460
461
462
463
464
465
466
467
468
	 * 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
469
int  mdb_env_create(MDB_env **env);
470

471
472
	/** @brief Open an environment handle.
	 *
473
474
	 * 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
475
476
	 * @param[in] path The directory in which the database files reside. This
	 * directory must already exist and be writable.
477
478
479
	 * @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.
480
	 * Flags set by mdb_env_set_flags() are also used.
481
482
483
484
485
486
487
488
489
	 * <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.
490
491
492
493
494
495
	 *	<li>#MDB_NOSUBDIR
	 *		By default, MDB creates its environment in a directory whose
	 *		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.
496
	 *	<li>#MDB_RDONLY
497
498
499
500
501
502
503
504
	 *		Open the environment in read-only mode. No write operations will be
	 *		allowed. MDB will still modify the lock file - except on read-only
	 *		filesystems, where MDB does not use locks.
	 *	<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.
505
	 *		Processes with and without MDB_WRITEMAP on the same environment do
506
	 *		not cooperate well.
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
	 *	<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
535
536
537
538
539
540
541
542
543
	 *	<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
	 *		thread, since MDB's write locking is unaware of the user threads.
Howard Chu's avatar
Howard Chu committed
544
545
546
547
548
549
550
	 *	<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.
551
552
553
554
555
556
	 *	<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
557
558
559
560
561
562
563
564
565
	 *	<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
566
567
	 *		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
568
569
570
571
	 *		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
572
573
574
575
	 *		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().
576
	 * </ul>
Howard Chu's avatar
Howard Chu committed
577
578
	 * @param[in] mode The UNIX permissions to set on created files. This parameter
	 * is ignored on Windows.
579
580
581
582
583
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>#MDB_VERSION_MISMATCH - the version of the MDB library doesn't match the
	 *	version that created the database environment.
Howard Chu's avatar
Howard Chu committed
584
	 *	<li>#MDB_INVALID - the environment file headers are corrupted.
585
586
587
588
589
	 *	<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>
	 */
590
int  mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mdb_mode_t mode);
591

592
593
594
	/** @brief Copy an MDB environment to the specified path.
	 *
	 * This function may be used to make a backup of an existing environment.
595
596
597
598
	 * 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.
599
600
601
602
603
604
605
606
607
	 * @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
608
609
610
	/** @brief Copy an MDB environment to the specified file descriptor.
	 *
	 * This function may be used to make a backup of an existing environment.
611
612
613
614
	 * 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
615
616
617
618
619
620
	 * @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.
	 */
621
int  mdb_env_copyfd(MDB_env *env, mdb_filehandle_t fd);
Howard Chu's avatar
Howard Chu committed
622

623
624
	/** @brief Return statistics about the MDB environment.
	 *
625
626
627
628
	 * @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
629
int  mdb_env_stat(MDB_env *env, MDB_stat *stat);
630

631
632
633
634
635
636
637
638
	/** @brief Return information about the MDB environment.
	 *
	 * @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);

639
640
	/** @brief Flush the data buffers to disk.
	 *
641
642
643
	 * Data is always written to disk when #mdb_txn_commit() is called,
	 * but the operating system may keep it buffered. MDB always flushes
	 * the OS buffers upon commit as well, unless the environment was
644
	 * opened with #MDB_NOSYNC or in part #MDB_NOMETASYNC.
645
	 * @param[in] env An environment handle returned by #mdb_env_create()
646
	 * @param[in] force If non-zero, force a synchronous flush.  Otherwise
647
	 *  if the environment has the #MDB_NOSYNC flag set the flushes
648
	 *	will be omitted, and with #MDB_MAPASYNC they will be asynchronous.
649
650
651
652
653
654
655
	 * @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
656
int  mdb_env_sync(MDB_env *env, int force);
657

658
659
	/** @brief Close the environment and release the memory map.
	 *
660
661
662
663
664
665
	 * 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
666
void mdb_env_close(MDB_env *env);
667

668
669
	/** @brief Set environment flags.
	 *
670
	 * This may be used to set some flags in addition to those from
Howard Chu's avatar
Howard Chu committed
671
	 * #mdb_env_open(), or to unset these flags.
672
673
674
675
676
677
678
679
680
	 * @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>
	 */
681
int  mdb_env_set_flags(MDB_env *env, unsigned int flags, int onoff);
682

683
684
	/** @brief Get environment flags.
	 *
685
686
687
688
689
690
691
692
	 * @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
693
int  mdb_env_get_flags(MDB_env *env, unsigned int *flags);
694

695
696
	/** @brief Return the path that was used in #mdb_env_open().
	 *
697
698
699
700
701
702
703
704
705
706
	 * @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
707
int  mdb_env_get_path(MDB_env *env, const char **path);
708

Howard Chu's avatar
Howard Chu committed
709
710
711
712
713
714
715
716
717
718
719
720
	/** @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);

721
722
	/** @brief Set the size of the memory map to use for this environment.
	 *
723
	 * The size should be a multiple of the OS page size. The default is
Howard Chu's avatar
Howard Chu committed
724
725
	 * 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
726
	 * to accommodate future growth of the database.
727
728
729
730
731
732
733
734
735
	 * This function should be called after #mdb_env_create() and before #mdb_env_open().
	 * It may be called at later times if no transactions are active in
	 * this process. Note that the library does not check for this condition,
	 * the caller must ensure it explicitly.
	 *
	 * If the mapsize is changed by another process, #mdb_txn_begin() will
	 * return #MDB_MAP_RESIZED. This function may be called with a size
	 * of zero to adopt the new size.
	 *
736
737
	 * 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.
738
739
740
741
742
	 * @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>
743
744
	 *	<li>EINVAL - an invalid parameter was specified, or the environment has
	 *   	an active write transaction.
745
746
	 * </ul>
	 */
Howard Chu's avatar
Howard Chu committed
747
int  mdb_env_set_mapsize(MDB_env *env, size_t size);
748

Howard Chu's avatar
Howard Chu committed
749
	/** @brief Set the maximum number of threads/reader slots for the environment.
750
	 *
751
752
	 * 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
753
754
755
756
	 * 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.
757
758
	 * 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
759
	 * @param[in] readers The maximum number of reader lock table slots
760
761
762
763
764
765
	 * @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>
	 */
766
int  mdb_env_set_maxreaders(MDB_env *env, unsigned int readers);
767

Howard Chu's avatar
Howard Chu committed
768
	/** @brief Get the maximum number of threads/reader slots for the environment.
769
	 *
770
771
772
773
774
775
776
777
	 * @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>
	 */
778
int  mdb_env_get_maxreaders(MDB_env *env, unsigned int *readers);
779

780
	/** @brief Set the maximum number of named databases for the environment.
781
	 *
782
	 * This function is only needed if multiple databases will be used in the
783
784
	 * environment. Simpler applications that use the environment as a single
	 * unnamed database can ignore this option.
785
786
787
788
789
790
791
792
793
	 * 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()
	 * @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>
	 */
794
int  mdb_env_set_maxdbs(MDB_env *env, MDB_dbi dbs);
Howard Chu's avatar
Howard Chu committed
795

796
	/** @brief Get the maximum size of keys and #MDB_DUPSORT data we can write.
Howard Chu's avatar
Howard Chu committed
797
	 *
798
	 * Depends on the compile-time constant #MDB_MAXKEYSIZE. Default 511.
799
	 * See @ref MDB_val.
Howard Chu's avatar
Howard Chu committed
800
	 * @param[in] env An environment handle returned by #mdb_env_create()
801
	 * @return The maximum size of a key we can write
Howard Chu's avatar
Howard Chu committed
802
803
804
	 */
int  mdb_env_get_maxkeysize(MDB_env *env);

805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
	/** @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);

820
821
	/** @brief Create a transaction for use with the environment.
	 *
822
	 * The transaction handle may be discarded using #mdb_txn_abort() or #mdb_txn_commit().
Howard Chu's avatar
Howard Chu committed
823
824
825
	 * @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.
826
	 * @note Cursors may not span transactions.
827
	 * @param[in] env An environment handle returned by #mdb_env_create()
828
829
830
	 * @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
831
832
	 * transaction and its cursors may not issue any other operations than
	 * mdb_txn_commit and mdb_txn_abort while it has active child transactions.
833
834
835
836
837
838
839
840
841
842
843
844
	 * @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
845
	 *		must be shut down.
846
	 *	<li>#MDB_MAP_RESIZED - another process wrote data beyond this MDB_env's
847
848
	 *		mapsize and this environment's map must be resized as well.
	 *		See #mdb_env_set_mapsize().
Howard Chu's avatar
Howard Chu committed
849
	 *	<li>#MDB_READERS_FULL - a read-only transaction was requested and
850
	 *		the reader lock table is full. See #mdb_env_set_maxreaders().
Howard Chu's avatar
Howard Chu committed
851
	 *	<li>ENOMEM - out of memory.
852
853
	 * </ul>
	 */
854
int  mdb_txn_begin(MDB_env *env, MDB_txn *parent, unsigned int flags, MDB_txn **txn);
855

856
857
858
859
860
861
	/** @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);

862
863
	/** @brief Commit all the operations of a transaction into the database.
	 *
864
865
866
867
	 * 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.
868
869
870
871
872
873
874
	 * @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
875
	 *	<li>ENOMEM - out of memory.
876
877
	 * </ul>
	 */
Howard Chu's avatar
Howard Chu committed
878
int  mdb_txn_commit(MDB_txn *txn);
879

880
881
	/** @brief Abandon all the operations of the transaction instead of saving them.
	 *
882
883
884
885
	 * 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.
886
887
	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
	 */
Howard Chu's avatar
Howard Chu committed
888
889
void mdb_txn_abort(MDB_txn *txn);

890
891
	/** @brief Reset a read-only transaction.
	 *
Howard Chu's avatar
Howard Chu committed
892
893
894
895
896
897
898
	 * 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.
899
900
	 * Cursors opened within the transaction must not be used
	 * again after this call, except with #mdb_cursor_renew().
901
902
903
904
905
906
907
908
	 * 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);

909
910
	/** @brief Renew a read-only transaction.
	 *
911
912
913
914
915
916
917
918
919
920
921
922
923
924
	 * 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
	 * errors are:
	 * <ul>
	 *	<li>#MDB_PANIC - a fatal error occurred earlier and the environment
	 *		must be shut down.
	 *	<li>EINVAL - an invalid parameter was specified.
	 * </ul>
	 */
int  mdb_txn_renew(MDB_txn *txn);

925
926
927
928
929
/** Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project */
#define mdb_open(txn,name,flags,dbi)	mdb_dbi_open(txn,name,flags,dbi)
/** Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project */
#define mdb_close(env,dbi)				mdb_dbi_close(env,dbi)

930
931
	/** @brief Open a database in the environment.
	 *
932
933
	 * A database handle denotes the name and parameters of a database,
	 * independently of whether such a database exists.
934
	 * The database handle may be discarded by calling #mdb_dbi_close().
935
936
937
938
939
940
941
942
943
944
945
946
	 * The old database handle is returned if the database was already open.
	 * The handle must only be closed once.
	 * The database handle will be private to the current transaction until
	 * the transaction is successfully committed. If the transaction is
	 * aborted the handle will be closed automatically.
	 * After a successful commit the
	 * handle will reside in the shared environment, and may be used
	 * by other transactions. This function must not be called from
	 * multiple concurrent transactions. A transaction that uses this function
	 * must finish (either commit or abort) before any other transaction may
	 * use this function.
	 *
947
	 * To use named databases (with name != NULL), #mdb_env_set_maxdbs()
948
	 * must be called before opening the environment.
949
950
	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
	 * @param[in] name The name of the database to open. If only a single
Hallvard Furuseth's avatar
Hallvard Furuseth committed
951
	 * 	database is needed in the environment, this value may be NULL.
952
953
954
955
956
957
958
959
960
961
962
963
964
	 * @param[in] flags Special options for this database. This parameter
	 * must be set to 0 or by bitwise OR'ing together one or more of the
	 * values described here.
	 * <ul>
	 *	<li>#MDB_REVERSEKEY
	 *		Keys are strings to be compared in reverse order, from the end
	 *		of the strings to the beginning. By default, Keys are treated as strings and
	 *		compared from beginning to end.
	 *	<li>#MDB_DUPSORT
	 *		Duplicate keys may be used in the database. (Or, from another perspective,
	 *		keys may have multiple data items, stored in sorted order.) By default
	 *		keys must be unique and may have only a single data item.
	 *	<li>#MDB_INTEGERKEY
965
966
	 *		Keys are binary integers in native byte order. Setting this option
	 *		requires all keys to be the same size, typically sizeof(int)
967
	 *		or sizeof(size_t).
968
969
970
971
972
973
974
975
976
	 *	<li>#MDB_DUPFIXED
	 *		This flag may only be used in combination with #MDB_DUPSORT. This option
	 *		tells the library that the data items for this database are all the same
	 *		size, which allows further optimizations in storage and retrieval. When
	 *		all data items are the same size, the #MDB_GET_MULTIPLE and #MDB_NEXT_MULTIPLE
	 *		cursor operations may be used to retrieve multiple items at once.
	 *	<li>#MDB_INTEGERDUP
	 *		This option specifies that duplicate data items are also integers, and
	 *		should be sorted as such.
977
978
979
	 *	<li>#MDB_REVERSEDUP
	 *		This option specifies that duplicate data items should be compared as
	 *		strings in reverse order.
980
981
982
983
984
985
986
987
988
989
	 *	<li>#MDB_CREATE
	 *		Create the named database if it doesn't exist. This option is not
	 *		allowed in a read-only transaction or a read-only environment.
	 * </ul>
	 * @param[out] dbi Address where the new #MDB_dbi handle will be stored
	 * @return A non-zero error value on failure and 0 on success. Some possible
	 * errors are:
	 * <ul>
	 *	<li>#MDB_NOTFOUND - the specified database doesn't exist in the environment
	 *		and #MDB_CREATE was not specified.
Howard Chu's avatar
Howard Chu committed
990
	 *	<li>#MDB_DBS_FULL - too many databases have been opened. See #mdb_env_set_maxdbs().
991
992
	 * </ul>
	 */
993
int  mdb_dbi_open(MDB_txn *txn, const char *name, unsigned int flags, MDB_dbi *dbi);
994

995
996
	/** @brief Retrieve statistics for a database.
	 *
997
	 * @param[in] txn A transaction handle returned by #mdb_txn_begin()
998
	 * @param[in] dbi A database handle returned by #mdb_dbi_open()
999
1000
	 * @param[out] stat The address of an #MDB_stat structure
	 * 	where the statistics will be copied
For faster browsing, not all history is shown. View entire blame