From 2b2a672da8d6860b6677c1987ddb196f5dce313f Mon Sep 17 00:00:00 2001 From: Eric Biggers Date: Sun, 5 May 2013 15:18:06 -0500 Subject: [PATCH] Document imagex-extract and wimlib_extract_files() --- Makefile.am | 1 + configure.ac | 1 + doc/imagex-apply.1.in | 2 +- doc/imagex-extract.1.in | 142 ++++++++++++++++++++++++++++++++++++++++ programs/imagex.c | 6 +- src/wimlib.h | 85 ++++++++++++++++++++++-- 6 files changed, 227 insertions(+), 10 deletions(-) create mode 100644 doc/imagex-extract.1.in diff --git a/Makefile.am b/Makefile.am index 1ba1c796..94af43dc 100644 --- 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@-extract.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 48aa4ad6..7fca1542 100644 --- 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"-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] diff --git a/doc/imagex-apply.1.in b/doc/imagex-apply.1.in index 5db59f92..76913a32 100644 --- 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) - +.BR @IMAGEX_PROGNAME@-extract (1) diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in new file mode 100644 index 00000000..f6bbedad --- /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 fb2f08b7..e55828e3 100644 --- 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( -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( diff --git a/src/wimlib.h b/src/wimlib.h index b522c687..3b3f7f2c 100644 --- 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, - /** 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. @@ -331,7 +333,9 @@ enum wimlib_progress_msg { * ::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 @@ -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 - * 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 /****************************** @@ -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 { + /** 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; }; @@ -1289,7 +1301,68 @@ wimlib_export_image(WIMStruct *src_wim, int src_image, 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, -- 2.43.0