wimlib
Macros | Typedefs | Enumerations | Functions
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). More...
 
#define WIMLIB_MINOR_VERSION   12
 Minor version of the library (for example, the 2 in 1.2.5). More...
 
#define WIMLIB_PATCH_VERSION   0
 Patch version of the library (for example, the 5 in 1.2.5). More...
 
#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. More...
 
#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. More...
 
#define WIMLIB_IS_WIM_ROOT_PATH(path)
 Use this to test if the specified path refers to the root directory of the WIM image. More...
 
#define WIMLIB_GUID_LEN   16
 Length of a Globally Unique Identifier (GUID), in bytes. More...
 
#define WIMLIB_INIT_FLAG_ASSUME_UTF8   0x00000001
 Deprecated; no longer has any effect. More...
 
#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. More...
 
#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. More...
 
#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. More...
 
#define WIMLIB_INIT_FLAG_DEFAULT_CASE_SENSITIVE   0x00000010
 Default to interpreting WIM paths case sensitively (default on UNIX-like systems). More...
 
#define WIMLIB_INIT_FLAG_DEFAULT_CASE_INSENSITIVE   0x00000020
 Default to interpreting WIM paths case insensitively (default on Windows). More...
 
#define WIMLIB_NO_IMAGE   0
 Used to indicate no image or an invalid image. More...
 
#define WIMLIB_ALL_IMAGES   (-1)
 Used to specify all images in the WIM. More...
 

Typedefs

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

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

void wimlib_free (WIMStruct *wim)
 Release a reference to a WIMStruct. More...
 
const wimlib_tcharwimlib_get_compression_type_string (enum wimlib_compression_type ctype)
 Convert a wimlib_compression_type value into a string. More...
 
const wimlib_tcharwimlib_get_error_string (enum wimlib_error_code code)
 Convert a wimlib error code into a string describing it. More...
 
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. More...
 
int wimlib_global_init (int init_flags)
 Initialization function for wimlib. More...
 
void wimlib_global_cleanup (void)
 Cleanup function for wimlib. More...
 
void wimlib_register_progress_function (WIMStruct *wim, wimlib_progress_func_t progfunc, void *progctx)
 Register a progress function with a WIMStruct. More...
 
int wimlib_set_error_file (FILE *fp)
 Set the file to which the library will print error and warning messages. More...
 
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. More...
 
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. More...
 
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. More...
 
int wimlib_verify_wim (WIMStruct *wim, int verify_flags)
 Perform verification checks on a WIM file. More...
 

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   12

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

◆ WIMLIB_PATCH_VERSION

#define WIMLIB_PATCH_VERSION   0

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)
#define WIMLIB_WIM_PATH_SEPARATOR
Path separator for WIM paths passed back to progress callbacks.
Definition: wimlib.h:470

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

Enumeration Type Documentation

◆ 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

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()

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
wimPointer to the WIMStruct to release. If NULL, no action is taken.

◆ wimlib_get_compression_type_string()

const wimlib_tchar* wimlib_get_compression_type_string ( enum wimlib_compression_type  ctype)

Convert a wimlib_compression_type value into a string.

Parameters
ctypeThe 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()

const wimlib_tchar* wimlib_get_error_string ( enum wimlib_error_code  code)

Convert a wimlib error code into a string describing it.

Parameters
codeAn 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()

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_global_init()

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_flagsBitwise OR of flags prefixed with WIMLIB_INIT_FLAG.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INSUFFICIENT_PRIVILEGESWIMLIB_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()

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_register_progress_function()

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

Register a progress function with a WIMStruct.

Parameters
wimThe WIMStruct for which to register the progress function.
progfuncPointer 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.
progctxThe value which will be passed as the third argument to calls to progfunc.

◆ wimlib_set_error_file()

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 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_UNSUPPORTEDwimlib was compiled using the –without-error-messages option.

◆ wimlib_set_error_file_by_name()

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_OPENThe file named by path could not be opened for appending.
WIMLIB_ERR_UNSUPPORTEDwimlib was compiled using the –without-error-messages option.

◆ wimlib_set_memory_allocator()

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

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_funcA 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_funcA 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_funcA 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()

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_messagestrue if messages are to be printed; false if messages are not to be printed.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_UNSUPPORTEDwimlib was compiled using the –without-error-messages option.

◆ wimlib_verify_wim()

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
wimThe 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_flagsReserved; 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_DECOMPRESSIONThe WIM file contains invalid compressed data.
WIMLIB_ERR_INVALID_METADATA_RESOURCEThe metadata resource for an image is invalid.
WIMLIB_ERR_INVALID_RESOURCE_HASHFile data stored in the WIM file is corrupt.
WIMLIB_ERR_RESOURCE_NOT_FOUNDThe 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.