X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=src%2Fwimlib.h;h=ce079ce477d499f8ea1d5ee321ecb7b51e11a683;hp=8c133a261cca606e45c8b5e84119cdb60830759a;hb=9368708ff94a8da723874c098d24fefcd5866207;hpb=c8c6ce6f5e94086eb3b210661c1cfb08dacff67d diff --git a/src/wimlib.h b/src/wimlib.h index 8c133a26..ce079ce4 100644 --- a/src/wimlib.h +++ b/src/wimlib.h @@ -141,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 @@ -262,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 @@ -278,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 @@ -345,6 +373,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, @@ -399,7 +428,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 @@ -914,7 +945,10 @@ extern int wimlib_join(const char **swms, unsigned num_swms, * * wimlib_mount() cannot be used on an image that was exported with * wimlib_export_image() while the dentry trees for both images are still in - * memory. + * 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. @@ -954,7 +988,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_image(). + * 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 @@ -1061,20 +1096,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: @@ -1084,50 +1142,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. @@ -1525,13 +1554,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 @@ -1570,7 +1605,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);