*
* @section sec_intro Introduction
*
- * This is the documentation for the library interface of wimlib 1.5.3, a C
+ * This is the documentation for the library interface of wimlib 1.6.0, a C
* library for creating, modifying, extracting, and mounting files in the
* Windows Imaging Format. This documentation is intended for developers only.
* If you have installed wimlib and want to know how to use the @b wimlib-imagex
*
* wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a set
* of paths from a WIM image in a manner that may be easier to use than
- * wimlib_extract_files(), and also can wildcard characters.
+ * wimlib_extract_files(), and also allow wildcard patterns.
*
* wimlib_extract_image_from_pipe() allows an image to be extracted from a
* pipable WIM sent over a pipe; see @ref subsec_pipable_wims.
#define WIMLIB_MAJOR_VERSION 1
/** Minor version of the library (for example, the 2 in 1.2.5). */
-#define WIMLIB_MINOR_VERSION 5
+#define WIMLIB_MINOR_VERSION 6
/** Patch version of the library (for example, the 5 in 1.2.5). */
-#define WIMLIB_PATCH_VERSION 3
+#define WIMLIB_PATCH_VERSION 0
#ifdef __cplusplus
extern "C" {
* ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN = 0,
- /** A file or directory tree within a WIM image (not the full image) is
- * about to be extracted. @p info will point to
+ /** One or more file or directory trees within a WIM image (not the full
+ * image) is about to be extracted. @p info will point to
* ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
* extracted. @p info will point to ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END,
- /** The WIM image's files resources are currently being extracted. @p
- * info will point to ::wimlib_progress_info.extract. */
+ /** File data is currently being extracted. @p info will point to
+ * ::wimlib_progress_info.extract. */
WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
/** Starting to read a new part of a split pipable WIM over the pipe.
* ::wimlib_progress_info.integrity. */
WIMLIB_PROGRESS_MSG_CALC_INTEGRITY,
- /** Reserved. (Previously used for WIMLIB_PROGRESS_MSG_JOIN_STREAMS,
- * but in wimlib v1.5.0 this was removed to simplify the code and now
- * you'll get ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages instead.) */
+ /** Reserved. */
WIMLIB_PROGRESS_MSG_RESERVED,
/** A wimlib_split() operation is in progress, and a new split part is
unsigned completed_parts;
} write_streams;
- /** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
- * ::WIMLIB_PROGRESS_MSG_SCAN_END. */
+ /** Valid on messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN,
+ * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY, and
+ * ::WIMLIB_PROGRESS_MSG_SCAN_END. */
struct wimlib_progress_info_scan {
- /** Directory or NTFS volume that is being scanned. */
+ /** Top-level directory being scanned; or, when capturing a NTFS
+ * volume with ::WIMLIB_ADD_FLAG_NTFS, this is instead the path
+ * to the file or block device that contains the NTFS volume
+ * being scanned. */
const wimlib_tchar *source;
- /** Path to the file or directory that is about to be scanned,
- * relative to the root of the image capture or the NTFS volume.
- * */
+ /** Path to the file (or directory) that has been scanned, valid
+ * on ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. When capturing a NTFS
+ * volume with ::WIMLIB_ADD_FLAG_NTFS, this path will be
+ * relative to the root of the NTFS volume. */
const wimlib_tchar *cur_path;
+ /** Dentry scan status, valid on
+ * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY. */
enum {
- /** File or directory looks okay and will be captured. */
+ /** The file looks okay and will be captured. */
WIMLIB_SCAN_DENTRY_OK = 0,
- /** File or directory is being excluded from capture due
- * to the capture configuration file, or being an
- * absolute symbolic link that points outside of the
- * capture directory without ::WIMLIB_ADD_FLAG_NORPFIX.
- */
+ /** File is being excluded from capture due to the
+ * capture configuration. */
WIMLIB_SCAN_DENTRY_EXCLUDED,
- /** File or directory is being excluded from capture due
- * to being unsupported (e.g. an encrypted or device
- * file). */
+ /** File is being excluded from capture due to being
+ * unsupported (e.g. an encrypted or device file). */
WIMLIB_SCAN_DENTRY_UNSUPPORTED,
+
+ /** The file is an absolute symbolic link or junction
+ * point and it is being excluded from capture because
+ * it points outside of the capture directory and
+ * reparse-point fixups are enabled. (Reparse point
+ * fixups can be disabled by using the flag
+ * ::WIMLIB_ADD_FLAG_NORPFIX.) */
+ WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK,
} status;
- /** Target path in the WIM. Only valid on messages
- * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
- * ::WIMLIB_PROGRESS_MSG_SCAN_END. */
- const wimlib_tchar *wim_target_path;
+ union {
+ /** Target path in the WIM image. Only valid on
+ * messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and
+ * ::WIMLIB_PROGRESS_MSG_SCAN_END. If capturing a full
+ * image, this will be the empty string; otherwise it
+ * will name the place in the WIM image at which the
+ * directory tree is being added. */
+ const wimlib_tchar *wim_target_path;
+
+ /** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status
+ * of ::WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is the
+ * target of the absolute symbolic link or junction
+ * point. */
+ const wimlib_tchar *symlink_target;
+ };
/** Number of directories scanned so far, including the root
* directory but excluding any unsupported/excluded directories.
- * */
+ *
+ * Details: On Windows and in NTFS capture mode, a reparse point
+ * counts as a directory if and only if it has
+ * FILE_ATTRIBUTE_DIRECTORY set. Otherwise, a symbolic link
+ * counts as a directory if and only if when fully dereferenced
+ * it points to an accessible directory. If a file has multiple
+ * names (hard links), it is only counted one time. */
uint64_t num_dirs_scanned;
/** Number of non-directories scanned so far, excluding any
- * unsupported/excluded files. */
+ * unsupported/excluded files.
+ *
+ * Details: On Windows and in NTFS capture mode, a reparse point
+ * counts as a non-directory if and only if it does not have
+ * FILE_ATTRIBUTE_DIRECTORY set. Otherwise, a symbolic link
+ * counts as a non-directory if and only if when fully
+ * dereferenced it points to a non-directory or its target is
+ * inaccessible. If a file has multiple names (hard links), it
+ * is only counted one time. */
uint64_t num_nondirs_scanned;
/** Number of bytes of file data that have been detected so far.
- * This data may not actually have been read yet, and it will
- * not actually be written to the WIM file until wimlib_write()
- * or wimlib_overwrite() has been called. */
+ *
+ * Details: This data may not actually have been read yet, and
+ * it will not actually be written to the WIM file until
+ * wimlib_write() or wimlib_overwrite() has been called. Data
+ * from excluded files is not counted. This number includes
+ * default file contents as well as named data streams and
+ * reparse point data. The size of reparse point data is
+ * tallied after any reparse-point fixups, and in the case of
+ * capturing a symbolic link on a UNIX-like system, the creation
+ * of the reparse point data itself. If a file has multiple
+ * names (hard links), its size(s) are only counted one time.
+ * On Windows, encrypted files have their encrypted size
+ * counted, not their unencrypted size; however, compressed
+ * files have their uncompressed size counted. */
uint64_t num_bytes_scanned;
} scan;
- /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
+ /** Valid on messages
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN,
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_BEGIN,
* ::WIMLIB_PROGRESS_MSG_EXTRACT_DIR_STRUCTURE_END,
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, and
- * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END. */
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS,
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END,
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END, and
+ * ::WIMLIB_PROGRESS_MSG_APPLY_TIMESTAMPS.
+ *
+ * Note: most of the time of an extraction operation will be spent
+ * extracting streams, and the application will receive
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS during this time. Using @p
+ * completed_bytes and @p total_bytes, the application can calculate a
+ * percentage complete. However, note that this message does not, in
+ * general, actually provide information about which "file" is currently
+ * being extracted. This is because wimlib, by default, extracts the
+ * individual data streams in whichever order it determines to be the
+ * most efficient. */
struct wimlib_progress_info_extract {
- /** Number of the image being extracted (1-based). */
+ /** Number of the image from which files are being extracted
+ * (1-based). */
int image;
- /** Flags passed to to wimlib_extract_image() */
+ /** Extraction flags being used. */
int extract_flags;
- /** Full path to the WIM file being extracted. */
+ /** Full path to the WIM file from which files are being
+ * extracted, or @c NULL if the WIMStruct has no associated
+ * on-disk file. */
const wimlib_tchar *wimfile_name;
- /** Name of the image being extracted. */
+ /** Name of the image from which files are being extracted, or
+ * the empty string if the image is unnamed. */
const wimlib_tchar *image_name;
- /** Directory or NTFS volume to which the image is being
- * extracted. */
+ /** Path to the directory or NTFS volume to which the files are
+ * being extracted. */
const wimlib_tchar *target;
/** Reserved. */
- const wimlib_tchar *cur_path;
+ const wimlib_tchar *reserved;
/** Number of bytes of uncompressed data that will be extracted.
- * Takes into account hard links (they are not counted for each
- * link.) */
+ * If a file has multiple names (hard links), its size (or
+ * sizes, in the case of named data streams) is only counted one
+ * time. For "reparse points" and symbolic links, the size to
+ * be extracted is the size of the reparse data buffer.
+ *
+ * This number will stay constant throughout the extraction. */
uint64_t total_bytes;
- /** Number of bytes that have been written so far. Will be 0
- * initially, and equal to @p total_bytes at the end. */
+ /** Number of bytes of uncompressed data that have been
+ * extracted so far. This initially be 0 and will equal to @p
+ * total_bytes at the end of the extraction. */
uint64_t completed_bytes;
- /** Number of streams that will be extracted. This may more or
- * less than the number of "files" to be extracted due to
- * special cases (hard links, symbolic links, and alternate data
- * streams.) */
+ /** Number of (not necessarily unique) streams that will be
+ * extracted. This may be more or less than the number of
+ * "files" to be extracted due to hard links as well as
+ * potentially multiple streams per file (named data streams).
+ * A "stream" may be the default contents of a file, a named
+ * data stream, or a reparse data buffer. */
uint64_t num_streams;
- /** Path to the root dentry within the WIM for the tree that is
- * being extracted. Will be the empty string when extracting a
- * full image. */
+ /** When extracting files using wimlib_extract_files(), this
+ * will be the path within the WIM image to the file or
+ * directory tree currently being extracted. Otherwise, this
+ * will be the empty string. */
const wimlib_tchar *extract_root_wim_source_path;
/** Currently only used for
* ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */
-
unsigned part_number;
/** Currently only used for
#define WIMLIB_ADD_FLAG_DEREFERENCE 0x00000002
/** Call the progress function with the message
- * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file is starting to
- * be scanned, or when a directory or file is being excluded from capture. */
+ * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file has been
+ * scanned. */
#define WIMLIB_ADD_FLAG_VERBOSE 0x00000004
/** Mark the image being added as the bootable image of the WIM. */
/** Store the UNIX owner, group, and mode. This is done by adding a special
* alternate data stream to each regular file, symbolic link, and directory to
* contain this information. Please note that this flag is for convenience
- * only; Microsoft's @a imagex.exe will not understand this special information.
- * This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */
+ * only; Microsoft's implementation will not understand this special
+ * information. This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */
#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS capture
- * mode, or in Win32 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 Win32 native builds. The default
- * behavior without this flag is to first try omitting the SACL from the
+ * 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
#define WIMLIB_EXTRACT_FLAG_FILE_ORDER 0x00020000
/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the
- * paths in the WIM as case-insensitive globs which may contain the characters
- * '?' and '*'. The '?' character matches any character, whereas the '*'
- * character matches zero or more characters in the same path component. */
+ * paths in the WIM as "glob" patterns which may contain the wildcard characters
+ * '?' and '*'. The '?' character matches any character except a path
+ * separator, whereas the '*' character matches zero or more non-path-separator
+ * characters. Each glob pattern may match zero or more paths in the WIM file.
+ * If a glob pattern ends in a path separator, it will only match directories
+ * (including reparse points with FILE_ATTRIBUTE_DIRECTORY set). By default, if
+ * a glob pattern does not match any files, a warning but not an error will be
+ * issued, even if the glob pattern 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
-/** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes the globbing to
- * be performed case insensitively. On Windows this is already the default
- * behavior but on UNIX-like systems it is not. */
-#define WIMLIB_EXTRACT_FLAG_CASE_INSENSITIVE_GLOB 0x00100000
-
/** @} */
/** @ingroup G_mounting_wim_images
* @{ */
*/
#define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008
+/** Default to interpreting WIM paths case sensitively (default on UNIX-like
+ * systems). */
+#define WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE 0x00000010
+
+/** Default to interpreting WIM paths case insensitively (default on Windows).
+ * This does not apply to mounted images. */
+#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020
+
/** @} */
/** @ingroup G_nonstandalone_wims
* @{ */
/**
* Similar to wimlib_extract_paths(), but the paths to extract from the WIM
- * image specified in the UTF-8 text file @p path_list_file which itself
- * contains the list of paths to use, one per line. Leading and trailing
+ * image specified in the UTF-8 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_files(), but the files or directories to extract
- * from the WIM image are specified as an array of paths. Each path will be
- * extracted to a corresponding location in @p target based on its location in
- * the WIM image.
+ * from the WIM image are specified as an array of paths.
+ *
+ * Each path will be extracted to a corresponding subdirectory of the @p target
+ * based on its location in the WIM image. For example, if one of the paths to
+ * extract is "/Windows/explorer.exe" and the target is "outdir", the file will
+ * be extracted to "outdir/Windows/explorer.exe". Each path to extract must be
+ * specified as the absolute path to a directory within the WIM image.
+ * Separators in the paths to extract may be either forwards or backwards
+ * slashes, and leading path separators are optional. Symbolic links are not
+ * dereferenced when interpreting paths to extract. Paths to extract will be
+ * interpreted either case-sensitively (UNIX default) or case-insensitively
+ * (Windows default); this can be changed by wimlib_global_init().
+ *
+ * The @p target path, on the other hand, is expected to be a native path. On
+ * UNIX-like systems it may not contain backslashes, for example.
+ *
+ * By default, if any paths to extract do not exist,
+ * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST is issued. This behavior changes if
+ * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS is specified.
*
* With ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified in @p extract_flags, this
* function additionally allows paths to be globs using the wildcard characters
* Initialization function for wimlib. Call before using any other wimlib
* function except wimlib_set_print_errors(). If not done manually, this
* function will be called automatically with @p init_flags set to
- * ::WIMLIB_INIT_FLAG_ASSUME_UTF8.
+ * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. This function does nothing if called again
+ * after it has already successfully run.
*
* @param init_flags
* Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG.
git://wimlib.net / wimlib / blobdiff