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
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.
#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
/**
* 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.
/**
* 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
* 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.
git://wimlib.net / wimlib / commitdiff