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