-.TH WIMLIB-IMAGEX "1" "December 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "March 2014" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
.SH NAME
@IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
.SH SYNOPSIS
Extended attributes. This mainly includes extensions to the traditional UNIX
security model, such as SELinux security labels, POSIX ACLs, and capabilities
labels.
+.IP \[bu]
+Linux file attributes, as can be changed using the \fBchattr\fR (1) utility.
+.PP
+Notes: Timestamps are stored with 100 nanosecond granularity and include last
+modification time (mtime) and last access time (atime), but not last status
+change time (ctime). Hard links and symbolic links are supported by the WIM
+format and \fIare\fR stored. Symbolic links are turned into "native" Windows
+symbolic links, or "reparse points"; this process is fully reversible, e.g.
+automatically by \fB@IMAGEX_PROGNAME@ apply\fR, unless the symbolic link target
+contains backslash characters.
.PP
-Notes: hard links and symbolic links are supported by the WIM format and
-\fIare\fR stored. (Symbolic links are turned into "native" Windows symbolic
-links via reparse points; this process is reversible, e.g. automatically by
-\fB@IMAGEX_PROGNAME@ apply\fR.) Timestamps are stored with 100 nanosecond
-granularity and include last modification time (mtime) and last access time
-(atime), but not last status change time (ctime).
+Pedantic note: A limitation of the WIM format prevents the unusual case where a
+single symbolic link file itself has multiple names (hard links); in this
+unlikely case, each symbolic link is stored as an independent file.
.SH NTFS VOLUME CAPTURE (UNIX)
This section documents how \fB@IMAGEX_PROGNAME@\fR captures files directly from
an NTFS volume image on UNIX-like systems.
filesystem. One exception is that since encrypted files are stored as
encrypted, their data will not be available if restored on a Windows system
that does not have the decryption key.
+.PP
+Pedantic note: since Windows is not fully compatible with its own filesystem
+(NTFS), on Windows wimlib cannot archive certain files that may exist on a valid
+NTFS filesystem but are inaccessible to the Windows API, for example two files
+with names differing only in case in the same directory, or a file whose name
+contains certain characters considered invalid by Windows. If you run into
+problems archiving such files consider using the \fBNTFS VOLUME CAPTURE
+(UNIX)\fR mode from Linux.
.SH OPTIONS
.TP 6
\fB--boot\fR
.IP ""
You may also specify the actual names of the compression algorithms, "XPRESS"
and "LZX", instead of "fast" and "maximum", respectively.
+.IP ""
+As of wimlib v1.6.0, a third compression type, "recovery" or "LZMS", is also
+available. Its use is generally not recommended because other than wimlib
+itself, as of Windows 8 it is only compatible with WIMGAPI and Windows Setup
+(not even ImageX or Dism). However, LZMS is the compression algorithm used in
+packed resources created if the \fB--pack-streams\fR option is specified.
.TP
\fB--compress-slow\fR
-Like \fB--compress\fR=\fImaximum\fR, but spend even more time compressing the
-data to achieve a very slightly better compression ratio.
+Spend even more time compressing the data to achieve a very slightly better
+compression ratio. This currently only has an effect for LZX ("maximum", the
+default) and LZMS ("recovery") compression.
.TP
\fB--chunk-size\fR=\fISIZE\fR
-Set the WIM compression chunk size to \fISIZE\fR. Using this option is not
-recommended because WIM chunk sizes other than the default of 32768 are not
-supported by Microsoft's software. But if you decide to use this option
-regardless, you can choose a chunk size that is any power of 2 greater than or
-equal to 2^15 (32768) up to 2^21 (2097152) for LZX ("maximum") compression or
-2^26 (67108864) for XPRESS ("fast") compression. Larger chunks mean larger LZ77
-dictionaries and better compression ratios on sufficiently large files, but
-slower random access.
+Set the WIM compression chunk size to \fISIZE\fR. Larger chunks mean larger
+LZ77 dictionaries and better compression ratios on sufficiently large files, but
+slower random access. \fBUsing this option is generally not recommended because
+of the compatibility limitations detailed in the next paragraph.\fR But if you
+decide to use this option regardless, you may choose a chunk size that is a
+power of 2 greater than or equal to 2^15 (32768) up to a maximum determined by
+the compression format. For LZX ("maximum") compression, the maximum allowed
+chunk size is 2^21 (2097152), and for XPRESS ("fast") and LZMS ("recovery")
+compression, the maximum allowed chunk size is 2^30 (1073741824).
+.IP ""
+For XPRESS and LZX compression, Microsoft's implementation (as of Windows 8)
+does not appear to support alternate chunk sizes; although it will still open
+such files, it will crash, extract the data incorrectly, or report that the data
+is invalid. For LZMS compression, Microsoft's implementation (as of Windows 8)
+appears to only support chunk sizes that are powers of 2 between 2^15 (32768)
+and 2^20 (1048576) inclusively. In addition, wimlib versions before 1.6.0 do
+not support alternate chunk sizes.
+.TP
+\fB--pack-streams\fR, \fB--solid\fR
+Create a "solid" archive that compresses multiple unique streams ("files")
+together, rather than each unique stream ("file") independently. This can
+result in a significantly better compression ratio, but this format greatly
+decreases the performance of random access to the data, as may occur on a WIM
+mounted with \fB@IMAGEX_PROGNAME@ mount\fR. Also, WIMs created using this
+option use a different version number in their header and as of Windows 8 are
+only compatible with Windows Setup and WIMGAPI, not even ImageX and Dism.
+.IP ""
+Packed resources use a compression type and chunk size that is independent of
+the WIM's "default compression type" and "default chunk size" (which may be
+adjusted by the \fB--compress\fR and \fB--chunk-size\fR options, respectively).
+For compatibility reasons, \fB@IMAGEX_PROGNAME@ capture\fR currently has no
+option to change the compression type used in packed resources; however, the
+\fB--pack-chunk-size\fR option may be used to set the chunk size.
+.TP
+\fB--pack-chunk-size\fR=\fISIZE\fR, \fB--solid-chunk-size\fR=\fISIZE\fR
+Like \fB--chunk-size\fR, but set the chunk size used in packed resources. The
+compression format is LZMS, so the chunk size can be any power of 2 between 2^15
+and 2^30, inclusively. WIMGAPI (Windows 8) appears to be compatible with these
+sizes up to 2^26 inclusively, despite not being compatible with sizes greater
+than 2^20 in non-packed resources. The default is currently 2^25 (33554432).
+Note: currently, the LZMS compression algorithm uses about 15 times the chunk
+size in memory per thread, which is about 500 MB per thread for the default pack
+chunk size of 2^25 or 1 GB per thread if you change it to 2^26 (67108864).
.TP
\fB--threads\fR=\fINUM_THREADS\fR
Number of threads to use for compressing data. Default: autodetect (number of
Pipable WIMs are incompatible with Microsoft's software. Pipable WIMs are
created only if \fIWIMFILE\fR was specified as "-" (standard output) or if
the \fB--pipable\fR flag was specified.
+.IP \[bu]
+WIMs captured with a non-default chunk size (with the \fB--chunk-size\fR option)
+or as solid archives (with the \fB--pack-streams\fR option) or with LZMS
+compression (with \fB--compress\fR=LZMS or \fB--compress\fR=recovery) have
+varying levels of compatibility with Microsoft's software. The best
+compatibility is achieved with WIMGAPI itself (not ImageX or Dism) on Windows 8
+or later.
.SH EXAMPLES
First example: Create a new WIM 'mywim.wim' with "maximum" (LZX) compression
that will contain a captured image of the directory tree 'somedir'. Note that
abbreviated form can be used:
.RS
.PP
-wimcapture somedir mywim.wim
+wimcapture somedir mywim.wim --compress=maximum
.RE
.PP
The remaining examples will use the long form, however. Next, append the image