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