wimlib-imagex documentation updates
authorEric Biggers <ebiggers3@gmail.com>
Wed, 14 Aug 2013 05:13:12 +0000 (00:13 -0500)
committerEric Biggers <ebiggers3@gmail.com>
Wed, 14 Aug 2013 05:14:29 +0000 (00:14 -0500)
13 files changed:
doc/imagex-apply.1.in
doc/imagex-capture.1.in
doc/imagex-delete.1.in
doc/imagex-dir.1.in
doc/imagex-export.1.in
doc/imagex-extract.1.in
doc/imagex-info.1.in
doc/imagex-join.1.in
doc/imagex-mount.1.in
doc/imagex-optimize.1.in
doc/imagex-split.1.in
doc/imagex-update.1.in
doc/imagex.1.in

index 9ec08a3..1801296 100644 (file)
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-apply \- Extract one image, or all images, from a WIM archive
 .SH SYNOPSIS
 \fB@IMAGEX_PROGNAME@ apply\fR \fIWIMFILE\fR [\fIIMAGE\fR] \fITARGET\fR [\fIOPTION\fR...]
 .SH DESCRIPTION
 \fB@IMAGEX_PROGNAME@ apply\fR extracts an image, or all images, from the Windows
-Imaging (WIM) file \fIWIMFILE\fR.  \fIWIMFILE\fR may be "-" to read the WIM from
-standard input, but see \fBPIPABLE WIMS\fR.
-This command is also available as simply \fBwimapply\fR if the appropriate hard
-link is installed.
+Imaging (WIM) file \fIWIMFILE\fR.  This command is also available as simply
+\fBwimapply\fR if the appropriate hard link or batch file has been installed.
 .PP
 This command is designed to extract, or "apply", one or more full WIM images.
 If you instead 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.
 .PP
-\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.  \fIIMAGE\fR may be
-omitted if \fIWIMFILE\fR contains only one image.
-.PP
-\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.  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.
+\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to extract.  It may be a
+1-based index of an image in \fIWIMFILE\fR, the name of an image in
+\fIWIMFILE\fR, or the keyword "all" to indicate that all images in \fIWIMFILE\fR
+are to be extracted.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1) command to show
+what images a WIM file contains.  \fIIMAGE\fR may be omitted if \fIWIMFILE\fR
+contains only one image.
+.PP
+\fITARGET\fR specifies where to extract the WIM image to.  If \fITARGET\fR
+specifies a directory, the WIM image is extracted to that directory (see
+\fBDIRECTORY EXTRACTION (UNIX)\fR or \fBDIRECTORY EXTRACTION (WINDOWS)\fR).
+Similarly, if \fITARGET\fR specifies a non-existent file, a directory is created
+in that location and the WIM image is extracted to that directory.
+.PP
+If \fIIMAGE\fR is specified as "all", then all the images in \fIWIMFILE\fR are
+actually extracted into subdirectories of \fITARGET\fR, each of which is given
+the name of the corresponding image, falling back to the image index in the case
+of an image with no name or a name not valid as a filename.
+.PP
+Alternatively, on UNIX-like systems 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 (see \fBNTFS VOLUME EXTRACTION (UNIX)\fR).  Only a single
+image can be extracted in this mode, and only extracting to the root of the NTFS
+volume (not a subdirectory thereof) is supported.
+.PP
+\fIWIMFILE\fR may be "-" to read the WIM from standard input rather than from a
+file, but see \fBPIPABLE WIMS\fR for more information.
 .PP
 \fB@IMAGEX_PROGNAME@ apply\fR supports applying images from stand-alone WIMs as
 well as split WIMs.  See \fBSPLIT WIMS\fR.
-.SH NORMAL MODE (UNIX)
-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.
-.PP
-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.
-.PP
-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
-.IP \[bu]
-Hard links
-.IP \[bu]
-File and directory creation, access, and modification timestamps to the nearest
-100 nanoseconds, if supported by the underlying filesystem, operating system,
-and C library
-.IP \[bu]
-Symbolic links and junction points.  Drive letters will be stripped.
-(Note: see \fB--rpfix\fR and \fB--norpfix\fR for documentation on how absolute
-symbolic links and junctions are applied.)
-.PP
-However, in the "normal" mode of extraction on UNIX, the following information
-will \fInot\fR be extracted from the WIM image(s):
+.SH DIRECTORY EXTRACTION (UNIX)
+This section documents how \fB@IMAGEX_PROGNAME@ apply\fR (and also
+\fB@IMAGEX_PROGNAME@ extract\fR) extract a WIM image (or a possibly a subset
+thereof, in the case of \fB@IMAGEX_PROGNAME@ extract\fR) to a directory on
+UNIX-like systems.  See \fBDIRECTORY EXTRACTION (WINDOWS)\fR for the
+corresponding documentation for Windows.
+
+As mentioned, a WIM image can be applied to a directory on a UNIX-like system by
+providing a \fITARGET\fR directory.  However, it is important to keep in mind
+that the WIM format was designed for Windows, and as a result WIM files can
+contain data or metadata that cannot be represented on UNIX-like systems.  The
+main information that \fB@IMAGEX_PROGNAME@\fR will \fInot\fR be able to extract
+on UNIX-like systems is the following:
 .IP \[bu] 4
-Security descriptors (file permissions) except through the extensions available
-through the \fB--unix-data\fR option
+Windows security descriptors (which include the file owner, group, and ACLs).
 .IP \[bu]
-The alternate (named) data streams for each file
+Named data streams.
 .IP \[bu]
-Reparse points other than symbolic links and junction points
+Reparse points other than symbolic links and junction points.
 .IP \[bu]
 Certain file attributes such as compression, encryption, and sparseness.
 .IP \[bu]
-Short (DOS) names for files
-.SH NTFS MODE (UNIX)
-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.
-.PP
-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.
-.PP
-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 \fBmkntfs\fR (8) command.
-.PP
-The NTFS extraction mode is not available if wimlib was compiled using the
-\fB--without-ntfs-3g\fR option.
-.PP
-Please note that the NTFS extraction mode is \fInot\fR entered if \fITARGET\fR
-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).
-.PP
-In the NTFS extraction mode on UNIX, the following information will be extracted
-from the WIM image:
+Short (DOS) names for files.
+.IP \[bu]
+File creation timestamps.
+.PP
+Notes: Unsupported data and metadata is simply not extracted, but
+\fB@IMAGEX_PROGNAME@\fR always warns you when the contents of the WIM image
+can't be exactly represented when extracted.  Last access and last modification
+timestamps are specified to 100 nanosecond granularity in the WIM file, but will
+only be extracted to the highest precision supported by the underlying operating
+system, C library, and filesystem.
+.SH NTFS VOLUME EXTRACTION (UNIX)
+This section documents how \fB@IMAGEX_PROGNAME@ apply\fR extracts a WIM image
+directly to an NTFS volume image on UNIX-like systems.  See \fBDIRECTORY EXTRACTION
+(WINDOWS)\fR for the corresponding documentation for Windows.
+.PP
+As mentioned, \fB@IMAGEX_PROGNAME@\fR running on a UNIX-like system can apply a
+WIM image directly to an NTFS volume by specifying \fITARGET\fR as a regular file
+or block device containing an NTFS filesystem.  The NTFS filesystem need not be
+empty, although it's expected that it be empty for the intended use cases.  A
+new NTFS filesystem can be created using the \fBmkntfs\fR(8) command provided
+with \fBntfs-3g\fR.
+.PP
+In this NTFS volume extraction mode, the WIM image is extracted to the root of
+the NTFS volume in a way preserves almost all information contained in the WIM
+image.  It therefore does not suffer from the limitations described in
+\fBDIRECTORY EXTRACTION (UNIX)\fR.  This support relies on libntfs-3g to write
+to the NTFS volume and handle NTFS-specific and Windows-specific data.
+.PP
+Please note that this NTFS volume extraction mode is \fInot\fR entered if
+\fITARGET\fR 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).
+.PP
+This NTFS volume extraction mode attempts to extract as much information as
+possible, including:
 .IP \[bu] 4
-The data streams of all files, including the un-named data stream as well as all
+All data streams of all files, including the unnamed data stream as well as all
 named data streams.
 .IP \[bu]
 Reparse points, including symbolic links, junction points, and other reparse
 points.
 .IP \[bu]
-Hard links.
+File and directory creation, access, and modification timestamps, using the
+native NTFS resolution of 100 nanoseconds.
 .IP \[bu]
-File and directory creation, access, and modification timestamps are set to the
-100-nanosecond resolution values specified in the WIM file.
-.IP \[bu] 4
-The security descriptor for each file is applied if there is one specified in
-the WIM.
+Windows security descriptors, including all components (owner, group, DACL, and
+SACL).
 .IP \[bu]
-File attribute flags are applied.
+DOS/Windows file attribute flags.
 .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.
+All names of all files, including names in the Win32 namespace, DOS namespace,
+Win32+DOS namespace, and POSIX namespace.  This includes hard links.
 .PP
-However, the extraction of encrypted files is not supported in this mode.
+Currently, the only known limitation (in terms of exactly extracting all data
+and metadata) is that the extraction of encrypted files is not expected to work
+properly.
 .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.
+\fB@IMAGEX_PROGNAME@\fR on UNIX-like systems 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
@@ -163,30 +165,38 @@ layout.
 Besides setting up the files on the "System" partition, don't forget to set the
 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 WINDOWS VERSION
-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.
-.PP
-On Windows, \fB@IMAGEX_PROGNAME@ apply\fR tries to extract as much data as
-possible.  This includes:
+.SH DIRECTORY EXTRACTION (WINDOWS)
+On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR
+natively support Windows-specific and NTFS-specific data.  For best results, the
+target directory should be located on an NTFS volume and \fB@IMAGEX_PROGNAME@\fR
+should be run with Administrator privileges; however, non-NTFS filesystems and
+running without Administrator privileges are also supported.
+.PP
+On Windows, \fB@IMAGEX_PROGNAME@ apply\fR and \fB@IMAGEX_PROGNAME@ extract\fR
+try to extract as much data and metadata as possible, including:
 .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.
+as named data streams if supported by the target volume.
 .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.)
+points, if supported by the target volume.  (Note: see \fB--rpfix\fR and
+\fB--norpfix\fR for documentation on exactly how absolute symbolic links and
+junctions are extracted.)  However, as per the default security settings of
+Windows, it is impossible to create a symbolic link or junction point without
+Administrator privileges; therefore, you must run \fB@IMAGEX_PROGNAME@\fR as the
+Administrator if you wish to fully restore an image containing symbolic links
+and/or junction points.  (Otherwise, merely a warning will be issued when a
+symbolic link or junction point cannot be extracted due to insufficient
+privileges.)
 .IP \[bu]
-File and directory creation, access, and modification timestamps.
+File and directory creation, access, and modification timestamps, to the highest
+resolution supported by the target volume.
 .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.
+descriptors for individual files or directories may be omitted or only partially
+set if the user does not have permission to set them, which can be a problem if
+\fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
 .IP \[bu]
 File attributes, including hidden, sparse, compressed, encrypted, etc, when
 supported by the filesystem.
@@ -198,12 +208,16 @@ Hard links, if supported by the filesystem.
 .PP
 Additional notes about extracting files on Windows:
 .IP \[bu] 4
-Encrypted files will be extracted as raw encrypted data if the filesystem
-does not support encryption.
+\fB@IMAGEX_PROGNAME@\fR will always issue a warning when it is unable to extract
+the exact metadata and data of the WIM image, for example due to features
+mentioned above not being supported by the target filesystem.
 .IP \[bu]
-Compressed files and directories (with the compression attribute set) will be
-extracted as uncompressed if the filesystem does not support transparent
-compression.
+Since encrypted files (with FILE_ATTRIBUTE_ENCRYPTED) are not stored in
+plaintext in the WIM image, \fB@IMAGEX_PROGNAME@\fR cannot restore encrypted
+files to filesystems not supporting encryption.  (The current behavior is to
+just extract the encrypted data anyway.)  Furthermore, even if encrypted files
+are restored to a filesystem that supports encryption, they will only be
+decryptable if the decryption key is available.
 .IP \[bu]
 Files with names that cannot be represented on Windows will not
 be extracted by default; see \fB--include-invalid-names\fR.
@@ -243,7 +257,7 @@ To apply the first image of this split WIM to the directory "dir", run:
 As a special case, if you are applying an image from standard input from a split
 WIM that is also pipable (as described in \fBPIPABLE WIMS\fR), the \fB--ref\fR
 option is unneeded; instead you must ensure that all the split WIM parts are
-concatenated together on standard input.  They can be provided in any other,
+concatenated together on standard input.  They can be provided in any order,
 with the exception of the first part, which must be first.
 .SH PIPABLE WIMS
 As of wimlib 1.5.0, \fB@IMAGEX_PROGNAME@ apply\fR supports applying a WIM from a
@@ -251,15 +265,17 @@ nonseekable file, such as a pipe, provided that the WIM was captured with
 \fB--pipable\fR (see \fB@IMAGEX_PROGNAME@ capture\fR(1)).  To use standard input
 as the WIM, specify "-" as \fIWIMFILE\fR.  A useful use of this ability is to
 apply an image from a WIM while streaming it from a webserver; for example, to
-apply the first image from a WIM file to a NTFS volume on /dev/sda1:
+apply the first image from a WIM file to an NTFS volume on /dev/sda1:
 .PP
 .RS
-wget -O - http://myserver/mywim.wim | @IMAGEX_PROGNAME@ apply - 1 /dev/sda1
+wget -O - http://myserver/mywim.wim | wimapply - 1 /dev/sda1
 .RE
 .PP
-Note: WIM files are \fInot\fR pipable by default; you have to explicitly capture
-them with \fB--pipable\fR, and they are \fInot\fR compatible with Microsoft's
-software.  See \fB@IMAGEX_PROGNAME@ capture\fR(1) for more information.
+(The above also used the \fBwimapply\fR abbreviation for \fB@IMAGEX_PROGNAME@
+apply\fR.) Note: WIM files are \fInot\fR pipable by default; you have to
+explicitly capture them with \fB--pipable\fR, and they are \fInot\fR compatible
+with Microsoft's software.  See \fB@IMAGEX_PROGNAME@ capture\fR(1) for more
+information.
 .PP
 It is possible to apply an image from a pipable WIM split into multiple parts;
 see \fBSPLIT WIMS\fR.
@@ -281,12 +297,13 @@ absolute targets relative to the image root, and therefore have the actual root
 of extraction prepended to their targets.  The intention is that you can apply
 an image containing absolute symbolic links and still have them be valid after
 it has been applied to any location.
-.IP "" 6
+.IP ""
 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.
-.IP "" 6
-Reparse point fixups are never done in the NTFS extraction mode on UNIX.
-.TP
+.IP ""
+Reparse point fixups are never done in the NTFS volume extraction mode on
+UNIX-like systems.
+.IP ""
 \fB--verbose\fR
 Print the path to of each file or directory within the WIM image as it is
 extracted.
@@ -297,96 +314,124 @@ 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.
+.IP ""
+However, hard-linked extraction mode does have some additional quirks.  Named
+data streams will not be extracted, and files can be hard linked even if their
+metadata is not fully consistent.
 .TP
 \fB--symlink\fR
-(UNIX only) This option is similar to \fB--hardlink\fR, except symbolic links are created
+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,
+(UNIX-like systems only)  By default, in the directory 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.
+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.
+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.
+Fail immediately if the full security descriptor of any file or directory cannot
+be set exactly as specified in the WIM file.  On Windows, 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
+\fB@IMAGEX_PROGNAME@\fR does not have permission to set the desired one.  Also,
+on UNIX-like systems, this flag can also be combined with \fB--unix-data\fR to
+cause \fB@IMAGEX_PROGNAME@\fR to fail immediately if the UNIX owner, group, or
+mode on an extracted file cannot be set for any reason.
 .TP
 \fB--include-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.
+On POSIX-compliant systems, filenames are case-sensitive and may contain any
+byte except '\\0' and \'/', so on a POSIX-compliant system 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--include-invalid-names\fR, all names will be sanitized and
-extracted in some form.
+\'\\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 a POSIX-compliant system 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--include-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
-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 \fB@IMAGEX_PROGNAME@ apply\fR don't have a \fB/verify\fR option like
-Microsoft's 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.
+\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 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 that need to be
+extracted cannot be found in the stream lookup table.  So you can be fairly
+certain that the file streams are extracted correctly, even though
+\fB@IMAGEX_PROGNAME@ apply\fR don't have a \fB/verify\fR option like Microsoft's
+ImageX does.  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 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
+Extract the first image from the Windows PE image on the Windows Vista/7/8
 installation media to the directory "boot":
 .RS
 .PP
-@IMAGEX_PROGNAME@ apply /media/windows/sources/boot.wim 1 boot
+@IMAGEX_PROGNAME@ apply /mnt/windows/sources/boot.wim 1 boot
 .RE
 .PP
-Extract all images from the Windows PE image from the Windows Vista/7/8
-installation media to the directory "boot", and hard link all identical files:
+Same as above, but using the \fBwimapply\fR abbreviation:
 .RS
 .PP
-@IMAGEX_PROGNAME@ apply /media/windows8/sources/boot.wim all boot --hardlink
+wimapply /media/windows/sources/boot.wim 1 boot
 .RE
 .PP
-.SS Applying a WIM image directly to a NTFS volume image (UNIX only)
-Apply a WIM image to an NTFS filesystem image:
+On Windows, apply an image of an entire volume, for example from "install.wim"
+which can be found on the Windows Vista/7/8 installation media:
 .RS
 .PP
-@IMAGEX_PROGNAME@ apply mywim.wim 1 fsimage.ntfs
+@IMAGEX_PROGNAME@ apply install.wim 1 E:\\
 .RE
 .PP
-Create a new NTFS filesystem on the partition /dev/sda2 and apply the first
-image in the Windows Vista/7/8 installation WIM to it.  (Obviously, only do this
-if you want to erase everything on that partition.)
+Same as above, but running on a UNIX-like system where the corresponding
+partition is /dev/sda2:
 .RS
 .PP
-mkntfs /dev/sda2 && @IMAGEX_PROGNAME@ apply /media/windows/sources/install.wim 1 /dev/sda2
+@IMAGEX_PROGNAME@ apply install.wim 1 /dev/sda2
 .RE
+.PP
+Note that before running either of the above commands, an NTFS filesystem may
+need to be created on the partition, for example with format.exe on Windows or
+\fBmkntfs\fR(8) (part of NTFS-3g) on UNIX-like systems.  For example, you might
+run:
+.RS
+.PP
+mkntfs /dev/sda2 && wimapply install.wim 1 /dev/sda2
+.RE
+.PP
+(Of course don't do that if you don't want to destroy all existing data on the
+partition!)
+.PP
+An example of applying a pipable WIM from a pipe can be found in \fBPIPABLE
+WIMS\fR, and an example of applying a split WIM can be found in \fBSPLIT
+WIMS\fR.
+.PP
+And finally, just for fun, a silly way to recursively copy a directory tree
+\fIsrc\fR to \fIdst\fR (but subject to the documented limitations, e.g.
+platform and filesystem-dependent, of the capture and apply functionality of
+\fB@IMAGEX_PROGNAME@\fR):
+.RS
+.PP
+@IMAGEX_PROGNAME@ capture src - | @IMAGEX_PROGNAME@ apply - 1 dst
+.RE
+.PP
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
+.BR @IMAGEX_PROGNAME@-capture (1)
 .BR @IMAGEX_PROGNAME@-extract (1)
 .BR @IMAGEX_PROGNAME@-info (1)
index 79a85b1..35fe06d 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-capture, @IMAGEX_PROGNAME@-append \- Create or append a WIM image
 .SH SYNOPSIS
@@ -73,13 +73,13 @@ links via reparse points; this process is reversible, e.g. automatically by
 granularity and include last modification time (mtime) and last access time
 (atime), but not last status change time (ctime).
 .SH NTFS VOLUME CAPTURE (UNIX)
-This section documents how \fB@IMAGEX_PROGNAME@\fR captures files from an NTFS
-volume image on UNIX-like systems.  See \fBDIRECTORY CAPTURE (WINDOWS)\fR for
-the corresponding documentation for Windows.
+This section documents how \fB@IMAGEX_PROGNAME@\fR captures files directly from
+an NTFS volume image on UNIX-like systems.  See \fBDIRECTORY CAPTURE
+(WINDOWS)\fR for the corresponding documentation for Windows.
 .PP
 On UNIX-like systems, a special image capture mode is entered when \fISOURCE\fR
 is a regular file or block device.  In this mode, \fISOURCE\fR is assumed to be
-a NTFS volume or volume image, and wimlib will capture a WIM image containing a
+an NTFS volume or volume image, and wimlib will capture a WIM image containing a
 full contents of the NTFS volume, including NTFS-specific data.  This is done
 using libntfs-3g.
 .PP
@@ -111,12 +111,13 @@ Win32+DOS namespace, and POSIX namespace.  This includes hard links.
 On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR
 natively support Windows-specific and NTFS-specific data.  They therefore act
 similarly to the corresponding commands of Microsoft's ImageX.  For best
-results, the directory being captured 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.
+results, the directory being captured should be on an NTFS volume and
+\fB@IMAGEX_PROGNAME@\fR should be run with Administrator privileges; however,
+non-NTFS filesystems and running without Administrator privileges are also
+supported.
 .PP
 On Windows, \fB@IMAGEX_PROGNAME@ capture\fR and \fB@IMAGEX_PROGNAME@ append\fR
-try to archive as much data as possible, including:
+try to archive as much data and metadata as possible, including:
 .IP \[bu] 4
 All data streams of all files, unless running on a version of Windows prior to
 Vista, in which case named data streams (if supported by the source filesystem)
@@ -132,9 +133,9 @@ stored with Windows NT's native timestamp resolution of 100 nanoseconds.
 .IP \[bu]
 Security descriptors, if supported by the source filesystem and \fB--no-acls\fR
 is not specified.  However, beware that unless \fB--strict-acls\fR is specified,
-the security descriptor for individual files or directories may be omitted or
-only partially captured if the user does not have permission to read it, which
-is mainly a problem if \fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
+the security descriptors for individual files or directories may be omitted or
+only partially captured if the user does not have permission to read them, which
+can be a problem if \fB@IMAGEX_PROGNAME@\fR is run as a non-Administrator.
 .IP \[bu]
 File attributes, including hidden, sparse, compressed, encrypted, etc.
 Encrypted files will be stored in encrypted form rather than in plain text.
@@ -418,7 +419,7 @@ name need not be specified and will default to 'somedir':
 @IMAGEX_PROGNAME@ capture somedir mywim.wim
 .RE
 .PP
-or, if the \fBwimcapture\fR hard link or batch file is installed, the
+or, if the \fBwimcapture\fR hard link or batch file has been installed, the
 abbreviated form can be used:
 .RS
 .PP
@@ -447,7 +448,7 @@ with absolute symbolic links, and an image name and description:
 Capture an entire NTFS volume into a new WIM file and name the image "Windows
 7".  On UNIX-like systems, this requires using the special mode described in
 \fBNTFS VOLUME CAPTURE (UNIX)\fR where \fISOURCE\fR is a file or block device
-containing a NTFS filesystem:
+containing an NTFS filesystem:
 .RS
 .PP
 @IMAGEX_PROGNAME@ capture /dev/sda2 windows7.wim "Windows 7"
@@ -460,7 +461,7 @@ root directory of the mounted volume, for example:
 @IMAGEX_PROGNAME@ capture E:\\ windows7.wim "Windows 7"
 .RE
 .PP
-Same as above example with capturing a NTFS volume from \fB@IMAGEX_PROGNAME@\fR
+Same as above example with capturing an NTFS volume from \fB@IMAGEX_PROGNAME@\fR
 running on a UNIX-like system, but capture the WIM in the wimlib-specific
 "pipable" format that can be piped to \fB@IMAGEX_PROGNAME@ apply\fR:
 .RS
index 34277a1..3e5b4c1 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-delete \- Delete an image from a WIM archive
 .SH SYNOPSIS
@@ -6,13 +6,14 @@
 .SH DESCRIPTION
 \fB@IMAGEX_PROGNAME@ delete\fR deletes the specified image from the Windows Imaging (WIM)
 file \fIWIMFILE\fR.
-.PP
-\fIIMAGE\fR specifies the WIM image to deleted.  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 deleted.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
-command to show what images a WIM file contains.
 This command is also available as simply \fBwimdelete\fR if the appropriate hard
-link is installed.
+link or batch file has been installed.
+.PP
+\fIIMAGE\fR specifies the WIM image in \fIWIMFILE\fR to deleted.  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 deleted.  Use the
+\fB@IMAGEX_PROGNAME@ info\fR (1) command to show what images a WIM file
+contains.
 .SH NOTES
 By default, the WIM file is rebuilt with all unnecessary file data removed.
 This is different from Microsoft's imagex.exe, which only will delete the
@@ -38,7 +39,7 @@ Perform a "soft delete".  Specifying this flag overrides the default behavior of
 rebuilding the entire WIM after deleting an image.  Instead, only minimal
 changes to correctly remove the image from the WIM will be taken.  In
 particular, all streams will be left alone, even if they are no longer
-referenced.  This is probably not what you want, because almost no space will be
+referenced.  This is probably not what you want, because no space will be
 saved by deleting an image in this way.
 .IP ""
 You may use \fB@IMAGEX_PROGNAME@ optimize\fR to delete unreferenced streams from a WIM that
index bba3a9a..d5fc076 100644 (file)
@@ -1,19 +1,19 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-dir \- Show the files contained in a WIM archive
 .SH SYNOPSIS
 \fB@IMAGEX_PROGNAME@ dir\fR \fIWIMFILE\fR \fIIMAGE\fR [\fIOPTIONS\fR]
 .SH DESCRIPTION
-Lists all the files and directories contained in the specified image of the
-Windows Imaging (WIM) file \fIWIMFILE\fR.
-This command is also available as simply \fBwiminfo\fR if the appropriate hard
-link is installed.
+Lists the files and directories contained in the specified image of the Windows
+Imaging (WIM) file \fIWIMFILE\fR.
+This command is also available as simply \fBwimdir\fR if the appropriate hard
+link or batch file has been installed.
 .PP
-\fIIMAGE\fR specifies the WIM image to show the files of.  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 files from all images are to be shown.  Use the
-\fB@IMAGEX_PROGNAME@ info\fR (1) command to show what images a WIM file
-contains.
+\fIIMAGE\fR specifies the image in \fIWIMFILE\fR to show the files of.  It may
+be a 1-based index of an image in \fIWIMFILE\fR, the name of an image in
+\fIWIMFILE\fR, or the keyword "all" to indicate that files from all images in
+\fIWIMFILE\fR are to be shown.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1) command
+to show what images a WIM file contains.
 .SH OPTIONS
 .TP 6
 \fB--path\fR=\fIPATH\fR
@@ -25,7 +25,7 @@ first part of the split WIM.
 .PP
 The DOS names of files are not displayed.
 .PP
-Alternate data streams are not displayed.
+Alternate (named) data streams are not displayed.
 .SH EXAMPLES
 List all files in the first image of 'boot.wim':
 .RS
index 10e0e15..34b63ea 100644 (file)
@@ -1,9 +1,9 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-export \- Exports an image from a WIM archive to an existing or new WIM archive
 .SH SYNOPSIS
 \fB@IMAGEX_PROGNAME@ export\fR \fISRC_WIMFILE\fR \fISRC_IMAGE\fR
-\fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR\] [\fIDEST_IMAGE_DESCRIPTION\fR]
+\fIDEST_WIMFILE\fR [\fIDEST_IMAGE_NAME\fR [\fIDEST_IMAGE_DESCRIPTION\fR]]
 [\fIOPTION\fR...]
 .SH DESCRIPTION
 Copies the specified image in \fISRC_WIMFILE\fR to \fIDEST_WIMFILE\fR,
@@ -12,19 +12,20 @@ If \fIDEST_WIMFILE\fR exists, it is taken be be a WIM archive to which the image
 will be appended.  Otherwise, it is created as a new WIM archive containing only
 the exported image.
 This command is also available as simply \fBwimexport\fR if the appropriate hard
-link is installed.
+link or batch file has been installed.
 .PP
 \fISRC_IMAGE\fR specifies the image in \fISRC_WIMFILE\fR to export.  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 exported.  Use the
-\fB@IMAGEX_PROGNAME@ info\fR (1) command to list the images a WIM file contains.
+1-based index of an image in \fISRC_WIMFILE\fR, the name of an image in
+\fISRC_WIMFILE\fR, or the keyword "all" to indicate that all images in
+\fISRC_WIMFILE\fR are to be exported.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
+command to list the images a WIM file contains.
 .PP
-If given, \fIDEST_IMAGE_NAME\fR specifies the name to give the image being
-exported to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.
+If specified, \fIDEST_IMAGE_NAME\fR is the name to give the image being exported
+to \fIDEST_WIMFILE\fR.  The default is its name in \fISRC_WIMFILE\fR.
 \fIDEST_IMAGE_NAME\fR cannot be specified if multiple images are being exported.
 .PP
-If given, \fIDEST_IMAGE_DESCRIPTION\fR specifies the description to give the
-image being exported to \fIDEST_WIMFILE\fR.  The default is its description in
+If specified, \fIDEST_IMAGE_DESCRIPTION\fR is the description to give the image
+being exported to \fIDEST_WIMFILE\fR.  The default is its description in
 \fISRC_WIMFILE\fR.
 .PP
 \fB@IMAGEX_PROGNAME@ export\fR supports exporting images from stand-alone WIMs as well as
@@ -32,7 +33,9 @@ from split WIMs.  However, you cannot export an image to a split WIM.  See
 \fBSPLIT WIMS\fR.
 .PP
 \fB@IMAGEX_PROGNAME@ export\fR also supports exporting images from a non-pipable
-WIM into a (possibly new) pipable WIM, and vice versa.  See \fB--pipable\fR and
+WIM into a (possibly new) pipable WIM, and vice versa.  Furthermore, it will
+export a pipable WIM directly to standard output if "-" is specified as
+\fIDEST_WIMFILE\fR (this implies \fB--pipable\fR).  See \fB--pipable\fR and
 \fB--not-pipable\fR.
 .PP
 .SH OPTIONS
@@ -74,10 +77,9 @@ and "LZX", instead of "fast" and "maximum", respectively.
 .TP
 \fB--threads\fR=\fINUM_THREADS\fR
 Number of threads to use for compressing data.  Default: autodetect (number of
-processors).  Note: if exporting to an uncompressed WIM, or exporting to a WIM
-with the same compression type as the source WIM, additional threads will not
-be used, regardless of this parameter, since no data compression needs to be
-done in these cases.
+processors).  Note: multiple compressor threads are not very useful when
+exporting to a WIM with the same compression type as the source WIM, since
+wimlib optimizes this case by re-using the raw compressed data.
 .TP
 \fB--rebuild\fR
 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
@@ -94,12 +96,12 @@ Build, or rebuild, \fIDEST_WIMFILE\fR as a "pipable WIM" so that it can be
 applied fully sequentially, including from a pipe.  See \fB@IMAGEX_PROGNAME@
 capture\fR(1) for more details about creating pipable WIMs.  The default without
 this option is to make \fIDEST_WIMFILE\fR pipable if and only if it already
-existed and was already pipable.
+existed and was already pipable, or was "-" (standard output).
 .TP
 \fB--not-pipable\fR
 Build, or rebuld, \fIDEST_WIMFILE\fR as a normal, non-pipable WIM.  This is the
 default behavior, unless \fIDEST_WIMFILE\fR already existed and was already
-pipable.
+pipable, or if \fIDEST_WIMFILE\fR was "-" (standard output).
 .SH SPLIT WIMS
 You may use \fB@IMAGEX_PROGNAME@ export\fR to export images from a split WIM.  The
 \fISRC_WIMFILE\fR argument is used to specify the first part of the split WIM, and
@@ -133,11 +135,24 @@ It is safe to abort an \fB@IMAGEX_PROGNAME@ export\fR command partway through;
 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
 optimize\fR on the destination WIM to remove any data that was appended to the
 physical WIM file but not yet incorporated into the structure of the WIM, unless
-\fB--rebuild\fR was specified, in which case you should delete the temporary
-file left over.
+the WIM was being rebuild (e.g. with \fB--rebuild\fR), in which case you should
+delete the temporary file left over.
+.PP
+Since the WIM format uses single-instancing (streams are content-addressed by
+SHA1 message digests), when an image is exported, only the streams not already
+present in the destination WIM need to be copied.  However, a new copy of the
+image's metadata resource always needs to be created.
+.PP
 .SH EXAMPLES
-Export the second image of 'boot.wim' to the new WIM file 'new.wim', and
-change the compression type to maximum, if it wasn't maximum already:
+Export the second image of 'boot.wim' to the new WIM file 'new.wim':
+.RS
+.PP
+@IMAGEX_PROGNAME@ export boot.wim 2 new.wim
+.RE
+.PP
+The above example creates "new.wim" with the same compression type as
+"boot.wim".  If you wish to change the compression type, specify
+\fB--compress\fR=\fITYPE\fR; for example:
 .RS
 .PP
 @IMAGEX_PROGNAME@ export boot.wim 2 new.wim --compress=maximum
index 1cf1c51..ff9eaa0 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
 .SH SYNOPSIS
@@ -8,7 +8,7 @@
 from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
 \fIWIMFILE\fR.
 This command is also available as simply \fBwimextract\fR if the appropriate hard
-link is installed.
+link or batch file has been installed.
 .PP
 \fB@IMAGEX_PROGNAME@ extract\fR is intended for extracting only a subset of a
 WIM image.  If you want to extract or "apply" a full WIM image to a directory or
@@ -55,8 +55,7 @@ File glob of additional split WIM parts that are part of the split WIM.  See
 \fBSPLIT_WIMS\fR.
 .TP
 \fB--verbose\fR
-Print the path of each file or directory within the WIM image as it is
-extracted.
+This option no longer does anything but is reserved for future use.
 .TP
 \fB--unix-data\fR
 See the documentation for this option in \fB@IMAGEX_PROGNAME@-apply\fR (1).
@@ -81,11 +80,12 @@ Extract the files and directories to the directory \fIDIR\fR instead of to the
 current working directory.
 .SH NOTES
 See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about
-what data and metadata are extracted on UNIX versus on Windows.
+what data and metadata are extracted on UNIX-like systems versus on Windows.
 .PP
-On UNIX, one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@
-mount\fR and then extract the desired files or directories using any standard
-command-line or graphical program.
+On UNIX-like systems that support userspace filesystems with FUSE (e.g. Linux),
+one can alternatively mount the WIM image with \fB@IMAGEX_PROGNAME@ mount\fR and
+then extract the desired files or directories using any standard command-line or
+graphical program.
 .PP
 Reparse-point fixups (a.k.a. changing absolute symbolic links and junctions to
 point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
@@ -103,13 +103,21 @@ Extract a file from the first image in "boot.wim" to the current directory:
 Extract a file from the first image in "boot.wim" to standard output:
 .RS
 .PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --to-stdout
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
+.br
+.RS
+--to-stdout
+.RE
 .RE
 .PP
 Extract a file from the first image in "boot.wim" to the specified directory:
 .RS
 .PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe --dest-dir=somedir
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe \\
+.br
+.RS
+--dest-dir=somedir
+.RE
 .RE
 .PP
 Extract the "sources" directory from the first image in "boot.wim" to the
@@ -122,7 +130,11 @@ current directory:
 Extract multiple files and directories in one command:
 .RS
 .PP
-@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts /sources /Windows/System32/cmd.exe
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts \\
+.br
+.RS
+/sources /Windows/System32/cmd.exe
+.RE
 .RE
 .PP
 .SH SEE ALSO
index d5c274f..1840df6 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-info \- Display information about a WIM file, or change information about
 an image
@@ -10,7 +10,7 @@ an image
 changes which image is bootable, or what the name and description of an image
 are.
 This command is also available as simply \fBwiminfo\fR if the appropriate hard
-link is installed.
+link or batch file has been installed.
 .PP
 If neither an image nor any flags other than \fB--check\fR are specified, some
 basic information about the WIM archive as well as information about the images
index c3112fd..4c062b3 100644 (file)
@@ -1,12 +1,13 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-join \- Join split WIMs into a standalone one-part WIM
 .SH SYNOPSIS
-\fB@IMAGEX_PROGNAME@ join\fR [\fIOPTION\fR...] \fIOUT_WIMFILE\fR \fISPLIT_WIM\fR...
+\fB@IMAGEX_PROGNAME@ join\fR [\fIOPTION\fR...] \fIOUT_WIMFILE\fR
+\fISPLIT_WIM_PART\fR...
 .SH DESCRIPTION
-Joins the \fISPLIT_WIMs\fR into a standalone one-part WIM \fIOUT_WIMFILE\fR.
+Joins the \fISPLIT_WIM_PARTs\fR into a standalone one-part WIM \fIOUT_WIMFILE\fR.
 This command is also available as simply \fBwimjoin\fR if the appropriate hard
-link is installed.
+link or batch file has been installed.
 .PP
 All parts of the split WIM  must be specified.  You probably want to do so using
 a shell wildcard.
@@ -15,7 +16,7 @@ a shell wildcard.
 .SH OPTIONS
 .TP 6
 \fB--check\fR
-When reading each \fISPLIT_WIM\fR, verify its integrity if the integrity table
+When reading each \fISPLIT_WIM_PART\fR, verify its integrity if the integrity table
 is present; additionally, when writing \fIOUT_WIMFILE\fR, write an integrity
 table.  If this option is not specified, an integrity table will be included in
 \fIOUT_WIMFILE\fR if and only if one was present in the first part of the split
@@ -32,7 +33,7 @@ number), and write the joined WIM to the file `windows.wim'.
 \fB@IMAGEX_PROGNAME@ join\fR is roughly equivalent to:
 .RS
 .PP
-\fB@IMAGEX_PROGNAME@ export\fR \fISWM_PART_1\fR --ref="\fISWM_GLOB\fR" [--check] all \fIOUT_WIMFILE\fR
+\fB@IMAGEX_PROGNAME@ export\fR \fISWM_PART_1\fR --ref="\fISWM_GLOB\fR" all \fIOUT_WIMFILE\fR
 .RE
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
index 0553055..33102ff 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-mount, @IMAGEX_PROGNAME@-mountrw, @IMAGEX_PROGNAME@-unmount \- Mount and unmount an image from a WIM archive
 .SH SYNOPSIS
@@ -14,7 +14,7 @@ by \fIIMAGE\fR on the directory \fIDIRECTORY\fR using FUSE (Filesystem in
 Userspace).  \fB@IMAGEX_PROGNAME@ mount\fR will mount the image read-only, while
 \fB@IMAGEX_PROGNAME@ mountrw\fR will mount the image read-write.
 These commands are also available as simply \fBwimmount\fR, \fBwimmountrw\fR,
-and \fBwimunmount\fR if the appropriate hard links are installed.
+and \fBwimunmount\fR if the appropriate hard links or batch files are installed.
 .PP
 \fIIMAGE\fR may be a 1-based index of the image in the WIM to mount, or it may
 be the name of an image in the WIM.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
index b4ec85f..c7be1d3 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-optimize \- Optimize a WIM archive
 .SH SYNOPSIS
@@ -11,15 +11,15 @@ of appending images, so the new WIM may be slightly smaller than the old WIM.
 In addition, some errors in the original WIM may be fixed by re-writing it
 (although most cannot).
 This command is also available as simply \fBwimoptimize\fR if the appropriate
-hard link is installed.
+hard link or batch file has been installed.
 .SH OPTIONS
 .TP 6
 \fB--check\fR
 When reading \fIWIMFILE\fR, verify its integrity if an integrity table is
 present.  In addition, include an integrity table in the optimized WIM.  If this
 option is not specified, by default the integrity table (if present) is not
-checked, but an integrity table is included in the new WIM if there was one in
-the old WIM.
+checked, and an integrity table is included in the rebuilt WIM if and only if
+one was present in the original WIM.
 .TP
 \fB--nocheck\fR
 Neither verify the integrity of \fIWIMFILE\fR using the integrity table, nor
@@ -45,7 +45,7 @@ processors).  This parameter is only meaningful when \fB--recompress\fR is also
 specified.
 .TP
 \fB--pipable\fR
-Rebuild the WIM that it can be applied fully sequentially, including from a
+Rebuild the WIM so that it can be applied fully sequentially, including from a
 pipe.  See \fB@IMAGEX_PROGNAME@ capture\fR(1) for more details about creating
 pipable WIMs.  By default, when neither \fB--pipable\fR or \fB--not-pipable\fR
 is specified, the rebuilt WIM will be pipable if and only if it was already
index 7dd52d4..27b5cea 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-split \- Split a WIM into multiple parts
 .SH SYNOPSIS
@@ -8,7 +8,7 @@ Splits \fIWIMFILE\fR into parts with size at most \fIPART_SIZE\fR mebibytes,
 with the first part having the name \fISPLIT_WIM_PART\fR and the other parts
 having names numbered in order of the parts.
 This command is also available as simply \fBwimsplit\fR if the appropriate
-hard link is installed.
+hard link or batch file has been installed.
 .PP
 \fB@IMAGEX_PROGNAME@ split\fR can split both non-pipable and pipable WIMs.
 .SH OPTIONS
index a426ffc..f262e5e 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@-update \- Update a WIM image
 .SH SYNOPSIS
@@ -8,7 +8,7 @@
 Imaging (WIM) file \fIWIMFILE\fR by adding, deleting, or renaming files or
 directories in it.
 This command is also available as simply \fBwimupdate\fR if the appropriate
-hard link is installed.
+hard link or batch file has been installed.
 .PP
 \fIIMAGE\fR specifies the image in \fIWIMFILE\fR to update.  It may be a 1-based
 index of an image in the WIM or the name of an image in the WIM.  Use the
@@ -33,34 +33,10 @@ existing directory in the WIM image in one command.  If \fIDESTINATION\fR does
 not exist in the WIM image, then any prerequisite directories are created as
 needed to add the \fISOURCE\fR at that location.
 .PP
-The available options for the \fBadd\fR command are:
-.TP 6
-\fB--verbose\fR
-Print the names of files as they are captured.
-.TP
-\fB--dereference\fR
-(UNIX only) Follow symbolic links and archive the files they point to, rather
-than archiving the links themselves.
-.TP
-\fB--unix-data\fR
-(UNIX only) Store the UNIX owner, group, and mode of all captured files.  This
-is done by adding a special alternate data stream to each directory entry that
-contains this information.  Please note that this flag is for convenience only,
-in case you want to use \fB@IMAGEX_PROGNAME@\fR to archive files on UNIX.
-Microsoft's software will not understand this special information.
-.TP
-\fB--no-acls\fR
-(Windows only) Do not capture files' security descriptors.
-.TP
-\fB--strict-acls\fR
-(Windows only) Fail immediately if the full security descriptor of any file
-cannot be read.  The default behavior without this option is to first try
-omitting the SACL from the security descriptor, then to try omitting the
-security descriptor entirely.  The purpose of this is to capture as much data as
-possible without always requiring Administrator privileges.  However, if you
-desire that all security descriptors be captured exactly, you may wish to
-provide this option, although the Administrator should have permission to read
-everything anyway.
+The \fBadd\fR command supports a subset of the options accepted by
+\fB@IMAGEX_PROGNAME@-capture\fR; namely, \fB--verbose\fR, \fB--dereference\fR,
+\fB--unix-data\fR, \fB--no-acls\fR, and \fB--strict-acls\fR.  See
+\fB@IMAGEX_PROGNAME@-capture\fR (1) for explanations of these options.
 .SS \fBdelete\fR [\fIOPTION\fR...] \fIPATH\fR
 Delete a file or directory tree from the WIM image.  \fIPATH\fR must specify the
 path inside the WIM image of the file or directory tree to delete.
@@ -140,7 +116,11 @@ quotes and single quotes for the inner quotes.  Example:
 .RS
 .PP
 .nf
-@IMAGEX_PROGNAME@ update boot.wim 1 --command="add 'C:\\My Dir' '\\My Dir'"
+@IMAGEX_PROGNAME@ update boot.wim 1 \\
+.br
+.RS
+--command="add 'C:\\My Dir' '\\My Dir'"
+.RE
 .RE
 .RE
 .fi
@@ -148,8 +128,9 @@ quotes and single quotes for the inner quotes.  Example:
 \fB@IMAGEX_PROGNAME@ update\fR is partly redundant with \fB@IMAGEX_PROGNAME@
 mountrw\fR, since if a WIM image can be mounted read-write, then there
 theoretically is no need for \fB@IMAGEX_PROGNAME@ update\fR.  The main advantage
-of \fB@IMAGEX_PROGNAME@ update\fR is that it works on both UNIX and Windows,
-whereas \fB@IMAGEX_PROGNAME@ mountrw\fR only works on UNIX.
+of \fB@IMAGEX_PROGNAME@ update\fR is that it works on both UNIX-like systems and
+Windows, whereas \fB@IMAGEX_PROGNAME@ mountrw\fR only works on UNIX-like
+systems, and even then just those with a compatible FUSE implementation.
 .PP
 Symbolic links inside a WIM image are not dereferenced when being interpreted.
 So, for example, if you have a WIM image that contains a symbolic link
@@ -160,17 +141,17 @@ subdirectory named "Public" in this directory must be specified as
 All paths to files or directories within the WIM image must be specified
 relative to the root of the image.  However, the leading slash is optional, and
 both forward slashes and backslashes are accepted.  In addition, on Windows, the
-paths are treated case-insensitively, while on UNIX, the paths are treated
-case-sensitively.
+paths are treated case-insensitively, while on UNIX-like systems, the paths are
+treated case-sensitively.
 .PP
 The command file (\fICMDFILE\fR) is parsed by \fB@IMAGEX_PROGNAME@ update\fR
 itself and not by the system shell.  Therefore, its syntax is limited.  However,
 comment lines beginning with '#' are allowed, and it is also possible to quote
 arguments with whitespace inside them.
 .PP
-On UNIX, you cannot use \fB@IMAGEX_PROGNAME@ update\fR to add files to an image
-directly from a NTFS volume using libntfs-3g, even though \fB@IMAGEX_PROGNAME@
-capture\fR supports capturing a full image this way.
+On UNIX-like systems, you cannot use \fB@IMAGEX_PROGNAME@ update\fR to add files
+to an image directly from a NTFS volume using libntfs-3g, even though
+\fB@IMAGEX_PROGNAME@ capture\fR supports capturing a full image this way.
 .PP
 It is safe to abort an \fB@IMAGEX_PROGNAME@ update\fR command partway through;
 however, after doing this, it is recommended to run \fB@IMAGEX_PROGNAME@
index ffdbe79..6a952ac 100644 (file)
@@ -1,4 +1,4 @@
-.TH IMAGEX 1 "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.TH WIMLIB-IMAGEX 1 "August 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
 .SH NAME
 @IMAGEX_PROGNAME@ \- Create, modify, extract, mount, or unmount a WIM (Windows Imaging Format) archive
 .SH SYNOPSIS