X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=0b46a8cc0ce216186a744ca083f2348b521b2217;hp=0b0f04bf6b045acea1a988f154cfbecf072ee144;hb=63b76b34c79107cba091d1ea62e304d2666ec86d;hpb=7c83ef53090441de11cc78d8d26dc337cd7ac475

diff --git a/src/wimlib.h b/src/wimlib.h
index 0b0f04bf..0b46a8cc 100644
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -9,7 +9,7 @@
  */
 
 /*
- * Copyright (C) 2012 Eric Biggers
+ * Copyright (C) 2012, 2013 Eric Biggers
  *
  * This file is part of wimlib, a library for working with WIM files.
  *
@@ -31,6 +31,12 @@
  *
  * \section intro Introduction
  *
+ * This is the documentation for the library interface of wimlib 1.2.7.  If you
+ * have installed wimlib and want to know how to use the @c imagex program,
+ * please see the man pages instead.  Also: the actual project page where you
+ * can download the source code for the library is at <a
+ * href="https://sourceforge.net/projects/wimlib">https://sourceforge.net/projects/wimlib</a>.
+ *
  * wimlib is a C library to read, write, and mount archive files in the Windows
  * Imaging Format (WIM files).  These files are normally created using the @c
  * imagex.exe utility on Windows, but this library provides a free
@@ -113,8 +119,14 @@
  * message being printed.
  *
  * wimlib is thread-safe as long as different ::WIMStruct's are used, except for
- * the fact that wimlib_set_print_errors() and wimlib_set_memory_allocator()
- * both apply globally.
+ * the following exceptions:
+ * - wimlib_set_print_errors() and wimlib_set_memory_allocator() both apply globally.
+ * - You also must call wimlib_global_init() in the main thread to avoid any
+ *   race conditions with one-time allocations of memory.
+ * - wimlib_mount_image(), while it can be used to mount multiple WIMs
+ *   concurrently in the same process, will daemonize the entire process when it
+ *   does so for the first time.  This includes changing the working directory
+ *   to the root directory.
  *
  * To open an existing WIM, use wimlib_open_wim().
  *
@@ -211,9 +223,14 @@
 #include <stdbool.h>
 #include <inttypes.h>
 
+/** Major version of the library (for example, the 1 in 1.2.5). */
 #define WIMLIB_MAJOR_VERSION 1
+
+/** Minor version of the library (for example, the 2 in 1.2.5). */
 #define WIMLIB_MINOR_VERSION 2
-#define WIMLIB_PATCH_VERSION 0
+
+/** Patch version of the library (for example, the 5 in 1.2.5). */
+#define WIMLIB_PATCH_VERSION 7
 
 /**
  * Opaque structure that represents a WIM file.  This is an in-memory structure
@@ -297,17 +314,17 @@ enum wimlib_progress_msg {
 	 * ::wimlib_progress_info.scan. */
 	WIMLIB_PROGRESS_MSG_SCAN_END,
 
-	/** 
+	/**
 	 * File resources are currently being written to the WIM.
 	 * @a info will point to ::wimlib_progress_info.write_streams. */
 	WIMLIB_PROGRESS_MSG_WRITE_STREAMS,
 
-	/** 
+	/**
 	 * The metadata resource for each image is about to be written to the
 	 * WIM. @a info will not be valid. */
 	WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN,
 
-	/** 
+	/**
 	 * The metadata resource for each image has successfully been writen to
 	 * the WIM.  @a info will not be valid. */
 	WIMLIB_PROGRESS_MSG_WRITE_METADATA_END,
@@ -399,6 +416,11 @@ union wimlib_progress_info {
 		/** True iff @a cur_path is being excluded from the image
 		 * capture due to the capture configuration file. */
 		bool excluded;
+
+		/** Target path in the WIM.  Only valid on messages
+		 * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
+		 * ::WIMLIB_PROGRESS_MSG_SCAN_END. */
+		const char *wim_target_path;
 	} scan;
 
 	/** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
@@ -410,6 +432,12 @@ union wimlib_progress_info {
 		/** Number of the image being extracted (1-based). */
 		int image;
 
+		/** Flags passed to to wimlib_extract_image() */
+		int extract_flags;
+
+		/** Full path to the WIM file being extracted. */
+		const char *wimfile_name;
+
 		/** Name of the image being extracted. */
 		const char *image_name;
 
@@ -493,9 +521,6 @@ union wimlib_progress_info {
 
 		/** Number of split WIM parts. */
 		unsigned total_parts;
-
-		/** Name of the joined WIM file being written. */
-		const char *filename;
 	} join;
 
 	/** Valid on messages ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and
@@ -534,12 +559,30 @@ union wimlib_progress_info {
 typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
 				      const union wimlib_progress_info *info);
 
+/** An array of these structures is passed to wimlib_add_image_multisource() to
+ * specify the sources from which to create a WIM image. */
+struct wimlib_capture_source {
+	/** Absolute or relative path to a file or directory on the external
+	 * filesystem to be included in the WIM image. */
+	char *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. */
+	char *wim_target_path;
+
+	/** Reserved; set to 0. */
+	long reserved;
+};
+
 
 /*****************************
  * WIMLIB_ADD_IMAGE_FLAG_*   *
  *****************************/
 
-/** Directly capture a NTFS volume rather than a generic directory */
+/** Directly capture a NTFS volume rather than a generic directory.  This flag
+ * cannot be combined with ::WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE or
+ * ::WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA.   */
 #define WIMLIB_ADD_IMAGE_FLAG_NTFS			0x00000001
 
 /** Follow symlinks; archive and dump the files they point to.  Cannot be used
@@ -554,6 +597,14 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
 /** Mark the image being added as the bootable image of the WIM. */
 #define WIMLIB_ADD_IMAGE_FLAG_BOOT			0x00000008
 
+/** Store the UNIX owner, group, and mode.  This is done by adding a special
+ * 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 version of imagex.exe will not understand this special
+ * information.  This flag cannot be combined with ::WIMLIB_ADD_IMAGE_FLAG_NTFS.
+ * */
+#define WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA			0x00000010
+
 /******************************
  * WIMLIB_EXPORT_FLAG_* *
  ******************************/
@@ -586,6 +637,10 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
 /** Read the WIM file sequentially while extracting the image. */
 #define WIMLIB_EXTRACT_FLAG_SEQUENTIAL			0x00000010
 
+/** Extract special UNIX data captured with ::WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA.
+ * Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */
+#define WIMLIB_EXTRACT_FLAG_UNIX_DATA			0x00000020
+
 /******************************
  * WIMLIB_MOUNT_FLAG_*        *
  ******************************/
@@ -607,6 +662,14 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * file name, a colon, then the alternate file stream name. */
 #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS	0x00000010
 
+/** Use UNIX file owners, groups, and modes if available in the WIM (see
+ * ::WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA). */
+#define WIMLIB_MOUNT_FLAG_UNIX_DATA			0x00000020
+
+/** Allow other users to see the mounted filesystem.  (this passes the @c
+ * allow_other option to FUSE mount) */
+#define WIMLIB_MOUNT_FLAG_ALLOW_OTHER			0x00000040
+
 /******************************
  * WIMLIB_OPEN_FLAG_*         *
  ******************************/
@@ -629,6 +692,12 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * discarded.  Ignored for read-only mounts. */
 #define WIMLIB_UNMOUNT_FLAG_COMMIT			0x00000002
 
+/** See ::WIMLIB_WRITE_FLAG_REBUILD */
+#define WIMLIB_UNMOUNT_FLAG_REBUILD			0x00000004
+
+/** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */
+#define WIMLIB_UNMOUNT_FLAG_RECOMPRESS			0x00000008
+
 /******************************
  * WIMLIB_WRITE_FLAG_*        *
  ******************************/
@@ -648,7 +717,7 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
 /** Call fsync() when the WIM file is closed */
 #define WIMLIB_WRITE_FLAG_FSYNC				0x00000008
 
-/** Specifying this flag overrides the default behavior of wimlib_overwrite()
+/* 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.
  *
@@ -665,15 +734,20 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type,
  * See the documentation for each wimlib function to see specifically what error
  * codes can be returned by a given function, and what they mean.
  */
+/* Note: these are currently in alphabetic order, but new error codes should be
+ * added at the end to maintain a compatible ABI, except when it's being broken
+ * anyway. */
 enum wimlib_error_code {
 	WIMLIB_ERR_SUCCESS = 0,
 	WIMLIB_ERR_ALREADY_LOCKED,
 	WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE,
 	WIMLIB_ERR_DECOMPRESSION,
 	WIMLIB_ERR_DELETE_STAGING_DIR,
+	WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED,
 	WIMLIB_ERR_FORK,
 	WIMLIB_ERR_FUSE,
 	WIMLIB_ERR_FUSERMOUNT,
+	WIMLIB_ERR_ICONV_NOT_AVAILABLE,
 	WIMLIB_ERR_IMAGE_COUNT,
 	WIMLIB_ERR_IMAGE_NAME_COLLISION,
 	WIMLIB_ERR_INTEGRITY,
@@ -686,9 +760,14 @@ enum wimlib_error_code {
 	WIMLIB_ERR_INVALID_INTEGRITY_TABLE,
 	WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY,
 	WIMLIB_ERR_INVALID_PARAM,
+	WIMLIB_ERR_INVALID_PART_NUMBER,
 	WIMLIB_ERR_INVALID_RESOURCE_HASH,
 	WIMLIB_ERR_INVALID_RESOURCE_SIZE,
 	WIMLIB_ERR_INVALID_SECURITY_DATA,
+	WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE,
+	WIMLIB_ERR_INVALID_UTF8_STRING,
+	WIMLIB_ERR_INVALID_UTF16_STRING,
+	WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE,
 	WIMLIB_ERR_LINK,
 	WIMLIB_ERR_MKDIR,
 	WIMLIB_ERR_MQUEUE,
@@ -713,6 +792,7 @@ enum wimlib_error_code {
 	WIMLIB_ERR_UNSUPPORTED,
 	WIMLIB_ERR_WRITE,
 	WIMLIB_ERR_XML,
+	WIMLIB_ERR_INVALID_OVERLAY,
 };
 
 
@@ -725,14 +805,19 @@ enum wimlib_error_code {
 /**
  * Adds an image to a WIM file from an on-disk directory tree or NTFS volume.
  *
- * The directory tree is read immediately for the purpose of constructing a
- * directory entry tree in-memory.  Also, all files are read to calculate their
- * SHA1 message digests.  However, because the directory tree may contain a very
- * large amount of data, the files themselves are not read into memory
- * permanently, and instead references to their paths saved.  The files are then
- * read on-demand if wimlib_write() or wimlib_overwrite() is called.
+ * The directory tree of NTFS volume is read immediately for the purpose of
+ * constructing a directory entry tree in-memory.  Also, all files are read to
+ * calculate their SHA1 message digests.  However, because the directory tree
+ * may contain a very large amount of data, the files themselves are not read
+ * into memory permanently, and instead references to their paths saved.  The
+ * files are then read on-demand if wimlib_write() or wimlib_overwrite() is
+ * called.
  *
- * Please note that @b no changes are committed to the underlying WIM file (if
+ * See the manual page for the @c imagex program for more information about the
+ * "normal" capture mode versus the NTFS capture mode (entered by providing the
+ * flag ::WIMLIB_ADD_IMAGE_FLAG_NTFS).
+ *
+ * Note that @b no changes are committed to the underlying WIM file (if
  * any) until wimlib_write() or wimlib_overwrite() is called.
  *
  * @param wim
@@ -748,19 +833,10 @@ enum wimlib_error_code {
  * 	NULL, a default string is used.  Please see the manual page for
  * 	<b>imagex capture</b> for more information.
  * @param config_len
- * 	Length of the string @a config in bytes.  Ignored if @a config is @c
- * 	NULL.
- *
+ * 	Length of the string @a config in bytes, not including an optional
+ * 	null-terminator.  Ignored if @a config is @c NULL.
  * @param add_image_flags
- * 	Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_BOOT is specified, the image in @a wim that is
- * 	marked as bootable is changed to the one being added.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_VERBOSE is specified, the name of each file is
- * 	printed as it is scanned or captured.  If
- * 	::WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE is specified, the files or
- * 	directories pointed to by symbolic links are archived rather than the
- * 	symbolic links themselves.
- *
+ * 	Bitwise OR of flags prefixed with WIMLIB_ADD_IMAGE_FLAG.
  * @param progress_func
  * 	If non-NULL, a function that will be called periodically with the
  * 	progress of the current operation.
@@ -805,7 +881,7 @@ enum wimlib_error_code {
  * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
  * 	@a wim is part of a split WIM.  Adding an image to a split WIM is
  * 	unsupported.
- * @retval ::WIMLIB_ERR_UNSUPPORTED:
+ * @retval ::WIMLIB_ERR_UNSUPPORTED
  * 	::WIMLIB_ADD_IMAGE_FLAG_NTFS was specified in @a add_image_flags, but
  * 	wimlib was configured with the @c --without-ntfs-3g flag.
  */
@@ -814,6 +890,37 @@ extern int wimlib_add_image(WIMStruct *wim, const char *source,
 			    size_t config_len, int add_image_flags,
 			    wimlib_progress_func_t progress_func);
 
+/** This function is equivalent to wimlib_add_image() except it allows for
+ * multiple sources to be combined into a single WIM image.  This is done by
+ * specifying the @a sources and @a num_sources parameters instead of the @a
+ * source parameter of wimlib_add_image().  The rest of the parameters are the
+ * same as wimlib_add_image().  See the documentation for <b>imagex capture</b>
+ * for full details on how this mode works.
+ *
+ * Additional note:  @a sources is not a @c const parameter and you cannot
+ * assume that its contents are valid after this function returns.  You must
+ * save pointers to the strings in these structures if you need to free them
+ * later, and/or save copies if needed.
+ *
+ * In addition to the error codes that wimlib_add_image() can return,
+ * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY
+ * when trying to overlay a non-directory on a directory or when otherwise
+ * trying to overlay multiple conflicting files to the same location in the WIM
+ * image.  It will also return ::WIMLIB_ERR_INVALID_PARAM if
+ * ::WIMLIB_ADD_IMAGE_FLAG_NTFS was specified in @a add_image_flags but there
+ * was not exactly one capture source with the target being the root directory.
+ * (In this respect, there is no advantage to using
+ * wimlib_add_image_multisource() instead of wimlib_add_image() when requesting
+ * NTFS mode.) */
+extern int wimlib_add_image_multisource(WIMStruct *w,
+					struct wimlib_capture_source *sources,
+					size_t num_sources,
+					const char *name,
+					const char *config_str,
+					size_t config_len,
+					int add_image_flags,
+					wimlib_progress_func_t progress_func);
+
 /**
  * Creates a ::WIMStruct for a new WIM file.
  *
@@ -970,8 +1077,7 @@ extern int wimlib_delete_image(WIMStruct *wim, int image);
  * 	::WIMLIB_ALL_IMAGES, @a src_wim contains multiple images, and no images in
  * 	@a src_wim are marked as bootable; or @a dest_name and/or @a
  * 	dest_description were non-<code>NULL</code>, @a src_image was
- * 	::WIMLIB_ALL_IMAGES, and @a src_wim contains multiple images; or @a src_wim
- * 	or @a dest_wim was @c NULL.
+ * 	::WIMLIB_ALL_IMAGES, and @a src_wim contains multiple images.
  * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
  *	The metadata resource for @a src_image in @a src_wim is invalid.
  * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA
@@ -1073,12 +1179,14 @@ extern int wimlib_export_image(WIMStruct *src_wim, int src_image,
  * 	A directory entry in the metadata resource for @a image in @a wim is
  * 	invalid.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a wim was @c NULL, or @a target was @c NULL, or both
- * 	::WIMLIB_EXTRACT_FLAG_HARDLINK and ::WIMLIB_EXTRACT_FLAG_SYMLINK were
- * 	specified in @a extract_flags, or both ::WIMLIB_EXTRACT_FLAG_NTFS and
- * 	either ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK
- * 	were specified in @a extract_flags, or ::WIMLIB_EXTRACT_FLAG_NTFS was
- * 	specified in @a extract_flags and @a image was ::WIMLIB_ALL_IMAGES.
+ * 	@a target was @c NULL, or both ::WIMLIB_EXTRACT_FLAG_HARDLINK and
+ * 	::WIMLIB_EXTRACT_FLAG_SYMLINK were specified in @a extract_flags; or
+ * 	both ::WIMLIB_EXTRACT_FLAG_NTFS and either
+ * 	::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK were
+ * 	specified in @a extract_flags; or ::WIMLIB_EXTRACT_FLAG_NTFS was
+ * 	specified in @a extract_flags and @a image was ::WIMLIB_ALL_IMAGES; or
+ * 	both ::WIMLIB_EXTRACT_FLAG_NTFS and ::WIMLIB_EXTRACT_FLAG_UNIX_DATA were
+ * 	specified in @a extract_flag.
  * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
  * 	The SHA1 message digest of an extracted stream did not match the SHA1
  * 	message digest given in the WIM file.
@@ -1267,6 +1375,34 @@ extern int wimlib_get_num_images(const WIMStruct *wim);
  */
 extern int wimlib_get_part_number(const WIMStruct *wim, int *total_parts_ret);
 
+/**
+ * Since wimlib 1.2.6:  Initialization function for wimlib.  This is not
+ * re-entrant.  If you are calling wimlib functions concurrently in different
+ * threads, then you must call this function serially first.  Otherwise, calling
+ * this function is not required.
+ *
+ * @return 0 on success; nonzero on error.
+ * @retval ::WIMLIB_ERR_NOMEM
+ * 	Could not allocate memory.
+ * @retval ::WIMLIB_ERR_ICONV_NOT_AVAILABLE
+ * 	wimlib was configured @c --without-libntfs-3g at compilation time, and
+ * 	at runtime the @c iconv() set of functions did not seem to be available,
+ * 	perhaps due to missing files in the C library installation.
+ *
+ * If this function is not called or returns nonzero, then it will not be safe
+ * to use wimlib in multiple threads.  Furthermore, a nonzero return value here
+ * indicates that further calls into wimlib will probably fail when they try to
+ * repeat the same initializations.
+ */
+extern int wimlib_global_init();
+
+/**
+ * Since wimlib 1.2.6:  Cleanup function for wimlib.  This is not re-entrant.
+ * You are not required to call this function, but it will release any global
+ * memory allocated by the library.
+ */
+extern void wimlib_global_cleanup();
+
 /**
  * Returns true if the WIM has an integrity table.
  *
@@ -1333,7 +1469,7 @@ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const char *name);
  * Note: wimlib_export_image() can provide similar functionality to
  * wimlib_join(), since it is possible to export all images from a split WIM.
  */
-extern int wimlib_join(const char **swms, unsigned num_swms,
+extern int wimlib_join(const char * const *swms, unsigned num_swms,
 		       const char *output_path, int swm_open_flags,
 		       int wim_write_flags,
 		       wimlib_progress_func_t progress_func);
@@ -1341,27 +1477,20 @@ extern int wimlib_join(const char **swms, unsigned num_swms,
 /**
  * Mounts an image in a WIM file on a directory read-only or read-write.
  *
- * A daemon will be forked to service the filesystem, unless
- * ::WIMLIB_MOUNT_FLAG_DEBUG is specified in @a mount_flags.  In other words,
- * this function returns @b before the image is unmounted, and filesystem
- * requests are handled by a new thread.  This also means that no functions may
- * be safely called on @a wim after wimlib_mount_image() has been called on any
- * images from it.  (@a wim will be freed by the filesystem thread after the
- * filesystem is unmounted.)
+ * Unless ::WIMLIB_MOUNT_FLAG_DEBUG is specified or an early error occurs, the
+ * process shall be daemonized.
  *
  * If the mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified),
- * modifications to the WIM are staged in a temporary directory created in the
- * process's working directory when this function is called.
+ * modifications to the WIM are staged in a temporary directory.
  *
  * It is safe to mount multiple images from the same WIM file read-only at the
- * same time (but different ::WIMStruct's should be used).  However, it is @b
- * not safe to mount multiple images from the same WIM file read-write at the
- * same time.
+ * same time, but only if different ::WIMStruct's are used.  It is @b not safe
+ * to mount multiple images from the same WIM file read-write at the same time.
  *
  * wimlib_mount_image() cannot be used on an image that was exported with
  * wimlib_export_image() while the dentry trees for both images are still in
  * memory.  In addition, wimlib_mount_image() may not be used to mount an image
- * that has just been added with wimlib_add_image(), or unless the WIM has been
+ * that has just been added with wimlib_add_image(), unless the WIM has been
  * written and read into a new ::WIMStruct.
  *
  * @param wim
@@ -1395,10 +1524,18 @@ extern int wimlib_join(const char **swms, unsigned num_swms,
  * 	This number should be one less than the total number of parts in the
  * 	split WIM.  Set to 0 if the WIM is a standalone WIM.
  * @param staging_dir
- * 	Currently ignored, but may provide a way to specify the staging
- * 	directory in the future.  Set to @c NULL.
+ * 	If non-NULL, the name of a directory in which the staging directory will
+ * 	be created.  Ignored if ::WIMLIB_MOUNT_FLAG_READWRITE is not specified
+ * 	in @a mount_flags.  If left @c NULL, the staging directory is created in
+ * 	the same directory as the WIM file that @a wim was originally read from.
  *
  * @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
+ * 	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.
  * @retval ::WIMLIB_ERR_DECOMPRESSION
  * 	Could not decompress the metadata resource for @a image in @a wim.
  * @retval ::WIMLIB_ERR_FUSE
@@ -1411,7 +1548,7 @@ extern int wimlib_join(const char **swms, unsigned num_swms,
  * @retval ::WIMLIB_ERR_INVALID_PARAM
  * 	@a image is shared among multiple ::WIMStruct's as a result of a call to
  * 	wimlib_export_image(), or @a image has been added with
- * 	wimlib_add_image() or wimlib_add_image_from_ntfs_volume().
+ * 	wimlib_add_image().
  * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
  *	The metadata resource for @a image in @a wim is invalid.
  * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA
@@ -1577,10 +1714,10 @@ extern int wimlib_open_wim(const char *wim_file, int open_flags,
  * @return 0 on success; nonzero on error.  This function may return any value
  * returned by wimlib_write() as well as the following error codes:
  * @retval ::WIMLIB_ERR_ALREADY_LOCKED
- * 	The append-only overwrite mode was going to be used, but an exclusive
- * 	advisory lock on the on-disk WIM file could not be acquired, probably
- * 	because another thread or process was calling wimlib_overwrite() on the
- * 	same underlying on-disk file at the same time.
+ * 	The WIM was going to be modifien in-place (with no temporary file), 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.
  * @retval ::WIMLIB_ERR_NO_FILENAME
  * 	@a wim corresponds to a WIM created with wimlib_create_new_wim() rather
  * 	than a WIM read with wimlib_open_wim().
@@ -1633,8 +1770,6 @@ extern void wimlib_print_available_images(const WIMStruct *wim, int image);
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@a image does not specify a valid image in @a wim, and is not
  * 	::WIMLIB_ALL_IMAGES.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a wim was @c NULL.
  * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
  * 	The metadata resource for one of the specified images is invalid.
  * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA
@@ -1697,8 +1832,6 @@ extern void wimlib_print_lookup_table(WIMStruct *wim);
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@a image does not specify a valid image in @a wim, and is not
  * 	::WIMLIB_ALL_IMAGES.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a wim was @c NULL.
  * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
  * 	The metadata resource for one of the specified images is invalid.
  * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA
@@ -1764,8 +1897,6 @@ extern int wimlib_resolve_image(WIMStruct *wim, const char *image_name_or_num);
  * 	The number of the image to mark as bootable, or 0 to mark no image as
  * 	bootable.
  * @return 0 on success; nonzero on error.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a wim was @c NULL.
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@a boot_idx does not specify an existing image in @a wim, and it was not
  * 	0.
@@ -1791,8 +1922,6 @@ extern int wimlib_set_boot_idx(WIMStruct *wim, int boot_idx);
  * @return 0 on success; nonzero on error.
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@a image does not specify a single existing image in @a wim.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a wim was @c NULL.
  * @retval ::WIMLIB_ERR_NOMEM
  * 	Failed to allocate the memory needed to duplicate the @a description
  * 	string.
@@ -1817,8 +1946,6 @@ extern int wimlib_set_image_descripton(WIMStruct *wim, int image,
  * @return 0 on success; nonzero on error.
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@a image does not specify a single existing image in @a wim.
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a wim was @c NULL.
  * @retval ::WIMLIB_ERR_NOMEM
  * 	Failed to allocate the memory needed to duplicate the @a flags string.
  */
@@ -1834,13 +1961,13 @@ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const char *flags);
  * @param image
  * 	The number of the image for which to change the name.
  * @param name
- * 	The new name to give the image.  It must not a nonempty string.
+ * 	The new name to give the image.  It must be a nonempty string.
  *
  * @return 0 on success; nonzero on error.
  * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
  * 	There is already an image named @a name in @a wim.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a name was @c NULL or the empty string, or @a wim was @c NULL.
+ * 	@a name was @c NULL or the empty string.
  * @retval ::WIMLIB_ERR_INVALID_IMAGE
  * 	@a image does not specify a single existing image in @a wim.
  * @retval ::WIMLIB_ERR_NOMEM
@@ -1927,10 +2054,10 @@ extern int wimlib_set_print_errors(bool show_messages);
  * @return 0 on success; nonzero on error.  This function may return any value
  * returned by wimlib_write() as well as the following error codes:
  *
- * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED:
+ * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED
  * 	@a wim is not part 1 of a stand-alone WIM.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a w was @c NULL, @a swm_name was @c NULL, or @a part_size was 0.
+ * 	@a swm_name was @c NULL, or @a part_size was 0.
  *
  * Note: the WIM's uncompressed and compressed resources are not checksummed
  * when they are copied from the joined WIM to the split WIM parts, nor are
@@ -1949,29 +2076,29 @@ extern int wimlib_split(WIMStruct *wim, const char *swm_name,
  *
  * To unmount the image, the thread calling this function communicates with the
  * thread that is managing the mounted WIM image.  This function blocks until it
- * is known whether the unmount succeeded or failed.  (This means until the
- * entire WIM has been re-written, in the case of a read-write mounted WIM.)
- *
- * There is currently a design problem with this function because it is hard to
- * know whether the filesystem thread is still working or whether it has crashed
- * or has been killed.  Currently, a timeout of 600 seconds (so long because
- * WIMs can be very large) is implemented so that this function will not wait
- * forever before returning failure.
+ * is known whether the unmount succeeded or failed.  In the case of a
+ * read-write mounted WIM, the unmount is not considered to have succeeded until
+ * all changes have been saved to the underlying WIM file.
  *
  * @param dir
  * 	The directory that the WIM image was mounted on.
  * @param unmount_flags
- * 	Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY and/or
- * 	::WIMLIB_UNMOUNT_FLAG_COMMIT.  Neither of these flags affect read-only
+ * 	Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY,
+ * 	::WIMLIB_UNMOUNT_FLAG_COMMIT, ::WIMLIB_UNMOUNT_FLAG_REBUILD, and/or
+ * 	::WIMLIB_UNMOUNT_FLAG_RECOMPRESS.  None of these flags affect read-only
  * 	mounts.
  * @param progress_func
- * 	Currently ignored, but may be used for a progress callback in the
- * 	future.  Set to @c NULL.
+ * 	If non-NULL, a function that will be called periodically with the
+ * 	progress of the current operation.
  *
  * @return 0 on success; nonzero on error.
+ *
  * @retval ::WIMLIB_ERR_DELETE_STAGING_DIR
  * 	The filesystem daemon was unable to remove the staging directory and the
  * 	temporary files that it contains.
+ * @retval ::WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED
+ * 	The filesystem daemon appears to have terminated before sending an exit
+ * 	status.
  * @retval ::WIMLIB_ERR_FORK
  * 	Could not @c fork() the process.
  * @retval ::WIMLIB_ERR_FUSERMOUNT
@@ -1986,10 +2113,6 @@ extern int wimlib_split(WIMStruct *wim, const char *swm_name,
  * @retval ::WIMLIB_ERR_OPEN
  * 	The filesystem daemon could not open a temporary file for writing the
  * 	new WIM.
- * @retval ::WIMLIB_ERR_TIMEOUT
- * 	600 seconds elapsed while waiting for the filesystem daemon to notify
- * 	the process of its exit status, so the WIM file probably was not written
- * 	successfully.
  * @retval ::WIMLIB_ERR_READ
  * 	A read error occurred when the filesystem daemon tried to a file from
  * 	the staging directory
@@ -2045,11 +2168,11 @@ extern int wimlib_unmount_image(const char *dir, int unmount_flags,
  * 	@a image does not specify a single existing image in @a wim, and is not
  * 	::WIMLIB_ALL_IMAGES.
  * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
- * 	A file that had previously been scanned for inclusion in the WIM by the
- * 	wimlib_add_image() or wimlib_add_image_from_ntfs_volume() functions was
- * 	concurrently modified, so it failed the SHA1 message digest check.
+ * 	A file that had previously been scanned for inclusion in the WIM by
+ * 	wimlib_add_image() was concurrently modified, so it failed the SHA1
+ * 	message digest check.
  * @retval ::WIMLIB_ERR_INVALID_PARAM
- * 	@a wim or @a path was @c NULL.
+ * 	@a path was @c NULL.
  * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE
  *	The metadata resource for @a image in @a wim is invalid.
  * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA