X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=6aa36f5888ddb41ccdca9a3928b2efec61c91ecc;hp=9c043c1ba5d31e2d112c4ba8997ec481508bc832;hb=af272527f1ecb860907ede7ca33ce667701c571b;hpb=4c532e2a9f1a40e1c1a6ed44a50025cfbfab6e4f diff --git a/include/wimlib.h b/include/wimlib.h index 9c043c1b..6aa36f58 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -294,14 +294,16 @@ * * @brief Mount and unmount WIM images. * - * On UNIX-like systems supporting FUSE (such as Linux), wimlib supports - * mounting images from WIM files either read-only or read-write. To mount an - * image, call wimlib_mount_image(). To unmount an image, call - * wimlib_unmount_image(). Mounting can be done without root privileges because - * it is implemented using FUSE (Filesystem in Userspace). If wimlib is - * compiled with the --without-fuse flag, these functions will be - * available but will fail with ::WIMLIB_ERR_UNSUPPORTED. Note that mounting an - * image read-write is an alternative to calling wimlib_update_image(). + * On Linux, wimlib supports mounting images from WIM files either read-only or + * read-write. To mount an image, call wimlib_mount_image(). To unmount an + * image, call wimlib_unmount_image(). Mounting can be done without root + * privileges because it is implemented using FUSE (Filesystem in Userspace). + * + * If wimlib is compiled using the --without-fuse flag, these + * functions will be available but will fail with ::WIMLIB_ERR_UNSUPPORTED. + * + * Note: if mounting is unsupported, wimlib still provides another way to modify + * a WIM image (wimlib_update_image()). */ /** @@ -442,36 +444,70 @@ typedef char wimlib_tchar; /** * Specifies a compression format. Pass one of these values to - * wimlib_create_new_wim(), wimlib_create_compressor(), or - * wimlib_create_decompressor(). + * wimlib_create_new_wim(), wimlib_set_output_compression_type(), + * wimlib_create_compressor(), or wimlib_create_decompressor(). * * A WIM file has one default compression type and chunk size. Normally, each - * resource is compressed with this compression type. However, resources may be - * stored as uncompressed. In addition, a WIM with the new version number of - * 3584, or "ESD file", might contain solid blocks with different compression - * types. + * resource in the WIM file is compressed with this compression type. However, + * resources may be stored as uncompressed; for example, wimlib will do so if a + * resource does not compress to less than its original size. In addition, a + * WIM with the new version number of 3584, or "ESD file", might contain solid + * blocks with different compression types. */ enum wimlib_compression_type { - /** No compression. */ + /** + * No compression. + * + * This is a valid argument to wimlib_create_new_wim() and + * wimlib_set_output_compression_type(), but not to the functions in the + * compression API such as wimlib_create_compressor(). + */ WIMLIB_COMPRESSION_TYPE_NONE = 0, - /** The XPRESS compression format. This format combines Lempel-Ziv + /** + * The XPRESS compression format. This format combines Lempel-Ziv * factorization with Huffman encoding. Compression and decompression * are both fast. This format supports chunk sizes that are powers of 2 - * between 2^12 and 2^26, inclusively. */ + * between 2^12 and 2^16, inclusively. + * + * wimlib's XPRESS compressor will, with the default settings, usually + * produce a better compression ratio, and work more quickly, than the + * implementation in Microsoft's WIMGAPI (as of Windows 8.1). + * Non-default compression levels are also supported. For example, + * level 80 will enable two-pass optimal parsing, which is significantly + * slower but usually improves compression by several percent over the + * default level of 50. + * + * If using wimlib_create_compressor() to create an XPRESS compressor + * directly, the @p max_block_size parameter may be any positive value + * up to 2^16. + */ WIMLIB_COMPRESSION_TYPE_XPRESS = 1, - /** The LZX compression format. This format combines Lempel-Ziv + /** + * The LZX compression format. This format combines Lempel-Ziv * factorization with Huffman encoding, but with more features and * complexity than XPRESS. Compression is slow to somewhat fast, * depending on the settings. Decompression is fast but slower than * XPRESS. This format supports chunk sizes that are powers of 2 * between 2^15 and 2^21, inclusively. Note: chunk sizes * other than 2^15 are not compatible with the Microsoft - * implementation. */ + * implementation. + * + * wimlib's LZX compressor will, with the default settings, usually + * produce a better compression ratio, and work more quickly, than the + * implementation in Microsoft's WIMGAPI (as of Windows 8.1). + * Non-default compression levels are also supported. For example, + * level 20 will provide fast compression, almost as fast as XPRESS. + * + * If using wimlib_create_compressor() to create an LZX compressor + * directly, the @p max_block_size parameter may be any positive value + * up to 2^21. + */ WIMLIB_COMPRESSION_TYPE_LZX = 2, - /** The LZMS compression format. This format combines Lempel-Ziv + /** + * The LZMS compression format. This format combines Lempel-Ziv * factorization with adaptive Huffman encoding and range coding. * Compression and decompression are both fairly slow. This format * supports chunk sizes that are powers of 2 between 2^15 and @@ -479,7 +515,16 @@ enum wimlib_compression_type { * sizes. Note: LZMS compression is only compatible with wimlib v1.6.0 * and later, WIMGAPI Windows 8 and later, and DISM Windows 8.1 and * later. Also, chunk sizes larger than 2^26 are not compatible - * with the Microsoft implementation. */ + * with the Microsoft implementation. + * + * wimlib's LZMS compressor is currently faster but will usually not + * compress as much as the implementation in Microsoft's WIMGAPI + * (Windows 8.1). + * + * If using wimlib_create_compressor() to create an LZMS compressor + * directly, the @p max_block_size parameter may be any positive value + * up to 2^31 - 2. + */ WIMLIB_COMPRESSION_TYPE_LZMS = 3, }; @@ -504,6 +549,12 @@ enum wimlib_progress_msg { * single extraction operation for optimization purposes. */ WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN = 1, + /** This message may be sent periodically (not for every file) while + * files or directories are being created, prior to data stream + * extraction. @p info will point to ::wimlib_progress_info.extract. + */ + WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE = 3, + /** 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. */ @@ -513,6 +564,12 @@ enum wimlib_progress_msg { * @p info will point to ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN = 5, + /** This message may be sent periodically (not for every file) while + * file and directory metadata is being applied, following data stream + * extraction. @p info will point to ::wimlib_progress_info.extract. + */ + WIMLIB_PROGRESS_MSG_EXTRACT_METADATA = 6, + /** 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. */ @@ -626,6 +683,19 @@ enum wimlib_progress_msg { * ::wimlib_progress_info.done_with_file. This message is only received * if ::WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES was provided. */ WIMLIB_PROGRESS_MSG_DONE_WITH_FILE = 26, + + /** wimlib_verify_wim() is starting to verify the metadata for an image. + * @p info will point to ::wimlib_progress_info.verify_image. */ + WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE = 27, + + /** wimlib_verify_wim() has finished verifying the metadata for an + * image. @p info will point to ::wimlib_progress_info.verify_image. + */ + WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE = 28, + + /** wimlib_verify_wim() is verifying stream integrity. @p info will + * point to ::wimlib_progress_info.verify_streams. */ + WIMLIB_PROGRESS_MSG_VERIFY_STREAMS = 29, }; /** Valid return values from user-provided progress functions @@ -837,7 +907,9 @@ union wimlib_progress_info { * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN, * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE, * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, + * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA, * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END, and * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. * @@ -1053,6 +1125,23 @@ union wimlib_progress_info { */ const wimlib_tchar *path_to_file; } done_with_file; + + /** Valid on messages ::WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE and + * ::WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE. */ + struct wimlib_progress_info_verify_image { + const wimlib_tchar *wimfile; + uint32_t total_images; + uint32_t current_image; + } verify_image; + + /** Valid on messages ::WIMLIB_PROGRESS_MSG_VERIFY_STREAMS. */ + struct wimlib_progress_info_verify_streams { + const wimlib_tchar *wimfile; + uint64_t total_streams; + uint64_t total_bytes; + uint64_t completed_streams; + uint64_t completed_bytes; + } verify_streams; }; /** @@ -1125,8 +1214,7 @@ struct wimlib_capture_source { /** @} */ -/** @addtogroup G_wim_information - * { */ +/** @addtogroup G_wim_information */ /** @{ */ @@ -1180,11 +1268,11 @@ struct wimlib_wim_info { /** 1 if the WIM is considered readonly for any reason. */ uint32_t is_readonly : 1; - /** 1 if reparse-point fixups are supposedly enabled for one or more - * images in the WIM. */ + /** 1 if reparse-point fixups are enabled for one or more images in the + * WIM. */ uint32_t has_rpfix : 1; - /** 1 if the WIM is marked as read-only. */ + /** 1 if the WIM is marked read-only. */ uint32_t is_marked_readonly : 1; /** 1 if the WIM is part of a spanned set. */ @@ -1207,8 +1295,8 @@ struct wimlib_resource_entry { uint64_t uncompressed_size; /** Compressed size of the stream in bytes. This will be the same as @p - * uncompressed_size if the stream is uncompressed. Or, if @p - * is_packed_streams is 1, this will be 0. */ + * uncompressed_size if the stream is uncompressed. Or, if @p packed is + * 1, this will be 0. */ uint64_t compressed_size; /** Offset, in bytes, of this stream from the start of the WIM file. Or @@ -1220,8 +1308,7 @@ struct wimlib_resource_entry { /** SHA1 message digest of the stream's uncompressed contents. */ uint8_t sha1_hash[20]; - /** Which part number of the split WIM this stream is in. This should - * be the same as the part number provided by wimlib_get_wim_info(). */ + /** Which part of WIM this stream is in. */ uint32_t part_number; /** Number of times this stream is referenced over all WIM images. */ @@ -1253,18 +1340,25 @@ struct wimlib_resource_entry { * resource in the WIM. */ uint64_t raw_resource_offset_in_wim; - /** If @p is_packed_streams is 1, then this will specify the compressed - * size of the packed resource in the WIM. */ + /** If @p packed is 1, then this will specify the compressed size of the + * packed resource in the WIM. */ uint64_t raw_resource_compressed_size; uint64_t reserved[2]; }; -/** Information about a stream of a particular file in the WIM. */ +/** + * Information about a stream of a particular file in the WIM. + * + * Normally, only WIM images captured from NTFS filesystems will have multiple + * streams per file. In practice, this is a rarely used feature of the + * filesystem. + */ struct wimlib_stream_entry { /** Name of the stream, or NULL if the stream is unnamed. */ const wimlib_tchar *stream_name; - /** Location, size, etc. of the stream within the WIM file. */ + /** Location, size, and other information about the stream's data as + * stored in the WIM file. */ struct wimlib_resource_entry resource; uint64_t reserved[4]; }; @@ -1274,15 +1368,16 @@ struct wimlib_stream_entry { * entry ("dentry") because hard links are allowed. The hard_link_group_id * field can be used to distinguish actual file inodes. */ struct wimlib_dir_entry { - /** Name of the file, or NULL if this file is unnamed (only possible for - * the root directory) */ + /** Name of the file, or NULL if this file is unnamed. Only the root + * directory of an image will be unnamed. */ const wimlib_tchar *filename; - /** 8.3 DOS name of this file, or NULL if this file has no such name. - * */ + /** 8.3 name (or "DOS name", or "short name") of this file; or NULL if + * this file has no such name. */ const wimlib_tchar *dos_name; - /** Full path to this file within the WIM image. */ + /** Full path to this file within the WIM image. Path separators will + * be ::WIMLIB_WIM_PATH_SEPARATOR. */ const wimlib_tchar *full_path; /** Depth of this directory entry, where 0 is the root, 1 is the root's @@ -1330,20 +1425,28 @@ struct wimlib_dir_entry { #define WIMLIB_REPARSE_TAG_FILTER_MANAGER 0x8000000B #define WIMLIB_REPARSE_TAG_WOF 0x80000017 #define WIMLIB_REPARSE_TAG_SYMLINK 0xA000000C - /** If the file is a reparse point (FILE_ATTRIBUTE_DIRECTORY set in the - * attributes), this will give the reparse tag. This tells you whether - * the reparse point is a symbolic link, junction point, or some other, - * more unusual kind of reparse point. */ + /** If the file is a reparse point (FILE_ATTRIBUTE_REPARSE_POINT set in + * the attributes), this will give the reparse tag. This tells you + * whether the reparse point is a symbolic link, junction point, or some + * other, more unusual kind of reparse point. */ uint32_t reparse_tag; - /* Number of (hard) links to this file. */ + /** Number of links to this file's inode (hard links). + * + * Currently, this will always be 1 for directories. However, it can be + * greater than 1 for nondirectory files. */ uint32_t num_links; - /** Number of named data streams that this file has. Normally 0. */ + /** Number of named data streams this file has. Normally 0. */ uint32_t num_named_streams; - /** Roughly, the inode number of this file. However, it may be 0 if - * @p num_links == 1. */ + /** A unique identifier for this file's inode. However, as a special + * case, if the inode only has a single link (@p num_links == 1), this + * value may be 0. + * + * Note: if a WIM image is captured from a filesystem, this value is not + * guaranteed to be the same as the original number of the inode on the + * filesystem. */ uint64_t hard_link_group_id; /** Time this file was created. */ @@ -1355,20 +1458,43 @@ struct wimlib_dir_entry { /** Time this file was last accessed. */ struct timespec last_access_time; - /* UNIX data (wimlib extension), only valid if unix_mode != 0 */ + /** The UNIX user ID of this file. This is a wimlib extension. + * + * This field is only valid if @p unix_mode != 0. */ uint32_t unix_uid; + + /** The UNIX group ID of this file. This is a wimlib extension. + * + * This field is only valid if @p unix_mode != 0. */ uint32_t unix_gid; + + /** The UNIX mode of this file. This is a wimlib extension. + * + * If this field is 0, then @p unix_uid, @p unix_gid, @p unix_mode, and + * @p unix_rdev are all unknown (fields are not present in the WIM + * image). */ uint32_t unix_mode; + + /** The UNIX device ID (major and minor number) of this file. This is a + * wimlib extension. + * + * This field is only valid if @p unix_mode != 0. */ uint32_t unix_rdev; 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 - * file contents), so it will have @p stream_name == @c NULL. There - * will then be @p num_named_streams additional entries that specify the - * named data streams, if any, each of which will have @p stream_name != - * @c NULL. */ + /** + * Array of streams that make up this file. + * + * The first entry will always exist and will correspond to the unnamed + * data stream (default file contents), so it will have stream_name + * == NULL. Alternatively, for reparse point files, the first entry + * will corresponding to the reparse data stream. + * + * Then, following the first entry, there be @p num_named_streams + * additional entries that specify the named data streams, if any, each + * of which will have stream_name != NULL. + */ struct wimlib_stream_entry streams[]; }; @@ -1406,12 +1532,18 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** @addtogroup G_modifying_wims * @{ */ -/** 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. */ +/** UNIX-like systems only: Directly capture an NTFS volume rather than a + * generic directory. This requires that wimlib was compiled with support for + * libntfs-3g. + * + * This flag cannot be combined with ::WIMLIB_ADD_FLAG_DEREFERENCE or + * ::WIMLIB_ADD_FLAG_UNIX_DATA. + * + * Do not use this flag on Windows, where wimlib already supports all + * Windows-native filesystems, including NTFS, through the Windows APIs. */ #define WIMLIB_ADD_FLAG_NTFS 0x00000001 -/** Follow symlinks; archive and dump the files they point to. Currently only +/** Follow symbolic links when scanning the directory tree. Currently only * supported on UNIX-like systems. */ #define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002 @@ -1420,65 +1552,72 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * scanned. */ #define WIMLIB_ADD_FLAG_VERBOSE 0x00000004 -/** Mark the image being added as the bootable image of the WIM. Not valid for - * wimlib_update_image(). */ +/** Mark the image being added as the bootable image of the WIM. This flag is + * valid only for wimlib_add_image() and wimlib_add_image_multisource(). + * + * Note that you can also change the bootable image of a WIM using + * wimlib_set_wim_info(). + * + * Note: ::WIMLIB_ADD_FLAG_BOOT does something different from, and independent + * from, ::WIMLIB_ADD_FLAG_WIMBOOT. */ #define WIMLIB_ADD_FLAG_BOOT 0x00000008 /** 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 + * (major and minor number) of each file. Also allows capturing special files + * such as device nodes and FIFOs. See the documentation for the * --unix-data option to wimlib-imagex capture for more * information. */ #define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010 /** Do not capture security descriptors. Only has an effect in NTFS capture - * mode, or in Windows native builds. */ + * mode, or in Windows native builds. */ #define WIMLIB_ADD_FLAG_NO_ACLS 0x00000020 /** Fail immediately if the full security descriptor of any file or directory * cannot be accessed. Only has an effect in Windows native builds. The * default behavior without this flag is to first try omitting the SACL from the * security descriptor, then to try omitting the security descriptor entirely. - * */ + */ #define WIMLIB_ADD_FLAG_STRICT_ACLS 0x00000040 /** Call the progress function with the message * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from * capture. This is a subset of the messages provided by - * ::WIMLIB_ADD_FLAG_VERBOSE. */ + * ::WIMLIB_ADD_FLAG_VERBOSE. */ #define WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE 0x00000080 -/** 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. +/** Reparse-point fixups: Modify absolute symbolic links (and junctions, in the + * case of Windows) that point inside the directory being captured to instead be + * absolute relative to the directory being captured. * - * 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. - * WIM_HDR_FLAG_RP_FIX is set if the first image in a WIM is captured with - * reparse point fixups enabled and currently cannot be unset. */ + * Without this flag, the default is to do reparse-point fixups if + * WIM_HDR_FLAG_RP_FIX is set in the WIM header or if this is the first image + * being added. WIM_HDR_FLAG_RP_FIX is set if the first image in a WIM is + * captured with reparse point fixups enabled and currently cannot be unset. */ #define WIMLIB_ADD_FLAG_RPFIX 0x00000100 -/** Don't do reparse point fixups. The default behavior is described in the - * documentation for ::WIMLIB_ADD_FLAG_RPFIX. */ +/** Don't do reparse point fixups. See ::WIMLIB_ADD_FLAG_RPFIX. */ #define WIMLIB_ADD_FLAG_NORPFIX 0x00000200 /** Do not automatically exclude unsupported files or directories from capture; * e.g. encrypted files in NTFS-3g capture mode, or device files and FIFOs on - * UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when - * such a file is encountered. */ + * UNIX-like systems when not also using ::WIMLIB_ADD_FLAG_UNIX_DATA. Instead, + * fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when such a file is encountered. */ #define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400 /** * Automatically select a capture configuration appropriate for capturing * filesystems containing Windows operating systems. For example, - * "pagefile.sys" and "System Volume Information" will be excluded. + * "/pagefile.sys" and "System Volume Information" will be excluded. * - * When this flag is specified, the corresponding @p config parameter or member - * must be @c NULL. + * When this flag is specified, the corresponding @p config parameter (for + * wimlib_add_image()) or member (for wimlib_update_image()) must be @c NULL. + * Otherwise, ::WIMLIB_ERR_INVALID_PARAM will be returned. * - * Note that the default behavior--- that is, when this flag is not specified - * and @p config is @c NULL--- is to use no capture configuration, meaning that - * no files are excluded from capture. + * Note that the default behavior--- that is, when neither + * ::WIMLIB_ADD_FLAG_WINCONFIG nor ::WIMLIB_ADD_FLAG_WIMBOOT is specified and @p + * config is @c NULL--- is to use no capture configuration, meaning that no + * files are excluded from capture. */ #define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800 @@ -1500,6 +1639,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * * since that makes access to the data faster (at the cost of a worse * compression ratio compared to the 32768-byte LZX chunks usually used). + * + * Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and + * independent from, ::WIMLIB_ADD_FLAG_BOOT. */ #define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000 @@ -1634,29 +1776,39 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Instead of ignoring files and directories with names that cannot be * represented on the current platform (note: Windows has more restrictions on * filenames than POSIX-compliant systems), try to replace characters or append - * junk to the names so that they can be extracted in some form. */ + * junk to the names so that they can be extracted in some form. + * + * Note: this flag is unlikely to have any effect when extracting a WIM image + * that was captured on Windows. + */ #define WIMLIB_EXTRACT_FLAG_REPLACE_INVALID_FILENAMES 0x00000800 /** On Windows, when there exist two or more files with the same case * insensitive name but different case sensitive names, try to extract them all * by appending junk to the end of them, rather than arbitrarily extracting only - * one. */ + * one. + * + * Note: this flag is unlikely to have any effect when extracting a WIM image + * that was captured on Windows. + */ #define WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS 0x00001000 -/** Do not ignore failure to set timestamps on extracted files. */ +/** Do not ignore failure to set timestamps on extracted files. This flag + * currently only has an effect when extracting to a directory on UNIX-like + * systems. */ #define WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS 0x00002000 -/** Do not ignore failure to set short names on extracted files. */ +/** Do not ignore failure to set short names on extracted files. This flag + * currently only has an effect on Windows. */ #define WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000 -/** 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. */ +/** Do not ignore failure to extract symbolic links and junctions due to + * permissions problems. This flag currently only has an effect on Windows. 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). */ +/** Reserved for future use. */ #define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000 /** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the @@ -1664,10 +1816,13 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * wildcard characters @c ? and @c *. The @c ? character matches any * non-path-separator character, whereas the @c * character matches zero or more * non-path-separator characters. Consequently, each glob may match zero or - * more actual paths in the WIM image. By default, if a glob does not match any - * files, a warning but not an error will be issued, even if the glob did not - * actually contain wildcard characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB - * to get an error instead. */ + * more actual paths in the WIM image. + * + * By default, if a glob does not match any files, a warning but not an error + * will be issued. This is the case even if the glob did not actually contain + * wildcard characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB to get an error + * instead. + * */ #define WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000 /** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error @@ -1675,18 +1830,24 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * one of the provided globs did not match a file. */ #define WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000 -/** Do not extract Windows file attributes such as readonly, hidden, etc. */ +/** Do not extract Windows file attributes such as readonly, hidden, etc. + * + * This flag has an effect on Windows as well as in the NTFS-3g extraction mode. + */ #define WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES 0x00100000 /** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Do not * preserve the directory structure of the archive when extracting --- that is, * place each extracted file or directory tree directly in the target directory. - */ + * + * The target directory will still be created if it does not already exist. */ #define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000 -/** Windows only: Extract files as "pointers" back to the WIM archive. See the - * documentation for the --wimboot option of wimlib-imagex apply - * for more information. */ +/** Windows only: Extract files as "pointers" back to the WIM archive. + * + * The effects of this option are fairly complex. See the documentation for the + * --wimboot option of wimlib-imagex apply for more information. + */ #define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000 /** @} */ @@ -1696,7 +1857,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Mount the WIM image read-write rather than the default of read-only. */ #define WIMLIB_MOUNT_FLAG_READWRITE 0x00000001 -/** Enable FUSE debugging by passing the @c -d flag to @c fuse_main().*/ +/** Enable FUSE debugging by passing the @c -d option to @c fuse_main(). */ #define WIMLIB_MOUNT_FLAG_DEBUG 0x00000002 /** Do not allow accessing named data streams in the mounted WIM image. */ @@ -1716,7 +1877,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020 /** Allow other users to see the mounted filesystem. This passes the @c - * allow_other option to the FUSE mount. */ + * allow_other option to fuse_main(). */ #define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040 /** @} */ @@ -1837,16 +1998,17 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * 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.7.0, it usually compresses slightly better than the competing - * Microsoft implementation and is almost as fast. - * - * ::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.) + * compression ratio for the same compression type and chunk size. Simply using + * the default compression settings may suffice for this, especially if the WIM + * file was created using another program/library that may not use as + * sophisticated compression algorithms. Or, + * wimlib_set_default_compression_level() can be called beforehand to set an + * even higher compression level than the default. + * + * If the WIM contains solid blocks, then ::WIMLIB_WRITE_FLAG_RECOMPRESS can 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 not cause recompression of streams * that would not otherwise be written. For example, a call to @@ -1860,18 +2022,26 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** * Immediately before closing the WIM file, sync its data to disk. * + * This flag forces the function to wait until the data is safely on disk before + * returning success. Otherwise, modern operating systems tend to cache data + * for some time (in some cases, 30+ seconds) before actually writing it to + * disk, even after reporting to the application that the writes have succeeded. + * * wimlib_overwrite() will set this flag automatically if it decides to - * overwrite the WIM file via a temporary file instead of in-place. + * overwrite the WIM file via a temporary file instead of in-place. This is + * necessary on POSIX systems; it will, for example, avoid problems with delayed + * allocation on ext4. */ #define WIMLIB_WRITE_FLAG_FSYNC 0x00000020 /** * For wimlib_overwrite(), rebuild the entire WIM file, even if it otherwise - * could be updated merely by appending to it. + * could be updated in-place by 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. + * not be included in the resulting WIM file. This can free up space that is + * currently not being used. * * 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. @@ -1948,7 +2118,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * all streams recompressed in solid mode. * * Currently, new solid blocks will, by default, be written using LZMS - * compression with 64 MiB (67108864 byte) chunks. Use + * 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 @@ -2349,6 +2519,12 @@ wimlib_add_tree(WIMStruct *wim, int image, * @param ctype * The type of compression to be used in the new WIM file, as one of the * ::wimlib_compression_type constants. + *
+ * This choice is not necessarily final; if desired, it can still be + * changed at any time before the WIM is written to disk, using + * wimlib_set_output_compression_type(). In addition, if you wish to use a + * non-default chunk size, you will need to call + * wimlib_set_output_chunk_size(). * @param wim_ret * On success, a pointer to an opaque ::WIMStruct for the new WIM file is * written to the memory location pointed to by this parameter. The @@ -2368,12 +2544,8 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); * * Deletes an image, or all images, from a WIM file. * - * All streams referenced by the image(s) being deleted are removed from the - * lookup table of the WIM if they are not referenced by any other images in the - * WIM. - * - * Please note that @b no changes are committed to the underlying WIM file (if - * any) until wimlib_write() or wimlib_overwrite() is called. + * Note: no changes are committed to the underlying WIM file (if any) until + * wimlib_write() or wimlib_overwrite() is called. * * @param wim * Pointer to the ::WIMStruct for the WIM file that contains the image(s) @@ -2381,6 +2553,7 @@ wimlib_create_new_wim(int ctype, WIMStruct **wim_ret); * @param image * The number of the image to delete, or ::WIMLIB_ALL_IMAGES to delete all * images. + * * @return 0 on success; nonzero on failure. On failure, @p wim is guaranteed * to be left unmodified only if @p image specified a single image. If instead * @p image was ::WIMLIB_ALL_IMAGES and @p wim contained more than one image, it's @@ -2512,8 +2685,7 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * controllable by the @p extract_flags parameter, but there also are * differences depending on the platform (UNIX-like vs Windows). See the manual * page for wimlib-imagex apply for more information, including about the - * special "NTFS volume extraction mode" entered by providing - * ::WIMLIB_EXTRACT_FLAG_NTFS. + * NTFS-3g extraction mode. * * @param wim * The WIM from which to extract the image(s), specified as a pointer to @@ -2525,7 +2697,7 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * @param image * The image to extract, specified as either the 1-based index of a single * image to extract, or ::WIMLIB_ALL_IMAGES to specify that all images are - * to be extracted. ::WIMLIB_ALL_IMAGES cannot be used if + * to be extracted. However, ::WIMLIB_ALL_IMAGES cannot be used if * ::WIMLIB_EXTRACT_FLAG_NTFS is specified in @p extract_flags. * @param target * Directory to extract the WIM image(s) to; or, with @@ -2542,10 +2714,11 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * @retval ::WIMLIB_ERR_INVALID_PARAM * The extraction flags were invalid; more details may be found in the * documentation for the specific extraction flags that were specified. Or - * @p target was @c NULL or the empty string, or @p wim was @c NULL. + * @p target was @c NULL or an empty string, or @p wim was @c NULL. * @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. + * message digest given in the WIM. In other words, the WIM file is + * corrupted, so the data cannot be extracted in its original form. * @retval ::WIMLIB_ERR_LINK * Failed to create a symbolic link or a hard link. * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND @@ -2570,22 +2743,20 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND * One of the files or directories that needed to be extracted referenced a * stream not present in the WIM's lookup table (or in any of the lookup - * tables of the split WIM parts). + * tables of the split WIM parts). This can happen if the WIM is not + * standalone and the necessary resource WIMs, or split WIM parts, were not + * referenced with wimlib_reference_resource_files(). * @retval ::WIMLIB_ERR_SET_ATTRIBUTES * Failed to set attributes on a file. * @retval ::WIMLIB_ERR_SET_REPARSE_DATA * Failed to set reparse data on a file (only if reparse data was supported * by the extraction mode). * @retval ::WIMLIB_ERR_SET_SECURITY - * Failed to set security descriptor on a file - * (only if ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS was specified in @p - * extract_flags). + * Failed to set security descriptor on a file. * @retval ::WIMLIB_ERR_SET_SHORT_NAME - * Failed to set the short name of a file (only if - * ::WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES was specified in @p extract_flags). + * Failed to set the short name of a file. * @retval ::WIMLIB_ERR_SET_TIMESTAMPS - * Failed to set timestamps on a file (only if - * ::WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS was specified in @p extract_flags). + * Failed to set timestamps on a file. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE * Unexpected end-of-file occurred when reading data from the WIM. * @retval ::WIMLIB_ERR_UNSUPPORTED @@ -2611,7 +2782,9 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * * If a progress function is registered with @p wim, then as each image is * extracted it will receive ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, then - * zero or more ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS messages, then + * zero or more ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE messages, then zero + * or more ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS messages, then zero or more + * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, then * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. */ extern int @@ -2621,11 +2794,10 @@ wimlib_extract_image(WIMStruct *wim, int image, /** * @ingroup G_extracting_wims * - * Since wimlib v1.5.0: Extract one image from a pipe on which a pipable WIM is - * being sent. + * Extract one image from a pipe on which a pipable WIM is being sent. * - * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE for more information - * about pipable WIMs. + * See the documentation for ::WIMLIB_WRITE_FLAG_PIPABLE, and @ref + * subsec_pipable_wims, for more information about pipable WIMs. * * This function operates in a special way to read the WIM fully sequentially. * As a result, there is no ::WIMStruct is made visible to library users, and @@ -2655,7 +2827,7 @@ wimlib_extract_image(WIMStruct *wim, int image, * @retval ::WIMLIB_ERR_INVALID_PIPABLE_WIM * Data read from the pipable WIM was invalid. * @retval ::WIMLIB_ERR_NOT_PIPABLE - * The WIM being piped in a @p pipe_fd is a normal WIM, not a pipable WIM. + * The WIM being piped over @p pipe_fd is a normal WIM, not a pipable WIM. */ extern int wimlib_extract_image_from_pipe(int pipe_fd, @@ -2682,12 +2854,13 @@ wimlib_extract_image_from_pipe_with_progress(int pipe_fd, /** * @ingroup G_extracting_wims * - * Since wimlib v1.6.0: Similar to wimlib_extract_paths(), but the paths to - * extract from the WIM image are specified in the ASCII, UTF-8, or UTF-16LE - * text file named by @p path_list_file which itself contains the list of paths - * to use, one per line. Leading and trailing whitespace, and otherwise empty - * lines and lines beginning with the ';' character are ignored. No quotes are - * needed as paths are otherwise delimited by the newline character. + * Similar to wimlib_extract_paths(), but the paths to extract from the WIM + * image are specified in the ASCII, UTF-8, or UTF-16LE text file named by @p + * path_list_file which itself contains the list of paths to use, one per line. + * Leading and trailing whitespace is ignored. Empty lines and lines beginning + * with the ';' or '#' characters are ignored. No quotes are needed, as paths + * are otherwise delimited by the newline character. However, quotes will be + * stripped if present. * * The error codes are the same as those returned by wimlib_extract_paths(), * except that wimlib_extract_pathlist() returns an appropriate error code if it @@ -2703,8 +2876,8 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, /** * @ingroup G_extracting_wims * - * Since wimlib v1.6.0: Extract zero or more paths (files or directory trees) - * from the specified WIM image. + * Extract zero or more paths (files or directory trees) from the specified WIM + * image. * * By default, each path will be extracted to a corresponding subdirectory of * the target based on its location in the WIM image. For example, if one of @@ -2732,8 +2905,9 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * file or directory within the WIM image. Separators may be either * forwards or backwards slashes, and leading path separators are optional. * The paths will be interpreted either case-sensitively (UNIX default) or - * case-insensitively (Windows default); this can be changed by - * wimlib_global_init(). + * case-insensitively (Windows default); however, the behavior can be + * configured explicitly at library initialization time by passing an + * appropriate flag to wimlib_global_init(). *
* By default, the characters @c * and @c ? are interpreted literally. * This can be changed by specifying ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p @@ -2757,9 +2931,6 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * as those returned by wimlib_extract_image(). Below, some of the error codes * returned in situations specific to path-mode extraction are documented: * - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image was ::WIMLIB_ALL_IMAGES or was otherwise not a valid single - * image in the WIM. * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST * One of the paths to extract did not exist in the WIM image. This error * code can only be returned if ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS was not @@ -2852,8 +3023,9 @@ wimlib_get_compression_type_string(int ctype); * The error code returned by one of wimlib's functions. * * @return - * Pointer to a statically allocated string describing the error code, - * or @c NULL if the error code is not valid. + * Pointer to a statically allocated string describing the error code. If + * the error code is for some reason not recognized by the library, the + * string will be "Unknown error". */ extern const wimlib_tchar * wimlib_get_error_string(enum wimlib_error_code code); @@ -3189,7 +3361,7 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, * ::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. + * directory is automatically deleted when the image is unmounted. * * @return 0 on success; nonzero on error. The possible error codes include: * @@ -3201,7 +3373,7 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, * @retval ::WIMLIB_ERR_INVALID_IMAGE * @p image does not specify an existing, single image in @p wim. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p wim was @c NULL; or @p dir was NULL or the empty string; or an + * @p wim was @c NULL; or @p dir was NULL or an 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 @@ -3212,9 +3384,7 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, * 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 using - * --without-fuse. + * Mounting is not supported in this build of the library. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, @@ -3290,7 +3460,7 @@ wimlib_mount_image(WIMStruct *wim, * @retval ::WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY * The lookup table of the WIM was invalid. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p wim_ret was @c NULL. + * @p wim_ret was @c NULL; or, @p wim_file was not a nonempty string. * @retval ::WIMLIB_ERR_IS_SPLIT_WIM * The WIM was a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was * specified in @p open_flags. @@ -3300,11 +3470,13 @@ wimlib_mount_image(WIMStruct *wim, * The file did not begin with the magic characters that identify a WIM * file. * @retval ::WIMLIB_ERR_OPEN - * Failed to open the file for reading. + * Failed to open the WIM file for reading. Some possible reasons: the WIM + * file does not exist, or the calling process does not have permission to + * open it. * @retval ::WIMLIB_ERR_READ - * Failed to read data from the file. + * Failed to read data from the WIM file. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Unexpected end-of-file while reading data from the file. + * Unexpected end-of-file while reading data from the WIM file. * @retval ::WIMLIB_ERR_UNKNOWN_VERSION * The WIM version number was not recognized. (May be a pre-Vista WIM.) * @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED @@ -3331,7 +3503,7 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * wimlib_register_progress_function(). In addition, if * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p open_flags, the * progress function will receive ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY - * messages while checking the WIM's integrity. + * messages while checking the WIM file's integrity. */ extern int wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, @@ -3372,8 +3544,8 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, * images have been deleted from the WIM. * * If this function completes successfully, no more functions should be called - * on @p wim other than wimlib_free(). You must use wimlib_open_wim() to read - * the WIM file anew. + * on @p wim other than wimlib_free(). If you need to continue using the WIM, + * you must use wimlib_open_wim() to read it anew. * * @param wim * Pointer to the ::WIMStruct for the WIM file to write. There may have @@ -3382,7 +3554,8 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, * @param write_flags * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. * @param num_threads - * Number of threads to use for compression (see wimlib_write()). + * Number of threads to use for compression, or 0 for the default. (See + * wimlib_write().) * * @return 0 on success; nonzero on error. This function may return most error * codes returned by wimlib_write() as well as the following error codes: @@ -3661,6 +3834,43 @@ extern int wimlib_resolve_image(WIMStruct *wim, const wimlib_tchar *image_name_or_num); +/** + * @ingroup G_general + * + * Sets the file to which the library will print error and warning messages. + * + * This version of the function takes a C library FILE * opened for + * writing (or appending). Use wimlib_set_error_file_by_name() to specify the + * file by name instead. + * + * This also enables error messages, as if by a call to + * wimlib_set_print_errors(true). + * + * @return 0 on success; nonzero on error. + * @retval ::WIMLIB_ERR_UNSUPPORTED + * wimlib was compiled using the --without-error-messages option. + */ +extern int +wimlib_set_error_file(FILE *fp); + +/** + * @ingroup G_general + * + * Sets the path to the file to which the library will print error and warning + * messages. The library will open this file for appending. + * + * This also enables error messages, as if by a call to + * wimlib_set_print_errors(true). + * + * @return 0 on success; nonzero on error. + * @retval ::WIMLIB_ERR_OPEN + * The file named by @p path could not be opened for appending. + * @retval ::WIMLIB_ERR_UNSUPPORTED + * wimlib was compiled using the --without-error-messages option. + */ +extern int +wimlib_set_error_file_by_name(const wimlib_tchar *path); + /** * @ingroup G_modifying_wims * @@ -3942,6 +4152,45 @@ wimlib_split(WIMStruct *wim, uint64_t part_size, int write_flags); +/** + * @ingroup G_general + * + * Perform verification checks on a WIM file. + * + * @param wim + * The ::WIMStruct for the WIM file to verify. Note: for an extra layer of + * verification, it is a good idea to have used + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY when you opened the file. + *
+ * If verifying a split WIM, specify the first part of the split WIM here, + * and reference the other parts using wimlib_reference_resource_files() + * before calling this function. + * + * @param verify_flags + * Reserved; must be 0. + * + * @retval 0 if the WIM file was successfully verified; nonzero if it failed + * verification or another error occurred. Some of the possible error codes + * are: + * + * @retval ::WIMLIB_ERR_DECOMPRESSION + * A compressed resource could not be decompressed. + * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE + * The metadata resource for an image is invalid. + * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH + * One of the files did not decompress to its original data, as given by a + * cryptographic checksum. + * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND + * One of the files referenced by an image could not be located. + * + * If a progress function is registered with @p wim, it will receive the + * following progress messages: ::WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE, + * ::WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE, and + * ::WIMLIB_PROGRESS_MSG_VERIFY_STREAMS. + */ +extern int +wimlib_verify_wim(WIMStruct *wim, int verify_flags); + /** * @ingroup G_mounting_wim_images * @@ -3969,9 +4218,7 @@ wimlib_split(WIMStruct *wim, * @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 using @c - * --without-fuse. + * Mounting is not supported in this build of the library. * * 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 @@ -4130,12 +4377,10 @@ wimlib_update_image(WIMStruct *wim, * Bitwise OR of any of the flags prefixed with @c WIMLIB_WRITE_FLAG. * @param num_threads * Number of threads to use for compressing data. If 0, the number of - * threads is taken to be the number of online processors. Note: if no - * data compression needs to be done, no additional threads will be created - * regardless of this parameter (e.g. if writing an uncompressed WIM, or - * exporting an image from a compressed WIM to another WIM of the same - * compression type without ::WIMLIB_WRITE_FLAG_RECOMPRESS specified in @p - * write_flags). + * threads will be set by the library automatically. This chosen value + * will generally be the number of online processors, but the + * implementation may take into account other information (e.g. available + * memory and overall system activity). * * @return 0 on success; nonzero on error. * @@ -4143,11 +4388,11 @@ wimlib_update_image(WIMStruct *wim, * @p image does not specify a single existing image in @p 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 - * wimlib_add_image() was concurrently modified, so it failed the SHA1 - * message digest check. + * A file resource failed a SHA-1 message digest check. This can happen if + * a file that had previously been scanned for inclusion in the WIM by was + * concurrently modified. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p path was @c NULL. + * @p path was not a nonempty string, or invalid flags were passed. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_OPEN @@ -4172,8 +4417,7 @@ wimlib_update_image(WIMStruct *wim, * ::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 an image that needed to - * be written. + * different reasons) to read the data from a WIM archive. * * If a progress function is registered with @p wim, it will receive the * messages ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS, @@ -4190,12 +4434,11 @@ wimlib_write(WIMStruct *wim, /** * @ingroup G_writing_and_overwriting_wims * - * Since wimlib v1.5.0: Same as wimlib_write(), but write the WIM directly to a - * file descriptor, which need not be seekable if the write is done in a special - * pipable WIM format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p - * write_flags. This can, for example, allow capturing a WIM image and - * streaming it over the network. See the documentation for - * ::WIMLIB_WRITE_FLAG_PIPABLE for more information about pipable WIMs. + * Same as wimlib_write(), but write the WIM directly to a file descriptor, + * which need not be seekable if the write is done in a special pipable WIM + * format by providing ::WIMLIB_WRITE_FLAG_PIPABLE in @p write_flags. This can, + * for example, allow capturing a WIM image and streaming it over the network. + * See @ref subsec_pipable_wims for more information about pipable WIMs. * * The file descriptor @p fd will @b not be closed when the write is complete; * the calling code is responsible for this. @@ -4217,157 +4460,19 @@ wimlib_write_to_fd(WIMStruct *wim, /** * @defgroup G_compression Compression and decompression functions * - * @brief Functions for LZX, XPRESS, and LZMS compression and decompression, - * exported for convenience only, as they are already used by wimlib internally - * when appropriate. + * @brief Functions for XPRESS, LZX, and LZMS compression and decompression. * - * These functions can be used for general-purpose lossless data compression, - * but some limitations apply; for example, none of the compressors or - * decompressors currently support sliding windows, and there also exist - * slightly different variants of these formats that are not supported - * unmodified. + * These functions are already used by wimlib internally when appropriate for + * reading and writing WIM archives. But they are exported and documented so + * that they can be used in other applications or libraries for general-purpose + * lossless data compression. They are implemented in highly optimized C code, + * using state-of-the-art compression techniques. The main limitation is the + * lack of sliding window support; this has, however, allowed the algorithms to + * be optimized for block-based compression. * * @{ */ -/** Header for compression parameters to pass to wimlib_create_compressor() or - * wimlib_set_default_compressor_params(). */ -struct wimlib_compressor_params_header { - /** Size of the parameters, in bytes. */ - uint32_t size; -}; - -/** Header for decompression parameters to pass to wimlib_create_decompressor() - * or wimlib_set_default_decompressor_params() */ -struct wimlib_decompressor_params_header { - /** Size of the parameters, in bytes. */ - uint32_t size; -}; - -/** LZX compression parameters that can optionally be passed to - * wimlib_create_compressor() with the compression type - * ::WIMLIB_COMPRESSION_TYPE_LZX. */ -struct wimlib_lzx_compressor_params { - /** hdr.size Must be set to the size of this structure, in bytes. */ - struct wimlib_compressor_params_header hdr; - - /** Relatively fast LZX compression algorithm with a decent compression - * ratio. */ -#define WIMLIB_LZX_ALGORITHM_FAST 0 - - /** Slower LZX compression algorithm that provides a better compression - * ratio. This is the default. */ -#define WIMLIB_LZX_ALGORITHM_SLOW 1 - - /** Algorithm to use to perform the compression: either - * ::WIMLIB_LZX_ALGORITHM_FAST or ::WIMLIB_LZX_ALGORITHM_SLOW. The - * format is still LZX; this refers to the method the code will use to - * perform LZX-compatible compression. */ - uint32_t algorithm : 3; - - /** If set to 1, the default parameters for the specified algorithm are - * used rather than the ones specified in the following union. */ - uint32_t use_defaults : 1; - - union { - /** Parameters for the fast algorithm. */ - struct wimlib_lzx_fast_params { - uint32_t fast_reserved1[10]; - } fast; - - /** 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 can only output - * matches of length 3 or greater. Suggested value: 1 - */ - uint32_t use_len2_matches : 1; - - uint32_t slow_reserved1 : 31; - - /** Matches with length (in bytes) greater than or equal - * to this value are immediately taken without spending - * time on minimum-cost measurements. Suggested value: - * 32. */ - uint32_t nice_match_length; - - /** Number of passes to compute a match/literal sequence - * for each LZX block. This is for an iterative - * algorithm that attempts to minimize the cost of the - * match/literal sequence by using a cost model provided - * by the previous iteration. Must be at least 1. - * Suggested value: 2. */ - uint32_t num_optim_passes; - - /** Reserved; set to 0. */ - uint32_t slow_reserved_blocksplit; - - /** Maximum depth to search for matches at each - * position. Suggested value: 50. */ - uint32_t max_search_depth; - - /* Note: max_matches_per_pos has been removed and no - * longer has any effect. */ - - 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: 15. */ - uint8_t main_nostat_cost; - - /** Assumed cost of a length symbol with zero frequency. - * Must be at least 1 and no more than 16. Suggested - * value: 15. */ - uint8_t len_nostat_cost; - - /** Assumed cost of an aligned symbol with zero - * frequency. Must be at least 1 and no more than 8. - * Suggested value: 7. */ - uint8_t aligned_nostat_cost; - - uint8_t slow_reserved3[5]; - } slow; - } alg_params; -}; - -/** LZMS compression parameters that can optionally be passed to - * wimlib_create_compressor() with the compression type - * ::WIMLIB_COMPRESSION_TYPE_LZMS. */ -struct wimlib_lzms_compressor_params { - /** hdr.size Must be set to the size of this structure, in bytes. */ - struct wimlib_compressor_params_header hdr; - - /** Minimum match length to output. This must be at least 2. Suggested - * value: 2 */ - uint32_t min_match_length; - - /** Maximum match length to output. This must be at least @p - * min_match_length. Suggested value: @p UINT32_MAX. */ - uint32_t max_match_length; - - /** Matches with length (in bytes) greater than or equal to this value - * are immediately taken without spending time on minimum-cost - * measurements. The minimum of @p max_match_length and @p - * nice_match_length may not exceed 65536. Suggested value: 32. */ - uint32_t nice_match_length; - - /** Maximum depth to search for matches at each position. Suggested - * value: 50. */ - uint32_t max_search_depth; - - /* 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. */ - uint32_t optim_array_length; - - uint64_t reserved2[4]; -}; - /** Opaque compressor handle. */ struct wimlib_compressor; @@ -4375,41 +4480,49 @@ struct wimlib_compressor; struct wimlib_decompressor; /** - * Set the default compression parameters for the specified compression type. - * This will affect both explicit and library-internal calls to - * wimlib_create_compressor(). + * Set the default compression level for the specified compression type. This + * is the compression level that wimlib_create_compressor() assumes if it is + * called with @p compression_level specified as 0. + * + * wimlib's WIM writing code (e.g. wimlib_write()) will pass 0 to + * wimlib_create_compressor() internally. Therefore, calling this function will + * affect the compression level of any data later written to WIM files using the + * specified compression type. + * + * The initial state, before this function is called, is that all compression + * types have a default compression level of 50. * * @param ctype - * Compression type for which to set the default compression parameters. - * @param params - * Compression-type specific parameters. This may be @c NULL, in which - * case the "default default" parameters are restored. + * Compression type for which to set the default compression level, as one + * of the ::wimlib_compression_type constants. Or, if this is the special + * value -1, the default compression levels for all compression types will + * be set. + * @param compression_level + * The default compression level to set. If 0, the "default default" level + * of 50 is restored. Otherwise, a higher value indicates higher + * compression, whereas a lower value indicates lower compression. See + * wimlib_create_compressor() for more information. * * @return 0 on success; nonzero on error. * * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE - * @p ctype was not a supported compression type. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p params were invalid. - * @retval ::WIMLIB_ERR_NOMEM - * Not enough memory to duplicate the parameters (perhaps @c params->size - * was invalid). + * @p ctype was neither a supported compression type nor -1. */ extern int -wimlib_set_default_compressor_params(enum wimlib_compression_type ctype, - const struct wimlib_compressor_params_header *params); +wimlib_set_default_compression_level(int ctype, unsigned int compression_level); /** * Returns the approximate number of bytes needed to allocate a compressor with - * wimlib_create_compressor() for the specified compression type, block size, - * and parameters. @p params may be @c NULL, in which case the current default - * parameters for @p ctype are used. Returns 0 if the compression type or - * parameters are invalid. + * wimlib_create_compressor() for the specified compression type, maximum block + * size, and compression level. @p compression_level may be 0, in which case + * the current default compression level for @p ctype is used. Returns 0 if the + * compression type is invalid, or the @p max_block_size for that compression + * type is invalid. */ extern uint64_t wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype, size_t max_block_size, - const struct wimlib_compressor_params_header *params); + unsigned int compression_level); /** * Allocate a compressor for the specified compression type using the specified @@ -4417,45 +4530,74 @@ wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype, * necessary to call this to process a WIM file. * * @param ctype - * Compression type for which to create the compressor. + * Compression type for which to create the compressor, as one of the + * ::wimlib_compression_type constants. * @param max_block_size - * Maximum block size to support. The exact meaning and allowed values for - * this parameter depend on the compression type, but it at least specifies - * the maximum allowed value for @p uncompressed_size to wimlib_compress(). - * @param extra_params - * An optional pointer to extra compressor parameters for the specified - * compression type. For LZX, a pointer to ::wimlib_lzx_compressor_params - * may be specified here. For LZMS, a pointer to - * ::wimlib_lzms_compressor_params may be specified here. If left @c NULL, - * the default parameters are used. + * The maximum compression block size to support. This specifies the + * maximum allowed value for the @p uncompressed_size parameter of + * wimlib_compress() when called using this compressor. + *
+ * Usually, the amount of memory used by the compressor will scale in + * proportion to the @p max_block_size parameter. + * wimlib_get_compressor_needed_memory() can be used to query the specific + * amount of memory that will be required. + *
+ * This parameter must be at least 1 and must be less than or equal to a + * compression-type-specific limit. + *
+ * In general, the same value of @p max_block_size must be passed to + * wimlib_create_decompressor() when the data is later decompressed. + * However, some compression types have looser requirements regarding this. + * @param compression_level + * The compression level to use. If 0, the default compression level (50, + * or another value as set through wimlib_set_default_compression_level()) + * is used. Otherwise, a higher value indicates higher compression. The + * values are scaled so that 10 is low compression, 50 is medium + * compression, and 100 is high compression. This is not a percentage; + * values above 100 are also valid. + *
+ * Using a higher-than-default compression level can result in a better + * compression ratio, but can significantly reduce performance. Similarly, + * using a lower-than-default compression level can result in better + * performance, but can significantly worsen the compression ratio. The + * exact results will depend heavily on the compression type and what + * algorithms are implemented for it. If you are considering using a + * non-default compression level, you should run benchmarks to see if it is + * worthwhile for your application. + *
+ * The compression level does not affect the format of the compressed data. + * Therefore, it is a compressor-only parameter and does not need to be + * passed to the decompressor. * @param compressor_ret - * A location into which to return the pointer to the allocated compressor, - * which can be used for any number of calls to wimlib_compress() before - * being freed with wimlib_free_compressor(). + * A location into which to return the pointer to the allocated compressor. + * The allocated compressor can be used for any number of calls to + * wimlib_compress() before being freed with wimlib_free_compressor(). * * @return 0 on success; nonzero on error. * * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE * @p ctype was not a supported compression type. * @retval ::WIMLIB_ERR_INVALID_PARAM - * The compression parameters were invalid. + * @p max_block_size was invalid for the compression type, or @p + * compressor_ret was @c NULL. * @retval ::WIMLIB_ERR_NOMEM * Insufficient memory to allocate the compressor. */ extern int wimlib_create_compressor(enum wimlib_compression_type ctype, size_t max_block_size, - const struct wimlib_compressor_params_header *extra_params, + unsigned int compression_level, struct wimlib_compressor **compressor_ret); /** - * Losslessly compress a block of data using a compressor previously created - * with wimlib_create_compressor(). + * Compress a buffer of data. * * @param uncompressed_data * Buffer containing the data to compress. * @param uncompressed_size - * Size, in bytes, of the data to compress. + * Size, in bytes, of the data to compress. This cannot be greater than + * the @p max_block_size with which wimlib_create_compressor() was called. + * (If it is, the data will not be compressed and 0 will be returned.) * @param compressed_data * Buffer into which to write the compressed data. * @param compressed_size_avail @@ -4464,8 +4606,8 @@ wimlib_create_compressor(enum wimlib_compression_type ctype, * A compressor previously allocated with wimlib_create_compressor(). * * @return - * The size of the compressed data, in bytes, or 0 if the input data could - * not be compressed to @p compressed_size_avail or fewer bytes. + * The size of the compressed data, in bytes, or 0 if the data could not be + * compressed to @p compressed_size_avail or fewer bytes. */ extern size_t wimlib_compress(const void *uncompressed_data, size_t uncompressed_size, @@ -4476,72 +4618,51 @@ wimlib_compress(const void *uncompressed_data, size_t uncompressed_size, * Free a compressor previously allocated with wimlib_create_compressor(). * * @param compressor - * The compressor to free. + * The compressor to free. If @c NULL, no action is taken. */ extern void wimlib_free_compressor(struct wimlib_compressor *compressor); /** - * Set the default decompression parameters for the specified compression type. - * This will affect both explicit and library-internal calls to - * wimlib_create_decompressor(). + * Allocate a decompressor for the specified compression type. This function is + * part of wimlib's compression API; it is not necessary to call this to process + * a WIM file. * * @param ctype - * Compression type for which to set the default decompression parameters. - * @param params - * Compression-type specific parameters. This may be @c NULL, in which - * case the "default default" parameters are restored. - * - * @return 0 on success; nonzero on error. - * - * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE - * @p ctype was not a supported compression type. - * @retval ::WIMLIB_ERR_NOMEM - * Not enough memory to duplicate the parameters (perhaps @c params->size - * was invalid). - */ -extern int -wimlib_set_default_decompressor_params(enum wimlib_compression_type ctype, - const struct wimlib_decompressor_params_header *params); - -/** - * Allocate a decompressor for the specified compression type using the - * specified parameters. This function is part of wimlib's compression API; it - * is not necessary to call this to process a WIM file. - * - * @param ctype - * Compression type for which to create the decompressor. + * Compression type for which to create the decompressor, as one of the + * ::wimlib_compression_type constants. * @param max_block_size - * Maximum block size to support. The exact meaning and allowed values for - * this parameter depend on the compression type, but it at least specifies - * the maximum allowed value for @p uncompressed_size to + * The maximum compression block size to support. This specifies the + * maximum allowed value for the @p uncompressed_size parameter of * wimlib_decompress(). - * @param extra_params - * An optional pointer to extra decompressor parameters for the specified - * compression type. If @c NULL, the default parameters are used. + *
+ * In general, this parameter must be the same as the @p max_block_size + * that was passed to wimlib_create_compressor() when the data was + * compressed. However, some compression types have looser requirements + * regarding this. * @param decompressor_ret * A location into which to return the pointer to the allocated - * decompressor, which can be used for any number of calls to - * wimlib_decompress() before being freed with wimlib_free_decompressor(). + * decompressor. The allocated decompressor can be used for any number of + * calls to wimlib_decompress() before being freed with + * wimlib_free_decompressor(). * * @return 0 on success; nonzero on error. * * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE * @p ctype was not a supported compression type. * @retval ::WIMLIB_ERR_INVALID_PARAM - * The decompression parameters were invalid. + * @p max_block_size was invalid for the compression type, or @p + * decompressor_ret was @c NULL. * @retval ::WIMLIB_ERR_NOMEM * Insufficient memory to allocate the decompressor. */ extern int wimlib_create_decompressor(enum wimlib_compression_type ctype, size_t max_block_size, - const struct wimlib_decompressor_params_header *extra_params, struct wimlib_decompressor **decompressor_ret); /** - * Decompress a block of data using a decompressor previously created with - * wimlib_create_decompressor(). + * Decompress a buffer of data. * * @param compressed_data * Buffer containing the data to decompress. @@ -4550,11 +4671,22 @@ wimlib_create_decompressor(enum wimlib_compression_type ctype, * @param uncompressed_data * Buffer into which to write the uncompressed data. * @param uncompressed_size - * Size, in bytes, of the data when uncompressed. + * Size, in bytes, of the data when uncompressed. This cannot exceed the + * @p max_block_size with which wimlib_create_decompressor() was called. + * (If it does, the data will not be decompressed and a nonzero value will + * be returned.) * @param decompressor * A decompressor previously allocated with wimlib_create_decompressor(). * * @return 0 on success; nonzero on error. + * + * No specific error codes are defined; any nonzero value indicates that the + * decompression failed. This can only occur if the data is truly invalid; + * there will never be transient errors like "out of memory", for example. + * + * This function requires that the exact uncompressed size of the data be passed + * as the @p uncompressed_size parameter. If this is not done correctly, + * decompression may fail or the data may be decompressed incorrectly. */ extern int wimlib_decompress(const void *compressed_data, size_t compressed_size, @@ -4565,7 +4697,7 @@ wimlib_decompress(const void *compressed_data, size_t compressed_size, * Free a decompressor previously allocated with wimlib_create_decompressor(). * * @param decompressor - * The decompressor to free. + * The decompressor to free. If @c NULL, no action is taken. */ extern void wimlib_free_decompressor(struct wimlib_decompressor *decompressor);