1*cf1d77f7Schristos /* $NetBSD: lmdb.h,v 1.3 2021/08/14 16:14:57 christos Exp $ */ 233197c6aStron 333197c6aStron /** @file lmdb.h 433197c6aStron * @brief Lightning memory-mapped database library 533197c6aStron * 68bd9f7cdSchristos * @mainpage Lightning Memory-Mapped Database Manager (LMDB) 733197c6aStron * 833197c6aStron * @section intro_sec Introduction 98bd9f7cdSchristos * LMDB is a Btree-based database management library modeled loosely on the 1033197c6aStron * BerkeleyDB API, but much simplified. The entire database is exposed 1133197c6aStron * in a memory map, and all data fetches return data directly 1233197c6aStron * from the mapped memory, so no malloc's or memcpy's occur during 1333197c6aStron * data fetches. As such, the library is extremely simple because it 1433197c6aStron * requires no page caching layer of its own, and it is extremely high 1533197c6aStron * performance and memory-efficient. It is also fully transactional with 1633197c6aStron * full ACID semantics, and when the memory map is read-only, the 1733197c6aStron * database integrity cannot be corrupted by stray pointer writes from 1833197c6aStron * application code. 1933197c6aStron * 2033197c6aStron * The library is fully thread-aware and supports concurrent read/write 2133197c6aStron * access from multiple processes and threads. Data pages use a copy-on- 2233197c6aStron * write strategy so no active data pages are ever overwritten, which 2333197c6aStron * also provides resistance to corruption and eliminates the need of any 2433197c6aStron * special recovery procedures after a system crash. Writes are fully 2533197c6aStron * serialized; only one write transaction may be active at a time, which 2633197c6aStron * guarantees that writers can never deadlock. The database structure is 2733197c6aStron * multi-versioned so readers run with no locks; writers cannot block 2833197c6aStron * readers, and readers don't block writers. 2933197c6aStron * 3033197c6aStron * Unlike other well-known database mechanisms which use either write-ahead 318bd9f7cdSchristos * transaction logs or append-only data writes, LMDB requires no maintenance 3233197c6aStron * during operation. Both write-ahead loggers and append-only databases 3333197c6aStron * require periodic checkpointing and/or compaction of their log or database 348bd9f7cdSchristos * files otherwise they grow without bound. LMDB tracks free pages within 3533197c6aStron * the database and re-uses them for new write operations, so the database 3633197c6aStron * size does not grow without bound in normal use. 3733197c6aStron * 3833197c6aStron * The memory map can be used as a read-only or read-write map. It is 3933197c6aStron * read-only by default as this provides total immunity to corruption. 4033197c6aStron * Using read-write mode offers much higher write performance, but adds 4133197c6aStron * the possibility for stray application writes thru pointers to silently 4233197c6aStron * corrupt the database. Of course if your application code is known to 4333197c6aStron * be bug-free (...) then this is not an issue. 4433197c6aStron * 458bd9f7cdSchristos * If this is your first time using a transactional embedded key/value 468bd9f7cdSchristos * store, you may find the \ref starting page to be helpful. 478bd9f7cdSchristos * 4833197c6aStron * @section caveats_sec Caveats 4933197c6aStron * Troubleshooting the lock file, plus semaphores on BSD systems: 5033197c6aStron * 5133197c6aStron * - A broken lockfile can cause sync issues. 5233197c6aStron * Stale reader transactions left behind by an aborted program 5333197c6aStron * cause further writes to grow the database quickly, and 5433197c6aStron * stale locks can block further operation. 5533197c6aStron * 5633197c6aStron * Fix: Check for stale readers periodically, using the 578bd9f7cdSchristos * #mdb_reader_check function or the \ref mdb_stat_1 "mdb_stat" tool. 588bd9f7cdSchristos * Stale writers will be cleared automatically on some systems: 598bd9f7cdSchristos * - Windows - automatic 608bd9f7cdSchristos * - Linux, systems using POSIX mutexes with Robust option - automatic 618bd9f7cdSchristos * - not on BSD, systems using POSIX semaphores. 628bd9f7cdSchristos * Otherwise just make all programs using the database close it; 638bd9f7cdSchristos * the lockfile is always reset on first open of the environment. 6433197c6aStron * 6533197c6aStron * - On BSD systems or others configured with MDB_USE_POSIX_SEM, 6633197c6aStron * startup can fail due to semaphores owned by another userid. 6733197c6aStron * 6833197c6aStron * Fix: Open and close the database as the user which owns the 6933197c6aStron * semaphores (likely last user) or as root, while no other 7033197c6aStron * process is using the database. 7133197c6aStron * 7233197c6aStron * Restrictions/caveats (in addition to those listed for some functions): 7333197c6aStron * 7433197c6aStron * - Only the database owner should normally use the database on 7533197c6aStron * BSD systems or when otherwise configured with MDB_USE_POSIX_SEM. 7633197c6aStron * Multiple users can cause startup to fail later, as noted above. 7733197c6aStron * 7833197c6aStron * - There is normally no pure read-only mode, since readers need write 7933197c6aStron * access to locks and lock file. Exceptions: On read-only filesystems 8033197c6aStron * or with the #MDB_NOLOCK flag described under #mdb_env_open(). 8133197c6aStron * 8282bf52b1Schristos * - An LMDB configuration will often reserve considerable \b unused 8382bf52b1Schristos * memory address space and maybe file size for future growth. 8482bf52b1Schristos * This does not use actual memory or disk space, but users may need 8582bf52b1Schristos * to understand the difference so they won't be scared off. 8682bf52b1Schristos * 8733197c6aStron * - By default, in versions before 0.9.10, unused portions of the data 8833197c6aStron * file might receive garbage data from memory freed by other code. 8933197c6aStron * (This does not happen when using the #MDB_WRITEMAP flag.) As of 9033197c6aStron * 0.9.10 the default behavior is to initialize such memory before 9133197c6aStron * writing to the data file. Since there may be a slight performance 9233197c6aStron * cost due to this initialization, applications may disable it using 9333197c6aStron * the #MDB_NOMEMINIT flag. Applications handling sensitive data 9433197c6aStron * which must not be written should not use this flag. This flag is 9533197c6aStron * irrelevant when using #MDB_WRITEMAP. 9633197c6aStron * 9733197c6aStron * - A thread can only use one transaction at a time, plus any child 9833197c6aStron * transactions. Each transaction belongs to one thread. See below. 9933197c6aStron * The #MDB_NOTLS flag changes this for read-only transactions. 10033197c6aStron * 10182bf52b1Schristos * - Use an MDB_env* in the process which opened it, not after fork(). 10233197c6aStron * 1038bd9f7cdSchristos * - Do not have open an LMDB database twice in the same process at 10433197c6aStron * the same time. Not even from a plain open() call - close()ing it 10582bf52b1Schristos * breaks fcntl() advisory locking. (It is OK to reopen it after 10682bf52b1Schristos * fork() - exec*(), since the lockfile has FD_CLOEXEC set.) 10733197c6aStron * 10833197c6aStron * - Avoid long-lived transactions. Read transactions prevent 10933197c6aStron * reuse of pages freed by newer write transactions, thus the 11033197c6aStron * database can grow quickly. Write transactions prevent 11133197c6aStron * other write transactions, since writes are serialized. 11233197c6aStron * 11333197c6aStron * - Avoid suspending a process with active transactions. These 11433197c6aStron * would then be "long-lived" as above. Also read transactions 11533197c6aStron * suspended when writers commit could sometimes see wrong data. 11633197c6aStron * 11733197c6aStron * ...when several processes can use a database concurrently: 11833197c6aStron * 11933197c6aStron * - Avoid aborting a process with an active transaction. 12033197c6aStron * The transaction becomes "long-lived" as above until a check 12133197c6aStron * for stale readers is performed or the lockfile is reset, 12233197c6aStron * since the process may not remove it from the lockfile. 12333197c6aStron * 1248bd9f7cdSchristos * This does not apply to write transactions if the system clears 1258bd9f7cdSchristos * stale writers, see above. 1268bd9f7cdSchristos * 12733197c6aStron * - If you do that anyway, do a periodic check for stale readers. Or 12833197c6aStron * close the environment once in a while, so the lockfile can get reset. 12933197c6aStron * 1308bd9f7cdSchristos * - Do not use LMDB databases on remote filesystems, even between 13133197c6aStron * processes on the same host. This breaks flock() on some OSes, 13233197c6aStron * possibly memory map sync, and certainly sync between programs 13333197c6aStron * on different hosts. 13433197c6aStron * 13533197c6aStron * - Opening a database can fail if another process is opening or 13633197c6aStron * closing it at exactly the same time. 13733197c6aStron * 13833197c6aStron * @author Howard Chu, Symas Corporation. 13933197c6aStron * 140*cf1d77f7Schristos * @copyright Copyright 2011-2021 Howard Chu, Symas Corp. All rights reserved. 14133197c6aStron * 14233197c6aStron * Redistribution and use in source and binary forms, with or without 14333197c6aStron * modification, are permitted only as authorized by the OpenLDAP 14433197c6aStron * Public License. 14533197c6aStron * 14633197c6aStron * A copy of this license is available in the file LICENSE in the 14733197c6aStron * top-level directory of the distribution or, alternatively, at 14833197c6aStron * <http://www.OpenLDAP.org/license.html>. 14933197c6aStron * 15033197c6aStron * @par Derived From: 15133197c6aStron * This code is derived from btree.c written by Martin Hedenfalk. 15233197c6aStron * 15333197c6aStron * Copyright (c) 2009, 2010 Martin Hedenfalk <martin@bzero.se> 15433197c6aStron * 15533197c6aStron * Permission to use, copy, modify, and distribute this software for any 15633197c6aStron * purpose with or without fee is hereby granted, provided that the above 15733197c6aStron * copyright notice and this permission notice appear in all copies. 15833197c6aStron * 15933197c6aStron * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 16033197c6aStron * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16133197c6aStron * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16233197c6aStron * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 16333197c6aStron * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16433197c6aStron * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16533197c6aStron * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16633197c6aStron */ 16733197c6aStron #ifndef _LMDB_H_ 16833197c6aStron #define _LMDB_H_ 16933197c6aStron 17033197c6aStron #include <sys/types.h> 17133197c6aStron 17233197c6aStron #ifdef __cplusplus 17333197c6aStron extern "C" { 17433197c6aStron #endif 17533197c6aStron 17633197c6aStron /** Unix permissions for creating files, or dummy definition for Windows */ 17733197c6aStron #ifdef _MSC_VER 17833197c6aStron typedef int mdb_mode_t; 17933197c6aStron #else 18033197c6aStron typedef mode_t mdb_mode_t; 18133197c6aStron #endif 18233197c6aStron 18333197c6aStron /** An abstraction for a file handle. 18433197c6aStron * On POSIX systems file handles are small integers. On Windows 18533197c6aStron * they're opaque pointers. 18633197c6aStron */ 18733197c6aStron #ifdef _WIN32 18833197c6aStron typedef void *mdb_filehandle_t; 18933197c6aStron #else 19033197c6aStron typedef int mdb_filehandle_t; 19133197c6aStron #endif 19233197c6aStron 1938bd9f7cdSchristos /** @defgroup mdb LMDB API 19433197c6aStron * @{ 19533197c6aStron * @brief OpenLDAP Lightning Memory-Mapped Database Manager 19633197c6aStron */ 19733197c6aStron /** @defgroup Version Version Macros 19833197c6aStron * @{ 19933197c6aStron */ 20033197c6aStron /** Library major version */ 20133197c6aStron #define MDB_VERSION_MAJOR 0 20233197c6aStron /** Library minor version */ 20333197c6aStron #define MDB_VERSION_MINOR 9 20433197c6aStron /** Library patch version */ 205*cf1d77f7Schristos #define MDB_VERSION_PATCH 29 20633197c6aStron 20733197c6aStron /** Combine args a,b,c into a single integer for easy version comparisons */ 20833197c6aStron #define MDB_VERINT(a,b,c) (((a) << 24) | ((b) << 16) | (c)) 20933197c6aStron 21033197c6aStron /** The full library version as a single integer */ 21133197c6aStron #define MDB_VERSION_FULL \ 21233197c6aStron MDB_VERINT(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH) 21333197c6aStron 21433197c6aStron /** The release date of this library version */ 215*cf1d77f7Schristos #define MDB_VERSION_DATE "March 16, 2021" 21633197c6aStron 21733197c6aStron /** A stringifier for the version info */ 2188bd9f7cdSchristos #define MDB_VERSTR(a,b,c,d) "LMDB " #a "." #b "." #c ": (" d ")" 21933197c6aStron 22033197c6aStron /** A helper for the stringifier macro */ 22133197c6aStron #define MDB_VERFOO(a,b,c,d) MDB_VERSTR(a,b,c,d) 22233197c6aStron 22333197c6aStron /** The full library version as a C string */ 22433197c6aStron #define MDB_VERSION_STRING \ 22533197c6aStron MDB_VERFOO(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH,MDB_VERSION_DATE) 22633197c6aStron /** @} */ 22733197c6aStron 22833197c6aStron /** @brief Opaque structure for a database environment. 22933197c6aStron * 23033197c6aStron * A DB environment supports multiple databases, all residing in the same 23133197c6aStron * shared-memory map. 23233197c6aStron */ 23333197c6aStron typedef struct MDB_env MDB_env; 23433197c6aStron 23533197c6aStron /** @brief Opaque structure for a transaction handle. 23633197c6aStron * 23733197c6aStron * All database operations require a transaction handle. Transactions may be 23833197c6aStron * read-only or read-write. 23933197c6aStron */ 24033197c6aStron typedef struct MDB_txn MDB_txn; 24133197c6aStron 24233197c6aStron /** @brief A handle for an individual database in the DB environment. */ 24333197c6aStron typedef unsigned int MDB_dbi; 24433197c6aStron 24533197c6aStron /** @brief Opaque structure for navigating through a database */ 24633197c6aStron typedef struct MDB_cursor MDB_cursor; 24733197c6aStron 24833197c6aStron /** @brief Generic structure used for passing keys and data in and out 24933197c6aStron * of the database. 25033197c6aStron * 25133197c6aStron * Values returned from the database are valid only until a subsequent 25233197c6aStron * update operation, or the end of the transaction. Do not modify or 25333197c6aStron * free them, they commonly point into the database itself. 25433197c6aStron * 25533197c6aStron * Key sizes must be between 1 and #mdb_env_get_maxkeysize() inclusive. 25633197c6aStron * The same applies to data sizes in databases with the #MDB_DUPSORT flag. 25733197c6aStron * Other data items can in theory be from 0 to 0xffffffff bytes long. 25833197c6aStron */ 25933197c6aStron typedef struct MDB_val { 26033197c6aStron size_t mv_size; /**< size of the data item */ 26133197c6aStron void *mv_data; /**< address of the data item */ 26233197c6aStron } MDB_val; 26333197c6aStron 26433197c6aStron /** @brief A callback function used to compare two keys in a database */ 26533197c6aStron typedef int (MDB_cmp_func)(const MDB_val *a, const MDB_val *b); 26633197c6aStron 26733197c6aStron /** @brief A callback function used to relocate a position-dependent data item 26833197c6aStron * in a fixed-address database. 26933197c6aStron * 27033197c6aStron * The \b newptr gives the item's desired address in 27133197c6aStron * the memory map, and \b oldptr gives its previous address. The item's actual 27233197c6aStron * data resides at the address in \b item. This callback is expected to walk 27333197c6aStron * through the fields of the record in \b item and modify any 27433197c6aStron * values based at the \b oldptr address to be relative to the \b newptr address. 27533197c6aStron * @param[in,out] item The item that is to be relocated. 27633197c6aStron * @param[in] oldptr The previous address. 27733197c6aStron * @param[in] newptr The new address to relocate to. 27833197c6aStron * @param[in] relctx An application-provided context, set by #mdb_set_relctx(). 27933197c6aStron * @todo This feature is currently unimplemented. 28033197c6aStron */ 28133197c6aStron typedef void (MDB_rel_func)(MDB_val *item, void *oldptr, void *newptr, void *relctx); 28233197c6aStron 28333197c6aStron /** @defgroup mdb_env Environment Flags 28433197c6aStron * @{ 28533197c6aStron */ 28633197c6aStron /** mmap at a fixed address (experimental) */ 28733197c6aStron #define MDB_FIXEDMAP 0x01 28833197c6aStron /** no environment directory */ 28933197c6aStron #define MDB_NOSUBDIR 0x4000 29033197c6aStron /** don't fsync after commit */ 29133197c6aStron #define MDB_NOSYNC 0x10000 29233197c6aStron /** read only */ 29333197c6aStron #define MDB_RDONLY 0x20000 29433197c6aStron /** don't fsync metapage after commit */ 29533197c6aStron #define MDB_NOMETASYNC 0x40000 29633197c6aStron /** use writable mmap */ 29733197c6aStron #define MDB_WRITEMAP 0x80000 29833197c6aStron /** use asynchronous msync when #MDB_WRITEMAP is used */ 29933197c6aStron #define MDB_MAPASYNC 0x100000 30033197c6aStron /** tie reader locktable slots to #MDB_txn objects instead of to threads */ 30133197c6aStron #define MDB_NOTLS 0x200000 30233197c6aStron /** don't do any locking, caller must manage their own locks */ 30333197c6aStron #define MDB_NOLOCK 0x400000 30433197c6aStron /** don't do readahead (no effect on Windows) */ 30533197c6aStron #define MDB_NORDAHEAD 0x800000 30633197c6aStron /** don't initialize malloc'd memory before writing to datafile */ 30733197c6aStron #define MDB_NOMEMINIT 0x1000000 30833197c6aStron /** @} */ 30933197c6aStron 31033197c6aStron /** @defgroup mdb_dbi_open Database Flags 31133197c6aStron * @{ 31233197c6aStron */ 31333197c6aStron /** use reverse string keys */ 31433197c6aStron #define MDB_REVERSEKEY 0x02 31533197c6aStron /** use sorted duplicates */ 31633197c6aStron #define MDB_DUPSORT 0x04 3178bd9f7cdSchristos /** numeric keys in native byte order: either unsigned int or size_t. 31833197c6aStron * The keys must all be of the same size. */ 31933197c6aStron #define MDB_INTEGERKEY 0x08 32033197c6aStron /** with #MDB_DUPSORT, sorted dup items have fixed size */ 32133197c6aStron #define MDB_DUPFIXED 0x10 3228bd9f7cdSchristos /** with #MDB_DUPSORT, dups are #MDB_INTEGERKEY-style integers */ 32333197c6aStron #define MDB_INTEGERDUP 0x20 32433197c6aStron /** with #MDB_DUPSORT, use reverse string dups */ 32533197c6aStron #define MDB_REVERSEDUP 0x40 32633197c6aStron /** create DB if not already existing */ 32733197c6aStron #define MDB_CREATE 0x40000 32833197c6aStron /** @} */ 32933197c6aStron 33033197c6aStron /** @defgroup mdb_put Write Flags 33133197c6aStron * @{ 33233197c6aStron */ 33333197c6aStron /** For put: Don't write if the key already exists. */ 33433197c6aStron #define MDB_NOOVERWRITE 0x10 33533197c6aStron /** Only for #MDB_DUPSORT<br> 33633197c6aStron * For put: don't write if the key and data pair already exist.<br> 33733197c6aStron * For mdb_cursor_del: remove all duplicate data items. 33833197c6aStron */ 33933197c6aStron #define MDB_NODUPDATA 0x20 34033197c6aStron /** For mdb_cursor_put: overwrite the current key/data pair */ 34133197c6aStron #define MDB_CURRENT 0x40 34233197c6aStron /** For put: Just reserve space for data, don't copy it. Return a 34333197c6aStron * pointer to the reserved space. 34433197c6aStron */ 34533197c6aStron #define MDB_RESERVE 0x10000 34633197c6aStron /** Data is being appended, don't split full pages. */ 34733197c6aStron #define MDB_APPEND 0x20000 34833197c6aStron /** Duplicate data is being appended, don't split full pages. */ 34933197c6aStron #define MDB_APPENDDUP 0x40000 35033197c6aStron /** Store multiple data items in one call. Only for #MDB_DUPFIXED. */ 35133197c6aStron #define MDB_MULTIPLE 0x80000 35233197c6aStron /* @} */ 35333197c6aStron 3548bd9f7cdSchristos /** @defgroup mdb_copy Copy Flags 3558bd9f7cdSchristos * @{ 3568bd9f7cdSchristos */ 3578bd9f7cdSchristos /** Compacting copy: Omit free space from copy, and renumber all 3588bd9f7cdSchristos * pages sequentially. 3598bd9f7cdSchristos */ 3608bd9f7cdSchristos #define MDB_CP_COMPACT 0x01 3618bd9f7cdSchristos /* @} */ 3628bd9f7cdSchristos 36333197c6aStron /** @brief Cursor Get operations. 36433197c6aStron * 36533197c6aStron * This is the set of all operations for retrieving data 36633197c6aStron * using a cursor. 36733197c6aStron */ 36833197c6aStron typedef enum MDB_cursor_op { 36933197c6aStron MDB_FIRST, /**< Position at first key/data item */ 37033197c6aStron MDB_FIRST_DUP, /**< Position at first data item of current key. 37133197c6aStron Only for #MDB_DUPSORT */ 37233197c6aStron MDB_GET_BOTH, /**< Position at key/data pair. Only for #MDB_DUPSORT */ 37333197c6aStron MDB_GET_BOTH_RANGE, /**< position at key, nearest data. Only for #MDB_DUPSORT */ 37433197c6aStron MDB_GET_CURRENT, /**< Return key/data at current cursor position */ 3758da6f2f6Schristos MDB_GET_MULTIPLE, /**< Return up to a page of duplicate data items 3768bd9f7cdSchristos from current cursor position. Move cursor to prepare 3778bd9f7cdSchristos for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */ 37833197c6aStron MDB_LAST, /**< Position at last key/data item */ 37933197c6aStron MDB_LAST_DUP, /**< Position at last data item of current key. 38033197c6aStron Only for #MDB_DUPSORT */ 38133197c6aStron MDB_NEXT, /**< Position at next data item */ 38233197c6aStron MDB_NEXT_DUP, /**< Position at next data item of current key. 38333197c6aStron Only for #MDB_DUPSORT */ 3848da6f2f6Schristos MDB_NEXT_MULTIPLE, /**< Return up to a page of duplicate data items 3858bd9f7cdSchristos from next cursor position. Move cursor to prepare 3868bd9f7cdSchristos for #MDB_NEXT_MULTIPLE. Only for #MDB_DUPFIXED */ 38733197c6aStron MDB_NEXT_NODUP, /**< Position at first data item of next key */ 38833197c6aStron MDB_PREV, /**< Position at previous data item */ 38933197c6aStron MDB_PREV_DUP, /**< Position at previous data item of current key. 39033197c6aStron Only for #MDB_DUPSORT */ 39133197c6aStron MDB_PREV_NODUP, /**< Position at last data item of previous key */ 39233197c6aStron MDB_SET, /**< Position at specified key */ 39333197c6aStron MDB_SET_KEY, /**< Position at specified key, return key + data */ 39482bf52b1Schristos MDB_SET_RANGE, /**< Position at first key greater than or equal to specified key. */ 3958da6f2f6Schristos MDB_PREV_MULTIPLE /**< Position at previous page and return up to 39682bf52b1Schristos a page of duplicate data items. Only for #MDB_DUPFIXED */ 39733197c6aStron } MDB_cursor_op; 39833197c6aStron 39933197c6aStron /** @defgroup errors Return Codes 40033197c6aStron * 40133197c6aStron * BerkeleyDB uses -30800 to -30999, we'll go under them 40233197c6aStron * @{ 40333197c6aStron */ 40433197c6aStron /** Successful result */ 40533197c6aStron #define MDB_SUCCESS 0 40633197c6aStron /** key/data pair already exists */ 40733197c6aStron #define MDB_KEYEXIST (-30799) 40833197c6aStron /** key/data pair not found (EOF) */ 40933197c6aStron #define MDB_NOTFOUND (-30798) 41033197c6aStron /** Requested page not found - this usually indicates corruption */ 41133197c6aStron #define MDB_PAGE_NOTFOUND (-30797) 41233197c6aStron /** Located page was wrong type */ 41333197c6aStron #define MDB_CORRUPTED (-30796) 4148bd9f7cdSchristos /** Update of meta page failed or environment had fatal error */ 41533197c6aStron #define MDB_PANIC (-30795) 41633197c6aStron /** Environment version mismatch */ 41733197c6aStron #define MDB_VERSION_MISMATCH (-30794) 4188bd9f7cdSchristos /** File is not a valid LMDB file */ 41933197c6aStron #define MDB_INVALID (-30793) 42033197c6aStron /** Environment mapsize reached */ 42133197c6aStron #define MDB_MAP_FULL (-30792) 42233197c6aStron /** Environment maxdbs reached */ 42333197c6aStron #define MDB_DBS_FULL (-30791) 42433197c6aStron /** Environment maxreaders reached */ 42533197c6aStron #define MDB_READERS_FULL (-30790) 42633197c6aStron /** Too many TLS keys in use - Windows only */ 42733197c6aStron #define MDB_TLS_FULL (-30789) 42833197c6aStron /** Txn has too many dirty pages */ 42933197c6aStron #define MDB_TXN_FULL (-30788) 43033197c6aStron /** Cursor stack too deep - internal error */ 43133197c6aStron #define MDB_CURSOR_FULL (-30787) 43233197c6aStron /** Page has not enough space - internal error */ 43333197c6aStron #define MDB_PAGE_FULL (-30786) 43433197c6aStron /** Database contents grew beyond environment mapsize */ 43533197c6aStron #define MDB_MAP_RESIZED (-30785) 4368bd9f7cdSchristos /** Operation and DB incompatible, or DB type changed. This can mean: 4378bd9f7cdSchristos * <ul> 4388bd9f7cdSchristos * <li>The operation expects an #MDB_DUPSORT / #MDB_DUPFIXED database. 4398bd9f7cdSchristos * <li>Opening a named DB when the unnamed DB has #MDB_DUPSORT / #MDB_INTEGERKEY. 4408bd9f7cdSchristos * <li>Accessing a data record as a database, or vice versa. 4418bd9f7cdSchristos * <li>The database was dropped and recreated with different flags. 4428bd9f7cdSchristos * </ul> 4438bd9f7cdSchristos */ 44433197c6aStron #define MDB_INCOMPATIBLE (-30784) 44533197c6aStron /** Invalid reuse of reader locktable slot */ 44633197c6aStron #define MDB_BAD_RSLOT (-30783) 4478bd9f7cdSchristos /** Transaction must abort, has a child, or is invalid */ 44833197c6aStron #define MDB_BAD_TXN (-30782) 4498bd9f7cdSchristos /** Unsupported size of key/DB name/data, or wrong DUPFIXED size */ 45033197c6aStron #define MDB_BAD_VALSIZE (-30781) 4518bd9f7cdSchristos /** The specified DBI was changed unexpectedly */ 4528bd9f7cdSchristos #define MDB_BAD_DBI (-30780) 4538bd9f7cdSchristos /** The last defined error code */ 4548bd9f7cdSchristos #define MDB_LAST_ERRCODE MDB_BAD_DBI 45533197c6aStron /** @} */ 45633197c6aStron 45733197c6aStron /** @brief Statistics for a database in the environment */ 45833197c6aStron typedef struct MDB_stat { 45933197c6aStron unsigned int ms_psize; /**< Size of a database page. 46033197c6aStron This is currently the same for all databases. */ 46133197c6aStron unsigned int ms_depth; /**< Depth (height) of the B-tree */ 46233197c6aStron size_t ms_branch_pages; /**< Number of internal (non-leaf) pages */ 46333197c6aStron size_t ms_leaf_pages; /**< Number of leaf pages */ 46433197c6aStron size_t ms_overflow_pages; /**< Number of overflow pages */ 46533197c6aStron size_t ms_entries; /**< Number of data items */ 46633197c6aStron } MDB_stat; 46733197c6aStron 46833197c6aStron /** @brief Information about the environment */ 46933197c6aStron typedef struct MDB_envinfo { 47033197c6aStron void *me_mapaddr; /**< Address of map, if fixed */ 47133197c6aStron size_t me_mapsize; /**< Size of the data memory map */ 47233197c6aStron size_t me_last_pgno; /**< ID of the last used page */ 47333197c6aStron size_t me_last_txnid; /**< ID of the last committed transaction */ 47433197c6aStron unsigned int me_maxreaders; /**< max reader slots in the environment */ 47533197c6aStron unsigned int me_numreaders; /**< max reader slots used in the environment */ 47633197c6aStron } MDB_envinfo; 47733197c6aStron 4788bd9f7cdSchristos /** @brief Return the LMDB library version information. 47933197c6aStron * 48033197c6aStron * @param[out] major if non-NULL, the library major version number is copied here 48133197c6aStron * @param[out] minor if non-NULL, the library minor version number is copied here 48233197c6aStron * @param[out] patch if non-NULL, the library patch version number is copied here 48333197c6aStron * @retval "version string" The library version as a string 48433197c6aStron */ 48533197c6aStron char *mdb_version(int *major, int *minor, int *patch); 48633197c6aStron 48733197c6aStron /** @brief Return a string describing a given error code. 48833197c6aStron * 48933197c6aStron * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) 49033197c6aStron * function. If the error code is greater than or equal to 0, then the string 49133197c6aStron * returned by the system function strerror(3) is returned. If the error code 4928bd9f7cdSchristos * is less than 0, an error string corresponding to the LMDB library error is 4938bd9f7cdSchristos * returned. See @ref errors for a list of LMDB-specific error codes. 49433197c6aStron * @param[in] err The error code 49533197c6aStron * @retval "error message" The description of the error 49633197c6aStron */ 49733197c6aStron char *mdb_strerror(int err); 49833197c6aStron 4998bd9f7cdSchristos /** @brief Create an LMDB environment handle. 50033197c6aStron * 50133197c6aStron * This function allocates memory for a #MDB_env structure. To release 50233197c6aStron * the allocated memory and discard the handle, call #mdb_env_close(). 50333197c6aStron * Before the handle may be used, it must be opened using #mdb_env_open(). 50433197c6aStron * Various other options may also need to be set before opening the handle, 50533197c6aStron * e.g. #mdb_env_set_mapsize(), #mdb_env_set_maxreaders(), #mdb_env_set_maxdbs(), 50633197c6aStron * depending on usage requirements. 50733197c6aStron * @param[out] env The address where the new handle will be stored 50833197c6aStron * @return A non-zero error value on failure and 0 on success. 50933197c6aStron */ 51033197c6aStron int mdb_env_create(MDB_env **env); 51133197c6aStron 51233197c6aStron /** @brief Open an environment handle. 51333197c6aStron * 51433197c6aStron * If this function fails, #mdb_env_close() must be called to discard the #MDB_env handle. 51533197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 51633197c6aStron * @param[in] path The directory in which the database files reside. This 51733197c6aStron * directory must already exist and be writable. 51833197c6aStron * @param[in] flags Special options for this environment. This parameter 51933197c6aStron * must be set to 0 or by bitwise OR'ing together one or more of the 52033197c6aStron * values described here. 52133197c6aStron * Flags set by mdb_env_set_flags() are also used. 52233197c6aStron * <ul> 52333197c6aStron * <li>#MDB_FIXEDMAP 52433197c6aStron * use a fixed address for the mmap region. This flag must be specified 52533197c6aStron * when creating the environment, and is stored persistently in the environment. 52633197c6aStron * If successful, the memory map will always reside at the same virtual address 52733197c6aStron * and pointers used to reference data items in the database will be constant 52833197c6aStron * across multiple invocations. This option may not always work, depending on 52933197c6aStron * how the operating system has allocated memory to shared libraries and other uses. 53033197c6aStron * The feature is highly experimental. 53133197c6aStron * <li>#MDB_NOSUBDIR 5328bd9f7cdSchristos * By default, LMDB creates its environment in a directory whose 53333197c6aStron * pathname is given in \b path, and creates its data and lock files 53433197c6aStron * under that directory. With this option, \b path is used as-is for 53533197c6aStron * the database main data file. The database lock file is the \b path 53633197c6aStron * with "-lock" appended. 53733197c6aStron * <li>#MDB_RDONLY 53833197c6aStron * Open the environment in read-only mode. No write operations will be 5398bd9f7cdSchristos * allowed. LMDB will still modify the lock file - except on read-only 5408bd9f7cdSchristos * filesystems, where LMDB does not use locks. 54133197c6aStron * <li>#MDB_WRITEMAP 5428bd9f7cdSchristos * Use a writeable memory map unless MDB_RDONLY is set. This uses 5438bd9f7cdSchristos * fewer mallocs but loses protection from application bugs 54433197c6aStron * like wild pointer writes and other bad updates into the database. 5458bd9f7cdSchristos * This may be slightly faster for DBs that fit entirely in RAM, but 5468bd9f7cdSchristos * is slower for DBs larger than RAM. 54733197c6aStron * Incompatible with nested transactions. 5488bd9f7cdSchristos * Do not mix processes with and without MDB_WRITEMAP on the same 5498bd9f7cdSchristos * environment. This can defeat durability (#mdb_env_sync etc). 55033197c6aStron * <li>#MDB_NOMETASYNC 55133197c6aStron * Flush system buffers to disk only once per transaction, omit the 55233197c6aStron * metadata flush. Defer that until the system flushes files to disk, 55333197c6aStron * or next non-MDB_RDONLY commit or #mdb_env_sync(). This optimization 55433197c6aStron * maintains database integrity, but a system crash may undo the last 55533197c6aStron * committed transaction. I.e. it preserves the ACI (atomicity, 55633197c6aStron * consistency, isolation) but not D (durability) database property. 55733197c6aStron * This flag may be changed at any time using #mdb_env_set_flags(). 55833197c6aStron * <li>#MDB_NOSYNC 55933197c6aStron * Don't flush system buffers to disk when committing a transaction. 56033197c6aStron * This optimization means a system crash can corrupt the database or 56133197c6aStron * lose the last transactions if buffers are not yet flushed to disk. 56233197c6aStron * The risk is governed by how often the system flushes dirty buffers 56333197c6aStron * to disk and how often #mdb_env_sync() is called. However, if the 56433197c6aStron * filesystem preserves write order and the #MDB_WRITEMAP flag is not 56533197c6aStron * used, transactions exhibit ACI (atomicity, consistency, isolation) 56633197c6aStron * properties and only lose D (durability). I.e. database integrity 56733197c6aStron * is maintained, but a system crash may undo the final transactions. 56833197c6aStron * Note that (#MDB_NOSYNC | #MDB_WRITEMAP) leaves the system with no 56933197c6aStron * hint for when to write transactions to disk, unless #mdb_env_sync() 57033197c6aStron * is called. (#MDB_MAPASYNC | #MDB_WRITEMAP) may be preferable. 57133197c6aStron * This flag may be changed at any time using #mdb_env_set_flags(). 57233197c6aStron * <li>#MDB_MAPASYNC 57333197c6aStron * When using #MDB_WRITEMAP, use asynchronous flushes to disk. 57433197c6aStron * As with #MDB_NOSYNC, a system crash can then corrupt the 57533197c6aStron * database or lose the last transactions. Calling #mdb_env_sync() 57633197c6aStron * ensures on-disk database integrity until next commit. 57733197c6aStron * This flag may be changed at any time using #mdb_env_set_flags(). 57833197c6aStron * <li>#MDB_NOTLS 57933197c6aStron * Don't use Thread-Local Storage. Tie reader locktable slots to 58033197c6aStron * #MDB_txn objects instead of to threads. I.e. #mdb_txn_reset() keeps 581*cf1d77f7Schristos * the slot reserved for the #MDB_txn object. A thread may use parallel 58233197c6aStron * read-only transactions. A read-only transaction may span threads if 58333197c6aStron * the user synchronizes its use. Applications that multiplex many 58433197c6aStron * user threads over individual OS threads need this option. Such an 58533197c6aStron * application must also serialize the write transactions in an OS 5868bd9f7cdSchristos * thread, since LMDB's write locking is unaware of the user threads. 58733197c6aStron * <li>#MDB_NOLOCK 58833197c6aStron * Don't do any locking. If concurrent access is anticipated, the 58933197c6aStron * caller must manage all concurrency itself. For proper operation 59033197c6aStron * the caller must enforce single-writer semantics, and must ensure 59133197c6aStron * that no readers are using old transactions while a writer is 59233197c6aStron * active. The simplest approach is to use an exclusive lock so that 59333197c6aStron * no readers may be active at all when a writer begins. 59433197c6aStron * <li>#MDB_NORDAHEAD 59533197c6aStron * Turn off readahead. Most operating systems perform readahead on 59633197c6aStron * read requests by default. This option turns it off if the OS 59733197c6aStron * supports it. Turning it off may help random read performance 59833197c6aStron * when the DB is larger than RAM and system RAM is full. 59933197c6aStron * The option is not implemented on Windows. 60033197c6aStron * <li>#MDB_NOMEMINIT 60133197c6aStron * Don't initialize malloc'd memory before writing to unused spaces 60233197c6aStron * in the data file. By default, memory for pages written to the data 60333197c6aStron * file is obtained using malloc. While these pages may be reused in 60433197c6aStron * subsequent transactions, freshly malloc'd pages will be initialized 60533197c6aStron * to zeroes before use. This avoids persisting leftover data from other 60633197c6aStron * code (that used the heap and subsequently freed the memory) into the 60733197c6aStron * data file. Note that many other system libraries may allocate 60833197c6aStron * and free memory from the heap for arbitrary uses. E.g., stdio may 60933197c6aStron * use the heap for file I/O buffers. This initialization step has a 61033197c6aStron * modest performance cost so some applications may want to disable 61133197c6aStron * it using this flag. This option can be a problem for applications 61233197c6aStron * which handle sensitive data like passwords, and it makes memory 61333197c6aStron * checkers like Valgrind noisy. This flag is not needed with #MDB_WRITEMAP, 61433197c6aStron * which writes directly to the mmap instead of using malloc for pages. The 61533197c6aStron * initialization is also skipped if #MDB_RESERVE is used; the 61633197c6aStron * caller is expected to overwrite all of the memory that was 61733197c6aStron * reserved in that case. 61833197c6aStron * This flag may be changed at any time using #mdb_env_set_flags(). 61933197c6aStron * </ul> 6208bd9f7cdSchristos * @param[in] mode The UNIX permissions to set on created files and semaphores. 6218bd9f7cdSchristos * This parameter is ignored on Windows. 62233197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 62333197c6aStron * errors are: 62433197c6aStron * <ul> 6258bd9f7cdSchristos * <li>#MDB_VERSION_MISMATCH - the version of the LMDB library doesn't match the 62633197c6aStron * version that created the database environment. 62733197c6aStron * <li>#MDB_INVALID - the environment file headers are corrupted. 62833197c6aStron * <li>ENOENT - the directory specified by the path parameter doesn't exist. 62933197c6aStron * <li>EACCES - the user didn't have permission to access the environment files. 63033197c6aStron * <li>EAGAIN - the environment was locked by another process. 63133197c6aStron * </ul> 63233197c6aStron */ 63333197c6aStron int mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mdb_mode_t mode); 63433197c6aStron 6358bd9f7cdSchristos /** @brief Copy an LMDB environment to the specified path. 63633197c6aStron * 63733197c6aStron * This function may be used to make a backup of an existing environment. 63833197c6aStron * No lockfile is created, since it gets recreated at need. 63933197c6aStron * @note This call can trigger significant file size growth if run in 64033197c6aStron * parallel with write transactions, because it employs a read-only 64133197c6aStron * transaction. See long-lived transactions under @ref caveats_sec. 64233197c6aStron * @param[in] env An environment handle returned by #mdb_env_create(). It 64333197c6aStron * must have already been opened successfully. 64433197c6aStron * @param[in] path The directory in which the copy will reside. This 64533197c6aStron * directory must already exist and be writable but must otherwise be 64633197c6aStron * empty. 64733197c6aStron * @return A non-zero error value on failure and 0 on success. 64833197c6aStron */ 64933197c6aStron int mdb_env_copy(MDB_env *env, const char *path); 65033197c6aStron 6518bd9f7cdSchristos /** @brief Copy an LMDB environment to the specified file descriptor. 65233197c6aStron * 65333197c6aStron * This function may be used to make a backup of an existing environment. 65433197c6aStron * No lockfile is created, since it gets recreated at need. 65533197c6aStron * @note This call can trigger significant file size growth if run in 65633197c6aStron * parallel with write transactions, because it employs a read-only 65733197c6aStron * transaction. See long-lived transactions under @ref caveats_sec. 65833197c6aStron * @param[in] env An environment handle returned by #mdb_env_create(). It 65933197c6aStron * must have already been opened successfully. 66033197c6aStron * @param[in] fd The filedescriptor to write the copy to. It must 66133197c6aStron * have already been opened for Write access. 66233197c6aStron * @return A non-zero error value on failure and 0 on success. 66333197c6aStron */ 66433197c6aStron int mdb_env_copyfd(MDB_env *env, mdb_filehandle_t fd); 66533197c6aStron 6668bd9f7cdSchristos /** @brief Copy an LMDB environment to the specified path, with options. 6678bd9f7cdSchristos * 6688bd9f7cdSchristos * This function may be used to make a backup of an existing environment. 6698bd9f7cdSchristos * No lockfile is created, since it gets recreated at need. 6708bd9f7cdSchristos * @note This call can trigger significant file size growth if run in 6718bd9f7cdSchristos * parallel with write transactions, because it employs a read-only 6728bd9f7cdSchristos * transaction. See long-lived transactions under @ref caveats_sec. 6738bd9f7cdSchristos * @param[in] env An environment handle returned by #mdb_env_create(). It 6748bd9f7cdSchristos * must have already been opened successfully. 6758bd9f7cdSchristos * @param[in] path The directory in which the copy will reside. This 6768bd9f7cdSchristos * directory must already exist and be writable but must otherwise be 6778bd9f7cdSchristos * empty. 6788bd9f7cdSchristos * @param[in] flags Special options for this operation. This parameter 6798bd9f7cdSchristos * must be set to 0 or by bitwise OR'ing together one or more of the 6808bd9f7cdSchristos * values described here. 6818bd9f7cdSchristos * <ul> 6828bd9f7cdSchristos * <li>#MDB_CP_COMPACT - Perform compaction while copying: omit free 6838bd9f7cdSchristos * pages and sequentially renumber all pages in output. This option 6848bd9f7cdSchristos * consumes more CPU and runs more slowly than the default. 68582bf52b1Schristos * Currently it fails if the environment has suffered a page leak. 6868bd9f7cdSchristos * </ul> 6878bd9f7cdSchristos * @return A non-zero error value on failure and 0 on success. 6888bd9f7cdSchristos */ 6898bd9f7cdSchristos int mdb_env_copy2(MDB_env *env, const char *path, unsigned int flags); 6908bd9f7cdSchristos 6918bd9f7cdSchristos /** @brief Copy an LMDB environment to the specified file descriptor, 6928bd9f7cdSchristos * with options. 6938bd9f7cdSchristos * 6948bd9f7cdSchristos * This function may be used to make a backup of an existing environment. 6958bd9f7cdSchristos * No lockfile is created, since it gets recreated at need. See 6968bd9f7cdSchristos * #mdb_env_copy2() for further details. 6978bd9f7cdSchristos * @note This call can trigger significant file size growth if run in 6988bd9f7cdSchristos * parallel with write transactions, because it employs a read-only 6998bd9f7cdSchristos * transaction. See long-lived transactions under @ref caveats_sec. 7008bd9f7cdSchristos * @param[in] env An environment handle returned by #mdb_env_create(). It 7018bd9f7cdSchristos * must have already been opened successfully. 7028bd9f7cdSchristos * @param[in] fd The filedescriptor to write the copy to. It must 7038bd9f7cdSchristos * have already been opened for Write access. 7048bd9f7cdSchristos * @param[in] flags Special options for this operation. 7058bd9f7cdSchristos * See #mdb_env_copy2() for options. 7068bd9f7cdSchristos * @return A non-zero error value on failure and 0 on success. 7078bd9f7cdSchristos */ 7088bd9f7cdSchristos int mdb_env_copyfd2(MDB_env *env, mdb_filehandle_t fd, unsigned int flags); 7098bd9f7cdSchristos 7108bd9f7cdSchristos /** @brief Return statistics about the LMDB environment. 71133197c6aStron * 71233197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 71333197c6aStron * @param[out] stat The address of an #MDB_stat structure 71433197c6aStron * where the statistics will be copied 71533197c6aStron */ 71633197c6aStron int mdb_env_stat(MDB_env *env, MDB_stat *stat); 71733197c6aStron 7188bd9f7cdSchristos /** @brief Return information about the LMDB environment. 71933197c6aStron * 72033197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 72133197c6aStron * @param[out] stat The address of an #MDB_envinfo structure 72233197c6aStron * where the information will be copied 72333197c6aStron */ 72433197c6aStron int mdb_env_info(MDB_env *env, MDB_envinfo *stat); 72533197c6aStron 72633197c6aStron /** @brief Flush the data buffers to disk. 72733197c6aStron * 72833197c6aStron * Data is always written to disk when #mdb_txn_commit() is called, 7298bd9f7cdSchristos * but the operating system may keep it buffered. LMDB always flushes 73033197c6aStron * the OS buffers upon commit as well, unless the environment was 7318bd9f7cdSchristos * opened with #MDB_NOSYNC or in part #MDB_NOMETASYNC. This call is 7328bd9f7cdSchristos * not valid if the environment was opened with #MDB_RDONLY. 73333197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 73433197c6aStron * @param[in] force If non-zero, force a synchronous flush. Otherwise 73533197c6aStron * if the environment has the #MDB_NOSYNC flag set the flushes 73633197c6aStron * will be omitted, and with #MDB_MAPASYNC they will be asynchronous. 73733197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 73833197c6aStron * errors are: 73933197c6aStron * <ul> 7408bd9f7cdSchristos * <li>EACCES - the environment is read-only. 74133197c6aStron * <li>EINVAL - an invalid parameter was specified. 74233197c6aStron * <li>EIO - an error occurred during synchronization. 74333197c6aStron * </ul> 74433197c6aStron */ 74533197c6aStron int mdb_env_sync(MDB_env *env, int force); 74633197c6aStron 74733197c6aStron /** @brief Close the environment and release the memory map. 74833197c6aStron * 74933197c6aStron * Only a single thread may call this function. All transactions, databases, 75033197c6aStron * and cursors must already be closed before calling this function. Attempts to 75133197c6aStron * use any such handles after calling this function will cause a SIGSEGV. 75233197c6aStron * The environment handle will be freed and must not be used again after this call. 75333197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 75433197c6aStron */ 75533197c6aStron void mdb_env_close(MDB_env *env); 75633197c6aStron 75733197c6aStron /** @brief Set environment flags. 75833197c6aStron * 75933197c6aStron * This may be used to set some flags in addition to those from 7608bd9f7cdSchristos * #mdb_env_open(), or to unset these flags. If several threads 7618bd9f7cdSchristos * change the flags at the same time, the result is undefined. 76233197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 76333197c6aStron * @param[in] flags The flags to change, bitwise OR'ed together 76433197c6aStron * @param[in] onoff A non-zero value sets the flags, zero clears them. 76533197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 76633197c6aStron * errors are: 76733197c6aStron * <ul> 76833197c6aStron * <li>EINVAL - an invalid parameter was specified. 76933197c6aStron * </ul> 77033197c6aStron */ 77133197c6aStron int mdb_env_set_flags(MDB_env *env, unsigned int flags, int onoff); 77233197c6aStron 77333197c6aStron /** @brief Get environment flags. 77433197c6aStron * 77533197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 77633197c6aStron * @param[out] flags The address of an integer to store the flags 77733197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 77833197c6aStron * errors are: 77933197c6aStron * <ul> 78033197c6aStron * <li>EINVAL - an invalid parameter was specified. 78133197c6aStron * </ul> 78233197c6aStron */ 78333197c6aStron int mdb_env_get_flags(MDB_env *env, unsigned int *flags); 78433197c6aStron 78533197c6aStron /** @brief Return the path that was used in #mdb_env_open(). 78633197c6aStron * 78733197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 78833197c6aStron * @param[out] path Address of a string pointer to contain the path. This 78933197c6aStron * is the actual string in the environment, not a copy. It should not be 79033197c6aStron * altered in any way. 79133197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 79233197c6aStron * errors are: 79333197c6aStron * <ul> 79433197c6aStron * <li>EINVAL - an invalid parameter was specified. 79533197c6aStron * </ul> 79633197c6aStron */ 79733197c6aStron int mdb_env_get_path(MDB_env *env, const char **path); 79833197c6aStron 79933197c6aStron /** @brief Return the filedescriptor for the given environment. 80033197c6aStron * 80182bf52b1Schristos * This function may be called after fork(), so the descriptor can be 80282bf52b1Schristos * closed before exec*(). Other LMDB file descriptors have FD_CLOEXEC. 80382bf52b1Schristos * (Until LMDB 0.9.18, only the lockfile had that.) 80482bf52b1Schristos * 80533197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 80633197c6aStron * @param[out] fd Address of a mdb_filehandle_t to contain the descriptor. 80733197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 80833197c6aStron * errors are: 80933197c6aStron * <ul> 81033197c6aStron * <li>EINVAL - an invalid parameter was specified. 81133197c6aStron * </ul> 81233197c6aStron */ 81333197c6aStron int mdb_env_get_fd(MDB_env *env, mdb_filehandle_t *fd); 81433197c6aStron 81533197c6aStron /** @brief Set the size of the memory map to use for this environment. 81633197c6aStron * 81733197c6aStron * The size should be a multiple of the OS page size. The default is 81833197c6aStron * 10485760 bytes. The size of the memory map is also the maximum size 81933197c6aStron * of the database. The value should be chosen as large as possible, 82033197c6aStron * to accommodate future growth of the database. 82133197c6aStron * This function should be called after #mdb_env_create() and before #mdb_env_open(). 82233197c6aStron * It may be called at later times if no transactions are active in 82333197c6aStron * this process. Note that the library does not check for this condition, 82433197c6aStron * the caller must ensure it explicitly. 82533197c6aStron * 8268bd9f7cdSchristos * The new size takes effect immediately for the current process but 8278bd9f7cdSchristos * will not be persisted to any others until a write transaction has been 8288bd9f7cdSchristos * committed by the current process. Also, only mapsize increases are 8298bd9f7cdSchristos * persisted into the environment. 8308bd9f7cdSchristos * 8318bd9f7cdSchristos * If the mapsize is increased by another process, and data has grown 8328bd9f7cdSchristos * beyond the range of the current mapsize, #mdb_txn_begin() will 83333197c6aStron * return #MDB_MAP_RESIZED. This function may be called with a size 83433197c6aStron * of zero to adopt the new size. 83533197c6aStron * 83633197c6aStron * Any attempt to set a size smaller than the space already consumed 83733197c6aStron * by the environment will be silently changed to the current size of the used space. 83833197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 83933197c6aStron * @param[in] size The size in bytes 84033197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 84133197c6aStron * errors are: 84233197c6aStron * <ul> 84333197c6aStron * <li>EINVAL - an invalid parameter was specified, or the environment has 84433197c6aStron * an active write transaction. 84533197c6aStron * </ul> 84633197c6aStron */ 84733197c6aStron int mdb_env_set_mapsize(MDB_env *env, size_t size); 84833197c6aStron 84933197c6aStron /** @brief Set the maximum number of threads/reader slots for the environment. 85033197c6aStron * 85133197c6aStron * This defines the number of slots in the lock table that is used to track readers in the 85233197c6aStron * the environment. The default is 126. 85333197c6aStron * Starting a read-only transaction normally ties a lock table slot to the 85433197c6aStron * current thread until the environment closes or the thread exits. If 85533197c6aStron * MDB_NOTLS is in use, #mdb_txn_begin() instead ties the slot to the 85633197c6aStron * MDB_txn object until it or the #MDB_env object is destroyed. 85733197c6aStron * This function may only be called after #mdb_env_create() and before #mdb_env_open(). 85833197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 85933197c6aStron * @param[in] readers The maximum number of reader lock table slots 86033197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 86133197c6aStron * errors are: 86233197c6aStron * <ul> 86333197c6aStron * <li>EINVAL - an invalid parameter was specified, or the environment is already open. 86433197c6aStron * </ul> 86533197c6aStron */ 86633197c6aStron int mdb_env_set_maxreaders(MDB_env *env, unsigned int readers); 86733197c6aStron 86833197c6aStron /** @brief Get the maximum number of threads/reader slots for the environment. 86933197c6aStron * 87033197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 87133197c6aStron * @param[out] readers Address of an integer to store the number of readers 87233197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 87333197c6aStron * errors are: 87433197c6aStron * <ul> 87533197c6aStron * <li>EINVAL - an invalid parameter was specified. 87633197c6aStron * </ul> 87733197c6aStron */ 87833197c6aStron int mdb_env_get_maxreaders(MDB_env *env, unsigned int *readers); 87933197c6aStron 88033197c6aStron /** @brief Set the maximum number of named databases for the environment. 88133197c6aStron * 88233197c6aStron * This function is only needed if multiple databases will be used in the 88333197c6aStron * environment. Simpler applications that use the environment as a single 88433197c6aStron * unnamed database can ignore this option. 88533197c6aStron * This function may only be called after #mdb_env_create() and before #mdb_env_open(). 8868bd9f7cdSchristos * 8878bd9f7cdSchristos * Currently a moderate number of slots are cheap but a huge number gets 8888bd9f7cdSchristos * expensive: 7-120 words per transaction, and every #mdb_dbi_open() 8898bd9f7cdSchristos * does a linear search of the opened slots. 89033197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 89133197c6aStron * @param[in] dbs The maximum number of databases 89233197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 89333197c6aStron * errors are: 89433197c6aStron * <ul> 89533197c6aStron * <li>EINVAL - an invalid parameter was specified, or the environment is already open. 89633197c6aStron * </ul> 89733197c6aStron */ 89833197c6aStron int mdb_env_set_maxdbs(MDB_env *env, MDB_dbi dbs); 89933197c6aStron 90033197c6aStron /** @brief Get the maximum size of keys and #MDB_DUPSORT data we can write. 90133197c6aStron * 90233197c6aStron * Depends on the compile-time constant #MDB_MAXKEYSIZE. Default 511. 90333197c6aStron * See @ref MDB_val. 90433197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 90533197c6aStron * @return The maximum size of a key we can write 90633197c6aStron */ 90733197c6aStron int mdb_env_get_maxkeysize(MDB_env *env); 90833197c6aStron 90933197c6aStron /** @brief Set application information associated with the #MDB_env. 91033197c6aStron * 91133197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 91233197c6aStron * @param[in] ctx An arbitrary pointer for whatever the application needs. 91333197c6aStron * @return A non-zero error value on failure and 0 on success. 91433197c6aStron */ 91533197c6aStron int mdb_env_set_userctx(MDB_env *env, void *ctx); 91633197c6aStron 91733197c6aStron /** @brief Get the application information associated with the #MDB_env. 91833197c6aStron * 91933197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 92033197c6aStron * @return The pointer set by #mdb_env_set_userctx(). 92133197c6aStron */ 92233197c6aStron void *mdb_env_get_userctx(MDB_env *env); 92333197c6aStron 9248bd9f7cdSchristos /** @brief A callback function for most LMDB assert() failures, 92533197c6aStron * called before printing the message and aborting. 92633197c6aStron * 92733197c6aStron * @param[in] env An environment handle returned by #mdb_env_create(). 92833197c6aStron * @param[in] msg The assertion message, not including newline. 92933197c6aStron */ 93033197c6aStron typedef void MDB_assert_func(MDB_env *env, const char *msg); 93133197c6aStron 93233197c6aStron /** Set or reset the assert() callback of the environment. 933*cf1d77f7Schristos * Disabled if liblmdb is built with NDEBUG. 93433197c6aStron * @note This hack should become obsolete as lmdb's error handling matures. 93533197c6aStron * @param[in] env An environment handle returned by #mdb_env_create(). 9368bd9f7cdSchristos * @param[in] func An #MDB_assert_func function, or 0. 93733197c6aStron * @return A non-zero error value on failure and 0 on success. 93833197c6aStron */ 93933197c6aStron int mdb_env_set_assert(MDB_env *env, MDB_assert_func *func); 94033197c6aStron 94133197c6aStron /** @brief Create a transaction for use with the environment. 94233197c6aStron * 94333197c6aStron * The transaction handle may be discarded using #mdb_txn_abort() or #mdb_txn_commit(). 94433197c6aStron * @note A transaction and its cursors must only be used by a single 94533197c6aStron * thread, and a thread may only have a single transaction at a time. 94633197c6aStron * If #MDB_NOTLS is in use, this does not apply to read-only transactions. 94733197c6aStron * @note Cursors may not span transactions. 94833197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 94933197c6aStron * @param[in] parent If this parameter is non-NULL, the new transaction 95033197c6aStron * will be a nested transaction, with the transaction indicated by \b parent 95133197c6aStron * as its parent. Transactions may be nested to any level. A parent 95233197c6aStron * transaction and its cursors may not issue any other operations than 95333197c6aStron * mdb_txn_commit and mdb_txn_abort while it has active child transactions. 95433197c6aStron * @param[in] flags Special options for this transaction. This parameter 95533197c6aStron * must be set to 0 or by bitwise OR'ing together one or more of the 95633197c6aStron * values described here. 95733197c6aStron * <ul> 95833197c6aStron * <li>#MDB_RDONLY 95933197c6aStron * This transaction will not perform any write operations. 96033197c6aStron * </ul> 96133197c6aStron * @param[out] txn Address where the new #MDB_txn handle will be stored 96233197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 96333197c6aStron * errors are: 96433197c6aStron * <ul> 96533197c6aStron * <li>#MDB_PANIC - a fatal error occurred earlier and the environment 96633197c6aStron * must be shut down. 96733197c6aStron * <li>#MDB_MAP_RESIZED - another process wrote data beyond this MDB_env's 96833197c6aStron * mapsize and this environment's map must be resized as well. 96933197c6aStron * See #mdb_env_set_mapsize(). 97033197c6aStron * <li>#MDB_READERS_FULL - a read-only transaction was requested and 97133197c6aStron * the reader lock table is full. See #mdb_env_set_maxreaders(). 97233197c6aStron * <li>ENOMEM - out of memory. 97333197c6aStron * </ul> 97433197c6aStron */ 97533197c6aStron int mdb_txn_begin(MDB_env *env, MDB_txn *parent, unsigned int flags, MDB_txn **txn); 97633197c6aStron 97733197c6aStron /** @brief Returns the transaction's #MDB_env 97833197c6aStron * 97933197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 98033197c6aStron */ 98133197c6aStron MDB_env *mdb_txn_env(MDB_txn *txn); 98233197c6aStron 9838bd9f7cdSchristos /** @brief Return the transaction's ID. 9848bd9f7cdSchristos * 9858bd9f7cdSchristos * This returns the identifier associated with this transaction. For a 9868bd9f7cdSchristos * read-only transaction, this corresponds to the snapshot being read; 9878bd9f7cdSchristos * concurrent readers will frequently have the same transaction ID. 9888bd9f7cdSchristos * 9898bd9f7cdSchristos * @param[in] txn A transaction handle returned by #mdb_txn_begin() 9908bd9f7cdSchristos * @return A transaction ID, valid if input is an active transaction. 9918bd9f7cdSchristos */ 9928bd9f7cdSchristos size_t mdb_txn_id(MDB_txn *txn); 9938bd9f7cdSchristos 99433197c6aStron /** @brief Commit all the operations of a transaction into the database. 99533197c6aStron * 99633197c6aStron * The transaction handle is freed. It and its cursors must not be used 99733197c6aStron * again after this call, except with #mdb_cursor_renew(). 99833197c6aStron * @note Earlier documentation incorrectly said all cursors would be freed. 99933197c6aStron * Only write-transactions free cursors. 100033197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 100133197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 100233197c6aStron * errors are: 100333197c6aStron * <ul> 100433197c6aStron * <li>EINVAL - an invalid parameter was specified. 100533197c6aStron * <li>ENOSPC - no more disk space. 100633197c6aStron * <li>EIO - a low-level I/O error occurred while writing. 100733197c6aStron * <li>ENOMEM - out of memory. 100833197c6aStron * </ul> 100933197c6aStron */ 101033197c6aStron int mdb_txn_commit(MDB_txn *txn); 101133197c6aStron 101233197c6aStron /** @brief Abandon all the operations of the transaction instead of saving them. 101333197c6aStron * 101433197c6aStron * The transaction handle is freed. It and its cursors must not be used 101533197c6aStron * again after this call, except with #mdb_cursor_renew(). 101633197c6aStron * @note Earlier documentation incorrectly said all cursors would be freed. 101733197c6aStron * Only write-transactions free cursors. 101833197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 101933197c6aStron */ 102033197c6aStron void mdb_txn_abort(MDB_txn *txn); 102133197c6aStron 102233197c6aStron /** @brief Reset a read-only transaction. 102333197c6aStron * 102433197c6aStron * Abort the transaction like #mdb_txn_abort(), but keep the transaction 102533197c6aStron * handle. #mdb_txn_renew() may reuse the handle. This saves allocation 102633197c6aStron * overhead if the process will start a new read-only transaction soon, 102733197c6aStron * and also locking overhead if #MDB_NOTLS is in use. The reader table 102833197c6aStron * lock is released, but the table slot stays tied to its thread or 102933197c6aStron * #MDB_txn. Use mdb_txn_abort() to discard a reset handle, and to free 103033197c6aStron * its lock table slot if MDB_NOTLS is in use. 103133197c6aStron * Cursors opened within the transaction must not be used 103233197c6aStron * again after this call, except with #mdb_cursor_renew(). 103333197c6aStron * Reader locks generally don't interfere with writers, but they keep old 103433197c6aStron * versions of database pages allocated. Thus they prevent the old pages 103533197c6aStron * from being reused when writers commit new data, and so under heavy load 103633197c6aStron * the database size may grow much more rapidly than otherwise. 103733197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 103833197c6aStron */ 103933197c6aStron void mdb_txn_reset(MDB_txn *txn); 104033197c6aStron 104133197c6aStron /** @brief Renew a read-only transaction. 104233197c6aStron * 104333197c6aStron * This acquires a new reader lock for a transaction handle that had been 104433197c6aStron * released by #mdb_txn_reset(). It must be called before a reset transaction 104533197c6aStron * may be used again. 104633197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 104733197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 104833197c6aStron * errors are: 104933197c6aStron * <ul> 105033197c6aStron * <li>#MDB_PANIC - a fatal error occurred earlier and the environment 105133197c6aStron * must be shut down. 105233197c6aStron * <li>EINVAL - an invalid parameter was specified. 105333197c6aStron * </ul> 105433197c6aStron */ 105533197c6aStron int mdb_txn_renew(MDB_txn *txn); 105633197c6aStron 105733197c6aStron /** Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project */ 105833197c6aStron #define mdb_open(txn,name,flags,dbi) mdb_dbi_open(txn,name,flags,dbi) 105933197c6aStron /** Compat with version <= 0.9.4, avoid clash with libmdb from MDB Tools project */ 106033197c6aStron #define mdb_close(env,dbi) mdb_dbi_close(env,dbi) 106133197c6aStron 106233197c6aStron /** @brief Open a database in the environment. 106333197c6aStron * 106433197c6aStron * A database handle denotes the name and parameters of a database, 106533197c6aStron * independently of whether such a database exists. 106633197c6aStron * The database handle may be discarded by calling #mdb_dbi_close(). 106733197c6aStron * The old database handle is returned if the database was already open. 10688bd9f7cdSchristos * The handle may only be closed once. 10698bd9f7cdSchristos * 107033197c6aStron * The database handle will be private to the current transaction until 107133197c6aStron * the transaction is successfully committed. If the transaction is 107233197c6aStron * aborted the handle will be closed automatically. 10738bd9f7cdSchristos * After a successful commit the handle will reside in the shared 10748bd9f7cdSchristos * environment, and may be used by other transactions. 10758bd9f7cdSchristos * 10768bd9f7cdSchristos * This function must not be called from multiple concurrent 10778bd9f7cdSchristos * transactions in the same process. A transaction that uses 10788bd9f7cdSchristos * this function must finish (either commit or abort) before 10798bd9f7cdSchristos * any other transaction in the process may use this function. 108033197c6aStron * 108133197c6aStron * To use named databases (with name != NULL), #mdb_env_set_maxdbs() 10828bd9f7cdSchristos * must be called before opening the environment. Database names are 10838bd9f7cdSchristos * keys in the unnamed database, and may be read but not written. 10848bd9f7cdSchristos * 108533197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 108633197c6aStron * @param[in] name The name of the database to open. If only a single 108733197c6aStron * database is needed in the environment, this value may be NULL. 108833197c6aStron * @param[in] flags Special options for this database. This parameter 108933197c6aStron * must be set to 0 or by bitwise OR'ing together one or more of the 109033197c6aStron * values described here. 109133197c6aStron * <ul> 109233197c6aStron * <li>#MDB_REVERSEKEY 109333197c6aStron * Keys are strings to be compared in reverse order, from the end 109433197c6aStron * of the strings to the beginning. By default, Keys are treated as strings and 109533197c6aStron * compared from beginning to end. 109633197c6aStron * <li>#MDB_DUPSORT 109733197c6aStron * Duplicate keys may be used in the database. (Or, from another perspective, 109833197c6aStron * keys may have multiple data items, stored in sorted order.) By default 109933197c6aStron * keys must be unique and may have only a single data item. 110033197c6aStron * <li>#MDB_INTEGERKEY 11018bd9f7cdSchristos * Keys are binary integers in native byte order, either unsigned int 11028bd9f7cdSchristos * or size_t, and will be sorted as such. 11038bd9f7cdSchristos * The keys must all be of the same size. 110433197c6aStron * <li>#MDB_DUPFIXED 110533197c6aStron * This flag may only be used in combination with #MDB_DUPSORT. This option 110633197c6aStron * tells the library that the data items for this database are all the same 110733197c6aStron * size, which allows further optimizations in storage and retrieval. When 110882bf52b1Schristos * all data items are the same size, the #MDB_GET_MULTIPLE, #MDB_NEXT_MULTIPLE 110982bf52b1Schristos * and #MDB_PREV_MULTIPLE cursor operations may be used to retrieve multiple 111082bf52b1Schristos * items at once. 111133197c6aStron * <li>#MDB_INTEGERDUP 11128bd9f7cdSchristos * This option specifies that duplicate data items are binary integers, 11138bd9f7cdSchristos * similar to #MDB_INTEGERKEY keys. 111433197c6aStron * <li>#MDB_REVERSEDUP 111533197c6aStron * This option specifies that duplicate data items should be compared as 111633197c6aStron * strings in reverse order. 111733197c6aStron * <li>#MDB_CREATE 111833197c6aStron * Create the named database if it doesn't exist. This option is not 111933197c6aStron * allowed in a read-only transaction or a read-only environment. 112033197c6aStron * </ul> 112133197c6aStron * @param[out] dbi Address where the new #MDB_dbi handle will be stored 112233197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 112333197c6aStron * errors are: 112433197c6aStron * <ul> 112533197c6aStron * <li>#MDB_NOTFOUND - the specified database doesn't exist in the environment 112633197c6aStron * and #MDB_CREATE was not specified. 112733197c6aStron * <li>#MDB_DBS_FULL - too many databases have been opened. See #mdb_env_set_maxdbs(). 112833197c6aStron * </ul> 112933197c6aStron */ 113033197c6aStron int mdb_dbi_open(MDB_txn *txn, const char *name, unsigned int flags, MDB_dbi *dbi); 113133197c6aStron 113233197c6aStron /** @brief Retrieve statistics for a database. 113333197c6aStron * 113433197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 113533197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 113633197c6aStron * @param[out] stat The address of an #MDB_stat structure 113733197c6aStron * where the statistics will be copied 113833197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 113933197c6aStron * errors are: 114033197c6aStron * <ul> 114133197c6aStron * <li>EINVAL - an invalid parameter was specified. 114233197c6aStron * </ul> 114333197c6aStron */ 114433197c6aStron int mdb_stat(MDB_txn *txn, MDB_dbi dbi, MDB_stat *stat); 114533197c6aStron 114633197c6aStron /** @brief Retrieve the DB flags for a database handle. 114733197c6aStron * 114833197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 114933197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 115033197c6aStron * @param[out] flags Address where the flags will be returned. 115133197c6aStron * @return A non-zero error value on failure and 0 on success. 115233197c6aStron */ 115333197c6aStron int mdb_dbi_flags(MDB_txn *txn, MDB_dbi dbi, unsigned int *flags); 115433197c6aStron 11558bd9f7cdSchristos /** @brief Close a database handle. Normally unnecessary. Use with care: 115633197c6aStron * 115733197c6aStron * This call is not mutex protected. Handles should only be closed by 115833197c6aStron * a single thread, and only if no other threads are going to reference 115933197c6aStron * the database handle or one of its cursors any further. Do not close 116033197c6aStron * a handle if an existing transaction has modified its database. 11618bd9f7cdSchristos * Doing so can cause misbehavior from database corruption to errors 11628bd9f7cdSchristos * like MDB_BAD_VALSIZE (since the DB name is gone). 11638bd9f7cdSchristos * 11648bd9f7cdSchristos * Closing a database handle is not necessary, but lets #mdb_dbi_open() 11658bd9f7cdSchristos * reuse the handle value. Usually it's better to set a bigger 11668bd9f7cdSchristos * #mdb_env_set_maxdbs(), unless that value would be large. 11678bd9f7cdSchristos * 116833197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 116933197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 117033197c6aStron */ 117133197c6aStron void mdb_dbi_close(MDB_env *env, MDB_dbi dbi); 117233197c6aStron 117333197c6aStron /** @brief Empty or delete+close a database. 117433197c6aStron * 11758bd9f7cdSchristos * See #mdb_dbi_close() for restrictions about closing the DB handle. 117633197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 117733197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 117833197c6aStron * @param[in] del 0 to empty the DB, 1 to delete it from the 117933197c6aStron * environment and close the DB handle. 118033197c6aStron * @return A non-zero error value on failure and 0 on success. 118133197c6aStron */ 118233197c6aStron int mdb_drop(MDB_txn *txn, MDB_dbi dbi, int del); 118333197c6aStron 118433197c6aStron /** @brief Set a custom key comparison function for a database. 118533197c6aStron * 118633197c6aStron * The comparison function is called whenever it is necessary to compare a 118733197c6aStron * key specified by the application with a key currently stored in the database. 118833197c6aStron * If no comparison function is specified, and no special key flags were specified 118933197c6aStron * with #mdb_dbi_open(), the keys are compared lexically, with shorter keys collating 119033197c6aStron * before longer keys. 119133197c6aStron * @warning This function must be called before any data access functions are used, 119233197c6aStron * otherwise data corruption may occur. The same comparison function must be used by every 119333197c6aStron * program accessing the database, every time the database is used. 119433197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 119533197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 119633197c6aStron * @param[in] cmp A #MDB_cmp_func function 119733197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 119833197c6aStron * errors are: 119933197c6aStron * <ul> 120033197c6aStron * <li>EINVAL - an invalid parameter was specified. 120133197c6aStron * </ul> 120233197c6aStron */ 120333197c6aStron int mdb_set_compare(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp); 120433197c6aStron 120533197c6aStron /** @brief Set a custom data comparison function for a #MDB_DUPSORT database. 120633197c6aStron * 120733197c6aStron * This comparison function is called whenever it is necessary to compare a data 120833197c6aStron * item specified by the application with a data item currently stored in the database. 120933197c6aStron * This function only takes effect if the database was opened with the #MDB_DUPSORT 121033197c6aStron * flag. 121133197c6aStron * If no comparison function is specified, and no special key flags were specified 121233197c6aStron * with #mdb_dbi_open(), the data items are compared lexically, with shorter items collating 121333197c6aStron * before longer items. 121433197c6aStron * @warning This function must be called before any data access functions are used, 121533197c6aStron * otherwise data corruption may occur. The same comparison function must be used by every 121633197c6aStron * program accessing the database, every time the database is used. 121733197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 121833197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 121933197c6aStron * @param[in] cmp A #MDB_cmp_func function 122033197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 122133197c6aStron * errors are: 122233197c6aStron * <ul> 122333197c6aStron * <li>EINVAL - an invalid parameter was specified. 122433197c6aStron * </ul> 122533197c6aStron */ 122633197c6aStron int mdb_set_dupsort(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp); 122733197c6aStron 122833197c6aStron /** @brief Set a relocation function for a #MDB_FIXEDMAP database. 122933197c6aStron * 123033197c6aStron * @todo The relocation function is called whenever it is necessary to move the data 123133197c6aStron * of an item to a different position in the database (e.g. through tree 123233197c6aStron * balancing operations, shifts as a result of adds or deletes, etc.). It is 123333197c6aStron * intended to allow address/position-dependent data items to be stored in 123433197c6aStron * a database in an environment opened with the #MDB_FIXEDMAP option. 123533197c6aStron * Currently the relocation feature is unimplemented and setting 123633197c6aStron * this function has no effect. 123733197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 123833197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 123933197c6aStron * @param[in] rel A #MDB_rel_func function 124033197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 124133197c6aStron * errors are: 124233197c6aStron * <ul> 124333197c6aStron * <li>EINVAL - an invalid parameter was specified. 124433197c6aStron * </ul> 124533197c6aStron */ 124633197c6aStron int mdb_set_relfunc(MDB_txn *txn, MDB_dbi dbi, MDB_rel_func *rel); 124733197c6aStron 124833197c6aStron /** @brief Set a context pointer for a #MDB_FIXEDMAP database's relocation function. 124933197c6aStron * 125033197c6aStron * See #mdb_set_relfunc and #MDB_rel_func for more details. 125133197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 125233197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 125333197c6aStron * @param[in] ctx An arbitrary pointer for whatever the application needs. 125433197c6aStron * It will be passed to the callback function set by #mdb_set_relfunc 125533197c6aStron * as its \b relctx parameter whenever the callback is invoked. 125633197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 125733197c6aStron * errors are: 125833197c6aStron * <ul> 125933197c6aStron * <li>EINVAL - an invalid parameter was specified. 126033197c6aStron * </ul> 126133197c6aStron */ 126233197c6aStron int mdb_set_relctx(MDB_txn *txn, MDB_dbi dbi, void *ctx); 126333197c6aStron 126433197c6aStron /** @brief Get items from a database. 126533197c6aStron * 126633197c6aStron * This function retrieves key/data pairs from the database. The address 126733197c6aStron * and length of the data associated with the specified \b key are returned 126833197c6aStron * in the structure to which \b data refers. 126933197c6aStron * If the database supports duplicate keys (#MDB_DUPSORT) then the 127033197c6aStron * first data item for the key will be returned. Retrieval of other 127133197c6aStron * items requires the use of #mdb_cursor_get(). 127233197c6aStron * 127333197c6aStron * @note The memory pointed to by the returned values is owned by the 127433197c6aStron * database. The caller need not dispose of the memory, and may not 127533197c6aStron * modify it in any way. For values returned in a read-only transaction 127633197c6aStron * any modification attempts will cause a SIGSEGV. 127733197c6aStron * @note Values returned from the database are valid only until a 127833197c6aStron * subsequent update operation, or the end of the transaction. 127933197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 128033197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 128133197c6aStron * @param[in] key The key to search for in the database 128233197c6aStron * @param[out] data The data corresponding to the key 128333197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 128433197c6aStron * errors are: 128533197c6aStron * <ul> 128633197c6aStron * <li>#MDB_NOTFOUND - the key was not in the database. 128733197c6aStron * <li>EINVAL - an invalid parameter was specified. 128833197c6aStron * </ul> 128933197c6aStron */ 129033197c6aStron int mdb_get(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data); 129133197c6aStron 129233197c6aStron /** @brief Store items into a database. 129333197c6aStron * 129433197c6aStron * This function stores key/data pairs in the database. The default behavior 129533197c6aStron * is to enter the new key/data pair, replacing any previously existing key 129633197c6aStron * if duplicates are disallowed, or adding a duplicate data item if 129733197c6aStron * duplicates are allowed (#MDB_DUPSORT). 129833197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 129933197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 130033197c6aStron * @param[in] key The key to store in the database 130133197c6aStron * @param[in,out] data The data to store 130233197c6aStron * @param[in] flags Special options for this operation. This parameter 130333197c6aStron * must be set to 0 or by bitwise OR'ing together one or more of the 130433197c6aStron * values described here. 130533197c6aStron * <ul> 130633197c6aStron * <li>#MDB_NODUPDATA - enter the new key/data pair only if it does not 130733197c6aStron * already appear in the database. This flag may only be specified 130833197c6aStron * if the database was opened with #MDB_DUPSORT. The function will 130933197c6aStron * return #MDB_KEYEXIST if the key/data pair already appears in the 131033197c6aStron * database. 131133197c6aStron * <li>#MDB_NOOVERWRITE - enter the new key/data pair only if the key 131233197c6aStron * does not already appear in the database. The function will return 131333197c6aStron * #MDB_KEYEXIST if the key already appears in the database, even if 131433197c6aStron * the database supports duplicates (#MDB_DUPSORT). The \b data 131533197c6aStron * parameter will be set to point to the existing item. 131633197c6aStron * <li>#MDB_RESERVE - reserve space for data of the given size, but 131733197c6aStron * don't copy the given data. Instead, return a pointer to the 131833197c6aStron * reserved space, which the caller can fill in later - before 131933197c6aStron * the next update operation or the transaction ends. This saves 132033197c6aStron * an extra memcpy if the data is being generated later. 13218bd9f7cdSchristos * LMDB does nothing else with this memory, the caller is expected 13228bd9f7cdSchristos * to modify all of the space requested. This flag must not be 13238bd9f7cdSchristos * specified if the database was opened with #MDB_DUPSORT. 132433197c6aStron * <li>#MDB_APPEND - append the given key/data pair to the end of the 13258bd9f7cdSchristos * database. This option allows fast bulk loading when keys are 13268bd9f7cdSchristos * already known to be in the correct order. Loading unsorted keys 13278bd9f7cdSchristos * with this flag will cause a #MDB_KEYEXIST error. 132833197c6aStron * <li>#MDB_APPENDDUP - as above, but for sorted dup data. 132933197c6aStron * </ul> 133033197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 133133197c6aStron * errors are: 133233197c6aStron * <ul> 133333197c6aStron * <li>#MDB_MAP_FULL - the database is full, see #mdb_env_set_mapsize(). 133433197c6aStron * <li>#MDB_TXN_FULL - the transaction has too many dirty pages. 133533197c6aStron * <li>EACCES - an attempt was made to write in a read-only transaction. 133633197c6aStron * <li>EINVAL - an invalid parameter was specified. 133733197c6aStron * </ul> 133833197c6aStron */ 133933197c6aStron int mdb_put(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data, 134033197c6aStron unsigned int flags); 134133197c6aStron 134233197c6aStron /** @brief Delete items from a database. 134333197c6aStron * 134433197c6aStron * This function removes key/data pairs from the database. 134533197c6aStron * If the database does not support sorted duplicate data items 134633197c6aStron * (#MDB_DUPSORT) the data parameter is ignored. 134733197c6aStron * If the database supports sorted duplicates and the data parameter 134833197c6aStron * is NULL, all of the duplicate data items for the key will be 134933197c6aStron * deleted. Otherwise, if the data parameter is non-NULL 135033197c6aStron * only the matching data item will be deleted. 135133197c6aStron * This function will return #MDB_NOTFOUND if the specified key/data 135233197c6aStron * pair is not in the database. 135333197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 135433197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 135533197c6aStron * @param[in] key The key to delete from the database 135633197c6aStron * @param[in] data The data to delete 135733197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 135833197c6aStron * errors are: 135933197c6aStron * <ul> 136033197c6aStron * <li>EACCES - an attempt was made to write in a read-only transaction. 136133197c6aStron * <li>EINVAL - an invalid parameter was specified. 136233197c6aStron * </ul> 136333197c6aStron */ 136433197c6aStron int mdb_del(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data); 136533197c6aStron 136633197c6aStron /** @brief Create a cursor handle. 136733197c6aStron * 136833197c6aStron * A cursor is associated with a specific transaction and database. 136933197c6aStron * A cursor cannot be used when its database handle is closed. Nor 137033197c6aStron * when its transaction has ended, except with #mdb_cursor_renew(). 137133197c6aStron * It can be discarded with #mdb_cursor_close(). 137233197c6aStron * A cursor in a write-transaction can be closed before its transaction 137333197c6aStron * ends, and will otherwise be closed when its transaction ends. 137433197c6aStron * A cursor in a read-only transaction must be closed explicitly, before 137533197c6aStron * or after its transaction ends. It can be reused with 137633197c6aStron * #mdb_cursor_renew() before finally closing it. 137733197c6aStron * @note Earlier documentation said that cursors in every transaction 137833197c6aStron * were closed when the transaction committed or aborted. 137933197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 138033197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 138133197c6aStron * @param[out] cursor Address where the new #MDB_cursor handle will be stored 138233197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 138333197c6aStron * errors are: 138433197c6aStron * <ul> 138533197c6aStron * <li>EINVAL - an invalid parameter was specified. 138633197c6aStron * </ul> 138733197c6aStron */ 138833197c6aStron int mdb_cursor_open(MDB_txn *txn, MDB_dbi dbi, MDB_cursor **cursor); 138933197c6aStron 139033197c6aStron /** @brief Close a cursor handle. 139133197c6aStron * 139233197c6aStron * The cursor handle will be freed and must not be used again after this call. 139333197c6aStron * Its transaction must still be live if it is a write-transaction. 139433197c6aStron * @param[in] cursor A cursor handle returned by #mdb_cursor_open() 139533197c6aStron */ 139633197c6aStron void mdb_cursor_close(MDB_cursor *cursor); 139733197c6aStron 139833197c6aStron /** @brief Renew a cursor handle. 139933197c6aStron * 140033197c6aStron * A cursor is associated with a specific transaction and database. 140133197c6aStron * Cursors that are only used in read-only 140233197c6aStron * transactions may be re-used, to avoid unnecessary malloc/free overhead. 140333197c6aStron * The cursor may be associated with a new read-only transaction, and 140433197c6aStron * referencing the same database handle as it was created with. 140533197c6aStron * This may be done whether the previous transaction is live or dead. 140633197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 140733197c6aStron * @param[in] cursor A cursor handle returned by #mdb_cursor_open() 140833197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 140933197c6aStron * errors are: 141033197c6aStron * <ul> 141133197c6aStron * <li>EINVAL - an invalid parameter was specified. 141233197c6aStron * </ul> 141333197c6aStron */ 141433197c6aStron int mdb_cursor_renew(MDB_txn *txn, MDB_cursor *cursor); 141533197c6aStron 141633197c6aStron /** @brief Return the cursor's transaction handle. 141733197c6aStron * 141833197c6aStron * @param[in] cursor A cursor handle returned by #mdb_cursor_open() 141933197c6aStron */ 142033197c6aStron MDB_txn *mdb_cursor_txn(MDB_cursor *cursor); 142133197c6aStron 142233197c6aStron /** @brief Return the cursor's database handle. 142333197c6aStron * 142433197c6aStron * @param[in] cursor A cursor handle returned by #mdb_cursor_open() 142533197c6aStron */ 142633197c6aStron MDB_dbi mdb_cursor_dbi(MDB_cursor *cursor); 142733197c6aStron 142833197c6aStron /** @brief Retrieve by cursor. 142933197c6aStron * 143033197c6aStron * This function retrieves key/data pairs from the database. The address and length 143133197c6aStron * of the key are returned in the object to which \b key refers (except for the 143233197c6aStron * case of the #MDB_SET option, in which the \b key object is unchanged), and 143333197c6aStron * the address and length of the data are returned in the object to which \b data 143433197c6aStron * refers. 143533197c6aStron * See #mdb_get() for restrictions on using the output values. 143633197c6aStron * @param[in] cursor A cursor handle returned by #mdb_cursor_open() 143733197c6aStron * @param[in,out] key The key for a retrieved item 143833197c6aStron * @param[in,out] data The data of a retrieved item 143933197c6aStron * @param[in] op A cursor operation #MDB_cursor_op 144033197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 144133197c6aStron * errors are: 144233197c6aStron * <ul> 144333197c6aStron * <li>#MDB_NOTFOUND - no matching key found. 144433197c6aStron * <li>EINVAL - an invalid parameter was specified. 144533197c6aStron * </ul> 144633197c6aStron */ 144733197c6aStron int mdb_cursor_get(MDB_cursor *cursor, MDB_val *key, MDB_val *data, 144833197c6aStron MDB_cursor_op op); 144933197c6aStron 145033197c6aStron /** @brief Store by cursor. 145133197c6aStron * 145233197c6aStron * This function stores key/data pairs into the database. 14538bd9f7cdSchristos * The cursor is positioned at the new item, or on failure usually near it. 14548bd9f7cdSchristos * @note Earlier documentation incorrectly said errors would leave the 14558bd9f7cdSchristos * state of the cursor unchanged. 145633197c6aStron * @param[in] cursor A cursor handle returned by #mdb_cursor_open() 145733197c6aStron * @param[in] key The key operated on. 145833197c6aStron * @param[in] data The data operated on. 145933197c6aStron * @param[in] flags Options for this operation. This parameter 146033197c6aStron * must be set to 0 or one of the values described here. 146133197c6aStron * <ul> 14628bd9f7cdSchristos * <li>#MDB_CURRENT - replace the item at the current cursor position. 14638bd9f7cdSchristos * The \b key parameter must still be provided, and must match it. 14648bd9f7cdSchristos * If using sorted duplicates (#MDB_DUPSORT) the data item must still 14658bd9f7cdSchristos * sort into the same place. This is intended to be used when the 14668bd9f7cdSchristos * new data is the same size as the old. Otherwise it will simply 14678bd9f7cdSchristos * perform a delete of the old record followed by an insert. 146833197c6aStron * <li>#MDB_NODUPDATA - enter the new key/data pair only if it does not 146933197c6aStron * already appear in the database. This flag may only be specified 147033197c6aStron * if the database was opened with #MDB_DUPSORT. The function will 147133197c6aStron * return #MDB_KEYEXIST if the key/data pair already appears in the 147233197c6aStron * database. 147333197c6aStron * <li>#MDB_NOOVERWRITE - enter the new key/data pair only if the key 147433197c6aStron * does not already appear in the database. The function will return 147533197c6aStron * #MDB_KEYEXIST if the key already appears in the database, even if 147633197c6aStron * the database supports duplicates (#MDB_DUPSORT). 147733197c6aStron * <li>#MDB_RESERVE - reserve space for data of the given size, but 147833197c6aStron * don't copy the given data. Instead, return a pointer to the 14798bd9f7cdSchristos * reserved space, which the caller can fill in later - before 14808bd9f7cdSchristos * the next update operation or the transaction ends. This saves 14818bd9f7cdSchristos * an extra memcpy if the data is being generated later. This flag 14828bd9f7cdSchristos * must not be specified if the database was opened with #MDB_DUPSORT. 148333197c6aStron * <li>#MDB_APPEND - append the given key/data pair to the end of the 148433197c6aStron * database. No key comparisons are performed. This option allows 148533197c6aStron * fast bulk loading when keys are already known to be in the 148633197c6aStron * correct order. Loading unsorted keys with this flag will cause 14878bd9f7cdSchristos * a #MDB_KEYEXIST error. 148833197c6aStron * <li>#MDB_APPENDDUP - as above, but for sorted dup data. 148933197c6aStron * <li>#MDB_MULTIPLE - store multiple contiguous data elements in a 149033197c6aStron * single request. This flag may only be specified if the database 149133197c6aStron * was opened with #MDB_DUPFIXED. The \b data argument must be an 149233197c6aStron * array of two MDB_vals. The mv_size of the first MDB_val must be 149333197c6aStron * the size of a single data element. The mv_data of the first MDB_val 149433197c6aStron * must point to the beginning of the array of contiguous data elements. 149533197c6aStron * The mv_size of the second MDB_val must be the count of the number 149633197c6aStron * of data elements to store. On return this field will be set to 149733197c6aStron * the count of the number of elements actually written. The mv_data 149833197c6aStron * of the second MDB_val is unused. 149933197c6aStron * </ul> 150033197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 150133197c6aStron * errors are: 150233197c6aStron * <ul> 150333197c6aStron * <li>#MDB_MAP_FULL - the database is full, see #mdb_env_set_mapsize(). 150433197c6aStron * <li>#MDB_TXN_FULL - the transaction has too many dirty pages. 15058bd9f7cdSchristos * <li>EACCES - an attempt was made to write in a read-only transaction. 150633197c6aStron * <li>EINVAL - an invalid parameter was specified. 150733197c6aStron * </ul> 150833197c6aStron */ 150933197c6aStron int mdb_cursor_put(MDB_cursor *cursor, MDB_val *key, MDB_val *data, 151033197c6aStron unsigned int flags); 151133197c6aStron 151233197c6aStron /** @brief Delete current key/data pair 151333197c6aStron * 151433197c6aStron * This function deletes the key/data pair to which the cursor refers. 15158da6f2f6Schristos * This does not invalidate the cursor, so operations such as MDB_NEXT 15168da6f2f6Schristos * can still be used on it. 15178da6f2f6Schristos * Both MDB_NEXT and MDB_GET_CURRENT will return the same record after 15188da6f2f6Schristos * this operation. 151933197c6aStron * @param[in] cursor A cursor handle returned by #mdb_cursor_open() 152033197c6aStron * @param[in] flags Options for this operation. This parameter 152133197c6aStron * must be set to 0 or one of the values described here. 152233197c6aStron * <ul> 152333197c6aStron * <li>#MDB_NODUPDATA - delete all of the data items for the current key. 152433197c6aStron * This flag may only be specified if the database was opened with #MDB_DUPSORT. 152533197c6aStron * </ul> 152633197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 152733197c6aStron * errors are: 152833197c6aStron * <ul> 15298bd9f7cdSchristos * <li>EACCES - an attempt was made to write in a read-only transaction. 153033197c6aStron * <li>EINVAL - an invalid parameter was specified. 153133197c6aStron * </ul> 153233197c6aStron */ 153333197c6aStron int mdb_cursor_del(MDB_cursor *cursor, unsigned int flags); 153433197c6aStron 153533197c6aStron /** @brief Return count of duplicates for current key. 153633197c6aStron * 153733197c6aStron * This call is only valid on databases that support sorted duplicate 153833197c6aStron * data items #MDB_DUPSORT. 153933197c6aStron * @param[in] cursor A cursor handle returned by #mdb_cursor_open() 154033197c6aStron * @param[out] countp Address where the count will be stored 154133197c6aStron * @return A non-zero error value on failure and 0 on success. Some possible 154233197c6aStron * errors are: 154333197c6aStron * <ul> 154433197c6aStron * <li>EINVAL - cursor is not initialized, or an invalid parameter was specified. 154533197c6aStron * </ul> 154633197c6aStron */ 154733197c6aStron int mdb_cursor_count(MDB_cursor *cursor, size_t *countp); 154833197c6aStron 154933197c6aStron /** @brief Compare two data items according to a particular database. 155033197c6aStron * 155133197c6aStron * This returns a comparison as if the two data items were keys in the 155233197c6aStron * specified database. 155333197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 155433197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 155533197c6aStron * @param[in] a The first item to compare 155633197c6aStron * @param[in] b The second item to compare 155733197c6aStron * @return < 0 if a < b, 0 if a == b, > 0 if a > b 155833197c6aStron */ 155933197c6aStron int mdb_cmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b); 156033197c6aStron 156133197c6aStron /** @brief Compare two data items according to a particular database. 156233197c6aStron * 156333197c6aStron * This returns a comparison as if the two items were data items of 156433197c6aStron * the specified database. The database must have the #MDB_DUPSORT flag. 156533197c6aStron * @param[in] txn A transaction handle returned by #mdb_txn_begin() 156633197c6aStron * @param[in] dbi A database handle returned by #mdb_dbi_open() 156733197c6aStron * @param[in] a The first item to compare 156833197c6aStron * @param[in] b The second item to compare 156933197c6aStron * @return < 0 if a < b, 0 if a == b, > 0 if a > b 157033197c6aStron */ 157133197c6aStron int mdb_dcmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b); 157233197c6aStron 157333197c6aStron /** @brief A callback function used to print a message from the library. 157433197c6aStron * 157533197c6aStron * @param[in] msg The string to be printed. 157633197c6aStron * @param[in] ctx An arbitrary context pointer for the callback. 157733197c6aStron * @return < 0 on failure, >= 0 on success. 157833197c6aStron */ 157933197c6aStron typedef int (MDB_msg_func)(const char *msg, void *ctx); 158033197c6aStron 158133197c6aStron /** @brief Dump the entries in the reader lock table. 158233197c6aStron * 158333197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 158433197c6aStron * @param[in] func A #MDB_msg_func function 158533197c6aStron * @param[in] ctx Anything the message function needs 158633197c6aStron * @return < 0 on failure, >= 0 on success. 158733197c6aStron */ 158833197c6aStron int mdb_reader_list(MDB_env *env, MDB_msg_func *func, void *ctx); 158933197c6aStron 159033197c6aStron /** @brief Check for stale entries in the reader lock table. 159133197c6aStron * 159233197c6aStron * @param[in] env An environment handle returned by #mdb_env_create() 159333197c6aStron * @param[out] dead Number of stale slots that were cleared 159433197c6aStron * @return 0 on success, non-zero on failure. 159533197c6aStron */ 159633197c6aStron int mdb_reader_check(MDB_env *env, int *dead); 159733197c6aStron /** @} */ 159833197c6aStron 159933197c6aStron #ifdef __cplusplus 160033197c6aStron } 160133197c6aStron #endif 16028bd9f7cdSchristos /** @page tools LMDB Command Line Tools 16038bd9f7cdSchristos The following describes the command line tools that are available for LMDB. 16048bd9f7cdSchristos \li \ref mdb_copy_1 16058bd9f7cdSchristos \li \ref mdb_dump_1 16068bd9f7cdSchristos \li \ref mdb_load_1 16078bd9f7cdSchristos \li \ref mdb_stat_1 16088bd9f7cdSchristos */ 16098bd9f7cdSchristos 161033197c6aStron #endif /* _LMDB_H_ */ 1611