diff --git a/mdbx.h b/mdbx.h index 2b3a8a8a..05c4205f 100644 --- a/mdbx.h +++ b/mdbx.h @@ -63,334 +63,313 @@ extern "C" { #define MDB_VERSION_FULL \ MDB_VERINT(MDB_VERSION_MAJOR, MDB_VERSION_MINOR, MDB_VERSION_PATCH) -/** The release date of this library version */ +/* The release date of this library version */ #define MDB_VERSION_DATE "DEVEL" -/** A stringifier for the version info */ +/* A stringifier for the version info */ #define MDB_VERSTR(a, b, c, d) \ "MDBX " #a "." #b "." #c ": (" d ", https://github.com/ReOpen/libmdbx)" -/** A helper for the stringifier macro */ +/* A helper for the stringifier macro */ #define MDB_VERFOO(a, b, c, d) MDB_VERSTR(a, b, c, d) -/** The full library version as a C string */ +/* The full library version as a C string */ #define MDB_VERSION_STRING \ MDB_VERFOO(MDB_VERSION_MAJOR, MDB_VERSION_MINOR, MDB_VERSION_PATCH, \ MDB_VERSION_DATE) -/** @} */ -/** @brief Opaque structure for a database environment. +/* Opaque structure for a database environment. * * A DB environment supports multiple databases, all residing in the same * shared-memory map. */ typedef struct MDB_env MDB_env; -/** @brief Opaque structure for a transaction handle. +/* Opaque structure for a transaction handle. * * All database operations require a transaction handle. Transactions may be * read-only or read-write. */ typedef struct MDB_txn MDB_txn; -/** @brief A handle for an individual database in the DB environment. */ +/* A handle for an individual database in the DB environment. */ typedef unsigned MDB_dbi; -/** @brief Opaque structure for navigating through a database */ +/* Opaque structure for navigating through a database */ typedef struct MDB_cursor MDB_cursor; -/** @brief Generic structure used for passing keys and data in and out +/* Generic structure used for passing keys and data in and out * of the database. * * Values returned from the database are valid only until a subsequent * update operation, or the end of the transaction. Do not modify or * free them, they commonly point into the database itself. * - * Key sizes must be between 1 and #mdbx_env_get_maxkeysize() inclusive. - * The same applies to data sizes in databases with the #MDB_DUPSORT flag. + * Key sizes must be between 1 and mdbx_env_get_maxkeysize() inclusive. + * The same applies to data sizes in databases with the MDB_DUPSORT flag. * Other data items can in theory be from 0 to 0xffffffff bytes long. */ typedef struct iovec MDB_val; #define mv_size iov_len #define mv_data iov_base -/** @brief A callback function used to compare two keys in a database */ +/* A callback function used to compare two keys in a database */ typedef int(MDB_cmp_func)(const MDB_val *a, const MDB_val *b); -/** @defgroup mdbx_env Environment Flags - * @{ - */ -/** mmap at a fixed address (experimental) */ +/* Environment Flags */ +/* mmap at a fixed address (experimental) */ #define MDB_FIXEDMAP 0x01 -/** no environment directory */ +/* no environment directory */ #define MDB_NOSUBDIR 0x4000 -/** don't fsync after commit */ +/* don't fsync after commit */ #define MDB_NOSYNC 0x10000 -/** read only */ +/* read only */ #define MDB_RDONLY 0x20000 -/** don't fsync metapage after commit */ +/* don't fsync metapage after commit */ #define MDB_NOMETASYNC 0x40000 -/** use writable mmap */ +/* use writable mmap */ #define MDB_WRITEMAP 0x80000 -/** use asynchronous msync when #MDB_WRITEMAP is used */ +/* use asynchronous msync when MDB_WRITEMAP is used */ #define MDB_MAPASYNC 0x100000 -/** tie reader locktable slots to #MDB_txn objects instead of to threads */ +/* tie reader locktable slots to MDB_txn objects instead of to threads */ #define MDB_NOTLS 0x200000 -/** don't do any locking, caller must manage their own locks +/* don't do any locking, caller must manage their own locks * WARNING: libmdbx don't support this mode. */ #define MDB_NOLOCK__UNSUPPORTED 0x400000 -/** don't do readahead */ +/* don't do readahead */ #define MDB_NORDAHEAD 0x800000 -/** don't initialize malloc'd memory before writing to datafile */ +/* don't initialize malloc'd memory before writing to datafile */ #define MDB_NOMEMINIT 0x1000000 #if MDBX_MODE_ENABLED -/** aim to coalesce FreeDB records */ +/* aim to coalesce FreeDB records */ #define MDBX_COALESCE 0x2000000 -/** LIFO policy for reclaiming FreeDB records */ +/* LIFO policy for reclaiming FreeDB records */ #define MDBX_LIFORECLAIM 0x4000000 #endif /* MDBX_MODE_ENABLED */ -/** make a steady-sync only on close and explicit env-sync */ +/* make a steady-sync only on close and explicit env-sync */ #define MDBX_UTTERLY_NOSYNC (MDB_NOSYNC | MDB_MAPASYNC) -/** debuging option, fill/perturb released pages */ +/* debuging option, fill/perturb released pages */ #define MDBX_PAGEPERTURB 0x8000000 -/** @} */ -/** @defgroup mdbx_dbi_open Database Flags - * @{ - */ -/** use reverse string keys */ +/* Database Flags */ +/* use reverse string keys */ #define MDB_REVERSEKEY 0x02 -/** use sorted duplicates */ +/* use sorted duplicates */ #define MDB_DUPSORT 0x04 -/** numeric keys in native byte order, either unsigned int or #mdbx_size_t. +/* numeric keys in native byte order, either unsigned int or mdbx_size_t. * (lmdb expects 32-bit int <= size_t <= 32/64-bit mdbx_size_t.) * The keys must all be of the same size. */ #define MDB_INTEGERKEY 0x08 -/** with #MDB_DUPSORT, sorted dup items have fixed size */ +/* with MDB_DUPSORT, sorted dup items have fixed size */ #define MDB_DUPFIXED 0x10 -/** with #MDB_DUPSORT, dups are #MDB_INTEGERKEY-style integers */ +/* with MDB_DUPSORT, dups are MDB_INTEGERKEY-style integers */ #define MDB_INTEGERDUP 0x20 -/** with #MDB_DUPSORT, use reverse string dups */ +/* with MDB_DUPSORT, use reverse string dups */ #define MDB_REVERSEDUP 0x40 -/** create DB if not already existing */ +/* create DB if not already existing */ #define MDB_CREATE 0x40000 -/** @} */ -/** @defgroup mdbx_put Write Flags - * @{ - */ -/** For put: Don't write if the key already exists. */ +/* Write Flags */ +/* For put: Don't write if the key already exists. */ #define MDB_NOOVERWRITE 0x10 -/** Only for #MDB_DUPSORT
- * For put: don't write if the key and data pair already exist.
+/* Only for MDB_DUPSORT + * For put: don't write if the key and data pair already exist. * For mdbx_cursor_del: remove all duplicate data items. */ #define MDB_NODUPDATA 0x20 -/** For mdbx_cursor_put: overwrite the current key/data pair +/* For mdbx_cursor_put: overwrite the current key/data pair * MDBX allows this flag for mdbx_put() for explicit overwrite/update without * insertion. */ #define MDB_CURRENT 0x40 -/** For put: Just reserve space for data, don't copy it. Return a +/* For put: Just reserve space for data, don't copy it. Return a * pointer to the reserved space. */ #define MDB_RESERVE 0x10000 -/** Data is being appended, don't split full pages. */ +/* Data is being appended, don't split full pages. */ #define MDB_APPEND 0x20000 -/** Duplicate data is being appended, don't split full pages. */ +/* Duplicate data is being appended, don't split full pages. */ #define MDB_APPENDDUP 0x40000 -/** Store multiple data items in one call. Only for #MDB_DUPFIXED. */ +/* Store multiple data items in one call. Only for MDB_DUPFIXED. */ #define MDB_MULTIPLE 0x80000 -/* @} */ -/** @defgroup mdbx_copy Copy Flags - * @{ - */ -/** Compacting copy: Omit free space from copy, and renumber all - * pages sequentially. - */ -#define MDB_CP_COMPACT 0x01 -/* @} */ +/* Copy Flags */ +/* Compacting copy: Omit free space from copy, and renumber all + * pages sequentially. */ +#define MDB_CP_COMPACT 1 -/** @brief Cursor Get operations. +/* Cursor Get operations. * * This is the set of all operations for retrieving data * using a cursor. */ typedef enum MDB_cursor_op { - MDB_FIRST, /**< Position at first key/data item */ - MDB_FIRST_DUP, /**< Position at first data item of current key. - Only for #MDB_DUPSORT */ - MDB_GET_BOTH, /**< Position at key/data pair. Only for #MDB_DUPSORT */ - MDB_GET_BOTH_RANGE, /**< position at key, nearest data. Only for - #MDB_DUPSORT */ - MDB_GET_CURRENT, /**< Return key/data at current cursor position */ - MDB_GET_MULTIPLE, /**< Return key and up to a page of duplicate data items + MDB_FIRST, /* Position at first key/data item */ + MDB_FIRST_DUP, /* Position at first data item of current key. + Only for MDB_DUPSORT */ + MDB_GET_BOTH, /* Position at key/data pair. Only for MDB_DUPSORT */ + MDB_GET_BOTH_RANGE, /* position at key, nearest data. Only for + MDB_DUPSORT */ + MDB_GET_CURRENT, /* Return key/data at current cursor position */ + MDB_GET_MULTIPLE, /* Return key and up to a page of duplicate data items from current cursor position. Move cursor to prepare - for #MDB_NEXT_MULTIPLE. Only for - #MDB_DUPFIXED */ - MDB_LAST, /**< Position at last key/data item */ - MDB_LAST_DUP, /**< Position at last data item of current key. - Only for #MDB_DUPSORT */ - MDB_NEXT, /**< Position at next data item */ - MDB_NEXT_DUP, /**< Position at next data item of current key. - Only for #MDB_DUPSORT */ - MDB_NEXT_MULTIPLE, /**< Return key and up to a page of duplicate data items + for MDB_NEXT_MULTIPLE. Only for + MDB_DUPFIXED */ + MDB_LAST, /* Position at last key/data item */ + MDB_LAST_DUP, /* Position at last data item of current key. + Only for MDB_DUPSORT */ + MDB_NEXT, /* Position at next data item */ + MDB_NEXT_DUP, /* Position at next data item of current key. + Only for MDB_DUPSORT */ + MDB_NEXT_MULTIPLE, /* Return key and up to a page of duplicate data items from next cursor position. Move cursor to prepare - for #MDB_NEXT_MULTIPLE. Only for - #MDB_DUPFIXED */ - MDB_NEXT_NODUP, /**< Position at first data item of next key */ - MDB_PREV, /**< Position at previous data item */ - MDB_PREV_DUP, /**< Position at previous data item of current key. - Only for #MDB_DUPSORT */ - 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 + for MDB_NEXT_MULTIPLE. Only for + MDB_DUPFIXED */ + MDB_NEXT_NODUP, /* Position at first data item of next key */ + MDB_PREV, /* Position at previous data item */ + MDB_PREV_DUP, /* Position at previous data item of current key. + Only for MDB_DUPSORT */ + 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_PREV_MULTIPLE /**< Position at previous page and return key and up to + MDB_PREV_MULTIPLE /* Position at previous page and return key and up to a page of duplicate data items. - Only for #MDB_DUPFIXED */ + Only for MDB_DUPFIXED */ } MDB_cursor_op; -/** @defgroup errors Return Codes - * - * BerkeleyDB uses -30800 to -30999, we'll go under them - * @{ - */ -/** Successful result */ +/* Return Codes + * BerkeleyDB uses -30800 to -30999, we'll go under them */ + +/* Successful result */ #define MDB_SUCCESS 0 -/** key/data pair already exists */ +/* key/data pair already exists */ #define MDB_KEYEXIST (-30799) -/** key/data pair not found (EOF) */ +/* key/data pair not found (EOF) */ #define MDB_NOTFOUND (-30798) -/** Requested page not found - this usually indicates corruption */ +/* Requested page not found - this usually indicates corruption */ #define MDB_PAGE_NOTFOUND (-30797) -/** Located page was wrong type */ +/* Located page was wrong type */ #define MDB_CORRUPTED (-30796) -/** Update of meta page failed or environment had fatal error */ +/* Update of meta page failed or environment had fatal error */ #define MDB_PANIC (-30795) -/** Environment version mismatch */ +/* Environment version mismatch */ #define MDB_VERSION_MISMATCH (-30794) -/** File is not a valid LMDB file */ +/* File is not a valid LMDB file */ #define MDB_INVALID (-30793) -/** Environment mapsize reached */ +/* Environment mapsize reached */ #define MDB_MAP_FULL (-30792) -/** Environment maxdbs reached */ +/* Environment maxdbs reached */ #define MDB_DBS_FULL (-30791) -/** Environment maxreaders reached */ +/* Environment maxreaders reached */ #define MDB_READERS_FULL (-30790) -/** Txn has too many dirty pages */ +/* Txn has too many dirty pages */ #define MDB_TXN_FULL (-30788) -/** Cursor stack too deep - internal error */ +/* Cursor stack too deep - internal error */ #define MDB_CURSOR_FULL (-30787) -/** Page has not enough space - internal error */ +/* Page has not enough space - internal error */ #define MDB_PAGE_FULL (-30786) -/** Database contents grew beyond environment mapsize */ +/* Database contents grew beyond environment mapsize */ #define MDB_MAP_RESIZED (-30785) -/** Operation and DB incompatible, or DB type changed. This can mean: - * +/* Operation and DB incompatible, or DB type changed. This can mean: + * - The operation expects an MDB_DUPSORT / MDB_DUPFIXED database. + * - Opening a named DB when the unnamed DB has MDB_DUPSORT/MDB_INTEGERKEY. + * - Accessing a data record as a database, or vice versa. + * - The database was dropped and recreated with different flags. */ #define MDB_INCOMPATIBLE (-30784) -/** Invalid reuse of reader locktable slot */ +/* Invalid reuse of reader locktable slot */ #define MDB_BAD_RSLOT (-30783) -/** Transaction must abort, has a child, or is invalid */ +/* Transaction must abort, has a child, or is invalid */ #define MDB_BAD_TXN (-30782) -/** Unsupported size of key/DB name/data, or wrong DUPFIXED size */ +/* Unsupported size of key/DB name/data, or wrong DUPFIXED size */ #define MDB_BAD_VALSIZE (-30781) -/** The specified DBI was changed unexpectedly */ +/* The specified DBI was changed unexpectedly */ #define MDB_BAD_DBI (-30780) -/** Unexpected problem - txn should abort */ +/* Unexpected problem - txn should abort */ #define MDB_PROBLEM (-30779) -/** The last defined error code */ +/* The last defined error code */ #define MDB_LAST_ERRCODE MDB_PROBLEM -/** @} */ -/** @brief Statistics for a database in the environment */ +/* Statistics for a database in the environment */ typedef struct MDBX_stat { - unsigned ms_psize; /**< Size of a database page. + unsigned ms_psize; /* Size of a database page. This is currently the same for all databases. */ - unsigned 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 */ + unsigned 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 */ } MDBX_stat; -/** @brief Information about the environment */ +/* Information about the environment */ typedef struct MDBX_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 */ - unsigned me_maxreaders; /**< max reader slots in the environment */ - unsigned me_numreaders; /**< max reader slots used in the environment */ - size_t me_tail_txnid; /**< ID of the last reader transaction */ + 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 */ + unsigned me_maxreaders; /* max reader slots in the environment */ + unsigned me_numreaders; /* max reader slots used in the environment */ + size_t me_tail_txnid; /* ID of the last reader transaction */ size_t me_meta1_txnid, me_meta1_sign; size_t me_meta2_txnid, me_meta2_sign; } MDBX_envinfo; -/** @brief Return the LMDB library version information. +/* Return the LMDB library version information. * - * @param[out] major if non-NULL, the library major version number is copied + * [out] major if non-NULL, the library major version number is copied * here - * @param[out] minor if non-NULL, the library minor version number is copied + * [out] minor if non-NULL, the library minor version number is copied * here - * @param[out] patch if non-NULL, the library patch version number is copied + * [out] patch if non-NULL, the library patch version number is copied * here - * @retval "version string" The library version as a string + * Returns "version string" The library version as a string */ char *mdbx_version(int *major, int *minor, int *patch); -/** @brief Return a string describing a given error code. +/* Return a string describing a given error code. * * This function is a superset of the ANSI C X3.159-1989 (ANSI C) strerror(3) * function. If the error code is greater than or equal to 0, then the string * returned by the system function strerror(3) is returned. If the error code * is less than 0, an error string corresponding to the LMDB library error is - * returned. See @ref errors for a list of LMDB-specific error codes. - * @param[in] err The error code - * @retval "error message" The description of the error + * returned. See errors for a list of LMDB-specific error codes. + * [in] err The error code + * Returns "error message" The description of the error */ char *mdbx_strerror(int err); -/** @brief Create an LMDB environment handle. +/* Create an LMDB environment handle. * - * This function allocates memory for a #MDB_env structure. To release - * the allocated memory and discard the handle, call #mdbx_env_close(). - * Before the handle may be used, it must be opened using #mdbx_env_open(). + * This function allocates memory for a MDB_env structure. To release + * the allocated memory and discard the handle, call mdbx_env_close(). + * Before the handle may be used, it must be opened using mdbx_env_open(). * Various other options may also need to be set before opening the handle, - * e.g. #mdbx_env_set_mapsize(), #mdbx_env_set_maxreaders(), - * #mdbx_env_set_maxdbs(), + * e.g. mdbx_env_set_mapsize(), mdbx_env_set_maxreaders(), + * mdbx_env_set_maxdbs(), * depending on usage requirements. - * @param[out] env The address where the new handle will be stored - * @return A non-zero error value on failure and 0 on success. + * [out] env The address where the new handle will be stored + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_env_create(MDB_env **env); -/** @brief Open an environment handle. +/* Open an environment handle. * - * If this function fails, #mdbx_env_close() must be called to discard the - *#MDB_env handle. - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] path The directory in which the database files reside. This + * If this function fails, mdbx_env_close() must be called to discard the + *MDB_env handle. + * [in] env An environment handle returned by mdbx_env_create() + * [in] path The directory in which the database files reside. This * directory must already exist and be writable. - * @param[in] flags Special options for this environment. This parameter + * [in] flags Special options for this environment. This parameter * must be set to 0 or by bitwise OR'ing together one or more of the * values described here. * Flags set by mdbx_env_set_flags() are also used. - * - * @param[in] mode The UNIX permissions to set on created files and + * [in] mode The UNIX permissions to set on created files and *semaphores. * This parameter is ignored on Windows. - * @return A non-zero error value on failure and 0 on success. Some possible + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EAGAIN - the environment was locked by another process. */ int mdbx_env_open(MDB_env *env, const char *path, unsigned flags, mode_t mode); int mdbx_env_open_ex(MDB_env *env, const char *path, unsigned flags, mode_t mode, int *exclusive); -/** @brief Copy an LMDB environment to the specified path. +/* Copy an LMDB environment to the specified path. * * This function may be used to make a backup of an existing environment. * No lockfile is created, since it gets recreated at need. - * @note This call can trigger significant file size growth if run in + * Note: This call can trigger significant file size growth if run in * parallel with write transactions, because it employs a read-only - * transaction. See long-lived transactions under @ref caveats_sec. - * @param[in] env An environment handle returned by #mdbx_env_create(). It + * transaction. See long-lived transactions under caveats_sec. + * [in] env An environment handle returned by mdbx_env_create(). It * must have already been opened successfully. - * @param[in] path The directory in which the copy will reside. This + * [in] path The directory in which the copy will reside. This * directory must already exist and be writable but must otherwise be * empty. - * @return A non-zero error value on failure and 0 on success. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_env_copy(MDB_env *env, const char *path); -/** @brief Copy an LMDB environment to the specified file descriptor. +/* Copy an LMDB environment to the specified file descriptor. * * This function may be used to make a backup of an existing environment. * No lockfile is created, since it gets recreated at need. - * @note This call can trigger significant file size growth if run in + * Note: This call can trigger significant file size growth if run in * parallel with write transactions, because it employs a read-only - * transaction. See long-lived transactions under @ref caveats_sec. - * @param[in] env An environment handle returned by #mdbx_env_create(). It + * transaction. See long-lived transactions under caveats_sec. + * [in] env An environment handle returned by mdbx_env_create(). It * must have already been opened successfully. - * @param[in] fd The filedescriptor to write the copy to. It must + * [in] fd The filedescriptor to write the copy to. It must * have already been opened for Write access. - * @return A non-zero error value on failure and 0 on success. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_env_copyfd(MDB_env *env, int fd); -/** @brief Copy an LMDB environment to the specified path, with options. +/* Copy an LMDB environment to the specified path, with options. * * This function may be used to make a backup of an existing environment. * No lockfile is created, since it gets recreated at need. - * @note This call can trigger significant file size growth if run in + * Note: This call can trigger significant file size growth if run in * parallel with write transactions, because it employs a read-only - * transaction. See long-lived transactions under @ref caveats_sec. - * @param[in] env An environment handle returned by #mdbx_env_create(). It + * transaction. See long-lived transactions under caveats_sec. + * [in] env An environment handle returned by mdbx_env_create(). It * must have already been opened successfully. - * @param[in] path The directory in which the copy will reside. This + * [in] path The directory in which the copy will reside. This * directory must already exist and be writable but must otherwise be * empty. - * @param[in] flags Special options for this operation. This parameter + * [in] flags Special options for this operation. This parameter * must be set to 0 or by bitwise OR'ing together one or more of the * values described here. - * - * @return A non-zero error value on failure and 0 on success. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_env_copy2(MDB_env *env, const char *path, unsigned flags); -/** @brief Copy an LMDB environment to the specified file descriptor, +/* Copy an LMDB environment to the specified file descriptor, * with options. * * This function may be used to make a backup of an existing environment. * No lockfile is created, since it gets recreated at need. See - * #mdbx_env_copy2() for further details. - * @note This call can trigger significant file size growth if run in + * mdbx_env_copy2() for further details. + * Note: This call can trigger significant file size growth if run in * parallel with write transactions, because it employs a read-only - * transaction. See long-lived transactions under @ref caveats_sec. - * @param[in] env An environment handle returned by #mdbx_env_create(). It + * transaction. See long-lived transactions under caveats_sec. + * [in] env An environment handle returned by mdbx_env_create(). It * must have already been opened successfully. - * @param[in] fd The filedescriptor to write the copy to. It must + * [in] fd The filedescriptor to write the copy to. It must * have already been opened for Write access. - * @param[in] flags Special options for this operation. - * See #mdbx_env_copy2() for options. - * @return A non-zero error value on failure and 0 on success. + * [in] flags Special options for this operation. + * See mdbx_env_copy2() for options. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_env_copyfd2(MDB_env *env, int fd, unsigned flags); -/** @brief Return statistics about the LMDB environment. +/* Return statistics about the LMDB environment. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[out] stat The address of an #MDB_stat structure + * [in] env An environment handle returned by mdbx_env_create() + * [out] stat The address of an MDB_stat structure * where the statistics will be copied */ int mdbx_env_stat(MDB_env *env, MDBX_stat *stat, size_t bytes); -/** @brief Return information about the LMDB environment. +/* Return information about the LMDB environment. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[out] stat The address of an #MDB_envinfo structure + * [in] env An environment handle returned by mdbx_env_create() + * [out] stat The address of an MDB_envinfo structure * where the information will be copied */ int mdbx_env_info(MDB_env *env, MDBX_envinfo *info, size_t bytes); -/** @brief Flush the data buffers to disk. +/* Flush the data buffers to disk. * - * Data is always written to disk when #mdbx_txn_commit() is called, + * Data is always written to disk when mdbx_txn_commit() is called, * but the operating system may keep it buffered. LMDB always flushes * the OS buffers upon commit as well, unless the environment was - * opened with #MDB_NOSYNC or in part #MDB_NOMETASYNC. This call is - * not valid if the environment was opened with #MDB_RDONLY. - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] force If non-zero, force a synchronous flush. Otherwise - * if the environment has the #MDB_NOSYNC flag set the flushes - * will be omitted, and with #MDB_MAPASYNC they will be asynchronous. - * @return A non-zero error value on failure and 0 on success. Some possible + * opened with MDB_NOSYNC or in part MDB_NOMETASYNC. This call is + * not valid if the environment was opened with MDB_RDONLY. + * [in] env An environment handle returned by mdbx_env_create() + * [in] force If non-zero, force a synchronous flush. Otherwise + * if the environment has the MDB_NOSYNC flag set the flushes + * will be omitted, and with MDB_MAPASYNC they will be asynchronous. + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EACCES - the environment is read-only. + * - EINVAL - an invalid parameter was specified. + * - EIO - an error occurred during synchronization. */ int mdbx_env_sync(MDB_env *env, int force); -/** @brief Close the environment and release the memory map. +/* Close the environment and release the memory map. * * Only a single thread may call this function. All transactions, databases, * and cursors must already be closed before calling this function. Attempts @@ -694,8 +666,8 @@ int mdbx_env_sync(MDB_env *env, int force); * use any such handles after calling this function will cause a SIGSEGV. * The environment handle will be freed and must not be used again after this * call. - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] dont_sync A dont'sync flag, if non-zero the last checkpoint + * [in] env An environment handle returned by mdbx_env_create() + * [in] dont_sync A dont'sync flag, if non-zero the last checkpoint * (meta-page update) will be kept "as is" and may be still "weak" * in NOSYNC/MAPASYNC modes. Such "weak" checkpoint will be ignored * on opening next time, and transactions since the last non-weak @@ -703,72 +675,64 @@ int mdbx_env_sync(MDB_env *env, int force); */ void mdbx_env_close(MDB_env *env); -/** @brief Set environment flags. +/* Set environment flags. * * This may be used to set some flags in addition to those from - * #mdbx_env_open(), or to unset these flags. If several threads + * mdbx_env_open(), or to unset these flags. If several threads * change the flags at the same time, the result is undefined. - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] flags The flags to change, bitwise OR'ed together - * @param[in] onoff A non-zero value sets the flags, zero clears them. - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] env An environment handle returned by mdbx_env_create() + * [in] flags The flags to change, bitwise OR'ed together + * [in] onoff A non-zero value sets the flags, zero clears them. + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_env_set_flags(MDB_env *env, unsigned flags, int onoff); -/** @brief Get environment flags. +/* Get environment flags. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[out] flags The address of an integer to store the flags - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] env An environment handle returned by mdbx_env_create() + * [out] flags The address of an integer to store the flags + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_env_get_flags(MDB_env *env, unsigned *flags); -/** @brief Return the path that was used in #mdbx_env_open(). +/* Return the path that was used in mdbx_env_open(). * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[out] path Address of a string pointer to contain the path. This + * [in] env An environment handle returned by mdbx_env_create() + * [out] path Address of a string pointer to contain the path. This * is the actual string in the environment, not a copy. It should not be * altered in any way. - * @return A non-zero error value on failure and 0 on success. Some possible + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_env_get_path(MDB_env *env, const char **path); -/** @brief Return the filedescriptor for the given environment. +/* Return the filedescriptor for the given environment. * * This function may be called after fork(), so the descriptor can be * closed before exec*(). Other LMDB file descriptors have FD_CLOEXEC. * (Until LMDB 0.9.18, only the lockfile had that.) * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[out] fd Address of a int to contain the descriptor. - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] env An environment handle returned by mdbx_env_create() + * [out] fd Address of a int to contain the descriptor. + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_env_get_fd(MDB_env *env, int *fd); -/** @brief Set the size of the memory map to use for this environment. +/* Set the size of the memory map to use for this environment. * * The size should be a multiple of the OS page size. The default is * 10485760 bytes. The size of the memory map is also the maximum size * of the database. The value should be chosen as large as possible, * to accommodate future growth of the database. - * This function should be called after #mdbx_env_create() and before - *#mdbx_env_open(). + * This function should be called after mdbx_env_create() and before + *mdbx_env_open(). * It may be called at later times if no transactions are active in * this process. Note that the library does not check for this condition, * the caller must ensure it explicitly. @@ -779,263 +743,247 @@ int mdbx_env_get_fd(MDB_env *env, int *fd); * persisted into the environment. * * If the mapsize is increased by another process, and data has grown - * beyond the range of the current mapsize, #mdbx_txn_begin() will - * return #MDB_MAP_RESIZED. This function may be called with a size + * beyond the range of the current mapsize, mdbx_txn_begin() will + * return MDB_MAP_RESIZED. This function may be called with a size * of zero to adopt the new size. * * Any attempt to set a size smaller than the space already consumed * by the environment will be silently changed to the current size of the used *space. - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] size The size in bytes - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] env An environment handle returned by mdbx_env_create() + * [in] size The size in bytes + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * */ int mdbx_env_set_mapsize(MDB_env *env, size_t size); -/** @brief Set the maximum number of threads/reader slots for the environment. +/* Set the maximum number of threads/reader slots for the environment. * * This defines the number of slots in the lock table that is used to track *readers in the * the environment. The default is 126. * Starting a read-only transaction normally ties a lock table slot to the * current thread until the environment closes or the thread exits. If - * MDB_NOTLS is in use, #mdbx_txn_begin() instead ties the slot to the - * MDB_txn object until it or the #MDB_env object is destroyed. - * This function may only be called after #mdbx_env_create() and before - *#mdbx_env_open(). - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] readers The maximum number of reader lock table slots - * @return A non-zero error value on failure and 0 on success. Some possible + * MDB_NOTLS is in use, mdbx_txn_begin() instead ties the slot to the + * MDB_txn object until it or the MDB_env object is destroyed. + * This function may only be called after mdbx_env_create() and before + *mdbx_env_open(). + * [in] env An environment handle returned by mdbx_env_create() + * [in] readers The maximum number of reader lock table slots + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * */ int mdbx_env_set_maxreaders(MDB_env *env, unsigned readers); -/** @brief Get the maximum number of threads/reader slots for the environment. +/* Get the maximum number of threads/reader slots for the environment. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[out] readers Address of an integer to store the number of readers - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] env An environment handle returned by mdbx_env_create() + * [out] readers Address of an integer to store the number of readers + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_env_get_maxreaders(MDB_env *env, unsigned *readers); -/** @brief Set the maximum number of named databases for the environment. +/* Set the maximum number of named databases for the environment. * * This function is only needed if multiple databases will be used in the * environment. Simpler applications that use the environment as a single * unnamed database can ignore this option. - * This function may only be called after #mdbx_env_create() and before - *#mdbx_env_open(). + * This function may only be called after mdbx_env_create() and before + *mdbx_env_open(). * * Currently a moderate number of slots are cheap but a huge number gets - * expensive: 7-120 words per transaction, and every #mdbx_dbi_open() + * expensive: 7-120 words per transaction, and every mdbx_dbi_open() * does a linear search of the opened slots. - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] dbs The maximum number of databases - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] env An environment handle returned by mdbx_env_create() + * [in] dbs The maximum number of databases + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * */ int mdbx_env_set_maxdbs(MDB_env *env, MDB_dbi dbs); -/** @brief Get the maximum size of keys and #MDB_DUPSORT data we can write. +/* Get the maximum size of keys and MDB_DUPSORT data we can write. * - * Depends on the compile-time constant #MDB_MAXKEYSIZE. Default 511. - * See @ref MDB_val. - * @param[in] env An environment handle returned by #mdbx_env_create() - * @return The maximum size of a key we can write + * Depends on the compile-time constant MDB_MAXKEYSIZE. Default 511. + * See MDB_val. + * [in] env An environment handle returned by mdbx_env_create() + * Returns The maximum size of a key we can write */ int mdbx_env_get_maxkeysize(MDB_env *env); -/** @brief Set application information associated with the #MDB_env. +/* Set application information associated with the MDB_env. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] ctx An arbitrary pointer for whatever the application needs. - * @return A non-zero error value on failure and 0 on success. + * [in] env An environment handle returned by mdbx_env_create() + * [in] ctx An arbitrary pointer for whatever the application needs. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_env_set_userctx(MDB_env *env, void *ctx); -/** @brief Get the application information associated with the #MDB_env. +/* Get the application information associated with the MDB_env. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @return The pointer set by #mdbx_env_set_userctx(). + * [in] env An environment handle returned by mdbx_env_create() + * Returns The pointer set by mdbx_env_set_userctx(). */ void *mdbx_env_get_userctx(MDB_env *env); -/** @brief A callback function for most LMDB assert() failures, +/* A callback function for most LMDB assert() failures, * called before printing the message and aborting. * - * @param[in] env An environment handle returned by #mdbx_env_create(). - * @param[in] msg The assertion message, not including newline. + * [in] env An environment handle returned by mdbx_env_create(). + * [in] msg The assertion message, not including newline. */ typedef void MDB_assert_func(MDB_env *env, const char *msg, const char *function, unsigned line); -/** Set or reset the assert() callback of the environment. +/* Set or reset the assert() callback of the environment. * Disabled if liblmdb is buillt with MDB_DEBUG=0. - * @note This hack should become obsolete as lmdb's error handling matures. - * @param[in] env An environment handle returned by #mdbx_env_create(). - * @param[in] func An #MDB_assert_func function, or 0. - * @return A non-zero error value on failure and 0 on success. + * Note: This hack should become obsolete as lmdb's error handling matures. + * [in] env An environment handle returned by mdbx_env_create(). + * [in] func An MDB_assert_func function, or 0. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_env_set_assert(MDB_env *env, MDB_assert_func *func); -/** @brief Create a transaction for use with the environment. +/* Create a transaction for use with the environment. * - * The transaction handle may be discarded using #mdbx_txn_abort() or - *#mdbx_txn_commit(). - * @note A transaction and its cursors must only be used by a single + * The transaction handle may be discarded using mdbx_txn_abort() or + *mdbx_txn_commit(). + * Note: A transaction and its cursors must only be used by a single * thread, and a thread may only have a single transaction at a time. - * If #MDB_NOTLS is in use, this does not apply to read-only transactions. - * @note Cursors may not span transactions. - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] parent If this parameter is non-NULL, the new transaction + * If MDB_NOTLS is in use, this does not apply to read-only transactions. + * Note: Cursors may not span transactions. + * [in] env An environment handle returned by mdbx_env_create() + * [in] parent If this parameter is non-NULL, the new transaction * will be a nested transaction, with the transaction indicated by \b parent * as its parent. Transactions may be nested to any level. A parent * transaction and its cursors may not issue any other operations than * mdbx_txn_commit and mdbx_txn_abort while it has active child transactions. - * @param[in] flags Special options for this transaction. This parameter + * [in] flags Special options for this transaction. This parameter * must be set to 0 or by bitwise OR'ing together one or more of the * values described here. - * - * @param[out] txn Address where the new #MDB_txn handle will be stored - * @return A non-zero error value on failure and 0 on success. Some possible + * [out] txn Address where the new MDB_txn handle will be stored + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * See mdbx_env_set_mapsize(). + * - MDB_READERS_FULL - a read-only transaction was requested and + * the reader lock table is full. See mdbx_env_set_maxreaders(). + * - ENOMEM - out of memory. */ int mdbx_txn_begin(MDB_env *env, MDB_txn *parent, unsigned flags, MDB_txn **txn); -/** @brief Returns the transaction's #MDB_env +/* Returns the transaction's MDB_env * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() + * [in] txn A transaction handle returned by mdbx_txn_begin() */ MDB_env *mdbx_txn_env(MDB_txn *txn); -/** @brief Return the transaction's ID. +/* Return the transaction's ID. * * This returns the identifier associated with this transaction. For a * read-only transaction, this corresponds to the snapshot being read; * concurrent readers will frequently have the same transaction ID. * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @return A transaction ID, valid if input is an active transaction. + * [in] txn A transaction handle returned by mdbx_txn_begin() + * Returns A transaction ID, valid if input is an active transaction. */ size_t mdbx_txn_id(MDB_txn *txn); -/** @brief Commit all the operations of a transaction into the database. +/* Commit all the operations of a transaction into the database. * * The transaction handle is freed. It and its cursors must not be used - * again after this call, except with #mdbx_cursor_renew(). + * again after this call, except with mdbx_cursor_renew(). * - * @note MDBX-mode: + * Note: MDBX-mode: * A cursor must be closed explicitly always, before * or after its transaction ends. It can be reused with - * #mdbx_cursor_renew() before finally closing it. + * mdbx_cursor_renew() before finally closing it. * - * @note LMDB-compatible mode: + * Note: LMDB-compatible mode: * Earlier documentation incorrectly said all cursors would be freed. * Only write-transactions free cursors. * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] txn A transaction handle returned by mdbx_txn_begin() + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. + * - ENOSPC - no more disk space. + * - EIO - a low-level I/O error occurred while writing. + * - ENOMEM - out of memory. */ int mdbx_txn_commit(MDB_txn *txn); -/** @brief Abandon all the operations of the transaction instead of saving +/* Abandon all the operations of the transaction instead of saving * them. * * The transaction handle is freed. It and its cursors must not be used - * again after this call, except with #mdbx_cursor_renew(). + * again after this call, except with mdbx_cursor_renew(). * - * @note MDBX-mode: + * Note: MDBX-mode: * A cursor must be closed explicitly always, before * or after its transaction ends. It can be reused with - * #mdbx_cursor_renew() before finally closing it. + * mdbx_cursor_renew() before finally closing it. * - * @note LMDB-compatible mode: + * Note: LMDB-compatible mode: * Earlier documentation incorrectly said all cursors would be freed. * Only write-transactions free cursors. * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() + * [in] txn A transaction handle returned by mdbx_txn_begin() */ int mdbx_txn_abort(MDB_txn *txn); -/** @brief Reset a read-only transaction. +/* Reset a read-only transaction. * - * Abort the transaction like #mdbx_txn_abort(), but keep the transaction - * handle. #mdbx_txn_renew() may reuse the handle. This saves allocation + * Abort the transaction like mdbx_txn_abort(), but keep the transaction + * handle. mdbx_txn_renew() may reuse the handle. This saves allocation * overhead if the process will start a new read-only transaction soon, - * and also locking overhead if #MDB_NOTLS is in use. The reader table + * and also locking overhead if MDB_NOTLS is in use. The reader table * lock is released, but the table slot stays tied to its thread or - * #MDB_txn. Use mdbx_txn_abort() to discard a reset handle, and to free + * MDB_txn. Use mdbx_txn_abort() to discard a reset handle, and to free * its lock table slot if MDB_NOTLS is in use. * Cursors opened within the transaction must not be used - * again after this call, except with #mdbx_cursor_renew(). + * again after this call, except with mdbx_cursor_renew(). * Reader locks generally don't interfere with writers, but they keep old * versions of database pages allocated. Thus they prevent the old pages * from being reused when writers commit new data, and so under heavy load * the database size may grow much more rapidly than otherwise. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() + * [in] txn A transaction handle returned by mdbx_txn_begin() */ int mdbx_txn_reset(MDB_txn *txn); -/** @brief Renew a read-only transaction. +/* Renew a read-only transaction. * * This acquires a new reader lock for a transaction handle that had been - * released by #mdbx_txn_reset(). It must be called before a reset transaction + * released by mdbx_txn_reset(). It must be called before a reset transaction * may be used again. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] txn A transaction handle returned by mdbx_txn_begin() + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_txn_renew(MDB_txn *txn); -/** @brief Open a database in the environment. +/* Open a database in the environment. * A database handle denotes the name and parameters of a database, * independently of whether such a database exists. - * The database handle may be discarded by calling #mdbx_dbi_close(). + * The database handle may be discarded by calling mdbx_dbi_close(). * The old database handle is returned if the database was already open. * The handle may only be closed once. * @@ -1050,96 +998,90 @@ int mdbx_txn_renew(MDB_txn *txn); * this function must finish (either commit or abort) before * any other transaction in the process may use this function. * - * To use named databases (with name != NULL), #mdbx_env_set_maxdbs() + * To use named databases (with name != NULL), mdbx_env_set_maxdbs() * must be called before opening the environment. Database names are * keys in the unnamed database, and may be read but not written. * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] name The name of the database to open. If only a single + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] name The name of the database to open. If only a single * database is needed in the environment, this value may be NULL. - * @param[in] flags Special options for this database. This parameter + * [in] flags Special options for this database. This parameter * must be set to 0 or by bitwise OR'ing together one or more of the * values described here. - * - * @param[out] dbi Address where the new #MDB_dbi handle will be stored - * @return A non-zero error value on failure and 0 on success. Some possible + * [out] dbi Address where the new MDB_dbi handle will be stored + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * and MDB_CREATE was not specified. + * - MDB_DBS_FULL - too many databases have been opened. See + *mdbx_env_set_maxdbs(). */ int mdbx_dbi_open(MDB_txn *txn, const char *name, unsigned flags, MDB_dbi *dbi); -/** @brief Retrieve statistics for a database. +/* Retrieve statistics for a database. * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[out] stat The address of an #MDB_stat structure + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [out] stat The address of an MDB_stat structure * where the statistics will be copied - * @return A non-zero error value on failure and 0 on success. Some possible + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_stat(MDB_txn *txn, MDB_dbi dbi, MDBX_stat *stat, size_t bytes); -/** @brief Retrieve the DB flags for a database handle. +/* Retrieve the DB flags for a database handle. * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[out] flags Address where the flags will be returned. - * @return A non-zero error value on failure and 0 on success. + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [out] flags Address where the flags will be returned. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_dbi_flags(MDB_txn *txn, MDB_dbi dbi, unsigned *flags); -/** @brief Close a database handle. Normally unnecessary. Use with care: +/* Close a database handle. Normally unnecessary. Use with care: * * This call is not mutex protected. Handles should only be closed by * a single thread, and only if no other threads are going to reference @@ -1148,140 +1090,133 @@ int mdbx_dbi_flags(MDB_txn *txn, MDB_dbi dbi, unsigned *flags); * Doing so can cause misbehavior from database corruption to errors * like MDB_BAD_VALSIZE (since the DB name is gone). * - * Closing a database handle is not necessary, but lets #mdbx_dbi_open() + * Closing a database handle is not necessary, but lets mdbx_dbi_open() * reuse the handle value. Usually it's better to set a bigger - * #mdbx_env_set_maxdbs(), unless that value would be large. + * mdbx_env_set_maxdbs(), unless that value would be large. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() + * [in] env An environment handle returned by mdbx_env_create() + * [in] dbi A database handle returned by mdbx_dbi_open() */ void mdbx_dbi_close(MDB_env *env, MDB_dbi dbi); -/** @brief Empty or delete+close a database. +/* Empty or delete+close a database. * - * See #mdbx_dbi_close() for restrictions about closing the DB handle. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[in] del 0 to empty the DB, 1 to delete it from the + * See mdbx_dbi_close() for restrictions about closing the DB handle. + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [in] del 0 to empty the DB, 1 to delete it from the * environment and close the DB handle. - * @return A non-zero error value on failure and 0 on success. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_drop(MDB_txn *txn, MDB_dbi dbi, int del); -/** @brief Set a custom key comparison function for a database. +/* Set a custom key comparison function for a database. * * The comparison function is called whenever it is necessary to compare a * key specified by the application with a key currently stored in the *database. * If no comparison function is specified, and no special key flags were *specified - * with #mdbx_dbi_open(), the keys are compared lexically, with shorter keys + * with mdbx_dbi_open(), the keys are compared lexically, with shorter keys *collating * before longer keys. - * @warning This function must be called before any data access functions are + * Warning: This function must be called before any data access functions are *used, * otherwise data corruption may occur. The same comparison function must be *used by every * program accessing the database, every time the database is used. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[in] cmp A #MDB_cmp_func function - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [in] cmp A MDB_cmp_func function + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_set_compare(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp); -/** @brief Set a custom data comparison function for a #MDB_DUPSORT database. +/* Set a custom data comparison function for a MDB_DUPSORT database. * * This comparison function is called whenever it is necessary to compare a *data * item specified by the application with a data item currently stored in the *database. * This function only takes effect if the database was opened with the - *#MDB_DUPSORT + *MDB_DUPSORT * flag. * If no comparison function is specified, and no special key flags were *specified - * with #mdbx_dbi_open(), the data items are compared lexically, with shorter + * with mdbx_dbi_open(), the data items are compared lexically, with shorter *items collating * before longer items. - * @warning This function must be called before any data access functions are + * Warning: This function must be called before any data access functions are *used, * otherwise data corruption may occur. The same comparison function must be *used by every * program accessing the database, every time the database is used. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[in] cmp A #MDB_cmp_func function - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [in] cmp A MDB_cmp_func function + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_set_dupsort(MDB_txn *txn, MDB_dbi dbi, MDB_cmp_func *cmp); -/** @brief Get items from a database. +/* Get items from a database. * * This function retrieves key/data pairs from the database. The address * and length of the data associated with the specified \b key are returned * in the structure to which \b data refers. - * If the database supports duplicate keys (#MDB_DUPSORT) then the + * If the database supports duplicate keys (MDB_DUPSORT) then the * first data item for the key will be returned. Retrieval of other - * items requires the use of #mdbx_cursor_get(). + * items requires the use of mdbx_cursor_get(). * - * @note The memory pointed to by the returned values is owned by the + * Note: The memory pointed to by the returned values is owned by the * database. The caller need not dispose of the memory, and may not * modify it in any way. For values returned in a read-only transaction * any modification attempts will cause a SIGSEGV. - * @note Values returned from the database are valid only until a + * Note: Values returned from the database are valid only until a * subsequent update operation, or the end of the transaction. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[in] key The key to search for in the database - * @param[out] data The data corresponding to the key - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [in] key The key to search for in the database + * [out] data The data corresponding to the key + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - MDB_NOTFOUND - the key was not in the database. + * - EINVAL - an invalid parameter was specified. */ int mdbx_get(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data); -/** @brief Store items into a database. +/* Store items into a database. * * This function stores key/data pairs in the database. The default behavior * is to enter the new key/data pair, replacing any previously existing key * if duplicates are disallowed, or adding a duplicate data item if - * duplicates are allowed (#MDB_DUPSORT). - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[in] key The key to store in the database - * @param[in,out] data The data to store - * @param[in] flags Special options for this operation. This parameter + * duplicates are allowed (MDB_DUPSORT). + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [in] key The key to store in the database + * [in,out] data The data to store + * [in] flags Special options for this operation. This parameter * must be set to 0 or by bitwise OR'ing together one or more of the * values described here. - * - * @return A non-zero error value on failure and 0 on success. Some possible + * with this flag will cause a MDB_KEYEXIST error. + * - MDB_APPENDDUP - as above, but for sorted dup data. + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - MDB_MAP_FULL - the database is full, see mdbx_env_set_mapsize(). + * - MDB_TXN_FULL - the transaction has too many dirty pages. + * - EACCES - an attempt was made to write in a read-only transaction. + * - EINVAL - an invalid parameter was specified. */ int mdbx_put(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data, unsigned flags); -/** @brief Delete items from a database. +/* Delete items from a database. * * This function removes key/data pairs from the database. * @@ -1320,68 +1252,64 @@ int mdbx_put(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data, * * LMDB-compatible mode: * If the database does not support sorted duplicate data items - * (#MDB_DUPSORT) the data parameter is ignored. + * (MDB_DUPSORT) the data parameter is ignored. * If the database supports sorted duplicates and the data parameter * is NULL, all of the duplicate data items for the key will be * deleted. Otherwise, if the data parameter is non-NULL * only the matching data item will be deleted. * - * This function will return #MDB_NOTFOUND if the specified key/data + * This function will return MDB_NOTFOUND if the specified key/data * pair is not in the database. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[in] key The key to delete from the database - * @param[in] data The data to delete - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [in] key The key to delete from the database + * [in] data The data to delete + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EACCES - an attempt was made to write in a read-only transaction. + * - EINVAL - an invalid parameter was specified. */ int mdbx_del(MDB_txn *txn, MDB_dbi dbi, MDB_val *key, MDB_val *data); -/** @brief Create a cursor handle. +/* Create a cursor handle. * * A cursor is associated with a specific transaction and database. * A cursor cannot be used when its database handle is closed. Nor - * when its transaction has ended, except with #mdbx_cursor_renew(). - * It can be discarded with #mdbx_cursor_close(). + * when its transaction has ended, except with mdbx_cursor_renew(). + * It can be discarded with mdbx_cursor_close(). * * MDBX-mode: * A cursor must be closed explicitly always, before * or after its transaction ends. It can be reused with - * #mdbx_cursor_renew() before finally closing it. + * mdbx_cursor_renew() before finally closing it. * * LMDB-compatible mode: * A cursor in a write-transaction can be closed before its transaction * ends, and will otherwise be closed when its transaction ends. * A cursor in a read-only transaction must be closed explicitly, before * or after its transaction ends. It can be reused with - * #mdbx_cursor_renew() before finally closing it. - * @note Earlier documentation said that cursors in every transaction + * mdbx_cursor_renew() before finally closing it. + * Note: Earlier documentation said that cursors in every transaction * were closed when the transaction committed or aborted. * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[out] cursor Address where the new #MDB_cursor handle will be stored - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [out] cursor Address where the new MDB_cursor handle will be stored + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_cursor_open(MDB_txn *txn, MDB_dbi dbi, MDB_cursor **cursor); -/** @brief Close a cursor handle. +/* Close a cursor handle. * * The cursor handle will be freed and must not be used again after this call. * Its transaction must still be live if it is a write-transaction. - * @param[in] cursor A cursor handle returned by #mdbx_cursor_open() + * [in] cursor A cursor handle returned by mdbx_cursor_open() */ void mdbx_cursor_close(MDB_cursor *cursor); -/** @brief Renew a cursor handle. +/* Renew a cursor handle. * * A cursor is associated with a specific transaction and database. * Cursors that are only used in read-only @@ -1389,105 +1317,100 @@ void mdbx_cursor_close(MDB_cursor *cursor); * The cursor may be associated with a new read-only transaction, and * referencing the same database handle as it was created with. * This may be done whether the previous transaction is live or dead. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] cursor A cursor handle returned by #mdbx_cursor_open() - * @return A non-zero error value on failure and 0 on success. Some possible + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] cursor A cursor handle returned by mdbx_cursor_open() + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EINVAL - an invalid parameter was specified. */ int mdbx_cursor_renew(MDB_txn *txn, MDB_cursor *cursor); -/** @brief Return the cursor's transaction handle. +/* Return the cursor's transaction handle. * - * @param[in] cursor A cursor handle returned by #mdbx_cursor_open() + * [in] cursor A cursor handle returned by mdbx_cursor_open() */ MDB_txn *mdbx_cursor_txn(MDB_cursor *cursor); -/** @brief Return the cursor's database handle. +/* Return the cursor's database handle. * - * @param[in] cursor A cursor handle returned by #mdbx_cursor_open() + * [in] cursor A cursor handle returned by mdbx_cursor_open() */ MDB_dbi mdbx_cursor_dbi(MDB_cursor *cursor); -/** @brief Retrieve by cursor. +/* Retrieve by cursor. * * This function retrieves key/data pairs from the database. The address and *length * of the key are returned in the object to which \b key refers (except for *the - * case of the #MDB_SET option, in which the \b key object is unchanged), and + * case of the MDB_SET option, in which the \b key object is unchanged), and * the address and length of the data are returned in the object to which \b *data * refers. - * See #mdbx_get() for restrictions on using the output values. - * @param[in] cursor A cursor handle returned by #mdbx_cursor_open() - * @param[in,out] key The key for a retrieved item - * @param[in,out] data The data of a retrieved item - * @param[in] op A cursor operation #MDB_cursor_op - * @return A non-zero error value on failure and 0 on success. Some possible + * See mdbx_get() for restrictions on using the output values. + * [in] cursor A cursor handle returned by mdbx_cursor_open() + * [in,out] key The key for a retrieved item + * [in,out] data The data of a retrieved item + * [in] op A cursor operation MDB_cursor_op + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - MDB_NOTFOUND - no matching key found. + * - EINVAL - an invalid parameter was specified. */ int mdbx_cursor_get(MDB_cursor *cursor, MDB_val *key, MDB_val *data, MDB_cursor_op op); -/** @brief Store by cursor. +/* Store by cursor. * * This function stores key/data pairs into the database. * The cursor is positioned at the new item, or on failure usually near it. - * @note Earlier documentation incorrectly said errors would leave the + * Note: Earlier documentation incorrectly said errors would leave the * state of the cursor unchanged. - * @param[in] cursor A cursor handle returned by #mdbx_cursor_open() - * @param[in] key The key operated on. - * @param[in] data The data operated on. - * @param[in] flags Options for this operation. This parameter + * [in] cursor A cursor handle returned by mdbx_cursor_open() + * [in] key The key operated on. + * [in] data The data operated on. + * [in] flags Options for this operation. This parameter * must be set to 0 or one of the values described here. - * - * @return A non-zero error value on failure and 0 on success. Some possible + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - MDB_MAP_FULL - the database is full, see mdbx_env_set_mapsize(). + * - MDB_TXN_FULL - the transaction has too many dirty pages. + * - EACCES - an attempt was made to write in a read-only transaction. + * - EINVAL - an invalid parameter was specified. */ int mdbx_cursor_put(MDB_cursor *cursor, MDB_val *key, MDB_val *data, unsigned flags); -/** @brief Delete current key/data pair +/* Delete current key/data pair * * This function deletes the key/data pair to which the cursor refers. - * @param[in] cursor A cursor handle returned by #mdbx_cursor_open() - * @param[in] flags Options for this operation. This parameter + * [in] cursor A cursor handle returned by mdbx_cursor_open() + * [in] flags Options for this operation. This parameter * must be set to 0 or one of the values described here. - * - * @return A non-zero error value on failure and 0 on success. Some possible + *MDB_DUPSORT. + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * + * - EACCES - an attempt was made to write in a read-only transaction. + * - EINVAL - an invalid parameter was specified. */ int mdbx_cursor_del(MDB_cursor *cursor, unsigned flags); -/** @brief Return count of duplicates for current key. +/* Return count of duplicates for current key. * * This call is only valid on databases that support sorted duplicate - * data items #MDB_DUPSORT. - * @param[in] cursor A cursor handle returned by #mdbx_cursor_open() - * @param[out] countp Address where the count will be stored - * @return A non-zero error value on failure and 0 on success. Some possible + * data items MDB_DUPSORT. + * [in] cursor A cursor handle returned by mdbx_cursor_open() + * [out] countp Address where the count will be stored + * Returns A non-zero error value on failure and 0 on success. Some possible * errors are: - * */ int mdbx_cursor_count(MDB_cursor *cursor, size_t *countp); -/** @brief Compare two data items according to a particular database. +/* Compare two data items according to a particular database. * * This returns a comparison as if the two data items were keys in the * specified database. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[in] a The first item to compare - * @param[in] b The second item to compare - * @return < 0 if a < b, 0 if a == b, > 0 if a > b + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [in] a The first item to compare + * [in] b The second item to compare + * Returns < 0 if a < b, 0 if a == b, > 0 if a > b */ int mdbx_cmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b); -/** @brief Compare two data items according to a particular database. +/* Compare two data items according to a particular database. * * This returns a comparison as if the two items were data items of - * the specified database. The database must have the #MDB_DUPSORT flag. - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[in] dbi A database handle returned by #mdbx_dbi_open() - * @param[in] a The first item to compare - * @param[in] b The second item to compare - * @return < 0 if a < b, 0 if a == b, > 0 if a > b + * the specified database. The database must have the MDB_DUPSORT flag. + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [in] dbi A database handle returned by mdbx_dbi_open() + * [in] a The first item to compare + * [in] b The second item to compare + * Returns < 0 if a < b, 0 if a == b, > 0 if a > b */ int mdbx_dcmp(MDB_txn *txn, MDB_dbi dbi, const MDB_val *a, const MDB_val *b); -/** @brief A callback function used to print a message from the library. +/* A callback function used to print a message from the library. * - * @param[in] msg The string to be printed. - * @param[in] ctx An arbitrary context pointer for the callback. - * @return < 0 on failure, >= 0 on success. + * [in] msg The string to be printed. + * [in] ctx An arbitrary context pointer for the callback. + * Returns < 0 on failure, >= 0 on success. */ typedef int(MDB_msg_func)(const char *msg, void *ctx); -/** @brief Dump the entries in the reader lock table. +/* Dump the entries in the reader lock table. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] func A #MDB_msg_func function - * @param[in] ctx Anything the message function needs - * @return < 0 on failure, >= 0 on success. + * [in] env An environment handle returned by mdbx_env_create() + * [in] func A MDB_msg_func function + * [in] ctx Anything the message function needs + * Returns < 0 on failure, >= 0 on success. */ int mdbx_reader_list(MDB_env *env, MDB_msg_func *func, void *ctx); -/** @brief Check for stale entries in the reader lock table. +/* Check for stale entries in the reader lock table. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[out] dead Number of stale slots that were cleared - * @return 0 on success, non-zero on failure. + * [in] env An environment handle returned by mdbx_env_create() + * [out] dead Number of stale slots that were cleared + * Returns 0 on success, non-zero on failure. */ int mdbx_reader_check(MDB_env *env, int *dead); @@ -1601,46 +1515,46 @@ char *mdbx_dkey(MDB_val *key, char *buf); int mdbx_env_close_ex(MDB_env *env, int dont_sync); -/** @brief Set threshold to force flush the data buffers to disk, - * even of #MDB_NOSYNC, #MDB_NOMETASYNC and #MDB_MAPASYNC flags +/* Set threshold to force flush the data buffers to disk, + * even of MDB_NOSYNC, MDB_NOMETASYNC and MDB_MAPASYNC flags * in the environment. * - * Data is always written to disk when #mdbx_txn_commit() is called, + * Data is always written to disk when mdbx_txn_commit() is called, * but the operating system may keep it buffered. LMDB always flushes * the OS buffers upon commit as well, unless the environment was - * opened with #MDB_NOSYNC or in part #MDB_NOMETASYNC. + * opened with MDB_NOSYNC or in part MDB_NOMETASYNC. * * The default is 0, than mean no any threshold checked, * and no additional flush will be made. * - * @param[in] env An environment handle returned by #mdbx_env_create() - * @param[in] bytes The size in bytes of summary changes + * [in] env An environment handle returned by mdbx_env_create() + * [in] bytes The size in bytes of summary changes * when a synchronous flush would be made. - * @return A non-zero error value on failure and 0 on success. + * Returns A non-zero error value on failure and 0 on success. */ int mdbx_env_set_syncbytes(MDB_env *env, size_t bytes); -/** @brief Returns a lag of the reading. +/* Returns a lag of the reading. * * Returns an information for estimate how much given read-only * transaction is lagging relative the to actual head. * - * @param[in] txn A transaction handle returned by #mdbx_txn_begin() - * @param[out] percent Percentage of page allocation in the database. - * @return Number of transactions committed after the given was started for + * [in] txn A transaction handle returned by mdbx_txn_begin() + * [out] percent Percentage of page allocation in the database. + * Returns Number of transactions committed after the given was started for * read, or -1 on failure. */ int mdbx_txn_straggler(MDB_txn *txn, int *percent); -/** @brief A callback function for killing a laggard readers, +/* A callback function for killing a laggard readers, * but also could waiting ones. Called in case of MDB_MAP_FULL error. * - * @param[in] env An environment handle returned by #mdbx_env_create(). - * @param[in] pid pid of the reader process. - * @param[in] thread_id thread_id of the reader thread. - * @param[in] txn Transaction number on which stalled. - * @param[in] gap a lag from the last commited txn. - * @param[in] retry a retry number, less that zero for notify end of OOM-loop. - * @return -1 on failure (reader is not killed), + * [in] env An environment handle returned by mdbx_env_create(). + * [in] pid pid of the reader process. + * [in] thread_id thread_id of the reader thread. + * [in] txn Transaction number on which stalled. + * [in] gap a lag from the last commited txn. + * [in] retry a retry number, less that zero for notify end of OOM-loop. + * Returns -1 on failure (reader is not killed), * 0 on a race condition (no such reader), * 1 on success (reader was killed), * >1 on success (reader was SURE killed). @@ -1648,23 +1562,23 @@ int mdbx_txn_straggler(MDB_txn *txn, int *percent); typedef int(MDBX_oom_func)(MDB_env *env, int pid, void *thread_id, size_t txn, unsigned gap, int retry); -/** @brief Set the OOM callback. +/* Set the OOM callback. * * Callback will be called only on out-of-pages case for killing * a laggard readers to allowing reclaiming of freeDB. * - * @param[in] env An environment handle returned by #mdbx_env_create(). - * @param[in] oomfunc A #MDBX_oom_func function or NULL to disable. + * [in] env An environment handle returned by mdbx_env_create(). + * [in] oomfunc A #MDBX_oom_func function or NULL to disable. */ void mdbx_env_set_oomfunc(MDB_env *env, MDBX_oom_func *oom_func); -/** @brief Get the current oom_func callback. +/* Get the current oom_func callback. * * Callback will be called only on out-of-pages case for killing * a laggard readers to allowing reclaiming of freeDB. * - * @param[in] env An environment handle returned by #mdbx_env_create(). - * @return A #MDBX_oom_func function or NULL if disabled. + * [in] env An environment handle returned by mdbx_env_create(). + * Returns A #MDBX_oom_func function or NULL if disabled. */ MDBX_oom_func *mdbx_env_get_oomfunc(MDB_env *env);