imagex-apply.1.in: Document encrypted/sparse limitations

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index 21907621c757c2efdc99ecb14abf6eb9c91d1e09..2612870711b4a9cc18f88d33adfc39aec0b1f36c 100644 (file)
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -74,7 +74,9 @@ Notes: Unsupported data and metadata is simply not extracted, but
 image can't be exactly represented when extracted.  Last access and last
 modification timestamps are specified to 100 nanosecond granularity in the WIM
 file, but will only be extracted to the highest precision supported by the
-underlying operating system, C library, and filesystem.
+underlying operating system, C library, and filesystem.  Compressed files will
+be extracted as uncompressed, while encrypted files will not be extracted at
+all.
 .SH NTFS VOLUME EXTRACTION (UNIX)
 This section documents how \fB@IMAGEX_PROGNAME@ apply\fR extracts a WIM image
 directly to an NTFS volume image on UNIX-like systems.  See \fBDIRECTORY EXTRACTION
@@ -118,11 +120,16 @@ DOS/Windows file attribute flags.
 All names of all files, including names in the Win32 namespace, DOS namespace,
 Win32+DOS namespace, and POSIX namespace.  This includes hard links.
 .PP
-Currently, the only known limitation (in terms of exactly extracting all data
-and metadata) is that the extraction of encrypted files is not expected to work
-properly.
+However, there are also several known limitations of the NTFS volume extraction
+mode:
+.IP \[bu] 4
+Encrypted files will not be extracted.
+.IP \[bu]
+Although sparse file attributes will be applied, the full data will be extracted
+to each sparse file, so extracted "sparse" files may not actually contain any
+sparse regions.
 .PP
-Since all (or almost all) information from the WIM image is restored in this
+Regardless, since almost all information from the WIM image is restored in this
 mode, it is possible to restore an image of an actual Windows installation using
 \fB@IMAGEX_PROGNAME@\fR on UNIX-like systems in addition to with
 \fB@IMAGEX_PROGNAME@\fR on Windows.  In the examples at the end of this manual
@@ -215,10 +222,10 @@ above not being supported by the target filesystem.
 .IP \[bu]
 Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
 plaintext in the WIM image, \fB@IMAGEX_PROGNAME@\fR cannot restore encrypted
-files to filesystems not supporting encryption.  (The current behavior is to
-just extract the encrypted data anyway.)  Furthermore, even if encrypted files
-are restored to a filesystem that supports encryption, they will only be
-decryptable if the decryption key is available.
+files to filesystems not supporting encryption.  Therefore, such files are not
+extracted.  Furthermore, even if encrypted files are restored to a filesystem
+that supports encryption, they will only be decryptable if the decryption key is
+available.
 .IP \[bu]
 Files with names that cannot be represented on Windows will not
 be extracted by default; see \fB--include-invalid-names\fR.

diff --git a/include/wimlib.h b/include/wimlib.h
index f3b395f9cd80eb0e719184083b5dde8d3a9230da..1655f5c6ec918ebf1f2238309950cb4d9f36e275 100644 (file)
--- a/include/wimlib.h
+++ b/include/wimlib.h
@@ -925,7 +925,7 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour
 
 /** Call the progress function with the message
  * ::WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file is starting to
- * be scanned. */
+ * be scanned, or when a directory or file is being excluded from capture.  */
 #define WIMLIB_ADD_FLAG_VERBOSE                        0x00000004
 
 /** Mark the image being added as the bootable image of the WIM. */
@@ -2975,9 +2975,11 @@ wimlib_unmount_image(const wimlib_tchar *dir,
  * @retval ::WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED
  *     (Windows only) Failed to perform a reparse point fixup because of
  *     problems with the data of a reparse point.
- * @retval ::WIMLIB_ERR_SPECIAL_FILE
+ * @retval ::WIMLIB_ERR_UNSUPPORTED_FILE
  *     While executing an add command, attempted to capture a file that was not
- *     a supported file type (e.g. a device file).
+ *     a supported file type (e.g. a device file).  Only if
+ *     ::WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified in @p the add_flags
+ *     for an update command.
  * @retval ::WIMLIB_ERR_STAT
  *     While executing an add command, failed to get attributes for a file or
  *     directory.