wimlib.h: update outdated comment

[wimlib] / include / wimlib.h

diff --git a/include/wimlib.h b/include/wimlib.h
index bdb2c33ea88e4be8fd6401d7f4929481d34426fc..98f3d0234535c5c7ba3b943c10351d811c715d47 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -2260,6 +2260,24 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  */
 #define WIMLIB_WRITE_FLAG_NO_SOLID_SORT                        0x00004000
 
+/**
+ * Since wimlib v1.8.3 and for wimlib_overwrite() only: <b>unsafely</b> compact
+ * the WIM file in-place, without appending.  Existing resources are shifted
+ * down to fill holes and new resources are appended as needed.  The WIM file is
+ * truncated to its final size, which may shrink the on-disk file.  <b>This
+ * operation cannot be safely interrupted.  If the operation is interrupted,
+ * then the WIM file will be corrupted, and it may be impossible (or at least
+ * very difficult) to recover any data from it.  Users of this flag are expected
+ * to know what they are doing and assume responsibility for any data corruption
+ * that may result.</b>
+ *
+ * If the WIM file cannot be compacted in-place because of its structure, its
+ * layout, or other requested write parameters, then wimlib_overwrite() fails
+ * with ::WIMLIB_ERR_COMPACTION_NOT_POSSIBLE, and the caller may wish to retry
+ * the operation without this flag.
+ */
+#define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT               0x00008000
+
 /** @} */
 /** @addtogroup G_general
  * @{ */
@@ -2270,12 +2288,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 #define WIMLIB_INIT_FLAG_ASSUME_UTF8                   0x00000001
 
 /** Windows-only: do not attempt to acquire additional privileges (currently
- * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and
- * SeTakeOwnershipPrivilege) when initializing the library.  This flag is
- * intended for the case where the calling program manages these privileges
- * itself.  Note: by default, no error is issued if privileges cannot be
- * acquired, although related errors may be reported later, depending on if the
- * operations performed actually require additional privileges or not.  */
+ * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege,
+ * SeTakeOwnershipPrivilege, and SeManageVolumePrivilege) when initializing the
+ * library.  This flag is intended for the case where the calling program
+ * manages these privileges itself.  Note: by default, no error is issued if
+ * privileges cannot be acquired, although related errors may be reported later,
+ * depending on if the operations performed actually require additional
+ * privileges or not.  */
 #define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES       0x00000002
 
 /** Windows only:  If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified,
@@ -2477,6 +2496,7 @@ enum wimlib_error_code {
        WIMLIB_ERR_FVE_LOCKED_VOLUME                  = 82,
        WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG      = 83,
        WIMLIB_ERR_WIM_IS_INCOMPLETE                  = 84,
+       WIMLIB_ERR_COMPACTION_NOT_POSSIBLE            = 85,
 };
 
 
@@ -3588,22 +3608,23 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file,
 /**
  * @ingroup G_writing_and_overwriting_wims
  *
- * Commit a ::WIMStruct to disk, overwriting its backing file or appending to it
- * as needed.
+ * Commit a ::WIMStruct to disk, updating its backing file.
  *
- * There are two alternative ways in which changes may be committed:
+ * There are several alternative ways in which changes may be committed:
  *
  *   1. Full rebuild: write the updated WIM to a temporary file, then rename the
  *     temporary file to the original.
  *   2. Appending: append updates to the new original WIM file, then overwrite
  *     its header such that those changes become visible to new readers.
- *
- * Append mode is often much faster, but it wastes some amount of space due to
- * leaving "holes" in the WIM file.  Because of the greater efficiency,
- * wimlib_overwrite() normally defaults to append mode.  However,
- * ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full rebuild.
- * In addition, if wimlib_delete_image() has been used on the ::WIMStruct, then
- * the default mode switches to rebuild mode, and
+ *   3. Compaction: normally should not be used; see
+ *     ::WIMLIB_WRITE_FLAG_UNSAFE_COMPACT for details.
+ *
+ * Append mode is often much faster than a full rebuild, but it wastes some
+ * amount of space due to leaving "holes" in the WIM file.  Because of the
+ * greater efficiency, wimlib_overwrite() normally defaults to append mode.
+ * However, ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full
+ * rebuild.  In addition, if wimlib_delete_image() has been used on the
+ * ::WIMStruct, then the default mode switches to rebuild mode, and
  * ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append
  * mode.
  *