* set the readonly flag on the on-disk WIM file. */
#define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG 0x00000100
+/** Do not include non-metadata resources already present in other WIMs. This
+ * flag can be used to write a "delta" WIM after resources from the WIM on which
+ * the delta is to be based were referenced with
+ * wimlib_reference_resource_files() or wimlib_reference_resources(). */
+#define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS 0x00000200
+
+/** Asserts that for writes of all WIM images, all streams needed for the WIM
+ * are already present (not in external resource WIMs) and their reference
+ * counts are correct, so the code does not need to recalculate which streams
+ * are referenced. This is for optimization purposes only, since with this flag
+ * specified, the metadata resources may not need to be decompressed and parsed.
+ *
+ * This flag can be passed to wimlib_write() and wimlib_write_to_fd(), but is
+ * already implied for wimlib_overwrite(). */
+#define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400
+
/**
* @name Init flags
*
* @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND
* A resource that needed to be exported could not be found in either the
* source or destination WIMs. This error can occur if, for example, @p
- * src_wim is part of a split WIM but resources from the other split WIM
- * parts were not referenced with wimlib_reference_resources() or
- * wimlib_reference_resource_files().
+ * src_wim is part of a split WIM but needed resources from the other split
+ * WIM parts were not referenced with wimlib_reference_resources() or
+ * wimlib_reference_resource_files() before the call to
+ * wimlib_export_image().
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
* @p dest_wim is considered read-only because of any of the reasons
* mentioned in the documentation for the ::WIMLIB_OPEN_FLAG_WRITE_ACCESS
* If non-NULL, a function that will be called periodically with the
* progress of the current operation.
*
- * @return 0 on success; nonzero on error. This function may return any value
- * returned by wimlib_write() as well as the following error codes:
+ * @return 0 on success; nonzero on error. This function may return most error
+ * codes returned by wimlib_write() as well as the following error codes:
+ *
* @retval ::WIMLIB_ERR_ALREADY_LOCKED
* The WIM was going to be modified in-place (with no temporary file), but
* an exclusive advisory lock on the on-disk WIM file could not be acquired
* @param ref_flags
* Currently ignored (set to 0).
*
- * @return 0 on success; nonzero on error. On success, the ::WIMStruct's
- * specified in @p resource_wims should be considered "don't touch" until either
- * wimlib_free() is called on @p wim, or wimlib_unreference_resources() is
- * called to unreference them.
+ * @return 0 on success; nonzero on error. On success, the ::WIMStruct's of the
+ * @p resource_wims are referenced internally by @p wim and must not be freed
+ * with wimlib_free() or overwritten with wimlib_overwrite() until @p wim has
+ * been freed with wimlib_free(), or immediately before freeing @p wim with
+ * wimlib_free().
*
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @p wim was @c NULL, or @p num_resource_wims was nonzero but @p
- * resource_wims was @c NULL, or @p wim did not contain metadata resources,
- * or an entry in @p resource_wims was @p NULL, or an entry in @p
- * resource_wims was already referenced by a call to this function without
- * a corresponding call to wimlib_free() on the metadata WIM, or
- * wimlib_unreference_resources().
+ * resource_wims was @c NULL, or an entry in @p resource_wims was @p NULL.
+ * @retval ::WIMLIB_ERR_NOMEM
+ * Failed to allocate memory.
*/
extern int
wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims,
* intervening time. This is designed to be used in incremental backups of the
* same filesystem or directory tree.
*
- * This function compares the directory tree of the newly added image against
- * that of the old image. Any files that are present in both the newly added
- * image and the old image and have timestamps that indicate they haven't been
- * modified are deemed not to have been modified. Such files will not be read
- * from the filesystem when the WIM is being written or overwritten. Note that
- * these unchanged files will still be "archived" and will be logically present
- * in the new image; the optimization is that they don't need to actually be
- * read from the filesystem because the WIM already contains them.
+ * This function compares the metadata of the directory tree of the newly added
+ * image against that of the old image. Any files that are present in both the
+ * newly added image and the old image and have timestamps that indicate they
+ * haven't been modified are deemed not to have been modified and have their
+ * SHA1 message digest copied from the old image. Because of this and because
+ * WIM uses single-instance streams, such files need not be read from the
+ * filesystem when the WIM is being written or overwritten. Note that these
+ * unchanged files will still be "archived" and will be logically present in the
+ * new image; the optimization is that they don't need to actually be read from
+ * the filesystem because the WIM already contains them.
*
* This function is provided to optimize incremental backups. The resulting WIM
* file will still be the same regardless of whether this function is called.
* 1-based index in the WIM of the newly added image. This image can have
* been added with wimlib_add_image() or wimlib_add_image_multisource(), or
* wimlib_add_empty_image() followed by wimlib_update_image().
+ * @param template_wim
+ * The ::WIMStruct for the WIM containing the template image. This can be
+ * the same as @p wim, or it can be a different ::WIMStruct.
* @param template_image
* 1-based index in the WIM of a template image that reflects a prior state
* of the directory tree being captured.
*/
extern int
wimlib_reference_template_image(WIMStruct *wim, int new_image,
- int template_image, int flags,
- wimlib_progress_func_t progress_func);
+ WIMStruct *template_wim, int template_image,
+ int flags, wimlib_progress_func_t progress_func);
/**
* Translates a string specifying the name or number of an image in the WIM into
int unmount_flags,
wimlib_progress_func_t progress_func);
-/**
- * Unreferences resources previously referenced with
- * wimlib_reference_resources().
- *
- * Calling this is not necessary (or even possible) if the higher-level function
- * wimlib_reference_resource_files() is used.
- *
- * @param wim
- * See corresponding parameter to wimlib_reference_resources().
- * @param resource_wims
- * See corresponding parameter to wimlib_reference_resources().
- * @param num_resource_wims
- * See corresponding parameter to wimlib_reference_resources().
- *
- * @return 0 on success; nonzero on error.
- *
- * @retval ::WIMLIB_ERR_INVALID_PARAM
- * Not all entries in @p resource_wims specify valid ::WIMStruct's that are
- * referenced by @p wim.
- */
-extern int
-wimlib_unreference_resources(WIMStruct *wim, WIMStruct **resource_wims,
- unsigned num_resource_wims);
-
/**
* Update a WIM image by adding, deleting, and/or renaming files or directories.
*
* with @p wim, or some file resources in @p wim refer to files in the
* outside filesystem, and a read error occurred when reading one of these
* files.
+ * @retval ::WIMLIB_ERR_RESOURCE_NOT_FOUND
+ * A stream that needed to be written could not be found in the stream
+ * lookup table of @p wim. This error can occur if, for example, @p wim is
+ * part of a split WIM but needed resources from the other split WIM parts
+ * were not referenced with wimlib_reference_resources() or
+ * wimlib_reference_resource_files() before the call to wimlib_write().
* @retval ::WIMLIB_ERR_WRITE
* An error occurred when trying to write data to the new WIM file.
*
git://wimlib.net / wimlib / blobdiff