Update NEWS, docs
[wimlib] / doc / imagex-apply.1.in
index 0c8ceec8f711fc05aa4e6ef6334922f6c99c6e49..06caf05e9bf5deb86b3f03dfc997e8094d1d1c72 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH IMAGEX "1" "September 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
 .SH NAME
 imagex apply \- Extract one image, or all images, from a WIM archive
 
@@ -11,32 +11,33 @@ imagex apply \- Extract one image, or all images, from a WIM archive
 \fBimagex apply\fR extracts an image, or all images, from the Windows Imaging
 (WIM) file \fIWIMFILE\fR.
 
-\fIIMAGE\fR specifies the image to extract.  It may be a 1-based index of an
+\fIIMAGE\fR specifies the WIM image to extract.  It may be a 1-based index of an
 image in the WIM, the name of an image in the WIM, or the keyword "all" to
 indicate that all images are to be extracted.  Use the \fBimagex info\fR (1)
 command to show what images a WIM file contains.
 
-\fBTARGET\fR specifies where to extract the WIM image(s) to.  If \fBTARGET\fR
+\fITARGET\fR specifies where to extract the WIM image(s) to.  If \fITARGET\fR
 specifies a directory, the WIM image(s) are extracted to that directory.  If
-\fBTARGET\fR specifies a non-existent file, a directory is created in that
-location and the WIM image(s) are extracted to that directory.  If \fBTARGET\fR
+\fITARGET\fR specifies a non-existent file, a directory is created in that
+location and the WIM image(s) are extracted to that directory.  If \fITARGET\fR
 specifies a regular file or block device, it is interpreted as a NTFS volume to
 which the WIM image is to be extracted.
 
 .SH NORMAL MODE
 
-The normal extraction mode is entered when \fBTARGET\fR is a directory or
+The normal extraction mode is entered when \fITARGET\fR is a directory or
 non-existent file.  If a single WIM image is being extracted, it will be
 extracted with the root of the image corresponding to the directory named by
-\fBTARGET\fR; or, if the keyword \fBall\fR is given, the images are extracted
+\fITARGET\fR; or, if the keyword \fBall\fR is given, the images are extracted
 into subdirectories of \fITARGET\fR that will be named after the image names,
 falling back to the image indices if there is an image with no name.
+\fITARGET\fR can specify a directory on any type of filesystem.
 
 In the normal mode of extraction, the following information will be extracted
 from the WIM image(s):
 
 .IP \[bu] 4
-The default (unnamed) data streams of each file
+The default (unnamed) data stream of each file
 .IP \[bu]
 Hard links, if supported by the underlying filesystem
 .IP \[bu]
@@ -64,11 +65,11 @@ Short (DOS) names for files
 
 .SH NTFS MODE
 
-A special extraction mode is entered when \fBTARGET\fR is a regular file or
-block device.  \fBTARGET\fR is interpreted as an NTFS volume and opened using
+A special extraction mode is entered when \fITARGET\fR is a regular file or
+block device.  \fITARGET\fR is interpreted as an NTFS volume and opened using
 libntfs-3g.  If successful, the WIM image is extracted to the root of the NTFS
 volume in a special mode that preserves all, or almost all, information
-contained in the WIM.  \fBIMAGE\fR may not be "all" for this action.
+contained in the WIM.  \fIIMAGE\fR may not be "all" for this action.
 
 The NTFS volume does not need to be empty, although it's expected that it be
 empty for the intended use cases.  A new NTFS filesystem can be created using
@@ -77,6 +78,11 @@ the \fBmkntfs\fR (8) command.
 The NTFS extraction mode is not available if wimlib was compiled using the
 --without-ntfs-3g option.
 
+Please note that the NTFS extraction mode is \fInot\fR entered if \fITARGET\fR
+is a directory, even if a NTFS filesystem is mounted on \fITARGET\fR.  You must
+specify the NTFS volume itself (and it must be unmounted, and you must have
+permission to write to it).
+
 In the NTFS extraction mode, the following information will be extracted from
 the WIM image:
 
@@ -172,6 +178,20 @@ instead.  This option is not available in the NTFS extraction mode.
 Print the path to of each file or directory within the WIM image as it is
 extracted, and some additional informational messages.
 
+.SH NOTES
+
+\fBimagex apply\fR does not yet support split WIMs.
+
+\fBimagex 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
+the WIM file.  It is an error if the message digests don't match.  It's also
+considered to be an error if any WIM resources cannot be found in the stream
+lookup table.  So you can be sure that the files are extracted correctly, even
+though we don't provide a \fB/verify\fR option like Microsoft's version of
+imagex does.  Please note that this is separate from the integrity table of the
+WIM, which provides SHA1 message digests over raw chunks of the entire WIM file
+and is checked separately if the \fB--check\fR option is specified.
+
 .SH EXAMPLES
 .SS Normal extraction mode
 Extract the first image from the Windows PE image from the Windows Vista/7/8