X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=include%2Fwimlib.h;h=23c53ad68bf2affac160ab0dcf995d774c798a32;hp=728d132af45f57bc0b3e80645c85905ae370cc8d;hb=19ce03addb8071555d951a965fa0bd7e3ae7224b;hpb=b5b9681794d1f5f13350e3567f6f6e74f5c779cf diff --git a/include/wimlib.h b/include/wimlib.h index 728d132a..23c53ad6 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -31,28 +31,45 @@ /** * @mainpage * - * @section sec_intro Introduction - * - * This is the documentation for the library interface of wimlib 1.6.3, a C + * This is the documentation for the library interface of wimlib 1.7.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 README file or manual pages. + * program, please see the manual pages and also the README + * file. * - * @section sec_installing_and_compiling Installing and Compiling + * @section sec_installing Installing * - * wimlib uses the GNU autotools, so, on UNIX-like systems, it should be easy to - * install with configure && make && sudo make install; however, - * please see the README for more information about installing it. + * @subsection UNIX * - * To use wimlib in your program after installing it, include wimlib.h and link - * your program with @c -lwim. + * Download the source code from http://sourceforge.net/projects/wimlib/files. + * 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. * - * As of wimlib 1.5.0, wimlib.h is also compatible with C++. + * @subsection Windows * - * 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. + * Download the Windows binary distribution with the appropriate architecture + * (i686 or x86_64 --- also called "x86" and "amd64" respectively) from http://sourceforge.net/projects/wimlib/files. + * 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". + * + * @section sec_examples Examples + * + * Several examples are located in the examples + * directory of the source distribution. + * + * There is also the + * source code of wimlib-imagex, which is complicated but uses most + * capabilities of wimlib. * * @section sec_basic_wim_handling_concepts Basic WIM handling concepts * @@ -88,6 +105,10 @@ * you can make multiple changes to a WIM and commit them all to the underlying * file in only one overwrite operation, which is more efficient. * + * 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. + * * @section sec_cleaning_up Cleaning up * * After you are done with any ::WIMStruct, you can call wimlib_free() to free @@ -301,9 +322,9 @@ * 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.6.3 and later, progress functions are no longer just + * 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.6.3 also added the third + * 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. */ @@ -312,17 +333,17 @@ * @brief Write and overwrite on-disk WIM files. * * As described in @ref sec_basic_wim_handling_concepts, these functions are - * critical to the design of the library as they allow new or modified WIMs to - * actually be written to on-disk files. Generally, wimlib_write() is the - * function you need to call to write a new WIM file, and wimlib_overwrite() is - * the function you need to call to persistently update an existing WIM file. + * fundamental to the design of the library as they allow new or modified + * ::WIMStruct's to actually be written to on-disk files. Call wimlib_write() + * to write a new WIM file, or wimlib_overwrite() to persistently update an + * existing WIM file. */ /** @defgroup G_nonstandalone_wims Creating and handling non-standalone WIMs * * @brief Create and handle non-standalone WIMs, such as split and delta WIMs. * - * Normally, ::WIMStruct represents a WIM file, but there's a bit more to it + * Normally, a ::WIMStruct represents a WIM file, but there's a bit more to it * than that. Normally, WIM files are "standalone". However, WIM files can * also be arranged in non-standalone ways, such as a set of on-disk files that * together form a single "split WIM" or "delta WIM". Such arrangements are @@ -346,26 +367,28 @@ #include #include -/** @ingroup G_general +#ifdef __GNUC__ +# define _wimlib_deprecated __attribute__((deprecated)) +#else +# define _wimlib_deprecated +#endif + +/** @addtogroup G_general * @{ */ /** Major version of the library (for example, the 1 in 1.2.5). */ #define WIMLIB_MAJOR_VERSION 1 /** Minor version of the library (for example, the 2 in 1.2.5). */ -#define WIMLIB_MINOR_VERSION 6 +#define WIMLIB_MINOR_VERSION 7 /** Patch version of the library (for example, the 5 in 1.2.5). */ -#define WIMLIB_PATCH_VERSION 3 +#define WIMLIB_PATCH_VERSION 0 #ifdef __cplusplus extern "C" { #endif -/** @} */ -/** @ingroup G_general - * @{ */ - /** * Opaque structure that represents a WIM file. This is an in-memory structure * and need not correspond to a specific on-disk file. However, a ::WIMStruct @@ -394,11 +417,13 @@ typedef char wimlib_tchar; #endif #ifdef __WIN32__ -/** Path separator for WIM paths passed back to progress callbacks. */ +/** 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 '\\' # define WIMLIB_WIM_PATH_SEPARATOR_STRING L"\\" #else -/** Path separator for WIM paths passed back to progress callbacks. */ +/** 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 '/' # define WIMLIB_WIM_PATH_SEPARATOR_STRING "/" #endif @@ -412,39 +437,54 @@ typedef char wimlib_tchar; ((path)[0] == WIMLIB_WIM_PATH_SEPARATOR && \ (path)[1] == 0) -#ifdef __GNUC__ -# define _wimlib_deprecated __attribute__((deprecated)) -#else -# define _wimlib_deprecated -#endif - +/** Length of a Globally Unique Identifier (GUID) */ #define WIMLIB_GUID_LEN 16 /** - * Specifies the compression type of a WIM file. + * Specifies a compression format. Pass one of these values to + * wimlib_create_new_wim(), wimlib_create_compressor(), or + * wimlib_create_decompressor(). + * + * A WIM file has one default compression type and chunk size. Normally, each + * resource is compressed with this compression type. However, resources may be + * stored as uncompressed. In addition, a WIM with the new version number of + * 3584, or "ESD file", might contain solid blocks with different compression + * types. */ enum wimlib_compression_type { - /** An invalid compression type. */ - WIMLIB_COMPRESSION_TYPE_INVALID = -1, - - /** The WIM does not include any compressed resources. */ + /** No compression. */ WIMLIB_COMPRESSION_TYPE_NONE = 0, - /** Compressed resources in the WIM use XPRESS compression. */ + /** The XPRESS compression format. This format combines Lempel-Ziv + * factorization with Huffman encoding. Compression and decompression + * are both fast. This format supports chunk sizes that are powers of 2 + * between 2^12 and 2^26, inclusively. */ WIMLIB_COMPRESSION_TYPE_XPRESS = 1, - /** Compressed resources in the WIM use LZX compression. */ + /** The LZX compression format. This format combines Lempel-Ziv + * factorization with Huffman encoding, but with more features and + * complexity than XPRESS. Compression is slow to somewhat fast, + * depending on the settings. Decompression is fast but slower than + * XPRESS. This format supports chunk sizes that are powers of 2 + * between 2^15 and 2^21, inclusively. Note: chunk sizes + * other than 2^15 are not compatible with the Microsoft + * implementation. */ WIMLIB_COMPRESSION_TYPE_LZX = 2, - /** Compressed resources in the WIM use LZMS compression. Note: LZMS - * compression is only compatible with wimlib v1.6.0 and later and with - * WIMGAPI Windows 8 and later (and some restrictions apply on the - * latter). */ + /** The LZMS compression format. This format combines Lempel-Ziv + * factorization with adaptive Huffman encoding and range coding. + * Compression and decompression are both fairly slow. This format + * supports chunk sizes that are powers of 2 between 2^15 and + * 2^30, inclusively. This format is best used for large chunk + * sizes. Note: LZMS compression is only compatible with wimlib v1.6.0 + * and later, WIMGAPI Windows 8 and later, and DISM Windows 8.1 and + * later. Also, chunk sizes larger than 2^26 are not compatible + * with the Microsoft implementation. */ WIMLIB_COMPRESSION_TYPE_LZMS = 3, }; /** @} */ -/** @ingroup G_progress +/** @addtogroup G_progress * @{ */ /** Possible values of the first parameter to the user-supplied @@ -571,10 +611,15 @@ enum wimlib_progress_msg { /** A WIM image is being applied 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. @info will point to ::wimlib_progress_info.wimboot_exclude. + * configuration file @c \\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 + * ::wimlib_progress_info.unmount. */ + WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN = 25, }; /** Valid return values from user-provided progress functions @@ -594,7 +639,8 @@ enum wimlib_progress_status { WIMLIB_PROGRESS_STATUS_ABORT = 1, }; -/** A pointer to this union is passed to the user-supplied +/** + * A pointer to this union is passed to the user-supplied * ::wimlib_progress_func_t progress function. One (or none) of the structures * contained in this union will be applicable for the operation * (::wimlib_progress_msg) indicated in the first argument to the progress @@ -713,12 +759,18 @@ union wimlib_progress_info { WIMLIB_SCAN_DENTRY_UNSUPPORTED, /** The file is an absolute symbolic link or junction - * point and it is being excluded from capture because - * it points outside of the capture directory and - * reparse-point fixups are enabled. (Reparse point - * fixups can be disabled by using the flag - * ::WIMLIB_ADD_FLAG_NORPFIX.) */ - WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, + * that points into the capture directory, and + * reparse-point fixups are enabled, so its target is + * being adjusted. (Reparse point fixups can be + * disabled with the flag ::WIMLIB_ADD_FLAG_NORPFIX.) + */ + WIMLIB_SCAN_DENTRY_FIXED_SYMLINK, + + /** 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, } status; union { @@ -728,9 +780,9 @@ union wimlib_progress_info { const wimlib_tchar *wim_target_path; /** For ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY and a status - * of @p WIMLIB_SCAN_DENTRY_EXCLUDED_SYMLINK, this is - * the target of the absolute symbolic link or junction - * point. */ + * of @p WIMLIB_SCAN_DENTRY_FIXED_SYMLINK or @p + * WIMLIB_SCAN_DENTRY_NOT_FIXED_SYMLINK, this is the + * target of the absolute symbolic link or junction. */ const wimlib_tchar *symlink_target; }; @@ -931,8 +983,12 @@ 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). */ - const wimlib_tchar *part_name; + * finished (::WIMLIB_PROGRESS_MSG_SPLIT_END_PART). + * As of 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. */ + wimlib_tchar *part_name; } split; /** Valid on messages ::WIMLIB_PROGRESS_MSG_REPLACE_FILE_IN_WIM */ @@ -949,6 +1005,25 @@ union wimlib_progress_info { /** Path to which the file is being extracted */ const wimlib_tchar *extraction_path; } wimboot_exclude; + + /** Valid on messages ::WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN. */ + struct wimlib_progress_info_unmount { + /** Path to directory being unmounted */ + const wimlib_tchar *mountpoint; + + /** Path to WIM file being unmounted */ + const wimlib_tchar *mounted_wim; + + /** 1-based index of image being unmounted. */ + uint32_t mounted_image; + + /** Flags that were passed to wimlib_mount_image() when the + * mountpoint was set up. */ + uint32_t mount_flags; + + /** Flags passed to wimlib_unmount_image(). */ + uint32_t unmount_flags; + } unmount; }; /** @@ -975,7 +1050,7 @@ typedef enum wimlib_progress_status void *progctx); /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** An array of these structures is passed to wimlib_add_image_multisource() to @@ -1020,8 +1095,11 @@ struct wimlib_capture_source { #define WIMLIB_CHANGE_RPFIX_FLAG 0x00000008 /** @} */ -/** @ingroup G_wim_information - * @{ */ + +/** @addtogroup G_wim_information + * { */ + +/** @{ */ /** General information about a WIM file. */ struct wimlib_wim_info { @@ -1153,7 +1231,7 @@ struct wimlib_resource_entry { uint64_t reserved[2]; }; -/** A stream of a file in the WIM. */ +/** Information about a stream of a particular file in the WIM. */ struct wimlib_stream_entry { /** Name of the stream, or NULL if the stream is unnamed. */ const wimlib_tchar *stream_name; @@ -1252,7 +1330,7 @@ struct wimlib_dir_entry { uint32_t unix_uid; uint32_t unix_gid; uint32_t unix_mode; - uint32_t unix_reserved; + uint32_t unix_rdev; uint64_t reserved[14]; @@ -1296,7 +1374,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** Directly capture an NTFS volume rather than a generic directory. This flag @@ -1317,10 +1395,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * wimlib_update_image(). */ #define WIMLIB_ADD_FLAG_BOOT 0x00000008 -/** Store the UNIX owner, group, and mode. This is done by adding a special - * alternate data stream to each regular file, symbolic link, and directory to - * contain this information. Please note that this flag is for convenience - * only; Microsoft's implementation will not understand this special +/** UNIX-like systems only: Store the UNIX owner, group, mode, and device ID + * (major and minor number) of each file. See the documentation for the + * --unix-data option to wimlib-imagex capture for more * information. */ #define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010 @@ -1344,8 +1421,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Reparse-point fixups: Modify absolute symbolic links (or junction points, * in the case of Windows) that point inside the directory being captured to * instead be absolute relative to the directory being captured, rather than the - * current root; also exclude absolute symbolic links that point outside the - * directory tree being captured. + * current root. * * Without this flag, the default is to do this if WIM_HDR_FLAG_RP_FIX is set in * the WIM header or if this is the first image being added. @@ -1424,7 +1500,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** Do not issue an error if the path to delete does not exist. */ @@ -1435,7 +1511,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_DELETE_FLAG_RECURSIVE 0x00000002 /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** @@ -1463,8 +1539,9 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * Mark each exported image as WIMBoot-compatible. * * Note: by itself, this does change the destination WIM's compression type, nor - * does it add the file \Windows\System32\WimBootCompress.ini in the WIM image. - * Before writing the destination WIM, it's recommended to do something like: + * does it add the file @c \\Windows\\System32\\WimBootCompress.ini in the WIM + * image. Before writing the destination WIM, it's recommended to do something + * like: * * \code * wimlib_set_output_compression_type(wim, WIMLIB_COMPRESSION_TYPE_XPRESS); @@ -1476,7 +1553,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_EXPORT_FLAG_WIMBOOT 0x00000010 /** @} */ -/** @ingroup G_extracting_wims +/** @addtogroup G_extracting_wims * @{ */ /** Extract the image directly to an NTFS volume rather than a generic directory. @@ -1584,7 +1661,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000 /** @} */ -/** @ingroup G_mounting_wim_images +/** @addtogroup G_mounting_wim_images * @{ */ /** Mount the WIM image read-write rather than the default of read-only. */ @@ -1593,77 +1670,90 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** Enable FUSE debugging by passing the @c -d flag to @c fuse_main().*/ #define WIMLIB_MOUNT_FLAG_DEBUG 0x00000002 -/** Do not allow accessing alternate data streams in the mounted WIM image. */ +/** Do not allow accessing named data streams in the mounted WIM image. */ #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE 0x00000004 -/** Access alternate data streams in the mounted WIM image through extended file - * attributes. This is the default mode. */ +/** Access named data streams in the mounted WIM image through extended file + * attributes named "user.X", where X is the name of a data stream. This is the + * default mode. */ #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR 0x00000008 -/** Access alternate data streams in the mounted WIM image by specifying the - * file name, a colon, then the alternate file stream name. */ +/** Access named data streams in the mounted WIM image by specifying the file + * name, a colon, then the name of the data stream. */ #define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS 0x00000010 -/** Use UNIX file owners, groups, and modes if available in the WIM (see - * ::WIMLIB_ADD_FLAG_UNIX_DATA). */ +/** Use UNIX metadata if available in the WIM image. See + * ::WIMLIB_ADD_FLAG_UNIX_DATA. */ #define WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020 -/** Allow other users to see the mounted filesystem. (this passes the @c - * allow_other option to FUSE mount) */ +/** Allow other users to see the mounted filesystem. This passes the @c + * allow_other option to the FUSE mount. */ #define WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040 /** @} */ -/** @ingroup G_creating_and_opening_wims +/** @addtogroup G_creating_and_opening_wims * @{ */ /** Verify the WIM contents against the WIM's integrity table, if present. This * causes the raw data of the WIM file, divided into 10 MB chunks, to be * checksummed and checked against the SHA1 message digests specified in the - * integrity table. ::WIMLIB_ERR_INTEGRITY is returned if there are any - * mismatches (or, ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE is returned if the - * integrity table is invalid). */ + * integrity table. If there are any mismatches, ::WIMLIB_ERR_INTEGRITY is + * issued. If the WIM file does not contain an integrity table, this flag has + * no effect. */ #define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001 -/** Issue an error if the WIM is part of a split WIM. Software can provide - * this flag for convenience if it explicitly does not want to support split - * WIMs. */ +/** Issue an error (::WIMLIB_ERR_IS_SPLIT_WIM) if the WIM is part of a split + * WIM. Software can provide this flag for convenience if it explicitly does + * not want to support split WIMs. */ #define WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT 0x00000002 -/** Check if the WIM is writable and return ::WIMLIB_ERR_WIM_IS_READONLY if it - * is not. A WIM is considered writable only if it is writable at the - * filesystem level, does not have the WIM_HDR_FLAG_READONLY flag set in its - * header, and is not part of a spanned set. It is not required to provide this - * flag before attempting to make changes to the WIM, but with this flag you get - * an error sooner rather than later. */ +/** Check if the WIM is writable and issue an error + * (::WIMLIB_ERR_WIM_IS_READONLY) if it is not. A WIM is considered writable + * only if it is writable at the filesystem level, does not have the + * WIM_HDR_FLAG_READONLY flag set in its header, and is not part of a spanned + * set. It is not required to provide this flag before attempting to make + * changes to the WIM, but with this flag you get an error sooner rather than + * later. */ #define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004 /** @} */ -/** @ingroup G_mounting_wim_images +/** @addtogroup G_mounting_wim_images * @{ */ -/** See ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */ +/** Provide ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image. + * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ #define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001 -/** Unless this flag is given, changes to a read-write mounted WIM are - * discarded. Ignored for read-only mounts. */ +/** Commit changes to the read-write mounted WIM image. + * If this flag is not specified, changes will be discarded. */ #define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002 -/** See ::WIMLIB_WRITE_FLAG_REBUILD. */ +/** Provide ::WIMLIB_WRITE_FLAG_REBUILD when committing the WIM image. + * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ #define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004 -/** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */ +/** Provide ::WIMLIB_WRITE_FLAG_RECOMPRESS when committing the WIM image. + * Ignored if ::WIMLIB_UNMOUNT_FLAG_COMMIT not also specified. */ #define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008 -/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */ -#define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010 +/** + * In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM + * image, forces all file descriptors to the open WIM image to be closed before + * committing it. + * + * Without ::WIMLIB_UNMOUNT_FLAG_COMMIT or with a read-only mounted WIM image, + * this flag has no effect. + */ +#define WIMLIB_UNMOUNT_FLAG_FORCE 0x00000010 /** In combination with ::WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted - * image, causes the modified image to be committed as a new, unnamed image - * appended to the archive. The original image will be unmodified. */ + * WIM image, causes the modified image to be committed to the WIM file as a + * new, unnamed image appended to the archive. The original image in the WIM + * file will be unmodified. */ #define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE 0x00000020 /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and @@ -1671,7 +1761,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001 /** @} */ -/** @ingroup G_writing_and_overwriting_wims +/** @addtogroup G_writing_and_overwriting_wims * @{ */ /** @@ -1694,9 +1784,10 @@ 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 - * flag of `wimlib-imagex capture' for more information. Beware: WIMs written - * with this flag will not be compatible with Microsoft's software. + * 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. * * 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 @@ -1720,8 +1811,8 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * compression ratio for the same compression type and chunk size. wimlib's LZX * compressor currently can be given different parameters in order to achieve * different balances between compression ratio and time. In its default mode - * as of v1.5.3, it usually compresses slightly better than the competing - * Microsoft implementation. + * as of v1.7.0, it usually compresses slightly better than the competing + * Microsoft implementation and is almost as fast. * * ::WIMLIB_WRITE_FLAG_RECOMPRESS can also be used in combination with * ::WIMLIB_WRITE_FLAG_PACK_STREAMS to prevent any solid blocks from being @@ -1747,7 +1838,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour /** * For wimlib_overwrite(), rebuild the entire WIM file, even if it otherwise - * could be updated merely be appending to it. + * could be updated merely by appending to it. * * When rebuilding the WIM file, stream reference counts will be recomputed, and * any streams with 0 reference count (e.g. from deleted files or images) will @@ -1828,7 +1919,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour * all streams recompressed in solid mode. * * Currently, new solid blocks will, by default, be written using LZMS - * compression with 32 MiB (33554432 byte) chunks. Use + * compression with 64 MiB (67108864 byte) chunks. Use * wimlib_set_output_pack_compression_type() and/or * wimlib_set_output_pack_chunk_size() to change this. This is independent of * the WIM's main compression type and chunk size; you can have a WIM that @@ -1846,7 +1937,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_WRITE_FLAG_PACK_STREAMS 0x00001000 /** @} */ -/** @ingroup G_general +/** @addtogroup G_general * @{ */ /** Assume that strings are represented in UTF-8, even if this is not the @@ -1886,7 +1977,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020 /** @} */ -/** @ingroup G_nonstandalone_wims +/** @addtogroup G_nonstandalone_wims * @{ */ /** For wimlib_reference_resource_files(), enable shell-style filename globbing. @@ -1903,7 +1994,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH 0x00000002 /** @} */ -/** @ingroup G_modifying_wims +/** @addtogroup G_modifying_wims * @{ */ /** The specific type of update to perform. */ @@ -1976,7 +2067,7 @@ struct wimlib_update_command { }; /** @} */ -/** @ingroup G_general +/** @addtogroup G_general * @{ */ /** @@ -1986,84 +2077,80 @@ struct wimlib_update_command { * codes can be returned by a given function, and what they mean. */ enum wimlib_error_code { - WIMLIB_ERR_SUCCESS = 0, - WIMLIB_ERR_ALREADY_LOCKED, - WIMLIB_ERR_DECOMPRESSION, - WIMLIB_ERR_DELETE_STAGING_DIR, - WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED, - WIMLIB_ERR_FORK, - WIMLIB_ERR_FUSE, - WIMLIB_ERR_FUSERMOUNT, - WIMLIB_ERR_GLOB_HAD_NO_MATCHES, - WIMLIB_ERR_ICONV_NOT_AVAILABLE, - WIMLIB_ERR_IMAGE_COUNT, - WIMLIB_ERR_IMAGE_NAME_COLLISION, - WIMLIB_ERR_INSUFFICIENT_PRIVILEGES, - WIMLIB_ERR_INTEGRITY, - WIMLIB_ERR_INVALID_CAPTURE_CONFIG, - WIMLIB_ERR_INVALID_CHUNK_SIZE, - WIMLIB_ERR_INVALID_COMPRESSION_TYPE, - WIMLIB_ERR_INVALID_HEADER, - WIMLIB_ERR_INVALID_IMAGE, - WIMLIB_ERR_INVALID_INTEGRITY_TABLE, - WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY, - WIMLIB_ERR_INVALID_METADATA_RESOURCE, - WIMLIB_ERR_INVALID_MULTIBYTE_STRING, - WIMLIB_ERR_INVALID_OVERLAY, - WIMLIB_ERR_INVALID_PARAM, - WIMLIB_ERR_INVALID_PART_NUMBER, - WIMLIB_ERR_INVALID_PIPABLE_WIM, - WIMLIB_ERR_INVALID_REPARSE_DATA, - WIMLIB_ERR_INVALID_RESOURCE_HASH, - WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE, - WIMLIB_ERR_INVALID_UTF16_STRING, - WIMLIB_ERR_INVALID_UTF8_STRING, - WIMLIB_ERR_IS_DIRECTORY, - WIMLIB_ERR_IS_SPLIT_WIM, - WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE, - WIMLIB_ERR_LINK, - WIMLIB_ERR_METADATA_NOT_FOUND, - WIMLIB_ERR_MKDIR, - WIMLIB_ERR_MQUEUE, - WIMLIB_ERR_NOMEM, - WIMLIB_ERR_NOTDIR, - WIMLIB_ERR_NOTEMPTY, - WIMLIB_ERR_NOT_A_REGULAR_FILE, - WIMLIB_ERR_NOT_A_WIM_FILE, - WIMLIB_ERR_NOT_PIPABLE, - WIMLIB_ERR_NO_FILENAME, - WIMLIB_ERR_NTFS_3G, - WIMLIB_ERR_OPEN, - WIMLIB_ERR_OPENDIR, - WIMLIB_ERR_PATH_DOES_NOT_EXIST, - WIMLIB_ERR_READ, - WIMLIB_ERR_READLINK, - WIMLIB_ERR_RENAME, - WIMLIB_ERR_REOPEN, - WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED, - WIMLIB_ERR_RESOURCE_NOT_FOUND, - WIMLIB_ERR_RESOURCE_ORDER, - WIMLIB_ERR_SET_ATTRIBUTES, - WIMLIB_ERR_SET_REPARSE_DATA, - WIMLIB_ERR_SET_SECURITY, - WIMLIB_ERR_SET_SHORT_NAME, - WIMLIB_ERR_SET_TIMESTAMPS, - WIMLIB_ERR_SPLIT_INVALID, - WIMLIB_ERR_STAT, - WIMLIB_ERR_TIMEOUT, - WIMLIB_ERR_UNEXPECTED_END_OF_FILE, - WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE, - WIMLIB_ERR_UNKNOWN_VERSION, - WIMLIB_ERR_UNSUPPORTED, - WIMLIB_ERR_UNSUPPORTED_FILE, - WIMLIB_ERR_VOLUME_LACKS_FEATURES, - WIMLIB_ERR_WIM_IS_READONLY, - WIMLIB_ERR_WRITE, - WIMLIB_ERR_XML, - WIMLIB_ERR_WIM_IS_ENCRYPTED, - WIMLIB_ERR_WIMBOOT, - WIMLIB_ERR_ABORTED_BY_PROGRESS, - WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS, + WIMLIB_ERR_SUCCESS = 0, + WIMLIB_ERR_ALREADY_LOCKED = 1, + 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, + WIMLIB_ERR_INTEGRITY = 13, + WIMLIB_ERR_INVALID_CAPTURE_CONFIG = 14, + WIMLIB_ERR_INVALID_CHUNK_SIZE = 15, + WIMLIB_ERR_INVALID_COMPRESSION_TYPE = 16, + WIMLIB_ERR_INVALID_HEADER = 17, + WIMLIB_ERR_INVALID_IMAGE = 18, + 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, + WIMLIB_ERR_INVALID_PIPABLE_WIM = 26, + WIMLIB_ERR_INVALID_REPARSE_DATA = 27, + WIMLIB_ERR_INVALID_RESOURCE_HASH = 28, + WIMLIB_ERR_INVALID_UTF16_STRING = 30, + 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, + WIMLIB_ERR_MQUEUE = 38, + WIMLIB_ERR_NOMEM = 39, + WIMLIB_ERR_NOTDIR = 40, + WIMLIB_ERR_NOTEMPTY = 41, + WIMLIB_ERR_NOT_A_REGULAR_FILE = 42, + WIMLIB_ERR_NOT_A_WIM_FILE = 43, + WIMLIB_ERR_NOT_PIPABLE = 44, + WIMLIB_ERR_NO_FILENAME = 45, + WIMLIB_ERR_NTFS_3G = 46, + WIMLIB_ERR_OPEN = 47, + WIMLIB_ERR_OPENDIR = 48, + WIMLIB_ERR_PATH_DOES_NOT_EXIST = 49, + WIMLIB_ERR_READ = 50, + WIMLIB_ERR_READLINK = 51, + WIMLIB_ERR_RENAME = 52, + WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED = 54, + WIMLIB_ERR_RESOURCE_NOT_FOUND = 55, + WIMLIB_ERR_RESOURCE_ORDER = 56, + WIMLIB_ERR_SET_ATTRIBUTES = 57, + WIMLIB_ERR_SET_REPARSE_DATA = 58, + WIMLIB_ERR_SET_SECURITY = 59, + WIMLIB_ERR_SET_SHORT_NAME = 60, + WIMLIB_ERR_SET_TIMESTAMPS = 61, + WIMLIB_ERR_SPLIT_INVALID = 62, + WIMLIB_ERR_STAT = 63, + WIMLIB_ERR_UNEXPECTED_END_OF_FILE = 65, + WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE = 66, + WIMLIB_ERR_UNKNOWN_VERSION = 67, + WIMLIB_ERR_UNSUPPORTED = 68, + WIMLIB_ERR_UNSUPPORTED_FILE = 69, + WIMLIB_ERR_WIM_IS_READONLY = 71, + WIMLIB_ERR_WRITE = 72, + WIMLIB_ERR_XML = 73, + WIMLIB_ERR_WIM_IS_ENCRYPTED = 74, + WIMLIB_ERR_WIMBOOT = 75, + WIMLIB_ERR_ABORTED_BY_PROGRESS = 76, + WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS = 77, + WIMLIB_ERR_MKNOD = 78, + WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79, + WIMLIB_ERR_NOT_A_MOUNTPOINT = 80, + WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81, }; @@ -2131,8 +2218,7 @@ wimlib_add_empty_image(WIMStruct *wim, * any) until wimlib_write() or wimlib_overwrite() is called. * * @param wim - * Pointer to the ::WIMStruct for a WIM file to which the image will be - * added. + * 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. @@ -2229,7 +2315,7 @@ wimlib_add_tree(WIMStruct *wim, int image, * ::wimlib_compression_type constants. * @param wim_ret * On success, a pointer to an opaque ::WIMStruct for the new WIM file is - * written to the memory location pointed to by this paramater. The + * written to the memory location pointed to by this parameter. The * ::WIMStruct must be freed using using wimlib_free() when finished with * it. * @return 0 on success; nonzero on error. @@ -2301,13 +2387,9 @@ wimlib_delete_path(WIMStruct *wim, int image, * * The destination image is made to share the same dentry tree and security data * structure as the source image. This places some restrictions on additional - * functions that may be called. wimlib_mount_image() may not be called on - * either the source image or the destination image without an intervening call - * to a function that un-shares the images, such as wimlib_free() on @p - * dest_wim, or wimlib_delete_image() on either the source or destination image. - * Furthermore, you may not call wimlib_free() on @p src_wim before calling - * wimlib_write() or wimlib_overwrite() on @p dest_wim because @p dest_wim will - * have references back to @p src_wim. + * functions that may be called. For example, you may not call wimlib_free() on + * @p src_wim before calling wimlib_write() or wimlib_overwrite() on @p dest_wim + * because @p dest_wim will have references back to @p src_wim. * * If this function fails, all changes to @p dest_wim are rolled back. * @@ -2565,16 +2647,16 @@ wimlib_extract_image_from_pipe_with_progress(int pipe_fd, * @ingroup G_extracting_wims * * Since wimlib v1.6.0: Similar to wimlib_extract_paths(), but the paths to - * extract from the WIM image are specified in the UTF-8 text file named by @p - * path_list_file which itself contains the list of paths to use, one per line. - * Leading and trailing whitespace, and otherwise empty lines and lines - * beginning with the ';' character are ignored. No quotes are needed as paths - * are otherwise delimited by the newline character. + * extract from the WIM image are specified in the ASCII, UTF-8, or UTF-16LE + * text file named by @p path_list_file which itself contains the list of paths + * to use, one per line. Leading and trailing whitespace, and otherwise empty + * lines and lines beginning with the ';' character are ignored. No quotes are + * needed as paths are otherwise delimited by the newline character. * * The error codes are the same as those returned by wimlib_extract_paths(), * except that wimlib_extract_pathlist() returns an appropriate error code if it - * cannot read the path list file (::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT, - * ::WIMLIB_ERR_READ, ::WIMLIB_ERR_NOMEM, or ::WIMLIB_ERR_INVALID_UTF8_STRING). + * cannot read the path list file (e.g. ::WIMLIB_ERR_OPEN, ::WIMLIB_ERR_STAT, + * ::WIMLIB_ERR_READ). */ extern int wimlib_extract_pathlist(WIMStruct *wim, int image, @@ -2676,8 +2758,8 @@ wimlib_extract_paths(WIMStruct *wim, * See wimlib_get_xml_data() to read the XML data into memory instead. * * @param wim - * Pointer to the ::WIMStruct for a WIM file, which does not necessarily - * have to be standalone (e.g. it could be 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 fp * @c stdout, or a FILE* opened for writing, to extract the data to. * @@ -2685,9 +2767,11 @@ wimlib_extract_paths(WIMStruct *wim, * @retval ::WIMLIB_ERR_INVALID_PARAM * @p wim is not a ::WIMStruct that was created by wimlib_open_wim(). * @retval ::WIMLIB_ERR_NOMEM + * Failed to allocate needed memory. * @retval ::WIMLIB_ERR_READ + * Error reading the XML data from the WIM file. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Failed to read the XML data from the WIM. + * Error reading the XML data from the WIM file. * @retval ::WIMLIB_ERR_WRITE * Failed to completely write the XML data to @p fp. */ @@ -2701,7 +2785,7 @@ wimlib_extract_xml_data(WIMStruct *wim, FILE *fp); * with it. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * Pointer to the ::WIMStruct to free. * * @return This function has no return value. */ @@ -2744,8 +2828,8 @@ wimlib_get_error_string(enum wimlib_error_code code); * Returns the description of the specified image. * * @param wim - * Pointer to the ::WIMStruct for a WIM file that does not necessarily have - * to be standalone (e.g. it could be 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 number of the image, numbered starting at 1. * @@ -2765,8 +2849,8 @@ wimlib_get_image_description(const WIMStruct *wim, int image); * Returns the name of the specified image. * * @param wim - * Pointer to the ::WIMStruct for a WIM file that does not necessarily have - * to be standalone (e.g. it could be 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 number of the image, numbered starting at 1. * @@ -2800,8 +2884,8 @@ wimlib_get_version(void); * Get basic information about a WIM file. * * @param wim - * Pointer to the ::WIMStruct for a WIM file that does not necessarily have - * to be standalone (e.g. it could be 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. @@ -2821,8 +2905,8 @@ wimlib_get_wim_info(WIMStruct *wim, struct wimlib_wim_info *info); * instead. * * @param wim - * Pointer to the ::WIMStruct for a WIM file, which does not necessarily - * have to be standalone (e.g. it could be 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 data is written to this location. @@ -2879,7 +2963,8 @@ wimlib_global_cleanup(void); * Determines if an image name is already used by some image in the WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * 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. * @@ -2962,8 +3047,8 @@ wimlib_iterate_dir_tree(WIMStruct *wim, int image, const wimlib_tchar *path, * explicitly referenced. * * @param wim - * Pointer to the ::WIMStruct for a WIM file that does not necessarily have - * to be standalone (e.g. it could be 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 flags * Reserved; set to 0. @@ -3050,82 +3135,75 @@ wimlib_join_with_progress(const wimlib_tchar * const *swms, /** * @ingroup G_mounting_wim_images * - * Mounts an image in a WIM file on a directory read-only or read-write. - * - * As this is implemented using FUSE (Filesystme in UserSpacE), this is not - * supported if wimlib was configured with @c --without-fuse. This includes - * Windows builds of wimlib; ::WIMLIB_ERR_UNSUPPORTED will be returned in such - * cases. - * - * Calling this function daemonizes the process, unless - * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early occur occurs. If the - * mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), modifications - * to the WIM are staged in a temporary directory. - * - * It is safe to mount multiple images from the same underlying WIM file - * read-only at the same time, but only if different ::WIMStruct's are used. It - * is @b not safe to mount multiple images from the same WIM file read-write at - * the same time. - * - * wimlib_mount_image() cannot be used on an image that was exported with - * wimlib_export_image() while the dentry trees for both images are still in - * memory. In addition, wimlib_mount_image() may not be used to mount an image - * that already has modifications pending (e.g. an image added with - * wimlib_add_image()). + * Mounts 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. * @param image - * The number of the image to mount, indexed starting from it. It must be - * an existing, single image. + * The 1-based index of the image to mount. * @param dir - * The path to an existing empty directory to mount the image on. + * The path to an existing empty directory on which to mount the WIM image. * @param mount_flags - * Bitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. + * 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 the staging directory 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 WIM file that @p wim was originally read from. + * 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 WIM file that @p wim was originally read from. The staging + * directory is deleted when the image is unmounted. * - * @return 0 on success; nonzero on error. + * @return 0 on success; nonzero on error. The possible error codes include: * * @retval ::WIMLIB_ERR_ALREADY_LOCKED - * A read-write mount was requested, but an exclusive advisory lock on - * the on-disk WIM file could not be acquired because another thread or - * process has mounted an image from the WIM read-write or is currently - * modifying the WIM in-place. + * An image from the WIM file is already mounted read-write, or another + * process is currently appending data to the WIM file. * @retval ::WIMLIB_ERR_FUSE - * A non-zero status was returned by @c fuse_main(). + * A non-zero status code was returned by @c fuse_main(). * @retval ::WIMLIB_ERR_INVALID_IMAGE * @p image does not specify an existing, single image in @p wim. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @p image is shared among multiple ::WIMStruct's as a result of a call to - * wimlib_export_image(), or @p image has been added with - * wimlib_add_image(). + * @p wim was @c NULL; or @p dir was NULL or the empty string; or an + * unrecognized flag was specified in @p mount_flags; or the WIM image has + * already been modified in memory (e.g. by wimlib_update_image()). * @retval ::WIMLIB_ERR_MKDIR * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but the * staging directory could not be created. - * @retval ::WIMLIB_ERR_NOTDIR - * Could not determine the current working directory. - * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND - * One of the dentries in the image referenced a stream not present in the - * WIM's lookup table (or in any of the lookup tables of the split WIM - * parts). * @retval ::WIMLIB_ERR_WIM_IS_READONLY - * ::WIMLIB_MOUNT_FLAG_READWRITE was specified in @p mount_flags, but @p - * wim is considered read-only because of any of the reasons mentioned in - * the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS flag. + * ::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, either because the platform is Windows, or - * because the platform is UNIX-like and wimlib was compiled with @c - * --without-fuse. + * because the platform is UNIX-like and wimlib was compiled using + * --without-fuse. * * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION, * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_METADATA_NOT_FOUND, * ::WIMLIB_ERR_NOMEM, ::WIMLIB_ERR_READ, or * ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for * different reasons) to read the metadata resource for the image to mount. + * + * The ability to mount WIM image 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. + * + * Mounting WIM images is not supported if wimlib was configured + * --without-fuse. This includes Windows builds of wimlib; + * ::WIMLIB_ERR_UNSUPPORTED will be returned in such cases. + * + * Calling this function daemonizes the process, unless + * ::WIMLIB_MOUNT_FLAG_DEBUG was specified or an early error occurs. + * + * It is safe to mount multiple images from the same underlying WIM file + * read-only at the same time, but only if different ::WIMStruct's are used. It + * is @b not safe to mount multiple images from the same WIM file read-write at + * the same time. + * + * To unmount the image, call wimlib_unmount_image(). This may be done in a + * different process. */ extern int wimlib_mount_image(WIMStruct *wim, @@ -3148,60 +3226,60 @@ wimlib_mount_image(WIMStruct *wim, * @param wim_ret * On success, a pointer to an opaque ::WIMStruct for the opened WIM file * is written to the memory location pointed to by this parameter. The - * ::WIMStruct can be freed using using wimlib_free() when finished with + * ::WIMStruct must be freed using using wimlib_free() when finished with * it. * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_IMAGE_COUNT - * The WIM is not the non-first part of a split WIM, and the number of - * metadata resources found in the WIM did not match the image count given - * in the WIM header, or the number of <IMAGE> elements in the XML - * data for the WIM did not match the image count given 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 @p - * wim_file contains an integrity table, but the SHA1 message digest for a - * chunk of the WIM does not match the corresponding message digest given - * in the integrity table. + * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in @p open_flags and + * the WIM contained an integrity table, but the SHA1 message digest for a + * chunk of the WIM did not match the corresponding value in the integrity + * table. * @retval ::WIMLIB_ERR_INVALID_CHUNK_SIZE - * Resources in @p wim_file are compressed, but the chunk size was invalid - * for the WIM's 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 header of @p wim_file says that resources in the WIM are compressed, - * but the header flag for a recognized compression type is not set. + * The library did not recognize the compression type of the WIM. * @retval ::WIMLIB_ERR_INVALID_HEADER - * The header of @p wim_file 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 @p - * wim_file contains an integrity table, but the integrity table is + * ::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 for the WIM was invalid. + * The lookup table of the WIM was invalid. * @retval ::WIMLIB_ERR_INVALID_PARAM * @p wim_ret was @c NULL. * @retval ::WIMLIB_ERR_IS_SPLIT_WIM - * @p wim_file is a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was + * The WIM was a split WIM and ::WIMLIB_OPEN_FLAG_ERROR_IF_SPLIT was * specified in @p open_flags. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocated needed memory. * @retval ::WIMLIB_ERR_NOT_A_WIM_FILE - * @p wim_file does not begin with the expected magic characters. + * The file did not begin with the magic characters that identify a WIM + * file. * @retval ::WIMLIB_ERR_OPEN - * Failed to open the file @p wim_file for reading. + * Failed to open the file for reading. * @retval ::WIMLIB_ERR_READ - * Failed to read data from @p wim_file. + * Failed to read data from the file. * @retval ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE - * Unexpected end-of-file while reading data from @p wim_file. + * Unexpected end-of-file while reading data from the file. * @retval ::WIMLIB_ERR_UNKNOWN_VERSION * The WIM version number was not recognized. (May be a pre-Vista WIM.) * @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED * The WIM cannot be opened because it contains encrypted segments. (It - * may be a Windows 8 "ESD" file). + * may be a Windows 8 "ESD" file.) * @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 for @p wim_file is invalid. + * The XML data of the WIM was invalid. */ extern int wimlib_open_wim(const wimlib_tchar *wim_file, @@ -3213,7 +3291,8 @@ wimlib_open_wim(const wimlib_tchar *wim_file, * * Same as wimlib_open_wim(), but allows specifying a progress function and * progress context. If successful, the progress function will be registered in - * the newly open ::WIMStruct. In addition, if + * the newly open ::WIMStruct, as if by an automatic call to + * wimlib_register_progress_function(). In addition, if * ::WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in @p open_flags, the * progress function will receive ::WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY * messages while checking the WIM's integrity. @@ -3236,10 +3315,8 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, * rebuild. In this mode, the new WIM is written to a temporary file and then * renamed to the original file after it is has been completely written. The * temporary file is made in the same directory as the original WIM file. A - * full rebuild may take a while, but can be used even if images have been - * modified or deleted, will produce a WIM with no holes, and has little chance - * of unintentional data loss because the temporary WIM is fsync()ed before - * being renamed to the original WIM. + * full rebuild may take a while, but it will save space by producing a WIM with + * no "holes". * * The second way to overwrite a WIM is by appending to the end of it and * overwriting the header. This can be much faster than a full rebuild, but the @@ -3258,13 +3335,6 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, * ::WIMLIB_WRITE_FLAG_SOFT_DELETE to request the in-place overwrite even if * images have been deleted from the WIM. * - * In the temporary-file overwrite mode, no changes are made to the WIM on - * failure, and the temporary file is deleted if possible. Abnormal termination - * of the program will result in the temporary file being orphaned. In the - * direct append mode, the WIM is truncated to the original length on failure; - * and while abnormal termination of the program will result in extra data - * appended to the original WIM, it should still be a valid WIM. - * * If this function completes successfully, no more functions should be called * on @p wim other than wimlib_free(). You must use wimlib_open_wim() to read * the WIM file anew. @@ -3287,8 +3357,8 @@ wimlib_open_wim_with_progress(const wimlib_tchar *wim_file, * because another thread or process has mounted an image from the WIM * read-write or is currently modifying the WIM in-place. * @retval ::WIMLIB_ERR_NO_FILENAME - * @p wim corresponds to a WIM created with wimlib_create_new_wim() rather - * than a WIM read with wimlib_open_wim(). + * @p wim corresponds to a ::WIMStruct created with wimlib_create_new_wim() + * rather than a WIM read with wimlib_open_wim(). * @retval ::WIMLIB_ERR_RENAME * The temporary file that the WIM was written to could not be renamed to * the original filename of @p wim. @@ -3311,7 +3381,8 @@ wimlib_overwrite(WIMStruct *wim, int write_flags, unsigned num_threads); * Prints information about one image, or all images, contained in a WIM. * * @param wim - * Pointer to the ::WIMStruct for a WIM file. + * 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 image about which to print information. Can be the number of an * image, or ::WIMLIB_ALL_IMAGES to print information about all images in the @@ -3587,10 +3658,6 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * Set the compression chunk size of a WIM to use in subsequent calls to * wimlib_write() or wimlib_overwrite(). * - * For compatibility reasons, using this function is not generally recommended. - * See the documentation for the @c --chunk-size option of wimlib-imagex - * capture for more information. - * * A larger compression chunk size will likely result in a better compression * ratio, but the speed of random access to the WIM will be reduced. * Furthermore, the effect of a larger compression chunk size is limited by the @@ -3600,10 +3667,10 @@ wimlib_set_image_descripton(WIMStruct *wim, int image, * ::WIMStruct for a WIM. * @param chunk_size * The chunk size (in bytes) to set. The valid chunk sizes are dependent - * on the compression format; see the documentation for the @c --chunk-size - * option of wimlib-imagex capture for more information. As a - * special case, if @p chunk_size is specified as 0, the chunk size is set - * to the default for the currently selected output compression type. + * on the compression format. See the documentation for each + * ::wimlib_compression_type constant for more information. As a special + * case, if @p chunk_size is specified as 0, the chunk size is set to the + * default for the currently selected output compression type. * * @return 0 on success; nonzero on error. * @@ -3751,7 +3818,7 @@ wimlib_set_image_name(WIMStruct *wim, int image, const wimlib_tchar *name); * library. * * Please note that some external functions, such as those in @c libntfs-3g, may - * use the standard memory allocation functions. + * use the standard memory allocation functions regardless of this setting. * * @param malloc_func * A function equivalent to @c malloc() that wimlib will use to allocate @@ -3828,11 +3895,6 @@ wimlib_set_print_errors(bool show_messages); * @retval ::WIMLIB_ERR_INVALID_PARAM * @p swm_name was not a nonempty string, or @p part_size was 0. * - * Note: the WIM's uncompressed and compressed resources are not checksummed - * when they are copied from the joined WIM to the split WIM parts, nor are - * compressed resources re-compressed (unless explicitly requested with - * ::WIMLIB_WRITE_FLAG_RECOMPRESS). - * * If a progress function is registered with @p wim, for each split WIM part * that is written it will receive the messages * ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and @@ -3849,64 +3911,38 @@ wimlib_split(WIMStruct *wim, * * Unmounts a WIM image that was mounted using wimlib_mount_image(). * - * The image to unmount is specified by the path to the mountpoint, not the - * original ::WIMStruct passed to wimlib_mount_image(), which should not be - * touched and also may have been allocated in a different process. - * - * To unmount the image, the process calling this function communicates with the - * process that is managing the mounted WIM image. This function blocks until it - * is known whether the unmount succeeded or failed. In the case of a - * read-write mounted WIM, the unmount is not considered to have succeeded until - * all changes have been saved to the underlying WIM file. + * 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. * * @param dir - * The directory that the WIM image was mounted on. + * The directory the WIM image was mounted on. * @param unmount_flags - * Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY, - * ::WIMLIB_UNMOUNT_FLAG_COMMIT, ::WIMLIB_UNMOUNT_FLAG_REBUILD, and/or - * ::WIMLIB_UNMOUNT_FLAG_RECOMPRESS. None of these flags affect read-only - * mounts. + * Bitwise OR of flags prefixed with @p WIMLIB_UNMOUNT_FLAG. * - * @return 0 on success; nonzero on error. + * @return 0 on success; nonzero on error. The possible error codes include: * - * @retval ::WIMLIB_ERR_DELETE_STAGING_DIR - * The filesystem daemon was unable to remove the staging directory and the - * temporary files that it contains. - * @retval ::WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED - * The filesystem daemon appears to have terminated before sending an exit - * status. - * @retval ::WIMLIB_ERR_FORK - * Could not @c fork() the process. - * @retval ::WIMLIB_ERR_FUSERMOUNT - * The @b fusermount program could not be executed or exited with a failure - * status. + * @retval ::WIMLIB_ERR_NOT_A_MOUNTPOINT + * 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 + * specified. * @retval ::WIMLIB_ERR_MQUEUE - * Could not open a POSIX message queue to communicate with the filesystem - * daemon servicing the mounted filesystem, could not send a message - * through the queue, or could not receive a message through the queue. - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_OPEN - * The filesystem daemon could not open a temporary file for writing the - * new WIM. - * @retval ::WIMLIB_ERR_READ - * A read error occurred when the filesystem daemon tried to a file from - * the staging directory - * @retval ::WIMLIB_ERR_RENAME - * The filesystem daemon failed to rename the newly written WIM file to the - * original WIM file. + * Could not create a POSIX message queue. + * @retval ::WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT + * The WIM image was mounted by a different user. * @retval ::WIMLIB_ERR_UNSUPPORTED * Mounting is not supported, either because the platform is Windows, or - * because the platform is UNIX-like and wimlib was compiled with @c + * because the platform is UNIX-like and wimlib was compiled using @c * --without-fuse. - * @retval ::WIMLIB_ERR_WRITE - * A write error occurred when the filesystem daemon was writing to the new - * WIM file, or the filesystem daemon was unable to flush changes that had - * been made to files in the staging directory. + * + * 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 + * this function if you want changes to be committed. */ extern int -wimlib_unmount_image(const wimlib_tchar *dir, - int unmount_flags); +wimlib_unmount_image(const wimlib_tchar *dir, int unmount_flags); /** * @ingroup G_mounting_wim_images @@ -4180,11 +4216,11 @@ struct wimlib_lzx_compressor_params { struct wimlib_compressor_params_header hdr; /** Relatively fast LZX compression algorithm with a decent compression - * ratio; the suggested default. */ + * ratio. */ #define WIMLIB_LZX_ALGORITHM_FAST 0 /** Slower LZX compression algorithm that provides a better compression - * ratio. */ + * ratio. This is the default. */ #define WIMLIB_LZX_ALGORITHM_SLOW 1 /** Algorithm to use to perform the compression: either @@ -4203,10 +4239,10 @@ struct wimlib_lzx_compressor_params { uint32_t fast_reserved1[10]; } fast; - /** Parameters for the slow algorithm. */ + /** Parameters for the "slow" algorithm. */ struct wimlib_lzx_slow_params { /** If set to 1, the compressor can output length 2 - * matches. If set 0, the compressor only outputs + * matches. If set 0, the compressor can only output * matches of length 3 or greater. Suggested value: 1 */ uint32_t use_len2_matches : 1; @@ -4234,11 +4270,10 @@ struct wimlib_lzx_compressor_params { * position. Suggested value: 50. */ uint32_t max_search_depth; - /** Maximum number of potentially good matches to - * consider for each position. Suggested value: 3. */ - uint32_t max_matches_per_pos; + /* Note: max_matches_per_pos has been removed and no + * longer has any effect. */ - uint32_t slow_reserved2[2]; + uint32_t slow_reserved2[3]; /** Assumed cost of a main symbol with zero frequency. * Must be at least 1 and no more than 16. Suggested @@ -4285,9 +4320,10 @@ struct wimlib_lzms_compressor_params { * value: 50. */ uint32_t max_search_depth; - /** Maximum number of potentially good matches to consider at each - * position. Suggested value: 3. */ - uint32_t max_matches_per_pos; + /* Note: max_matches_per_pos has been removed and no longer has any + * effect. */ + + uint32_t reserved1; /** Length of the array for the near-optimal LZ parsing algorithm. This * must be at least 1. Suggested value: 1024. */ @@ -4304,7 +4340,7 @@ struct wimlib_decompressor; /** * Set the default compression parameters for the specified compression type. - * This will affect both explicit and wimlib-internal calls to + * This will affect both explicit and library-internal calls to * wimlib_create_compressor(). * * @param ctype @@ -4341,7 +4377,8 @@ wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype, /** * Allocate a compressor for the specified compression type using the specified - * parameters. + * parameters. This function is part of wimlib's compression API; it is not + * necessary to call this to process a WIM file. * * @param ctype * Compression type for which to create the compressor. @@ -4352,8 +4389,9 @@ wimlib_get_compressor_needed_memory(enum wimlib_compression_type ctype, * @param extra_params * An optional pointer to extra compressor parameters for the specified * compression type. For LZX, a pointer to ::wimlib_lzx_compressor_params - * may be specified here. If left @c NULL, the default parameters are - * used. + * may be specified here. For LZMS, a pointer to + * ::wimlib_lzms_compressor_params may be specified here. If left @c NULL, + * the default parameters are used. * @param compressor_ret * A location into which to return the pointer to the allocated compressor, * which can be used for any number of calls to wimlib_compress() before @@ -4409,7 +4447,7 @@ wimlib_free_compressor(struct wimlib_compressor *compressor); /** * Set the default decompression parameters for the specified compression type. - * This will affect both explicit and wimlib-internal calls to + * This will affect both explicit and library-internal calls to * wimlib_create_decompressor(). * * @param ctype @@ -4432,7 +4470,8 @@ wimlib_set_default_decompressor_params(enum wimlib_compression_type ctype, /** * Allocate a decompressor for the specified compression type using the - * specified parameters. + * specified parameters. This function is part of wimlib's compression API; it + * is not necessary to call this to process a WIM file. * * @param ctype * Compression type for which to create the decompressor.