* 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().
*
/** 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 */
/** 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
WIMLIB_ERR_READLINK,
WIMLIB_ERR_READ,
WIMLIB_ERR_RENAME,
+ WIMLIB_ERR_RESOURCE_ORDER,
WIMLIB_ERR_SPECIAL_FILE,
WIMLIB_ERR_SPLIT_INVALID,
WIMLIB_ERR_SPLIT_UNSUPPORTED,
* 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
* 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);
* 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.
* @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
* 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.)
*
* 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:
* The temporary file that the WIM was written to could not be renamed to
* the original filename of @a wim.
*/
-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
*
* @param wim
* Pointer to the ::WIMStruct for the WIM file to overwrite.
- * @param flags
+ * @param write_flags
* Bitwise OR of ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY and/or
* ::WIMLIB_WRITE_FLAG_SHOW_PROGRESS.
*
* 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.
*/
-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.
* @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
* 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);
git://wimlib.net / wimlib / blobdiff