Clarify doc: mdb_copy, nested txns, mdb_drop().

mdb_copy: Does not copy lockfile. Can trigger file growth.
mdb_txn_begin(): Clarify usage restrictions.
mdb_drop(): State what to do rather than what will be done, since
closing the handle could otherwise be read as happening even at failure.

diff --git a/libraries/liblmdb/lmdb.h b/libraries/liblmdb/lmdb.h
index b3cd5ef79e0b8cda5c19a3845d65f8e4ca534496..9e3e5b71f11862d28926dfbb262c417a59a1520c 100644 (file)
--- a/libraries/liblmdb/lmdb.h
+++ b/libraries/liblmdb/lmdb.h
@@ -138,6 +138,7 @@
 extern "C" {
 #endif
 
+/** Unix permissions for creating files, or dummy definition for Windows */
 #ifdef _MSC_VER
 typedef        int     mdb_mode_t;
 #else
@@ -534,6 +535,10 @@ int  mdb_env_open(MDB_env *env, const char *path, unsigned int flags, mdb_mode_t
        /** @brief Copy an MDB 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
+        * 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 #mdb_env_create(). It
         * must have already been opened successfully.
         * @param[in] path The directory in which the copy will reside. This
@@ -546,6 +551,10 @@ int  mdb_env_copy(MDB_env *env, const char *path);
        /** @brief Copy an MDB 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
+        * 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 #mdb_env_create(). It
         * must have already been opened successfully.
         * @param[in] fd The filedescriptor to write the copy to. It must
@@ -718,8 +727,8 @@ int  mdb_env_set_maxdbs(MDB_env *env, MDB_dbi dbs);
         * @param[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 may not issue any other operations besides mdb_txn_begin,
-        * mdb_txn_abort, or mdb_txn_commit while it has active child transactions.
+        * transaction and its cursors may not issue any other operations than
+        * mdb_txn_commit and mdb_txn_abort while it has active child transactions.
         * @param[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.
@@ -909,14 +918,12 @@ int mdb_dbi_flags(MDB_env *env, MDB_dbi dbi, unsigned int *flags);
         */
 void mdb_dbi_close(MDB_env *env, MDB_dbi dbi);
 
-       /** @brief Delete a database and/or free all its pages.
+       /** @brief Empty or delete+close a database.
         *
-        * If the \b del parameter is 1, the DB handle will be closed
-        * and the DB will be deleted.
         * @param[in] txn A transaction handle returned by #mdb_txn_begin()
         * @param[in] dbi A database handle returned by #mdb_dbi_open()
-        * @param[in] del 1 to delete the DB from the environment,
-        * 0 to just free its pages.
+        * @param[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.
         */
 int  mdb_drop(MDB_txn *txn, MDB_dbi dbi, int del);

diff --git a/libraries/liblmdb/mdb_copy.1 b/libraries/liblmdb/mdb_copy.1
index 7837de5f6beb88dead6c777fa2a4f03be9c7a7fa..9b053f97d518be547fdf2665338086fb9e67306a 100644 (file)
--- a/libraries/liblmdb/mdb_copy.1
+++ b/libraries/liblmdb/mdb_copy.1
@@ -11,6 +11,7 @@ The
 .B mdb_copy
 utility copies an LMDB environment. The environment can
 be copied regardless of whether it is currently in use.
+No lockfile is created, since it gets recreated at need.
 
 If
 .I dstpath
@@ -22,6 +23,10 @@ written to stdout.
 Exit status is zero if no errors occur.
 Errors result in a non-zero exit status and
 a diagnostic message being written to standard error.
+.SH CAVEATS
+This utility can trigger significant file size growth if run
+in parallel with write transactions, because pages which they
+free during copying cannot be reused until the copy is done.
 .SH "SEE ALSO"
 .BR mdb_stat (1)
 .SH AUTHOR