Document imagex-extract and wimlib_extract_files()

diff --git a/Makefile.am b/Makefile.am
index 1ba1c79612576327f04295a50b0e3a771ae3795e..94af43dc9302f7667067b2198567c8d2dd87c7da 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -150,6 +150,7 @@ wimlib_manpages =                           \
        doc/@IMAGEX_PROGNAME@-delete.1          \
        doc/@IMAGEX_PROGNAME@-dir.1             \
        doc/@IMAGEX_PROGNAME@-export.1          \
        doc/@IMAGEX_PROGNAME@-delete.1          \
        doc/@IMAGEX_PROGNAME@-dir.1             \
        doc/@IMAGEX_PROGNAME@-export.1          \

+       doc/@IMAGEX_PROGNAME@-extract.1         \

        doc/@IMAGEX_PROGNAME@-info.1            \
        doc/@IMAGEX_PROGNAME@-join.1            \
        doc/@IMAGEX_PROGNAME@-mount.1           \
        doc/@IMAGEX_PROGNAME@-info.1            \
        doc/@IMAGEX_PROGNAME@-join.1            \
        doc/@IMAGEX_PROGNAME@-mount.1           \

diff --git a/configure.ac b/configure.ac
index 48aa4ad6691b0309307f02e2db5fe32ee05f90b7..7fca1542e1a072ab7cdd648e32dfcba148bdbf46 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -28,6 +28,7 @@ AC_CONFIG_FILES([Makefile]
                [doc/"$IMAGEX_PROGNAME"-delete.1:doc/imagex-delete.1.in]
                [doc/"$IMAGEX_PROGNAME"-dir.1:doc/imagex-dir.1.in]
                [doc/"$IMAGEX_PROGNAME"-export.1:doc/imagex-export.1.in]
                [doc/"$IMAGEX_PROGNAME"-delete.1:doc/imagex-delete.1.in]
                [doc/"$IMAGEX_PROGNAME"-dir.1:doc/imagex-dir.1.in]
                [doc/"$IMAGEX_PROGNAME"-export.1:doc/imagex-export.1.in]

+               [doc/"$IMAGEX_PROGNAME"-extract.1:doc/imagex-extract.1.in]

                [doc/"$IMAGEX_PROGNAME"-info.1:doc/imagex-info.1.in]
                [doc/"$IMAGEX_PROGNAME"-join.1:doc/imagex-join.1.in]
                [doc/"$IMAGEX_PROGNAME"-mount.1:doc/imagex-mount.1.in]
                [doc/"$IMAGEX_PROGNAME"-info.1:doc/imagex-info.1.in]
                [doc/"$IMAGEX_PROGNAME"-join.1:doc/imagex-join.1.in]
                [doc/"$IMAGEX_PROGNAME"-mount.1:doc/imagex-mount.1.in]

diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in
index 5db59f92a7f0fd0ac91fb559aacef08c14a54d7f..76913a32c4e1c61169c65d02b42ffcfe6200cdb5 100644 (file)
--- a/doc/imagex-apply.1.in
+++ b/doc/imagex-apply.1.in
@@ -326,4 +326,4 @@ mkntfs /dev/sda2 && @IMAGEX_PROGNAME@ apply /media/windows/sources/install.wim 1
 
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)
 
 .SH SEE ALSO
 .BR @IMAGEX_PROGNAME@ (1)

-
+.BR @IMAGEX_PROGNAME@-extract (1)

diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in
new file mode 100644 (file)
index 0000000..f6bbeda
--- /dev/null
+++ b/doc/imagex-extract.1.in
@@ -0,0 +1,142 @@
+.TH IMAGEX "1" "April 2013" "@IMAGEX_PROGNAME@ @VERSION@" "User Commands"
+.SH NAME
+@IMAGEX_PROGNAME@-extract \- Extract files or directories from a WIM image
+
+.SH SYNOPSIS
+\fB@IMAGEX_PROGNAME@ extract\fR \fIWIMFILE\fR \fIIMAGE\fR \fI[PATH\fR]... [\fIOPTION\fR]...
+
+.SH DESCRIPTION
+.PP
+
+\fB@IMAGEX_PROGNAME@ extract\fR extracts one or more files or directory trees
+from the specified \fIIMAGE\fR contained in the Windows Imaging (WIM) file
+\fIWIMFILE\fR.
+
+\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
+NTFS volume, use \fB@IMAGEX_PROGNAME@ apply\fR (1) instead.
+
+\fIIMAGE\fR specifies the image in \fIWIMFILE\fR that contains the files or
+directory trees to extract.  It may be a 1-based index of an image in the WIM or
+the name of an image in the WIM.  Use the \fB@IMAGEX_PROGNAME@ info\fR (1)
+command to show what images a WIM file contains.
+
+Each \fIPATH\fR specifies a file or directory tree within the WIM image to
+extract.  See \fBPATH_SPECIFICATIONS\fR.
+
+By default, files and directories are extracted to the current directory.  Use
+\fB--dest-dir\fR to choose an alternate target directory.
+
+\fB@IMAGEX_PROGNAME@ extract\fR supports extracting files and directory trees
+from stand-alone WIMs as well as split WIMs.  See \fBSPLIT WIMS\fR.
+
+.SH PATH SPECIFICATIONS
+
+Each \fIPATH\fR specifies a file or directory tree within the WIM image to
+extract.  Each path must be specified as an absolute path starting from the root
+of the WIM image, like those output by the \fB@IMAGEX_PROGNAME@ dir\fR (1)
+command.  Path separators may be forward slashes on UNIX, or either forward
+slashes or backward slashes on Windows.  The leading slash is optional.
+
+If no \fIPATH\fRs are provided, the default behavior is to extract the full
+image, as if the path "/" had been provided.
+
+.SH SPLIT WIMS
+
+You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees
+from a split WIM.  This uses the \fB--refs\fR="\fIGLOB\fR" option in the same
+way as in other commands such as \fB@IMAGEX_PROGNAME@ apply\fR.  See
+\fB@IMAGEX_PROGNAME@ apply\fR (1) for more details.
+
+.SH OPTIONS
+.TP 6
+\fB--check\fR
+When reading \fIWIMFILE\fR, verify its integrity if the integrity table is
+present.
+.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.  See
+\fBSPLIT_WIMS\fR.
+.TP
+\fB--unix-data\fR
+Restore the UNIX-specific data captured using \fB@IMAGEX_PROGNAME@ capture\fR
+with the \fB--unix-data\fR option.  This option is only available on UNIX.
+.TP
+\fB--no-acls\fR
+Do not restore security descriptors on extracted files and directories.  This
+option is only available on Windows.
+.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.  This option is only available on Windows.
+.TP
+\fB--to-stdout\fR
+Extract the files to standard output instead of to the filesystem.  This can
+only be provided if all the specified \fIPATH\fRs are to regular files (not
+directories or reparse points).  If present, alternate data streams are not
+extracted.
+
+.SH NOTES
+
+\fB@IMAGEX_PROGNAME@ extract\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.  Thus, it should provide assurance of data integrity.
+
+Reparse-point fixups (a.k.a. changing absolute symbolic links and junction to
+point within the extraction location) are never done by \fB@IMAGEX_PROGNAME@
+extract\fR.  Use \fB@IMAGEX_PROGNAME@ apply\fR if you want this behavior.
+
+Unlike \fB@IMAGEX_PROGNAME@ apply\fR, \fB@IMAGEX_PROGNAME@ extract\fR does not
+support extracting files directly to a NTFS volume using libntfs-3g.
+
+Not all data and metadata containing in each WIM \fIPATH\fR will necessarily be
+extracted, since \fB@IMAGEX_PROGNAME@ extract\fR does the best it can given the
+platform (UNIX or Windows) and supported features of the filesystem.  The
+documentation for \fB@IMAGEX_PROGNAME@ apply\fR (1) goes into more detail about
+what data and metadata is extracted and what is not.
+
+.SH EXAMPLES
+Extract a file from the first image in "boot.wim" to the current directory:
+.RS
+.PP
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/System32/notepad.exe
+.RE
+.PP
+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
+.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
+.RE
+.PP
+Extract the "sources" directory from the first image in "boot.wim" to the
+current directory:
+.RS
+.PP
+@IMAGEX_PROGNAME@ extract boot.wim 1 /sources
+.RE
+.PP
+Extract multiple files and directories in one command:
+.RS
+.PP
+@IMAGEX_PROGNAME@ extract boot.wim 1 /Windows/Fonts /sources /Windows/System32/cmd.exe
+.RE
+.PP
+
+.SH SEE ALSO
+.BR @IMAGEX_PROGNAME@ (1)
+.BR @IMAGEX_PROGNAME@-apply (1)
+.BR @IMAGEX_PROGNAME@-dir (1)
+.BR @IMAGEX_PROGNAME@-info (1)

diff --git a/programs/imagex.c b/programs/imagex.c
index fb2f08b7576338fc689e91ca9bda496d0028645b..e55828e367fe5449afa8b2fb29b41065183bcaeb 100644 (file)
--- a/programs/imagex.c
+++ b/programs/imagex.c
@@ -127,9 +127,9 @@ IMAGEX_PROGNAME" export SRC_WIMFILE (SRC_IMAGE_NUM | SRC_IMAGE_NAME | all ) \n"
 ),
 [EXTRACT] =
 T(
 ),
 [EXTRACT] =
 T(

-IMAGEX_PROGNAME" extract SRC_WIMFILE (SRC_IMAGE_NUM | SRC_IMAGE_NAME) [PATH...]\n"
-"              [--check] [--ref=\"GLOB\"] [--verbose] [--unix-data] [--no-acls]\n"
-"              [--strict-acls] [--to-stdout] [--dest-dir=DIR]\n"
+IMAGEX_PROGNAME" extract WIMFILE (IMAGE_NUM | IMAGE_NAME) [PATH...]\n"
+"              [--check] [--ref=\"GLOB\"] [--verbose] [--unix-data]\n"
+"              [--no-acls] [--strict-acls] [--to-stdout] [--dest-dir=DIR]\n"

 ),
 [INFO] =
 T(
 ),
 [INFO] =
 T(

diff --git a/src/wimlib.h b/src/wimlib.h
index b522c6877e883f33f02feb1ddb5cffe5c4f4e257..3b3f7f2cefc10c6ce597b5630f81adc3c0b699e0 100644 (file)
--- a/src/wimlib.h
+++ b/src/wimlib.h
@@ -302,7 +302,9 @@ enum wimlib_progress_msg {
         * ::wimlib_progress_info.extract. */
        WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
 
         * ::wimlib_progress_info.extract. */
        WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN,
 

-       /** XXX */
+       /** A file or directory tree within a WIM image (not the full image) is
+        * about to be extracted.  @a info will point to
+        * ::wimlib_progress_info.extract. */

        WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
 
        /** The directory structure of the WIM image is about to be extracted.
        WIMLIB_PROGRESS_MSG_EXTRACT_TREE_BEGIN,
 
        /** The directory structure of the WIM image is about to be extracted.


@@ -331,7 +333,9 @@ enum wimlib_progress_msg {
         * ::wimlib_progress_info.extract. */
        WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END,
 
         * ::wimlib_progress_info.extract. */
        WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END,
 

-       /** XXX */
+       /** A file or directory tree within a WIM image (not the full image) has
+        * been successfully extracted.  @a info will point to
+        * ::wimlib_progress_info.extract. */

        WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END,
 
        /** The directory or NTFS volume is about to be scanned to build a tree
        WIMLIB_PROGRESS_MSG_EXTRACT_TREE_END,
 
        /** The directory or NTFS volume is about to be scanned to build a tree


@@ -771,14 +775,15 @@ struct wimlib_capture_config {
 /* Extract equivalent to ::WIMLIB_ADD_IMAGE_FLAG_RPFIX; force reparse-point
  * fixups on, so absolute symbolic links or junction points will be fixed to be
  * absolute relative to the actual extraction root.  Done by default if
 /* Extract equivalent to ::WIMLIB_ADD_IMAGE_FLAG_RPFIX; force reparse-point
  * fixups on, so absolute symbolic links or junction points will be fixed to be
  * absolute relative to the actual extraction root.  Done by default if

- * WIM_HDR_FLAG_RP_FIX is set in the WIM header. */
+ * WIM_HDR_FLAG_RP_FIX is set in the WIM header.  This flag may only be
+ * specified when extracting a full image. */

 #define WIMLIB_EXTRACT_FLAG_RPFIX                      0x00000100
 
 /** Force reparse-point fixups on extraction off, regardless of the state of the
  * WIM_HDR_FLAG_RP_FIX flag in the WIM header. */
 #define WIMLIB_EXTRACT_FLAG_NORPFIX                    0x00000200
 
 #define WIMLIB_EXTRACT_FLAG_RPFIX                      0x00000100
 
 /** Force reparse-point fixups on extraction off, regardless of the state of the
  * WIM_HDR_FLAG_RP_FIX flag in the WIM header. */
 #define WIMLIB_EXTRACT_FLAG_NORPFIX                    0x00000200
 

-/** Ignore the target directory; only extract file data to standard output. */
+/** Extract files to standard output rather than to the filesystem. */

 #define WIMLIB_EXTRACT_FLAG_TO_STDOUT                  0x00000400
 
 /******************************
 #define WIMLIB_EXTRACT_FLAG_TO_STDOUT                  0x00000400
 
 /******************************


@@ -898,10 +903,17 @@ struct wimlib_update_command {
        };
 };
 
        };
 };
 

-/** XXX */
+/** Specification of a file or directory tree to extract from a WIM image. */

 struct wimlib_extract_command {
 struct wimlib_extract_command {

+       /** Path to file or directory tree within the WIM image to extract.  It
+        * must be provided as an absolute path from the root of the WIM image.
+        * The path separators may be either forward slashes or backslashes. */

        wimlib_tchar *wim_source_path;
        wimlib_tchar *wim_source_path;

+
+       /** Filesystem path to extract the file or directory tree to. */

        wimlib_tchar *fs_dest_path;
        wimlib_tchar *fs_dest_path;

+
+       /** Bitwise or of zero or more of the WIMLIB_EXTRACT_FLAG_* flags. */

        int extract_flags;
 };
 
        int extract_flags;
 };
 


@@ -1289,7 +1301,68 @@ wimlib_export_image(WIMStruct *src_wim, int src_image,
                    unsigned num_additional_swms,
                    wimlib_progress_func_t progress_func);
 
                    unsigned num_additional_swms,
                    wimlib_progress_func_t progress_func);
 

-/** XXX */
+/**
+ * Extract zero or more files or directory trees from a WIM image.
+ *
+ * This generalizes the single-image extraction functionality of
+ * wimlib_extract_image() to allow extracting only the specified subsets of the
+ * image.
+ *
+ * @param wim
+ *     Pointer to the ::WIMStruct for a standalone WIM file, or part 1 of a
+ *     split WIM.
+ *
+ * @param image
+ *     The 1-based number of the image in @a wim from which the files or
+ *     directory trees are to be extracted.  It cannot be ::WIMLIB_ALL_IMAGES.
+ *
+ * @param default_extract_flags
+ *     Default extraction flags; the behavior shall be as if these flags had
+ *     been specified in the ::wimlib_extract_command.extract_flags member in
+ *     each extraction command, in combination with any flags already present.
+ *
+ * @param cmds
+ *     An array of ::wimlib_extract_command structures that specifies the
+ *     extractions to perform.
+ *
+ * @param num_cmds
+ *     Number of commands in the @a cmds array.
+ *
+ * @param additional_swms
+ *     Array of pointers to the ::WIMStruct for each additional part in the
+ *     split WIM.  Ignored if @a num_additional_swms is 0.  The pointers do not
+ *     need to be in any particular order, but they must include all parts of
+ *     the split WIM other than the first part, which must be provided in the
+ *     @a wim parameter.
+ *
+ * @param num_additional_swms
+ *     Number of additional WIM parts provided in the @a additional_swms array.
+ *     This number should be one less than the total number of parts in the
+ *     split WIM.  Set to 0 if the WIM is a standalone WIM.
+ *
+ * @param progress_func
+ *     If non-NULL, a function that will be called periodically with the
+ *     progress of the current operation.
+ *
+ * @return 0 on success; nonzero on error.  The possible error codes include
+ * those documented as returned by wimlib_extract_image() as well as the
+ * following additional error codes:
+ *
+ * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST
+ *     The ::wimlib_extract_command.wim_source_path member in one of the
+ *     extract commands did not exist in the WIM.
+ * @retval ::WIMLIB_ERR_NOT_A_REGULAR_FILE
+ *     ::WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified for an extraction command
+ *     in which ::wimlib_extract_command.wim_source_path existed but was not a
+ *     regular file or directory.
+ * @retval ::WIMLIB_ERR_INVALID_PARAM
+ *     ::WIMLIB_EXTRACT_FLAG_HARDLINK or ::WIMLIB_EXTRACT_FLAG_SYMLINK was
+ *     specified for some commands but not all; or
+ *     ::wimlib_extract_command.fs_dest_path was @c NULL or the empty string
+ *     for one or more commands; or ::WIMLIB_EXTRACT_FLAG_RPFIX was specified
+ *     for a command in which ::wimlib_extract_command.wim_source_path did not
+ *     specify the root directory of the WIM image.
+ */

 extern int
 wimlib_extract_files(WIMStruct *wim,
                     int image,
 extern int
 wimlib_extract_files(WIMStruct *wim,
                     int image,