* contain this information. Please note that this flag is for convenience
* only; Microsoft's @a imagex.exe will not understand this special information.
* This flag cannot be combined with ::WIMLIB_ADD_FLAG_NTFS. */
-#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
+#define WIMLIB_ADD_FLAG_UNIX_DATA 0x00000010
/** Do not capture security descriptors. Only has an effect in NTFS capture
* mode, or in Win32 native builds. */
* documentation for ::WIMLIB_ADD_FLAG_RPFIX. */
#define WIMLIB_ADD_FLAG_NORPFIX 0x00000200
-/** Do not exclude unsupported files or directories from capture; e.g. encrypted
- * directories in NTFS-3g capture mode, or device files and FIFOs on UNIX-like
- * systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when such a file
- * is encountered. */
+/** Do not automatically exclude unsupported files or directories from capture;
+ * e.g. encrypted directories in NTFS-3g capture mode, or device files and FIFOs
+ * on UNIX-like systems. Instead, fail with ::WIMLIB_ERR_UNSUPPORTED_FILE when
+ * such a file is encountered. */
#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE 0x00000400
+/** Automatically select a capture configuration appropriate for capturing
+ * filesystems containing Windows operating systems. When this flag is
+ * specified, the corresponding @p config parameter or member must be @c NULL.
+ *
+ * Currently, selecting this capture configuration will cause the following
+ * files and directories to be excluded from capture:
+ *
+ * - "\$ntfs.log"
+ * - "\hiberfil.sys"
+ * - "\pagefile.sys"
+ * - "\System Volume Information"
+ * - "\RECYCLER"
+ * - "\Windows\CSC"
+ *
+ * Note that the default behavior--- that is, when this flag is not specified
+ * and @p config is @c NULL--- is to use no capture configuration, meaning that
+ * no files are excluded from capture.
+ */
+#define WIMLIB_ADD_FLAG_WINCONFIG 0x00000800
#define WIMLIB_ADD_IMAGE_FLAG_NTFS WIMLIB_ADD_FLAG_NTFS
#define WIMLIB_ADD_IMAGE_FLAG_DEREFERENCE WIMLIB_ADD_FLAG_DEREFERENCE
#define WIMLIB_ADD_IMAGE_FLAG_NORPFIX WIMLIB_ADD_FLAG_NORPFIX
#define WIMLIB_ADD_IMAGE_FLAG_NO_UNSUPPORTED_EXCLUDE \
WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE
+#define WIMLIB_ADD_IMAGE_FLAG_WINCONFIG WIMLIB_ADD_FLAG_WINCONFIG
/******************************
* WIMLIB_DELETE_FLAG_*
/** Read the WIM file sequentially while extracting the image. */
#define WIMLIB_EXTRACT_FLAG_SEQUENTIAL 0x00000010
-/** Extract special UNIX data captured with ::WIMLIB_ADD_FLAG_UNIX_DATA.
- * Cannot be used with ::WIMLIB_EXTRACT_FLAG_NTFS. */
+/** Extract special UNIX data captured with ::WIMLIB_ADD_FLAG_UNIX_DATA. Only
+ * valid on UNIX-like platforms, and when ::WIMLIB_EXTRACT_FLAG_NTFS was not
+ * specified. */
#define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020
/** Do not extract security descriptors. */
* create symbolic links. */
#define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000
-/** TODO */
+/** TODO: this flag is intended to allow resuming an aborted extraction, but the
+ * behavior is currently less than satisfactory. Do not use (yet). */
#define WIMLIB_EXTRACT_FLAG_RESUME 0x00010000
-
/******************************
* WIMLIB_MOUNT_FLAG_*
******************************/
* causes the raw data of the WIM file, divided into 10 MB chunks, to be
* checksummed and checked against the SHA1 message digests specified in the
* integrity table. ::WIMLIB_ERR_INTEGRITY is returned if there are any
- * mismatches. */
+ * mismatches (or, ::WIMLIB_ERR_INVALID_INTEGRITY_TABLE is returned if the
+ * integrity table is invalid). */
#define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY 0x00000001
-/** Do not issue an error if the WIM is part of a split WIM. */
+/** Do not issue an error if the WIM is part of a split WIM. Programs must
+ * specify this flag if they intend to open part of a split WIM, rather than
+ * only supporting standalone WIMs. */
#define WIMLIB_OPEN_FLAG_SPLIT_OK 0x00000002
/** Check if the WIM is writable and return ::WIMLIB_ERR_WIM_IS_READONLY if it
* is not. A WIM is considered writable only if it is writable at the
* filesystem level, does not have the WIM_HDR_FLAG_READONLY flag set in its
* header, and is not part of a spanned set. It is not required to provide this
- * flag to make changes to the WIM, but with this flag you get the error sooner
- * rather than later. */
+ * flag before attempting to make changes to the WIM, but with this flag you get
+ * an error sooner rather than later. */
#define WIMLIB_OPEN_FLAG_WRITE_ACCESS 0x00000004
/******************************
* WIMLIB_UNMOUNT_FLAG_*
******************************/
-/** Include an integrity table in the WIM after it's been unmounted. Ignored
- * for read-only mounts. */
+/** See ::WIMLIB_WRITE_FLAG_CHECK_INTEGRITY. */
#define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001
/** Unless this flag is given, changes to a read-write mounted WIM are
- * discarded. Ignored for read-only mounts. */
+ * discarded. Ignored for read-only mounts. */
#define WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002
-/** See ::WIMLIB_WRITE_FLAG_REBUILD */
+/** See ::WIMLIB_WRITE_FLAG_REBUILD. */
#define WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004
/** See ::WIMLIB_WRITE_FLAG_RECOMPRESS */
#define WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008
-/** Do a "lazy" unmount (detach filesystem immediately, even if busy) */
+/** Do a "lazy" unmount (detach filesystem immediately, even if busy). */
#define WIMLIB_UNMOUNT_FLAG_LAZY 0x00000010
/******************************
******************************/
/** Send ::WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and
- * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */
+ * ::WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. */
#define WIMLIB_UPDATE_FLAG_SEND_PROGRESS 0x00000001
/******************************
* 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 referenced. This is probably not what you want, because almost no
- * space will be saved by deleting an image in this way. */
+ * space will be saved by deleting an image in this way. */
#define WIMLIB_WRITE_FLAG_SOFT_DELETE 0x00000080
/** wimlib_overwrite() only: Allow overwriting the WIM even if the readonly
******************************/
/** Assume that strings are represented in UTF-8, even if this is not the
- * locale's character encoding. Not used on Windows. */
+ * locale's character encoding. This flag is ignored on Windows, where wimlib
+ * always uses UTF-16LE. */
#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001
/** Windows-only: do not attempt to acquire additional privileges (currently
* 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,
+ * return ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed
+ * to read all possible data and metadata for a capture operation could not be
+ * acquired. Can be combined with ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES.
+ */
+#define WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES 0x00000004
+
+/** Windows only: If ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified,
+ * return ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed
+ * to restore all possible data and metadata for an apply operation could not be
+ * acquired. Can be combined with ::WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES.
+ */
+#define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008
+
/** Specification of an update to perform on a WIM image. */
struct wimlib_update_command {
wimlib_tchar *wim_target_path;
/** Configuration for excluded files. @c NULL means
- * exclude no files. */
+ * exclude no files (use no configuration), unless
+ * ::WIMLIB_ADD_FLAG_WINCONFIG is specified in @p
+ * add_flags. */
struct wimlib_capture_config *config;
/** Bitwise OR of WIMLIB_ADD_FLAG_* flags. */
WIMLIB_ERR_ICONV_NOT_AVAILABLE,
WIMLIB_ERR_IMAGE_COUNT,
WIMLIB_ERR_IMAGE_NAME_COLLISION,
+ WIMLIB_ERR_INSUFFICIENT_PRIVILEGES,
WIMLIB_ERR_INTEGRITY,
WIMLIB_ERR_INVALID_CAPTURE_CONFIG,
WIMLIB_ERR_INVALID_CHUNK_SIZE,
* but you should not rely on this behavior.)
*
* @param init_flags
- * Bitwise OR of ::WIMLIB_INIT_FLAG_ASSUME_UTF8 and/or
- * ::WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES.
+ * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG.
+ *
+ * @return 0 on success; nonzero on failure. Currently, only the following
+ * error code is defined:
*
- * @return 0; other error codes may be returned in future releases.
+ * @retval ::WIMLIB_ERR_INSUFFICIENT_PRIVILEGES
+ * ::WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES and/or
+ * ::WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES were specified in @p
+ * init_flags, but the corresponding privileges could not be acquired.
*/
extern int
wimlib_global_init(int init_flags);
* parts have the same GUID and compression type.
*
* Note: wimlib_export_image() can provide similar functionality to
- * wimlib_join(), since it is possible to export all images from a split WIM.
- * Actually, wimlib_join() currently calls wimlib_export_image internally.
+ * wimlib_join(), since it is possible to export all images from a split WIM
+ * into a new ::WIMStruct, then write it. However, wimlib_join() may have
+ * better performance than this method.
*/
extern int
wimlib_join(const wimlib_tchar * const *swms,
extern int
wimlib_print_metadata(WIMStruct *wim, int image) _wimlib_deprecated;
+/**
+ * Declares that a newly added image is mostly the same as a prior image, but
+ * captured at a later point in time, possibly with some modifications in the
+ * 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 is provided to optimize incremental backups. The resulting WIM
+ * file will still be the same regardless of whether this function is called.
+ * (This is, however, assuming that timestamps have not been manipulated or
+ * unmaintained as to trick this function into thinking a file has not been
+ * modified when really it has. To partly guard against such cases, other
+ * metadata such as file sizes will be checked as well.)
+ *
+ * This function must be called after adding the new image (e.g. with
+ * wimlib_add_image()), but before writing the updated WIM file (e.g. with
+ * wimlib_overwrite()).
+ *
+ * @p wim
+ * Pointer to the ::WIMStruct for a WIM.
+ * @p new_image
+ * 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().
+ * @p template_image
+ * 1-based index in the WIM of a template image that reflects a prior state
+ * of the directory tree being captured.
+ * @p flags
+ * Reserved; must be 0.
+ * @p progress_func
+ * Currently ignored, but reserved for a function that will be called with
+ * information about the operation. Use NULL if no additional information
+ * is desired.
+ *
+ * @return 0 on success; nonzero on error.
+ *
+ * @retval ::WIMLIB_ERR_INVALID_IMAGE
+ * @p new_image and/or @p template_image were not a valid image indices in
+ * the WIM.
+ * @retval ::WIMLIB_ERR_NOMEM
+ * Failed to allocate needed memory.
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ * @p new_image was equal to @p template_image, or @p new_image specified
+ * an image that had not been modified since opening the WIM.
+ *
+ * This function can additionally return ::WIMLIB_ERR_DECOMPRESSION,
+ * ::WIMLIB_ERR_INVALID_METADATA_RESOURCE, ::WIMLIB_ERR_NOMEM,
+ * ::WIMLIB_ERR_READ, or ::WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which
+ * indicate failure (for different reasons) to read the metadata resource for
+ * the template image.
+ */
+extern int
+wimlib_reference_template_image(WIMStruct *wim, int new_image,
+ 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
* the number of the image. The images are numbered starting at 1.
* 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_SPLIT_UNSUPPORTED
- * @p wim is part of a split WIM, not a standalone WIM.
* @retval ::WIMLIB_ERR_WRITE
* An error occurred when trying to write data to the new WIM file.
*/
git://wimlib.net / wimlib / blobdiff