-.TH IMAGEX "1" "May 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH IMAGEX "1" "January 2013" "imagex (wimlib) wimlib @VERSION@" "User Commands"
.SH NAME
-imagex apply \- Extract one image, or all images, from a WIM archive
+imagex-apply \- Extract one image, or all images, from a WIM archive
.SH SYNOPSIS
\fBimagex apply\fR \fIWIMFILE\fR \fIIMAGE\fR \fITARGET\fR [\fIOPTION\fR]...
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.
+\fBimagex apply\fR supports applying images from stand-alone WIMs as well as
+split WIMs. See \fBSPLIT WIMS\fR.
+
.SH NORMAL MODE
-The normal extraction mode is entered when \fBTARGET\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
-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.
+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 is extracted
+with the root directory of the image corresponding to the directory named by
+\fITARGET\fR; or, if the keyword \fBall\fR is given, the images are extracted
+into subdirectories of \fITARGET\fR that are be named after the image names,
+falling back to the image index for 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):
+In the normal mode of extraction, the following information is 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
+Hard links
.IP \[bu]
File and directory creation, access, and modification timestamps to the nearest
microsecond, if supported by the underlying filesystem
.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
-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.
+A special extraction mode is entered when \fITARGET\fR is a regular file or
+block device. If this is the case, \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 almost all
+information contained in the WIM image. \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
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:
.IP \[bu]
File attribute flags are applied.
.IP \[bu]
-Short (DOS) names for files are extracted. The corresponding long name for each
-DOS name is made to be a Win32 name. Any additional names for the file in the
-same directory are made to be names in the POSIX namespace.
+Short (DOS) names for non-hard-linked files are extracted. The corresponding
+long name for each DOS name is made to be a Win32 name. Files with multiple
+hard links are extracted with filenames in the POSIX namespace, and short names
+(if any) are ignored. A singly-linked file with no short name is also extracted
+in the POSIX namespace. Note that this assigning of namespaces may not be
+exactly the same as in the original filesystem that was captured, and also this
+means that some DOS names may be lost (most likely inconsequentially).
.PP
-In the NTFS extraction mode, we restore enough information from the WIM that it
-is possible, in most cases, to restore or install an image of an actual Windows
-installation. In the examples at the end of this manual page, we show an example
-of applying an image from the "install.wim" file contained in the installation
-media for Windows Vista, Windows 7, and Windows 8 in the "sources" directory.
+Since almost all information from the WIM image is restored in the NTFS
+extraction mode, it is possible to restore an image of an actual Windows
+installation. In the examples at the end of this manual page, there is an
+example of applying an image from the "install.wim" file contained in the
+installation media for Windows Vista, Windows 7, and Windows 8 in the "sources"
+directory.
-In order to actually boot Windows from an applied image, you must understand the
-boot process of Windows versions Vista and later. Basically, it is the
+But in order to actually boot Windows from an applied image, you must understand
+the boot process of Windows versions Vista and later. Basically, it is the
following:
.nr step 1 1
bootable flag on it, and have a master boot record that loads the bootable
partition (Windows' MBR does, and SYSLINUX provides an equivalent MBR).
+.SH SPLIT WIMS
+
+You may use \fBimagex 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
+the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
+that specifies the additional parts of the split WIM. \fIGLOB\fR is expected to
+be a single string on the command line, so \fIGLOB\fR must be quoted so that it
+is protected against shell expansion. \fIGLOB\fR must expand to all parts of
+the split WIM, except optionally the first part which may either omitted or
+included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
+well).
+
+Here's an example. The names for the split WIMs usually go something like:
+
+.RS
+.PP
+.nf
+mywim.swm
+mywim2.swm
+mywim3.swm
+mywim4.swm
+mywim5.swm
+.RE
+
+To apply the first image of this split WIM to the directory "dir", run:
+.PP
+.RS
+imagex apply mywim.swm 1 dir --ref="mywim*.swm"
+.RE
+.PP
+
.SH OPTIONS
.TP 6
\fB--check\fR
.TP
\fB--hardlink\fR
When extracting a file from the WIM that is identical to a file that has already
-extracted, create a hard link using \fBlink\fR (3) rather than creating a
-separate file. This option causes all identical files to be hard-linked,
-overriding the hard link groups that are specified in the WIM image(s). In the
-case of extracting all images from the WIM, files may be hard-linked even if
-they are in different WIM images. This option is not available in the NTFS
-extraction mode.
+extracted, create a hard link rather than creating a separate file. This option
+causes all identical files to be hard-linked, overriding the hard link groups
+that are specified in the WIM image(s). In the case of extracting all images
+from the WIM, files may be hard-linked even if they are in different WIM images.
+This option is not available in the NTFS extraction mode.
.TP
\fB--symlink\fR
This option is similar to \fB--hardlink\fR, except symbolic links are created
\fB--verbose\fR
Print the path to of each file or directory within the WIM image as it is
extracted, and some additional informational messages.
+.TP
+\fB--ref\fR="\fIGLOB\fR"
+File glob of additional split WIM parts that are part of the split WIM being
+applied. See \fBSPLIT_WIMS\fR.
.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 fairly certain that the file streams are extracted
+correctly, even though \fBimagex apply\fR don't have 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.
+
+You cannot use \fBimagex apply\fR to apply a WIM from a pipe (such as standard
+input) because the WIM file format is not designed for this.
.SH EXAMPLES
.SS Normal extraction mode
.RE
.PP
.SS NTFS extraction mode
-Verbosely apply a WIM image to a NTFS filesystem image:
+Apply a WIM image to a NTFS filesystem image:
.RS
.PP
-imagex apply mywim.wim 1 fsimage.ntfs --verbose
+imagex apply mywim.wim 1 fsimage.ntfs
.RE
.PP
Create a new NTFS filesystem on the partition /dev/sda2 and apply the first