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"-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]
.SH SEE ALSO
.BR @IMAGEX_PROGNAME@ (1)
-
+.BR @IMAGEX_PROGNAME@-extract (1)
--- /dev/null
+.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)
),
[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(
* ::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_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
/* 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
-/** 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
/******************************
};
};
-/** XXX */
+/** Specification of a file or directory tree to extract from a WIM image. */
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;
+
+ /** Filesystem path to extract the file or directory tree to. */
wimlib_tchar *fs_dest_path;
+
+ /** Bitwise or of zero or more of the WIMLIB_EXTRACT_FLAG_* flags. */
int extract_flags;
};
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,