+ * @ingroup G_extracting_wims
+ *
+ * Since wimlib v1.6.0: Extract zero or more paths (files or directory trees)
+ * from the specified WIM image.
+ *
+ * By default, each path will be extracted to a corresponding subdirectory of
+ * the 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". This behavior
+ * can be changed by providing the flag
+ * ::WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE, which will cause each file
+ * or directory tree to be placed directly in the target directory --- so the
+ * same example would extract "/Windows/explorer.exe" to "outdir/explorer.exe".
+ *
+ * Symbolic links will not be dereferenced when paths in the WIM image are
+ * interpreted.
+ *
+ * @param wim
+ * WIM from which to extract the paths, specified as a pointer to the
+ * ::WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a
+ * split WIM. In the case of a WIM file that is not standalone, this
+ * ::WIMStruct must have had any needed external resources previously
+ * referenced using wimlib_reference_resources() or
+ * wimlib_reference_resource_files().
+ * @param image
+ * 1-based index of the WIM image from which to extract the paths.
+ * @param paths
+ * Array of paths to extract. Each element must be the absolute path to a
+ * file or directory within the WIM image. Separators may be either
+ * forwards or backwards slashes, and leading path separators are optional.
+ * The paths will be interpreted either case-sensitively (UNIX default) or
+ * case-insensitively (Windows default); this can be changed by
+ * wimlib_global_init().
+ * <br/>
+ * By default, the characters @c * and @c ? are interpreted literally.
+ * This can be changed by specifying ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS in @p
+ * extract_flags.
+ * <br/>
+ * By default, if any paths to extract do not exist, the error code
+ * ::WIMLIB_ERR_PATH_DOES_NOT_EXIST is returned. This behavior changes if
+ * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS is specified in @p extract_flags.
+ * @param num_paths
+ * Number of paths specified in @p paths.
+ * @param target
+ * Directory to which to extract the paths; or with
+ * ::WIMLIB_EXTRACT_FLAG_NTFS specified in @p extract_flags, the path to an
+ * unmounted NTFS volume to which to extract the paths. Unlike the @p
+ * paths being extracted, the @p target must be native path. On UNIX-like
+ * systems it may not contain backslashes, for example.
+ * @param extract_flags
+ * Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG.
+ * @param progress_func
+ * If non-NULL, a function that will be called periodically with the
+ * progress of the current operation. The main message to look for is
+ * ::WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS; however, there are others as
+ * well. Note: because the extraction code is stream-based and not
+ * file-based, there is no way to get information about which path is
+ * currently being extracted, but based on byte count you can still
+ * calculate an approximate percentage complete for the extraction overall
+ * which may be all you really need anyway.
+ *
+ * @return 0 on success; nonzero on error. Most of the error codes are the same
+ * as those returned by wimlib_extract_image(). Below, some of the error codes
+ * returned in situations specific to path-mode extraction are documented:
+ *
+ * @retval ::WIMLIB_ERR_INVALID_IMAGE
+ * @p image was ::WIMLIB_ALL_IMAGES or was otherwise not a valid single
+ * image in the WIM.
+ * @retval ::WIMLIB_ERR_PATH_DOES_NOT_EXIST
+ * One of the paths to extract did not exist in the WIM image. This error
+ * code can only be returned if ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS was not
+ * specified in @p extract_flags, or if both
+ * ::WIMLIB_EXTRACT_FLAG_GLOB_PATHS and ::WIMLIB_EXTRACT_FLAG_STRICT_GLOB
+ * were specified in @p extract_flags.
+ * @retval ::WIMLIB_ERR_NOT_A_REGULAR_FILE
+ * ::WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified in @p extract_flags, but
+ * one of the paths to extract did not name a regular file.