X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=d22eb5811ffab8584caa3d30db7291ad0f606319;hp=c95e7635db4f014062caf338ceac69ae9be6c431;hb=ef01d3a49d4a0e83f0fb5bd6604a1b7ebeee71a1;hpb=ce50e9190bdb770640a53a1a8d612229be65d8e7 diff --git a/include/wimlib.h b/include/wimlib.h index c95e7635..d22eb581 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -3,7 +3,7 @@ * @brief External header for wimlib. * * This file contains comments for generating documentation with Doxygen. The - * built HTML documentation can be viewed at http://wimlib.net/apidoc. Make + * built HTML documentation can be viewed at https://wimlib.net/apidoc. Make * sure to see the Modules page to make more sense of * the declarations in this header. */ @@ -11,19 +11,18 @@ /** * @mainpage * - * This is the documentation for the library interface of wimlib 1.8.2, a C + * This is the documentation for the library interface of wimlib 1.10.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 * program, please see the manual pages and also the README - * file. + * href="https://wimlib.net/git/?p=wimlib;a=blob;f=README">README file. * * @section sec_installing Installing * * @subsection UNIX * - * Download the source code from http://wimlib.net. Install the library by + * Download the source code from https://wimlib.net. Install the library by * running configure && make && sudo make install. See the README for * information about configuration options. To use wimlib in your program after * installing it, include wimlib.h and link your program with -lwim. @@ -32,30 +31,31 @@ * * Download the Windows binary distribution with the appropriate architecture * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from - * http://wimlib.net. Link your program with the libwim-15.dll file. Make sure - * to also download the source code so you can get wimlib.h, as it is not + * https://wimlib.net. Link your program with the libwim-15.dll file. Make + * sure to also download the source code so you can get wimlib.h, as it is not * included in the binary distribution. If you need to access the DLL from * other programming languages, note that the calling convention is "cdecl". * + * Note that wimlib is developed using MinGW-w64, and there may be a little work + * required if you plan to use the header and DLL with Visual Studio. + * * @section sec_examples Examples * * Several examples are located in the "examples" directory of the source - * distribution. + * distribution. Also see @ref sec_basic_wim_handling_concepts below. * * There is also the source - * code of wimlib-imagex, which is complicated but uses most + * href="https://wimlib.net/git/?p=wimlib;a=blob;f=programs/imagex.c"> + * source code of wimlib-imagex, which is complicated but uses most * capabilities of wimlib. * - * @section backwards_compatibility Backwards Compatibility + * @section backward_compatibility Backward Compatibility * - * New releases of wimlib are intended to be API/ABI compatible with old + * New releases of wimlib are intended to be backward 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. + * occurred for the v1.7.0 (libwim15) release (June 2014). Since the library is + * becoming increasingly stable, the goal is to maintain the current API/ABI for + * as long as possible unless there is a strong reason not to. * * As with any other library, applications should not rely on internal * implementation details that may be subject to change. @@ -63,40 +63,64 @@ * @section sec_basic_wim_handling_concepts Basic WIM handling concepts * * wimlib wraps up a WIM file in an opaque ::WIMStruct structure. There are - * two ways to create such a structure: wimlib_open_wim(), which opens a WIM - * file and creates a ::WIMStruct representing it, and wimlib_create_new_wim(), - * which creates a new ::WIMStruct that initially contains no images and does - * not yet have a backing on-disk file. See @ref G_creating_and_opening_wims - * for more details. - * - * A WIM file, represented by a ::WIMStruct, contains zero or more images. - * Images can be extracted (or "applied") using wimlib_extract_image(), added - * (or "captured" or "appended") using wimlib_add_image(), deleted using - * wimlib_delete_image(), exported using wimlib_export_image(), and updated or - * modified using wimlib_update_image(). However, changes made to a WIM - * represented by a ::WIMStruct have no persistent effect until the WIM is - * actually written to an on-disk file. This can be done using wimlib_write(), - * but if the WIM was originally opened using wimlib_open_wim(), then - * wimlib_overwrite() can be used instead. See @ref G_extracting_wims, @ref - * G_modifying_wims, and @ref G_writing_and_overwriting_wims for more details. - * - * Note that with this ::WIMStruct abstraction, performing many tasks on WIM - * files is a multi-step process. For example, to add, or "append" an image to - * an existing stand-alone WIM file in a way similar to wimlib-imagex - * append, you must call the following functions: + * two ways to create such a structure: + * + * 1. wimlib_open_wim() opens an on-disk WIM file and creates a ::WIMStruct for + * it. + * 2. wimlib_create_new_wim() creates a new ::WIMStruct that initially contains + * no images and does not yet have a backing on-disk file. + * + * A ::WIMStruct contains zero or more independent directory trees called @a + * images. Images may be extracted, added, deleted, exported, and updated using + * various API functions. (See @ref G_extracting_wims and @ref G_modifying_wims + * for more details.) + * + * Changes made to a WIM represented by a ::WIMStruct have no persistent effect + * until the WIM is actually written to an on-disk file. This can be done using + * wimlib_write(), but if the WIM was originally opened using wimlib_open_wim(), + * then wimlib_overwrite() can be used instead. (See @ref + * G_writing_and_overwriting_wims for more details.) + * + * wimlib's API is designed to let you combine functions to accomplish tasks in + * a flexible way. Here are some example sequences of function calls: + * + * Apply an image from a WIM file, similar to the command-line program + * wimapply: * * 1. wimlib_open_wim() + * 2. wimlib_extract_image() + * + * Capture an image into a new WIM file, similar to wimcapture: + * + * 1. wimlib_create_new_wim() * 2. wimlib_add_image() + * 3. wimlib_write() + * + * Append an image to an existing WIM file, similar to wimappend: + * + * 1. wimlib_open_wim() + * 2. wimlib_add_image() + * 3. wimlib_overwrite() + * + * Delete an image from an existing WIM file, similar to wimdelete: + * + * 1. wimlib_open_wim() + * 2. wimlib_delete_image() * 3. wimlib_overwrite() * - * This design is very much on purpose as it makes the library more useful in - * general by allowing functions to be composed in different ways. For example, - * you can make multiple changes to a WIM and commit them all to the backing - * file in only one overwrite operation, which is more efficient. + * Export an image from one WIM file to another, similar to wimexport: + * + * 1. wimlib_open_wim() (on source) + * 2. wimlib_open_wim() (on destination) + * 3. wimlib_export_image() + * 4. wimlib_overwrite() (on destination) * - * Note: before calling any other function declared in wimlib.h, - * wimlib_global_init() can (and in some cases, must) be called. See its - * documentation for more details. + * The API also lets you do things the command-line tools don't directly allow. + * For example, you could make multiple changes to a WIM before efficiently + * committing the changes with just one call to wimlib_overwrite(). Perhaps you + * want to both delete an image and add a new one; or perhaps you want to + * customize an image with wimlib_update_image() after adding it. All these use + * cases are supported by the API. * * @section sec_cleaning_up Cleaning up * @@ -110,27 +134,28 @@ * Most functions in wimlib return 0 on success and a positive * ::wimlib_error_code value on failure. Use wimlib_get_error_string() to get a * string that describes an error code. wimlib also can print error messages to - * standard error itself when an error happens, and these may be more + * standard error or a custom file when an error occurs, and these may be more * informative than the error code; to enable this, call * wimlib_set_print_errors(). Please note that this is for convenience only, * and some errors can occur without a message being printed. Currently, error * messages and strings (as well as all documentation, for that matter) are only * available in English. * - * @section sec_encodings Locales and character encodings + * @section sec_encodings Character encoding * * To support Windows as well as UNIX-like systems, wimlib's API typically takes - * and returns strings of ::wimlib_tchar, which are in a platform-dependent - * encoding. + * and returns strings of ::wimlib_tchar which have a platform-dependent type + * and encoding. * - * On Windows, each ::wimlib_tchar is 2 bytes and is the same as a "wchar_t", - * and the encoding is UTF-16LE. + * On Windows, each ::wimlib_tchar is a 2-byte wchar_t. The encoding + * is meant to be UTF-16LE. However, unpaired surrogates are permitted because + * neither Windows nor the NTFS filesystem forbids them in filenames. * - * On UNIX-like systems, each ::wimlib_tchar is 1 byte and is simply a "char", - * and the encoding is the locale-dependent multibyte encoding. I recommend you - * set your locale to a UTF-8 capable locale to avoid any issues. Also, by - * default, wimlib on UNIX will assume the locale is UTF-8 capable unless you - * call wimlib_global_init() after having set your desired locale. + * On UNIX-like systems, each ::wimlib_tchar is a 1 byte char. The + * encoding is meant to be UTF-8. However, for compatibility with Windows-style + * filenames that are not valid UTF-16LE, surrogate codepoints are permitted. + * Other multibyte encodings (e.g. ISO-8859-1) or garbage sequences of bytes are + * not permitted. * * @section sec_advanced Additional information and features * @@ -159,8 +184,8 @@ * s using a seekable file descriptor using the regular function calls (e.g. * wimlib_open_wim(), wimlib_extract_image()). * - * See the documentation for the --pipable flag of wimlib-imagex - * capture for more information about pipable WIMs. + * See the documentation for the --pipable flag of wimcapture for + * more information about pipable WIMs. * * @subsection subsec_thread_safety Thread Safety * @@ -242,7 +267,7 @@ * wimlib_add_image_multisource() do internally.) * * Note that some details of how image addition/capture works are documented - * more fully in the documentation for wimlib-imagex capture. + * more fully in the documentation for wimcapture. * * @section sec_deleting_images Deleting WIM images * @@ -259,9 +284,7 @@ * * wimlib_update_image() can add, delete, and rename files in a WIM image. * - * wimlib_set_image_name(), wimlib_set_image_descripton(), - * wimlib_set_image_flags(), and wimlib_set_image_property() can change other - * image metadata. + * wimlib_set_image_property() can change other image metadata. * * wimlib_set_wim_info() can change information about the WIM file itself, such * as the boot index. @@ -286,8 +309,7 @@ * over a pipe; see @ref subsec_pipable_wims. * * Some details of how WIM extraction works are described more fully in the - * documentation for wimlib-imagex apply and wimlib-imagex - * extract. + * documentation for wimapply and wimextract. */ /** @defgroup G_mounting_wim_images Mounting WIM images @@ -324,10 +346,10 @@ * such as wimlib_join(), also take the progress function directly using an * extended version of the function, such as wimlib_join_with_progress(). * - * In wimlib v1.7.0 and later, progress functions are no longer just - * unidirectional. You can now return ::WIMLIB_PROGRESS_STATUS_ABORT to cause - * the current operation to be aborted. wimlib v1.7.0 also added the third - * argument to ::wimlib_progress_func_t, which is a user-supplied context. + * Since wimlib v1.7.0, progress functions are no longer just unidirectional. + * You can now return ::WIMLIB_PROGRESS_STATUS_ABORT to cause the current + * operation to be aborted. wimlib v1.7.0 also added the third argument to + * ::wimlib_progress_func_t, which is a user-supplied context. */ /** @defgroup G_writing_and_overwriting_wims Writing and Overwriting WIMs @@ -367,7 +389,7 @@ #include #include #include -#include +#include #include /** @addtogroup G_general @@ -377,15 +399,38 @@ #define WIMLIB_MAJOR_VERSION 1 /** Minor version of the library (for example, the 2 in 1.2.5). */ -#define WIMLIB_MINOR_VERSION 8 +#define WIMLIB_MINOR_VERSION 10 /** Patch version of the library (for example, the 5 in 1.2.5). */ -#define WIMLIB_PATCH_VERSION 2 +#define WIMLIB_PATCH_VERSION 0 #ifdef __cplusplus extern "C" { #endif +/* + * To represent file timestamps, wimlib's API uses the POSIX 'struct timespec'. + * This was probably a mistake because it doesn't play well with Visual Studio. + * In old VS versions it isn't present at all; in newer VS versions it is + * supposedly present, but I wouldn't trust it to be the same size as the one + * MinGW uses. The solution is to define a compatible structure ourselves when + * this header is included on Windows and the compiler is not MinGW. + */ +#if defined(_WIN32) && !defined(__GNUC__) +typedef struct { + /* Seconds since start of UNIX epoch (January 1, 1970) */ +#ifdef _WIN64 + int64_t tv_sec; +#else + int32_t tv_sec; +#endif + /* Nanoseconds (0-999999999) */ + int32_t tv_nsec; +} wimlib_timespec; +#else +# define wimlib_timespec struct timespec /* standard definition */ +#endif + /** * Opaque structure that represents a WIM, possibly backed by an on-disk file. * See @ref sec_basic_wim_handling_concepts for more information. @@ -395,14 +440,14 @@ typedef struct WIMStruct WIMStruct; #define WIMLIB_WIMSTRUCT_DECLARED #endif -#ifdef __WIN32__ +#ifdef _WIN32 typedef wchar_t wimlib_tchar; #else /** See @ref sec_encodings */ typedef char wimlib_tchar; #endif -#ifdef __WIN32__ +#ifdef _WIN32 /** Path separator for WIM paths passed back to progress callbacks. * This is forward slash on UNIX and backslash on Windows. */ # define WIMLIB_WIM_PATH_SEPARATOR '\\' @@ -414,7 +459,8 @@ typedef char wimlib_tchar; # define WIMLIB_WIM_PATH_SEPARATOR_STRING "/" #endif -/** Use this to specify the root directory of the WIM image. */ +/** A string containing a single path separator; use this to specify the root + * directory of a WIM image. */ #define WIMLIB_WIM_ROOT_PATH WIMLIB_WIM_PATH_SEPARATOR_STRING /** Use this to test if the specified path refers to the root directory of the @@ -503,7 +549,7 @@ enum wimlib_compression_type { * produce a better compression ratio, and work more quickly, than the * implementation in Microsoft's WIMGAPI (as of Windows 8.1). There is * limited support for non-default compression levels, but compression - * will be noticably faster if you choose a level < 35. + * will be noticeably faster if you choose a level < 35. * * If using wimlib_create_compressor() to create an LZMS compressor * directly, the @p max_block_size parameter may be any positive value @@ -644,22 +690,22 @@ enum wimlib_progress_msg { * ::WIMLIB_UPDATE_FLAG_SEND_PROGRESS. */ WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND = 22, - /** A file in the WIM image is being replaced as a result of a + /** A file in the image is being replaced as a result of a * ::wimlib_add_command without ::WIMLIB_ADD_FLAG_NO_REPLACE specified. * @p info will point to ::wimlib_progress_info.replace. This is only * received when ::WIMLIB_ADD_FLAG_VERBOSE is also specified in the add * command. */ WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM = 23, - /** A WIM image is being extracted with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, - * and a file is being extracted normally (not as a "WIMBoot pointer - * file") due to it matching a pattern in the [PrepopulateList] - * section of the configuration file + /** An image is being extracted with ::WIMLIB_EXTRACT_FLAG_WIMBOOT, and + * a file is being extracted normally (not as a "WIMBoot pointer file") + * due to it matching a pattern in the [PrepopulateList] section + * of the configuration file * /Windows/System32/WimBootCompress.ini in the WIM image. @p * info will point to ::wimlib_progress_info.wimboot_exclude. */ WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE = 24, - /** Starting to unmount a WIM image. @p info will point to + /** Starting to unmount an image. @p info will point to * ::wimlib_progress_info.unmount. */ WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25, @@ -776,7 +822,7 @@ union wimlib_progress_info { uint64_t completed_streams; /** The number of threads being used for data compression; or, - * if no compression is being peformed, this will be 1. */ + * if no compression is being performed, this will be 1. */ uint32_t num_threads; /** The compression type being used, as one of the @@ -817,11 +863,11 @@ union wimlib_progress_info { /** File is being excluded from capture due to the * capture configuration. */ - WIMLIB_SCAN_DENTRY_EXCLUDED, + WIMLIB_SCAN_DENTRY_EXCLUDED = 1, /** File is being excluded from capture due to being of * an unsupported type. */ - WIMLIB_SCAN_DENTRY_UNSUPPORTED, + WIMLIB_SCAN_DENTRY_UNSUPPORTED = 2, /** The file is an absolute symbolic link or junction * that points into the capture directory, and @@ -829,18 +875,18 @@ union wimlib_progress_info { * being adjusted. (Reparse point fixups can be * disabled with the flag ::WIMLIB_ADD_FLAG_NORPFIX.) */ - WIMLIB_SCAN_DENTRY_FIXED_SYMLINK, + WIMLIB_SCAN_DENTRY_FIXED_SYMLINK = 3, /** Reparse-point fixups are enabled, but the file is an * absolute symbolic link or junction that does * not point into the capture directory, so its * target is not being adjusted. */ - WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK, + WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK = 4, } status; union { - /** Target path in the WIM image. Only valid on - * messages ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and + /** Target path in the image. Only valid on messages + * ::WIMLIB_PROGRESS_MSG_SCAN_BEGIN and * ::WIMLIB_PROGRESS_MSG_SCAN_END. */ const wimlib_tchar *wim_target_path; @@ -856,13 +902,11 @@ union wimlib_progress_info { uint64_t num_dirs_scanned; /** The number of non-directories scanned so far, not counting - * excluded/unsupported files. If a file has multiple names - * (hard links), it is only counted one time. */ + * excluded/unsupported files. */ uint64_t num_nondirs_scanned; /** The number of bytes of file data detected so far, not - * counting excluded/unsupported files. If a file has multiple - * names (hard links), its data is counted only one time. */ + * counting excluded/unsupported files. */ uint64_t num_bytes_scanned; } scan; @@ -1042,8 +1086,8 @@ union wimlib_progress_info { /** Name of the split WIM part that is about to be started * (::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART) or has just been - * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). - * As of wimlib v1.7.0, the library user may change this when + * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). Since + * wimlib v1.7.0, the library user may change this when * receiving ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART in order to * cause the next split WIM part to be written to a different * location. */ @@ -1052,13 +1096,13 @@ union wimlib_progress_info { /** Valid on messages ::WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM */ struct wimlib_progress_info_replace { - /** Path to the file in the WIM image that is being replaced */ + /** Path to the file in the image that is being replaced */ const wimlib_tchar *path_in_wim; } replace; /** Valid on messages ::WIMLIB_PROGRESS_MSG_WIMBOOT_EXCLUDE */ struct wimlib_progress_info_wimboot_exclude { - /** Path to the file in the WIM image */ + /** Path to the file in the image */ const wimlib_tchar *path_in_wim; /** Path to which the file is being extracted */ @@ -1133,7 +1177,7 @@ union wimlib_progress_info { * 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 + * 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 @@ -1200,11 +1244,11 @@ typedef enum wimlib_progress_status * specify the sources from which to create a WIM image. */ struct wimlib_capture_source { /** Absolute or relative path to a file or directory on the external - * filesystem to be included in the WIM image. */ + * filesystem to be included in the image. */ wimlib_tchar *fs_source_path; - /** Destination path in the WIM image. Use ::WIMLIB_WIM_ROOT_PATH to - * specify the root directory of the WIM image. */ + /** Destination path in the image. To specify the root directory of the + * image, use ::WIMLIB_WIM_ROOT_PATH. */ wimlib_tchar *wim_target_path; /** Reserved; set to 0. */ @@ -1439,10 +1483,22 @@ struct wimlib_stream_entry { uint64_t reserved[4]; }; +/** + * Since wimlib v1.9.1: an object ID, which is an extra piece of metadata that + * may be associated with a file on NTFS filesystems. See: + * https://msdn.microsoft.com/en-us/library/windows/desktop/aa363997(v=vs.85).aspx + */ +struct wimlib_object_id { + uint8_t object_id[WIMLIB_GUID_LEN]; + uint8_t birth_volume_id[WIMLIB_GUID_LEN]; + uint8_t birth_object_id[WIMLIB_GUID_LEN]; + uint8_t domain_id[WIMLIB_GUID_LEN]; +}; + /** Structure passed to the wimlib_iterate_dir_tree() callback function. - * Roughly, the information about a "file" in the WIM--- but really a directory - * entry ("dentry") because hard links are allowed. The hard_link_group_id - * field can be used to distinguish actual file inodes. */ + * Roughly, the information about a "file" in the WIM image --- but really a + * directory 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 the root * directory of an image will be unnamed. */ @@ -1452,8 +1508,8 @@ struct wimlib_dir_entry { * this file has no such name. */ const wimlib_tchar *dos_name; - /** Full path to this file within the WIM image. Path separators will - * be ::WIMLIB_WIM_PATH_SEPARATOR. */ + /** Full path to this file within the 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 @@ -1465,7 +1521,7 @@ struct wimlib_dir_entry { * security descriptor. */ const char *security_descriptor; - /** Length of the above security descriptor. */ + /** Size of the above security descriptor, in bytes. */ size_t security_descriptor_size; #define WIMLIB_FILE_ATTRIBUTE_READONLY 0x00000001 @@ -1526,13 +1582,13 @@ struct wimlib_dir_entry { uint64_t hard_link_group_id; /** Time this file was created. */ - struct timespec creation_time; + wimlib_timespec creation_time; /** Time this file was last written to. */ - struct timespec last_write_time; + wimlib_timespec last_write_time; /** Time this file was last accessed. */ - struct timespec last_access_time; + wimlib_timespec last_access_time; /** The UNIX user ID of this file. This is a wimlib extension. * @@ -1557,10 +1613,14 @@ struct wimlib_dir_entry { * This field is only valid if @p unix_mode != 0. */ uint32_t unix_rdev; - uint64_t reserved[14]; + /* The object ID of this file, if any. Only valid if + * object_id.object_id is not all zeroes. */ + struct wimlib_object_id object_id; + + uint64_t reserved[6]; /** - * Array of streams that make up this file. + * Variable-length array of streams that make up this file. * * The first entry will always exist and will correspond to the unnamed * data stream (default file contents), so it will have stream_name @@ -1643,11 +1703,10 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID * (major and minor number) of each file. In addition, capture special files * such as device nodes and FIFOs. See the documentation for the - * --unix-data option to wimlib-imagex capture for more - * information. */ + * --unix-data option to wimcapture for more information. */ #define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010 -/** Do not capture security descriptors. Only has an effect in NTFS capture +/** Do not capture security descriptors. Only has an effect in NTFS-3G capture * mode, or in Windows native builds. */ #define WIMLIB_ADD_FLAG_NO_ACLS 0x00000020 @@ -1677,7 +1736,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_ADD_FLAG_NORPFIX 0x00000200 /** Do not automatically exclude unsupported files or directories from capture, - * such as encrypted files in NTFS-3g capture mode, or device files and FIFOs on + * such as encrypted files in NTFS-3G capture mode, or device files and FIFOs on * UNIX-like systems when not also using ::WIMLIB_ADD_FLAG_UNIX_DATA. Instead, * fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when such a file is encountered. */ #define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400 @@ -1721,15 +1780,19 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * * Note: ::WIMLIB_ADD_FLAG_WIMBOOT does something different from, and * independent from, ::WIMLIB_ADD_FLAG_BOOT. + * + * Since wimlib v1.8.3, ::WIMLIB_ADD_FLAG_WIMBOOT also causes offline WIM-backed + * files to be added as the "real" files rather than as their reparse points, + * provided that their data is already present in the WIM. This feature can be + * useful when updating a backing WIM file in an "offline" state. */ #define WIMLIB_ADD_FLAG_WIMBOOT 0x00001000 /** * If the add command involves adding a non-directory file to a location at - * which there already exists a nondirectory file in the WIM image, issue - * ::WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file. This only has an - * effect when updating an existing image with wimlib_update_image(). - * This was the default behavior in wimlib v1.6.2 and earlier. + * which there already exists a nondirectory file in the image, issue + * ::WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file. This was the + * default behavior before wimlib v1.7.0. */ #define WIMLIB_ADD_FLAG_NO_REPLACE 0x00002000 @@ -1742,23 +1805,27 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #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 -#define WIMLIB_ADD_IMAGE_FLAG_BOOT WIMLIB_ADD_FLAG_BOOT -#define WIMLIB_ADD_IMAGE_FLAG_UNIX_DATA WIMLIB_ADD_FLAG_UNIX_DATA -#define WIMLIB_ADD_IMAGE_FLAG_NO_ACLS WIMLIB_ADD_FLAG_NO_ACLS -#define WIMLIB_ADD_IMAGE_FLAG_STRICT_ACLS WIMLIB_ADD_FLAG_STRICT_ACLS -#define WIMLIB_ADD_IMAGE_FLAG_EXCLUDE_VERBOSE WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE -#define WIMLIB_ADD_IMAGE_FLAG_RPFIX WIMLIB_ADD_FLAG_RPFIX -#define WIMLIB_ADD_IMAGE_FLAG_NORPFIX WIMLIB_ADD_FLAG_NORPFIX -#define WIMLIB_ADD_IMAGE_FLAG_NO_UNSUPPORTED_EXCLUDE \ - WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE -#define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG WIMLIB_ADD_FLAG_WINCONFIG -#define WIMLIB_ADD_IMAGE_FLAG_WIMBOOT WIMLIB_ADD_FLAG_WIMBOOT +/** + * Since wimlib v1.9.0: create a temporary filesystem snapshot of the source + * directory and add the files from it. Currently, this option is only + * supported on Windows, where it uses the Volume Shadow Copy Service (VSS). + * Using this option, you can create a consistent backup of the system volume of + * a running Windows system without running into problems with locked files. + * For the VSS snapshot to be successfully created, your application must be run + * as an Administrator, and it cannot be run in WoW64 mode (i.e. if Windows is + * 64-bit, then your application must be 64-bit as well). + */ +#define WIMLIB_ADD_FLAG_SNAPSHOT 0x00008000 +/** + * Since wimlib v1.9.0: permit the library to discard file paths after the + * initial scan. If the application won't use + * ::WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES while writing the WIM + * archive, this flag can be used to allow the library to enable optimizations + * such as opening files by inode number rather than by path. Currently this + * only makes a difference on Windows. + */ +#define WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED 0x00010000 /** @} */ /** @addtogroup G_modifying_wims @@ -1837,22 +1904,25 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * ::WIMLIB_EXTRACT_FLAG_STRICT_ACLS. */ #define WIMLIB_EXTRACT_FLAG_NO_ACLS 0x00000040 -/** Fail immediately if the full security descriptor of any file or directory - * cannot be set exactly as specified in the WIM file. On Windows, the default +/** + * Fail immediately if the full security descriptor of any file or directory + * cannot be set exactly as specified in the WIM image. On Windows, the default * behavior without this flag when wimlib does not have permission to set the * correct security descriptor is to fall back to setting the security * descriptor with the SACL omitted, then with the DACL omitted, then with the * owner omitted, then not at all. This flag cannot be combined with - * ::WIMLIB_EXTRACT_FLAG_NO_ACLS. */ + * ::WIMLIB_EXTRACT_FLAG_NO_ACLS. + */ #define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080 -/** This is the extraction equivalent to ::WIMLIB_ADD_FLAG_RPFIX. This forces +/** + * This is the extraction equivalent to ::WIMLIB_ADD_FLAG_RPFIX. This forces * reparse-point fixups on, so absolute symbolic links or junction points will * be fixed to be absolute relative to the actual extraction root. Reparse- * point fixups are done by default for wimlib_extract_image() and * wimlib_extract_image_from_pipe() if WIM_HDR_FLAG_RP_FIX is set in the * WIM header. This flag cannot be combined with ::WIMLIB_EXTRACT_FLAG_NORPFIX. - * */ + */ #define WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100 /** Force reparse-point fixups on extraction off, regardless of the state of the @@ -1864,7 +1934,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * paths, each of which must name a regular file, to standard output. */ #define WIMLIB_EXTRACT_FLAG_TO_STDOUT 0x00000400 -/** Instead of ignoring files and directories with names that cannot be +/** + * 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. @@ -1874,10 +1945,10 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #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. +/** + * 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. * * Note: this flag is unlikely to have any effect when extracting a WIM image * that was captured on Windows. @@ -1899,10 +1970,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * only allows the Administrator to create symbolic links. */ #define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000 -/** Reserved for future use. */ -#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000 - -/** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the +/** + * For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the * paths to extract as wildcard patterns ("globs") which may contain the * wildcard characters @c ? and @c *. The @c ? character matches any * non-path-separator character, whereas the @c * character matches zero or more @@ -1913,7 +1982,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * 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 @@ -1921,49 +1990,49 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * one of the provided globs did not match a file. */ #define WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000 -/** Do not extract Windows file attributes such as readonly, hidden, etc. +/** + * Do not extract Windows file attributes such as readonly, hidden, etc. * - * This flag has an effect on Windows as well as in the NTFS-3g extraction mode. + * 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 +/** + * 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. */ + * 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. +/** + * Windows only: Extract files as "pointers" back to the WIM archive. * * The effects of this option are fairly complex. See the documentation for the - * --wimboot option of wimlib-imagex apply for more information. + * --wimboot option of wimapply for more information. */ #define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000 /** - * EXPERIMENTAL, Windows-only: compress the extracted files using System - * Compression, when possible. This only works on either Windows 10 or later, - * or on an older Windows to which Microsoft's wofadk.sys driver has been added. - * Several different compression formats may be used with System Compression; - * this particular flag selects the XPRESS compression format with 4096 byte - * chunks. This flag is currently experimental and may be changed or removed - * in future releases of wimlib. */ + * Since wimlib v1.8.2 and Windows-only: compress the extracted files using + * System Compression, when possible. This only works on either Windows 10 or + * later, or on an older Windows to which Microsoft's wofadk.sys driver has been + * added. Several different compression formats may be used with System + * Compression; this particular flag selects the XPRESS compression format with + * 4096 byte chunks. + */ #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with - * 8192 byte chunks. This flag is currently experimental and may be changed - * or removed in future releases of wimlib. */ + * 8192 byte chunks. */ #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with - * 16384 byte chunks. This flag is currently experimental and may be changed - * or removed in future releases of wimlib. */ + * 16384 byte chunks. */ #define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000 /** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with - * 32768 byte chunks. This flag is currently experimental and may be changed - * or removed in future releases of wimlib. */ + * 32768 byte chunks. */ #define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000 /** @} */ @@ -2092,9 +2161,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * Write the WIM as "pipable". After writing a WIM with this flag specified, * images from it can be applied directly from a pipe using * wimlib_extract_image_from_pipe(). See the documentation for the - * --pipable option of wimlib-imagex capture for more information. - * Beware: WIMs written with this flag will not be compatible with Microsoft's - * software. + * --pipable option of wimcapture for more information. Beware: + * WIMs written with this flag will not be compatible with Microsoft's software. * * For ::WIMStruct's created with wimlib_open_wim(), the default behavior is to * write the WIM as pipable if and only if it was pipable before. For @@ -2243,12 +2311,6 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour */ #define WIMLIB_WRITE_FLAG_SOLID 0x00001000 -/** - * Deprecated: this is the old name for ::WIMLIB_WRITE_FLAG_SOLID, retained for - * source compatibility. - */ -#define WIMLIB_WRITE_FLAG_PACK_STREAMS WIMLIB_WRITE_FLAG_SOLID - /** * Send ::WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM * file. This is only needed in the unusual case that the library user needs to @@ -2257,28 +2319,45 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES 0x00002000 /** - * Do not consider content similarily when arranging file data for solid + * Do not consider content similarity when arranging file data for solid * compression. Providing this flag will typically worsen the compression * ratio, so only provide this flag if you know what you are doing. */ #define WIMLIB_WRITE_FLAG_NO_SOLID_SORT 0x00004000 +/** + * Since wimlib v1.8.3 and for wimlib_overwrite() only: unsafely compact + * the WIM file in-place, without appending. Existing resources are shifted + * down to fill holes and new resources are appended as needed. The WIM file is + * truncated to its final size, which may shrink the on-disk file. This + * operation cannot be safely interrupted. If the operation is interrupted, + * then the WIM file will be corrupted, and it may be impossible (or at least + * very difficult) to recover any data from it. Users of this flag are expected + * to know what they are doing and assume responsibility for any data corruption + * that may result. + * + * If the WIM file cannot be compacted in-place because of its structure, its + * layout, or other requested write parameters, then wimlib_overwrite() fails + * with ::WIMLIB_ERR_COMPACTION_NOT_POSSIBLE, and the caller may wish to retry + * the operation without this flag. + */ +#define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT 0x00008000 + /** @} */ /** @addtogroup G_general * @{ */ -/** Assume that strings are represented in UTF-8, even if this is not the - * locale's character encoding. This flag is ignored on Windows, where wimlib - * always uses UTF-16LE. */ +/** Deprecated; no longer has any effect. */ #define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001 /** Windows-only: do not attempt to acquire additional privileges (currently - * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and - * SeTakeOwnershipPrivilege) when initializing the library. This flag is - * intended for the case where the calling program manages these privileges - * itself. Note: by default, no error is issued if privileges cannot be - * acquired, although related errors may be reported later, depending on if the - * operations performed actually require additional privileges or not. */ + * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, + * SeTakeOwnershipPrivilege, and SeManageVolumePrivilege) when initializing the + * library. This flag is intended for the case where the calling program + * manages these privileges itself. Note: by default, no error is issued if + * privileges cannot be acquired, although related errors may be reported later, + * depending on if the operations performed actually require additional + * privileges or not. */ #define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002 /** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, @@ -2326,15 +2405,14 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** The specific type of update to perform. */ enum wimlib_update_op { - /** Add a new file or directory tree to the WIM image in a - * certain location. */ + /** Add a new file or directory tree to the image. */ WIMLIB_UPDATE_OP_ADD = 0, - /** Delete a file or directory tree from the WIM image. */ - WIMLIB_UPDATE_OP_DELETE, + /** Delete a file or directory tree from the image. */ + WIMLIB_UPDATE_OP_DELETE = 1, - /** Rename a file or directory tree in the WIM image. */ - WIMLIB_UPDATE_OP_RENAME, + /** Rename a file or directory tree in the image. */ + WIMLIB_UPDATE_OP_RENAME = 2, }; /** Data for a ::WIMLIB_UPDATE_OP_ADD operation. */ @@ -2342,12 +2420,12 @@ struct wimlib_add_command { /** Filesystem path to the file or directory tree to add. */ wimlib_tchar *fs_source_path; - /** Destination path in the WIM image. Use ::WIMLIB_WIM_ROOT_PATH to - * specify the root directory of the WIM image. */ + /** Destination path in the image. To specify the root directory of the + * image, use ::WIMLIB_WIM_ROOT_PATH. */ wimlib_tchar *wim_target_path; - /** Path to capture configuration file to use, or @c NULL for default. - */ + /** Path to capture configuration file to use, or @c NULL if not + * specified. */ wimlib_tchar *config_file; /** Bitwise OR of WIMLIB_ADD_FLAG_* flags. */ @@ -2357,8 +2435,7 @@ struct wimlib_add_command { /** Data for a ::WIMLIB_UPDATE_OP_DELETE operation. */ struct wimlib_delete_command { - /** Path, specified from the root of the WIM image, for the file or - * directory tree within the WIM image to be deleted. */ + /** The path to the file or directory within the image to delete. */ wimlib_tchar *wim_path; /** Bitwise OR of WIMLIB_DELETE_FLAG_* flags. */ @@ -2368,12 +2445,10 @@ struct wimlib_delete_command { /** Data for a ::WIMLIB_UPDATE_OP_RENAME operation. */ struct wimlib_rename_command { - /** Path, specified from the root of the WIM image, for the source file - * or directory tree within the WIM image. */ + /** The path to the source file or directory within the image. */ wimlib_tchar *wim_source_path; - /** Path, specified from the root of the WIM image, for the destination - * file or directory tree within the WIM image. */ + /** The path to the destination file or directory within the image. */ wimlib_tchar *wim_target_path; /** Reserved; set to 0. */ @@ -2409,7 +2484,6 @@ enum wimlib_error_code { WIMLIB_ERR_DECOMPRESSION = 2, WIMLIB_ERR_FUSE = 6, WIMLIB_ERR_GLOB_HAD_NO_MATCHES = 8, - WIMLIB_ERR_ICONV_NOT_AVAILABLE = 9, WIMLIB_ERR_IMAGE_COUNT = 10, WIMLIB_ERR_IMAGE_NAME_COLLISION = 11, WIMLIB_ERR_INSUFFICIENT_PRIVILEGES = 12, @@ -2422,7 +2496,6 @@ enum wimlib_error_code { WIMLIB_ERR_INVALID_INTEGRITY_TABLE = 19, WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY = 20, WIMLIB_ERR_INVALID_METADATA_RESOURCE = 21, - WIMLIB_ERR_INVALID_MULTIBYTE_STRING = 22, WIMLIB_ERR_INVALID_OVERLAY = 23, WIMLIB_ERR_INVALID_PARAM = 24, WIMLIB_ERR_INVALID_PART_NUMBER = 25, @@ -2433,7 +2506,6 @@ enum wimlib_error_code { WIMLIB_ERR_INVALID_UTF8_STRING = 31, WIMLIB_ERR_IS_DIRECTORY = 32, WIMLIB_ERR_IS_SPLIT_WIM = 33, - WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE = 34, WIMLIB_ERR_LINK = 35, WIMLIB_ERR_METADATA_NOT_FOUND = 36, WIMLIB_ERR_MKDIR = 37, @@ -2478,12 +2550,18 @@ enum wimlib_error_code { 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, + WIMLIB_ERR_FVE_LOCKED_VOLUME = 82, WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83, + WIMLIB_ERR_WIM_IS_INCOMPLETE = 84, + WIMLIB_ERR_COMPACTION_NOT_POSSIBLE = 85, + WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES = 86, + WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87, + WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88, + WIMLIB_ERR_SNAPSHOT_FAILURE = 89, }; -/** Used to indicate no WIM image or an invalid WIM image. */ +/** Used to indicate no image or an invalid image. */ #define WIMLIB_NO_IMAGE 0 /** Used to specify all images in the WIM. */ @@ -2501,7 +2579,7 @@ enum wimlib_error_code { * automatically for it. * * After calling this function, you can use wimlib_update_image() to add files - * to the new WIM image. This gives you more control over making the new image + * to the new image. This gives you more control over making the new image * compared to calling wimlib_add_image() or wimlib_add_image_multisource(). * * @param wim @@ -2542,10 +2620,10 @@ wimlib_add_empty_image(WIMStruct *wim, * wimlib_overwrite() is called. * * @param wim - * Pointer to the ::WIMStruct to which to add the image. + * Pointer to the ::WIMStruct to which to add the image. * @param source - * A path to a directory or unmounted NTFS volume that will be captured as - * a WIM image. + * A path to a directory or unmounted NTFS volume that will be captured as + * a WIM image. * @param name * Name to give the new image. If @c NULL or empty, the new image is given * no name. If nonempty, it must specify a name that does not already @@ -2553,14 +2631,14 @@ wimlib_add_empty_image(WIMStruct *wim, * @param config_file * Path to capture configuration file, or @c NULL. This file may specify, * among other things, which files to exclude from capture. See the - * documentation for wimlib-imagex capture (--config option) - * for details of the file format. If @c NULL, the default capture - * configuration will be used. Ordinarily, the default capture - * configuration will result in no files being excluded from capture purely - * based on name; however, the ::WIMLIB_ADD_FLAG_WINCONFIG and - * ::WIMLIB_ADD_FLAG_WIMBOOT flags modify the default. + * documentation for wimcapture (--config option) for details + * of the file format. If @c NULL, the default capture configuration will + * be used. Ordinarily, the default capture configuration will result in + * no files being excluded from capture purely based on name; however, the + * ::WIMLIB_ADD_FLAG_WINCONFIG and ::WIMLIB_ADD_FLAG_WIMBOOT flags modify + * the default. * @param add_flags - * Bitwise OR of flags prefixed with WIMLIB_ADD_FLAG. + * Bitwise OR of flags prefixed with WIMLIB_ADD_FLAG. * * @return 0 on success; a ::wimlib_error_code value on failure. * @@ -2589,13 +2667,8 @@ wimlib_add_image(WIMStruct *wim, * multiple sources to be combined into a single WIM image. This is done by * specifying the @p sources and @p num_sources parameters instead of the @p * source parameter of wimlib_add_image(). The rest of the parameters are the - * same as wimlib_add_image(). See the documentation for wimlib-imagex - * capture for full details on how this mode works. - * - * In addition to the error codes that wimlib_add_image() can return, - * wimlib_add_image_multisource() can return ::WIMLIB_ERR_INVALID_OVERLAY when - * trying to overlay a non-directory on a directory or when otherwise trying to - * overlay multiple conflicting files to the same location in the WIM image. + * same as wimlib_add_image(). See the documentation for wimcapture for + * full details on how this mode works. */ extern int wimlib_add_image_multisource(WIMStruct *wim, @@ -2626,26 +2699,26 @@ wimlib_add_tree(WIMStruct *wim, int image, * an on-disk file. * * @param ctype - * The "output compression type" to assign to the ::WIMStruct. This is the - * compression type that will be used if the ::WIMStruct is later persisted - * to an on-disk file using wimlib_write(). - *
- * This choice is not necessarily final. If desired, it can still be - * changed at any time before wimlib_write() is called, using - * wimlib_set_output_compression_type(). In addition, if you wish to use a - * non-default compression chunk size, then you will need to call - * wimlib_set_output_chunk_size(). + * The "output compression type" to assign to the ::WIMStruct. This is the + * compression type that will be used if the ::WIMStruct is later persisted + * to an on-disk file using wimlib_write(). + *
+ * This choice is not necessarily final. If desired, it can still be + * changed at any time before wimlib_write() is called, using + * wimlib_set_output_compression_type(). In addition, if you wish to use a + * non-default compression chunk size, then you will need to call + * wimlib_set_output_chunk_size(). * @param wim_ret - * On success, a pointer to the new ::WIMStruct is written to the memory - * location pointed to by this parameter. This ::WIMStruct must be freed - * using using wimlib_free() when finished with it. + * On success, a pointer to the new ::WIMStruct is written to the memory + * location pointed to by this parameter. This ::WIMStruct must be freed + * using using wimlib_free() when finished with it. * * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE - * @p ctype was not a supported compression type. + * @p ctype was not a supported compression type. * @retval ::WIMLIB_ERR_NOMEM - * Insufficient memory to allocate a new ::WIMStruct. + * Insufficient memory to allocate a new ::WIMStruct. */ extern int wimlib_create_new_wim(enum wimlib_compression_type ctype, WIMStruct **wim_ret); @@ -2659,15 +2732,15 @@ wimlib_create_new_wim(enum wimlib_compression_type ctype, WIMStruct **wim_ret); * wimlib_overwrite() is called. * * @param wim - * Pointer to the ::WIMStruct from which to delete the image. + * Pointer to the ::WIMStruct from which to delete the image. * @param image - * The 1-based index of the image to delete, or ::WIMLIB_ALL_IMAGES to - * delete all images. + * The 1-based index of the image to delete, or ::WIMLIB_ALL_IMAGES to + * delete all images. * * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in the WIM. + * @p image does not exist in the WIM. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, @@ -2698,13 +2771,17 @@ wimlib_delete_path(WIMStruct *wim, int image, * * Export an image, or all images, from a ::WIMStruct into another ::WIMStruct. * - * Note: after calling this function, the exported WIM image(s) cannot be - * independently modified because the image metadata will be shared between the - * two ::WIMStruct's. In addition, @p dest_wim will depend on @p src_wim, so @p - * src_wim cannot be freed until @p dest_wim is ready to be freed as well. + * Specifically, if the destination ::WIMStruct contains n images, then + * the source image(s) will be appended, in order, starting at destination index + * n + 1. By default, all image metadata will be exported verbatim, + * but certain changes can be made by passing appropriate parameters. * - * Note: no changes are committed to disk until wimlib_write() or - * wimlib_overwrite() is called. + * wimlib_export_image() is only an in-memory operation; no changes are + * committed to disk until wimlib_write() or wimlib_overwrite() is called. + * + * A limitation of the current implementation of wimlib_export_image() is that + * the directory tree of a source or destination image cannot be updated + * following an export until one of the two images has been freed from memory. * * @param src_wim * The WIM from which to export the images, specified as a pointer to the @@ -2714,35 +2791,39 @@ wimlib_delete_path(WIMStruct *wim, int image, * referenced using wimlib_reference_resources() or * wimlib_reference_resource_files(). * @param src_image - * The 1-based index of the image from @p src_wim to export, or - * ::WIMLIB_ALL_IMAGES. + * The 1-based index of the image from @p src_wim to export, or + * ::WIMLIB_ALL_IMAGES. * @param dest_wim - * The ::WIMStruct to which to export the images. + * The ::WIMStruct to which to export the images. * @param dest_name - * For single-image exports, the name to give the exported image in @p - * dest_wim. If left @c NULL, the name from @p src_wim is used. For - * ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c NULL; in - * that case, the names are all taken from @p src_wim. This parameter is - * overridden by ::WIMLIB_EXPORT_FLAG_NO_NAMES. + * For single-image exports, the name to give the exported image in @p + * dest_wim. If left @c NULL, the name from @p src_wim is used. For + * ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c NULL; in + * that case, the names are all taken from @p src_wim. This parameter is + * overridden by ::WIMLIB_EXPORT_FLAG_NO_NAMES. * @param dest_description - * For single-image exports, the description to give the exported image in - * the new WIM file. If left @c NULL, the description from @p src_wim is - * used. For ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c - * NULL; in that case, the description are all taken from @p src_wim. This - * parameter is overridden by ::WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS. + * For single-image exports, the description to give the exported image in + * the new WIM file. If left @c NULL, the description from @p src_wim is + * used. For ::WIMLIB_ALL_IMAGES exports, this parameter must be left @c + * NULL; in that case, the description are all taken from @p src_wim. This + * parameter is overridden by ::WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS. * @param export_flags * Bitwise OR of flags prefixed with WIMLIB_EXPORT_FLAG. * * @return 0 on success; a ::wimlib_error_code value on failure. * + * @retval ::WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE + * One or more of the source images had already been exported into the + * destination WIM. * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION - * One or more of the names being given to an exported image was already in - * use in the destination WIM. + * One or more of the names being given to an exported image was already in + * use in the destination WIM. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p src_image does not exist in @p src_wim. + * @p src_image does not exist in @p src_wim. * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND - * At least one of @p src_wim and @p dest_wim do not contain image - * metadata. For example, one of them was a non-first part of a split WIM. + * At least one of @p src_wim and @p dest_wim does not contain image + * metadata; for example, one of them represents a non-first part of a + * split WIM. * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND * A file data blob that needed to be exported could not be found in the * blob lookup table of @p src_wim. See @ref G_nonstandalone_wims. @@ -2768,8 +2849,8 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * The exact behavior of how wimlib extracts files from a WIM image is * controllable by the @p extract_flags parameter, but there also are * differences depending on the platform (UNIX-like vs Windows). See the - * documentation for wimlib-imagex apply for more information, including - * about the NTFS-3g extraction mode. + * documentation for wimapply for more information, including about the + * NTFS-3G extraction mode. * * @param wim * The WIM from which to extract the image(s), specified as a pointer to the @@ -2780,7 +2861,7 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * wimlib_reference_resource_files(). * @param image * The 1-based index of the image to extract, or ::WIMLIB_ALL_IMAGES to - * extract all images. Note: ::WIMLIB_ALL_IMAGES is unsupported in NTFS-3g + * extract all images. Note: ::WIMLIB_ALL_IMAGES is unsupported in NTFS-3G * extraction mode. * @param target * A null-terminated string which names the location to which the image(s) @@ -2794,9 +2875,11 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_DECOMPRESSION - * Failed to decompress data contained in the WIM. + * The WIM file contains invalid compressed data. + * @retval ::WIMLIB_ERR_INVALID_IMAGE + * @p image does not exist in @p wim. * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE - * The metadata for one of the images to extract was invalid. + * The metadata for an image to extract was invalid. * @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 @@ -2806,10 +2889,13 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * @retval ::WIMLIB_ERR_LINK * Failed to create a symbolic link or a hard link. * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND - * The metadata resource for one of the images to extract was not found. - * This can happen if @p wim represents a non-first part of a split WIM. + * @p wim does not contain image metadata; for example, it represents a + * non-first part of a split WIM. * @retval ::WIMLIB_ERR_MKDIR * Failed create a directory. + * @retval ::WIMLIB_ERR_NTFS_3G + * libntfs-3g reported that a problem occurred while writing to the NTFS + * volume. * @retval ::WIMLIB_ERR_OPEN * Could not create a file, or failed to open an already-extracted file. * @retval ::WIMLIB_ERR_READ @@ -2858,7 +2944,7 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, * there was a problem creating WIMBoot pointer files or registering a * source WIM file with the Windows Overlay Filesystem (WOF) driver. * @retval ::WIMLIB_ERR_WRITE - * Failed to write data to a file being extracted. + * Failed to write data to a file being extracted. * * If a progress function is registered with @p wim, then as each image is * extracted it will receive ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, then @@ -2918,8 +3004,8 @@ wimlib_extract_image_from_pipe(int pipe_fd, * @ingroup G_extracting_wims * * Same as wimlib_extract_image_from_pipe(), but allows specifying a progress - * function. The progress function will be used while extracting the WIM image - * and will receive the normal extraction progress messages, such as + * function. The progress function will be used while extracting the image and + * will receive the normal extraction progress messages, such as * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, in addition to * ::WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN. */ @@ -2960,8 +3046,8 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * 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 - * the paths to extract is /Windows/explorer.exe and the target is + * the target based on its location in the 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. This behavior can be changed by * providing the flag ::WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE, which @@ -2969,8 +3055,15 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * directory --- so the same example would extract /Windows/explorer.exe * to outdir/explorer.exe. * - * Symbolic links will not be dereferenced when paths in the WIM image are - * interpreted. + * With globbing turned off (the default), paths are always checked for + * existence strictly; that is, if any path to extract does not exist in the + * image, then nothing is extracted and the function fails with + * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST. But with globbing turned on + * (::WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified), globs are by default permitted + * to match no files, and there is a flag (::WIMLIB_EXTRACT_FLAG_STRICT_GLOB) to + * enable the strict behavior if desired. + * + * Symbolic links are not dereferenced when paths in the image are interpreted. * * @param wim * WIM from which to extract the paths, specified as a pointer to the @@ -2983,28 +3076,20 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * The 1-based index of the WIM image from which to extract the paths. * @param paths * Array of paths to extract. Each element must be the absolute path to a - * file or directory within the WIM image. Path separators may be either + * file or directory within the image. Path 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); however, the behavior can be - * configured explicitly at library initialization time by passing an + * case-insensitively (Windows default); however, the case sensitivity can + * be configured explicitly at library initialization time by passing an * appropriate flag to wimlib_global_init(). *
- * By default, the characters @c * and @c ? are interpreted literally. - * This can be changed by specifying ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p - * extract_flags. - *
- * By default, if any paths to extract do not exist, the error code - * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST is returned. This behavior changes if - * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS is specified in @p extract_flags. + * By default, "globbing" is disabled, so the characters @c * and @c ? are + * interpreted literally. This can be changed by specifying + * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p extract_flags. * @param num_paths * Number of paths specified in @p paths. * @param target - * Directory to which to extract the paths; or with - * ::WIMLIB_EXTRACT_FLAG_NTFS specified in @p extract_flags, the path to an - * unmounted NTFS volume to which to extract the paths. Unlike the @p - * paths being extracted, the @p target must be native path. On UNIX-like - * systems it may not contain backslashes, for example. + * Directory to which to extract the paths. * @param extract_flags * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG. * @@ -3013,15 +3098,12 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, * some of the error codes returned in situations specific to path-mode * extraction are documented: * - * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST - * One of the paths to extract does not exist in the WIM image. This error - * code can only be returned if ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS was not - * specified in @p extract_flags, or if both - * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS and ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB - * were specified in @p extract_flags. * @retval ::WIMLIB_ERR_NOT_A_REGULAR_FILE * ::WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified in @p extract_flags, but * one of the paths to extract did not name a regular file. + * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST + * One of the paths to extract does not exist in the image; see discussion + * above about strict vs. non-strict behavior. * * If a progress function is registered with @p wim, then it will receive * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. @@ -3054,11 +3136,14 @@ wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); /** * @ingroup G_general * - * Free all memory allocated for a WIMStruct and close all files associated with - * it. + * Release a reference to a ::WIMStruct. If the ::WIMStruct is still referenced + * by other ::WIMStruct's (e.g. following calls to wimlib_export_image() or + * wimlib_reference_resources()), then the library will free it later, when the + * last reference is released; otherwise it is freed immediately and any + * associated file descriptors are closed. * * @param wim - * Pointer to the ::WIMStruct to free. If @c NULL, no action is taken. + * Pointer to the ::WIMStruct to release. If @c NULL, no action is taken. */ extern void wimlib_free(WIMStruct *wim); @@ -3069,12 +3154,12 @@ wimlib_free(WIMStruct *wim); * Convert a ::wimlib_compression_type value into a string. * * @param ctype - * The compression type value to convert. + * The compression type value to convert. * * @return - * A statically allocated string naming the compression type, such as - * "None", "LZX", or "XPRESS". If the value was unrecognized, then - * the resulting string will be "Invalid". + * A statically allocated string naming the compression type, such as + * "None", "LZX", or "XPRESS". If the value was unrecognized, then + * the resulting string will be "Invalid". */ extern const wimlib_tchar * wimlib_get_compression_type_string(enum wimlib_compression_type ctype); @@ -3085,12 +3170,12 @@ wimlib_get_compression_type_string(enum wimlib_compression_type ctype); * Convert a wimlib error code into a string describing it. * * @param code - * An error code returned by one of wimlib's functions. + * An error code returned by one of wimlib's functions. * * @return - * Pointer to a statically allocated string describing the error code. If - * the value was unrecognized, then the resulting string will be "Unknown - * error". + * Pointer to a statically allocated string describing the error code. If + * the value was unrecognized, then the resulting string will be "Unknown + * error". */ extern const wimlib_tchar * wimlib_get_error_string(enum wimlib_error_code code); @@ -3098,19 +3183,8 @@ wimlib_get_error_string(enum wimlib_error_code code); /** * @ingroup G_wim_information * - * Get the description of the specified image. - * - * @param wim - * Pointer to the ::WIMStruct to query. This need not represent a - * standalone WIM (e.g. it could represent part of a split WIM). - * @param image - * The 1-based index of the image for which to query the description. - * - * @return - * The description of the image, or @c NULL if there is no such image, or - * @c NULL if the specified image has no description. The string may not - * remain valid after later library calls, so the caller should duplicate - * it if needed. + * Get the description of the specified image. Equivalent to + * wimlib_get_image_property(wim, image, "DESCRIPTION"). */ extern const wimlib_tchar * wimlib_get_image_description(const WIMStruct *wim, int image); @@ -3118,18 +3192,10 @@ wimlib_get_image_description(const WIMStruct *wim, int image); /** * @ingroup G_wim_information * - * Get the name of the specified image. - * - * @param wim - * Pointer to the ::WIMStruct to query. This need not represent a - * standalone WIM (e.g. it could represent part of a split WIM). - * @param image - * The 1-based index of the image for which to query the name. - * - * @return - * The name of the image, or @c NULL if there is no such image, or an empty - * string if the image is unnamed. The string may not remain valid after - * later library calls, so the caller should duplicate it if needed. + * Get the name of the specified image. Equivalent to + * wimlib_get_image_property(wim, image, "NAME"), except that + * wimlib_get_image_name() will return an empty string if the image is unnamed + * whereas wimlib_get_image_property() may return @c NULL in that case. */ extern const wimlib_tchar * wimlib_get_image_name(const WIMStruct *wim, int image); @@ -3137,9 +3203,10 @@ wimlib_get_image_name(const WIMStruct *wim, int image); /** * @ingroup G_wim_information * - * Get a per-image property from the WIM's XML document. This is an alternative - * to wimlib_get_image_name() and wimlib_get_image_descripton() which allows - * getting any simple string property. + * Since wimlib v1.8.3: get a per-image property from the WIM's XML document. + * This is an alternative to wimlib_get_image_name() and + * wimlib_get_image_description() which allows getting any simple string + * property. * * @param wim * Pointer to the ::WIMStruct for the WIM. @@ -3150,11 +3217,15 @@ wimlib_get_image_name(const WIMStruct *wim, int image); * "TOTALBYTES". The name can contain forward slashes to indicate a nested * XML element; for example, "WINDOWS/VERSION/BUILD" indicates the BUILD * element nested within the VERSION element nested within the WINDOWS - * element. The [ character is reserved for future use. + * element. Since wimlib v1.9.0, a bracketed number can be used to + * indicate one of several identically-named elements; for example, + * "WINDOWS/LANGUAGES/LANGUAGE[2]" indicates the second "LANGUAGE" element + * nested within the "WINDOWS/LANGUAGES" element. Note that element names + * are case sensitive. * * @return - * The property's value as a wimlib_tchar string, or @c NULL if there is no - * such property. The string may not remain valid after later library + * The property's value as a ::wimlib_tchar string, or @c NULL if there is + * no such property. The string may not remain valid after later library * calls, so the caller should duplicate it if needed. */ extern const wimlib_tchar * @@ -3181,8 +3252,8 @@ wimlib_get_version(void); * Get basic information about a WIM file. * * @param wim - * Pointer to the ::WIMStruct to query. This need not represent a - * standalone WIM (e.g. it could represent part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param info * A ::wimlib_wim_info structure that will be filled in with information * about the WIM file. @@ -3201,8 +3272,8 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); * in it. * * @param wim - * Pointer to the ::WIMStruct to query. This need not represent a - * standalone WIM (e.g. it could represent part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param buf_ret * On success, a pointer to an allocated buffer containing the raw UTF16-LE * XML document is written to this location. @@ -3212,12 +3283,12 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_NO_FILENAME - * @p wim is not backed by a file and therefore does not have an XML - * document. + * @p wim is not backed by a file and therefore does not have an XML + * document. * @retval ::WIMLIB_ERR_READ * Failed to read the XML document from the WIM file. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Failed to read the XML document from the WIM file. + * Failed to read the XML document from the WIM file. */ extern int wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); @@ -3227,9 +3298,8 @@ wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); * * Initialization function for wimlib. Call before using any other wimlib * function (except possibly 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. This function does nothing if called again - * after it has already successfully run. + * this function will be called automatically with a flags argument of 0. 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. @@ -3259,15 +3329,15 @@ wimlib_global_cleanup(void); * Determine if an image name is already used by some image in the WIM. * * @param wim - * Pointer to the ::WIMStruct to query. This need not represent a - * standalone WIM (e.g. it could represent part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param name - * The name to check. + * The name to check. * * @return - * @c true if there is already an image in @p wim named @p name; @c false - * if there is no image named @p name in @p wim. If @p name is @c NULL or - * the empty string, then @c false is returned. + * @c true if there is already an image in @p wim named @p name; @c false + * if there is no image named @p name in @p wim. If @p name is @c NULL or + * the empty string, then @c false is returned. */ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); @@ -3275,10 +3345,10 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); /** * @ingroup G_wim_information * - * Iterate through a file or directory tree in the WIM image. By specifying + * Iterate through a file or directory tree in a WIM image. By specifying * appropriate flags and a callback function, you can get the attributes of a - * file in the WIM image, get a directory listing, or even get a listing of the - * entire WIM image. + * file in the image, get a directory listing, or even get a listing of the + * entire image. * * @param wim * The ::WIMStruct containing the image(s) over which to iterate. This @@ -3288,7 +3358,7 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * The 1-based index of the image that contains the files or directories to * iterate over, or ::WIMLIB_ALL_IMAGES to iterate over all images. * @param path - * Path in the WIM image at which to do the iteration. + * Path in the image at which to do the iteration. * @param flags * Bitwise OR of flags prefixed with WIMLIB_ITERATE_DIR_TREE_FLAG. * @param cb @@ -3301,8 +3371,10 @@ wimlib_image_name_in_use(const WIMStruct *wim, const wimlib_tchar *name); * first nonzero value that was returned from @p cb. However, additional * ::wimlib_error_code values may be returned, including the following: * + * @retval ::WIMLIB_ERR_INVALID_IMAGE + * @p image does not exist in @p wim. * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST - * @p path does not exist in the WIM image. + * @p path does not exist in the image. * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND * ::WIMLIB_ITERATE_DIR_TREE_FLAG_RESOURCES_NEEDED was specified, but the * data for some files could not be found in the blob lookup table of @p @@ -3336,7 +3408,7 @@ wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, * wimlib_reference_resource_files() or wimlib_reference_resources() * * @param wim - * Pointer to the ::WIMStruct for which to get the blob listing. + * Pointer to the ::WIMStruct for which to get the blob listing. * @param flags * Reserved; set to 0. * @param cb @@ -3359,28 +3431,28 @@ wimlib_iterate_lookup_table(WIMStruct *wim, int flags, * Join a split WIM into a stand-alone (one-part) WIM. * * @param swms - * An array of strings that gives the filenames of all parts of the split - * WIM. No specific order is required, but all parts must be included with - * no duplicates. + * An array of strings that gives the filenames of all parts of the split + * WIM. No specific order is required, but all parts must be included with + * no duplicates. * @param num_swms - * Number of filenames in @p swms. + * Number of filenames in @p swms. * @param swm_open_flags * Open flags for the split WIM parts (e.g. * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY). * @param wim_write_flags - * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will - * be used to write the joined WIM. + * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will + * be used to write the joined WIM. * @param output_path - * The path to write the joined WIM file to. + * The path to write the joined WIM file to. * * @return 0 on success; a ::wimlib_error_code value on failure. This function * may return most error codes that can be returned by wimlib_open_wim() and * wimlib_write(), as well as the following error codes: * * @retval ::WIMLIB_ERR_SPLIT_INVALID - * The split WIMs do not form a valid WIM because they do not include all - * the parts of the original WIM, there are duplicate parts, or not all the - * parts have the same GUID and compression type. + * The split WIMs do not form a valid WIM because they do not include all + * the parts of the original WIM, there are duplicate parts, or not all the + * parts have the same GUID and compression type. * * Note: wimlib is generalized enough that this function is not actually needed * to join a split WIM; instead, you could open the first part of the split WIM, @@ -3423,46 +3495,50 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, * Mount an image from a WIM file on a directory read-only or read-write. * * @param wim - * Pointer to the ::WIMStruct containing the image to be mounted. This - * ::WIMStruct must have a backing file. + * Pointer to the ::WIMStruct containing the image to be mounted. This + * ::WIMStruct must have a backing file. * @param image - * The 1-based index of the image to mount. This image cannot have been - * previously modified in memory. + * The 1-based index of the image to mount. This image cannot have been + * previously modified in memory. * @param dir - * The path to an existing empty directory on which to mount the WIM image. + * The path to an existing empty directory on which to mount the image. * @param mount_flags - * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. Use - * ::WIMLIB_MOUNT_FLAG_READWRITE to request a read-write mount instead of a - * read-only mount. + * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. Use + * ::WIMLIB_MOUNT_FLAG_READWRITE to request a read-write mount instead of a + * read-only mount. * @param staging_dir - * If non-NULL, the name of a directory in which a temporary directory for - * storing modified or added files will be created. Ignored if - * ::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 backing WIM file. The staging directory is automatically deleted - * when the image is unmounted. + * If non-NULL, the name of a directory in which a temporary directory for + * storing modified or added files will be created. Ignored if + * ::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 backing WIM file. The staging directory is automatically deleted + * when the image is unmounted. * * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_ALREADY_LOCKED - * Another process is currently modifying the WIM file. + * Another process is currently modifying the WIM file. * @retval ::WIMLIB_ERR_FUSE - * A non-zero status code was returned by @c fuse_main(). + * A non-zero status code was returned by @c fuse_main(). + * @retval ::WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES + * There are currently multiple references to the image as a result of a + * call to wimlib_export_image(). Free one before attempting the + * read-write mount. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in @p wim. + * @p image does not exist in @p wim. * @retval ::WIMLIB_ERR_INVALID_PARAM * @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 + * unrecognized flag was specified in @p mount_flags; or the image has * already been modified in memory (e.g. by wimlib_update_image()). * @retval ::WIMLIB_ERR_MKDIR - * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the - * staging directory could not be created. + * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the + * staging directory could not be created. * @retval ::WIMLIB_ERR_WIM_IS_READONLY * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but 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. * @retval ::WIMLIB_ERR_UNSUPPORTED - * Mounting is not supported in this build of the library. + * 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, @@ -3470,7 +3546,7 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, * indicate failure (for different reasons) to read the metadata resource for * the image to mount. * - * The ability to mount WIM image is implemented using FUSE (Filesystem in + * The ability to mount WIM images is implemented using FUSE (Filesystem in * UserSpacE). Depending on how FUSE is set up on your system, this function * may work as normal users in addition to the root user. * @@ -3501,65 +3577,68 @@ wimlib_mount_image(WIMStruct *wim, * Open a WIM file and create a ::WIMStruct for it. * * @param wim_file - * The path to the WIM file to open. + * The path to the WIM file to open. * @param open_flags - * Bitwise OR of flags prefixed with WIMLIB_OPEN_FLAG. + * Bitwise OR of flags prefixed with WIMLIB_OPEN_FLAG. * @param wim_ret - * On success, a pointer to a new ::WIMStruct backed by the specified - * on-disk WIM file is written to the memory location pointed to by this - * parameter. This ::WIMStruct must be freed using using wimlib_free() - * when finished with it. + * On success, a pointer to a new ::WIMStruct backed by the specified + * on-disk WIM file is written to the memory location pointed to by this + * parameter. This ::WIMStruct must be freed using using wimlib_free() + * when finished with it. * * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_IMAGE_COUNT - * The number of metadata resources found in the WIM did not match the - * image count specified in the WIM header, or the number of <IMAGE> - * elements in the XML data of the WIM did not match the image count - * specified in the WIM header. + * The number of metadata resources found in the WIM did not match the + * image count specified in the WIM header, or the number of <IMAGE> + * elements in the XML data of the WIM did not match the image count + * specified in the WIM header. * @retval ::WIMLIB_ERR_INTEGRITY - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags, and - * the WIM file failed the integrity check. + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags, and + * the WIM file failed the integrity check. * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * The library did not recognize the compression chunk size of the WIM as - * valid for its compression type. + * The library did not recognize the compression chunk size of the WIM as + * valid for its compression type. * @retval ::WIMLIB_ERR_INVALID_COMPRESSION_TYPE - * The library did not recognize the compression type of the WIM. + * The library did not recognize the compression type of the WIM. * @retval ::WIMLIB_ERR_INVALID_HEADER - * The header of the WIM was otherwise invalid. + * The header of the WIM was otherwise invalid. * @retval ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE - * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and - * the WIM contained an integrity table, but the integrity table was - * invalid. + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and + * the WIM contained an integrity table, but the integrity table was + * invalid. * @retval ::WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY - * The lookup table of the WIM was invalid. + * The lookup table of the WIM was invalid. * @retval ::WIMLIB_ERR_INVALID_PARAM * @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 WIM was a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was + * specified in @p open_flags. * @retval ::WIMLIB_ERR_NOT_A_WIM_FILE - * The file did not begin with the magic characters that identify a WIM - * file. + * The file did not begin with the magic characters that identify a WIM + * file. * @retval ::WIMLIB_ERR_OPEN - * 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. + * 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 WIM 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 WIM file. * @retval ::WIMLIB_ERR_UNKNOWN_VERSION - * The WIM version number was not recognized. (May be a pre-Vista WIM.) + * The WIM version number was not recognized. (May be a pre-Vista WIM.) * @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED * The WIM cannot be opened because it contains encrypted segments. (It * may be a Windows 8 "ESD" file.) + * @retval ::WIMLIB_ERR_WIM_IS_INCOMPLETE + * The WIM file is not complete (e.g. the program which wrote it was + * terminated before it finished) * @retval ::WIMLIB_ERR_WIM_IS_READONLY * ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was * considered read-only because of any of the reasons mentioned in the * documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. * @retval ::WIMLIB_ERR_XML - * The XML data of the WIM was invalid. + * The XML data of the WIM was invalid. */ extern int wimlib_open_wim(const wimlib_tchar *wim_file, @@ -3587,22 +3666,23 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, /** * @ingroup G_writing_and_overwriting_wims * - * Commit a ::WIMStruct to disk, overwriting its backing file or appending to it - * as needed. + * Commit a ::WIMStruct to disk, updating its backing file. * - * There are two alternative ways in which changes may be committed: + * There are several alternative ways in which changes may be committed: * * 1. Full rebuild: write the updated WIM to a temporary file, then rename the * temporary file to the original. * 2. Appending: append updates to the new original WIM file, then overwrite * its header such that those changes become visible to new readers. - * - * Append mode is often much faster, but it wastes some amount of space due to - * leaving "holes" in the WIM file. Because of the greater efficiency, - * wimlib_overwrite() normally defaults to append mode. However, - * ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full rebuild. - * In addition, if wimlib_delete_image() has been used on the ::WIMStruct, then - * the default mode switches to rebuild mode, and + * 3. Compaction: normally should not be used; see + * ::WIMLIB_WRITE_FLAG_UNSAFE_COMPACT for details. + * + * Append mode is often much faster than a full rebuild, but it wastes some + * amount of space due to leaving "holes" in the WIM file. Because of the + * greater efficiency, wimlib_overwrite() normally defaults to append mode. + * However, ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full + * rebuild. In addition, if wimlib_delete_image() has been used on the + * ::WIMStruct, then the default mode switches to rebuild mode, and * ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append * mode. * @@ -3612,26 +3692,26 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, * it. * * @param wim - * Pointer to a ::WIMStruct to commit to its backing file. + * Pointer to a ::WIMStruct to commit to its backing file. * @param write_flags - * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. + * Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. * @param num_threads - * The number of threads to use for compressing data, or 0 to have the - * library automatically choose an appropriate number. + * The number of threads to use for compressing data, or 0 to have the + * library automatically choose an appropriate number. * * @return 0 on success; a ::wimlib_error_code value on failure. This function * may return most error codes returned by wimlib_write() as well as the * following error codes: * * @retval ::WIMLIB_ERR_ALREADY_LOCKED - * Another process is currently modifying the WIM file. + * Another process is currently modifying the WIM file. * @retval ::WIMLIB_ERR_NO_FILENAME - * @p wim is not backed by an on-disk file. In other words, it is a - * ::WIMStruct created by wimlib_create_new_wim() rather than - * wimlib_open_wim(). + * @p wim is not backed by an on-disk file. In other words, it is a + * ::WIMStruct created by wimlib_create_new_wim() rather than + * wimlib_open_wim(). * @retval ::WIMLIB_ERR_RENAME - * The temporary file to which the WIM was written could not be renamed to - * the original file. + * The temporary file to which the WIM was written could not be renamed to + * the original file. * @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 @@ -3648,18 +3728,22 @@ wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads); /** * @ingroup G_wim_information * - * Print information about one image, or all images, contained in a WIM. + * (Deprecated) Print information about one image, or all images, contained in a + * WIM. * * @param wim - * Pointer to the ::WIMStruct to query. This need not represent a - * standalone WIM (e.g. it could represent part of a split WIM). + * Pointer to the ::WIMStruct to query. This need not represent a + * standalone WIM (e.g. it could represent part of a split WIM). * @param image - * The 1-based index of the image for which to print information, or - * ::WIMLIB_ALL_IMAGES to print information about all images. + * The 1-based index of the image for which to print information, or + * ::WIMLIB_ALL_IMAGES to print information about all images. * * @return This function has no return value. No error checking is done when * printing the information. If @p image is invalid, an error message is * printed. + * + * This function is deprecated; use wimlib_get_xml_data() or + * wimlib_get_image_property() to query image information instead. */ extern void wimlib_print_available_images(const WIMStruct *wim, int image); @@ -3738,11 +3822,7 @@ wimlib_reference_resource_files(WIMStruct *wim, * @param ref_flags * Reserved; must be 0. * - * @return 0 on success; a ::wimlib_error_code value on failure. On success, - * the ::WIMStruct's of the @p resource_wims are referenced internally by @p wim - * and must not be freed with wimlib_free() or overwritten with - * wimlib_overwrite() until @p wim has been freed with wimlib_free(), or - * immediately before freeing @p wim with wimlib_free(). + * @return 0 on success; a ::wimlib_error_code value on failure. */ extern int wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, @@ -3796,12 +3876,13 @@ wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims, * @p new_image does not exist in @p wim or @p template_image does not * exist in @p template_wim. * @retval ::WIMLIB_ERR_METADATA_NOT_FOUND - * The specified ::WIMStruct did not actually contain the metadata resource - * for the new or template image; for example, it was a non-first part of a + * At least one of @p wim and @p template_wim does not contain image + * metadata; for example, one of them represents a non-first part of a * split WIM. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p new_image was equal to @p template_image, or @p new_image specified - * an image that had not been modified since opening the WIM. + * Identical values were provided for the template and new image; or @p + * new_image specified an image that had not been modified since opening + * the WIM. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, @@ -3854,28 +3935,28 @@ wimlib_rename_path(WIMStruct *wim, int image, * the number of the image. The images are numbered starting at 1. * * @param wim - * Pointer to the ::WIMStruct for a WIM. + * Pointer to the ::WIMStruct for a WIM. * @param image_name_or_num - * A string specifying the name or number of an image in the WIM. If it - * parses to a positive integer, this integer is taken to specify the - * number of the image, indexed starting at 1. Otherwise, it is taken to - * be the name of an image, as given in the XML data for the WIM file. It - * also may be the keyword "all" or the string "*", both of which will - * resolve to ::WIMLIB_ALL_IMAGES. - *

- * There is no way to search for an image actually named "all", "*", or an - * integer number, or an image that has no name. However, you can use - * wimlib_get_image_name() to get the name of any image. + * A string specifying the name or number of an image in the WIM. If it + * parses to a positive integer, this integer is taken to specify the + * number of the image, indexed starting at 1. Otherwise, it is taken to + * be the name of an image, as given in the XML data for the WIM file. It + * also may be the keyword "all" or the string "*", both of which will + * resolve to ::WIMLIB_ALL_IMAGES. + *

+ * There is no way to search for an image actually named "all", "*", or an + * integer number, or an image that has no name. However, you can use + * wimlib_get_image_name() to get the name of any image. * * @return - * If the string resolved to a single existing image, the number of that - * image, indexed starting at 1, is returned. If the keyword "all" or "*" - * was specified, ::WIMLIB_ALL_IMAGES is returned. Otherwise, - * ::WIMLIB_NO_IMAGE is returned. If @p image_name_or_num was @c NULL or - * the empty string, ::WIMLIB_NO_IMAGE is returned, even if one or more - * images in @p wim has no name. (Since a WIM may have multiple unnamed - * images, an unnamed image must be specified by index to eliminate the - * ambiguity.) + * If the string resolved to a single existing image, the number of that + * image, indexed starting at 1, is returned. If the keyword "all" or "*" + * was specified, ::WIMLIB_ALL_IMAGES is returned. Otherwise, + * ::WIMLIB_NO_IMAGE is returned. If @p image_name_or_num was @c NULL or + * the empty string, ::WIMLIB_NO_IMAGE is returned, even if one or more + * images in @p wim has no name. (Since a WIM may have multiple unnamed + * images, an unnamed image must be specified by index to eliminate the + * ambiguity.) */ extern int wimlib_resolve_image(WIMStruct *wim, @@ -3896,7 +3977,7 @@ wimlib_resolve_image(WIMStruct *wim, * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_UNSUPPORTED - * wimlib was compiled using the --without-error-messages option. + * wimlib was compiled using the --without-error-messages option. */ extern int wimlib_set_error_file(FILE *fp); @@ -3915,7 +3996,7 @@ wimlib_set_error_file(FILE *fp); * @retval ::WIMLIB_ERR_OPEN * The file named by @p path could not be opened for appending. * @retval ::WIMLIB_ERR_UNSUPPORTED - * wimlib was compiled using the --without-error-messages option. + * wimlib was compiled using the --without-error-messages option. */ extern int wimlib_set_error_file_by_name(const wimlib_tchar *path); @@ -3923,20 +4004,10 @@ wimlib_set_error_file_by_name(const wimlib_tchar *path); /** * @ingroup G_modifying_wims * - * Change the description of a WIM image. + * Change the description of a WIM image. Equivalent to + * wimlib_set_image_property(wim, image, "DESCRIPTION", description). * - * @param wim - * Pointer to the ::WIMStruct for the WIM. - * @param image - * The 1-based index of the image for which to change the description. - * @param description - * The new description to give the image. It may be @c NULL, which - * indicates that the image is to be given no description. - * - * @return 0 on success; a ::wimlib_error_code value on failure. - * - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in @p wim. + * Note that "description" is misspelled in the name of this function. */ extern int wimlib_set_image_descripton(WIMStruct *wim, int image, @@ -3946,20 +4017,8 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * @ingroup G_modifying_wims * * Change what is stored in the \ element in the WIM XML document - * (usually something like "Core" or "Ultimate") - * - * @param wim - * Pointer to the ::WIMStruct for the WIM. - * @param image - * The 1-based index of the image for which to change the flags. - * @param flags - * The new \ element to give the image. It may be @c NULL, which - * indicates that the image is to be given no \ element. - * - * @return 0 on success; a ::wimlib_error_code value on failure. - * - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in @p wim. + * (usually something like "Core" or "Ultimate"). Equivalent to + * wimlib_set_image_property(wim, image, "FLAGS", flags). */ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); @@ -3967,23 +4026,8 @@ wimlib_set_image_flags(WIMStruct *wim, int image, const wimlib_tchar *flags); /** * @ingroup G_modifying_wims * - * Change the name of a WIM image. - * - * @param wim - * Pointer to the ::WIMStruct for the WIM. - * @param image - * The 1-based index of the image for which to change the name. - * @param name - * New name to give the new image. If @c NULL or empty, the new image is - * given no name. Otherwise, it must specify a name that does not already - * exist in @p wim. - * - * @return 0 on success; a ::wimlib_error_code value on failure. - * - * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION - * The WIM already contains an image with the requested name. - * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image does not exist in @p wim. + * Change the name of a WIM image. Equivalent to + * wimlib_set_image_property(wim, image, "NAME", name). */ extern int wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); @@ -3991,8 +4035,8 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); /** * @ingroup G_modifying_wims * - * Add, modify, or remove a per-image property from the WIM's XML document. - * This is an alternative to wimlib_set_image_name(), + * Since wimlib v1.8.3: add, modify, or remove a per-image property from the + * WIM's XML document. This is an alternative to wimlib_set_image_name(), * wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows * manipulating any simple string property. * @@ -4003,16 +4047,27 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); * @param property_name * The name of the image property in the same format documented for * wimlib_get_image_property(). + *
+ * Note: if creating a new element using a bracketed index such as + * "WINDOWS/LANGUAGES/LANGUAGE[2]", the highest index that can be specified + * is one greater than the number of existing elements with that same name, + * excluding the index. That means that if you are adding a list of new + * elements, they must be added sequentially from the first index (1) to + * the last index (n). * @param property_value * If not NULL and not empty, the property is set to this value. * Otherwise, the property is removed from the XML document. * * @return 0 on success; a ::wimlib_error_code value on failure. * + * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION + * The user requested to set the image name (the NAME property), + * but another image in the WIM already had the requested name. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @p image does not exist in @p wim. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p property_name has an unsupported format. + * @p property_name has an unsupported format, or @p property_name included + * a bracketed index that was too high. */ extern int wimlib_set_image_property(WIMStruct *wim, int image, @@ -4033,17 +4088,17 @@ wimlib_set_image_property(WIMStruct *wim, int image, * standard memory allocation functions regardless of this setting. * * @param malloc_func - * A function equivalent to @c malloc() that wimlib will use to allocate - * memory. If @c NULL, the allocator function is set back to the default - * @c malloc() from the C library. + * A function equivalent to @c malloc() that wimlib will use to allocate + * memory. If @c NULL, the allocator function is set back to the default + * @c malloc() from the C library. * @param free_func - * A function equivalent to @c free() that wimlib will use to free memory. - * If @c NULL, the free function is set back to the default @c free() from - * the C library. + * A function equivalent to @c free() that wimlib will use to free memory. + * If @c NULL, the free function is set back to the default @c free() from + * the C library. * @param realloc_func - * A function equivalent to @c realloc() that wimlib will use to reallocate - * memory. If @c NULL, the free function is set back to the default @c - * realloc() from the C library. + * A function equivalent to @c realloc() that wimlib will use to reallocate + * memory. If @c NULL, the free function is set back to the default @c + * realloc() from the C library. * * @return 0 */ @@ -4136,13 +4191,13 @@ wimlib_set_output_pack_compression_type(WIMStruct *wim, * This can be called before wimlib_global_init(). * * @param show_messages - * @c true if messages are to be printed; @c false if messages are not to - * be printed. + * @c true if messages are to be printed; @c false if messages are not to + * be printed. * * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_UNSUPPORTED - * wimlib was compiled using the --without-error-messages option. + * wimlib was compiled using the --without-error-messages option. */ extern int wimlib_set_print_errors(bool show_messages); @@ -4153,7 +4208,7 @@ wimlib_set_print_errors(bool show_messages); * Set basic information about a WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM. + * Pointer to the ::WIMStruct for a WIM. * @param info * Pointer to a ::wimlib_wim_info structure that contains the information * to set. Only the information explicitly specified in the @p which flags @@ -4180,29 +4235,29 @@ wimlib_set_wim_info(WIMStruct *wim, const struct wimlib_wim_info *info, * Split a WIM into multiple parts. * * @param wim - * The ::WIMStruct for the WIM to split. + * The ::WIMStruct for the WIM to split. * @param swm_name - * Name of the split WIM (SWM) file to create. This will be the name of - * the first part. The other parts will, by default, have the same name - * with 2, 3, 4, ..., etc. appended before the suffix. However, the exact - * names can be customized using the progress function. + * Name of the split WIM (SWM) file to create. This will be the name of + * the first part. The other parts will, by default, have the same name + * with 2, 3, 4, ..., etc. appended before the suffix. However, the exact + * names can be customized using the progress function. * @param part_size - * The maximum size per part, in bytes. Unfortunately, it is not - * guaranteed that this will really be the maximum size per part, because - * some file resources in the WIM may be larger than this size, and the WIM - * file format provides no way to split up file resources among multiple - * WIMs. + * The maximum size per part, in bytes. Unfortunately, it is not + * guaranteed that this will really be the maximum size per part, because + * some file resources in the WIM may be larger than this size, and the WIM + * file format provides no way to split up file resources among multiple + * WIMs. * @param write_flags - * Bitwise OR of relevant flags prefixed with @c WIMLIB_WRITE_FLAG. These - * flags will be used to write each split WIM part. Specify 0 here to get - * the default behavior. + * Bitwise OR of relevant flags prefixed with @c WIMLIB_WRITE_FLAG. These + * flags will be used to write each split WIM part. Specify 0 here to get + * the default behavior. * * @return 0 on success; a ::wimlib_error_code value on failure. This function * may return most error codes that can be returned by wimlib_write() as well as * the following error codes: * * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p swm_name was not a nonempty string, or @p part_size was 0. + * @p swm_name was not a nonempty string, or @p part_size was 0. * @retval ::WIMLIB_ERR_UNSUPPORTED * The WIM contains solid resources. Splitting a WIM containing solid * resources is not supported. @@ -4241,7 +4296,7 @@ wimlib_split(WIMStruct *wim, * value if it failed verification or another error occurred. * * @retval ::WIMLIB_ERR_DECOMPRESSION - * A compressed resource could not be decompressed. + * The WIM file contains invalid compressed data. * @retval ::WIMLIB_ERR_INVALID_METADATA_RESOURCE * The metadata resource for an image is invalid. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH @@ -4265,27 +4320,27 @@ wimlib_verify_wim(WIMStruct *wim, int verify_flags); * * When unmounting a read-write mounted image, the default behavior is to * discard changes to the image. Use ::WIMLIB_UNMOUNT_FLAG_COMMIT to cause the - * WIM image to be committed. + * image to be committed. * * @param dir - * The directory the WIM image was mounted on. + * The directory on which the WIM image is mounted. * @param unmount_flags - * Bitwise OR of flags prefixed with @p WIMLIB_UNMOUNT_FLAG. + * Bitwise OR of flags prefixed with @p WIMLIB_UNMOUNT_FLAG. * * @return 0 on success; a ::wimlib_error_code value on failure. * * @retval ::WIMLIB_ERR_NOT_A_MOUNTPOINT - * There is no WIM image mounted on the specified directory. + * There is no WIM image mounted on the specified directory. * @retval ::WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY - * The read-write mounted WIM image cannot be committed because there are - * file descriptors open to it, and ::WIMLIB_UNMOUNT_FLAG_FORCE was not + * The read-write mounted image cannot be committed because there are file + * descriptors open to it, and ::WIMLIB_UNMOUNT_FLAG_FORCE was not * specified. * @retval ::WIMLIB_ERR_MQUEUE - * Could not create a POSIX message queue. + * Could not create a POSIX message queue. * @retval ::WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT - * The WIM image was mounted by a different user. + * The image was mounted by a different user. * @retval ::WIMLIB_ERR_UNSUPPORTED - * Mounting is not supported in this build of the library. + * 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 @@ -4298,8 +4353,9 @@ wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags); * @ingroup G_mounting_wim_images * * Same as wimlib_unmount_image(), but allows specifying a progress function. - * If changes are committed from a read-write mount, the progress function will - * receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages. + * The progress function will receive a ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN + * message. In addition, if changes are committed from a read-write mount, the + * progress function will receive ::WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages. */ extern int wimlib_unmount_image_with_progress(const wimlib_tchar *dir, @@ -4331,67 +4387,65 @@ wimlib_unmount_image_with_progress(const wimlib_tchar *dir, * @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_IMAGE_HAS_MULTIPLE_REFERENCES + * There are currently multiple references to the image as a result of a + * call to wimlib_export_image(). Free one before attempting the update. * @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG * The contents of a capture configuration file were invalid. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @p image did not exist in @p wim. * @retval ::WIMLIB_ERR_INVALID_OVERLAY - * Attempted to perform an add command that conflicted with previously - * existing files in the WIM when an overlay was attempted. + * An add command with ::WIMLIB_ADD_FLAG_NO_REPLACE specified attempted to + * replace an existing nondirectory file. * @retval ::WIMLIB_ERR_INVALID_PARAM - * An unknown operation type was specified in the update commands; or, both - * ::WIMLIB_ADD_FLAG_RPFIX and ::WIMLIB_ADD_FLAG_NORPFIX were specified in - * the @p add_flags for one add command; or ::WIMLIB_ADD_FLAG_RPFIX were - * specified in the @p add_flags for an add command in which @p - * wim_target_path was not the root directory of the WIM image. + * An unknown operation type was provided in the update commands; or + * unknown or incompatible flags were provided in a flags parameter; or + * there was another problem with the provided parameters. * @retval ::WIMLIB_ERR_INVALID_REPARSE_DATA - * (Windows only): While executing an add command, tried to capture a - * reparse point with invalid data. + * While executing an add command, a reparse point had invalid data. * @retval ::WIMLIB_ERR_IS_DIRECTORY - * A delete command without ::WIMLIB_DELETE_FLAG_RECURSIVE specified was - * for a WIM path that corresponded to a directory; or, a rename command - * attempted to rename a directory to a non-directory. + * An add command attempted to replace a directory with a non-directory; or + * a delete command without ::WIMLIB_DELETE_FLAG_RECURSIVE attempted to + * delete a directory; or a rename command attempted to rename a directory + * to a non-directory. * @retval ::WIMLIB_ERR_NOTDIR - * A rename command attempted to rename a directory to a non-directory; or, - * an add command was executed that attempted to set the root of the WIM - * image as a non-directory; or, a path component used as a directory in a - * rename command was not, in fact, a directory. + * An add command attempted to replace a non-directory with a directory; or + * an add command attempted to set the root of the image to a + * non-directory; or a rename command attempted to rename a directory to a + * non-directory; or a component of an image path that was used as a + * directory was not, in fact, a directory. * @retval ::WIMLIB_ERR_NOTEMPTY * A rename command attempted to rename a directory to a non-empty - * directory. + * directory; or a rename command would have created a loop. * @retval ::WIMLIB_ERR_NTFS_3G * While executing an add command with ::WIMLIB_ADD_FLAG_NTFS specified, an * error occurred while reading data from the NTFS volume using libntfs-3g. * @retval ::WIMLIB_ERR_OPEN * Failed to open a file to be captured while executing an add command. * @retval ::WIMLIB_ERR_OPENDIR - * Failed to open a directory to be captured while executing an add command. + * Failed to open a directory to be captured while executing an add + * command. * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST * A delete command without ::WIMLIB_DELETE_FLAG_FORCE specified was for a - * WIM path that did not exist; or, a rename command attempted to rename a + * WIM path that did not exist; or a rename command attempted to rename a * file that does not exist. * @retval ::WIMLIB_ERR_READ * While executing an add command, failed to read data from a file or * directory to be captured. * @retval ::WIMLIB_ERR_READLINK * While executing an add command, failed to read the target of a symbolic - * link or junction point. + * link, junction, or other reparse point. * @retval ::WIMLIB_ERR_STAT - * While executing an add command, failed to get attributes for a file or + * While executing an add command, failed to read metadata for a file or * directory. * @retval ::WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG * A capture configuration file could not be read. * @retval ::WIMLIB_ERR_UNSUPPORTED - * ::WIMLIB_ADD_FLAG_NTFS was specified in the @p add_flags for an update - * command, but wimlib was configured with the @c --without-ntfs-3g flag; - * or, the platform is Windows and either the ::WIMLIB_ADD_FLAG_UNIX_DATA - * or the ::WIMLIB_ADD_FLAG_DEREFERENCE flags were specified in the @p - * add_flags for an update command. + * A command had flags provided that are not supported on this platform or + * in this build of the library. * @retval ::WIMLIB_ERR_UNSUPPORTED_FILE - * While executing an add command, attempted to capture a file that was not - * 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. + * An add command with ::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified + * discovered a file that was not of a supported type. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, @@ -4421,40 +4475,41 @@ wimlib_update_image(WIMStruct *wim, * wimlib_split() for that. * * @param wim - * Pointer to the ::WIMStruct being persisted. + * Pointer to the ::WIMStruct being persisted. * @param path - * The path to the on-disk file to write. + * The path to the on-disk file to write. * @param image - * Normally, specify ::WIMLIB_ALL_IMAGES here. This indicates that all - * images are to be included in the new on-disk WIM file. If for some - * reason you only want to include a single image, specify the 1-based - * index of that image instead. + * Normally, specify ::WIMLIB_ALL_IMAGES here. This indicates that all + * images are to be included in the new on-disk WIM file. If for some + * reason you only want to include a single image, specify the 1-based + * index of that image instead. * @param write_flags - * Bitwise OR of flags prefixed with @c WIMLIB_WRITE_FLAG. + * Bitwise OR of flags prefixed with @c WIMLIB_WRITE_FLAG. * @param num_threads - * The number of threads to use for compressing data, or 0 to have the - * library automatically choose an appropriate number. + * The number of threads to use for compressing data, or 0 to have the + * library automatically choose an appropriate number. * * @return 0 on success; a ::wimlib_error_code value on failure. * + * @retval ::WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED + * A file that had previously been scanned for inclusion in the WIM was + * concurrently modified. * @retval ::WIMLIB_ERR_INVALID_IMAGE - * @p image did not exist in @p wim. + * @p image did not exist in @p wim. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH - * A file, stored in another WIM, which needed to be written was corrupt; - * or a file that had previously been scanned for inclusion in the WIM was - * concurrently modified. + * A file, stored in another WIM, which needed to be written was corrupt. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p path was not a nonempty string, or invalid flags were passed. + * @p path was not a nonempty string, or invalid flags were passed. * @retval ::WIMLIB_ERR_OPEN - * Failed to open the output WIM file for writing, or failed to open a file - * whose data needed to be included in the WIM. + * Failed to open the output WIM file for writing, or failed to open a file + * whose data needed to be included in the WIM. * @retval ::WIMLIB_ERR_READ - * Failed to read data that needed to be included in the WIM. + * Failed to read data that needed to be included in the WIM. * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND * A file data blob that needed to be written could not be found in the * blob lookup table of @p wim. See @ref G_nonstandalone_wims. * @retval ::WIMLIB_ERR_WRITE - * An error occurred when trying to write data to the new WIM file. + * An error occurred when trying to write data to the new WIM file. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND,