* 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.2, 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 2
#ifdef __cplusplus
extern "C" {
/** 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()
+ */
+ 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
+
#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
* ::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.
git://wimlib.net / wimlib / blobdiff