* produce a better compression ratio, and work more quickly, than the
* implementation in Microsoft's WIMGAPI (as of Windows 8.1). There is
* limited support for non-default compression levels, but compression
- * will be noticably faster if you choose a level < 35.
+ * will be noticeably faster if you choose a level < 35.
*
* If using wimlib_create_compressor() to create an LZMS compressor
* directly, the @p max_block_size parameter may be any positive value
uint64_t completed_streams;
/** The number of threads being used for data compression; or,
- * if no compression is being peformed, this will be 1. */
+ * if no compression is being performed, this will be 1. */
uint32_t num_threads;
/** The compression type being used, as one of the
#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
/**
- * EXPERIMENTAL, Windows-only: compress the extracted files using System
- * Compression, when possible. This only works on either Windows 10 or later,
- * or on an older Windows to which Microsoft's wofadk.sys driver has been added.
- * Several different compression formats may be used with System Compression;
- * this particular flag selects the XPRESS compression format with 4096 byte
- * chunks. <b>This flag is currently experimental and may be changed or removed
- * in future releases of wimlib.</b> */
+ * Since wimlib v1.8.2 and Windows-only: compress the extracted files using
+ * System Compression, when possible. This only works on either Windows 10 or
+ * later, or on an older Windows to which Microsoft's wofadk.sys driver has been
+ * added. Several different compression formats may be used with System
+ * Compression; this particular flag selects the XPRESS compression format with
+ * 4096 byte chunks.
+ */
#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000
/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
- * 8192 byte chunks. <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b> */
+ * 8192 byte chunks. */
#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000
/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with
- * 16384 byte chunks. <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b> */
+ * 16384 byte chunks. */
#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000
/** Like ::WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with
- * 32768 byte chunks. <b>This flag is currently experimental and may be changed
- * or removed in future releases of wimlib.</b> */
+ * 32768 byte chunks. */
#define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000
/** @} */
#define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES 0x00002000
/**
- * Do not consider content similarily when arranging file data for solid
+ * Do not consider content similarity when arranging file data for solid
* compression. Providing this flag will typically worsen the compression
* ratio, so only provide this flag if you know what you are doing.
*/
#define WIMLIB_WRITE_FLAG_NO_SOLID_SORT 0x00004000
+/**
+ * Since wimlib v1.8.3 and for wimlib_overwrite() only: <b>unsafely</b> compact
+ * the WIM file in-place, without appending. Existing resources are shifted
+ * down to fill holes and new resources are appended as needed. The WIM file is
+ * truncated to its final size, which may shrink the on-disk file. <b>This
+ * operation cannot be safely interrupted. If the operation is interrupted,
+ * then the WIM file will be corrupted, and it may be impossible (or at least
+ * very difficult) to recover any data from it. Users of this flag are expected
+ * to know what they are doing and assume responsibility for any data corruption
+ * that may result.</b>
+ *
+ * If the WIM file cannot be compacted in-place because of its structure, its
+ * layout, or other requested write parameters, then wimlib_overwrite() fails
+ * with ::WIMLIB_ERR_COMPACTION_NOT_POSSIBLE, and the caller may wish to retry
+ * the operation without this flag.
+ */
+#define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT 0x00008000
+
/** @} */
/** @addtogroup G_general
* @{ */
#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001
/** Windows-only: do not attempt to acquire additional privileges (currently
- * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, and
- * SeTakeOwnershipPrivilege) when initializing the library. This flag is
- * intended for the case where the calling program manages these privileges
- * itself. Note: by default, no error is issued if privileges cannot be
- * acquired, although related errors may be reported later, depending on if the
- * operations performed actually require additional privileges or not. */
+ * SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege,
+ * SeTakeOwnershipPrivilege, and SeManageVolumePrivilege) when initializing the
+ * library. This flag is intended for the case where the calling program
+ * manages these privileges itself. Note: by default, no error is issued if
+ * privileges cannot be acquired, although related errors may be reported later,
+ * depending on if the operations performed actually require additional
+ * privileges or not. */
#define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002
/** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified,
WIMLIB_ERR_INVALID_UTF8_STRING = 31,
WIMLIB_ERR_IS_DIRECTORY = 32,
WIMLIB_ERR_IS_SPLIT_WIM = 33,
- WIMLIB_ERR_LIBXML_UTF16_HANDLER_NOT_AVAILABLE = 34,
WIMLIB_ERR_LINK = 35,
WIMLIB_ERR_METADATA_NOT_FOUND = 36,
WIMLIB_ERR_MKDIR = 37,
WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79,
WIMLIB_ERR_NOT_A_MOUNTPOINT = 80,
WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81,
- WIMLIB_ERR_FVE_LOCKED_VOLUME = 82,
+ WIMLIB_ERR_FVE_LOCKED_VOLUME = 82,
WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83,
+ WIMLIB_ERR_WIM_IS_INCOMPLETE = 84,
+ WIMLIB_ERR_COMPACTION_NOT_POSSIBLE = 85,
+ WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES = 86,
+ WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87,
};
*
* Export an image, or all images, from a ::WIMStruct into another ::WIMStruct.
*
- * Note: after calling this function, the exported WIM image(s) cannot be
- * independently modified because the image metadata will be shared between the
- * two ::WIMStruct's. In addition, @p dest_wim will depend on @p src_wim, so @p
- * src_wim cannot be freed until @p dest_wim is ready to be freed as well.
+ * Specifically, if the destination ::WIMStruct contains <tt>n</tt> images, then
+ * the source image(s) will be appended, in order, starting at destination index
+ * <tt>n + 1</tt>. By default, all image metadata will be exported verbatim,
+ * but certain changes can be made by passing appropriate parameters.
*
- * Note: no changes are committed to disk until wimlib_write() or
- * wimlib_overwrite() is called.
+ * wimlib_export_image() is only an in-memory operation; no changes are
+ * committed to disk until wimlib_write() or wimlib_overwrite() is called.
+ *
+ * A limitation of the current implementation of wimlib_export_image() is that
+ * the directory tree of a source or destination image cannot be updated
+ * following an export until one of the two images has been freed from memory.
*
* @param src_wim
* The WIM from which to export the images, specified as a pointer to the
*
* @return 0 on success; a ::wimlib_error_code value on failure.
*
+ * @retval ::WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE
+ * One or more of the source images had already been exported into the
+ * destination WIM.
* @retval ::WIMLIB_ERR_IMAGE_NAME_COLLISION
* One or more of the names being given to an exported image was already in
* use in the destination WIM.
/**
* @ingroup G_general
*
- * Free all memory allocated for a WIMStruct and close all files associated with
- * it.
+ * Release a reference to a ::WIMStruct. If the ::WIMStruct is still referenced
+ * by other ::WIMStruct's (e.g. following calls to wimlib_export_image() or
+ * wimlib_reference_resources()), then the library will free it later, when the
+ * last reference is released; otherwise it is freed immediately and any
+ * associated file descriptors are closed.
*
* @param wim
- * Pointer to the ::WIMStruct to free. If @c NULL, no action is taken.
+ * Pointer to the ::WIMStruct to release. If @c NULL, no action is taken.
*/
extern void
wimlib_free(WIMStruct *wim);
/**
* @ingroup G_wim_information
*
- * Get a per-image property from the WIM's XML document. This is an alternative
- * to wimlib_get_image_name() and wimlib_get_image_descripton() which allows
- * getting any simple string property.
+ * Since wimlib v1.8.3: get a per-image property from the WIM's XML document.
+ * This is an alternative to wimlib_get_image_name() and
+ * wimlib_get_image_description() which allows getting any simple string
+ * property.
*
* @param wim
* Pointer to the ::WIMStruct for the WIM.
* element. The <tt>[</tt> character is reserved for future use.
*
* @return
- * The property's value as a wimlib_tchar string, or @c NULL if there is no
- * such property. The string may not remain valid after later library
+ * The property's value as a ::wimlib_tchar string, or @c NULL if there is
+ * no such property. The string may not remain valid after later library
* calls, so the caller should duplicate it if needed.
*/
extern const wimlib_tchar *
* Another process is currently modifying the WIM file.
* @retval ::WIMLIB_ERR_FUSE
* A non-zero status code was returned by @c fuse_main().
+ * @retval ::WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES
+ * There are currently multiple references to the WIM image as a result of
+ * a call to wimlib_export_image(). Free one before attempting the
+ * read-write mount.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
* @p image does not exist in @p wim.
* @retval ::WIMLIB_ERR_INVALID_PARAM
* @retval ::WIMLIB_ERR_WIM_IS_ENCRYPTED
* The WIM cannot be opened because it contains encrypted segments. (It
* may be a Windows 8 "ESD" file.)
+ * @retval ::WIMLIB_ERR_WIM_IS_INCOMPLETE
+ * The WIM file is not complete (e.g. the program which wrote it was
+ * terminated before it finished)
* @retval ::WIMLIB_ERR_WIM_IS_READONLY
* ::WIMLIB_OPEN_FLAG_WRITE_ACCESS was specified but the WIM file was
* considered read-only because of any of the reasons mentioned in the
/**
* @ingroup G_writing_and_overwriting_wims
*
- * Commit a ::WIMStruct to disk, overwriting its backing file or appending to it
- * as needed.
+ * Commit a ::WIMStruct to disk, updating its backing file.
*
- * There are two alternative ways in which changes may be committed:
+ * There are several alternative ways in which changes may be committed:
*
* 1. Full rebuild: write the updated WIM to a temporary file, then rename the
* temporary file to the original.
* 2. Appending: append updates to the new original WIM file, then overwrite
* its header such that those changes become visible to new readers.
- *
- * Append mode is often much faster, but it wastes some amount of space due to
- * leaving "holes" in the WIM file. Because of the greater efficiency,
- * wimlib_overwrite() normally defaults to append mode. However,
- * ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full rebuild.
- * In addition, if wimlib_delete_image() has been used on the ::WIMStruct, then
- * the default mode switches to rebuild mode, and
+ * 3. Compaction: normally should not be used; see
+ * ::WIMLIB_WRITE_FLAG_UNSAFE_COMPACT for details.
+ *
+ * Append mode is often much faster than a full rebuild, but it wastes some
+ * amount of space due to leaving "holes" in the WIM file. Because of the
+ * greater efficiency, wimlib_overwrite() normally defaults to append mode.
+ * However, ::WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full
+ * rebuild. In addition, if wimlib_delete_image() has been used on the
+ * ::WIMStruct, then the default mode switches to rebuild mode, and
* ::WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append
* mode.
*
* @param ref_flags
* Reserved; must be 0.
*
- * @return 0 on success; a ::wimlib_error_code value on failure. 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().
+ * @return 0 on success; a ::wimlib_error_code value on failure.
*/
extern int
wimlib_reference_resources(WIMStruct *wim, WIMStruct **resource_wims,
/**
* @ingroup G_modifying_wims
*
- * Add, modify, or remove a per-image property from the WIM's XML document.
- * This is an alternative to wimlib_set_image_name(),
+ * Since wimlib v1.8.3: add, modify, or remove a per-image property from the
+ * WIM's XML document. This is an alternative to wimlib_set_image_name(),
* wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows
* manipulating any simple string property.
*
* @retval ::WIMLIB_ERR_FVE_LOCKED_VOLUME
* Windows-only: One of the "add" commands attempted to add files from an
* encrypted BitLocker volume that hasn't yet been unlocked.
+ * @retval ::WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES
+ * There are currently multiple references to the WIM image as a result of
+ * a call to wimlib_export_image(). Free one before attempting the update.
* @retval ::WIMLIB_ERR_INVALID_CAPTURE_CONFIG
* The contents of a capture configuration file were invalid.
* @retval ::WIMLIB_ERR_INVALID_IMAGE
git://wimlib.net / wimlib / blobdiff