]> wimlib.net Git - wimlib/blobdiff - include/wimlib.h
Remove duplicate words & fix grammatical errors
[wimlib] / include / wimlib.h
index 9d3c96160dddf269f31f081db821199892655a56..1b62717de940673fc9a33ce2d26dbd95fdd9d554 100644 (file)
@@ -33,7 +33,7 @@
  *
  * @section sec_intro Introduction
  *
- * This is the documentation for the library interface of wimlib 1.6.2, a C
+ * This is the documentation for the library interface of wimlib 1.6.3, a C
  * library for creating, modifying, extracting, and mounting files in the
  * Windows Imaging Format.  This documentation is intended for developers only.
  * If you have installed wimlib and want to know how to use the @b wimlib-imagex
  * documented in the man page for @b wimlib-imagex.
  *
  * - The old WIM format from Vista pre-releases is not supported.
- * - wimlib does not provide a clone of the @b PEImg tool, or the @b Dism
+ * - wimlib does not provide a clone of the @b PEImg tool, or the @b DISM
  *   functionality other than that already present in @b ImageX, that allows you
  *   to make certain Windows-specific modifications to a Windows PE image, such
  *   as adding a driver or Windows component.  Such a tool could be implemented
 #define WIMLIB_MINOR_VERSION 6
 
 /** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 2
+#define WIMLIB_PATCH_VERSION 3
 
 #ifdef __cplusplus
 extern "C" {
@@ -392,6 +392,15 @@ typedef char wimlib_tchar;
 #  define WIMLIB_WIM_PATH_SEPARATOR_STRING "/"
 #endif
 
+/** Use this to specify the root directory of the WIM image.  */
+#define WIMLIB_WIM_ROOT_PATH WIMLIB_WIM_PATH_SEPARATOR_STRING
+
+/** Use this to test if the specified path refers to the root directory of the
+ * WIM image.  */
+#define WIMLIB_IS_WIM_ROOT_PATH(path) \
+               ((path)[0] == WIMLIB_WIM_PATH_SEPARATOR &&      \
+                (path)[1] == 0)
+
 #ifdef __GNUC__
 #  define _wimlib_deprecated __attribute__((deprecated))
 #else
@@ -567,9 +576,18 @@ enum wimlib_progress_msg {
 
        /** A file in the WIM image is being replaced as a result of a
         * ::wimlib_add_command without ::WIMLIB_ADD_FLAG_NO_REPLACE specified.
-        * This is only received when ::WIMLIB_ADD_FLAG_VERBOSE is also
-        * specified in the add command.  */
+        * @p info will point to ::wimlib_progress_info.replace.  This is only
+        * received when ::WIMLIB_ADD_FLAG_VERBOSE is also specified in the add
+        * command.  */
        WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM,
+
+       /** A WIM image is being applied with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and
+        * a file is being extracted normally (not as a WIMBoot "pointer file")
+        * due to it matching a pattern in the [PrepopulateList] section of the
+        * configuration file \Windows\System32\WimBootCompress.ini in the WIM
+        * image.  @info will point to ::wimlib_progress_info.wimboot_exclude.
+        */
+       WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE,
 };
 
 /** A pointer to this union is passed to the user-supplied
@@ -653,11 +671,10 @@ union wimlib_progress_info {
                int32_t  compression_type;
 
                /** Number of split WIM parts from which streams are being
-                * written (may be 0 if irrelevant).  */
+                * written (may be 0 if irrelevant).   */
                uint32_t total_parts;
 
-               /** Number of split WIM parts from which streams have been
-                * written (may be 0 if irrelevant).  */
+               /** This is currently broken and will always be 0.  */
                uint32_t completed_parts;
        } write_streams;
 
@@ -665,14 +682,14 @@ union wimlib_progress_info {
         * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY, and
         * ::WIMLIB_PROGRESS_MSG_SCAN_END.  */
        struct wimlib_progress_info_scan {
-               /** Top-level directory being scanned; or, when capturing a NTFS
+               /** Top-level directory being scanned; or, when capturing an NTFS
                 * volume with ::WIMLIB_ADD_FLAG_NTFS, this is instead the path
                 * to the file or block device that contains the NTFS volume
                 * being scanned.  */
                const wimlib_tchar *source;
 
                /** Path to the file (or directory) that has been scanned, valid
-                * on ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY.  When capturing a NTFS
+                * on ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY.  When capturing an NTFS
                 * volume with ::WIMLIB_ADD_FLAG_NTFS, this path will be
                 * relative to the root of the NTFS volume.  */
                const wimlib_tchar *cur_path;
@@ -703,10 +720,7 @@ union wimlib_progress_info {
                union {
                        /** Target path in the WIM image.  Only valid on
                         * messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
-                        * ::WIMLIB_PROGRESS_MSG_SCAN_END.  If capturing a full
-                        * image, this will be the empty string; otherwise it
-                        * will name the place in the WIM image at which the
-                        * directory tree is being added.  */
+                        * ::WIMLIB_PROGRESS_MSG_SCAN_END.  */
                        const wimlib_tchar *wim_target_path;
 
                        /** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status
@@ -824,8 +838,8 @@ union wimlib_progress_info {
                 * data stream, or a reparse data buffer.  */
                uint64_t num_streams;
 
-               /** This will be the empty string.  */
-               const wimlib_tchar *extract_root_wim_source_path;
+               /** Reserved.  */
+               const wimlib_tchar *reserved_2;
 
                /** Currently only used for
                 * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN.  */
@@ -925,6 +939,15 @@ union wimlib_progress_info {
                /** Path to the file in the WIM image that is being replaced  */
                const wimlib_tchar *path_in_wim;
        } replace;
+
+       /** Valid on messages ::WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE  */
+       struct wimlib_progress_info_wimboot_exclude {
+               /** Path to the file in the WIM image  */
+               const wimlib_tchar *path_in_wim;
+
+               /** Path to which the file is being extracted  */
+               const wimlib_tchar *extraction_path;
+       } wimboot_exclude;
 };
 
 /** A user-supplied function that will be called periodically during certain WIM
@@ -950,9 +973,8 @@ struct wimlib_capture_source {
         * filesystem to be included in the WIM image. */
        wimlib_tchar *fs_source_path;
 
-       /** Destination path in the WIM image.  Leading and trailing slashes are
-        * ignored.  The empty string or @c NULL means the root directory of the
-        * WIM image. */
+       /** Destination path in the WIM image.  Use ::WIMLIB_WIM_ROOT_PATH to
+        * specify the root directory of the WIM image.  */
        wimlib_tchar *wim_target_path;
 
        /** Reserved; set to 0. */
@@ -1258,13 +1280,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 /** @ingroup G_modifying_wims
  * @{ */
 
-/** Directly capture a NTFS volume rather than a generic directory.  This flag
+/** Directly capture an NTFS volume rather than a generic directory.  This flag
  * cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or
  * ::WIMLIB_ADD_FLAG_UNIX_DATA.   */
 #define WIMLIB_ADD_FLAG_NTFS                   0x00000001
 
-/** Follow symlinks; archive and dump the files they point to.  Cannot be used
- * with ::WIMLIB_ADD_FLAG_NTFS. */
+/** Follow symlinks; archive and dump the files they point to.  Currently only
+ * supported on UNIX-like systems.  */
 #define WIMLIB_ADD_FLAG_DEREFERENCE            0x00000002
 
 /** Call the progress function with the message
@@ -1280,7 +1302,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
  * alternate data stream to each regular file, symbolic link, and directory to
  * contain this information.  Please note that this flag is for convenience
  * only; Microsoft's implementation will not understand this special
- * information.  This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS.  */
+ * information.  */
 #define WIMLIB_ADD_FLAG_UNIX_DATA              0x00000010
 
 /** Do not capture security descriptors.  Only has an effect in NTFS capture
@@ -1317,8 +1339,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 #define WIMLIB_ADD_FLAG_NORPFIX                        0x00000200
 
 /** Do not automatically exclude unsupported files or directories from capture;
- * e.g. encrypted directories in NTFS-3g capture mode, or device files and FIFOs
- * on UNIX-like systems.  Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
+ * e.g. encrypted files in NTFS-3g capture mode, or device files and FIFOs on
+ * UNIX-like systems.  Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
  * such a file is encountered.  */
 #define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400
 
@@ -1413,14 +1435,19 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 /** Give the exported image(s) no descriptions.  */
 #define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS             0x00000004
 
+/** This advises the library that the program is finished with the source
+ * WIMStruct and will not attempt to access it after the call to
+ * wimlib_export_image(), with the exception of the call to wimlib_free().  */
+#define WIMLIB_EXPORT_FLAG_GIFT                                0x00000008
+
 /** @} */
 /** @ingroup G_extracting_wims
  * @{ */
 
-/** Extract the image directly to a NTFS volume rather than a generic directory.
+/** Extract the image directly to an NTFS volume rather than a generic directory.
  * This mode is only available if wimlib was compiled with libntfs-3g support;
  * if not, ::WIMLIB_ERR_UNSUPPORTED will be returned.  In this mode, the
- * extraction target will be interpreted as the path to a NTFS volume image (as
+ * extraction target will be interpreted as the path to an NTFS volume image (as
  * a regular file or block device) rather than a directory.  It will be opened
  * using libntfs-3g, and the image will be extracted to the NTFS filesystem's
  * root directory.  Note: this flag cannot be used when wimlib_extract_image()
@@ -1637,94 +1664,175 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 /** @ingroup G_writing_and_overwriting_wims
  * @{ */
 
-/** Include an integrity table in the WIM.
+/**
+ * Include an integrity table in the resulting WIM file.
  *
- * For WIMs created with wimlib_open_wim(), the default behavior is to include
- * an integrity table if and only if one was present before.  For WIMs created
- * with wimlib_create_new_wim(), the default behavior is to not include an
- * integrity table.  */
+ * For ::WIMStruct's created with wimlib_open_wim(), the default behavior is to
+ * include an integrity table if and only if one was present before.  For
+ * ::WIMStruct's created with wimlib_create_new_wim(), the default behavior is
+ * to not include an integrity table.
+ */
 #define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY              0x00000001
 
-/** Do not include an integrity table in the new WIM file.  This is the default
- * behavior, unless the WIM already included an integrity table.  */
+/**
+ * Do not include an integrity table in the resulting WIM file.  This is the
+ * default behavior, unless the ::WIMStruct was created by opening a WIM with an
+ * integrity table.
+ */
 #define WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY           0x00000002
 
-/** Write the WIM as "pipable".  After writing a WIM with this flag specified,
+/**
+ * Write the WIM as "pipable".  After writing a WIM with this flag specified,
  * images from it can be applied directly from a pipe using
  * wimlib_extract_image_from_pipe().  See the documentation for the --pipable
  * flag of `wimlib-imagex capture' for more information.  Beware: WIMs written
  * with this flag will not be compatible with Microsoft's software.
  *
- * For WIMs created with wimlib_open_wim(), the default behavior is to write the
- * WIM as pipable if and only if it was pipable before.  For WIMs created with
- * wimlib_create_new_wim(), the default behavior is to write the WIM as
- * non-pipable.  */
+ * For ::WIMStruct's created with wimlib_open_wim(), the default behavior is to
+ * write the WIM as pipable if and only if it was pipable before.  For
+ * ::WIMStruct's created with wimlib_create_new_wim(), the default behavior is
+ * to write the WIM as non-pipable.
+ */
 #define WIMLIB_WRITE_FLAG_PIPABLE                      0x00000004
 
-/** Do not write the WIM as "pipable".  This is the default behavior, unless the
- * WIM was pipable already.  */
+/**
+ * Do not write the WIM as "pipable".  This is the default behavior, unless the
+ * ::WIMStruct was created by opening a pipable WIM.
+ */
 #define WIMLIB_WRITE_FLAG_NOT_PIPABLE                  0x00000008
 
-/** Recompress all resources, even if they could otherwise be copied from a
- * different WIM with the same compression type (in the case of
- * wimlib_export_image() being called previously).  This flag is also valid in
- * the @p wim_write_flags of wimlib_join(), in which case all resources included
- * in the joined WIM file will be recompressed.  */
+/**
+ * When writing streams to the WIM file, recompress them, even if their data is
+ * already available in the desired compressed form (for example, in a WIM file
+ * from which an image has been exported using wimlib_export_image()).
+ *
+ * ::WIMLIB_WRITE_FLAG_RECOMPRESS can be used to recompress with a higher
+ * compression ratio for the same compression type and chunk size.  wimlib's LZX
+ * compressor currently can be given different parameters in order to achieve
+ * different balances between compression ratio and time.  In its default mode
+ * as of v1.5.3, it usually compresses slightly better than the competing
+ * Microsoft implementation.
+ *
+ * ::WIMLIB_WRITE_FLAG_RECOMPRESS can also be used in combination with
+ * ::WIMLIB_WRITE_FLAG_PACK_STREAMS to prevent any solid blocks from being
+ * re-used.  (Otherwise, solid blocks are re-used somewhat more liberally than
+ * normal compressed blocks.)
+ *
+ * ::WIMLIB_WRITE_FLAG_RECOMPRESS does <b>not</b> cause recompression of streams
+ * that would not otherwise be written.  For example, a call to
+ * wimlib_overwrite() with ::WIMLIB_WRITE_FLAG_RECOMPRESS will not, by itself,
+ * cause already-existing streams in the WIM file to be recompressed.  To force
+ * the WIM file to be fully rebuilt and recompressed, combine
+ * ::WIMLIB_WRITE_FLAG_RECOMPRESS with ::WIMLIB_WRITE_FLAG_REBUILD.
+ */
 #define WIMLIB_WRITE_FLAG_RECOMPRESS                   0x00000010
 
-/** Call fsync() just before the WIM file is closed.  */
+/**
+ * Immediately before closing the WIM file, sync its data to disk.
+ *
+ * wimlib_overwrite() will set this flag automatically if it decides to
+ * overwrite the WIM file via a temporary file instead of in-place.
+ */
 #define WIMLIB_WRITE_FLAG_FSYNC                                0x00000020
 
-/** wimlib_overwrite() only:  Re-build the entire WIM file rather than appending
- * data to it if possible.  */
+/**
+ * For wimlib_overwrite(), rebuild the entire WIM file, even if it otherwise
+ * could be updated merely be appending to it.
+ *
+ * When rebuilding the WIM file, stream reference counts will be recomputed, and
+ * any streams with 0 reference count (e.g. from deleted files or images) will
+ * not be included in the resulting WIM file.
+ *
+ * This flag can be combined with ::WIMLIB_WRITE_FLAG_RECOMPRESS to force all
+ * data to be recompressed.  Otherwise, compressed data is re-used if possible.
+ *
+ * wimlib_write() ignores this flag.
+ */
 #define WIMLIB_WRITE_FLAG_REBUILD                      0x00000040
 
-/** wimlib_overwrite() only:  Specifying this flag overrides the default
- * behavior of wimlib_overwrite() after one or more calls to
- * wimlib_delete_image(), which is to rebuild the entire WIM.  With this flag,
- * only minimal changes to correctly remove the image from the WIM will be
- * taken.  In particular, all streams will be left alone, even if they are no
- * longer referenced.  This is probably not what you want, because almost no
- * space will be saved by deleting an image in this way.  */
+/**
+ * For wimlib_overwrite(), override the default behavior after one or more calls
+ * to wimlib_delete_image(), which is to rebuild the entire WIM file.  With this
+ * flag, only minimal changes to correctly remove the image from the WIM file
+ * will be taken.  In particular, all streams will be retained, even if they are
+ * no longer referenced.  This may not be what you want, because no space will
+ * be saved by deleting an image in this way.
+ *
+ * wimlib_write() ignores this flag.
+ */
 #define WIMLIB_WRITE_FLAG_SOFT_DELETE                  0x00000080
 
-/** wimlib_overwrite() only:  Allow overwriting the WIM even if the readonly
- * flag is set in the WIM header.  This can be used in combination with
- * wimlib_set_wim_info() with the ::WIMLIB_CHANGE_READONLY_FLAG flag to actually
- * set the readonly flag on the on-disk WIM file.  */
+/**
+ * For wimlib_overwrite(), allow overwriting the WIM file even if the readonly
+ * flag (WIM_HDR_FLAG_READONLY) is set in the WIM header.  This can be used
+ * following a call to wimlib_set_wim_info() with the
+ * ::WIMLIB_CHANGE_READONLY_FLAG flag to actually set the readonly flag on the
+ * on-disk WIM file.
+ *
+ * wimlib_write() ignores this flag.
+ */
 #define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG         0x00000100
 
-/** Do not include non-metadata resources already present in other WIMs.  This
- * flag can be used to write a "delta" WIM after resources from the WIM on which
- * the delta is to be based were referenced with
- * wimlib_reference_resource_files() or wimlib_reference_resources().  */
+/**
+ * Do not include streams already present in other WIMs.  This flag can be used
+ * to write a "delta" WIM after resources from the WIM on which the delta is to
+ * be based were referenced with wimlib_reference_resource_files() or
+ * wimlib_reference_resources().
+ */
 #define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS           0x00000200
 
-/** Asserts that for writes of all WIM images, all streams needed for the WIM
- * are already present (not in external resource WIMs) and their reference
- * counts are correct, so the code does not need to recalculate which streams
- * are referenced.  This is for optimization purposes only, since with this flag
- * specified, the metadata resources may not need to be decompressed and parsed.
- *
- * This flag can be passed to wimlib_write() and wimlib_write_to_fd(), but is
- * already implied for wimlib_overwrite().  */
+/**
+ * Advises the library that for writes of all WIM images, all streams needed for
+ * the WIM are already present (not in external resource WIMs) and their
+ * reference counts are correct, so the code does not need to recalculate which
+ * streams are referenced.  This is for optimization purposes only, since with
+ * this flag specified, the metadata resources may not need to be decompressed
+ * and parsed.
+ *
+ * wimlib_overwrite() will set this flag automatically.
+ */
 #define WIMLIB_WRITE_FLAG_STREAMS_OK                   0x00000400
 
-#define WIMLIB_WRITE_FLAG_RESERVED                     0x00000800
+/**
+ * For wimlib_write(), retain the WIM's GUID instead of generating a new one.
+ *
+ * wimlib_overwrite() sets this by default, since the WIM remains, logically,
+ * the same file.
+ */
+#define WIMLIB_WRITE_FLAG_RETAIN_GUID                  0x00000800
 
 /**
  * When writing streams in the resulting WIM file, pack multiple streams into a
- * single WIM resource instead of compressing them independently.  This tends to
- * produce a better compression ratio at the cost of less random access.
- * However, WIMs created with this flag are only compatible with wimlib v1.6.0
- * or later and WIMGAPI Windows 8 or later, seemingly for Windows Setup only and
- * <b>not including ImageX and Dism</b>.  WIMs created with this flag must use
- * version number 3584 in their header instead of 68864.
- *
- * If this flag is passed to wimlib_overwrite() and the WIM did not previously
- * contain packed streams, the WIM's version number will be changed to 3584 and
- * the new streams will be written packed.  Use ::WIMLIB_WRITE_FLAG_REBUILD to
- * force the WIM to be fully rebuilt.  */
+ * single compressed resource instead of compressing them independently.  This
+ * is also known as creating a "solid archive".  This tends to produce a better
+ * compression ratio at the cost of much slower random access.
+ *
+ * WIM files created with this flag are only compatible with wimlib v1.6.0 or
+ * later, WIMGAPI Windows 8 or later, and DISM Windows 8.1 or later.  WIM files
+ * created with this flag use a different version number in their header (3584
+ * instead of 68864) and are also called "ESD files".
+ *
+ * If this flag is passed to wimlib_overwrite(), any new data streams will be
+ * written in solid mode.  Use both ::WIMLIB_WRITE_FLAG_REBUILD and
+ * ::WIMLIB_WRITE_FLAG_RECOMPRESS to force the entire WIM file be rebuilt with
+ * all streams recompressed in solid mode.
+ *
+ * Currently, new solid blocks will, by default, be written using LZMS
+ * compression with 32 MiB (33554432 byte) chunks.  Use
+ * wimlib_set_output_pack_compression_type() and/or
+ * wimlib_set_output_pack_chunk_size() to change this.  This is independent of
+ * the WIM's main compression type and chunk size; you can have a WIM that
+ * nominally uses LZX compression and 32768 byte chunks but actually contains
+ * LZMS-compressed solid blocks, for example.  However, if including solid
+ * blocks, I suggest that you set the WIM's main compression type to LZMS as
+ * well, either by creating the WIM with
+ * ::wimlib_create_new_wim(::WIMLIB_COMPRESSION_TYPE_LZMS, ...) or by calling
+ * ::wimlib_set_output_compression_type(..., ::WIMLIB_COMPRESSION_TYPE_LZMS).
+ *
+ * This flag will be set by default when writing or overwriting a WIM file that
+ * either already contains packed streams, or has had packed streams exported
+ * into it and the WIM's main compression type is LZMS.
+ */
 #define WIMLIB_WRITE_FLAG_PACK_STREAMS                 0x00001000
 
 /** @} */
@@ -1803,12 +1911,11 @@ enum wimlib_update_op {
 
 /** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */
 struct wimlib_add_command {
-       /** Filesystem path to the file or directory tree to
-        * add. */
+       /** Filesystem path to the file or directory tree to add.  */
        wimlib_tchar *fs_source_path;
-       /** Path, specified from the root of the WIM image, at
-        * which to add the file or directory tree within the
-        * WIM image. */
+
+       /** Destination path in the WIM image.  Use ::WIMLIB_WIM_ROOT_PATH to
+        * specify the root directory of the WIM image.  */
        wimlib_tchar *wim_target_path;
 
        /** Path to capture configuration file to use, or @c NULL for default.
@@ -1821,25 +1928,27 @@ struct wimlib_add_command {
 
 /** Data for a ::WIMLIB_UPDATE_OP_DELETE operation. */
 struct wimlib_delete_command {
-       /** Path, specified from the root of the WIM image, for
-        * the file or directory tree within the WIM image to be
-        * deleted. */
+
+       /** Path, specified from the root of the WIM image, for the file or
+        * directory tree within the WIM image to be deleted.  */
        wimlib_tchar *wim_path;
-       /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */
+
+       /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags.  */
        int delete_flags;
 };
 
 /** Data for a ::WIMLIB_UPDATE_OP_RENAME operation. */
 struct wimlib_rename_command {
-       /** Path, specified from the root of the WIM image, for
-        * the source file or directory tree within the WIM
-        * image. */
+
+       /** Path, specified from the root of the WIM image, for the source file
+        * or directory tree within the WIM image.  */
        wimlib_tchar *wim_source_path;
-       /** Path, specified from the root of the WIM image, for
-        * the destination file or directory tree within the WIM
-        * image. */
+
+       /** Path, specified from the root of the WIM image, for the destination
+        * file or directory tree within the WIM image.  */
        wimlib_tchar *wim_target_path;
-       /** Reserved; set to 0. */
+
+       /** Reserved; set to 0.  */
        int rename_flags;
 };
 
@@ -2084,6 +2193,20 @@ wimlib_add_image_multisource(WIMStruct *wim,
                             int add_flags,
                             wimlib_progress_func_t progress_func);
 
+/**
+ * @ingroup G_modifying_wims
+ *
+ * Add the file or directory tree at @p fs_source_path on the filesystem to the
+ * location @p wim_target_path within the specified @p image of the @p wim.
+ *
+ * This just builds an appropriate ::wimlib_add_command and passes it to
+ * wimlib_update_image().
+ */
+extern int
+wimlib_add_tree(WIMStruct *wim, int image,
+               const wimlib_tchar *fs_source_path,
+               const wimlib_tchar *wim_target_path, int add_flags);
+
 /**
  * @ingroup G_creating_and_opening_wims
  *
@@ -2150,6 +2273,18 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret);
 extern int
 wimlib_delete_image(WIMStruct *wim, int image);
 
+/**
+ * @ingroup G_modifying_wims
+ *
+ * Delete the @p path from the specified @p image of the @p wim.
+ *
+ * This just builds an appropriate ::wimlib_delete_command and passes it to
+ * wimlib_update_image().
+ */
+extern int
+wimlib_delete_path(WIMStruct *wim, int image,
+                  const wimlib_tchar *path, int delete_flags);
+
 /**
  * @ingroup G_modifying_wims
  *
@@ -2934,7 +3069,7 @@ wimlib_join(const wimlib_tchar * const *swms,
  * @return 0 on success; nonzero on error.
  *
  * @retval ::WIMLIB_ERR_ALREADY_LOCKED
- *     A read-write mount was requested, but an an exclusive advisory lock on
+ *     A read-write mount was requested, but an exclusive advisory lock on
  *     the on-disk WIM file could not be acquired because another thread or
  *     process has mounted an image from the WIM read-write or is currently
  *     modifying the WIM in-place.
@@ -3328,6 +3463,19 @@ wimlib_reference_template_image(WIMStruct *wim, int new_image,
                                WIMStruct *template_wim, int template_image,
                                int flags, wimlib_progress_func_t progress_func);
 
+/**
+ * @ingroup G_modifying_wims
+ *
+ * Rename the @p source_path to the @p dest_path in the specified @p image of
+ * the @p wim.
+ *
+ * This just builds an appropriate ::wimlib_rename_command and passes it to
+ * wimlib_update_image().
+ */
+extern int
+wimlib_rename_path(WIMStruct *wim, int image,
+                  const wimlib_tchar *source_path, const wimlib_tchar *dest_path);
+
 /**
  * @ingroup G_wim_information
  *
@@ -3424,7 +3572,7 @@ wimlib_set_output_chunk_size(WIMStruct *wim, uint32_t chunk_size);
  * @ingroup G_writing_and_overwriting_wims
  *
  * Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing
- * packed streams.
+ * packed streams (solid blocks).
  */
 extern int
 wimlib_set_output_pack_chunk_size(WIMStruct *wim, uint32_t chunk_size);
@@ -3757,7 +3905,7 @@ wimlib_unmount_image(const wimlib_tchar *dir,
  *     An unknown operation type was specified in the update commands; or,
  *     attempted to execute an add command where ::WIMLIB_ADD_FLAG_NTFS was set
  *     in the @p add_flags, but the same image had previously already been
- *     added from a NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and
+ *     added from an NTFS volume; or, both ::WIMLIB_ADD_FLAG_RPFIX and
  *     ::WIMLIB_ADD_FLAG_NORPFIX were specified in the @p add_flags for one add
  *     command; or, ::WIMLIB_ADD_FLAG_NTFS or ::WIMLIB_ADD_FLAG_RPFIX were
  *     specified in the @p add_flags for an add command in which @p