X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=0618ff3801114645820b0584e99afeb6eb9dca88;hp=076aee176fab516609ee461ed2a33b1b70477b2b;hb=5cdd60306facd14cc9dcc24471386451294ca73c;hpb=16e3b6e5615abcefc9e5bb9607e2804b64d19cc2 diff --git a/src/wimlib.h b/src/wimlib.h index 076aee17..0618ff38 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -108,10 +108,9 @@ * that this is for convenience only, and some errors can occur without a * message being printed. * - * wimlib is thread-safe as long as different ::WIMStruct's are used, with the - * following exceptions: wimlib_set_print_errors() and - * wimlib_set_memory_allocator() apply globally, and wimlib_mount() can only be - * used by one ::WIMStruct at a time. + * wimlib is thread-safe as long as different ::WIMStruct's are used, except for + * the fact that wimlib_set_print_errors() and wimlib_set_memory_allocator() + * both apply globally. * * To open an existing WIM, use wimlib_open_wim(). * @@ -142,14 +141,18 @@ * * After creating or modifying a WIM file, you can write it to a file using * wimlib_write(). Alternatively, if the WIM was originally read from a file, - * you can use wimlib_overwrite() to overwrite the original file. In some - * cases, wimlib_overwrite_xml_and_header() can be used instead. + * you can use wimlib_overwrite() to overwrite the original file. + * + * Please not: merely by calling wimlib_add_image() or many of the other + * functions in this library that operate on ::WIMStruct's, you are @b not + * modifing the WIM file on disk. Changes are not saved until you explicitly + * call wimlib_write() or wimlib_overwrite(). * * After you are done with the WIM file, use wimlib_free() to free all memory * associated with a ::WIMStruct and close all files associated with it. * - * To see an example of how to use wimlib, see the file - * @c programs/imagex.c in wimlib's source tree. + * To see an example of how to use wimlib, see the file @c programs/imagex.c in + * wimlib's source tree. * * wimlib supports custom memory allocators; use wimlib_set_memory_allocator() * for this. However, if wimlib calls into @c libntfs-3g, the custom memory @@ -263,12 +266,33 @@ enum wim_compression_type { /** Include an integrity table in the new WIM file. */ #define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY 0x00000001 -/** Print progress information when writing the integrity table. */ +/** Print progress information when writing streams and when writing the + * integrity table. */ #define WIMLIB_WRITE_FLAG_SHOW_PROGRESS 0x00000002 /** Print file paths as we write then */ #define WIMLIB_WRITE_FLAG_VERBOSE 0x00000004 +/** Call fsync() when the WIM file is closed */ +#define WIMLIB_WRITE_FLAG_FSYNC 0x00000008 + +/** Re-build the entire WIM file rather than appending data to it, if possible. + * (Applies to wimlib_overwrite(), not wimlib_write()). */ +#define WIMLIB_WRITE_FLAG_REBUILD 0x00000010 + +/** Do not copy compressed resources between WIMs if the compression type is the + * same. Instead, recompress them. */ +#define WIMLIB_WRITE_FLAG_RECOMPRESS 0x00000020 + +/** 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. If you specifiy this flag to wimlib_overwrite() instead, only + * minimal changes to correctly remove the image from the WIM will be taken. In + * particular, all streams will be left alone, even if they are no longer + * references. This is probably not what you want, because almost no space will + * be spaced by deleting an image in this way. */ +#define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000040 + /** Mark the image being added as the bootable image of the WIM. */ #define WIMLIB_ADD_IMAGE_FLAG_BOOT 0x00000001 @@ -279,6 +303,9 @@ enum wim_compression_type { /** Follow symlinks; archive and dump the files they point to. */ #define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE 0x00000004 +/** Show progress information when scanning a directory tree */ +#define WIMLIB_ADD_IMAGE_FLAG_SHOW_PROGRESS 0x00000008 + /** See documentation for wimlib_export_image(). */ #define WIMLIB_EXPORT_FLAG_BOOT 0x00000001 @@ -304,6 +331,12 @@ enum wim_compression_type { /** Print the name of each file as it is extracted from the WIM image. */ #define WIMLIB_EXTRACT_FLAG_VERBOSE 0x00000008 +/** Read the WIM file sequentially while extracting the image. */ +#define WIMLIB_EXTRACT_FLAG_SEQUENTIAL 0x00000010 + +/** Print progress information while extracting the image. */ +#define WIMLIB_EXTRACT_FLAG_SHOW_PROGRESS 0x00000020 + /** * Possible values of the error code returned by many functions in wimlib. * @@ -346,6 +379,7 @@ enum wimlib_error_code { WIMLIB_ERR_READLINK, WIMLIB_ERR_READ, WIMLIB_ERR_RENAME, + WIMLIB_ERR_REOPEN, WIMLIB_ERR_RESOURCE_ORDER, WIMLIB_ERR_SPECIAL_FILE, WIMLIB_ERR_SPLIT_INVALID, @@ -400,7 +434,9 @@ enum wimlib_error_code { * printed as it is scanned or captured. If * ::WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE is specified, the files or * directories pointed to by symbolic links are archived rather than the - * symbolic links themselves. + * symbolic links themselves. If ::WIMLIB_ADD_IMAGE_FLAG_SHOW_PROGRESS is + * specified, progress information will be printed (distinct from the + * verbose information). * * @return 0 on success; nonzero on error. On error, changes to @a wim are * discarded so that it appears to be in the same state as when this function @@ -893,7 +929,10 @@ extern bool wimlib_image_name_in_use(const WIMStruct *wim, const char *name); * An error occurred when trying to write data to the new WIM at @a output_path. * * Note that this function merely copies the resources, so it will not check to - * see if the resources, including the metadata resource, are valid or not. + * see if the resources, including the metadata resources, are valid or not. + * + * Also, after this function is called, the only function that may be called on + * the ::WIMStruct's in the @a swms array is wimlib_free(). */ extern int wimlib_join(const char **swms, unsigned num_swms, const char *output_path, int flags); @@ -906,11 +945,16 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * If the mount is read-write, modifications to the WIM are staged in a staging * directory. * - * wimlib_mount() currently cannot be used with multiple ::WIMStruct's without - * intervening wimlib_unmount()s. + * wimlib_mount() may be called from multiple threads without intervening calls + * to wimlib_unmount(), provided that different ::WIMStruct's are used. (This + * was not the case for versions of this library 1.0.3 and earlier.) * * wimlib_mount() cannot be used on an image that was exported with - * wimlib_export() while the dentry trees for both images are still in memory. + * wimlib_export_image() while the dentry trees for both images are still in + * memory. In addition, wimlib_mount() may not be used to mount an image that + * has just been added with wimlib_add_image() or + * wimlib_add_image_from_ntfs_volume(), unless the WIM has been written and read + * into a new ::WIMStruct. * * @param wim * Pointer to the ::WIMStruct for the WIM file to be mounted. @@ -950,7 +994,8 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * @a image does not specify an existing, single image in @a wim. * @retval ::WIMLIB_ERR_INVALID_PARAM * @a image is shared among multiple ::WIMStruct's as a result of a call to - * wimlib_export(). + * wimlib_export_image(), or @a image has been added with + * wimlib_add_image() or wimlib_add_image_from_ntfs_volume(). * @retval ::WIMLIB_ERR_INVALID_RESOURCE_SIZE * The metadata resource for @a image in @a wim is invalid. * @retval ::WIMLIB_ERR_INVALID_SECURITY_DATA @@ -994,7 +1039,7 @@ extern int wimlib_mount(WIMStruct *wim, int image, const char *dir, int flags, * If ::WIMLIB_OPEN_FLAG_SHOW_PROGRESS is given, progress information will * be shown if the integrity of the WIM is checked. * If ::WIMLIB_OPEN_FLAG_SPLIT_OK is given, no error will be issued if the - * WIM is part of a split WIM; otherwise WIMLIB_ERR_SPLIT_UNSUPPORTED is + * WIM is part of a split WIM; otherwise ::WIMLIB_ERR_SPLIT_UNSUPPORTED is * returned. (This flag may be removed in the future, in which case no * error will be issued when opening a split WIM.) * @@ -1057,20 +1102,43 @@ extern int wimlib_open_wim(const char *wim_file, int flags, /** * Overwrites the file that the WIM was originally read from, with changes made. * - * 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 currently - * is made in the same directory as the original WIM file. - * - * After this function returns, @a wim must be freed using wimlib_free(). Any - * further actions on @a wim before doing this are undefined. + * There are two ways that a WIM may be overwritten. The first is to do a full + * rebuild: 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 + * currently 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. + * + * The second way to overwrite a WIM is by appending to the end of it. This can + * be much faster than a full rebuild, but it only works if the only operations + * on the WIM have been to change the header or XML data, or to add new images. + * Writing a WIM in this mode begins with writing any new file resources *after* + * everything in the old WIM, even though this will leave a hole where the old + * lookup table, XML data, and integrity were. This is done so that the WIM + * remains valid even if the operation is aborted mid-write. + * + * By default, the overwrite mode is chosen based on the past operations + * performed on the WIM. Use the flag ::WIMLIB_WRITE_FLAG_REBUILD to explicitly + * request a full rebuild. + * + * 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, while abnormal termination of the program will result in extra data + * appended to the original WIM, but it will still be a valid WIM. * * @param wim * Pointer to the ::WIMStruct for the WIM file to write. There may have * been in-memory changes made to it, which are then reflected in the * output file. - * @param flags + * @param write_flags * Bitwise OR of ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY and/or * ::WIMLIB_WRITE_FLAG_SHOW_PROGRESS. + * @param num_threads + * Number of threads to use for compression (see wimlib_write()). * * @return 0 on success; nonzero on error. This function may return any value * returned by wimlib_write() as well as the following error codes: @@ -1080,50 +1148,21 @@ extern int wimlib_open_wim(const char *wim_file, int flags, * @retval ::WIMLIB_ERR_RENAME * The temporary file that the WIM was written to could not be renamed to * the original filename of @a wim. + * @retval ::WIMLIB_ERR_REOPEN + * The WIM was overwritten successfully, but it could not be re-opened + * read-only. Therefore, the resources in the WIM can no longer be + * accessed, so this limits the functions that can be called on @a wim + * before calling wimlib_free(). */ -extern int wimlib_overwrite(WIMStruct *wim, int flags); +extern int wimlib_overwrite(WIMStruct *wim, int write_flags, + unsigned num_threads); /** - * Updates the header and XML data of the WIM file, without the need to write - * out the entire WIM to a temporary file as in wimlib_write(). - * - * This function must only be used if no files, directories, or images have been - * added, removed, or changed in the WIM. It must be used when only the boot - * index or the name or description of image(s) has been changed. - * - * After this function returns, @a wim must be freed using wimlib_free(). Any - * further actions on @a wim before doing this are undefined. - * - * @param wim - * Pointer to the ::WIMStruct for the WIM file to overwrite. - * @param flags - * Bitwise OR of ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY and/or - * ::WIMLIB_WRITE_FLAG_SHOW_PROGRESS. - * - * @return 0 on success; nonzero on error. - * - * @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(). - * @retval ::WIMLIB_ERR_NOMEM - * Failed to allocate needed memory. - * @retval ::WIMLIB_ERR_OPEN - * The WIM file associated with @a wim could not be re-opened read-write. - * @retval ::WIMLIB_ERR_READ - * ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY was specified in @a flags, but data - * from the WIM file associated with @a wim could not be read to compute - * the SHA1 message digests, or the old integrity table (if it existed) - * could not be read. - * @retval ::WIMLIB_ERR_RESOURCE_ORDER - * Stream resources appeared in the WIM after the XML data or integrity - * table, so we could not safely overwrite the XML data and integrity - * table. Note: this error should never be received from WIMs that were - * written by this library. - * @retval ::WIMLIB_ERR_WRITE - * Failed to write the WIM header, the XML data, or the integrity table to - * the WIM file associated with @a wim. + * This function is deprecated; call wimlib_overwrite() instead. + * (wimlib_overwrite() no longer rebuilds the full WIM unless it has to or is + * specified explicitly with ::WIMLIB_WRITE_FLAG_REBUILD) */ -extern int wimlib_overwrite_xml_and_header(WIMStruct *wim, int flags); +extern int wimlib_overwrite_xml_and_header(WIMStruct *wim, int write_flags); /** * Prints information about one image, or all images, contained in a WIM. @@ -1521,13 +1560,19 @@ extern int wimlib_unmount(const char *dir, int flags); * @param image * The image inside the WIM to write. Use ::WIM_ALL_IMAGES to include all * images. - * @param flags + * @param write_flags * Bitwise OR of ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY and/or * ::WIMLIB_WRITE_FLAG_SHOW_PROGRESS. If * ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY is given, an integrity table is * included in the WIM being written. If ::WIMLIB_WRITE_FLAG_SHOW_PROGRESS * is given, the progress of the calculation of the integrity table is * shown. + * @param num_threads + * Number of threads to use for compressing data. Autodetected if set to + * 0. Note: if no data compression needs to be done, no threads will be + * created regardless of this parameter (e.g. if writing an uncompressed + * WIM, or exporting an image from a compressed WIM to another WIM of the + * same compression type). * * @return 0 on success; nonzero on error. * @retval ::WIMLIB_ERR_DECOMPRESSION @@ -1566,7 +1611,8 @@ extern int wimlib_unmount(const char *dir, int flags); * An error occurred when trying to write data to the new WIM file at @a * path. */ -extern int wimlib_write(WIMStruct *wim, const char *path, int image, int flags); +extern int wimlib_write(WIMStruct *wim, const char *path, int image, + int write_flags, unsigned num_threads);