* corrupt the database. Of course if your application code is known to
* be bug-free (...) then this is not an issue.
*
+ * If this is your first time using a transactional embedded key/value
+ * store, you may find the \ref starting page to be helpful.
+ *
* @section caveats_sec Caveats
* Troubleshooting the lock file, plus semaphores on BSD systems:
*
* access to locks and lock file. Exceptions: On read-only filesystems
* or with the #MDB_NOLOCK flag described under #mdb_env_open().
*
+ * - An LMDB configuration will often reserve considerable \b unused
+ * memory address space and maybe file size for future growth.
+ * This does not use actual memory or disk space, but users may need
+ * to understand the difference so they won't be scared off.
+ *
* - By default, in versions before 0.9.10, unused portions of the data
* file might receive garbage data from memory freed by other code.
* (This does not happen when using the #MDB_WRITEMAP flag.) As of
*
* @author Howard Chu, Symas Corporation.
*
- * @copyright Copyright 2011-2015 Howard Chu, Symas Corp. All rights reserved.
+ * @copyright Copyright 2011-2016 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
#define _LMDB_H_
#include <sys/types.h>
+#include <inttypes.h>
+#include <limits.h>
#ifdef __cplusplus
extern "C" {
typedef mode_t mdb_mode_t;
#endif
+#ifdef _WIN32
+# define MDB_FMT_Z "I"
+#else
+# define MDB_FMT_Z "z" /**< printf/scanf format modifier for size_t */
+#endif
+
+#ifndef MDB_VL32
+typedef size_t mdb_size_t;
+# define MDB_SIZE_MAX SIZE_MAX /**< max #mdb_size_t */
+/** #mdb_size_t printf formats, \b t = one of [diouxX] without quotes */
+# define MDB_PRIy(t) MDB_FMT_Z #t
+/** #mdb_size_t scanf formats, \b t = one of [dioux] without quotes */
+# define MDB_SCNy(t) MDB_FMT_Z #t
+#else
+typedef uint64_t mdb_size_t;
+# define MDB_SIZE_MAX UINT64_MAX
+# define MDB_PRIy(t) PRI##t##64
+# define MDB_SCNy(t) SCN##t##64
+# define mdb_env_create mdb_env_create_vl32 /**< Prevent mixing with non-VL32 builds */
+#endif
+
/** An abstraction for a file handle.
* On POSIX systems file handles are small integers. On Windows
* they're opaque pointers.
/** Library minor version */
#define MDB_VERSION_MINOR 9
/** Library patch version */
-#define MDB_VERSION_PATCH 16
+#define MDB_VERSION_PATCH 70
/** Combine args a,b,c into a single integer for easy version comparisons */
#define MDB_VERINT(a,b,c) (((a) << 24) | ((b) << 16) | (c))
MDB_VERINT(MDB_VERSION_MAJOR,MDB_VERSION_MINOR,MDB_VERSION_PATCH)
/** The release date of this library version */
-#define MDB_VERSION_DATE "August 14, 2015"
+#define MDB_VERSION_DATE "December 19, 2015"
/** A stringifier for the version info */
#define MDB_VERSTR(a,b,c,d) "LMDB " #a "." #b "." #c ": (" d ")"
#define MDB_REVERSEKEY 0x02
/** use sorted duplicates */
#define MDB_DUPSORT 0x04
- /** numeric keys in native byte order: either unsigned int or size_t.
+ /** numeric keys in native byte order, either unsigned int or #mdb_size_t.
+ * (lmdb expects 32-bit int <= size_t <= 32/64-bit mdb_size_t.)
* The keys must all be of the same size. */
#define MDB_INTEGERKEY 0x08
/** with #MDB_DUPSORT, sorted dup items have fixed size */
MDB_PREV_NODUP, /**< Position at last data item of previous key */
MDB_SET, /**< Position at specified key */
MDB_SET_KEY, /**< Position at specified key, return key + data */
- MDB_SET_RANGE /**< Position at first key greater than or equal to specified key. */
+ MDB_SET_RANGE, /**< Position at first key greater than or equal to specified key. */
+ MDB_PREV_MULTIPLE /**< Position at previous page and return key and up to
+ a page of duplicate data items. Only for #MDB_DUPFIXED */
} MDB_cursor_op;
/** @defgroup errors Return Codes
#define MDB_BAD_VALSIZE (-30781)
/** The specified DBI was changed unexpectedly */
#define MDB_BAD_DBI (-30780)
+ /** Unexpected problem - txn should abort */
+#define MDB_PROBLEM (-30779)
/** The last defined error code */
-#define MDB_LAST_ERRCODE MDB_BAD_DBI
+#define MDB_LAST_ERRCODE MDB_PROBLEM
/** @} */
/** @brief Statistics for a database in the environment */
unsigned int ms_psize; /**< Size of a database page.
This is currently the same for all databases. */
unsigned int ms_depth; /**< Depth (height) of the B-tree */
- size_t ms_branch_pages; /**< Number of internal (non-leaf) pages */
- size_t ms_leaf_pages; /**< Number of leaf pages */
- size_t ms_overflow_pages; /**< Number of overflow pages */
- size_t ms_entries; /**< Number of data items */
+ mdb_size_t ms_branch_pages; /**< Number of internal (non-leaf) pages */
+ mdb_size_t ms_leaf_pages; /**< Number of leaf pages */
+ mdb_size_t ms_overflow_pages; /**< Number of overflow pages */
+ mdb_size_t ms_entries; /**< Number of data items */
} MDB_stat;
/** @brief Information about the environment */
typedef struct MDB_envinfo {
void *me_mapaddr; /**< Address of map, if fixed */
- size_t me_mapsize; /**< Size of the data memory map */
- size_t me_last_pgno; /**< ID of the last used page */
- size_t me_last_txnid; /**< ID of the last committed transaction */
+ mdb_size_t me_mapsize; /**< Size of the data memory map */
+ mdb_size_t me_last_pgno; /**< ID of the last used page */
+ mdb_size_t me_last_txnid; /**< ID of the last committed transaction */
unsigned int me_maxreaders; /**< max reader slots in the environment */
unsigned int me_numreaders; /**< max reader slots used in the environment */
} MDB_envinfo;
* allowed. LMDB will still modify the lock file - except on read-only
* filesystems, where LMDB does not use locks.
* <li>#MDB_WRITEMAP
- * Use a writeable memory map unless MDB_RDONLY is set. This is faster
- * and uses fewer mallocs, but loses protection from application bugs
+ * Use a writeable memory map unless MDB_RDONLY is set. This uses
+ * fewer mallocs but loses protection from application bugs
* like wild pointer writes and other bad updates into the database.
+ * This may be slightly faster for DBs that fit entirely in RAM, but
+ * is slower for DBs larger than RAM.
* Incompatible with nested transactions.
* Do not mix processes with and without MDB_WRITEMAP on the same
* environment. This can defeat durability (#mdb_env_sync etc).
* <li>#MDB_CP_COMPACT - Perform compaction while copying: omit free
* pages and sequentially renumber all pages in output. This option
* consumes more CPU and runs more slowly than the default.
+ * Currently it fails if the environment has suffered a page leak.
* </ul>
* @return A non-zero error value on failure and 0 on success.
*/
* an active write transaction.
* </ul>
*/
-int mdb_env_set_mapsize(MDB_env *env, size_t size);
+int mdb_env_set_mapsize(MDB_env *env, mdb_size_t size);
/** @brief Set the maximum number of threads/reader slots for the environment.
*
* @param[in] txn A transaction handle returned by #mdb_txn_begin()
* @return A transaction ID, valid if input is an active transaction.
*/
-size_t mdb_txn_id(MDB_txn *txn);
+mdb_size_t mdb_txn_id(MDB_txn *txn);
/** @brief Commit all the operations of a transaction into the database.
*
* keys must be unique and may have only a single data item.
* <li>#MDB_INTEGERKEY
* Keys are binary integers in native byte order, either unsigned int
- * or size_t, and will be sorted as such.
+ * or #mdb_size_t, and will be sorted as such.
+ * (lmdb expects 32-bit int <= size_t <= 32/64-bit mdb_size_t.)
* The keys must all be of the same size.
* <li>#MDB_DUPFIXED
* This flag may only be used in combination with #MDB_DUPSORT. This option
* the database supports duplicates (#MDB_DUPSORT).
* <li>#MDB_RESERVE - reserve space for data of the given size, but
* don't copy the given data. Instead, return a pointer to the
- * reserved space, which the caller can fill in later. This saves
+ * reserved space, which the caller can fill in later - before
+ * the next update operation or the transaction ends. This saves
* an extra memcpy if the data is being generated later. This flag
* must not be specified if the database was opened with #MDB_DUPSORT.
* <li>#MDB_APPEND - append the given key/data pair to the end of the
* <li>EINVAL - cursor is not initialized, or an invalid parameter was specified.
* </ul>
*/
-int mdb_cursor_count(MDB_cursor *cursor, size_t *countp);
+int mdb_cursor_count(MDB_cursor *cursor, mdb_size_t *countp);
/** @brief Compare two data items according to a particular database.
*