libmdbx  0.12.1.0 (2022-08-24T16:24:22+03:00)
One of the fastest compact embeddable key-value ACID database without WAL.
mdbx.h File Reference

The libmdbx C API header file. More...

#include <stdarg.h>
#include <stddef.h>
#include <stdint.h>
#include <assert.h>
#include <errno.h>
#include <pthread.h>
#include <sys/types.h>
#include <sys/uio.h>

Go to the source code of this file.

Classes

struct  MDBX_version_info
 libmdbx version information More...
 
struct  MDBX_build_info
 libmdbx build information More...
 
struct  MDBX_stat
 Statistics for a database in the environment. More...
 
struct  MDBX_envinfo
 Information about the environment. More...
 
struct  MDBX_txn_info
 Information about the transaction. More...
 
struct  MDBX_commit_latency
 Latency of commit stages in 1/65536 of seconds units. More...
 
struct  MDBX_canary
 The fours integers markers (aka "canary") associated with the environment. More...
 
struct  MDBX_version_info.git
 
struct  MDBX_envinfo.mi_geo
 
struct  MDBX_envinfo.mi_bootid
 A mostly unique ID that is regenerated on each boot. More...
 
struct  MDBX_envinfo.mi_bootid.current
 
struct  MDBX_envinfo.mi_bootid.meta0
 
struct  MDBX_envinfo.mi_bootid.meta1
 
struct  MDBX_envinfo.mi_bootid.meta2
 
struct  MDBX_envinfo.mi_pgop_stat
 

Macros

#define LIBMDBX_H
 
#define MDBX_PURE_FUNCTION   [[gnu::pure]]
 The 'pure' function attribute for optimization. More...
 
#define MDBX_NOTHROW_PURE_FUNCTION   [[gnu::pure, gnu::nothrow]]
 The 'pure nothrow' function attribute for optimization. More...
 
#define MDBX_CONST_FUNCTION   [[gnu::const]]
 The 'const' function attribute for optimization. More...
 
#define MDBX_NOTHROW_CONST_FUNCTION   [[gnu::const, gnu::nothrow]]
 The 'const nothrow' function attribute for optimization. More...
 
#define MDBX_DEPRECATED   [[deprecated]]
 The 'deprecated' attribute to produce warnings when used. More...
 
#define LIBMDBX_INLINE_API(TYPE, NAME, ARGS)   static __inline TYPE NAME ARGS
 Auxiliary macro for robustly define the both inline version of API function and non-inline fallback dll-exported version for applications linked with old version of libmdbx, with a strictly ODR-common implementation. More...
 
#define MDBX_CXX17_NOEXCEPT   noexcept
 
#define MDBX_CXX01_CONSTEXPR   constexpr
 
#define MDBX_CXX01_CONSTEXPR_VAR   constexpr
 
#define MDBX_CXX11_CONSTEXPR   constexpr
 
#define MDBX_CXX11_CONSTEXPR_VAR   constexpr
 
#define MDBX_CXX14_CONSTEXPR   constexpr
 
#define MDBX_CXX14_CONSTEXPR_VAR   constexpr
 
#define MDBX_NORETURN   [[noreturn]]
 
#define MDBX_MAYBE_UNUSED   [[maybe_unused]]
 
#define MDBX_VERSION_MAJOR   0
 
#define MDBX_VERSION_MINOR   12
 
#define LIBMDBX_API
 
#define LIBMDBX_API_TYPE
 
#define LIBMDBX_VERINFO_API   __dll_export
 
#define MDBX_LOCKNAME   "/mdbx.lck"
 The name of the lock file in the environment without using MDBX_NOSUBDIR. More...
 
#define MDBX_DATANAME   "/mdbx.dat"
 The name of the data file in the environment without using MDBX_NOSUBDIR. More...
 
#define MDBX_LOCK_SUFFIX   "-lck"
 The suffix of the lock file when MDBX_NOSUBDIR is used. More...
 
#define MDBX_LOGGER_DONTCHANGE   ((MDBX_debug_func *)(intptr_t)-1)
 The "don't change `logger`" value for mdbx_setup_debug() More...
 
#define MDBX_MAP_RESIZED   MDBX_MAP_RESIZED_is_deprecated()
 
#define MDBX_EPSILON   ((MDBX_val *)((ptrdiff_t)-1))
 The EPSILON value for mdbx_estimate_range() More...
 
#define MDBX_PGWALK_MAIN   ((const char *)((ptrdiff_t)0))
 Pseudo-name for MainDB. More...
 
#define MDBX_PGWALK_GC   ((const char *)((ptrdiff_t)-1))
 Pseudo-name for GarbageCollectorDB. More...
 
#define MDBX_PGWALK_META   ((const char *)((ptrdiff_t)-2))
 Pseudo-name for MetaPages. More...
 

Typedefs

typedef int mdbx_filehandle_t
 
typedef pid_t mdbx_pid_t
 
typedef pthread_t mdbx_tid_t
 
typedef mode_t mdbx_mode_t
 
typedef struct MDBX_env MDBX_env
 Opaque structure for a database environment. More...
 
typedef struct MDBX_txn MDBX_txn
 Opaque structure for a transaction handle. More...
 
typedef uint32_t MDBX_dbi
 A handle for an individual database (key-value spaces) in the environment. More...
 
typedef struct MDBX_cursor MDBX_cursor
 Opaque structure for navigating through a database. More...
 
typedef struct iovec MDBX_val
 Generic structure used for passing keys and data in and out of the database. . More...
 
typedef enum MDBX_log_level_t MDBX_log_level_t
 
typedef enum MDBX_debug_flags_t MDBX_debug_flags_t
 
typedef void MDBX_debug_func(MDBX_log_level_t loglevel, const char *function, int line, const char *fmt, va_list args) 1
 A debug-logger callback function, called before printing the message and aborting. More...
 
typedef void MDBX_assert_func(const MDBX_env *env, const char *msg, const char *function, unsigned line) 1
 A callback function for most MDBX assert() failures, called before printing the message and aborting. More...
 
typedef enum MDBX_env_flags_t MDBX_env_flags_t
 
typedef enum MDBX_txn_flags_t MDBX_txn_flags_t
 
typedef enum MDBX_db_flags_t MDBX_db_flags_t
 
typedef enum MDBX_put_flags_t MDBX_put_flags_t
 
typedef enum MDBX_copy_flags_t MDBX_copy_flags_t
 
typedef enum MDBX_cursor_op MDBX_cursor_op
 
typedef enum MDBX_error_t MDBX_error_t
 
typedef enum MDBX_option_t MDBX_option_t
 
typedef enum MDBX_env_delete_mode_t MDBX_env_delete_mode_t
 
typedef int() MDBX_cmp_func(const MDBX_val *a, const MDBX_val *b) 1
 A callback function used to compare two keys in a database. More...
 
typedef enum MDBX_dbi_state_t MDBX_dbi_state_t
 
typedef int(* MDBX_preserve_func) (void *context, MDBX_val *target, const void *src, size_t bytes)
 
typedef int() MDBX_reader_list_func(void *ctx, int num, int slot, mdbx_pid_t pid, mdbx_tid_t thread, uint64_t txnid, uint64_t lag, size_t bytes_used, size_t bytes_retained) 1
 A callback function used to enumerate the reader lock table. More...
 
typedef int() MDBX_hsr_func(const MDBX_env *env, const MDBX_txn *txn, mdbx_pid_t pid, mdbx_tid_t tid, uint64_t laggard, unsigned gap, size_t space, int retry) 1
 A Handle-Slow-Readers callback function to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled. More...
 
typedef enum MDBX_page_type_t MDBX_page_type_t
 
typedef int MDBX_pgvisitor_func(const uint64_t pgno, const unsigned number, void *const ctx, const int deep, const char *const dbi, const size_t page_size, const MDBX_page_type_t type, const MDBX_error_t err, const size_t nentries, const size_t payload_bytes, const size_t header_bytes, const size_t unused_bytes) 1
 Callback function for traverse the b-tree. More...
 

Enumerations

enum  MDBX_constants { MDBX_MAX_DBI = UINT32_C(32765) , MDBX_MAXDATASIZE = UINT32_C(0x7fff0000) , MDBX_MIN_PAGESIZE = 256 , MDBX_MAX_PAGESIZE = 65536 }
 
enum  MDBX_log_level_t {
  MDBX_LOG_FATAL = 0 , MDBX_LOG_ERROR = 1 , MDBX_LOG_WARN = 2 , MDBX_LOG_NOTICE = 3 ,
  MDBX_LOG_VERBOSE = 4 , MDBX_LOG_DEBUG = 5 , MDBX_LOG_TRACE = 6 , MDBX_LOG_EXTRA = 7 ,
  MDBX_LOG_DONTCHANGE = -1
}
 
enum  MDBX_debug_flags_t {
  MDBX_DBG_NONE = 0 , MDBX_DBG_ASSERT = 1 , MDBX_DBG_AUDIT = 2 , MDBX_DBG_JITTER = 4 ,
  MDBX_DBG_DUMP = 8 , MDBX_DBG_LEGACY_MULTIOPEN = 16 , MDBX_DBG_LEGACY_OVERLAP = 32 , MDBX_DBG_DONT_UPGRADE = 64 ,
  MDBX_DBG_DONTCHANGE = -1
}
 Runtime debug flags. More...
 
enum  MDBX_env_flags_t {
  MDBX_ENV_DEFAULTS = 0 , MDBX_VALIDATION = UINT32_C(0x00002000) , MDBX_NOSUBDIR = UINT32_C(0x4000) , MDBX_RDONLY = UINT32_C(0x20000) ,
  MDBX_EXCLUSIVE = UINT32_C(0x400000) , MDBX_ACCEDE = UINT32_C(0x40000000) , MDBX_WRITEMAP = UINT32_C(0x80000) , MDBX_NOTLS = UINT32_C(0x200000) ,
  MDBX_NORDAHEAD = UINT32_C(0x800000) , MDBX_NOMEMINIT = UINT32_C(0x1000000) , MDBX_COALESCE = UINT32_C(0x2000000) , MDBX_LIFORECLAIM = UINT32_C(0x4000000) ,
  MDBX_PAGEPERTURB = UINT32_C(0x8000000) , MDBX_SYNC_DURABLE = 0 , MDBX_NOMETASYNC = UINT32_C(0x40000) , MDBX_SAFE_NOSYNC = UINT32_C(0x10000) ,
  MDBX_MAPASYNC = MDBX_SAFE_NOSYNC , MDBX_UTTERLY_NOSYNC = MDBX_SAFE_NOSYNC | UINT32_C(0x100000)
}
 Environment flags. More...
 
enum  MDBX_txn_flags_t {
  MDBX_TXN_READWRITE = 0 , MDBX_TXN_RDONLY = MDBX_RDONLY , MDBX_TXN_RDONLY_PREPARE = MDBX_RDONLY | MDBX_NOMEMINIT , MDBX_TXN_TRY = UINT32_C(0x10000000) ,
  MDBX_TXN_NOMETASYNC = MDBX_NOMETASYNC , MDBX_TXN_NOSYNC = MDBX_SAFE_NOSYNC , MDBX_TXN_INVALID = INT32_MIN , MDBX_TXN_FINISHED = 0x01 ,
  MDBX_TXN_ERROR = 0x02 , MDBX_TXN_DIRTY = 0x04 , MDBX_TXN_SPILLS = 0x08 , MDBX_TXN_HAS_CHILD = 0x10 ,
  MDBX_TXN_BLOCKED = MDBX_TXN_FINISHED | MDBX_TXN_ERROR | MDBX_TXN_HAS_CHILD
}
 
enum  MDBX_db_flags_t {
  MDBX_DB_DEFAULTS = 0 , MDBX_REVERSEKEY = UINT32_C(0x02) , MDBX_DUPSORT = UINT32_C(0x04) , MDBX_INTEGERKEY = UINT32_C(0x08) ,
  MDBX_DUPFIXED = UINT32_C(0x10) , MDBX_INTEGERDUP = UINT32_C(0x20) , MDBX_REVERSEDUP = UINT32_C(0x40) , MDBX_CREATE = UINT32_C(0x40000) ,
  MDBX_DB_ACCEDE = MDBX_ACCEDE
}
 Database flags. More...
 
enum  MDBX_put_flags_t {
  MDBX_UPSERT = 0 , MDBX_NOOVERWRITE = UINT32_C(0x10) , MDBX_NODUPDATA = UINT32_C(0x20) , MDBX_CURRENT = UINT32_C(0x40) ,
  MDBX_ALLDUPS = UINT32_C(0x80) , MDBX_RESERVE = UINT32_C(0x10000) , MDBX_APPEND = UINT32_C(0x20000) , MDBX_APPENDDUP = UINT32_C(0x40000) ,
  MDBX_MULTIPLE = UINT32_C(0x80000)
}
 Data changing flags. More...
 
enum  MDBX_copy_flags_t { MDBX_CP_DEFAULTS = 0 , MDBX_CP_COMPACT = 1u , MDBX_CP_FORCE_DYNAMIC_SIZE = 2u }
 Environment copy flags. More...
 
enum  MDBX_cursor_op {
  MDBX_FIRST , MDBX_FIRST_DUP , MDBX_GET_BOTH , MDBX_GET_BOTH_RANGE ,
  MDBX_GET_CURRENT , MDBX_GET_MULTIPLE , MDBX_LAST , MDBX_LAST_DUP ,
  MDBX_NEXT , MDBX_NEXT_DUP , MDBX_NEXT_MULTIPLE , MDBX_NEXT_NODUP ,
  MDBX_PREV , MDBX_PREV_DUP , MDBX_PREV_NODUP , MDBX_SET ,
  MDBX_SET_KEY , MDBX_SET_RANGE , MDBX_PREV_MULTIPLE , MDBX_SET_LOWERBOUND ,
  MDBX_SET_UPPERBOUND
}
 Cursor operationsThis is the set of all operations for retrieving data using a cursor. More...
 
enum  MDBX_error_t {
  MDBX_SUCCESS = 0 , MDBX_RESULT_FALSE = MDBX_SUCCESS , MDBX_RESULT_TRUE = -1 , MDBX_KEYEXIST = -30799 ,
  MDBX_FIRST_LMDB_ERRCODE = MDBX_KEYEXIST , MDBX_NOTFOUND = -30798 , MDBX_PAGE_NOTFOUND = -30797 , MDBX_CORRUPTED = -30796 ,
  MDBX_PANIC = -30795 , MDBX_VERSION_MISMATCH = -30794 , MDBX_INVALID = -30793 , MDBX_MAP_FULL = -30792 ,
  MDBX_DBS_FULL = -30791 , MDBX_READERS_FULL = -30790 , MDBX_TXN_FULL = -30788 , MDBX_CURSOR_FULL = -30787 ,
  MDBX_PAGE_FULL = -30786 , MDBX_UNABLE_EXTEND_MAPSIZE = -30785 , MDBX_INCOMPATIBLE = -30784 , MDBX_BAD_RSLOT = -30783 ,
  MDBX_BAD_TXN = -30782 , MDBX_BAD_VALSIZE = -30781 , MDBX_BAD_DBI = -30780 , MDBX_PROBLEM = -30779 ,
  MDBX_LAST_LMDB_ERRCODE = MDBX_PROBLEM , MDBX_BUSY = -30778 , MDBX_FIRST_ADDED_ERRCODE = MDBX_BUSY , MDBX_EMULTIVAL = -30421 ,
  MDBX_EBADSIGN = -30420 , MDBX_WANNA_RECOVERY = -30419 , MDBX_EKEYMISMATCH = -30418 , MDBX_TOO_LARGE = -30417 ,
  MDBX_THREAD_MISMATCH = -30416 , MDBX_TXN_OVERLAPPING = -30415 , MDBX_LAST_ADDED_ERRCODE = MDBX_TXN_OVERLAPPING , MDBX_ENODATA = 9919 ,
  MDBX_EINVAL = EINVAL , MDBX_EACCESS = EACCES , MDBX_ENOMEM = ENOMEM , MDBX_EROFS = EROFS ,
  MDBX_ENOSYS = ENOSYS , MDBX_EIO = EIO , MDBX_EPERM = EPERM , MDBX_EINTR = EINTR ,
  MDBX_ENOFILE = ENOENT , MDBX_EREMOTE = ENOTBLK
}
 Errors and return codes. More...
 
enum  MDBX_option_t {
  MDBX_opt_max_db , MDBX_opt_max_readers , MDBX_opt_sync_bytes , MDBX_opt_sync_period ,
  MDBX_opt_rp_augment_limit , MDBX_opt_loose_limit , MDBX_opt_dp_reserve_limit , MDBX_opt_txn_dp_limit ,
  MDBX_opt_txn_dp_initial , MDBX_opt_spill_max_denominator , MDBX_opt_spill_min_denominator , MDBX_opt_spill_parent4child_denominator ,
  MDBX_opt_merge_threshold_16dot16_percent
}
 MDBX environment options. More...
 
enum  MDBX_env_delete_mode_t { MDBX_ENV_JUST_DELETE = 0 , MDBX_ENV_ENSURE_UNUSED = 1 , MDBX_ENV_WAIT_FOR_UNUSED = 2 }
 Deletion modes for mdbx_env_delete(). More...
 
enum  MDBX_dbi_state_t { MDBX_DBI_DIRTY = 0x01 , MDBX_DBI_STALE = 0x02 , MDBX_DBI_FRESH = 0x04 , MDBX_DBI_CREAT = 0x08 }
 DBI state bits returted by mdbx_dbi_flags_ex() More...
 
enum  MDBX_page_type_t {
  MDBX_page_broken , MDBX_page_meta , MDBX_page_large , MDBX_page_branch ,
  MDBX_page_leaf , MDBX_page_dupfixed_leaf , MDBX_subpage_leaf , MDBX_subpage_dupfixed_leaf ,
  MDBX_subpage_broken
}
 Page types for traverse the b-tree. More...
 

Functions

LIBMDBX_API int mdbx_setup_debug (MDBX_log_level_t log_level, MDBX_debug_flags_t debug_flags, MDBX_debug_func *logger)
 Setup global log-level, debug options and debug logger. More...
 
LIBMDBX_API int mdbx_env_set_assert (MDBX_env *env, MDBX_assert_func *func)
 Set or reset the assert() callback of the environment. More...
 
LIBMDBX_API const char * mdbx_dump_val (const MDBX_val *key, char *const buf, const size_t bufsize)
 Dump given MDBX_val to the buffer. More...
 
LIBMDBX_API void mdbx_panic (const char *fmt,...) MDBX_PRINTF_ARGS(1
 Panics with message and causes abnormal process termination. More...
 
LIBMDBX_API void LIBMDBX_API void mdbx_assert_fail (const MDBX_env *env, const char *msg, const char *func, unsigned line)
 Panics with asserton failed message and causes abnormal process termination. More...
 
LIBMDBX_API const char * mdbx_strerror (int errnum)
 Return a string describing a given error code. More...
 
LIBMDBX_API const char * mdbx_strerror_r (int errnum, char *buf, size_t buflen)
 Return a string describing a given error code. More...
 
LIBMDBX_API const char * mdbx_liberr2str (int errnum)
 
LIBMDBX_API const char * mdbx_strerror_ANSI2OEM (int errnum)
 
LIBMDBX_API const char * mdbx_strerror_r_ANSI2OEM (int errnum, char *buf, size_t buflen)
 
LIBMDBX_API int mdbx_env_create (MDBX_env **penv)
 Create an MDBX environment instance. More...
 
LIBMDBX_API int mdbx_env_set_option (MDBX_env *env, const MDBX_option_t option, uint64_t value)
 Sets the value of a runtime options for an environment. More...
 
LIBMDBX_API int mdbx_env_get_option (const MDBX_env *env, const MDBX_option_t option, uint64_t *pvalue)
 Gets the value of runtime options from an environment. More...
 
LIBMDBX_API int mdbx_env_open (MDBX_env *env, const char *pathname, MDBX_env_flags_t flags, mdbx_mode_t mode)
 Open an environment instance. More...
 
LIBMDBX_API int mdbx_env_delete (const char *pathname, MDBX_env_delete_mode_t mode)
 Delete the environment's files in a proper and multiprocess-safe way. More...
 
LIBMDBX_API int mdbx_env_copy (MDBX_env *env, const char *dest, MDBX_copy_flags_t flags)
 Copy an MDBX environment to the specified path, with options. More...
 
LIBMDBX_API int mdbx_env_copy2fd (MDBX_env *env, mdbx_filehandle_t fd, MDBX_copy_flags_t flags)
 Copy an environment to the specified file descriptor, with options. More...
 
LIBMDBX_API int mdbx_env_stat_ex (const MDBX_env *env, const MDBX_txn *txn, MDBX_stat *stat, size_t bytes)
 Return statistics about the MDBX environment. More...
 
MDBX_DEPRECATED int mdbx_env_stat (const MDBX_env *env, MDBX_stat *stat, size_t bytes)
 Return statistics about the MDBX environment. More...
 
LIBMDBX_API int mdbx_env_info_ex (const MDBX_env *env, const MDBX_txn *txn, MDBX_envinfo *info, size_t bytes)
 Return information about the MDBX environment. More...
 
MDBX_DEPRECATED int mdbx_env_info (const MDBX_env *env, MDBX_envinfo *info, size_t bytes)
 Return information about the MDBX environment. More...
 
LIBMDBX_API int mdbx_env_sync_ex (MDBX_env *env, bool force, bool nonblock)
 Flush the environment data buffers to disk. More...
 
int mdbx_env_sync (MDBX_env *env)
 The shortcut to calling mdbx_env_sync_ex() with the force=true and nonblock=false arguments. More...
 
int mdbx_env_sync_poll (MDBX_env *env)
 The shortcut to calling mdbx_env_sync_ex() with the force=false and nonblock=true arguments. More...
 
int mdbx_env_set_syncbytes (MDBX_env *env, size_t threshold)
 Sets threshold to force flush the data buffers to disk, even any of MDBX_SAFE_NOSYNC flag in the environment. More...
 
int mdbx_env_get_syncbytes (const MDBX_env *env, size_t *threshold)
 Get threshold to force flush the data buffers to disk, even any of MDBX_SAFE_NOSYNC flag in the environment. More...
 
int mdbx_env_set_syncperiod (MDBX_env *env, unsigned seconds_16dot16)
 Sets relative period since the last unsteady commit to force flush the data buffers to disk, even of MDBX_SAFE_NOSYNC flag in the environment. More...
 
int mdbx_env_get_syncperiod (const MDBX_env *env, unsigned *period_seconds_16dot16)
 Get relative period since the last unsteady commit to force flush the data buffers to disk, even of MDBX_SAFE_NOSYNC flag in the environment. More...
 
LIBMDBX_API int mdbx_env_close_ex (MDBX_env *env, bool dont_sync)
 Close the environment and release the memory map. More...
 
int mdbx_env_close (MDBX_env *env)
 The shortcut to calling mdbx_env_close_ex() with the dont_sync=false argument. More...
 
LIBMDBX_API int mdbx_env_set_flags (MDBX_env *env, MDBX_env_flags_t flags, bool onoff)
 Set environment flags. More...
 
LIBMDBX_API int mdbx_env_get_flags (const MDBX_env *env, unsigned *flags)
 Get environment flags. More...
 
LIBMDBX_API int mdbx_env_get_path (const MDBX_env *env, const char **dest)
 Return the path that was used in mdbx_env_open(). More...
 
LIBMDBX_API int mdbx_env_get_fd (const MDBX_env *env, mdbx_filehandle_t *fd)
 Return the file descriptor for the given environment. More...
 
LIBMDBX_API int mdbx_env_set_geometry (MDBX_env *env, intptr_t size_lower, intptr_t size_now, intptr_t size_upper, intptr_t growth_step, intptr_t shrink_threshold, intptr_t pagesize)
 Set all size-related parameters of environment, including page size and the min/max size of the memory map. More...
 
MDBX_DEPRECATED int mdbx_env_set_mapsize (MDBX_env *env, size_t size)
 
LIBMDBX_API int mdbx_is_readahead_reasonable (size_t volume, intptr_t redundancy)
 Find out whether to use readahead or not, based on the given database size and the amount of available memory. More...
 
intptr_t mdbx_limits_pgsize_min (void)
 Returns the minimal database page size in bytes. More...
 
intptr_t mdbx_limits_pgsize_max (void)
 Returns the maximal database page size in bytes. More...
 
LIBMDBX_API intptr_t mdbx_limits_dbsize_min (intptr_t pagesize)
 Returns minimal database size in bytes for given page size, or -1 if pagesize is invalid. More...
 
LIBMDBX_API intptr_t mdbx_limits_dbsize_max (intptr_t pagesize)
 Returns maximal database size in bytes for given page size, or -1 if pagesize is invalid. More...
 
LIBMDBX_API intptr_t mdbx_limits_keysize_max (intptr_t pagesize, MDBX_db_flags_t flags)
 Returns maximal key size in bytes for given page size and database flags, or -1 if pagesize is invalid. More...
 
LIBMDBX_API intptr_t mdbx_limits_valsize_max (intptr_t pagesize, MDBX_db_flags_t flags)
 Returns maximal data size in bytes for given page size and database flags, or -1 if pagesize is invalid. More...
 
LIBMDBX_API intptr_t mdbx_limits_txnsize_max (intptr_t pagesize)
 Returns maximal write transaction size (i.e. limit for summary volume of dirty pages) in bytes for given page size, or -1 if pagesize is invalid. More...
 
int mdbx_env_set_maxreaders (MDBX_env *env, unsigned readers)
 Set the maximum number of threads/reader slots for for all processes interacts with the database. More...
 
int mdbx_env_get_maxreaders (const MDBX_env *env, unsigned *readers)
 Get the maximum number of threads/reader slots for the environment. More...
 
int mdbx_env_set_maxdbs (MDBX_env *env, MDBX_dbi dbs)
 Set the maximum number of named databases for the environment. More...
 
int mdbx_env_get_maxdbs (const MDBX_env *env, MDBX_dbi *dbs)
 Get the maximum number of named databases for the environment. More...
 
LIBMDBX_API size_t mdbx_default_pagesize (void)
 Returns the default size of database page for the current system. More...
 
LIBMDBX_API int mdbx_get_sysraminfo (intptr_t *page_size, intptr_t *total_pages, intptr_t *avail_pages)
 Returns basic information about system RAM. This function provides a portable way to get information about available RAM and can be useful in that it returns the same information that libmdbx uses internally to adjust various options and control readahead. More...
 
LIBMDBX_API int mdbx_env_get_maxkeysize_ex (const MDBX_env *env, MDBX_db_flags_t flags)
 Returns the maximum size of keys can put. More...
 
LIBMDBX_API int mdbx_env_get_maxvalsize_ex (const MDBX_env *env, MDBX_db_flags_t flags)
 Returns the maximum size of data we can put. More...
 
MDBX_DEPRECATED LIBMDBX_API int mdbx_env_get_maxkeysize (const MDBX_env *env)
 
LIBMDBX_API int mdbx_env_set_userctx (MDBX_env *env, void *ctx)
 Sets application information (a context pointer) associated with the environment. More...
 
LIBMDBX_API void * mdbx_env_get_userctx (const MDBX_env *env)
 Returns an application information (a context pointer) associated with the environment. More...
 
LIBMDBX_API int mdbx_txn_begin_ex (MDBX_env *env, MDBX_txn *parent, MDBX_txn_flags_t flags, MDBX_txn **txn, void *context)
 Create a transaction with a user provided context pointer for use with the environment. More...
 
int mdbx_txn_begin (MDBX_env *env, MDBX_txn *parent, MDBX_txn_flags_t flags, MDBX_txn **txn)
 Create a transaction for use with the environment. More...
 
LIBMDBX_API int mdbx_txn_set_userctx (MDBX_txn *txn, void *ctx)
 Sets application information associated (a context pointer) with the transaction. More...
 
LIBMDBX_API void * mdbx_txn_get_userctx (const MDBX_txn *txn)
 Returns an application information (a context pointer) associated with the transaction. More...
 
LIBMDBX_API int mdbx_txn_info (const MDBX_txn *txn, MDBX_txn_info *info, bool scan_rlt)
 Return information about the MDBX transaction. More...
 
LIBMDBX_API MDBX_envmdbx_txn_env (const MDBX_txn *txn)
 Returns the transaction's MDBX_env. More...
 
LIBMDBX_API int mdbx_txn_flags (const MDBX_txn *txn)
 Return the transaction's flags. More...
 
LIBMDBX_API uint64_t mdbx_txn_id (const MDBX_txn *txn)
 Return the transaction's ID. More...
 
LIBMDBX_API int mdbx_txn_commit_ex (MDBX_txn *txn, MDBX_commit_latency *latency)
 Commit all the operations of a transaction into the database and collect latency information. More...
 
int mdbx_txn_commit (MDBX_txn *txn)
 Commit all the operations of a transaction into the database. More...
 
LIBMDBX_API int mdbx_txn_abort (MDBX_txn *txn)
 Abandon all the operations of the transaction instead of saving them. More...
 
LIBMDBX_API int mdbx_txn_break (MDBX_txn *txn)
 Marks transaction as broken. More...
 
LIBMDBX_API int mdbx_txn_reset (MDBX_txn *txn)
 Reset a read-only transaction. More...
 
LIBMDBX_API int mdbx_txn_renew (MDBX_txn *txn)
 Renew a read-only transaction. More...
 
LIBMDBX_API int mdbx_canary_put (MDBX_txn *txn, const MDBX_canary *canary)
 Set integers markers (aka "canary") associated with the environment. More...
 
LIBMDBX_API int mdbx_canary_get (const MDBX_txn *txn, MDBX_canary *canary)
 Returns fours integers markers (aka "canary") associated with the environment. More...
 
LIBMDBX_API int mdbx_dbi_open (MDBX_txn *txn, const char *name, MDBX_db_flags_t flags, MDBX_dbi *dbi)
 Open or Create a database in the environment. More...
 
MDBX_DEPRECATED LIBMDBX_API int mdbx_dbi_open_ex (MDBX_txn *txn, const char *name, MDBX_db_flags_t flags, MDBX_dbi *dbi, MDBX_cmp_func *keycmp, MDBX_cmp_func *datacmp)
 
LIBMDBX_API uint64_t mdbx_key_from_jsonInteger (const int64_t json_integer)
 
LIBMDBX_API uint64_t mdbx_key_from_double (const double ieee754_64bit)
 
LIBMDBX_API uint64_t mdbx_key_from_ptrdouble (const double *const ieee754_64bit)
 
LIBMDBX_API uint32_t mdbx_key_from_float (const float ieee754_32bit)
 
LIBMDBX_API uint32_t mdbx_key_from_ptrfloat (const float *const ieee754_32bit)
 
uint64_t mdbx_key_from_int64 (const int64_t i64)
 
uint32_t mdbx_key_from_int32 (const int32_t i32)
 
LIBMDBX_API int64_t mdbx_jsonInteger_from_key (const MDBX_val)
 
LIBMDBX_API double mdbx_double_from_key (const MDBX_val)
 
LIBMDBX_API float mdbx_float_from_key (const MDBX_val)
 
LIBMDBX_API int32_t mdbx_int32_from_key (const MDBX_val)
 
LIBMDBX_API int64_t mdbx_int64_from_key (const MDBX_val)
 
LIBMDBX_API int mdbx_dbi_stat (MDBX_txn *txn, MDBX_dbi dbi, MDBX_stat *stat, size_t bytes)
 Retrieve statistics for a database. More...
 
LIBMDBX_API int mdbx_dbi_dupsort_depthmask (MDBX_txn *txn, MDBX_dbi dbi, uint32_t *mask)
 Retrieve depth (bitmask) information of nested dupsort (multi-value) B+trees for given database. More...
 
LIBMDBX_API int mdbx_dbi_flags_ex (MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags, unsigned *state)
 Retrieve the DB flags and status for a database handle. More...
 
int mdbx_dbi_flags (MDBX_txn *txn, MDBX_dbi dbi, unsigned *flags)
 The shortcut to calling mdbx_dbi_flags_ex() with state=NULL for discarding it result. More...
 
LIBMDBX_API int mdbx_dbi_close (MDBX_env *env, MDBX_dbi dbi)
 Close a database handle. Normally unnecessary. More...
 
LIBMDBX_API int mdbx_drop (MDBX_txn *txn, MDBX_dbi dbi, bool del)
 Empty or delete and close a database. More...
 
LIBMDBX_API int mdbx_get (MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, MDBX_val *data)
 Get items from a database. More...
 
LIBMDBX_API int mdbx_get_ex (MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, MDBX_val *data, size_t *values_count)
 Get items from a database and optionally number of data items for a given key. More...
 
LIBMDBX_API int mdbx_get_equal_or_great (MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, MDBX_val *data)
 Get equal or great item from a database. More...
 
LIBMDBX_API int mdbx_put (MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, MDBX_val *data, MDBX_put_flags_t flags)
 Store items into a database. More...
 
LIBMDBX_API int mdbx_replace (MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, MDBX_val *new_data, MDBX_val *old_data, MDBX_put_flags_t flags)
 Replace items in a database. More...
 
LIBMDBX_API int mdbx_replace_ex (MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, MDBX_val *new_data, MDBX_val *old_data, MDBX_put_flags_t flags, MDBX_preserve_func preserver, void *preserver_context)
 
LIBMDBX_API int mdbx_del (MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *key, const MDBX_val *data)
 Delete items from a database. More...
 
LIBMDBX_API MDBX_cursormdbx_cursor_create (void *context)
 Create a cursor handle but not bind it to transaction nor DBI handle. More...
 
LIBMDBX_API int mdbx_cursor_set_userctx (MDBX_cursor *cursor, void *ctx)
 Set application information associated with the MDBX_cursor. More...
 
LIBMDBX_API void * mdbx_cursor_get_userctx (const MDBX_cursor *cursor)
 Get the application information associated with the MDBX_cursor. More...
 
LIBMDBX_API int mdbx_cursor_bind (MDBX_txn *txn, MDBX_cursor *cursor, MDBX_dbi dbi)
 Bind cursor to specified transaction and DBI handle. More...
 
LIBMDBX_API int mdbx_cursor_open (MDBX_txn *txn, MDBX_dbi dbi, MDBX_cursor **cursor)
 Create a cursor handle for the specified transaction and DBI handle. More...
 
LIBMDBX_API void mdbx_cursor_close (MDBX_cursor *cursor)
 Close a cursor handle. More...
 
LIBMDBX_API int mdbx_cursor_renew (MDBX_txn *txn, MDBX_cursor *cursor)
 Renew a cursor handle. More...
 
LIBMDBX_API MDBX_txnmdbx_cursor_txn (const MDBX_cursor *cursor)
 Return the cursor's transaction handle. More...
 
LIBMDBX_API MDBX_dbi mdbx_cursor_dbi (const MDBX_cursor *cursor)
 Return the cursor's database handle. More...
 
LIBMDBX_API int mdbx_cursor_copy (const MDBX_cursor *src, MDBX_cursor *dest)
 Copy cursor position and state. More...
 
LIBMDBX_API int mdbx_cursor_get (MDBX_cursor *cursor, MDBX_val *key, MDBX_val *data, MDBX_cursor_op op)
 Retrieve by cursor. More...
 
LIBMDBX_API int mdbx_cursor_get_batch (MDBX_cursor *cursor, size_t *count, MDBX_val *pairs, size_t limit, MDBX_cursor_op op)
 Retrieve multiple non-dupsort key/value pairs by cursor. More...
 
LIBMDBX_API int mdbx_cursor_put (MDBX_cursor *cursor, const MDBX_val *key, MDBX_val *data, MDBX_put_flags_t flags)
 Store by cursor. More...
 
LIBMDBX_API int mdbx_cursor_del (MDBX_cursor *cursor, MDBX_put_flags_t flags)
 Delete current key/data pair. More...
 
LIBMDBX_API int mdbx_cursor_count (const MDBX_cursor *cursor, size_t *pcount)
 Return count of duplicates for current key. More...
 
LIBMDBX_API int mdbx_cursor_eof (const MDBX_cursor *cursor)
 Determines whether the cursor is pointed to a key-value pair or not, i.e. was not positioned or points to the end of data. More...
 
LIBMDBX_API int mdbx_cursor_on_first (const MDBX_cursor *cursor)
 Determines whether the cursor is pointed to the first key-value pair or not. More...
 
LIBMDBX_API int mdbx_cursor_on_last (const MDBX_cursor *cursor)
 Determines whether the cursor is pointed to the last key-value pair or not. More...
 
LIBMDBX_API int mdbx_estimate_distance (const MDBX_cursor *first, const MDBX_cursor *last, ptrdiff_t *distance_items)
 Estimates the distance between cursors as a number of elements. More...
 
LIBMDBX_API int mdbx_estimate_move (const MDBX_cursor *cursor, MDBX_val *key, MDBX_val *data, MDBX_cursor_op move_op, ptrdiff_t *distance_items)
 Estimates the move distance. More...
 
LIBMDBX_API int mdbx_estimate_range (MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *begin_key, MDBX_val *begin_data, MDBX_val *end_key, MDBX_val *end_data, ptrdiff_t *distance_items)
 Estimates the size of a range as a number of elements. More...
 
LIBMDBX_API int mdbx_is_dirty (const MDBX_txn *txn, const void *ptr)
 Determines whether the given address is on a dirty database page of the transaction or not. More...
 
LIBMDBX_API int mdbx_dbi_sequence (MDBX_txn *txn, MDBX_dbi dbi, uint64_t *result, uint64_t increment)
 Sequence generation for a database. More...
 
LIBMDBX_API int mdbx_cmp (const MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *a, const MDBX_val *b)
 Compare two keys according to a particular database. More...
 
LIBMDBX_API MDBX_cmp_funcmdbx_get_keycmp (MDBX_db_flags_t flags)
 Returns default internal key's comparator for given database flags. More...
 
LIBMDBX_API int mdbx_dcmp (const MDBX_txn *txn, MDBX_dbi dbi, const MDBX_val *a, const MDBX_val *b)
 Compare two data items according to a particular database. More...
 
LIBMDBX_API MDBX_cmp_funcmdbx_get_datacmp (MDBX_db_flags_t flags)
 Returns default internal data's comparator for given database flags. More...
 
LIBMDBX_API int mdbx_reader_list (const MDBX_env *env, MDBX_reader_list_func *func, void *ctx)
 Enumerate the entries in the reader lock table. More...
 
LIBMDBX_API int mdbx_reader_check (MDBX_env *env, int *dead)
 Check for stale entries in the reader lock table. More...
 
MDBX_DEPRECATED LIBMDBX_API int mdbx_txn_straggler (const MDBX_txn *txn, int *percent)
 Returns a lag of the reading for the given transaction. More...
 
LIBMDBX_API int mdbx_thread_register (const MDBX_env *env)
 Registers the current thread as a reader for the environment. More...
 
LIBMDBX_API int mdbx_thread_unregister (const MDBX_env *env)
 Unregisters the current thread as a reader for the environment. More...
 
LIBMDBX_API int mdbx_env_set_hsr (MDBX_env *env, MDBX_hsr_func *hsr_callback)
 Sets a Handle-Slow-Readers callback to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled. More...
 
LIBMDBX_API MDBX_hsr_funcmdbx_env_get_hsr (const MDBX_env *env)
 Gets current Handle-Slow-Readers callback used to resolve database full/overflow issue due to a reader(s) which prevents the old data from being recycled. More...
 
LIBMDBX_API int mdbx_env_pgwalk (MDBX_txn *txn, MDBX_pgvisitor_func *visitor, void *ctx, bool dont_check_keys_ordering)
 B-tree traversal function. More...
 
LIBMDBX_API int mdbx_env_open_for_recovery (MDBX_env *env, const char *pathname, unsigned target_meta, bool writeable)
 Open an environment instance using specific meta-page for checking and recovery. More...
 
LIBMDBX_API int mdbx_env_turn_for_recovery (MDBX_env *env, unsigned target_meta)
 Turn database to the specified meta-page. More...
 

Variables

LIBMDBX_VERINFO_API const struct MDBX_version_info mdbx_version
 libmdbx version information More...
 
LIBMDBX_VERINFO_API const struct MDBX_build_info mdbx_build
 libmdbx build information More...
 

Detailed Description

The libmdbx C API header file.

Macro Definition Documentation

◆ LIBMDBX_H

#define LIBMDBX_H

libmdbx is an extremely fast, compact, powerful, embedded, transactional key-value store database, with permissive license. MDBX has a specific set of properties and capabilities, focused on creating unique lightweight solutions with extraordinary performance.

libmdbx is superior to LMDB in terms of features and reliability, not inferior in performance. In comparison to LMDB, libmdbx makes many things just work perfectly, not silently and catastrophically break down. libmdbx supports Linux, Windows, MacOS, OSX, iOS, Android, FreeBSD, DragonFly, Solaris, OpenSolaris, OpenIndiana, NetBSD, OpenBSD and other systems compliant with POSIX.1-2008.

The origin has been migrated to GitFlic since on 2022-04-15 the Github administration, without any warning nor explanation, deleted libmdbx along with a lot of other projects, simultaneously blocking access for many developers. For the same reason Github is blacklisted forever.

The Future will (be) Positive. Всё будет хорошо.

LICENSE & COPYRIGHT

Authors
Copyright (c) 2015-2022, Leonid Yuriev leo@y.nosp@m.urie.nosp@m.v.ru and other libmdbx authors: please see AUTHORS file.

A copy of this license is available in the file LICENSE in the top-level directory of the distribution or, alternatively, at http://www.OpenLDAP.org/license.html.


This code is derived from "LMDB engine" written by Howard Chu (Symas Corporation), which itself derived from btree.c written by Martin Hedenfalk.


Portions Copyright 2011-2015 Howard Chu, Symas Corp. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted only as authorized by the OpenLDAP Public License.

A copy of this license is available in the file LICENSE in the top-level directory of the distribution or, alternatively, at http://www.OpenLDAP.org/license.html.


Portions Copyright (c) 2009, 2010 Martin Hedenfalk marti.nosp@m.n@bz.nosp@m.ero.s.nosp@m.e

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.