* 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
* This message is received only once per wimlib_extract_paths() and
* wimlib_extract_pathlist(), since wimlib combines all paths into a
* single extraction operation for optimization purposes. */
- WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
-
- /** The directory structure and other preliminary metadata is about to
- * be extracted. @p info will point to ::wimlib_progress_info.extract.
- * This message is received once after either
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN or
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN. */
- WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN,
-
- /** Confirms that the directory structure and other preliminary metadata
- * has been successfully extracted. @p info will point to
- * ::wimlib_progress_info.extract. This message is paired with a
- * preceding ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN message.
- */
- WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END,
+ WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN = 1,
/** File data is currently being extracted. @p info will point to
* ::wimlib_progress_info.extract. This is the main message to track
* the progress of an extraction operation. */
- WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
+ WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS = 4,
/** Starting to read a new part of a split pipable WIM over the pipe.
* @p info will point to ::wimlib_progress_info.extract. */
- WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN,
-
- /** All data for WIM files and directories have been extracted, and
- * final metadata such as timestamps is about to be extracted. @p info
- * will point to ::wimlib_progress_info.extract. This message is
- * received once before ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END or
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END. */
- WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS,
+ WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN = 5,
/** Confirms that the image has been successfully extracted. @p info
* will point to ::wimlib_progress_info.extract. This is paired with
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN. */
- WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END,
+ WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END = 7,
/** Confirms that the files or directory trees have been successfully
* extracted. @p info will point to ::wimlib_progress_info.extract.
* This is paired with ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN. */
- WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END,
+ WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END = 8,
/** The directory or NTFS volume is about to be scanned for metadata.
* @p info will point to ::wimlib_progress_info.scan. This message is
* received once per call to wimlib_add_image(), or once per capture
* source passed to wimlib_add_image_multisource(), or once per add
* command passed to wimlib_update_image(). */
- WIMLIB_PROGRESS_MSG_SCAN_BEGIN,
+ WIMLIB_PROGRESS_MSG_SCAN_BEGIN = 9,
/** A directory or file has been scanned. @p info will point to
* ::wimlib_progress_info.scan, and its @p cur_path member will be
* valid. This message is only sent if ::WIMLIB_ADD_FLAG_VERBOSE has
* been specified. */
- WIMLIB_PROGRESS_MSG_SCAN_DENTRY,
+ WIMLIB_PROGRESS_MSG_SCAN_DENTRY = 10,
/** Confirms that the directory or NTFS volume has been successfully
* scanned. @p info will point to ::wimlib_progress_info.scan. This is
* paired with a previous ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN message,
* possibly with many intervening ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY
* messages. */
- WIMLIB_PROGRESS_MSG_SCAN_END,
+ WIMLIB_PROGRESS_MSG_SCAN_END = 11,
/** File resources ("streams") are currently being written to the WIM.
* @p info will point to ::wimlib_progress_info.write_streams. This
* message may be received many times while the WIM file is being
* written or appended to with wimlib_write(), wimlib_overwrite(), or
* wimlib_write_to_fd(). */
- WIMLIB_PROGRESS_MSG_WRITE_STREAMS,
+ WIMLIB_PROGRESS_MSG_WRITE_STREAMS = 12,
/** Per-image metadata is about to be written to the WIM file. @p info
* will not be valid. */
- WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN,
+ WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN = 13,
/** Confirms that per-image metadata has been successfully been written
* to the WIM file. @p info will not be valid. This message is paired
* with a preceding ::WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN message.
*/
- WIMLIB_PROGRESS_MSG_WRITE_METADATA_END,
+ WIMLIB_PROGRESS_MSG_WRITE_METADATA_END = 14,
/** wimlib_overwrite() has successfully renamed the temporary file to
* the original WIM file, thereby committing the update. @p info will
* point to ::wimlib_progress_info.rename. Note: this message is not
* received if wimlib_overwrite() chose to append to the WIM file
* in-place. */
- WIMLIB_PROGRESS_MSG_RENAME,
+ WIMLIB_PROGRESS_MSG_RENAME = 15,
/** The contents of the WIM file are being checked against the integrity
* table. @p info will point to ::wimlib_progress_info.integrity. This
* message is only received (and may be received many times) when
* wimlib_open_wim() is called with the
* ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY flag. */
- WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY,
+ WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY = 16,
/** An integrity table is being calculated for the WIM being written.
* @p info will point to ::wimlib_progress_info.integrity. This message
* is only received (and may be received many times) when a WIM file is
* being written with the flag ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */
- WIMLIB_PROGRESS_MSG_CALC_INTEGRITY,
-
- /** Reserved. */
- WIMLIB_PROGRESS_MSG_RESERVED,
+ WIMLIB_PROGRESS_MSG_CALC_INTEGRITY = 17,
/** A wimlib_split() operation is in progress, and a new split part is
* about to be started. @p info will point to
* ::wimlib_progress_info.split. */
- WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART,
+ WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART = 19,
/** A wimlib_split() operation is in progress, and a split part has been
* finished. @p info will point to ::wimlib_progress_info.split. */
- WIMLIB_PROGRESS_MSG_SPLIT_END_PART,
+ WIMLIB_PROGRESS_MSG_SPLIT_END_PART = 20,
/** A WIM update command is just about to be executed. @p info will
* point to ::wimlib_progress_info.update. This message is received
* once per update command when wimlib_update_image() is called with the
* flag ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */
- WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND,
+ WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND = 21,
/** A WIM update command has just been executed. @p info will point to
* ::wimlib_progress_info.update. This message is received once per
* update command when wimlib_update_image() is called with the flag
* ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */
- WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND,
+ WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND = 22,
/** A file in the WIM image is being replaced as a result of a
* ::wimlib_add_command without ::WIMLIB_ADD_FLAG_NO_REPLACE specified.
* @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,
+ WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM = 23,
/** A WIM image is being applied with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and
* a file is being extracted normally (not as a WIMBoot "pointer file")
* configuration file \Windows\System32\WimBootCompress.ini in the WIM
* image. @info will point to ::wimlib_progress_info.wimboot_exclude.
*/
- WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE,
+ WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE = 24,
};
/** A pointer to this union is passed to the user-supplied
* ::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;
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN,
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END,
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END, and
- * ::WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS.
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, and
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END.
*
* Note: most of the time of an extraction operation will be spent
* extracting streams, and the application will receive
/** Time this file was last accessed. */
struct timespec last_access_time;
- uint64_t reserved[16];
+
+ /* UNIX data (wimlib extension), only valid if unix_mode != 0 */
+ uint32_t unix_uid;
+ uint32_t unix_gid;
+ uint32_t unix_mode;
+ uint32_t unix_reserved;
+
+ uint64_t reserved[14];
/** Array of streams that make up this file. The first entry will
* always exist and will correspond to the unnamed data stream (default
/** @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
* wimlib_export_image(), with the exception of the call to wimlib_free(). */
#define WIMLIB_EXPORT_FLAG_GIFT 0x00000008
+/**
+ * Mark each exported image as WIMBoot-compatible.
+ *
+ * Note: by itself, this does change the destination WIM's compression type, nor
+ * does it add the file \Windows\System32\WimBootCompress.ini in the WIM image.
+ * Before writing the destination WIM, it's recommended to do something like:
+ *
+ * \code
+ * wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS);
+ * wimlib_set_output_chunk_size(wim, 4096);
+ * wimlib_add_tree(wim, image, L"myconfig.ini",
+ * L"\\Windows\\System32\\WimBootCompress.ini", 0);
+ * \endcode
+ */
+#define WIMLIB_EXPORT_FLAG_WIMBOOT 0x00000010
+
/** @} */
/** @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()
- * is called with ::WIMLIB_ALL_IMAGES as the @p image. */
+ * is called with ::WIMLIB_ALL_IMAGES as the @p image, nor can it be used with
+ * wimlib_extract_paths() when passed multiple paths. */
#define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001
-/** When identical files are extracted from the WIM, always hard link them
- * together. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_SYMLINK.
- */
-#define WIMLIB_EXTRACT_FLAG_HARDLINK 0x00000002
-
-/** When identical files are extracted from the WIM, always symlink them
- * together. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_HARDLINK.
- */
-#define WIMLIB_EXTRACT_FLAG_SYMLINK 0x00000004
-
-/** This flag no longer does anything but is reserved for future use. */
-#define WIMLIB_EXTRACT_FLAG_VERBOSE 0x00000008
-
-/** Read the WIM file sequentially while extracting the image. As of wimlib
- * v1.6.0 this is the default behavior, and this flag no longer does anything.
- */
-#define WIMLIB_EXTRACT_FLAG_SEQUENTIAL 0x00000010
-
-/** Extract special UNIX data captured with ::WIMLIB_ADD_FLAG_UNIX_DATA. Only
- * valid on UNIX-like platforms, and when ::WIMLIB_EXTRACT_FLAG_NTFS was not
- * specified. */
+/** UNIX-like systems only: Extract special UNIX data captured with
+ * ::WIMLIB_ADD_FLAG_UNIX_DATA. This flag cannot be combined with
+ * ::WIMLIB_EXTRACT_FLAG_NTFS. */
#define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020
/** Do not extract security descriptors. This flag cannot be combined with
* with ::WIMLIB_EXTRACT_FLAG_RPFIX. */
#define WIMLIB_EXTRACT_FLAG_NORPFIX 0x00000200
-/** Extract the paths, each of which must name a regular file, to standard
- * output. Not valid for wimlib_extract_image() and
- * wimlib_extract_image_from_pipe(). */
+/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Extract the
+ * paths, each of which must name a regular file, to standard output. */
#define WIMLIB_EXTRACT_FLAG_TO_STDOUT 0x00000400
/** Instead of ignoring files and directories with names that cannot be
/** Do not ignore failure to set short names on extracted files. */
#define WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000
-/** Do not ignore failure to extract symbolic links (and junction points, on
- * Windows) due to permissions problems. By default, such failures are ignored
- * since the default configuration of Windows only allows the Administrator to
- * create symbolic links. */
+/** On Windows, do not ignore failure to extract symbolic links and junctions
+ * due to permissions problems. By default, such failures are ignored since the
+ * default configuration of Windows only allows the Administrator to create
+ * symbolic links. */
#define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000
/** TODO: this flag is intended to allow resuming an aborted extraction, but the
* behavior is currently less than satisfactory. Do not use (yet). */
#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000
-/** Perform the extraction ordered by the tree of files to extract rather than
- * how the underlying streams are arranged in the WIM file. For regular WIM
- * files this may decrease or increase performance, depending on various
- * factors. For WIM files containing packed streams this will decrease
- * performance. */
-#define WIMLIB_EXTRACT_FLAG_FILE_ORDER 0x00020000
-
/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the
* paths to extract as wildcard patterns ("globs") which may contain the
* wildcard characters @c ? and @c *. The @c ? character matches any
/** @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
/** @} */
* volume. Flags affected by this include ::WIMLIB_EXTRACT_FLAG_NTFS,
* ::WIMLIB_EXTRACT_FLAG_UNIX_DATA, ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS,
* ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES,
- * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS,
- * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS, ::WIMLIB_EXTRACT_FLAG_SYMLINK,
- * and ::WIMLIB_EXTRACT_FLAG_HARDLINK. For example, if
+ * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS, and
+ * ::WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS. For example, if
* ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES is specified in @p
* extract_flags, ::WIMLIB_ERR_UNSUPPORTED will be returned if the WIM
* image contains one or more files with short names, but extracting short
* @param target
* Same as the corresponding parameter to wimlib_extract_image().
* @param extract_flags
- * Same as the corresponding parameter to wimlib_extract_image(), except
- * that ::WIMLIB_EXTRACT_FLAG_FILE_ORDER cannot be specified and will
- * result in ::WIMLIB_ERR_INVALID_PARAM being returned.
+ * Same as the corresponding parameter to wimlib_extract_image().
* @param progress_func
* Same as the corresponding parameter to wimlib_extract_image(), except
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN messages will also be
* @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.
* @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);
* 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
git://wimlib.net / wimlib / blobdiff