*
* @section sec_intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.6.3, a C
+ * This is the documentation for the library interface of wimlib 1.7.0, 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
* such as wimlib_join(), also take the progress function directly using an
* extended version of the function, such as wimlib_join_with_progress().
*
- * In wimlib v1.6.3 and later, progress functions are no longer just
+ * In wimlib v1.7.0 and later, progress functions are no longer just
* unidirectional. You can now return ::WIMLIB_PROGRESS_STATUS_ABORT to cause
- * the current operation to be aborted. wimlib v1.6.3 also added the third
+ * the current operation to be aborted. wimlib v1.7.0 also added the third
* argument to ::wimlib_progress_func_t, which is a user-supplied context.
*/
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 6
+#define WIMLIB_MINOR_VERSION 7
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 3
+#define WIMLIB_PATCH_VERSION 0
#ifdef __cplusplus
extern "C" {
* 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.
+ * image. @p info will point to ::wimlib_progress_info.wimboot_exclude.
*/
WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE = 24,
+
+ /** Starting to unmount a WIM image. @p info will point to
+ * ::wimlib_progress_info.unmount. */
+ WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25,
};
/** Valid return values from user-provided progress functions
WIMLIB_SCAN_DENTRY_UNSUPPORTED,
/** The file is an absolute symbolic link or junction
- * point and it is being excluded from capture because
- * it points outside of the capture directory and
- * reparse-point fixups are enabled. (Reparse point
- * fixups can be disabled by using the flag
- * ::WIMLIB_ADD_FLAG_NORPFIX.) */
- WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK,
+ * that points into the capture directory, and
+ * reparse-point fixups are enabled, so its target is
+ * being adjusted. (Reparse point fixups can be
+ * disabled with the flag ::WIMLIB_ADD_FLAG_NORPFIX.)
+ */
+ WIMLIB_SCAN_DENTRY_FIXED_SYMLINK,
+
+ /** Reparse-point fixups are enabled, but the file is an
+ * absolute symbolic link or junction that does
+ * <b>not</b> point into the capture directory, so its
+ * target is <b>not</b> being adjusted. */
+ WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK,
} status;
union {
const wimlib_tchar *wim_target_path;
/** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status
- * of @p WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is
- * the target of the absolute symbolic link or junction
- * point. */
+ * of @p WIMLIB_SCAN_DENTRY_FIXED_SYMLINK or @p
+ * WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK, this is the
+ * target of the absolute symbolic link or junction. */
const wimlib_tchar *symlink_target;
};
/** Name of the split WIM part that is about to be started
* (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART) or has just been
* finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART).
- * As of wimlib v1.6.3, the library user may change this when
+ * As of wimlib v1.7.0, the library user may change this when
* receiving ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART in order to
* cause the next split WIM part to be written to a different
* location. */
/** Path to which the file is being extracted */
const wimlib_tchar *extraction_path;
} wimboot_exclude;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN. */
+ struct wimlib_progress_info_unmount {
+ /** Path to directory being unmounted */
+ const wimlib_tchar *mountpoint;
+
+ /** Path to WIM file being unmounted */
+ const wimlib_tchar *mounted_wim;
+
+ /** 1-based index of image being unmounted. */
+ uint32_t mounted_image;
+
+ /** Flags that were passed to wimlib_mount_image() when the
+ * mountpoint was set up. */
+ uint32_t mount_flags;
+
+ /** Flags passed to wimlib_unmount_image(). */
+ uint32_t unmount_flags;
+ } unmount;
};
/**
uint32_t unix_uid;
uint32_t unix_gid;
uint32_t unix_mode;
- uint32_t unix_reserved;
+ uint32_t unix_rdev;
uint64_t reserved[14];
* wimlib_update_image(). */
#define WIMLIB_ADD_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 implementation will not understand this special
+/** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID
+ * (major and minor number) of each file. See the documentation for the
+ * <b>--unix-data</b> option to <b>wimlib-imagex capture</b> for more
* information. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Reparse-point fixups: Modify absolute symbolic links (or junction points,
* in the case of Windows) that point inside the directory being captured to
* instead be absolute relative to the directory being captured, rather than the
- * current root; also exclude absolute symbolic links that point outside the
- * directory tree being captured.
+ * current root.
*
* Without this flag, the default is to do this if WIM_HDR_FLAG_RP_FIX is set in
* the WIM header or if this is the first image being added.
/** Enable FUSE debugging by passing the @c -d flag to @c fuse_main().*/
#define WIMLIB_MOUNT_FLAG_DEBUG 0x00000002
-/** Do not allow accessing alternate data streams in the mounted WIM image. */
+/** Do not allow accessing named data streams in the mounted WIM image. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE 0x00000004
-/** Access alternate data streams in the mounted WIM image through extended file
- * attributes. This is the default mode. */
+/** Access named data streams in the mounted WIM image through extended file
+ * attributes named "user.X", where X is the name of a data stream. This is the
+ * default mode. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR 0x00000008
-/** Access alternate data streams in the mounted WIM image by specifying the
- * file name, a colon, then the alternate file stream name. */
+/** Access named data streams in the mounted WIM image by specifying the file
+ * name, a colon, then the name of the data stream. */
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010
-/** Use UNIX file owners, groups, and modes if available in the WIM (see
- * ::WIMLIB_ADD_FLAG_UNIX_DATA). */
+/** Use UNIX metadata if available in the WIM image. See
+ * ::WIMLIB_ADD_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) */
+/** Allow other users to see the mounted filesystem. This passes the @c
+ * allow_other option to the FUSE mount. */
#define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040
/** @} */
/** @ingroup G_mounting_wim_images
* @{ */
-/** See ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */
+/** Provide ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image.
+ * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */
#define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001
-/** Unless this flag is given, changes to a read-write mounted WIM are
- * discarded. Ignored for read-only mounts. */
+/** Commit changes to the read-write mounted WIM image.
+ * If this flag is not specified, changes will be discarded. */
#define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002
-/** See ::WIMLIB_WRITE_FLAG_REBUILD. */
+/** Provide ::WIMLIB_WRITE_FLAG_REBUILD when committing the WIM image.
+ * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */
#define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004
-/** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */
+/** Provide ::WIMLIB_WRITE_FLAG_RECOMPRESS when committing the WIM image.
+ * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */
#define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008
-/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */
-#define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010
+/**
+ * In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM
+ * image, forces all file descriptors to the open WIM image to be closed before
+ * committing it.
+ *
+ * Without ::WIMLIB_UNMOUNT_FLAG_COMMIT or with a read-only mounted WIM image,
+ * this flag has no effect.
+ */
+#define WIMLIB_UNMOUNT_FLAG_FORCE 0x00000010
/** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted
- * image, causes the modified image to be committed as a new, unnamed image
- * appended to the archive. The original image will be unmodified. */
+ * WIM image, causes the modified image to be committed to the WIM file as a
+ * new, unnamed image appended to the archive. The original image in the WIM
+ * file will be unmodified. */
#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020
/** @} */
* 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
+ * compression with 64 MiB (67108864 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
* codes can be returned by a given function, and what they mean.
*/
enum wimlib_error_code {
- WIMLIB_ERR_SUCCESS = 0,
- WIMLIB_ERR_ALREADY_LOCKED,
- WIMLIB_ERR_DECOMPRESSION,
- WIMLIB_ERR_DELETE_STAGING_DIR,
- WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED,
- WIMLIB_ERR_FORK,
- WIMLIB_ERR_FUSE,
- WIMLIB_ERR_FUSERMOUNT,
- WIMLIB_ERR_GLOB_HAD_NO_MATCHES,
- WIMLIB_ERR_ICONV_NOT_AVAILABLE,
- WIMLIB_ERR_IMAGE_COUNT,
- WIMLIB_ERR_IMAGE_NAME_COLLISION,
- WIMLIB_ERR_INSUFFICIENT_PRIVILEGES,
- WIMLIB_ERR_INTEGRITY,
- WIMLIB_ERR_INVALID_CAPTURE_CONFIG,
- WIMLIB_ERR_INVALID_CHUNK_SIZE,
- WIMLIB_ERR_INVALID_COMPRESSION_TYPE,
- WIMLIB_ERR_INVALID_HEADER,
- WIMLIB_ERR_INVALID_IMAGE,
- WIMLIB_ERR_INVALID_INTEGRITY_TABLE,
- WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY,
- WIMLIB_ERR_INVALID_METADATA_RESOURCE,
- WIMLIB_ERR_INVALID_MULTIBYTE_STRING,
- WIMLIB_ERR_INVALID_OVERLAY,
- WIMLIB_ERR_INVALID_PARAM,
- WIMLIB_ERR_INVALID_PART_NUMBER,
- WIMLIB_ERR_INVALID_PIPABLE_WIM,
- WIMLIB_ERR_INVALID_REPARSE_DATA,
- WIMLIB_ERR_INVALID_RESOURCE_HASH,
- WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE,
- WIMLIB_ERR_INVALID_UTF16_STRING,
- WIMLIB_ERR_INVALID_UTF8_STRING,
- WIMLIB_ERR_IS_DIRECTORY,
- WIMLIB_ERR_IS_SPLIT_WIM,
- WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE,
- WIMLIB_ERR_LINK,
- WIMLIB_ERR_METADATA_NOT_FOUND,
- WIMLIB_ERR_MKDIR,
- WIMLIB_ERR_MQUEUE,
- WIMLIB_ERR_NOMEM,
- WIMLIB_ERR_NOTDIR,
- WIMLIB_ERR_NOTEMPTY,
- WIMLIB_ERR_NOT_A_REGULAR_FILE,
- WIMLIB_ERR_NOT_A_WIM_FILE,
- WIMLIB_ERR_NOT_PIPABLE,
- WIMLIB_ERR_NO_FILENAME,
- WIMLIB_ERR_NTFS_3G,
- WIMLIB_ERR_OPEN,
- WIMLIB_ERR_OPENDIR,
- WIMLIB_ERR_PATH_DOES_NOT_EXIST,
- WIMLIB_ERR_READ,
- WIMLIB_ERR_READLINK,
- WIMLIB_ERR_RENAME,
- WIMLIB_ERR_REOPEN,
- WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED,
- WIMLIB_ERR_RESOURCE_NOT_FOUND,
- WIMLIB_ERR_RESOURCE_ORDER,
- WIMLIB_ERR_SET_ATTRIBUTES,
- WIMLIB_ERR_SET_REPARSE_DATA,
- WIMLIB_ERR_SET_SECURITY,
- WIMLIB_ERR_SET_SHORT_NAME,
- WIMLIB_ERR_SET_TIMESTAMPS,
- WIMLIB_ERR_SPLIT_INVALID,
- WIMLIB_ERR_STAT,
- WIMLIB_ERR_TIMEOUT,
- WIMLIB_ERR_UNEXPECTED_END_OF_FILE,
- WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE,
- WIMLIB_ERR_UNKNOWN_VERSION,
- WIMLIB_ERR_UNSUPPORTED,
- WIMLIB_ERR_UNSUPPORTED_FILE,
- WIMLIB_ERR_VOLUME_LACKS_FEATURES,
- WIMLIB_ERR_WIM_IS_READONLY,
- WIMLIB_ERR_WRITE,
- WIMLIB_ERR_XML,
- WIMLIB_ERR_WIM_IS_ENCRYPTED,
- WIMLIB_ERR_WIMBOOT,
- WIMLIB_ERR_ABORTED_BY_PROGRESS,
- WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS,
+ WIMLIB_ERR_SUCCESS = 0,
+ WIMLIB_ERR_ALREADY_LOCKED = 1,
+ WIMLIB_ERR_DECOMPRESSION = 2,
+ WIMLIB_ERR_FUSE = 6,
+ WIMLIB_ERR_GLOB_HAD_NO_MATCHES = 8,
+ WIMLIB_ERR_ICONV_NOT_AVAILABLE = 9,
+ WIMLIB_ERR_IMAGE_COUNT = 10,
+ WIMLIB_ERR_IMAGE_NAME_COLLISION = 11,
+ WIMLIB_ERR_INSUFFICIENT_PRIVILEGES = 12,
+ WIMLIB_ERR_INTEGRITY = 13,
+ WIMLIB_ERR_INVALID_CAPTURE_CONFIG = 14,
+ WIMLIB_ERR_INVALID_CHUNK_SIZE = 15,
+ WIMLIB_ERR_INVALID_COMPRESSION_TYPE = 16,
+ WIMLIB_ERR_INVALID_HEADER = 17,
+ WIMLIB_ERR_INVALID_IMAGE = 18,
+ WIMLIB_ERR_INVALID_INTEGRITY_TABLE = 19,
+ WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY = 20,
+ WIMLIB_ERR_INVALID_METADATA_RESOURCE = 21,
+ WIMLIB_ERR_INVALID_MULTIBYTE_STRING = 22,
+ WIMLIB_ERR_INVALID_OVERLAY = 23,
+ WIMLIB_ERR_INVALID_PARAM = 24,
+ WIMLIB_ERR_INVALID_PART_NUMBER = 25,
+ WIMLIB_ERR_INVALID_PIPABLE_WIM = 26,
+ WIMLIB_ERR_INVALID_REPARSE_DATA = 27,
+ WIMLIB_ERR_INVALID_RESOURCE_HASH = 28,
+ WIMLIB_ERR_INVALID_UTF16_STRING = 30,
+ WIMLIB_ERR_INVALID_UTF8_STRING = 31,
+ WIMLIB_ERR_IS_DIRECTORY = 32,
+ WIMLIB_ERR_IS_SPLIT_WIM = 33,
+ WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE = 34,
+ WIMLIB_ERR_LINK = 35,
+ WIMLIB_ERR_METADATA_NOT_FOUND = 36,
+ WIMLIB_ERR_MKDIR = 37,
+ WIMLIB_ERR_MQUEUE = 38,
+ WIMLIB_ERR_NOMEM = 39,
+ WIMLIB_ERR_NOTDIR = 40,
+ WIMLIB_ERR_NOTEMPTY = 41,
+ WIMLIB_ERR_NOT_A_REGULAR_FILE = 42,
+ WIMLIB_ERR_NOT_A_WIM_FILE = 43,
+ WIMLIB_ERR_NOT_PIPABLE = 44,
+ WIMLIB_ERR_NO_FILENAME = 45,
+ WIMLIB_ERR_NTFS_3G = 46,
+ WIMLIB_ERR_OPEN = 47,
+ WIMLIB_ERR_OPENDIR = 48,
+ WIMLIB_ERR_PATH_DOES_NOT_EXIST = 49,
+ WIMLIB_ERR_READ = 50,
+ WIMLIB_ERR_READLINK = 51,
+ WIMLIB_ERR_RENAME = 52,
+ WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED = 54,
+ WIMLIB_ERR_RESOURCE_NOT_FOUND = 55,
+ WIMLIB_ERR_RESOURCE_ORDER = 56,
+ WIMLIB_ERR_SET_ATTRIBUTES = 57,
+ WIMLIB_ERR_SET_REPARSE_DATA = 58,
+ WIMLIB_ERR_SET_SECURITY = 59,
+ WIMLIB_ERR_SET_SHORT_NAME = 60,
+ WIMLIB_ERR_SET_TIMESTAMPS = 61,
+ WIMLIB_ERR_SPLIT_INVALID = 62,
+ WIMLIB_ERR_STAT = 63,
+ WIMLIB_ERR_UNEXPECTED_END_OF_FILE = 65,
+ WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE = 66,
+ WIMLIB_ERR_UNKNOWN_VERSION = 67,
+ WIMLIB_ERR_UNSUPPORTED = 68,
+ WIMLIB_ERR_UNSUPPORTED_FILE = 69,
+ WIMLIB_ERR_WIM_IS_READONLY = 71,
+ WIMLIB_ERR_WRITE = 72,
+ WIMLIB_ERR_XML = 73,
+ WIMLIB_ERR_WIM_IS_ENCRYPTED = 74,
+ WIMLIB_ERR_WIMBOOT = 75,
+ WIMLIB_ERR_ABORTED_BY_PROGRESS = 76,
+ WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS = 77,
+ WIMLIB_ERR_MKNOD = 78,
+ WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79,
+ WIMLIB_ERR_NOT_A_MOUNTPOINT = 80,
+ WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81,
};
/**
* @ingroup G_mounting_wim_images
*
- * Mounts an image in a WIM file on a directory read-only or read-write.
- *
- * As this is implemented using FUSE (Filesystme in UserSpacE), this is not
- * supported if wimlib was configured with @c --without-fuse. This includes
- * Windows builds of wimlib; ::WIMLIB_ERR_UNSUPPORTED will be returned in such
- * cases.
- *
- * Calling this function daemonizes the process, unless
- * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early occur occurs. If the
- * mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), modifications
- * to the WIM are staged in a temporary directory.
- *
- * It is safe to mount multiple images from the same underlying WIM file
- * read-only at the 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 already has modifications pending (e.g. an image added with
- * wimlib_add_image()).
+ * Mounts an image from a WIM file on a directory read-only or read-write.
*
* @param wim
* Pointer to the ::WIMStruct containing the image to be mounted.
* @param image
- * The number of the image to mount, indexed starting from it. It must be
- * an existing, single image.
+ * The 1-based index of the image to mount.
* @param dir
- * The path to an existing empty directory to mount the image on.
+ * The path to an existing empty directory on which to mount the WIM image.
* @param mount_flags
- * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG.
+ * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. Use
+ * ::WIMLIB_MOUNT_FLAG_READWRITE to request a read-write mount instead of a
+ * read-only mount.
* @param staging_dir
- * 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 @p mount_flags. If left @c NULL, the staging directory is created in
- * the same directory as the WIM file that @p wim was originally read from.
+ * If non-NULL, the name of a directory in which a temporary directory for
+ * storing modified or added files will be created. Ignored if
+ * ::WIMLIB_MOUNT_FLAG_READWRITE is not specified in @p mount_flags. If
+ * left @c NULL, the staging directory is created in the same directory as
+ * the WIM file that @p wim was originally read from. The staging
+ * directory is deleted when the image is unmounted.
*
- * @return 0 on success; nonzero on error.
+ * @return 0 on success; nonzero on error. The possible error codes include:
*
* @retval ::WIMLIB_ERR_ALREADY_LOCKED
- * 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.
+ * An image from the WIM file is already mounted read-write, or another
+ * process is currently appending data to the WIM file.
* @retval ::WIMLIB_ERR_FUSE
- * A non-zero status was returned by @c fuse_main().
+ * A non-zero status code was returned by @c fuse_main().
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image does not specify an existing, single image in @p wim.
* @retval ::WIMLIB_ERR_INVALID_PARAM
- * @p image is shared among multiple ::WIMStruct's as a result of a call to
- * wimlib_export_image(), or @p image has been added with
- * wimlib_add_image().
+ * @p wim was @c NULL; or @p dir was NULL or the empty string; or an
+ * unrecognized flag was specified in @p mount_flags; or the WIM image has
+ * already been modified in memory (e.g. by wimlib_update_image()).
* @retval ::WIMLIB_ERR_MKDIR
* ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the
* staging directory could not be created.
- * @retval ::WIMLIB_ERR_NOTDIR
- * Could not determine the current working directory.
- * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND
- * One of the dentries in the image referenced a stream not present in the
- * WIM's lookup table (or in any of the lookup tables of the split WIM
- * parts).
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but @p
- * wim is considered read-only because of any of the reasons mentioned in
- * the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
+ * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the
+ * WIM file is considered read-only because of any of the reasons mentioned
+ * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
* @retval ::WIMLIB_ERR_UNSUPPORTED
* Mounting is not supported, either because the platform is Windows, or
- * because the platform is UNIX-like and wimlib was compiled with @c
- * --without-fuse.
+ * because the platform is UNIX-like and wimlib was compiled using
+ * <code>--without-fuse</code>.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
* ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or
* ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for
* different reasons) to read the metadata resource for the image to mount.
+ *
+ * The ability to mount WIM image is implemented using FUSE (Filesystem in
+ * UserSpacE). Depending on how FUSE is set up on your system, this function
+ * may work as normal users in addition to the root user.
+ *
+ * Mounting WIM images is not supported if wimlib was configured
+ * <code>--without-fuse</code>. This includes Windows builds of wimlib;
+ * ::WIMLIB_ERR_UNSUPPORTED will be returned in such cases.
+ *
+ * Calling this function daemonizes the process, unless
+ * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early error occurs.
+ *
+ * It is safe to mount multiple images from the same underlying WIM file
+ * read-only at the 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.
+ *
+ * To unmount the image, call wimlib_unmount_image(). This may be done in a
+ * different process.
*/
extern int
wimlib_mount_image(WIMStruct *wim,
*
* Unmounts a WIM image that was mounted using wimlib_mount_image().
*
- * The image to unmount is specified by the path to the mountpoint, not the
- * original ::WIMStruct passed to wimlib_mount_image(), which should not be
- * touched and also may have been allocated in a different process.
- *
- * To unmount the image, the process calling this function communicates with the
- * process that is managing the mounted WIM image. This function blocks until it
- * 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.
+ * When unmounting a read-write mounted image, the default behavior is to
+ * discard changes to the image. Use ::WIMLIB_UNMOUNT_FLAG_COMMIT to cause the
+ * WIM image to be committed.
*
* @param dir
- * The directory that the WIM image was mounted on.
+ * The directory the WIM image was mounted on.
* @param unmount_flags
- * 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.
+ * Bitwise OR of flags prefixed with @p WIMLIB_UNMOUNT_FLAG.
*
- * @return 0 on success; nonzero on error.
+ * @return 0 on success; nonzero on error. The possible error codes include:
*
- * @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
- * The @b fusermount program could not be executed or exited with a failure
- * status.
+ * @retval ::WIMLIB_ERR_NOT_A_MOUNTPOINT
+ * There is no WIM image mounted on the specified directory.
+ * @retval ::WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY
+ * The read-write mounted WIM image cannot be committed because there are
+ * file descriptors open to it, and ::WIMLIB_UNMOUNT_FLAG_FORCE was not
+ * specified.
* @retval ::WIMLIB_ERR_MQUEUE
- * Could not open a POSIX message queue to communicate with the filesystem
- * daemon servicing the mounted filesystem, could not send a message
- * through the queue, or could not receive a message through the queue.
- * @retval ::WIMLIB_ERR_NOMEM
- * Failed to allocate needed memory.
- * @retval ::WIMLIB_ERR_OPEN
- * The filesystem daemon could not open a temporary file for writing the
- * new WIM.
- * @retval ::WIMLIB_ERR_READ
- * A read error occurred when the filesystem daemon tried to a file from
- * the staging directory
- * @retval ::WIMLIB_ERR_RENAME
- * The filesystem daemon failed to rename the newly written WIM file to the
- * original WIM file.
+ * Could not create a POSIX message queue.
+ * @retval ::WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT
+ * The WIM image was mounted by a different user.
* @retval ::WIMLIB_ERR_UNSUPPORTED
* Mounting is not supported, either because the platform is Windows, or
- * because the platform is UNIX-like and wimlib was compiled with @c
+ * because the platform is UNIX-like and wimlib was compiled using @c
* --without-fuse.
- * @retval ::WIMLIB_ERR_WRITE
- * A write error occurred when the filesystem daemon was writing to the new
- * WIM file, or the filesystem daemon was unable to flush changes that had
- * been made to files in the staging directory.
+ *
+ * Note: you can also unmount the image by using the @c umount() system call, or
+ * by using the @c umount or @c fusermount programs. However, you need to call
+ * this function if you want changes to be committed.
*/
extern int
-wimlib_unmount_image(const wimlib_tchar *dir,
- int unmount_flags);
+wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags);
/**
* @ingroup G_mounting_wim_images
struct wimlib_compressor_params_header hdr;
/** Relatively fast LZX compression algorithm with a decent compression
- * ratio; the suggested default. */
+ * ratio. */
#define WIMLIB_LZX_ALGORITHM_FAST 0
/** Slower LZX compression algorithm that provides a better compression
- * ratio. */
+ * ratio. This is the default. */
#define WIMLIB_LZX_ALGORITHM_SLOW 1
/** Algorithm to use to perform the compression: either
uint32_t fast_reserved1[10];
} fast;
- /** Parameters for the slow algorithm. */
+ /** Parameters for the "slow" algorithm. */
struct wimlib_lzx_slow_params {
/** If set to 1, the compressor can output length 2
- * matches. If set 0, the compressor only outputs
+ * matches. If set 0, the compressor can only output
* matches of length 3 or greater. Suggested value: 1
*/
uint32_t use_len2_matches : 1;
* position. Suggested value: 50. */
uint32_t max_search_depth;
- /** Maximum number of potentially good matches to
- * consider for each position. Suggested value: 3. */
- uint32_t max_matches_per_pos;
+ /* Note: max_matches_per_pos has been removed and no
+ * longer has any effect. */
- uint32_t slow_reserved2[2];
+ uint32_t slow_reserved2[3];
/** Assumed cost of a main symbol with zero frequency.
* Must be at least 1 and no more than 16. Suggested
* value: 50. */
uint32_t max_search_depth;
- /** Maximum number of potentially good matches to consider at each
- * position. Suggested value: 3. */
- uint32_t max_matches_per_pos;
+ /* Note: max_matches_per_pos has been removed and no longer has any
+ * effect. */
+
+ uint32_t reserved1;
/** Length of the array for the near-optimal LZ parsing algorithm. This
* must be at least 1. Suggested value: 1024. */
git://wimlib.net / wimlib / blobdiff