* 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
/** 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_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);
git://wimlib.net / wimlib / blobdiff