Loading...
Searching...
No Matches
General

Declarations and structures shared across the library. More...

## Macros

#define | WIMLIB_MAJOR_VERSION 1
| Major version of the library (for example, the 1 in 1.2.5).
#define | WIMLIB_MINOR_VERSION 14
| Minor version of the library (for example, the 2 in 1.2.5).
#define | WIMLIB_PATCH_VERSION 5
| Patch version of the library (for example, the 5 in 1.2.5).
#define | wimlib_timespec timespec /* standard definition */
#define | WIMLIB_WIMSTRUCT_DECLARED
#define | WIMLIB_WIM_PATH_SEPARATOR '/'
| Path separator for WIM paths passed back to progress callbacks.
#define | WIMLIB_WIM_PATH_SEPARATOR_STRING "/"
#define | WIMLIB_WIM_ROOT_PATH WIMLIB_WIM_PATH_SEPARATOR_STRING
| A string containing a single path separator; use this to specify the root directory of a WIM image.
#define | WIMLIB_IS_WIM_ROOT_PATH(path)
| Use this to test if the specified path refers to the root directory of the WIM image.
#define | WIMLIB_GUID_LEN 16
| Length of a Globally Unique Identifier (GUID), in bytes.
#define | WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001
| Deprecated; no longer has any effect.
#define | WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002
| Windows-only: do not attempt to acquire additional privileges (currently SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, SeTakeOwnershipPrivilege, and SeManageVolumePrivilege) when initializing the library.
#define | WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES 0x00000004
| Windows only: If WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, return WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed to read all possible data and metadata for a capture operation could not be acquired.
#define | WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008
| Windows only: If WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, return WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed to restore all possible data and metadata for an apply operation could not be acquired.
#define | WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE 0x00000010
| Default to interpreting WIM paths case sensitively (default on UNIX-like systems).
#define | WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020
| Default to interpreting WIM paths case insensitively (default on Windows).
#define | WIMLIB_NO_IMAGE 0
| Used to indicate no image or an invalid image.
#define | WIMLIB_ALL_IMAGES (-1)
| Used to specify all images in the WIM.

## Typedefs

typedef struct WIMStruct | WIMStruct
| Opaque structure that represents a WIM, possibly backed by an on-disk file.
typedef char | wimlib_tchar
| See Character encoding.

## Enumerations

enum | wimlib_compression_type { WIMLIB_COMPRESSION_TYPE_NONE = 0 , WIMLIB_COMPRESSION_TYPE_XPRESS = 1 , WIMLIB_COMPRESSION_TYPE_LZX = 2 , WIMLIB_COMPRESSION_TYPE_LZMS = 3 }
| Specifies a compression type. More...

enum

wimlib_error_code {
WIMLIB_ERR_SUCCESS = 0 , WIMLIB_ERR_ALREADY_LOCKED = 1 , WIMLIB_ERR_DECOMPRESSION = 2 , WIMLIB_ERR_FUSE = 6 ,
WIMLIB_ERR_GLOB_HAD_NO_MATCHES = 8 , WIMLIB_ERR_IMAGE_COUNT = 10 , WIMLIB_ERR_IMAGE_NAME_COLLISION = 11 , WIMLIB_ERR_INSUFFICIENT_PRIVILEGES = 12 ,
WIMLIB_ERR_INTEGRITY = 13 , WIMLIB_ERR_INVALID_CAPTURE_CONFIG = 14 , WIMLIB_ERR_INVALID_CHUNK_SIZE = 15 , WIMLIB_ERR_INVALID_COMPRESSION_TYPE = 16 ,
WIMLIB_ERR_INVALID_HEADER = 17 , WIMLIB_ERR_INVALID_IMAGE = 18 , WIMLIB_ERR_INVALID_INTEGRITY_TABLE = 19 , WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY = 20 ,
WIMLIB_ERR_INVALID_METADATA_RESOURCE = 21 , WIMLIB_ERR_INVALID_OVERLAY = 23 , WIMLIB_ERR_INVALID_PARAM = 24 , WIMLIB_ERR_INVALID_PART_NUMBER = 25 ,
WIMLIB_ERR_INVALID_PIPABLE_WIM = 26 , WIMLIB_ERR_INVALID_REPARSE_DATA = 27 , WIMLIB_ERR_INVALID_RESOURCE_HASH = 28 , WIMLIB_ERR_INVALID_UTF16_STRING = 30 ,
WIMLIB_ERR_INVALID_UTF8_STRING = 31 , WIMLIB_ERR_IS_DIRECTORY = 32 , WIMLIB_ERR_IS_SPLIT_WIM = 33 , WIMLIB_ERR_LINK = 35 ,
WIMLIB_ERR_METADATA_NOT_FOUND = 36 , WIMLIB_ERR_MKDIR = 37 , WIMLIB_ERR_MQUEUE = 38 , WIMLIB_ERR_NOMEM = 39 ,
WIMLIB_ERR_NOTDIR = 40 , WIMLIB_ERR_NOTEMPTY = 41 , WIMLIB_ERR_NOT_A_REGULAR_FILE = 42 , WIMLIB_ERR_NOT_A_WIM_FILE = 43 ,
WIMLIB_ERR_NOT_PIPABLE = 44 , WIMLIB_ERR_NO_FILENAME = 45 , WIMLIB_ERR_NTFS_3G = 46 , WIMLIB_ERR_OPEN = 47 ,
WIMLIB_ERR_OPENDIR = 48 , WIMLIB_ERR_PATH_DOES_NOT_EXIST = 49 , WIMLIB_ERR_READ = 50 , WIMLIB_ERR_READLINK = 51 ,
WIMLIB_ERR_RENAME = 52 , WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED = 54 , WIMLIB_ERR_RESOURCE_NOT_FOUND = 55 , WIMLIB_ERR_RESOURCE_ORDER = 56 ,
WIMLIB_ERR_SET_ATTRIBUTES = 57 , WIMLIB_ERR_SET_REPARSE_DATA = 58 , WIMLIB_ERR_SET_SECURITY = 59 , WIMLIB_ERR_SET_SHORT_NAME = 60 ,
WIMLIB_ERR_SET_TIMESTAMPS = 61 , WIMLIB_ERR_SPLIT_INVALID = 62 , WIMLIB_ERR_STAT = 63 , WIMLIB_ERR_UNEXPECTED_END_OF_FILE = 65 ,
WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE = 66 , WIMLIB_ERR_UNKNOWN_VERSION = 67 , WIMLIB_ERR_UNSUPPORTED = 68 , WIMLIB_ERR_UNSUPPORTED_FILE = 69 ,
WIMLIB_ERR_WIM_IS_READONLY = 71 , WIMLIB_ERR_WRITE = 72 , WIMLIB_ERR_XML = 73 , WIMLIB_ERR_WIM_IS_ENCRYPTED = 74 ,
WIMLIB_ERR_WIMBOOT = 75 , WIMLIB_ERR_ABORTED_BY_PROGRESS = 76 , WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS = 77 , WIMLIB_ERR_MKNOD = 78 ,
WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY = 79 , WIMLIB_ERR_NOT_A_MOUNTPOINT = 80 , WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT = 81 , WIMLIB_ERR_FVE_LOCKED_VOLUME = 82 ,
WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG = 83 , WIMLIB_ERR_WIM_IS_INCOMPLETE = 84 , WIMLIB_ERR_COMPACTION_NOT_POSSIBLE = 85 , WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES = 86 ,
WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE = 87 , WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED = 88 , WIMLIB_ERR_SNAPSHOT_FAILURE = 89 , WIMLIB_ERR_INVALID_XATTR = 90 ,
WIMLIB_ERR_SET_XATTR = 91
}

| Possible values of the error code returned by many functions in wimlib. More...

## Functions

WIMLIBAPI void | wimlib_free (WIMStruct *wim)
| Release a reference to a WIMStruct.
WIMLIBAPI const wimlib_tchar * | wimlib_get_compression_type_string (enum wimlib_compression_type ctype)
| Convert a wimlib_compression_type value into a string.
WIMLIBAPI const wimlib_tchar * | wimlib_get_error_string (enum wimlib_error_code code)
| Convert a wimlib error code into a string describing it.
WIMLIBAPI uint32_t | wimlib_get_version (void)
| Return the version of wimlib as a 32-bit number whose top 12 bits contain the major version, the next 10 bits contain the minor version, and the low 10 bits contain the patch version.
WIMLIBAPI const wimlib_tchar * | wimlib_get_version_string (void)
| Since wimlib v1.13.0: like wimlib_get_version(), but returns the full PACKAGE_VERSION string that was set at build time.
WIMLIBAPI int | wimlib_global_init (int init_flags)
| Initialization function for wimlib.
WIMLIBAPI void | wimlib_global_cleanup (void)
| Cleanup function for wimlib.
WIMLIBAPI int | wimlib_load_text_file (const wimlib_tchar *path, wimlib_tchar **tstr_ret, size_t *tstr_nchars_ret)
| Load a UTF-8 or UTF-16LE encoded text file into memory.
WIMLIBAPI void | wimlib_register_progress_function (WIMStruct *wim, wimlib_progress_func_t progfunc, void *progctx)
| Register a progress function with a WIMStruct.
WIMLIBAPI int | wimlib_set_error_file (FILE *fp)
| Set the file to which the library will print error and warning messages.
WIMLIBAPI int | wimlib_set_error_file_by_name (const wimlib_tchar *path)
| Set the path to the file to which the library will print error and warning messages.
WIMLIBAPI int | wimlib_set_memory_allocator (void *(*malloc_func)(size_t), void(*free_func)(void *), void *(*realloc_func)(void *, size_t))
| Set the functions that wimlib uses to allocate and free memory.
WIMLIBAPI int | wimlib_set_print_errors (bool show_messages)
| Set whether wimlib can print error and warning messages to the error file, which defaults to standard error.
WIMLIBAPI int | wimlib_verify_wim (WIMStruct *wim, int verify_flags)
| Perform verification checks on a WIM file.

## Detailed Description

Declarations and structures shared across the library.

## Macro Definition Documentation

## WIMLIB_MAJOR_VERSION

#define WIMLIB_MAJOR_VERSION 1

Major version of the library (for example, the 1 in 1.2.5).

## WIMLIB_MINOR_VERSION

#define WIMLIB_MINOR_VERSION 14

Minor version of the library (for example, the 2 in 1.2.5).

## WIMLIB_PATCH_VERSION

#define WIMLIB_PATCH_VERSION 5

Patch version of the library (for example, the 5 in 1.2.5).

## wimlib_timespec

#define wimlib_timespec timespec /* standard definition */

## WIMLIB_WIMSTRUCT_DECLARED

#define WIMLIB_WIMSTRUCT_DECLARED

## WIMLIB_WIM_PATH_SEPARATOR

#define WIMLIB_WIM_PATH_SEPARATOR '/'

Path separator for WIM paths passed back to progress callbacks.

This is forward slash on UNIX and backslash on Windows.

## WIMLIB_WIM_PATH_SEPARATOR_STRING

#define WIMLIB_WIM_PATH_SEPARATOR_STRING "/"

## WIMLIB_WIM_ROOT_PATH

#define WIMLIB_WIM_ROOT_PATH WIMLIB_WIM_PATH_SEPARATOR_STRING

A string containing a single path separator; use this to specify the root directory of a WIM image.

## WIMLIB_IS_WIM_ROOT_PATH

#define WIMLIB_IS_WIM_ROOT_PATH | ( |  | path | ) |

Value:
((path)[0] == WIMLIB_WIM_PATH_SEPARATOR && \
(path)[1] == 0)
WIMLIB_WIM_PATH_SEPARATOR
#define WIMLIB_WIM_PATH_SEPARATOR
Path separator for WIM paths passed back to progress callbacks.
Definition wimlib.h:492

Use this to test if the specified path refers to the root directory of the WIM image.

## WIMLIB_GUID_LEN

#define WIMLIB_GUID_LEN 16

Length of a Globally Unique Identifier (GUID), in bytes.

## WIMLIB_INIT_FLAG_ASSUME_UTF8

#define WIMLIB_INIT_FLAG_ASSUME_UTF8 0x00000001

Deprecated; no longer has any effect.

## WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES

#define WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES 0x00000002

Windows-only: do not attempt to acquire additional privileges (currently SeBackupPrivilege, SeRestorePrivilege, SeSecurityPrivilege, SeTakeOwnershipPrivilege, and SeManageVolumePrivilege) when initializing the library.

This flag is intended for the case where the calling program manages these privileges itself. Note: by default, no error is issued if privileges cannot be acquired, although related errors may be reported later, depending on if the operations performed actually require additional privileges or not.

## WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES

#define WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES 0x00000004

Windows only: If WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, return WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed to read all possible data and metadata for a capture operation could not be acquired.

Can be combined with WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES.

## WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES

#define WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES 0x00000008

Windows only: If WIMLIB_INIT_FLAG_DONT_ACQUIRE_PRIVILEGES not specified, return WIMLIB_ERR_INSUFFICIENT_PRIVILEGES if privileges that may be needed to restore all possible data and metadata for an apply operation could not be acquired.

Can be combined with WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES.

## WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE

#define WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE 0x00000010

Default to interpreting WIM paths case sensitively (default on UNIX-like systems).

## WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE

#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE 0x00000020

Default to interpreting WIM paths case insensitively (default on Windows).

This does not apply to mounted images.

## WIMLIB_NO_IMAGE

#define WIMLIB_NO_IMAGE 0

Used to indicate no image or an invalid image.

## WIMLIB_ALL_IMAGES

#define WIMLIB_ALL_IMAGES (-1)

Used to specify all images in the WIM.

## Typedef Documentation

## WIMStruct

typedef struct WIMStruct WIMStruct

Opaque structure that represents a WIM, possibly backed by an on-disk file.

See Basic WIM handling concepts for more information.

## wimlib_tchar

typedef char wimlib_tchar

See Character encoding.

## Enumeration Type Documentation

## wimlib_compression_type

enum wimlib_compression_type

Specifies a compression type.

A WIM file has a default compression type, indicated by its file header. Normally, each resource in the WIM file is compressed with this compression type. However, resources may be stored as uncompressed; for example, wimlib may do so if a resource does not compress to less than its original size. In addition, a WIM with the new version number of 3584, or "ESD file", might contain solid resources with different compression types.

Enumerator
WIMLIB_COMPRESSION_TYPE_NONE | No compression. This is a valid argument to wimlib_create_new_wim() and wimlib_set_output_compression_type(), but not to the functions in the compression API such as wimlib_create_compressor().

WIMLIB_COMPRESSION_TYPE_XPRESS

The XPRESS compression format.

This format combines Lempel-Ziv factorization with Huffman encoding. Compression and decompression are both fast. This format supports chunk sizes that are powers of 2 between `2^12` and `2^16`, inclusively.

wimlib's XPRESS compressor will, with the default settings, usually produce a better compression ratio, and work more quickly, than the implementation in Microsoft's WIMGAPI (as of Windows 8.1). Non-default compression levels are also supported. For example, level 80 will enable two-pass optimal parsing, which is significantly slower but usually improves compression by several percent over the default level of 50.

If using wimlib_create_compressor() to create an XPRESS compressor directly, the `max_block_size` parameter may be any positive value up to and including `2^16`.

WIMLIB_COMPRESSION_TYPE_LZX

The LZX compression format.

This format combines Lempel-Ziv factorization with Huffman encoding, but with more features and complexity than XPRESS. Compression is slow to somewhat fast, depending on the settings. Decompression is fast but slower than XPRESS. This format supports chunk sizes that are powers of 2 between `2^15` and `2^21`, inclusively. Note: chunk sizes other than `2^15` are not compatible with the Microsoft implementation.

wimlib's LZX compressor will, with the default settings, usually produce a better compression ratio, and work more quickly, than the implementation in Microsoft's WIMGAPI (as of Windows 8.1). Non-default compression levels are also supported. For example, level 20 will provide fast compression, almost as fast as XPRESS.

If using wimlib_create_compressor() to create an LZX compressor directly, the `max_block_size` parameter may be any positive value up to and including `2^21`.

WIMLIB_COMPRESSION_TYPE_LZMS

The LZMS compression format.

This format combines Lempel-Ziv factorization with adaptive Huffman encoding and range coding. Compression and decompression are both fairly slow. This format supports chunk sizes that are powers of 2 between `2^15` and `2^30`, inclusively. This format is best used for large chunk sizes. Note: LZMS compression is only compatible with wimlib v1.6.0 and later, WIMGAPI Windows 8 and later, and DISM Windows 8.1 and later. Also, chunk sizes larger than `2^26` are not compatible with the Microsoft implementation.

wimlib's LZMS compressor will, with the default settings, usually produce a better compression ratio, and work more quickly, than the implementation in Microsoft's WIMGAPI (as of Windows 8.1). There is limited support for non-default compression levels, but compression will be noticeably faster if you choose a level < 35.

If using wimlib_create_compressor() to create an LZMS compressor directly, the `max_block_size` parameter may be any positive value up to and including `2^30`.

## wimlib_error_code

enum wimlib_error_code

Possible values of the error code returned by many functions in wimlib.

See the documentation for each wimlib function to see specifically what error codes can be returned by a given function, and what they mean.

Enumerator
WIMLIB_ERR_SUCCESS |
WIMLIB_ERR_ALREADY_LOCKED |
WIMLIB_ERR_DECOMPRESSION |
WIMLIB_ERR_FUSE |
WIMLIB_ERR_GLOB_HAD_NO_MATCHES |
WIMLIB_ERR_IMAGE_COUNT |
WIMLIB_ERR_IMAGE_NAME_COLLISION |
WIMLIB_ERR_INSUFFICIENT_PRIVILEGES |
WIMLIB_ERR_INTEGRITY |
WIMLIB_ERR_INVALID_CAPTURE_CONFIG |
WIMLIB_ERR_INVALID_CHUNK_SIZE |
WIMLIB_ERR_INVALID_COMPRESSION_TYPE |
WIMLIB_ERR_INVALID_HEADER |
WIMLIB_ERR_INVALID_IMAGE |
WIMLIB_ERR_INVALID_INTEGRITY_TABLE |
WIMLIB_ERR_INVALID_LOOKUP_TABLE_ENTRY |
WIMLIB_ERR_INVALID_METADATA_RESOURCE |
WIMLIB_ERR_INVALID_OVERLAY |
WIMLIB_ERR_INVALID_PARAM |
WIMLIB_ERR_INVALID_PART_NUMBER |
WIMLIB_ERR_INVALID_PIPABLE_WIM |
WIMLIB_ERR_INVALID_REPARSE_DATA |
WIMLIB_ERR_INVALID_RESOURCE_HASH |
WIMLIB_ERR_INVALID_UTF16_STRING |
WIMLIB_ERR_INVALID_UTF8_STRING |
WIMLIB_ERR_IS_DIRECTORY |
WIMLIB_ERR_IS_SPLIT_WIM |
WIMLIB_ERR_LINK |
WIMLIB_ERR_METADATA_NOT_FOUND |
WIMLIB_ERR_MKDIR |
WIMLIB_ERR_MQUEUE |
WIMLIB_ERR_NOMEM |
WIMLIB_ERR_NOTDIR |
WIMLIB_ERR_NOTEMPTY |
WIMLIB_ERR_NOT_A_REGULAR_FILE |
WIMLIB_ERR_NOT_A_WIM_FILE |
WIMLIB_ERR_NOT_PIPABLE |
WIMLIB_ERR_NO_FILENAME |
WIMLIB_ERR_NTFS_3G |
WIMLIB_ERR_OPEN |
WIMLIB_ERR_OPENDIR |
WIMLIB_ERR_PATH_DOES_NOT_EXIST |
WIMLIB_ERR_READ |
WIMLIB_ERR_READLINK |
WIMLIB_ERR_RENAME |
WIMLIB_ERR_REPARSE_POINT_FIXUP_FAILED |
WIMLIB_ERR_RESOURCE_NOT_FOUND |
WIMLIB_ERR_RESOURCE_ORDER |
WIMLIB_ERR_SET_ATTRIBUTES |
WIMLIB_ERR_SET_REPARSE_DATA |
WIMLIB_ERR_SET_SECURITY |
WIMLIB_ERR_SET_SHORT_NAME |
WIMLIB_ERR_SET_TIMESTAMPS |
WIMLIB_ERR_SPLIT_INVALID |
WIMLIB_ERR_STAT |
WIMLIB_ERR_UNEXPECTED_END_OF_FILE |
WIMLIB_ERR_UNICODE_STRING_NOT_REPRESENTABLE |
WIMLIB_ERR_UNKNOWN_VERSION |
WIMLIB_ERR_UNSUPPORTED |
WIMLIB_ERR_UNSUPPORTED_FILE |
WIMLIB_ERR_WIM_IS_READONLY |
WIMLIB_ERR_WRITE |
WIMLIB_ERR_XML |
WIMLIB_ERR_WIM_IS_ENCRYPTED |
WIMLIB_ERR_WIMBOOT |
WIMLIB_ERR_ABORTED_BY_PROGRESS |
WIMLIB_ERR_UNKNOWN_PROGRESS_STATUS |
WIMLIB_ERR_MKNOD |
WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY |
WIMLIB_ERR_NOT_A_MOUNTPOINT |
WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT |
WIMLIB_ERR_FVE_LOCKED_VOLUME |
WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIG |
WIMLIB_ERR_WIM_IS_INCOMPLETE |
WIMLIB_ERR_COMPACTION_NOT_POSSIBLE |
WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES |
WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGE |
WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED |
WIMLIB_ERR_SNAPSHOT_FAILURE |
WIMLIB_ERR_INVALID_XATTR |
WIMLIB_ERR_SET_XATTR |

## Function Documentation

## wimlib_free()

WIMLIBAPI void wimlib_free | ( | WIMStruct * | wim | ) |

Release a reference to a WIMStruct.

If the WIMStruct is still referenced by other WIMStruct's (e.g. following calls to wimlib_export_image() or wimlib_reference_resources()), then the library will free it later, when the last reference is released; otherwise it is freed immediately and any associated file descriptors are closed.

Parameters

  wim | Pointer to the WIMStruct to release. If `NULL`, no action is taken.

## wimlib_get_compression_type_string()

WIMLIBAPI const wimlib_tchar * wimlib_get_compression_type_string | ( | enum wimlib_compression_type | ctype | ) |

Convert a wimlib_compression_type value into a string.

Parameters

  ctype | The compression type value to convert.

Returns
  A statically allocated string naming the compression type, such as "None", "LZX", or "XPRESS". If the value was unrecognized, then the resulting string will be "Invalid".

## wimlib_get_error_string()

WIMLIBAPI const wimlib_tchar * wimlib_get_error_string | ( | enum wimlib_error_code | code | ) |

Convert a wimlib error code into a string describing it.

Parameters

  code | An error code returned by one of wimlib's functions.

Returns
  Pointer to a statically allocated string describing the error code. If the value was unrecognized, then the resulting string will be "Unknown error".

## wimlib_get_version()

WIMLIBAPI uint32_t wimlib_get_version | ( | void |  | ) |

Return the version of wimlib as a 32-bit number whose top 12 bits contain the major version, the next 10 bits contain the minor version, and the low 10 bits contain the patch version.

In other words, the returned value is equal to `((WIMLIB_MAJOR_VERSION << 20) | (WIMLIB_MINOR_VERSION << 10) | WIMLIB_PATCH_VERSION)` for the corresponding header file.

## wimlib_get_version_string()

WIMLIBAPI const wimlib_tchar * wimlib_get_version_string | ( | void |  | ) |

Since wimlib v1.13.0: like wimlib_get_version(), but returns the full PACKAGE_VERSION string that was set at build time.

(This allows a beta release to be distinguished from an official release.)

## wimlib_global_init()

WIMLIBAPI int wimlib_global_init | ( | int | init_flags | ) |

Initialization function for wimlib.

Call before using any other wimlib function (except possibly wimlib_set_print_errors()). If not done manually, this function will be called automatically with a flags argument of 0. This function does nothing if called again after it has already successfully run.

Parameters

  init_flags | Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG.

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_INSUFFICIENT_PRIVILEGES | WIMLIB_INIT_FLAG_STRICT_APPLY_PRIVILEGES and/or WIMLIB_INIT_FLAG_STRICT_CAPTURE_PRIVILEGES were specified in `init_flags`, but the corresponding privileges could not be acquired.

## wimlib_global_cleanup()

WIMLIBAPI void wimlib_global_cleanup | ( | void |  | ) |

Cleanup function for wimlib.

You are not required to call this function, but it will release any global resources allocated by the library.

## wimlib_load_text_file()

WIMLIBAPI int wimlib_load_text_file | ( | const wimlib_tchar * | path,
|  | wimlib_tchar ** | tstr_ret,
|  | size_t * | tstr_nchars_ret )

Load a UTF-8 or UTF-16LE encoded text file into memory.

Parameters

  path | The path to the file, or NULL or "-" to use standard input.
  tstr_ret | On success, a buffer containing the file's text as a "wimlib_tchar" string is returned here. The buffer must be freed using free().
  tstr_nchars_ret | On success, the length of the text in "wimlib_tchar"s is returned here.

Returns
  0 on success; a wimlib_error_code value on failure.

## wimlib_register_progress_function()

WIMLIBAPI void wimlib_register_progress_function | ( | WIMStruct * | wim,
|  | wimlib_progress_func_t | progfunc,
|  | void * | progctx )

Register a progress function with a WIMStruct.

Parameters

  wim | The WIMStruct for which to register the progress function.
  progfunc | Pointer to the progress function to register. If the WIM already has a progress function registered, it will be replaced with this one. If `NULL`, the current progress function (if any) will be unregistered.
  progctx | The value which will be passed as the third argument to calls to `progfunc`.

## wimlib_set_error_file()

WIMLIBAPI int wimlib_set_error_file | ( | FILE * | fp | ) |

Set the file to which the library will print error and warning messages.

This version of the function takes a C library `FILE*` opened for writing (or appending). Use wimlib_set_error_file_by_name() to specify the file by name instead.

This also enables error messages, as if by a call to wimlib_set_print_errors(true).

Returns
  0

## wimlib_set_error_file_by_name()

WIMLIBAPI int wimlib_set_error_file_by_name | ( | const wimlib_tchar * | path | ) |

Set the path to the file to which the library will print error and warning messages.

The library will open this file for appending.

This also enables error messages, as if by a call to wimlib_set_print_errors(true).

Returns
  0 on success; a wimlib_error_code value on failure.

Return values

  WIMLIB_ERR_OPEN | The file named by `path` could not be opened for appending.

## wimlib_set_memory_allocator()

WIMLIBAPI int wimlib_set_memory_allocator | ( | void *(* | malloc_func )(size_t),
|  | void(* | free_func )(void *),
|  | void *(* | realloc_func )(void *, size_t) )

Set the functions that wimlib uses to allocate and free memory.

These settings are global and not per-WIM.

The default is to use the default `malloc()`, `free()`, and `realloc()` from the standard C library.

Note: some external functions, such as those in `libntfs-3g`, may use the standard memory allocation functions regardless of this setting.

Parameters

  malloc_func | A function equivalent to `malloc()` that wimlib will use to allocate memory. If `NULL`, the allocator function is set back to the default `malloc()` from the C library.
  free_func | A function equivalent to `free()` that wimlib will use to free memory. If `NULL`, the free function is set back to the default `free()` from the C library.
  realloc_func | A function equivalent to `realloc()` that wimlib will use to reallocate memory. If `NULL`, the free function is set back to the default `realloc()` from the C library.

Returns
  0

## wimlib_set_print_errors()

WIMLIBAPI int wimlib_set_print_errors | ( | bool | show_messages | ) |

Set whether wimlib can print error and warning messages to the error file, which defaults to standard error.

Error and warning messages may provide information that cannot be determined only from returned error codes.

By default, error messages are not printed.

This setting applies globally (it is not per-WIM).

This can be called before wimlib_global_init().

Parameters

  show_messages | `true` if messages are to be printed; `false` if messages are not to be printed.

Returns
  0

## wimlib_verify_wim()

WIMLIBAPI int wimlib_verify_wim | ( | WIMStruct * | wim,
|  | int | verify_flags )

Perform verification checks on a WIM file.

This function is intended for safety checking and/or debugging. If used on a well-formed WIM file, it should always succeed.

Parameters

  wim | The WIMStruct for the WIM file to verify. Note: for an extra layer of verification, it is a good idea to have used WIMLIB_OPEN_FLAG_CHECK_INTEGRITY when you opened the file. If verifying a split WIM, specify the first part of the split WIM here, and reference the other parts using wimlib_reference_resource_files() before calling this function.
  verify_flags | Reserved; must be 0.

Returns
  0 if the WIM file was successfully verified; a wimlib_error_code value if it failed verification or another error occurred.

Return values

  WIMLIB_ERR_DECOMPRESSION | The WIM file contains invalid compressed data.
  WIMLIB_ERR_INVALID_METADATA_RESOURCE | The metadata resource for an image is invalid.
  WIMLIB_ERR_INVALID_RESOURCE_HASH | File data stored in the WIM file is corrupt.
  WIMLIB_ERR_RESOURCE_NOT_FOUND | The data for a file in an image could not be found. See Creating and handling non-standalone WIMs.

If a progress function is registered with `wim`, then it will receive the following progress messages: WIMLIB_PROGRESS_MSG_BEGIN_VERIFY_IMAGE, WIMLIB_PROGRESS_MSG_END_VERIFY_IMAGE, and WIMLIB_PROGRESS_MSG_VERIFY_STREAMS.