* in this header.
*/
-/*
- * Copyright (C) 2012, 2013, 2014 Eric Biggers
- *
- * This file is part of wimlib, a library for working with WIM files.
- *
- * wimlib is free software; you can redistribute it and/or modify it under the
- * terms of the GNU General Public License as published by the Free
- * Software Foundation; either version 3 of the License, or (at your option)
- * any later version.
- *
- * wimlib is distributed in the hope that it will be useful, but WITHOUT ANY
- * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
- * A PARTICULAR PURPOSE. See the GNU General Public License for more
- * details.
- *
- * You should have received a copy of the GNU General Public License
- * along with wimlib; if not, see http://www.gnu.org/licenses/.
- */
-
/**
* @mainpage
*
- * This is the documentation for the library interface of wimlib 1.7.1, a C
+ * This is the documentation for the library interface of wimlib 1.7.4, a C
* library for creating, modifying, extracting, and mounting files in the
* Windows Imaging Format. This documentation is intended for developers only.
* If you have installed wimlib and want to know how to use the @b wimlib-imagex
* source code of <b>wimlib-imagex</b></a>, which is complicated but uses most
* capabilities of wimlib.
*
+ * @section backwards_compatibility Backwards Compatibility
+ *
+ * New releases of wimlib are intended to be API/ABI compatible with old
+ * releases, except when the libtool "age" is reset. This most recently
+ * occurred for the v1.4.0 (libwim7), v1.5.0 (libwim9), and v1.7.0 (libwim15)
+ * releases. However, the library is becoming increasingly stable, and the goal
+ * is to maintain the current API/ABI for as long as possible unless there is a
+ * strong reason not to. Even for the v1.7.0 release (libwim15), the changes
+ * were fairly limited.
+ *
+ * As with any other library, applications should not rely on internal
+ * implementation details that may be subject to change.
+ *
* @section sec_basic_wim_handling_concepts Basic WIM handling concepts
*
* wimlib wraps up a WIM file in an opaque ::WIMStruct structure. There are
*
* @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 <code>--without-fuse</code> 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 <code>--without-fuse</code> 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()).
*/
/**
#define WIMLIB_MINOR_VERSION 7
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 1
+#define WIMLIB_PATCH_VERSION 4
#ifdef __cplusplus
extern "C" {
/**
* 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 <c>2^12</c> and <c>2^16</c>, inclusively. */
+ * between <c>2^12</c> and <c>2^16</c>, 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 and including <c>2^16</c>.
+ */
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 <c>2^15</c> and <c>2^21</c>, inclusively. Note: chunk sizes
* other than <c>2^15</c> 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 and including <c>2^21</c>.
+ */
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 <c>2^15</c> and
* 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 <c>2^26</c> 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 and including <c>1180427429</c>.
+ */
WIMLIB_COMPRESSION_TYPE_LZMS = 3,
};
/** 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.
- */
+ * In particular, the @p current_file_count and @p end_file_count
+ * members may be used to track the progress of this phase of
+ * extraction. */
WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE = 3,
/** File data is currently being extracted. @p info will point to
/** 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.
- */
+ * In particular, the @p current_file_count and @p end_file_count
+ * members may be used to track the progress of this phase of
+ * extraction. */
WIMLIB_PROGRESS_MSG_EXTRACT_METADATA = 6,
/** Confirms that the image has been successfully extracted. @p info
/** wimlib_verify_wim() is verifying stream integrity. @p info will
* point to ::wimlib_progress_info.verify_streams. */
WIMLIB_PROGRESS_MSG_VERIFY_STREAMS = 29,
+
+ /**
+ * The progress function is being asked whether a file should be
+ * excluded from capture or not. @p info will point to
+ * ::wimlib_progress_info.test_file_exclusion. This is a bidirectional
+ * message that allows the progress function to set a flag if the file
+ * should be excluded.
+ *
+ * This message is only received if the flag
+ * ::WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION is used. This method for file
+ * exclusions is independent of the "capture configuration file"
+ * mechanism.
+ */
+ WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION = 30,
+
+ /**
+ * An error has occurred and the progress function is being asked
+ * whether to ignore the error or not. @p info will point to
+ * ::wimlib_progress_info.handle_error. This is a bidirectional
+ * message.
+ *
+ * This message provides a limited capability for applications to
+ * recover from "unexpected" errors (i.e. those with no in-library
+ * handling policy) arising from the underlying operating system.
+ * Normally, any such error will cause the library to abort the current
+ * operation. By implementing a handler for this message, the
+ * application can instead choose to ignore a given error.
+ *
+ * Currently, only the following types of errors will result in this
+ * progress message being sent:
+ *
+ * - Directory tree scan errors, e.g. from wimlib_add_image()
+ * - Most extraction errors; currently restricted to the Windows
+ * build of the library only.
+ */
+ WIMLIB_PROGRESS_MSG_HANDLE_ERROR = 31,
};
/** Valid return values from user-provided progress functions
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
uint8_t guid[WIMLIB_GUID_LEN];
+
+ /** For ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE and
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, this is the
+ * number of files that have been processed so far. Once the
+ * corresponding phase of extraction is complete, this value
+ * will be equal to @c end_file_count. */
+ uint64_t current_file_count;
+
+ /** For ::WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE and
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, this is
+ * total number of files that will be processed.
+ *
+ * This number is provided for informational purposes only.
+ * This number will not necessarily be equal to the number of
+ * files actually being extracted. This is because extraction
+ * backends are free to implement an extraction algorithm that
+ * might be more efficient than processing every file in the
+ * "extract file structure" and "extract metadata" phases. For
+ * example, the current implementation of the UNIX extraction
+ * backend will create files on-demand during the stream
+ * extraction phase. Therefore, when using that particular
+ * extraction backend, @p end_file_count will only include
+ * directories and empty files. */
+ uint64_t end_file_count;
} extract;
/** Valid on messages ::WIMLIB_PROGRESS_MSG_RENAME. */
uint64_t completed_streams;
uint64_t completed_bytes;
} verify_streams;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION. */
+ struct wimlib_progress_info_test_file_exclusion {
+
+ /**
+ * Path to the file for which exclusion is being tested.
+ *
+ * UNIX capture mode: The path will be a standard relative or
+ * absolute UNIX filesystem path.
+ *
+ * NTFS-3g capture mode: The path will be given relative to the
+ * root of the NTFS volume, with a leading slash.
+ *
+ * Windows capture mode: The path will be a Win32 namespace
+ * path to the file.
+ */
+ const wimlib_tchar *path;
+
+ /**
+ * Indicates whether the file or directory will be excluded from
+ * capture or not. This will be <tt>false</tt> by default. The
+ * progress function can set this to <tt>true</tt> if it decides
+ * that the file needs to be excluded.
+ */
+ bool will_exclude;
+ } test_file_exclusion;
+
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_HANDLE_ERROR. */
+ struct wimlib_progress_info_handle_error {
+
+ /** Path to the file for which the error occurred, or NULL if
+ * not relevant. */
+ const wimlib_tchar *path;
+
+ /** The wimlib error code associated with the error. */
+ int error_code;
+
+ /**
+ * Indicates whether the error will be ignored or not. This
+ * will be <tt>false</tt> by default; the progress function may
+ * set it to <tt>true</tt>.
+ */
+ bool will_ignore;
+ } handle_error;
};
/**
long reserved;
};
-/** Set or unset the WIM header flag that marks it read-only
- * (WIM_HDR_FLAG_READONLY in Microsoft's documentation), based on the
- * ::wimlib_wim_info.is_marked_readonly member of the @p info parameter. This
- * is distinct from basic file permissions; this flag can be set on a WIM file
- * that is physically writable. If this flag is set, all further operations to
- * modify the WIM will fail, except calling wimlib_overwrite() with
- * ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG specified, which is a loophole that
- * allows you to set this flag persistently on the underlying WIM file.
+/** Set or unset the "readonly" WIM header flag (WIM_HDR_FLAG_READONLY in
+ * Microsoft's documentation), based on the ::wimlib_wim_info.is_marked_readonly
+ * member of the @p info parameter. This is distinct from basic file
+ * permissions; this flag can be set on a WIM file that is physically writable.
+ *
+ * wimlib disallows modifying on-disk WIM files with the readonly flag set.
+ * However, wimlib_overwrite() with ::WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG
+ * will override this --- and in fact, this is necessary to set the readonly
+ * flag persistently on an existing WIM file.
*/
#define WIMLIB_CHANGE_READONLY_FLAG 0x00000001
/** @} */
-/** @addtogroup G_wim_information
- * { */
+/** @addtogroup G_wim_information */
/** @{ */
/** 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. */
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
/** 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. */
* 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];
};
* 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
#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. */
/** 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 <c>stream_name
+ * == NULL</c>. 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 <c>stream_name != NULL</c>.
+ */
struct wimlib_stream_entry streams[];
};
*/
#define WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000
+/**
+ * Send ::WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION messages to the progress
+ * function.
+ *
+ * Note: This method for file exclusions is independent from the capture
+ * configuration file mechanism.
+ */
+#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION 0x00004000
+
+/* Note: the WIMLIB_ADD_IMAGE_FLAG names are retained for source compatibility.
+ * Use the WIMLIB_ADD_FLAG names in new code. */
#define WIMLIB_ADD_IMAGE_FLAG_NTFS WIMLIB_ADD_FLAG_NTFS
#define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE WIMLIB_ADD_FLAG_DEREFERENCE
#define WIMLIB_ADD_IMAGE_FLAG_VERBOSE WIMLIB_ADD_FLAG_VERBOSE
/** 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
* 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
* 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 <b>--wimboot</b> option of <b>wimlib-imagex apply</b>
- * 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
+ * <b>--wimboot</b> option of <b>wimlib-imagex apply</b> for more information.
+ */
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
/** @} */
/** 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. */
#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
/** @} */
* only if it is writable at the filesystem level, does not have the
* WIM_HDR_FLAG_READONLY flag set in its header, and is not part of a spanned
* set. It is not required to provide this flag before attempting to make
- * changes to the WIM, but with this flag you get an error sooner rather than
- * later. */
+ * changes to the WIM, but with this flag you get an error immediately rather
+ * than potentially much later, when wimlib_overwrite() is finally called. */
#define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004
/** @} */
* 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 <b>not</b> cause recompression of streams
* that would not otherwise be written. For example, a call to
/**
* 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.
WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79,
WIMLIB_ERR_NOT_A_MOUNTPOINT = 80,
WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81,
+ WIMLIB_ERR_FVE_LOCKED_VOLUME = 82,
};
* There is already an image in @p wim named @p name.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to add the new image.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * The WIM file is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag.
*/
extern int
wimlib_add_empty_image(WIMStruct *wim,
* @param ctype
* The type of compression to be used in the new WIM file, as one of the
* ::wimlib_compression_type constants.
+ * <br/>
+ * 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
*
* 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)
* @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
*
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image does not exist in the WIM and is not ::WIMLIB_ALL_IMAGES.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * The WIM file is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
* WIM parts were not referenced with wimlib_reference_resources() or
* wimlib_reference_resource_files() before the call to
* wimlib_export_image().
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * @p dest_wim is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
* 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 <b>wimlib-imagex apply</b> 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
* @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
* @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
* @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
/**
* @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
* @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,
/**
* @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
/**
* @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
* 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().
* <br/>
* By default, the characters @c * and @c ? are interpreted literally.
* This can be changed by specifying ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p
* 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
* bits contain the patch version.
*
* In other words, the returned value is equal to <code>((WIMLIB_MAJOR_VERSION
- * << 22) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)</code> for the
+ * << 20) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)</code> for the
* corresponding header file.
*/
extern uint32_t
* ::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:
*
* @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
* 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
- * <code>--without-fuse</code>.
+ * 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,
* @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.
* 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
* 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,
* 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
* @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:
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @p description
* string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * @p wim is considered read-only because of any of the reasons mentioned
- * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int
wimlib_set_image_descripton(WIMStruct *wim, int image,
* ::WIMLIB_CHANGE_BOOT_INDEX, and/or ::WIMLIB_CHANGE_RPFIX_FLAG.
*
* @return 0 on success; nonzero on failure.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * The WIM file is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag. However, as a special case, if you are using
- * ::WIMLIB_CHANGE_READONLY_FLAG to unset the readonly flag, then this
- * function will not fail due to the readonly flag being previously set.
* @retval ::WIMLIB_ERR_IMAGE_COUNT
* ::WIMLIB_CHANGE_BOOT_INDEX was specified, but
* ::wimlib_wim_info.boot_index did not specify 0 or a valid 1-based image
* @p image does not specify a single existing image in @p wim.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @p flags string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * @p wim is considered read-only because of any of the reasons mentioned
- * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int
wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags);
* @p image does not specify a single existing image in @p wim.
* @retval ::WIMLIB_ERR_NOMEM
* Failed to allocate the memory needed to duplicate the @p name string.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * @p wim is considered read-only because of any of the reasons mentioned
- * in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.
*/
extern int
wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name);
* @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
* be rolled back, and no visible changes shall have been made to @p wim.
* Possible error codes include:
*
+ * @retval ::WIMLIB_ERR_FVE_LOCKED_VOLUME
+ * Windows-only: One of the "add" commands attempted to add files from an
+ * encrypted BitLocker volume that hasn't yet been unlocked.
* @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
* The capture configuration structure specified for an add command was
* invalid.
* a supported file type (e.g. a device file). Only if
* ::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified in @p the add_flags
* for an update command.
- * @retval ::WIMLIB_ERR_WIM_IS_READONLY
- * The WIM file is considered read-only because of any of the reasons
- * mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
- * flag.
*
* This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
* ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,
* 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.
*
* @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
* ::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,
/**
* @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.
/**
* @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.
*
* @{
*/
/**
* Set the default compression level for the specified compression type. This
- * will affect both explicit and library-internal calls to
- * wimlib_create_compressor().
+ * 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 level, as one
* of the ::wimlib_compression_type constants. Or, if this is the special
- * value -1, the default compression levels for all known compression types
- * will be set.
+ * 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
- * is restored. 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.
+ * 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.
*
/**
* Returns the approximate number of bytes needed to allocate a compressor with
- * wimlib_create_compressor() for the specified compression type, 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.
+ * 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,
* 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().
+ * 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.
+ * <br/>
+ * 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.
+ * <br/>
+ * This parameter must be at least 1 and must be less than or equal to a
+ * compression-type-specific limit.
+ * <br/>
+ * 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 is
- * used. Otherwise, a higher value indicates higher compression. The
+ * 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.
+ * compression, and 100 is high compression. This is not a percentage;
+ * values above 100 are also valid.
+ * <br/>
+ * 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.
+ * <br/>
+ * 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 compressor does not support the specified maximum block size.
+ * @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.
*/
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
* 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,
* 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);
/**
- * 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.
+ * 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 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().
+ * <br/>
+ * 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
+ * @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.
*/
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.
* @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,
* 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);
git://wimlib.net / wimlib / blobdiff