|
wimlib
|
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 4 |
| 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. | |
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. | |
Declarations and structures shared across the library.
| #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 4 |
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.
This is forward slash on UNIX and backslash on Windows.
| #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.
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.
| #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.
| #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.
| #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).
This does not apply to mounted images.
| #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.
Opaque structure that represents a WIM, possibly backed by an on-disk file.
See Basic WIM handling concepts for more information.
| typedef char wimlib_tchar |
See Character encoding.
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 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 |
| 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 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 |
| 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 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 |
| 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.
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.
| wim | Pointer to the WIMStruct to release. If NULL, no action is taken. |
| WIMLIBAPI const wimlib_tchar * wimlib_get_compression_type_string | ( | enum wimlib_compression_type | ctype | ) |
Convert a wimlib_compression_type value into a string.
| ctype | The compression type value to convert. |
| WIMLIBAPI const wimlib_tchar * wimlib_get_error_string | ( | enum wimlib_error_code | code | ) |
Convert a wimlib error code into a string describing it.
| code | An error code returned by one of wimlib's functions. |
| 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.
| 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.)
| 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.
| init_flags | Bitwise OR of flags prefixed with WIMLIB_INIT_FLAG. |
| 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. |
| 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.
| 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.
| 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. |
| WIMLIBAPI void wimlib_register_progress_function | ( | WIMStruct * | wim, |
| wimlib_progress_func_t | progfunc, | ||
| void * | progctx ) |
Register a progress function with a WIMStruct.
| 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. |
| 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).
| 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).
| WIMLIB_ERR_OPEN | The file named by path could not be opened for appending. |
| WIMLIBAPI 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.
| 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. |
| 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().
| show_messages | true if messages are to be printed; false if messages are not to be printed. |
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.
| 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. |
| 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.
1.10.0