X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=1b476be24763990d6112f2b479561feb7b89dc76;hp=0dd705c7e038449e338ac4f136237b92f447ed0f;hb=17dd0feabb235443ca310bfafbd95adfa54924cb;hpb=bde99a849d3e7a479cb04a4e16e405b0c2f022dd diff --git a/src/wimlib.h b/src/wimlib.h index 0dd705c7..1b476be2 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -31,6 +31,10 @@ * * \section intro Introduction * + * This is the documentation for the library interface of wimlib 1.2.1. If you + * have installed wimlib and want to know how to use the @c imagex program, + * please see the man pages instead. + * * wimlib is a C library to read, write, and mount archive files in the Windows * Imaging Format (WIM files). These files are normally created using the @c * imagex.exe utility on Windows, but this library provides a free @@ -211,6 +215,10 @@ #include #include +#define WIMLIB_MAJOR_VERSION 1 +#define WIMLIB_MINOR_VERSION 2 +#define WIMLIB_PATCH_VERSION 1 + /** * 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 @@ -263,6 +271,11 @@ enum wimlib_progress_msg { * info will point to ::wimlib_progress_info.extract. */ WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, + /** A file or directory is being extracted. @a info will point to + * ::wimlib_progress_info.extract, and the @a cur_path member will be + * valid. */ + WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY, + /** All the WIM files and directories have been extracted, and * timestamps are about to be applied. @a info will point to * ::wimlib_progress_info.extract. */ @@ -277,22 +290,28 @@ enum wimlib_progress_msg { * ::wimlib_progress_info.scan. */ WIMLIB_PROGRESS_MSG_SCAN_BEGIN, + /** A directory or file is being scanned. @a info will point to + * ::wimlib_progress_info.scan, and its @a cur_path member will be + * valid. This message is only sent if ::WIMLIB_ADD_IMAGE_FLAG_VERBOSE + * is passed to wimlib_add_image(). */ + WIMLIB_PROGRESS_MSG_SCAN_DENTRY, + /** The directory or NTFS volume has been successfully scanned, and a * tree of WIM dentries has been built in-memory. @a info will point to * ::wimlib_progress_info.scan. */ WIMLIB_PROGRESS_MSG_SCAN_END, - /** + /** * File resources are currently being written to the WIM. * @a info will point to ::wimlib_progress_info.write_streams. */ WIMLIB_PROGRESS_MSG_WRITE_STREAMS, - /** + /** * The metadata resource for each image is about to be written to the * WIM. @a info will not be valid. */ WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, - /** + /** * The metadata resource for each image has successfully been writen to * the WIM. @a info will not be valid. */ WIMLIB_PROGRESS_MSG_WRITE_METADATA_END, @@ -375,6 +394,15 @@ union wimlib_progress_info { struct wimlib_progress_info_scan { /** Directory or NTFS volume that is being scanned. */ const char *source; + + /** Path to the file or directory that is about to be scanned, + * relative to the root of the image capture or the NTFS volume. + * */ + const char *cur_path; + + /** True iff @a cur_path is being excluded from the image + * capture due to the capture configuration file. */ + bool excluded; } scan; /** Valid on messages ::WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, @@ -386,6 +414,12 @@ union wimlib_progress_info { /** Number of the image being extracted (1-based). */ int image; + /** Flags passed to to wimlib_extract_image() */ + int extract_flags; + + /** Full path to the WIM file being extracted. */ + const char *wimfile_name; + /** Name of the image being extracted. */ const char *image_name; @@ -393,6 +427,10 @@ union wimlib_progress_info { * extracted. */ const char *target; + /** Current dentry being extracted. (Valid only if message is + * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY.) */ + const char *cur_path; + /** Number of bytes of uncompressed data that will be extracted. * Takes into account hard links (they are not counted for each * link.) @@ -465,9 +503,6 @@ union wimlib_progress_info { /** Number of split WIM parts. */ unsigned total_parts; - - /** Name of the joined WIM file being written. */ - const char *filename; } join; /** Valid on messages ::WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and @@ -506,6 +541,7 @@ union wimlib_progress_info { typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, const union wimlib_progress_info *info); + /***************************** * WIMLIB_ADD_IMAGE_FLAG_* * *****************************/ @@ -517,8 +553,9 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, * with ::WIMLIB_ADD_IMAGE_FLAG_NTFS. */ #define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE 0x00000002 -/** Print the name of each file or directory as it is scanned to be included in - * the WIM image. */ +/** Call the progress function with the message + * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file is starting to + * be scanned. */ #define WIMLIB_ADD_IMAGE_FLAG_VERBOSE 0x00000004 /** Mark the image being added as the bootable image of the WIM. */ @@ -547,8 +584,10 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, * together. Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */ #define WIMLIB_EXTRACT_FLAG_SYMLINK 0x00000004 -/** Print the name of each file or directory as it is extracted from the WIM - * image. */ +/** Call the progress function with the argument + * ::WIMLIB_PROGRESS_MSG_EXTRACT_DENTRY each time a file or directory is + * extracted. Note: these calls will be interspersed with calls for the message + * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS. */ #define WIMLIB_EXTRACT_FLAG_VERBOSE 0x00000008 /** Read the WIM file sequentially while extracting the image. */ @@ -597,6 +636,12 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, * discarded. Ignored for read-only mounts. */ #define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002 +/** See ::WIMLIB_WRITE_FLAG_REBUILD */ +#define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004 + +/** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */ +#define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008 + /****************************** * WIMLIB_WRITE_FLAG_* * ******************************/ @@ -616,7 +661,7 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, /** Call fsync() when the WIM file is closed */ #define WIMLIB_WRITE_FLAG_FSYNC 0x00000008 -/** Specifying this flag overrides the default behavior of wimlib_overwrite() +/* Specifying this flag overrides the default behavior of wimlib_overwrite() * after one or more calls to wimlib_delete_image(), which is to rebuild the * entire WIM. * @@ -635,12 +680,15 @@ typedef int (*wimlib_progress_func_t)(enum wimlib_progress_msg msg_type, */ enum wimlib_error_code { WIMLIB_ERR_SUCCESS = 0, + WIMLIB_ERR_ALREADY_LOCKED, WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE, WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_DELETE_STAGING_DIR, + WIMLIB_ERR_FILESYSTEM_DAEMON_CRASHED, WIMLIB_ERR_FORK, WIMLIB_ERR_FUSE, WIMLIB_ERR_FUSERMOUNT, + WIMLIB_ERR_ICONV_NOT_AVAILABLE, WIMLIB_ERR_IMAGE_COUNT, WIMLIB_ERR_IMAGE_NAME_COLLISION, WIMLIB_ERR_INTEGRITY, @@ -653,9 +701,14 @@ enum wimlib_error_code { WIMLIB_ERR_INVALID_INTEGRITY_TABLE, WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY, WIMLIB_ERR_INVALID_PARAM, + WIMLIB_ERR_INVALID_PART_NUMBER, WIMLIB_ERR_INVALID_RESOURCE_HASH, WIMLIB_ERR_INVALID_RESOURCE_SIZE, WIMLIB_ERR_INVALID_SECURITY_DATA, + WIMLIB_ERR_INVALID_UNMOUNT_MESSAGE, + WIMLIB_ERR_INVALID_UTF8_STRING, + WIMLIB_ERR_INVALID_UTF16_STRING, + WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE, WIMLIB_ERR_LINK, WIMLIB_ERR_MKDIR, WIMLIB_ERR_MQUEUE, @@ -772,7 +825,7 @@ enum wimlib_error_code { * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED * @a wim is part of a split WIM. Adding an image to a split WIM is * unsupported. - * @retval ::WIMLIB_ERR_UNSUPPORTED: + * @retval ::WIMLIB_ERR_UNSUPPORTED * ::WIMLIB_ADD_IMAGE_FLAG_NTFS was specified in @a add_image_flags, but * wimlib was configured with the @c --without-ntfs-3g flag. */ @@ -937,8 +990,7 @@ extern int wimlib_delete_image(WIMStruct *wim, int image); * ::WIMLIB_ALL_IMAGES, @a src_wim contains multiple images, and no images in * @a src_wim are marked as bootable; or @a dest_name and/or @a * dest_description were non-NULL, @a src_image was - * ::WIMLIB_ALL_IMAGES, and @a src_wim contains multiple images; or @a src_wim - * or @a dest_wim was @c NULL. + * ::WIMLIB_ALL_IMAGES, and @a src_wim contains multiple images. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE * The metadata resource for @a src_image in @a src_wim is invalid. * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA @@ -1040,11 +1092,11 @@ extern int wimlib_export_image(WIMStruct *src_wim, int src_image, * A directory entry in the metadata resource for @a image in @a wim is * invalid. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a wim was @c NULL, or @a target was @c NULL, or both - * ::WIMLIB_EXTRACT_FLAG_HARDLINK and ::WIMLIB_EXTRACT_FLAG_SYMLINK were - * specified in @a extract_flags, or both ::WIMLIB_EXTRACT_FLAG_NTFS and - * either ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK - * were specified in @a extract_flags, or ::WIMLIB_EXTRACT_FLAG_NTFS was + * @a target was @c NULL, or both ::WIMLIB_EXTRACT_FLAG_HARDLINK and + * ::WIMLIB_EXTRACT_FLAG_SYMLINK were specified in @a extract_flags, or + * both ::WIMLIB_EXTRACT_FLAG_NTFS and either + * ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK were + * specified in @a extract_flags, or ::WIMLIB_EXTRACT_FLAG_NTFS was * specified in @a extract_flags and @a image was ::WIMLIB_ALL_IMAGES. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_HASH * The SHA1 message digest of an extracted stream did not match the SHA1 @@ -1308,27 +1360,21 @@ extern int wimlib_join(const char **swms, unsigned num_swms, /** * Mounts an image in a WIM file on a directory read-only or read-write. * - * A daemon will be forked to service the filesystem, unless - * ::WIMLIB_MOUNT_FLAG_DEBUG is specified in @a mount_flags. In other words, - * this function returns @b before the image is unmounted, and filesystem - * requests are handled by a new thread. This also means that no functions may - * be safely called on @a wim after wimlib_mount_image() has been called on any - * images from it. (@a wim will be freed by the filesystem thread after the - * filesystem is unmounted.) + * The calling thread will be daemonized to service the filesystem, and this + * function will not return until the image is unmounted, unless an error occurs + * before the filesystem is successfully mounted. * * If the mount is read-write (::WIMLIB_MOUNT_FLAG_READWRITE specified), - * modifications to the WIM are staged in a temporary directory created in the - * process's working directory when this function is called. + * modifications to the WIM are staged in a temporary directory. * * It is safe to mount multiple images from the same WIM file read-only at the - * same time (but different ::WIMStruct's should be used). However, it is @b - * not safe to mount multiple images from the same WIM file read-write at the - * same time. + * 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 has just been added with wimlib_add_image(), or unless the WIM has been + * that has just been added with wimlib_add_image(), unless the WIM has been * written and read into a new ::WIMStruct. * * @param wim @@ -1362,10 +1408,18 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * This number should be one less than the total number of parts in the * split WIM. Set to 0 if the WIM is a standalone WIM. * @param staging_dir - * Currently ignored, but may provide a way to specify the staging - * directory in the future. Set to @c NULL. + * 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 @a mount_flags. If left @c NULL, the staging directory is created in + * the same directory as the WIM file that @a wim was originally read from. * * @return 0 on success; nonzero on error. + * + * @retval ::WIMLIB_ERR_ALREADY_LOCKED + * A read-write mount was requested, but an 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. * @retval ::WIMLIB_ERR_DECOMPRESSION * Could not decompress the metadata resource for @a image in @a wim. * @retval ::WIMLIB_ERR_FUSE @@ -1543,6 +1597,11 @@ extern int wimlib_open_wim(const char *wim_file, int open_flags, * * @return 0 on success; nonzero on error. This function may return any value * returned by wimlib_write() as well as the following error codes: + * @retval ::WIMLIB_ERR_ALREADY_LOCKED + * The WIM was going to be modifien in-place (with no temporary file), 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. * @retval ::WIMLIB_ERR_NO_FILENAME * @a wim corresponds to a WIM created with wimlib_create_new_wim() rather * than a WIM read with wimlib_open_wim(). @@ -1595,8 +1654,6 @@ extern void wimlib_print_available_images(const WIMStruct *wim, int image); * @retval ::WIMLIB_ERR_INVALID_IMAGE * @a image does not specify a valid image in @a wim, and is not * ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a wim was @c NULL. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE * The metadata resource for one of the specified images is invalid. * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA @@ -1659,8 +1716,6 @@ extern void wimlib_print_lookup_table(WIMStruct *wim); * @retval ::WIMLIB_ERR_INVALID_IMAGE * @a image does not specify a valid image in @a wim, and is not * ::WIMLIB_ALL_IMAGES. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a wim was @c NULL. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE * The metadata resource for one of the specified images is invalid. * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA @@ -1712,8 +1767,8 @@ extern void wimlib_print_wim_information(const WIMStruct *wim); * 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 @a image_name_or_num was @c NULL or - * the empty string, ::WIM_NO_IMAGE is returned, even if one or more images - * in @a wim has no name. + * the empty string, ::WIMLIB_NO_IMAGE is returned, even if one or more + * images in @a wim has no name. */ extern int wimlib_resolve_image(WIMStruct *wim, const char *image_name_or_num); @@ -1726,8 +1781,6 @@ extern int wimlib_resolve_image(WIMStruct *wim, const char *image_name_or_num); * The number of the image to mark as bootable, or 0 to mark no image as * bootable. * @return 0 on success; nonzero on error. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a wim was @c NULL. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @a boot_idx does not specify an existing image in @a wim, and it was not * 0. @@ -1753,8 +1806,6 @@ extern int wimlib_set_boot_idx(WIMStruct *wim, int boot_idx); * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @a image does not specify a single existing image in @a wim. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a wim was @c NULL. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate the memory needed to duplicate the @a description * string. @@ -1779,8 +1830,6 @@ extern int wimlib_set_image_descripton(WIMStruct *wim, int image, * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @a image does not specify a single existing image in @a wim. - * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a wim was @c NULL. * @retval ::WIMLIB_ERR_NOMEM * Failed to allocate the memory needed to duplicate the @a flags string. */ @@ -1802,7 +1851,7 @@ extern int wimlib_set_image_flags(WIMStruct *wim, int image, const char *flags); * @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION * There is already an image named @a name in @a wim. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a name was @c NULL or the empty string, or @a wim was @c NULL. + * @a name was @c NULL or the empty string. * @retval ::WIMLIB_ERR_INVALID_IMAGE * @a image does not specify a single existing image in @a wim. * @retval ::WIMLIB_ERR_NOMEM @@ -1892,7 +1941,7 @@ extern int wimlib_set_print_errors(bool show_messages); * @retval ::WIMLIB_ERR_SPLIT_UNSUPPORTED: * @a wim is not part 1 of a stand-alone WIM. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a w was @c NULL, @a swm_name was @c NULL, or @a part_size was 0. + * @a swm_name was @c NULL, or @a 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 @@ -1911,29 +1960,29 @@ extern int wimlib_split(WIMStruct *wim, const char *swm_name, * * To unmount the image, the thread calling this function communicates with the * thread that is managing the mounted WIM image. This function blocks until it - * is known whether the unmount succeeded or failed. (This means until the - * entire WIM has been re-written, in the case of a read-write mounted WIM.) - * - * There is currently a design problem with this function because it is hard to - * know whether the filesystem thread is still working or whether it has crashed - * or has been killed. Currently, a timeout of 600 seconds (so long because - * WIMs can be very large) is implemented so that this function will not wait - * forever before returning failure. + * 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. * * @param dir * The directory that the WIM image was mounted on. * @param unmount_flags - * Bitwise OR of the flags ::WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY and/or - * ::WIMLIB_UNMOUNT_FLAG_COMMIT. Neither of these flags affect read-only + * 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. * @param progress_func - * Currently ignored, but may be used for a progress callback in the - * future. Set to @c NULL. + * If non-NULL, a function that will be called periodically with the + * progress of the current operation. * * @return 0 on success; nonzero on error. + * * @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 @@ -1948,10 +1997,6 @@ extern int wimlib_split(WIMStruct *wim, const char *swm_name, * @retval ::WIMLIB_ERR_OPEN * The filesystem daemon could not open a temporary file for writing the * new WIM. - * @retval ::WIMLIB_ERR_TIMEOUT - * 600 seconds elapsed while waiting for the filesystem daemon to notify - * the process of its exit status, so the WIM file probably was not written - * successfully. * @retval ::WIMLIB_ERR_READ * A read error occurred when the filesystem daemon tried to a file from * the staging directory @@ -2011,7 +2056,7 @@ extern int wimlib_unmount_image(const char *dir, int unmount_flags, * wimlib_add_image() or wimlib_add_image_from_ntfs_volume() functions was * concurrently modified, so it failed the SHA1 message digest check. * @retval ::WIMLIB_ERR_INVALID_PARAM - * @a wim or @a path was @c NULL. + * @a path was @c NULL. * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE * The metadata resource for @a image in @a wim is invalid. * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA