lmdb.h 72.3 KB
 Howard Chu committed Nov 30, 2012 1 2 /** @file lmdb.h * @brief Lightning memory-mapped database library  Howard Chu committed Sep 01, 2011 3  *  Howard Chu committed Jun 24, 2014 4  * @mainpage Lightning Memory-Mapped Database Manager (LMDB)  Howard Chu committed Nov 28, 2012 5 6  * * @section intro_sec Introduction  Howard Chu committed Jun 24, 2014 7  * LMDB is a Btree-based database management library modeled loosely on the  Howard Chu committed Sep 01, 2011 8  * BerkeleyDB API, but much simplified. The entire database is exposed  Howard Chu committed Sep 07, 2012 9  * in a memory map, and all data fetches return data directly  Howard Chu committed Sep 01, 2011 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 committed Sep 07, 2012 14  * full ACID semantics, and when the memory map is read-only, the  Howard Chu committed Sep 01, 2011 15 16 17 18 19 20 21 22 23 24 25 26 27 28  * database integrity cannot be corrupted by stray pointer writes from * application code. * * The library is fully thread-aware and supports concurrent read/write * access from multiple processes and threads. Data pages use a copy-on- * write strategy so no active data pages are ever overwritten, which * also provides resistance to corruption and eliminates the need of any * special recovery procedures after a system crash. Writes are fully * serialized; only one write transaction may be active at a time, which * guarantees that writers can never deadlock. The database structure is * multi-versioned so readers run with no locks; writers cannot block * readers, and readers don't block writers. * * Unlike other well-known database mechanisms which use either write-ahead  Howard Chu committed Jun 24, 2014 29  * transaction logs or append-only data writes, LMDB requires no maintenance  Howard Chu committed Sep 01, 2011 30 31  * during operation. Both write-ahead loggers and append-only databases * require periodic checkpointing and/or compaction of their log or database  Howard Chu committed Jun 24, 2014 32  * files otherwise they grow without bound. LMDB tracks free pages within  Howard Chu committed Sep 01, 2011 33 34 35  * the database and re-uses them for new write operations, so the database * size does not grow without bound in normal use. *  Howard Chu committed Sep 07, 2012 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 committed Dec 19, 2015 43 44 45  * If this is your first time using a transactional embedded key/value * store, you may find the \ref starting page to be helpful. *  Howard Chu committed Nov 28, 2012 46  * @section caveats_sec Caveats  Hallvard Furuseth committed Oct 03, 2012 47 48 49 50 51 52 53  * 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. *  Howard Chu committed Aug 20, 2013 54  * Fix: Check for stale readers periodically, using the  Hallvard Furuseth committed Oct 25, 2015 55 56 57 58 59 60 61  * #mdb_reader_check function or the \ref mdb_stat_1 "mdb_stat" tool. * Stale writers will be cleared automatically on some systems: * - Windows - automatic * - Linux, systems using POSIX mutexes with Robust option - automatic * - not on BSD, systems using POSIX semaphores. * Otherwise just make all programs using the database close it; * the lockfile is always reset on first open of the environment.  Hallvard Furuseth committed Oct 03, 2012 62 63 64 65 66 67 68 69 70 71 72 73 74 75  * * - 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. *  Hallvard Furuseth committed Oct 04, 2013 76 77 78 79  * - 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(). *  Hallvard Furuseth committed Jun 15, 2016 80 81 82 83 84  * - An LMDB configuration will often reserve considerable \b unused * memory address space and maybe file size for future growth. * This does not use actual memory or disk space, but users may need * to understand the difference so they won't be scared off. *  Howard Chu committed Nov 11, 2013 85 86  * - 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 committed Nov 11, 2013 87  * (This does not happen when using the #MDB_WRITEMAP flag.) As of  Howard Chu committed Nov 11, 2013 88 89 90 91  * 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 committed Nov 11, 2013 92 93  * which must not be written should not use this flag. This flag is * irrelevant when using #MDB_WRITEMAP.  Hallvard Furuseth committed Nov 07, 2013 94  *  Hallvard Furuseth committed Oct 03, 2012 95 96  * - A thread can only use one transaction at a time, plus any child * transactions. Each transaction belongs to one thread. See below.  Howard Chu committed Apr 18, 2013 97  * The #MDB_NOTLS flag changes this for read-only transactions.  Hallvard Furuseth committed Oct 03, 2012 98  *  Hallvard Furuseth committed Dec 15, 2016 99  * - Use an MDB_env* in the process which opened it, not after fork().  Hallvard Furuseth committed Oct 03, 2012 100  *  Howard Chu committed Jun 24, 2014 101  * - Do not have open an LMDB database twice in the same process at  Hallvard Furuseth committed Oct 03, 2012 102  * the same time. Not even from a plain open() call - close()ing it  Hallvard Furuseth committed Dec 15, 2016 103 104  * breaks fcntl() advisory locking. (It is OK to reopen it after * fork() - exec*(), since the lockfile has FD_CLOEXEC set.)  Hallvard Furuseth committed Oct 03, 2012 105 106 107 108 109 110 111  * * - 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  Hallvard Furuseth committed Jan 16, 2013 112 113 114 115  * 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:  Hallvard Furuseth committed Oct 03, 2012 116 117  * * - Avoid aborting a process with an active transaction.  Howard Chu committed Aug 20, 2013 118 119 120  * 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.  Hallvard Furuseth committed Oct 03, 2012 121  *  Hallvard Furuseth committed Oct 25, 2015 122 123 124  * This does not apply to write transactions if the system clears * stale writers, see above. *  Howard Chu committed Aug 20, 2013 125 126  * - 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.  Hallvard Furuseth committed Oct 03, 2012 127  *  Howard Chu committed Jun 24, 2014 128  * - Do not use LMDB databases on remote filesystems, even between  Hallvard Furuseth committed Oct 03, 2012 129 130 131  * processes on the same host. This breaks flock() on some OSes, * possibly memory map sync, and certainly sync between programs * on different hosts.  Hallvard Furuseth committed Oct 03, 2012 132 133 134 135  * * - Opening a database can fail if another process is opening or * closing it at exactly the same time. *  Howard Chu committed Sep 01, 2011 136 137  * @author Howard Chu, Symas Corporation. *  Quanah Gibson-Mount committed Jan 11, 2021 138  * @copyright Copyright 2011-2021 Howard Chu, Symas Corp. All rights reserved.  Howard Chu committed Sep 01, 2011 139 140 141 142 143 144 145 146 147  * * 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 * . *  Howard Chu committed Nov 28, 2012 148  * @par Derived From:  Howard Chu committed Sep 01, 2011 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164  * This code is derived from btree.c written by Martin Hedenfalk. * * Copyright (c) 2009, 2010 Martin Hedenfalk * * 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 committed Nov 30, 2012 165 166 #ifndef _LMDB_H_ #define _LMDB_H_  Howard Chu committed Jun 27, 2011 167 168 169  #include  Hallvard Furuseth committed Apr 12, 2012 170 171 172 173 #ifdef __cplusplus extern "C" { #endif  Hallvard Furuseth committed Aug 05, 2013 174 /** Unix permissions for creating files, or dummy definition for Windows */  Howard Chu committed Mar 31, 2013 175 #ifdef _MSC_VER  Howard Chu committed Mar 31, 2013 176 177 178 typedef int mdb_mode_t; #else typedef mode_t mdb_mode_t;  Howard Chu committed Mar 31, 2013 179 180 #endif  Howard Chu committed May 30, 2013 181 182 183 184 185 186 187 188 /** 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 committed May 30, 2013 189 190 #endif  Howard Chu committed Jun 24, 2014 191 /** @defgroup mdb LMDB API  Howard Chu committed Sep 03, 2011 192  * @{  Howard Chu committed Nov 30, 2012 193  * @brief OpenLDAP Lightning Memory-Mapped Database Manager  Howard Chu committed Sep 03, 2011 194  */  Howard Chu committed Sep 01, 2011 195 196 197 198 /** @defgroup Version Version Macros * @{ */ /** Library major version */  Howard Chu committed Sep 01, 2011 199 #define MDB_VERSION_MAJOR 0  Howard Chu committed Sep 01, 2011 200 /** Library minor version */  Howard Chu committed Sep 02, 2011 201 #define MDB_VERSION_MINOR 9  Howard Chu committed Sep 01, 2011 202 /** Library patch version */  Quanah Gibson-Mount committed Feb 04, 2021 203 #define MDB_VERSION_PATCH 28  Howard Chu committed Sep 01, 2011 204 205  /** Combine args a,b,c into a single integer for easy version comparisons */  Hallvard Furuseth committed Sep 01, 2011 206 #define MDB_VERINT(a,b,c) (((a) << 24) | ((b) << 16) | (c))  Howard Chu committed Sep 01, 2011 207 208  /** The full library version as a single integer */  Howard Chu committed Sep 01, 2011 209 210 #define MDB_VERSION_FULL \ MDB_VERINT(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH)  Howard Chu committed Sep 01, 2011 211 212  /** The release date of this library version */  Quanah Gibson-Mount committed Feb 04, 2021 213 #define MDB_VERSION_DATE "February 4, 2020"  Howard Chu committed Sep 01, 2011 214 215  /** A stringifier for the version info */  Howard Chu committed Jun 20, 2014 216 #define MDB_VERSTR(a,b,c,d) "LMDB " #a "." #b "." #c ": (" d ")"  Howard Chu committed Sep 01, 2011 217 218  /** A helper for the stringifier macro */  Howard Chu committed Sep 01, 2011 219 #define MDB_VERFOO(a,b,c,d) MDB_VERSTR(a,b,c,d)  Howard Chu committed Sep 01, 2011 220 221  /** The full library version as a C string */  Howard Chu committed Sep 01, 2011 222 223 #define MDB_VERSION_STRING \ MDB_VERFOO(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH,MDB_VERSION_DATE)  Howard Chu committed Sep 01, 2011 224 /** @} */  Howard Chu committed Sep 01, 2011 225   Howard Chu committed Sep 21, 2011 226 227 228 229 /** @brief Opaque structure for a database environment. * * A DB environment supports multiple databases, all residing in the same * shared-memory map.  Howard Chu committed Sep 02, 2011 230 231  */ typedef struct MDB_env MDB_env;  Howard Chu committed Sep 01, 2011 232   Howard Chu committed Sep 21, 2011 233 234 235 236 /** @brief Opaque structure for a transaction handle. * * All database operations require a transaction handle. Transactions may be * read-only or read-write.  Howard Chu committed Sep 01, 2011 237  */  Howard Chu committed Jun 27, 2011 238 typedef struct MDB_txn MDB_txn;  Howard Chu committed Sep 01, 2011 239   Howard Chu committed Sep 21, 2011 240 /** @brief A handle for an individual database in the DB environment. */  Howard Chu committed Sep 01, 2011 241 242 typedef unsigned int MDB_dbi;  Howard Chu committed Sep 21, 2011 243 /** @brief Opaque structure for navigating through a database */  Howard Chu committed Sep 02, 2011 244 245 typedef struct MDB_cursor MDB_cursor;  Hallvard Furuseth committed Feb 19, 2013 246 247 248 /** @brief Generic structure used for passing keys and data in and out * of the database. *  Hallvard Furuseth committed May 04, 2013 249  * Values returned from the database are valid only until a subsequent  Hallvard Furuseth committed Sep 23, 2013 250 251 252 253 254 255  * 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.  Hallvard Furuseth committed Feb 19, 2013 256  */  Howard Chu committed Jun 27, 2011 257 typedef struct MDB_val {  Howard Chu committed Sep 01, 2011 258 259  size_t mv_size; /**< size of the data item */ void *mv_data; /**< address of the data item */  Howard Chu committed Jun 27, 2011 260 261 } MDB_val;  Howard Chu committed Sep 21, 2011 262 /** @brief A callback function used to compare two keys in a database */  Howard Chu committed Jun 27, 2011 263 typedef int (MDB_cmp_func)(const MDB_val *a, const MDB_val *b);  Howard Chu committed Sep 01, 2011 264   Howard Chu committed Sep 21, 2011 265 266 267 268 /** @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  Howard Chu committed Sep 12, 2011 269 270 271  * 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 committed Sep 02, 2011 272  * values based at the \b oldptr address to be relative to the \b newptr address.  Howard Chu committed Sep 12, 2011 273 274 275 276  * @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 committed Sep 02, 2011 277  * @todo This feature is currently unimplemented.  Howard Chu committed Sep 01, 2011 278  */  Howard Chu committed Sep 12, 2011 279 typedef void (MDB_rel_func)(MDB_val *item, void *oldptr, void *newptr, void *relctx);  Howard Chu committed Sep 02, 2011 280   Howard Chu committed Sep 04, 2011 281 /** @defgroup mdb_env Environment Flags  Howard Chu committed Sep 02, 2011 282 283  * @{ */  Hallvard Furuseth committed Jan 16, 2013 284  /** mmap at a fixed address (experimental) */  Howard Chu committed Sep 02, 2011 285 #define MDB_FIXEDMAP 0x01  Howard Chu committed Sep 22, 2011 286  /** no environment directory */  Hallvard Furuseth committed Nov 28, 2012 287 #define MDB_NOSUBDIR 0x4000  Howard Chu committed Sep 02, 2011 288 289 290 291  /** don't fsync after commit */ #define MDB_NOSYNC 0x10000 /** read only */ #define MDB_RDONLY 0x20000  Howard Chu committed Jul 05, 2012 292 293  /** don't fsync metapage after commit */ #define MDB_NOMETASYNC 0x40000  Howard Chu committed Sep 05, 2012 294 295  /** use writable mmap */ #define MDB_WRITEMAP 0x80000  Howard Chu committed Oct 01, 2013 296  /** use asynchronous msync when #MDB_WRITEMAP is used */  Howard Chu committed Sep 06, 2012 297 #define MDB_MAPASYNC 0x100000  Howard Chu committed Apr 18, 2013 298 299  /** tie reader locktable slots to #MDB_txn objects instead of to threads */ #define MDB_NOTLS 0x200000  Howard Chu committed Oct 03, 2013 300 301  /** don't do any locking, caller must manage their own locks */ #define MDB_NOLOCK 0x400000  Howard Chu committed Oct 12, 2013 302 303  /** don't do readahead (no effect on Windows) */ #define MDB_NORDAHEAD 0x800000  Howard Chu committed Nov 11, 2013 304 305  /** don't initialize malloc'd memory before writing to datafile */ #define MDB_NOMEMINIT 0x1000000  Howard Chu committed Sep 02, 2011 306 307 /** @} */  Howard Chu committed Dec 03, 2012 308 /** @defgroup mdb_dbi_open Database Flags  Howard Chu committed Sep 02, 2011 309 310 311 312 313 314  * @{ */ /** use reverse string keys */ #define MDB_REVERSEKEY 0x02 /** use sorted duplicates */ #define MDB_DUPSORT 0x04  Hallvard Furuseth committed May 28, 2015 315  /** numeric keys in native byte order: either unsigned int or size_t.  Howard Chu committed Sep 09, 2011 316  * The keys must all be of the same size. */  Howard Chu committed Sep 02, 2011 317 318 319 #define MDB_INTEGERKEY 0x08 /** with #MDB_DUPSORT, sorted dup items have fixed size */ #define MDB_DUPFIXED 0x10  Hallvard Furuseth committed May 28, 2015 320  /** with #MDB_DUPSORT, dups are #MDB_INTEGERKEY-style integers */  Howard Chu committed Sep 02, 2011 321 #define MDB_INTEGERDUP 0x20  Howard Chu committed Sep 05, 2011 322 323  /** with #MDB_DUPSORT, use reverse string dups */ #define MDB_REVERSEDUP 0x40  Howard Chu committed Sep 02, 2011 324 325 326  /** create DB if not already existing */ #define MDB_CREATE 0x40000 /** @} */  Howard Chu committed Jun 27, 2011 327   Howard Chu committed Sep 04, 2011 328 /** @defgroup mdb_put Write Flags  Howard Chu committed Sep 01, 2011 329 330  * @{ */  Howard Chu committed Sep 04, 2011 331 /** For put: Don't write if the key already exists. */  Howard Chu committed Sep 01, 2011 332 #define MDB_NOOVERWRITE 0x10  Howard Chu committed Sep 04, 2011 333 334 335 /** Only for #MDB_DUPSORT
* For put: don't write if the key and data pair already exist.
* For mdb_cursor_del: remove all duplicate data items.  Howard Chu committed Sep 01, 2011 336  */  Howard Chu committed Sep 01, 2011 337 #define MDB_NODUPDATA 0x20  Howard Chu committed Sep 04, 2011 338 339 /** For mdb_cursor_put: overwrite the current key/data pair */ #define MDB_CURRENT 0x40  Howard Chu committed Oct 02, 2011 340 341 342 343 /** For put: Just reserve space for data, don't copy it. Return a * pointer to the reserved space. */ #define MDB_RESERVE 0x10000  Howard Chu committed Oct 02, 2011 344 345 /** Data is being appended, don't split full pages. */ #define MDB_APPEND 0x20000  Howard Chu committed Jul 21, 2012 346 347 /** Duplicate data is being appended, don't split full pages. */ #define MDB_APPENDDUP 0x40000  Howard Chu committed Jul 02, 2013 348 /** Store multiple data items in one call. Only for #MDB_DUPFIXED. */  Howard Chu committed Jul 21, 2012 349 #define MDB_MULTIPLE 0x80000  Howard Chu committed Sep 01, 2011 350 351 /* @} */  Howard Chu committed Jul 05, 2014 352 353 354 355 356 357 358 359 360 /** @defgroup mdb_copy Copy Flags * @{ */ /** Compacting copy: Omit free space from copy, and renumber all * pages sequentially. */ #define MDB_CP_COMPACT 0x01 /* @} */  Howard Chu committed Sep 21, 2011 361 362 /** @brief Cursor Get operations. *  Howard Chu committed Sep 12, 2011 363 364 365  * This is the set of all operations for retrieving data * using a cursor. */  Howard Chu committed Sep 01, 2011 366 367 typedef enum MDB_cursor_op { MDB_FIRST, /**< Position at first key/data item */  Howard Chu committed Sep 04, 2011 368 369  MDB_FIRST_DUP, /**< Position at first data item of current key. Only for #MDB_DUPSORT */  Howard Chu committed Sep 01, 2011 370 371  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 committed Sep 19, 2012 372  MDB_GET_CURRENT, /**< Return key/data at current cursor position */  Howard Chu committed Sep 10, 2018 373  MDB_GET_MULTIPLE, /**< Return up to a page of duplicate data items  Hallvard Furuseth committed Jun 18, 2014 374 375  from current cursor position. Move cursor to prepare for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */  Howard Chu committed Sep 01, 2011 376  MDB_LAST, /**< Position at last key/data item */  Howard Chu committed Sep 04, 2011 377 378  MDB_LAST_DUP, /**< Position at last data item of current key. Only for #MDB_DUPSORT */  Howard Chu committed Sep 01, 2011 379 380 381  MDB_NEXT, /**< Position at next data item */ MDB_NEXT_DUP, /**< Position at next data item of current key. Only for #MDB_DUPSORT */  Howard Chu committed Sep 10, 2018 382  MDB_NEXT_MULTIPLE, /**< Return up to a page of duplicate data items  Hallvard Furuseth committed Jun 18, 2014 383 384  from next cursor position. Move cursor to prepare for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */  Hallvard Furuseth committed May 21, 2013 385  MDB_NEXT_NODUP, /**< Position at first data item of next key */  Howard Chu committed Sep 01, 2011 386 387 388  MDB_PREV, /**< Position at previous data item */ MDB_PREV_DUP, /**< Position at previous data item of current key. Only for #MDB_DUPSORT */  Hallvard Furuseth committed May 21, 2013 389  MDB_PREV_NODUP, /**< Position at last data item of previous key */  Howard Chu committed Sep 01, 2011 390  MDB_SET, /**< Position at specified key */  Howard Chu committed Sep 17, 2012 391  MDB_SET_KEY, /**< Position at specified key, return key + data */  Howard Chu committed Dec 15, 2016 392  MDB_SET_RANGE, /**< Position at first key greater than or equal to specified key. */  Howard Chu committed Sep 10, 2018 393  MDB_PREV_MULTIPLE /**< Position at previous page and return up to  Howard Chu committed Dec 15, 2016 394  a page of duplicate data items. Only for #MDB_DUPFIXED */  Howard Chu committed Jun 27, 2011 395 396 } MDB_cursor_op;  Howard Chu committed Sep 01, 2011 397 398 399 400 401 402 /** @defgroup errors Return Codes * * BerkeleyDB uses -30800 to -30999, we'll go under them * @{ */ /** Successful result */  Howard Chu committed Jun 27, 2011 403 #define MDB_SUCCESS 0  Howard Chu committed Sep 01, 2011 404 405 406 407 408 409 410 411  /** 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)  Hallvard Furuseth committed Oct 25, 2015 412  /** Update of meta page failed or environment had fatal error */  Howard Chu committed Sep 01, 2011 413 414 415 #define MDB_PANIC (-30795) /** Environment version mismatch */ #define MDB_VERSION_MISMATCH (-30794)  Howard Chu committed Jun 24, 2014 416  /** File is not a valid LMDB file */  Howard Chu committed Sep 14, 2012 417 418 419 420 421 422 423 424 425 #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)  Howard Chu committed Jan 11, 2013 426  /** Txn has too many dirty pages */  Howard Chu committed Sep 14, 2012 427 428 429 430 431 #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)  Howard Chu committed Jul 23, 2014 432  /** Database contents grew beyond environment mapsize */  Hallvard Furuseth committed Feb 16, 2013 433 #define MDB_MAP_RESIZED (-30785)  Hallvard Furuseth committed Jul 28, 2015 434 435 436 437 438 439 440 441  /** Operation and DB incompatible, or DB type changed. This can mean: *
*
• The operation expects an #MDB_DUPSORT / #MDB_DUPFIXED database. *
• Opening a named DB when the unnamed DB has #MDB_DUPSORT / #MDB_INTEGERKEY. *
• Accessing a data record as a database, or vice versa. *
• The database was dropped and recreated with different flags. *
*/  Hallvard Furuseth committed Feb 19, 2013 442 #define MDB_INCOMPATIBLE (-30784)  Hallvard Furuseth committed Apr 18, 2013 443 444  /** Invalid reuse of reader locktable slot */ #define MDB_BAD_RSLOT (-30783)  Hallvard Furuseth committed Oct 25, 2015 445  /** Transaction must abort, has a child, or is invalid */  Hallvard Furuseth committed Aug 09, 2013 446 #define MDB_BAD_TXN (-30782)  Hallvard Furuseth committed May 30, 2014 447  /** Unsupported size of key/DB name/data, or wrong DUPFIXED size */  Hallvard Furuseth committed Aug 09, 2013 448 #define MDB_BAD_VALSIZE (-30781)  Howard Chu committed Jul 08, 2014 449 450 451 452  /** The specified DBI was changed unexpectedly */ #define MDB_BAD_DBI (-30780) /** The last defined error code */ #define MDB_LAST_ERRCODE MDB_BAD_DBI  Howard Chu committed Sep 01, 2011 453 454 /** @} */  Howard Chu committed Sep 21, 2011 455 /** @brief Statistics for a database in the environment */  Howard Chu committed Jun 27, 2011 456 typedef struct MDB_stat {  Howard Chu committed Sep 01, 2011 457 458 459  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 */  Hallvard Furuseth committed Sep 10, 2011 460 461 462 463  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 committed Jun 27, 2011 464 465 } MDB_stat;  Howard Chu committed Oct 16, 2012 466 467 /** @brief Information about the environment */ typedef struct MDB_envinfo {  Howard Chu committed Oct 16, 2012 468  void *me_mapaddr; /**< Address of map, if fixed */  Howard Chu committed Oct 16, 2012 469 470  size_t me_mapsize; /**< Size of the data memory map */ size_t me_last_pgno; /**< ID of the last used page */  Howard Chu committed Oct 16, 2012 471  size_t me_last_txnid; /**< ID of the last committed transaction */  Howard Chu committed Apr 18, 2013 472 473  unsigned int me_maxreaders; /**< max reader slots in the environment */ unsigned int me_numreaders; /**< max reader slots used in the environment */  Howard Chu committed Oct 16, 2012 474 475 } MDB_envinfo;  Howard Chu committed Jun 24, 2014 476  /** @brief Return the LMDB library version information.  Howard Chu committed Sep 21, 2011 477  *  Howard Chu committed Sep 01, 2011 478 479 480 481 482  * @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 committed Sep 01, 2011 483 char *mdb_version(int *major, int *minor, int *patch);  Howard Chu committed Sep 01, 2011 484   Howard Chu committed Sep 21, 2011 485 486  /** @brief Return a string describing a given error code. *  Howard Chu committed Sep 01, 2011 487 488 489  * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) * function. If the error code is greater than or equal to 0, then the string * returned by the system function strerror(3) is returned. If the error code  Howard Chu committed Jun 24, 2014 490 491  * is less than 0, an error string corresponding to the LMDB library error is * returned. See @ref errors for a list of LMDB-specific error codes.  Howard Chu committed Sep 01, 2011 492 493 494  * @param[in] err The error code * @retval "error message" The description of the error */  Howard Chu committed Sep 01, 2011 495 char *mdb_strerror(int err);  Howard Chu committed Sep 01, 2011 496   Howard Chu committed Jun 24, 2014 497  /** @brief Create an LMDB environment handle.  Howard Chu committed Sep 21, 2011 498  *  Howard Chu committed Sep 01, 2011 499 500 501 502 503 504 505 506 507  * 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 committed Sep 01, 2011 508 int mdb_env_create(MDB_env **env);  Howard Chu committed Sep 01, 2011 509   Howard Chu committed Sep 21, 2011 510 511  /** @brief Open an environment handle. *  Howard Chu committed Sep 01, 2011 512 513  * 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 committed Sep 02, 2011 514 515  * @param[in] path The directory in which the database files reside. This * directory must already exist and be writable.  Howard Chu committed Sep 01, 2011 516 517 518  * @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.  Hallvard Furuseth committed Oct 15, 2012 519  * Flags set by mdb_env_set_flags() are also used.  Howard Chu committed Sep 01, 2011 520 521 522 523 524 525 526 527 528  *
*
• #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.  Howard Chu committed Sep 22, 2011 529  *
• #MDB_NOSUBDIR  Howard Chu committed Jun 24, 2014 530  * By default, LMDB creates its environment in a directory whose  Howard Chu committed Sep 22, 2011 531 532 533 534  * 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.  Howard Chu committed Sep 01, 2011 535  *
• #MDB_RDONLY  Hallvard Furuseth committed Jan 16, 2013 536  * Open the environment in read-only mode. No write operations will be  Howard Chu committed Jun 24, 2014 537 538  * allowed. LMDB will still modify the lock file - except on read-only * filesystems, where LMDB does not use locks.  Hallvard Furuseth committed Jan 16, 2013 539  *
• #MDB_WRITEMAP  Howard Chu committed Jan 23, 2016 540 541  * Use a writeable memory map unless MDB_RDONLY is set. This uses * fewer mallocs but loses protection from application bugs  Hallvard Furuseth committed Jan 16, 2013 542  * like wild pointer writes and other bad updates into the database.  Howard Chu committed Jan 23, 2016 543 544  * This may be slightly faster for DBs that fit entirely in RAM, but * is slower for DBs larger than RAM.  Hallvard Furuseth committed Jan 16, 2013 545  * Incompatible with nested transactions.  Hallvard Furuseth committed Jan 12, 2015 546 547  * Do not mix processes with and without MDB_WRITEMAP on the same * environment. This can defeat durability (#mdb_env_sync etc).  Hallvard Furuseth committed Jan 16, 2013 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575  *
• #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(). *
• #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(). *
• #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 committed Apr 18, 2013 576 577 578 579 580 581 582 583  *
• #MDB_NOTLS * Don't use Thread-Local Storage. Tie reader locktable slots to * #MDB_txn objects instead of to threads. I.e. #mdb_txn_reset() keeps * the slot reseved for the #MDB_txn object. A thread may use parallel * read-only transactions. A read-only transaction may span threads if * the user synchronizes its use. Applications that multiplex many * user threads over individual OS threads need this option. Such an * application must also serialize the write transactions in an OS  Howard Chu committed Jun 24, 2014 584  * thread, since LMDB's write locking is unaware of the user threads.  Howard Chu committed Oct 03, 2013 585 586 587 588 589 590 591  *
• #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.  Howard Chu committed Oct 12, 2013 592 593 594 595 596 597  *
• #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 committed Nov 11, 2013 598 599 600 601 602 603 604 605 606  *
• #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 committed Nov 12, 2013 607 608  * 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 committed Nov 11, 2013 609 610 611 612  * 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 committed Nov 07, 2013 613 614 615 616  * 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().  Howard Chu committed Sep 01, 2011 617  *
 Hallvard Furuseth committed Jun 02, 2015 618 619  * @param[in] mode The UNIX permissions to set on created files and semaphores. * This parameter is ignored on Windows.  Howard Chu committed Sep 01, 2011 620 621 622  * @return A non-zero error value on failure and 0 on success. Some possible * errors are: *
 Howard Chu committed Jun 24, 2014 623  *
• #MDB_VERSION_MISMATCH - the version of the LMDB library doesn't match the  Howard Chu committed Sep 01, 2011 624  * version that created the database environment.  Howard Chu committed Feb 20, 2013 625  *
• #MDB_INVALID - the environment file headers are corrupted.  Howard Chu committed Sep 01, 2011 626 627 628 629 630  *
• ENOENT - the directory specified by the path parameter doesn't exist. *
• EACCES - the user didn't have permission to access the environment files. *
• EAGAIN - the environment was locked by another process. *
*/  Howard Chu committed Mar 31, 2013 631 int mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mdb_mode_t mode);  Howard Chu committed Sep 01, 2011 632   Howard Chu committed Jun 24, 2014 633  /** @brief Copy an LMDB environment to the specified path.  Howard Chu committed Oct 11, 2012 634 635  * * This function may be used to make a backup of an existing environment.  Hallvard Furuseth committed Aug 05, 2013 636 637 638 639  * 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 committed Oct 11, 2012 640 641 642 643 644 645 646 647 648  * @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 committed Jun 24, 2014 649  /** @brief Copy an LMDB environment to the specified file descriptor.  Howard Chu committed May 30, 2013 650 651  * * This function may be used to make a backup of an existing environment.  Hallvard Furuseth committed Aug 05, 2013 652 653 654 655  * 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 committed May 30, 2013 656 657 658 659 660 661  * @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. */  Howard Chu committed May 30, 2013 662 int mdb_env_copyfd(MDB_env *env, mdb_filehandle_t fd);  Howard Chu committed May 30, 2013 663   Howard Chu committed Jul 05, 2014 664  /** @brief Copy an LMDB environment to the specified path, with options.  Howard Chu committed Jul 01, 2014 665 666  * * This function may be used to make a backup of an existing environment.  Howard Chu committed Jul 05, 2014 667  * No lockfile is created, since it gets recreated at need.  Howard Chu committed Jul 01, 2014 668 669 670 671 672 673 674 675  * @note This call can trigger significant file size growth if run in * parallel with write transactions, because it employs a read-only * transaction. See long-lived transactions under @ref caveats_sec. * @param[in] env An environment handle returned by #mdb_env_create(). It * must have already been opened successfully. * @param[in] path The directory in which the copy will reside. This * directory must already exist and be writable but must otherwise be * empty.  Howard Chu committed Jul 05, 2014 676 677 678 679 680 681 682  * @param[in] flags Special options for this operation. This parameter * must be set to 0 or by bitwise OR'ing together one or more of the * values described here. *
*
• #MDB_CP_COMPACT - Perform compaction while copying: omit free * pages and sequentially renumber all pages in output. This option * consumes more CPU and runs more slowly than the default.  Hallvard Furuseth committed Dec 15, 2016 683  * Currently it fails if the environment has suffered a page leak.  Howard Chu committed Jul 05, 2014 684  *
 Howard Chu committed Jul 01, 2014 685 686  * @return A non-zero error value on failure and 0 on success. */  Howard Chu committed Jul 05, 2014 687 int mdb_env_copy2(MDB_env *env, const char *path, unsigned int flags);  Howard Chu committed Jul 01, 2014 688 689  /** @brief Copy an LMDB environment to the specified file descriptor,  Howard Chu committed Jul 05, 2014 690  * with options.  Howard Chu committed Jul 01, 2014 691 692 693 694 695 696 697 698 699 700 701  * * This function may be used to make a backup of an existing environment. * No lockfile is created, since it gets recreated at need. See * #mdb_env_copy2() for further details. * @note This call can trigger significant file size growth if run in * parallel with write transactions, because it employs a read-only * transaction. See long-lived transactions under @ref caveats_sec. * @param[in] env An environment handle returned by #mdb_env_create(). It * must have already been opened successfully. * @param[in] fd The filedescriptor to write the copy to. It must * have already been opened for Write access.  Howard Chu committed Jul 05, 2014 702 703  * @param[in] flags Special options for this operation. * See #mdb_env_copy2() for options.  Howard Chu committed Jul 01, 2014 704 705  * @return A non-zero error value on failure and 0 on success. */  Howard Chu committed Jul 05, 2014 706 int mdb_env_copyfd2(MDB_env *env, mdb_filehandle_t fd, unsigned int flags);  Howard Chu committed Jul 01, 2014 707   Howard Chu committed Jun 24, 2014 708  /** @brief Return statistics about the LMDB environment.  Howard Chu committed Sep 21, 2011 709  *  Howard Chu committed Sep 01, 2011 710 711 712 713  * @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 committed Sep 01, 2011 714 int mdb_env_stat(MDB_env *env, MDB_stat *stat);  Howard Chu committed Sep 01, 2011 715   Howard Chu committed Jun 24, 2014 716  /** @brief Return information about the LMDB environment.  Howard Chu committed Oct 16, 2012 717 718 719 720 721 722 723  * * @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);  Howard Chu committed Sep 21, 2011 724 725  /** @brief Flush the data buffers to disk. *  Howard Chu committed Sep 01, 2011 726  * Data is always written to disk when #mdb_txn_commit() is called,  Howard Chu committed Jun 24, 2014 727  * but the operating system may keep it buffered. LMDB always flushes  Howard Chu committed Sep 01, 2011 728  * the OS buffers upon commit as well, unless the environment was  Howard Chu committed Jan 09, 2015 729 730  * opened with #MDB_NOSYNC or in part #MDB_NOMETASYNC. This call is * not valid if the environment was opened with #MDB_RDONLY.  Howard Chu committed Sep 01, 2011 731  * @param[in] env An environment handle returned by #mdb_env_create()  Hallvard Furuseth committed Nov 28, 2012 732  * @param[in] force If non-zero, force a synchronous flush. Otherwise  Howard Chu committed Sep 01, 2011 733  * if the environment has the #MDB_NOSYNC flag set the flushes  Hallvard Furuseth committed Nov 28, 2012 734  * will be omitted, and with #MDB_MAPASYNC they will be asynchronous.  Howard Chu committed Sep 01, 2011 735 736 737  * @return A non-zero error value on failure and 0 on success. Some possible * errors are: *
 Howard Chu committed Jan 09, 2015 738  *
• EACCES - the environment is read-only.  Howard Chu committed Sep 01, 2011 739 740 741 742  *
• EINVAL - an invalid parameter was specified. *
• EIO - an error occurred during synchronization. *
*/  Howard Chu committed Sep 01, 2011 743 int mdb_env_sync(MDB_env *env, int force);  Howard Chu committed Sep 01, 2011 744   Howard Chu committed Sep 21, 2011 745 746  /** @brief Close the environment and release the memory map. *  Howard Chu committed Sep 01, 2011 747 748 749 750 751 752  * 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 committed Sep 01, 2011 753 void mdb_env_close(MDB_env *env);  Howard Chu committed Sep 01, 2011 754   Howard Chu committed Sep 21, 2011 755 756  /** @brief Set environment flags. *  Hallvard Furuseth committed Oct 15, 2012 757  * This may be used to set some flags in addition to those from  Hallvard Furuseth committed Mar 16, 2014 758 759  * #mdb_env_open(), or to unset these flags. If several threads * change the flags at the same time, the result is undefined.  Howard Chu committed Sep 01, 2011 760 761 762 763 764 765 766 767 768  * @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: *
*
• EINVAL - an invalid parameter was specified. *
*/  Howard Chu committed Sep 01, 2011 769 int mdb_env_set_flags(MDB_env *env, unsigned int flags, int onoff);  Howard Chu committed Sep 01, 2011 770   Howard Chu committed Sep 21, 2011 771 772  /** @brief Get environment flags. *  Howard Chu committed Sep 01, 2011 773 774 775 776 777 778 779 780  * @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: *
*
• EINVAL - an invalid parameter was specified. *
*/  Howard Chu committed Sep 01, 2011 781 int mdb_env_get_flags(MDB_env *env, unsigned int *flags);  Howard Chu committed Sep 01, 2011 782   Howard Chu committed Sep 21, 2011 783 784  /** @brief Return the path that was used in #mdb_env_open(). *  Howard Chu committed Sep 01, 2011 785 786 787 788 789 790 791 792 793 794  * @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: *
*
• EINVAL - an invalid parameter was specified. *
*/  Howard Chu committed Sep 01, 2011 795 int mdb_env_get_path(MDB_env *env, const char **path);  Howard Chu committed Sep 01, 2011 796   Howard Chu committed Oct 21, 2013 797  /** @brief Return the filedescriptor for the given environment.  Hallvard Furuseth committed Dec 15, 2016 798 799 800 801  * * This function may be called after fork(), so the descriptor can be * closed before exec*(). Other LMDB file descriptors have FD_CLOEXEC. * (Until LMDB 0.9.18, only the lockfile had that.)  Howard Chu committed Oct 21, 2013 802 803 804 805 806 807 808 809 810 811 812  * * @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: *
*
• EINVAL - an invalid parameter was specified. *
*/ int mdb_env_get_fd(MDB_env *env, mdb_filehandle_t *fd);  Howard Chu committed Sep 21, 2011 813 814  /** @brief Set the size of the memory map to use for this environment. *  Howard Chu committed Sep 01, 2011 815  * The size should be a multiple of the OS page size. The default is  Howard Chu committed Sep 02, 2011 816 817  * 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 committed Mar 03, 2012 818  * to accommodate future growth of the database.  Howard Chu committed Aug 28, 2013 819 820 821  * 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,  Howard Chu committed Jul 23, 2014 822  * the caller must ensure it explicitly.  Howard Chu committed Aug 28, 2013 823  *  Howard Chu committed Jul 23, 2014 824 825 826 827 828 829 830  * The new size takes effect immediately for the current process but * will not be persisted to any others until a write transaction has been * committed by the current process. Also, only mapsize increases are * persisted into the environment. * * If the mapsize is increased by another process, and data has grown * beyond the range of the current mapsize, #mdb_txn_begin() will  Howard Chu committed Aug 28, 2013 831 832 833  * return #MDB_MAP_RESIZED. This function may be called with a size * of zero to adopt the new size. *  Howard Chu committed Dec 11, 2012 834 835  * 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.  Howard Chu committed Sep 01, 2011 836 837 838 839 840  * @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: *
 Howard Chu committed Aug 28, 2013 841 842  *
• EINVAL - an invalid parameter was specified, or the environment has * an active write transaction.  Howard Chu committed Sep 01, 2011 843 844  *
*/  Howard Chu committed Sep 01, 2011 845 int mdb_env_set_mapsize(MDB_env *env, size_t size);  Howard Chu committed Sep 01, 2011 846   Howard Chu committed Apr 18, 2013 847  /** @brief Set the maximum number of threads/reader slots for the environment.  Howard Chu committed Sep 21, 2011 848  *  Howard Chu committed Sep 01, 2011 849 850  * 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 committed Apr 18, 2013 851 852 853 854  * 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.  Howard Chu committed Sep 01, 2011 855 856  * 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 committed Apr 18, 2013 857  * @param[in] readers The maximum number of reader lock table slots  Howard Chu committed Sep 01, 2011 858 859 860 861 862 863  * @return A non-zero error value on failure and 0 on success. Some possible * errors are: *
*
• EINVAL - an invalid parameter was specified, or the environment is already open. *
*/  Hallvard Furuseth committed Sep 10, 2011 864 int mdb_env_set_maxreaders(MDB_env *env, unsigned int readers);  Howard Chu committed Sep 01, 2011 865   Howard Chu committed Apr 18, 2013 866  /** @brief Get the maximum number of threads/reader slots for the environment.  Howard Chu committed Sep 21, 2011 867  *  Howard Chu committed Sep 01, 2011 868 869 870 871 872 873 874 875  * @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: *
*
• EINVAL - an invalid parameter was specified. *
*/  Hallvard Furuseth committed Sep 10, 2011 876 int mdb_env_get_maxreaders(MDB_env *env, unsigned int *readers);  Howard Chu committed Sep 01, 2011 877   Hallvard Furuseth committed Nov 28, 2012 878  /** @brief Set the maximum number of named databases for the environment.  Howard Chu committed Sep 21, 2011 879  *  Howard Chu committed Sep 01, 2011 880  * This function is only needed if multiple databases will be used in the  Hallvard Furuseth committed Nov 28, 2012 881 882  * environment. Simpler applications that use the environment as a single * unnamed database can ignore this option.  Howard Chu committed Sep 01, 2011 883  * This function may only be called after #mdb_env_create() and before #mdb_env_open().  Hallvard Furuseth committed May 30, 2014 884 885 886 887  * * Currently a moderate number of slots are cheap but a huge number gets * expensive: 7-120 words per transaction, and every #mdb_dbi_open() * does a linear search of the opened slots.  Howard Chu committed Sep 01, 2011 888 889 890 891 892 893 894 895  * @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: *
*
• EINVAL - an invalid parameter was specified, or the environment is already open. *
*/  Hallvard Furuseth committed Sep 11, 2011 896 int mdb_env_set_maxdbs(MDB_env *env, MDB_dbi dbs);  Howard Chu committed Jun 27, 2011 897   Hallvard Furuseth committed Dec 11, 2013 898  /** @brief Get the maximum size of keys and #MDB_DUPSORT data we can write.  Howard Chu committed Aug 09, 2013 899  *  Hallvard Furuseth committed Dec 11, 2013 900  * Depends on the compile-time constant #MDB_MAXKEYSIZE. Default 511.  Hallvard Furuseth committed Sep 23, 2013 901  * See @ref MDB_val.  Howard Chu committed Aug 09, 2013 902  * @param[in] env An environment handle returned by #mdb_env_create()  Hallvard Furuseth committed Dec 11, 2013 903  * @return The maximum size of a key we can write  Howard Chu committed Aug 09, 2013 904 905 906  */ int mdb_env_get_maxkeysize(MDB_env *env);  Hallvard Furuseth committed Jan 06, 2014 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921  /** @brief Set application information associated with the #MDB_env. * * @param[in] env An environment handle returned by #mdb_env_create() * @param[in] ctx An arbitrary pointer for whatever the application needs. * @return A non-zero error value on failure and 0 on success. */ int mdb_env_set_userctx(MDB_env *env, void *ctx); /** @brief Get the application information associated with the #MDB_env. * * @param[in] env An environment handle returned by #mdb_env_create() * @return The pointer set by #mdb_env_set_userctx(). */ void *mdb_env_get_userctx(MDB_env *env);  Howard Chu committed Jun 24, 2014 922  /** @brief A callback function for most LMDB assert() failures,  Hallvard Furuseth committed Jan 06, 2014 923 924 925 926 927 928 929 930 931 932 933  * called before printing the message and aborting. * * @param[in] env An environment handle returned by #mdb_env_create(). * @param[in] msg The assertion message, not including newline. */ typedef void MDB_assert_func(MDB_env *env, const char *msg); /** Set or reset the assert() callback of the environment. * Disabled if liblmdb is buillt with NDEBUG. * @note This hack should become obsolete as lmdb's error handling matures. * @param[in] env An environment handle returned by #mdb_env_create().  Hallvard Furuseth committed Mar 16, 2014 934  * @param[in] func An #MDB_assert_func function, or 0.  Hallvard Furuseth committed Jan 06, 2014 935 936 937 938  * @return A non-zero error value on failure and 0 on success. */ int mdb_env_set_assert(MDB_env *env, MDB_assert_func *func);  Howard Chu committed Sep 21, 2011 939 940  /** @brief Create a transaction for use with the environment. *  Howard Chu committed Sep 01, 2011 941  * The transaction handle may be discarded using #mdb_txn_abort() or #mdb_txn_commit().  Howard Chu committed Apr 18, 2013 942 943 944  * @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.  Hallvard Furuseth committed May 04, 2013 945  * @note Cursors may not span transactions.  Howard Chu committed Sep 01, 2011 946  * @param[in] env An environment handle returned by #mdb_env_create()  Howard Chu committed Sep 21, 2011 947 948 949  * @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  Hallvard Furuseth committed Aug 05, 2013 950 951  * transaction and its cursors may not issue any other operations than * mdb_txn_commit and mdb_txn_abort while it has active child transactions.  Howard Chu committed Sep 01, 2011 952 953 954 955 956 957 958 959 960 961 962 963  * @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. *
*
• #MDB_RDONLY * This transaction will not perform any write operations. *
* @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: *
*
• #MDB_PANIC - a fatal error occurred earlier and the environment  Howard Chu committed Apr 20, 2013 964  * must be shut down.  Hallvard Furuseth committed Feb 16, 2013 965  *
• #MDB_MAP_RESIZED - another process wrote data beyond this MDB_env's  Howard Chu committed Aug 28, 2013 966 967  * mapsize and this environment's map must be resized as well. * See #mdb_env_set_mapsize().  Howard Chu committed Feb 20, 2013 968  *
• #MDB_READERS_FULL - a read-only transaction was requested and  Howard Chu committed Sep 01, 2011 969  * the reader lock table is full. See #mdb_env_set_maxreaders().  Howard Chu committed Feb 20, 2013 970  *
• ENOMEM - out of memory.  Howard Chu committed Sep 01, 2011 971 972  *
*/  Howard Chu committed Sep 21, 2011 973 int mdb_txn_begin(MDB_env *env, MDB_txn *parent, unsigned int flags, MDB_txn **txn);  Howard Chu committed Sep 01, 2011 974   Salvador Ortiz committed Aug 10, 2013 975 976 977 978 979 980  /** @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);  David Barbour committed Oct 25, 2015 981 982 983 984 985 986 987 988 989 990 991  /** @brief Return the transaction's ID. * * This returns the identifier associated with this transaction. For a * read-only transaction, this corresponds to the snapshot being read; * concurrent readers will frequently have the same transaction ID. * * @param[in] txn A transaction handle returned by #mdb_txn_begin() * @return A transaction ID, valid if input is an active transaction. */ size_t mdb_txn_id(MDB_txn *txn);  Howard Chu committed Sep 21, 2011 992 993  /** @brief Commit all the operations of a transaction into the database. *  Hallvard Furuseth committed May 04, 2013 994 995 996 997  * 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.  Howard Chu committed Sep 01, 2011 998 999 1000  * @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: 
For faster browsing, not all history is shown.