*
* \section intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.2.0. If you
+ * This is the documentation for the library interface of wimlib 1.2.1. If you
* have installed wimlib and want to know how to use the @c imagex program,
* please see the man pages instead.
*
#define WIMLIB_MAJOR_VERSION 1
#define WIMLIB_MINOR_VERSION 2
-#define WIMLIB_PATCH_VERSION 0
+#define WIMLIB_PATCH_VERSION 1
/**
* Opaque structure that represents a WIM file. This is an in-memory structure
/** 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
* 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_* *
******************************/
/** 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.
*
enum wimlib_error_code {
WIMLIB_ERR_SUCCESS = 0,
WIMLIB_ERR_ALREADY_LOCKED,
+ WIMLIB_ERR_CHAR_CONVERSION,
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_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_LINK,
WIMLIB_ERR_MKDIR,
WIMLIB_ERR_MQUEUE,
* ::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
* 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
+ * @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.
* @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH
* The SHA1 message digest of an extracted stream did not match the SHA1
/**
* 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.)
+ * The calling thread will be daemonized service the filesystem, and this
+ * function will not return until the image is unmounted, unless an error occurs
+ * before the filesystem is successfully mounted.
*
* 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
* 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
* @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
* @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
* 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.
* @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.
* @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.
*/
* @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
* @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
*
* 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.
* ::WIMLIB_UNMOUNT_FLAG_COMMIT. Neither 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
* @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
* wimlib_add_image() or wimlib_add_image_from_ntfs_volume() functions 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