imagex-apply.1.in: Update man page
authorEric Biggers <ebiggers3@gmail.com>
Sun, 12 May 2013 18:26:05 +0000 (13:26 -0500)
committerEric Biggers <ebiggers3@gmail.com>
Sun, 12 May 2013 18:26:05 +0000 (13:26 -0500)
doc/imagex-apply.1.in

index b078ba0bbaf604f1838e54aae831438ed904cda4..c8a96a04a29f4f7813e325bafb6363ec20ba860a 100644 (file)
@@ -8,39 +8,45 @@
 .SH DESCRIPTION
 .PP
 
-\fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows Imaging
-(WIM) file \fIWIMFILE\fR.
+\fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows
+Imaging (WIM) file \fIWIMFILE\fR.
 
-Note: this man page primarily documents the UNIX behavior.  See \fBWINDOWS
-VERSION\fR for information specific to the Windows build of wimlib.
+This command is designed to extract, or "apply", one or more full WIM images.
+If you want to extract only certain files or directories contained in a WIM
+image, consider using \fB@IMAGEX_PROGNAME@ extract\fR or \fB@IMAGEX_PROGNAME@
+mount\fR instead.
 
 \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 \fB@IMAGEX_PROGNAME@ info\fR (1)
-command to show what images a WIM file contains.
+indicate that all images are to be extracted.  Use the \fB@IMAGEX_PROGNAME@
+info\fR (1) command to show what images a WIM file contains.
 
 \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
 \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.
+location and the WIM image(s) are extracted to that directory.  Alternatively,
+on UNIX only, if \fITARGET\fR specifies a regular file or block device, it is
+interpreted as an NTFS volume to which the WIM image is to be extracted.
 
-\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as well as
-split WIMs.  See \fBSPLIT WIMS\fR.
+\fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as
+well as split WIMs.  See \fBSPLIT WIMS\fR.
 
-.SH NORMAL MODE
+.SH NORMAL MODE (UNIX)
 
-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.
+This section documents how files are extracted on UNIX from the WIM image to a
+directory.  See \fBWINDOWS VERSION\fR for the corresponding documentation for
+the Windows version.
 
-In the normal mode of extraction, the following information is extracted from
-the WIM image(s):
+On UNIX, 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 on UNIX, the following information is
+extracted from the WIM image(s):
 
 .IP \[bu] 4
 The default (unnamed) data stream of each file
@@ -56,8 +62,8 @@ the desired location (for example, the target of the link may contain a Windows
 drive letter).
 
 .PP
-In the normal mode of extraction, the following information will \fInot\fR be
-extracted from the WIM image(s):
+However, in the "normal" mode of extraction on UNIX, the following information
+will \fInot\fR be extracted from the WIM image(s):
 
 .IP \[bu] 4
 Security descriptors (file permissions) except through the extensions available
@@ -71,13 +77,18 @@ Certain file attributes such as compression, encryption, and sparseness.
 .IP \[bu]
 Short (DOS) names for files
 
-.SH NTFS MODE
+.SH NTFS MODE (UNIX)
 
-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 all information
-contained in the WIM image.  \fIIMAGE\fR may not be "all" for this action.
+This section documents how files are extracted directly to an NTFS volume image
+on UNIX.  See \fBWINDOWS VERSION\fR for the corresponding documentation for the
+Windows version.
+
+On UNIX, 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 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
@@ -87,12 +98,12 @@ The NTFS extraction mode is not available if wimlib was compiled using the
 \fB--without-ntfs-3g\fR 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
+is a directory, even if an 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:
+In the NTFS extraction mode on UNIX, the following information will be extracted
+from the WIM image:
 
 .IP \[bu] 4
 The data streams of all files, including the un-named data stream as well as all
@@ -116,13 +127,15 @@ 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.
 
 .PP
-
-Since 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.
-
+However, the extraction of encrypted files is not supported in this mode.
+.PP
+Since all (or 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 in addition to with \fB@IMAGEX_PROGNAME@\fR on
+Windows.  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.
+.PP
 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:
@@ -186,6 +199,7 @@ mywim3.swm
 mywim4.swm
 mywim5.swm
 .RE
+.nf
 
 To apply the first image of this split WIM to the directory "dir", run:
 .PP
@@ -196,26 +210,44 @@ To apply the first image of this split WIM to the directory "dir", run:
 
 .SH WINDOWS VERSION
 
-This section documents the differences between \fB@IMAGEX_PROGNAME@ apply\fR in the Windows
-builds of wimlib versus the rest of this man page, which is written to document
-the UNIX build.
+The Windows version of \fB@IMAGEX_PROGNAME@ apply\fR acts similarly to the
+corresponding command of Microsoft's ImageX.  For best results, the target
+directory should be on an NTFS volume and you should be running with
+Administrator privileges; however, non-NTFS filesystems and running without
+Administrator privileges are also supported.
 
-\fB@IMAGEX_PROGNAME@ apply\fR does not have separate "normal" and "NTFS" modes on Windows.
-There is simply one mode, and it uses the Windows API to apply NTFS-specific
-information, including alternate data streams, reparse points, hard links, and
-file attributes.  So, you essentially get the advantages of the "NTFS mode"
-documented above, but you can apply the WIM image to any directory, not just an
-entire NTFS volume.  This is essentially the same behavior as Microsoft's
-ImageX.
+On Windows, \fB@IMAGEX_PROGNAME@ apply\fR tries to extract as much data as
+possible.  This includes:
 
-\fB--hardlink\fR, \fB--symlink\fR, and \fB--unix-data\fR are not supported on
-Windows.
+.IP \[bu] 4
+All data streams of all files.  This includes the default file contents, as well
+as named data streams if supported by the filesystem.
+.IP \[bu]
+Reparse points, including symbolic links, junction points, and other reparse
+points, if supported by the underlying filesystem.  (Note: see
+\fB--rpfix\fR and \fB--norpfix\fR for documentation on how absolute symbolic
+links and junctions are applied.)
+.IP \[bu]
+File and directory creation, access, and modification timestamps.
+.IP \[bu]
+Security descriptors, if supported by the filesystem and \fB--no-acls\fR is not
+specified.  Furthermore, unless \fB--strict-acls\fR is specified, the security
+descriptor for individual files or directories may be omitted or only partially
+set if the user does not have permission to set them.
+.IP \[bu]
+File attributes, including hidden, sparse, compressed, encrypted, etc, when
+supported by the filesystem.
+.IP \[bu]
+DOS names (8.3) names of files; however, the failure to set them is not
+considered an error condition.
+.IP \[bu]
+Hard links, if supported by the filesystem.
 
-Except for the differences documented in this section, the Windows build of
-\fB@IMAGEX_PROGNAME@ apply\fR should be essentially equivalent to the UNIX build.  However,
-one additional thing to note is that wimlib's Windows ImageX is NOT written to
-be command-line compatible with Microsoft's ImageX, although they are very
-similar.
+.PP
+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.
 
 .SH OPTIONS
 .TP 6
@@ -223,45 +255,10 @@ similar.
 When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
 present.
 .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 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
-instead.  This option is not available in the NTFS extraction mode.
-.TP
-\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.
 .TP
-\fB--unix-data\fR
-This option may only be given in the normal extraction mode (not NTFS).  By
-default, in the normal extraction mode on UNIX, \fB@IMAGEX_PROGNAME@ apply\fR
-will ignore both Windows-style security descriptors and UNIX-specific file
-owners, groups, and modes set when using \fB@IMAGEX_PROGNAME@ capture\fR with
-the \fB--unix-data\fR flag.  By passing \fB--unix-data\fR to
-\fB@IMAGEX_PROGNAME@ apply\fR instead, this causes this UNIX-specific data to be
-restored when available.
-.TP
-\fB--no-acls\fR
-Do not restore security descriptors on extracted files and directories.
-.TP
-\fB--strict-acls\fR
-Fail immediately if the full security descriptor of any file or directory cannot
-be set exactly as specified in the WIM file.  The default behavior without this
-option is to fall back to setting a security descriptor with the SACL omitted,
-then only the default inherited security descriptor, if we do not have
-permission to set the desired one.
-.TP
 \fB--rpfix\fR, \fB--norpfix\fR
 Set whether to fix targets of absolute symbolic links (reparse points in Windows
 terminology) or not.  When enabled (\fB--rpfix\fR), extracted absolute symbolic
@@ -273,6 +270,46 @@ it's been applied to any location.
 
 The default behavior is \fB--rpfix\fR if any images in \fIWIMFILE\fR have been
 captured with reparse-point fixups done.  Otherwise, it is \fB--norpfix\fR.
+.TP
+\fB--verbose\fR
+Print the path to of each file or directory within the WIM image as it is
+extracted.
+.TP
+\fB--hardlink\fR
+(UNIX only) When extracting a file from the WIM that is identical to a file that
+has already 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
+(UNIX only) This option is similar to \fB--hardlink\fR, except symbolic links are created
+instead.
+.TP
+\fB--unix-data\fR
+(UNIX only)  By default, in the normal extraction mode on UNIX,
+\fB@IMAGEX_PROGNAME@ apply\fR will ignore both Windows-style security
+descriptors and UNIX-specific file owners, groups, and modes set when
+using \fB@IMAGEX_PROGNAME@ capture\fR with the \fB--unix-data\fR flag.
+By passing \fB--unix-data\fR to \fB@IMAGEX_PROGNAME@ apply\fR instead,
+this causes this UNIX-specific data to be restored when available.  However, by
+default, if \fB@IMAGEX_PROGNAME@\fR does not have permission to set the UNIX
+owner, group or file mode on an extracted file, a warning will be printed and it
+will not be considered an error condition; use \fB--strict-acls\fR to get
+stricter behavior.
+.TP
+\fB--no-acls\fR
+(Windows only) Do not restore security descriptors on extracted files and directories.
+.TP
+\fB--strict-acls\fR
+On Windows: Fail immediately if the full security descriptor of any file or
+directory cannot be set exactly as specified in the WIM file.  The default
+behavior without this option is to fall back to setting a security descriptor
+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.
 
 .SH NOTES
 
@@ -291,7 +328,7 @@ You cannot use \fB@IMAGEX_PROGNAME@ apply\fR to apply a WIM from a pipe (such as
 input) because the WIM file format is not designed for this.
 
 .SH EXAMPLES
-.SS Normal extraction mode
+.SS Applying a WIM image to a directory (both UNIX and Windows)
 Extract the first image from the Windows PE image from the Windows Vista/7/8
 installation media to the directory "boot":
 .RS
@@ -306,8 +343,8 @@ installation media to the directory "boot", and hard link all identical files:
 @IMAGEX_PROGNAME@ apply /media/windows8/sources/boot.wim all boot --hardlink
 .RE
 .PP
-.SS NTFS extraction mode
-Apply a WIM image to a NTFS filesystem image:
+.SS Applying a WIM image directly to a NTFS volume image (UNIX only)
+Apply a WIM image to an NTFS filesystem image:
 .RS
 .PP
 @IMAGEX_PROGNAME@ apply mywim.wim 1 fsimage.ntfs
@@ -325,3 +362,4 @@ mkntfs /dev/sda2 && @IMAGEX_PROGNAME@ apply /media/windows/sources/install.wim 1
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
 .BR @IMAGEX_PROGNAME@-extract (1)
+.BR @IMAGEX_PROGNAME@-info (1)