Loading...
Searching...
No Matches
Extracting WIMs

Extract files, directories, and images from a WIM. More...

## Macros

#define | WIMLIB_EXTRACT_FLAG_NTFS 0x00000001
| Extract the image directly to an NTFS volume rather than a generic directory.
#define | WIMLIB_EXTRACT_FLAG_RECOVER_DATA 0x00000002
| Since wimlib v1.13.4: Don't consider corrupted files to be an error.
#define | WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020
| UNIX-like systems only: Extract UNIX-specific metadata captured with WIMLIB_ADD_FLAG_UNIX_DATA.
#define | WIMLIB_EXTRACT_FLAG_NO_ACLS 0x00000040
| Do not extract security descriptors.
#define | WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080
| Fail immediately if the full security descriptor of any file or directory cannot be set exactly as specified in the WIM image.
#define | WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100
| This is the extraction equivalent to WIMLIB_ADD_FLAG_RPFIX.
#define | WIMLIB_EXTRACT_FLAG_NORPFIX 0x00000200
| 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_TO_STDOUT 0x00000400
| For wimlib_extract_paths() and wimlib_extract_pathlist() only: Extract the paths, each of which must name a regular file, to standard output.
#define | WIMLIB_EXTRACT_FLAG_REPLACE_INVALID_FILENAMES 0x00000800
| Instead of ignoring files and directories with names that cannot be represented on the current platform (note: Windows has more restrictions on filenames than POSIX-compliant systems), try to replace characters or append junk to the names so that they can be extracted in some form.
#define | WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS 0x00001000
| On Windows, when there exist two or more files with the same case insensitive name but different case sensitive names, try to extract them all by appending junk to the end of them, rather than arbitrarily extracting only one.
#define | WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS 0x00002000
| Do not ignore failure to set timestamps on extracted files.
#define | WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000
| Do not ignore failure to set short names on extracted files.
#define | WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000
| Do not ignore failure to extract symbolic links and junctions due to permissions problems.
#define | WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000
| For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the paths to extract as wildcard patterns ("globs") which may contain the wildcard characters ``?
#define | WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000
| In combination with WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error (WIMLIB_ERR_PATH_DOES_NOT_EXIST) rather than a warning to be issued when one of the provided globs did not match a file.
#define | WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES 0x00100000
| Do not extract Windows file attributes such as readonly, hidden, etc.
#define | WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000
| For wimlib_extract_paths() and wimlib_extract_pathlist() only: Do not preserve the directory structure of the archive when extracting — that is, place each extracted file or directory tree directly in the target directory.
#define | WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000
| Windows only: Extract files as "pointers" back to the WIM archive.
#define | WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000
| Since wimlib v1.8.2 and Windows-only: compress the extracted files using System Compression, when possible.
#define | WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000
| Like WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with 8192 byte chunks.
#define | WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000
| Like WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with 16384 byte chunks.
#define | WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000
| Like WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with 32768 byte chunks.

## Functions

WIMLIBAPI int | wimlib_extract_image (WIMStruct *wim, int image, const wimlib_tchar *target, int extract_flags)
| Extract an image, or all images, from a WIMStruct.
WIMLIBAPI int | wimlib_extract_image_from_pipe (int pipe_fd, const wimlib_tchar *image_num_or_name, const wimlib_tchar *target, int extract_flags)
| Extract one image from a pipe on which a pipable WIM is being sent.
WIMLIBAPI int | wimlib_extract_image_from_pipe_with_progress (int pipe_fd, const wimlib_tchar *image_num_or_name, const wimlib_tchar *target, int extract_flags, wimlib_progress_func_t progfunc, void *progctx)
| Same as wimlib_extract_image_from_pipe(), but allows specifying a progress function.
WIMLIBAPI int | wimlib_extract_pathlist (WIMStruct *wim, int image, const wimlib_tchar *target, const wimlib_tchar *path_list_file, int extract_flags)
| Similar to wimlib_extract_paths(), but the paths to extract from the WIM image are specified in the ASCII, UTF-8, or UTF-16LE text file named by `path_list_file` which itself contains the list of paths to use, one per line.
WIMLIBAPI int | wimlib_extract_paths (WIMStruct *wim, int image, const wimlib_tchar *target, const wimlib_tchar *const *paths, size_t num_paths, int extract_flags)
| Extract zero or more paths (files or directory trees) from the specified WIM image.

## Detailed Description

Extract files, directories, and images from a WIM.

wimlib_extract_image() extracts, or "applies", an image from a WIM, represented by a WIMStruct. This normally extracts the image to a directory, but when supported by the build of the library there is also a special NTFS volume extraction mode (entered when WIMLIB_EXTRACT_FLAG_NTFS is specified) that allows extracting a WIM image directly to an unmounted NTFS volume. Various other flags allow further customization of image extraction.

wimlib_extract_paths() and wimlib_extract_pathlist() allow extracting a list of (possibly wildcard) paths from a WIM image.

wimlib_extract_image_from_pipe() extracts an image from a pipable WIM sent over a pipe; see Pipable WIMs.

Some details of how WIM extraction works are described more fully in the documentation for wimapply and wimextract.

## Macro Definition Documentation

## WIMLIB_EXTRACT_FLAG_NTFS

#define WIMLIB_EXTRACT_FLAG_NTFS 0x00000001

Extract the image directly to an NTFS volume rather than a generic directory.

This mode is only available if wimlib was compiled with libntfs-3g support; if not, WIMLIB_ERR_UNSUPPORTED will be returned. In this mode, the extraction target will be interpreted as the path to an NTFS volume image (as a regular file or block device) rather than a directory. It will be opened using libntfs-3g, and the image will be extracted to the NTFS filesystem's root directory. Note: this flag cannot be used when wimlib_extract_image() is called with WIMLIB_ALL_IMAGES as the `image`, nor can it be used with wimlib_extract_paths() when passed multiple paths.

## WIMLIB_EXTRACT_FLAG_RECOVER_DATA

#define WIMLIB_EXTRACT_FLAG_RECOVER_DATA 0x00000002

Since wimlib v1.13.4: Don't consider corrupted files to be an error.

Just extract them in whatever form we can.

## WIMLIB_EXTRACT_FLAG_UNIX_DATA

#define WIMLIB_EXTRACT_FLAG_UNIX_DATA 0x00000020

UNIX-like systems only: Extract UNIX-specific metadata captured with WIMLIB_ADD_FLAG_UNIX_DATA.

## WIMLIB_EXTRACT_FLAG_NO_ACLS

#define WIMLIB_EXTRACT_FLAG_NO_ACLS 0x00000040

Do not extract security descriptors.

This flag cannot be combined with WIMLIB_EXTRACT_FLAG_STRICT_ACLS.

## WIMLIB_EXTRACT_FLAG_STRICT_ACLS

#define WIMLIB_EXTRACT_FLAG_STRICT_ACLS 0x00000080

Fail immediately if the full security descriptor of any file or directory cannot be set exactly as specified in the WIM image.

On Windows, the default behavior without this flag when wimlib does not have permission to set the correct security descriptor is to fall back to setting the security descriptor with the SACL omitted, then with the DACL omitted, then with the owner omitted, then not at all. This flag cannot be combined with WIMLIB_EXTRACT_FLAG_NO_ACLS.

## WIMLIB_EXTRACT_FLAG_RPFIX

#define WIMLIB_EXTRACT_FLAG_RPFIX 0x00000100

This is the extraction equivalent to WIMLIB_ADD_FLAG_RPFIX.

This forces reparse-point fixups on, so absolute symbolic links or junction points will be fixed to be absolute relative to the actual extraction root. Reparse- point fixups are done by default for wimlib_extract_image() and wimlib_extract_image_from_pipe() if `WIM_HDR_FLAG_RP_FIX` is set in the WIM header. This flag cannot be combined with WIMLIB_EXTRACT_FLAG_NORPFIX.

## WIMLIB_EXTRACT_FLAG_NORPFIX

#define WIMLIB_EXTRACT_FLAG_NORPFIX 0x00000200

Force reparse-point fixups on extraction off, regardless of the state of the WIM_HDR_FLAG_RP_FIX flag in the WIM header.

This flag cannot be combined with WIMLIB_EXTRACT_FLAG_RPFIX.

## WIMLIB_EXTRACT_FLAG_TO_STDOUT

#define WIMLIB_EXTRACT_FLAG_TO_STDOUT 0x00000400

For wimlib_extract_paths() and wimlib_extract_pathlist() only: Extract the paths, each of which must name a regular file, to standard output.

## WIMLIB_EXTRACT_FLAG_REPLACE_INVALID_FILENAMES

#define WIMLIB_EXTRACT_FLAG_REPLACE_INVALID_FILENAMES 0x00000800

Instead of ignoring files and directories with names that cannot be represented on the current platform (note: Windows has more restrictions on filenames than POSIX-compliant systems), try to replace characters or append junk to the names so that they can be extracted in some form.

Note: this flag is unlikely to have any effect when extracting a WIM image that was captured on Windows.

## WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS

#define WIMLIB_EXTRACT_FLAG_ALL_CASE_CONFLICTS 0x00001000

On Windows, when there exist two or more files with the same case insensitive name but different case sensitive names, try to extract them all by appending junk to the end of them, rather than arbitrarily extracting only one.

Note: this flag is unlikely to have any effect when extracting a WIM image that was captured on Windows.

## WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS

#define WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS 0x00002000

Do not ignore failure to set timestamps on extracted files.

This flag currently only has an effect when extracting to a directory on UNIX-like systems.

## WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES

#define WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES 0x00004000

Do not ignore failure to set short names on extracted files.

This flag currently only has an effect on Windows.

## WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS

#define WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS 0x00008000

Do not ignore failure to extract symbolic links and junctions due to permissions problems.

This flag currently only has an effect on Windows. By default, such failures are ignored since the default configuration of Windows only allows the Administrator to create symbolic links.

## WIMLIB_EXTRACT_FLAG_GLOB_PATHS

#define WIMLIB_EXTRACT_FLAG_GLOB_PATHS 0x00040000

For wimlib_extract_paths() and wimlib_extract_pathlist() only: Treat the paths to extract as wildcard patterns ("globs") which may contain the wildcard characters ``?

and `*`. The ``? character matches any non-path-separator character, whereas the `*` character matches zero or more non-path-separator characters. Consequently, each glob may match zero or more actual paths in the WIM image.

By default, if a glob does not match any files, a warning but not an error will be issued. This is the case even if the glob did not actually contain wildcard characters. Use WIMLIB_EXTRACT_FLAG_STRICT_GLOB to get an error instead.

## WIMLIB_EXTRACT_FLAG_STRICT_GLOB

#define WIMLIB_EXTRACT_FLAG_STRICT_GLOB 0x00080000

In combination with WIMLIB_EXTRACT_FLAG_GLOB_PATHS, causes an error (WIMLIB_ERR_PATH_DOES_NOT_EXIST) rather than a warning to be issued when one of the provided globs did not match a file.

## WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES

#define WIMLIB_EXTRACT_FLAG_NO_ATTRIBUTES 0x00100000

Do not extract Windows file attributes such as readonly, hidden, etc.

This flag has an effect on Windows as well as in the NTFS-3G extraction mode.

## WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE

#define WIMLIB_EXTRACT_FLAG_NO_PRESERVE_DIR_STRUCTURE 0x00200000

For wimlib_extract_paths() and wimlib_extract_pathlist() only: Do not preserve the directory structure of the archive when extracting — that is, place each extracted file or directory tree directly in the target directory.

The target directory will still be created if it does not already exist.

## WIMLIB_EXTRACT_FLAG_WIMBOOT

#define WIMLIB_EXTRACT_FLAG_WIMBOOT 0x00400000

Windows only: Extract files as "pointers" back to the WIM archive.

The effects of this option are fairly complex. See the documentation for the –wimboot option of wimapply for more information.

## WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K

#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K 0x01000000

Since wimlib v1.8.2 and Windows-only: compress the extracted files using System Compression, when possible.

This only works on either Windows 10 or later, or on an older Windows to which Microsoft's wofadk.sys driver has been added. Several different compression formats may be used with System Compression; this particular flag selects the XPRESS compression format with 4096 byte chunks.

## WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K

#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS8K 0x02000000

Like WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with 8192 byte chunks.

## WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K

#define WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS16K 0x04000000

Like WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use XPRESS compression with 16384 byte chunks.

## WIMLIB_EXTRACT_FLAG_COMPACT_LZX

#define WIMLIB_EXTRACT_FLAG_COMPACT_LZX 0x08000000

Like WIMLIB_EXTRACT_FLAG_COMPACT_XPRESS4K, but use LZX compression with 32768 byte chunks.

## Function Documentation

## wimlib_extract_image()

WIMLIBAPI int wimlib_extract_image | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | target,
|  | int | extract_flags )

Extract an image, or all images, from a WIMStruct.

The exact behavior of how wimlib extracts files from a WIM image is controllable by the `extract_flags` parameter, but there also are differences depending on the platform (UNIX-like vs Windows). See the documentation for wimapply for more information, including about the NTFS-3G extraction mode.

Parameters

  wim | The WIM from which to extract the image(s), 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().
  image | The 1-based index of the image to extract, or WIMLIB_ALL_IMAGES to extract all images. Note: WIMLIB_ALL_IMAGES is unsupported in NTFS-3G extraction mode.
  target | A null-terminated string which names the location to which the image(s) will be extracted. By default, this is interpreted as a path to a directory. Alternatively, if WIMLIB_EXTRACT_FLAG_NTFS is specified in `extract_flags`, then this is interpreted as a path to an unmounted NTFS volume.
  extract_flags | Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_DECOMPRESSION | The WIM file contains invalid compressed data.
  WIMLIB_ERR_INVALID_IMAGE | `image` does not exist in `wim`.
  WIMLIB_ERR_INVALID_METADATA_RESOURCE | The metadata for an image to extract was invalid.
  WIMLIB_ERR_INVALID_PARAM | The extraction flags were invalid; more details may be found in the documentation for the specific extraction flags that were specified. Or `target` was `NULL` or an empty string, or `wim` was `NULL`.
  WIMLIB_ERR_INVALID_RESOURCE_HASH | The data of a file that needed to be extracted was corrupt.
  WIMLIB_ERR_LINK | Failed to create a symbolic link or a hard link.
  WIMLIB_ERR_METADATA_NOT_FOUND | `wim` does not contain image metadata; for example, it represents a non-first part of a split WIM.
  WIMLIB_ERR_MKDIR | Failed create a directory.
  WIMLIB_ERR_NTFS_3G | libntfs-3g reported that a problem occurred while writing to the NTFS volume.
  WIMLIB_ERR_OPEN | Could not create a file, or failed to open an already-extracted file.
  WIMLIB_ERR_READ | Failed to read data from the WIM.
  WIMLIB_ERR_READLINK | Failed to determine the target of a symbolic link in the WIM.
  WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED | Failed to fix the target of an absolute symbolic link (e.g. if the target would have exceeded the maximum allowed length). (Only if reparse data was supported by the extraction mode and WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS was specified in `extract_flags`.)
  WIMLIB_ERR_RESOURCE_NOT_FOUND | A file data blob that needed to be extracted could not be found in the blob lookup table of `wim`. See Creating and handling non-standalone WIMs.
  WIMLIB_ERR_SET_ATTRIBUTES | Failed to set attributes on a file.
  WIMLIB_ERR_SET_REPARSE_DATA | Failed to set reparse data on a file (only if reparse data was supported by the extraction mode).
  WIMLIB_ERR_SET_SECURITY | Failed to set security descriptor on a file.
  WIMLIB_ERR_SET_SHORT_NAME | Failed to set the short name of a file.
  WIMLIB_ERR_SET_TIMESTAMPS | Failed to set timestamps on a file.
  WIMLIB_ERR_UNEXPECTED_END_OF_FILE | Unexpected end-of-file occurred when reading data from the WIM.

  WIMLIB_ERR_UNSUPPORTED

  A requested extraction flag, or the data or metadata that must be extracted to support it, is unsupported in the build and configuration of wimlib, or on the current platform or extraction mode or target volume. Flags affected by this include WIMLIB_EXTRACT_FLAG_NTFS, WIMLIB_EXTRACT_FLAG_UNIX_DATA, WIMLIB_EXTRACT_FLAG_STRICT_ACLS, WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES, WIMLIB_EXTRACT_FLAG_STRICT_TIMESTAMPS, and WIMLIB_EXTRACT_FLAG_STRICT_SYMLINKS. For example, if WIMLIB_EXTRACT_FLAG_STRICT_SHORT_NAMES is specified in `extract_flags`, WIMLIB_ERR_UNSUPPORTED will be returned if the WIM image contains one or more files with short names, but extracting short names is not supported — on Windows, this occurs if the target volume does not support short names, while on non-Windows, this occurs if WIMLIB_EXTRACT_FLAG_NTFS was not specified in `extract_flags`.

  WIMLIB_ERR_WIMBOOT | WIMLIB_EXTRACT_FLAG_WIMBOOT was specified in `extract_flags`, but there was a problem creating WIMBoot pointer files or registering a source WIM file with the Windows Overlay Filesystem (WOF) driver.
  WIMLIB_ERR_WRITE | Failed to write data to a file being extracted.

If a progress function is registered with `wim`, then as each image is extracted it will receive WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_BEGIN, then zero or more WIMLIB_PROGRESS_MSG_EXTRACT_FILE_STRUCTURE messages, then zero or more WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS messages, then zero or more WIMLIB_PROGRESS_MSG_EXTRACT_METADATA messages, then WIMLIB_PROGRESS_MSG_EXTRACT_IMAGE_END.

## wimlib_extract_image_from_pipe()

WIMLIBAPI int wimlib_extract_image_from_pipe | ( | int | pipe_fd,
|  | const wimlib_tchar * | image_num_or_name,
|  | const wimlib_tchar * | target,
|  | int | extract_flags )

Extract one image from a pipe on which a pipable WIM is being sent.

See the documentation for WIMLIB_WRITE_FLAG_PIPABLE, and Pipable WIMs, for more information about pipable WIMs.

This function operates in a special way to read the WIM fully sequentially. As a result, there is no WIMStruct is made visible to library users, and you cannot call wimlib_open_wim() on the pipe. (You can, however, use wimlib_open_wim() to transparently open a pipable WIM if it's available as a seekable file, not a pipe.)

Parameters

  pipe_fd | File descriptor, which may be a pipe, opened for reading and positioned at the start of the pipable WIM.

  image_num_or_name

  String that specifies the 1-based index or name of the image to extract. It is translated to an image index using the same rules that wimlib_resolve_image() uses. However, unlike wimlib_extract_image(), only a single image (not all images) can be specified. Alternatively, specify `NULL` here to use the first image in the WIM if it contains exactly one image but otherwise return WIMLIB_ERR_INVALID_IMAGE.

  target | Same as the corresponding parameter to wimlib_extract_image().
  extract_flags | Same as the corresponding parameter to wimlib_extract_image().

Returns
  0 on success; a wimlib_error_code value on failure. The possible error codes include those returned by wimlib_extract_image() and wimlib_open_wim() as well as the following:

Return values

  WIMLIB_ERR_INVALID_PIPABLE_WIM | Data read from the pipable WIM was invalid.
  WIMLIB_ERR_NOT_PIPABLE | The WIM being piped over `pipe_fd` is a normal WIM, not a pipable WIM.

## wimlib_extract_image_from_pipe_with_progress()

WIMLIBAPI int wimlib_extract_image_from_pipe_with_progress | ( | int | pipe_fd,
|  | const wimlib_tchar * | image_num_or_name,
|  | const wimlib_tchar * | target,
|  | int | extract_flags,
|  | wimlib_progress_func_t | progfunc,
|  | void * | progctx )

Same as wimlib_extract_image_from_pipe(), but allows specifying a progress function.

The progress function will be used while extracting the image and will receive the normal extraction progress messages, such as WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS, in addition to WIMLIB_PROGRESS_MSG_EXTRACT_SPWM_PART_BEGIN.

## wimlib_extract_pathlist()

WIMLIBAPI int wimlib_extract_pathlist | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | target,
|  | const wimlib_tchar * | path_list_file,
|  | int | extract_flags )

Similar to wimlib_extract_paths(), but the paths to extract from the WIM image are specified in the ASCII, UTF-8, or UTF-16LE text file named by `path_list_file` which itself contains the list of paths to use, one per line.

Leading and trailing whitespace is ignored. Empty lines and lines beginning with the ';' or '#' characters are ignored. No quotes are needed, as paths are otherwise delimited by the newline character. However, quotes will be stripped if present.

If `path_list_file` is `NULL`, then the pathlist file is read from standard input.

The error codes are the same as those returned by wimlib_extract_paths(), except that wimlib_extract_pathlist() returns an appropriate error code if it cannot read the path list file (e.g. WIMLIB_ERR_OPEN, WIMLIB_ERR_STAT, WIMLIB_ERR_READ).

## wimlib_extract_paths()

WIMLIBAPI int wimlib_extract_paths | ( | WIMStruct * | wim,
|  | int | image,
|  | const wimlib_tchar * | target,
|  | const wimlib_tchar *const * | paths,
|  | size_t | num_paths,
|  | int | extract_flags )

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 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`.

With globbing turned off (the default), paths are always checked for existence strictly; that is, if any path to extract does not exist in the image, then nothing is extracted and the function fails with WIMLIB_ERR_PATH_DOES_NOT_EXIST. But with globbing turned on (WIMLIB_EXTRACT_FLAG_GLOB_PATHS specified), globs are by default permitted to match no files, and there is a flag (WIMLIB_EXTRACT_FLAG_STRICT_GLOB) to enable the strict behavior if desired.

Symbolic links are not dereferenced when paths in the image are interpreted.

Parameters

  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().
  image | The 1-based index of the WIM image from which to extract the paths.

  paths

  Array of paths to extract. Each element must be the absolute path to a file or directory within the image. Path 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); however, the case sensitivity can be configured explicitly at library initialization time by passing an appropriate flag to wimlib_global_init().
  By default, "globbing" is disabled, so the characters `*` and ``? are interpreted literally. This can be changed by specifying WIMLIB_EXTRACT_FLAG_GLOB_PATHS in `extract_flags`.

  num_paths | Number of paths specified in `paths`.
  target | Directory to which to extract the paths.
  extract_flags | Bitwise OR of flags prefixed with WIMLIB_EXTRACT_FLAG.

Returns
  0 on success; a wimlib_error_code value on failure. 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:

Return values

  WIMLIB_ERR_NOT_A_REGULAR_FILE | WIMLIB_EXTRACT_FLAG_TO_STDOUT was specified in `extract_flags`, but one of the paths to extract did not name a regular file.
  WIMLIB_ERR_PATH_DOES_NOT_EXIST | One of the paths to extract does not exist in the image; see discussion above about strict vs. non-strict behavior.

If a progress function is registered with `wim`, then it will receive WIMLIB_PROGRESS_MSG_EXTRACT_STREAMS.