Update docs for path extraction
authorEric Biggers <ebiggers3@gmail.com>
Sat, 28 Dec 2013 22:45:36 +0000 (16:45 -0600)
committerEric Biggers <ebiggers3@gmail.com>
Sat, 28 Dec 2013 22:45:36 +0000 (16:45 -0600)
doc/imagex-extract.1.in
include/wimlib.h

index 33bf9f7..d4b34ba 100644 (file)
@@ -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.
index c2cd9f0..71317c5 100644 (file)
@@ -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.