From: Eric Biggers Date: Sat, 28 Dec 2013 22:45:36 +0000 (-0600) Subject: Update docs for path extraction X-Git-Tag: v1.6.0~67 X-Git-Url: https://wimlib.net/git/?p=wimlib;a=commitdiff_plain;h=0ae4701460fdaa6d1c446e0e4fb7297319732533 Update docs for path extraction --- diff --git a/doc/imagex-extract.1.in b/doc/imagex-extract.1.in index 33bf9f7e..d4b34bae 100644 --- a/doc/imagex-extract.1.in +++ b/doc/imagex-extract.1.in @@ -54,12 +54,16 @@ each line, leading and trailing whitespace is ignored, and lines beginning with the ';' character and otherwise empty lines are ignored. Each path must be unquoted and must specify a full path in the WIM image, as described above. However, unless \fB--no-wildcards\fR is specified, each path in the list file -may also contain the wildcard characters '?' and '*', and therefore may expand -to multiple actual files or directories. By default, a path or wildcard glob -that matches no files or directories in the WIM image only produces a warning; -use \fB--strict-wildcards\fR if you want an error instead. Also, when using a -list file, files and directories not located at the root of the WIM image will -be extracted to a corresponding subdirectory of the destination directory rather +may also contain the wildcard characters '?' and '*'. The '?' character matches +any character other than a path separator, whereas the '*' character matches +zero or more non-path-separator characters. Consequently, a single wildcard +pattern may expand to multiple actual files or directories. +.PP +In the \fILISTFILE\fR mode, by default a wildcard pattern that matches no files +or directories in the WIM image only produces a warning; use +\fB--strict-wildcards\fR if you want an error instead. Also, when using a list +file, files and directories not located at the root of the WIM image will be +extracted to a corresponding subdirectory of the destination directory rather than directly to the destination directory itself. .SH SPLIT WIMS You may use \fB@IMAGEX_PROGNAME@ extract\fR to extract files or directory trees @@ -104,8 +108,11 @@ current working directory. Do not interpret wildcard characters in paths in the \fILISTFILE\fR. .TP \fB--strict-wildcards\fR -Fail if any wildcards or paths in \fILISTFILE\fR do not match any files in the -WIM image. The default behavior is to warn only. +Fail if any wildcard patterns in \fILISTFILE\fR do not match any files or +directories in the WIM image. The default behavior is to warn only. This +option has no effect if \fB--no-wildcards\fR is also specified or if \fIPATH\fRs +are specified instead of a \fILISTFILE\fR; in those cases, an error is issued if +any file to extract does not exist. .SH NOTES See the documentation \fB@IMAGEX_PROGNAME@ apply\fR (1) for documentation about what data and metadata are extracted on UNIX-like systems versus on Windows. diff --git a/include/wimlib.h b/include/wimlib.h index c2cd9f03..71317c58 100644 --- a/include/wimlib.h +++ b/include/wimlib.h @@ -1388,9 +1388,16 @@ typedef int (*wimlib_iterate_lookup_table_callback_t)(const struct wimlib_resour #define WIMLIB_EXTRACT_FLAG_FILE_ORDER 0x00020000 /** For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the - * paths in the WIM as case-insensitive globs which may contain the characters - * '?' and '*'. The '?' character matches any character, whereas the '*' - * character matches zero or more characters in the same path component. */ + * paths in the WIM as "glob" patterns which may contain the wildcard characters + * '?' and '*'. The '?' character matches any character except a path + * separator, whereas the '*' character matches zero or more non-path-separator + * characters. Each glob pattern may match zero or more paths in the WIM file. + * If a glob pattern ends in a path separator, it will only match directories + * (including reparse points with FILE_ATTRIBUTE_DIRECTORY set). By default, if + * a glob pattern does not match any files, a warning but not an error will be + * issued, even if the glob pattern did not actually contain wildcard + * characters. Use ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB to get an error instead. + */ #define WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000 /** In combination with ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error @@ -2354,8 +2361,8 @@ wimlib_extract_image_from_pipe(int pipe_fd, /** * Similar to wimlib_extract_paths(), but the paths to extract from the WIM - * image specified in the UTF-8 text file @p path_list_file which itself - * contains the list of paths to use, one per line. Leading and trailing + * image specified in the UTF-8 text file named by @p path_list_file which + * itself contains the list of paths to use, one per line. Leading and trailing * whitespace, and otherwise empty lines and lines beginning with the ';' * character are ignored. No quotes are needed as paths are otherwise delimited * by the newline character. @@ -2369,9 +2376,25 @@ wimlib_extract_pathlist(WIMStruct *wim, int image, /** * Similar to wimlib_extract_files(), but the files or directories to extract - * from the WIM image are specified as an array of paths. Each path will be - * extracted to a corresponding location in @p target based on its location in - * the WIM image. + * from the WIM image are specified as an array of paths. + * + * Each path will be extracted to a corresponding subdirectory of the @p target + * based on its location in the WIM image. For example, if one of the paths to + * extract is "/Windows/explorer.exe" and the target is "outdir", the file will + * be extracted to "outdir/Windows/explorer.exe". Each path to extract must be + * specified as the absolute path to a directory within the WIM image. + * Separators in the paths to extract may be either forwards or backwards + * slashes, and leading path separators are optional. Symbolic links are not + * dereferenced when interpreting paths to extract. Paths to extract will be + * interpreted either case-sensitively (UNIX default) or case-insensitively + * (Windows default); this can be changed by wimlib_global_init(). + * + * The @p target path, on the other hand, is expected to be a native path. On + * UNIX-like systems it may not contain backslashes, for example. + * + * By default, if any paths to extract do not exist, + * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST is issued. This behavior changes if + * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS is specified. * * With ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified in @p extract_flags, this * function additionally allows paths to be globs using the wildcard characters @@ -2554,7 +2577,8 @@ wimlib_get_xml_data(WIMStruct *wim, void **buf_ret, size_t *bufsize_ret); * Initialization function for wimlib. Call before using any other wimlib * function except wimlib_set_print_errors(). If not done manually, this * function will be called automatically with @p init_flags set to - * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. + * ::WIMLIB_INIT_FLAG_ASSUME_UTF8. This function does nothing if called again + * after it has already successfully run. * * @param init_flags * Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG.