Document handling of invalid filenames

[wimlib] / doc / imagex-apply.1.in

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index 94ca6f5d76d326897633234f83a432bb596cc277..c7ba4c31063e6bec497d830c75835f5e7377f858 100644 (file)
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -197,6 +197,9 @@ Note: encrypted files will be extracted as raw encrypted data if the filesystem
 does not support encryption.  Compressed files and directories (with the
 compression attribute set) will be extracted as uncompressed if the filesystem
 does not support transparent compression.
+
+Additional note: files with names that cannot be represented on Windows will not
+be extracted by default; see \fB--including-invalid-names\fR.
 .SH SPLIT WIMS
 You may use \fB@IMAGEX_PROGNAME@ apply\fR to apply images from a split WIM.  The
 \fIWIMFILE\fR argument is used to specify the first part of the split WIM, and
@@ -289,6 +292,25 @@ with the SACL omitted, then only the default inherited security descriptor, if
 we do not have permission to set the desired one.  On UNIX: with
 \fB--unix-data\fR, fail immediately if the UNIX owner, group, or file mode on an
 extracted file cannot be set for any reason.
+.TP
+\fB--including-invalid-names\fR
+Extract files and directories with invalid names by replacing characters and
+appending a suffix rather than ignoring them.  The meaning of this is
+platform-dependent.
+.IP "" 6
+On UNIX, filenames are case-sensitive and may contain any byte except '\\0' and
+\'/', so on UNIX this option will only have an effect in the unlikely case that
+the WIM image for some reason has a filename containing one of these characters.
+.IP "" 6
+On Windows, filenames are case-insensitive, cannot include the characters '/',
+\'\\0', '\\', ':', '*', '?', '"', '<', '>', or '|', and cannot end with a
+space or period.  Ordinarily, files in WIM images should meet these
+conditions as well. However, it is not guaranteed, and in particular a WIM
+image captured with \fB@IMAGEX_PROGNAME@\fR on UNIX could contain such files.
+By default, invalid names will be ignored, and if there are multiple names
+differing only in case, one will be chosen to extract arbitrarily; however,
+with \fB--including-invalid-names\fR, all names will be sanitized and
+extracted in some form.
 .SH NOTES
 \fB@IMAGEX_PROGNAME@ apply\fR calculates the SHA1 message digest of every file stream it
 extracts and verifies that it is the same as the SHA1 message digest provided in