|
wimlib
|
This is the documentation for the library interface of wimlib 1.14.4, a C library for creating, modifying, extracting, and mounting files in the Windows Imaging (WIM) format. This documentation is intended for developers only. If you have installed wimlib and want to know how to use the wimlib-imagex program, please see the manual pages and also the README file.
Download the source code from https://wimlib.net. Install the library by running configure && make && sudo make install. See the README for information about configuration options. To use wimlib in your program after installing it, include wimlib.h and link your program with -lwim.
Download the Windows binary distribution with the appropriate architecture from https://wimlib.net. Link your program with libwim-15.dll. If needed by your programming language or development environment, the import library libwim.lib and C/C++ header wimlib.h can be found in the directory "devel" in the ZIP file.
If you need to access the DLL from non-C/C++ programming languages, note that the calling convention is "cdecl".
If you want to build wimlib from source on Windows, see README.WINDOWS. This is only needed if you are making modifications to wimlib.
Several examples are located in the "examples" directory of the source distribution. Also see Basic WIM handling concepts below.
There is also the source code of wimlib-imagex, which is complicated but uses most capabilities of wimlib.
New releases of wimlib are intended to be backward compatible with old releases, except when the libtool "age" is reset. This most recently occurred for the v1.7.0 (libwim15) release (June 2014). Since the library is becoming increasingly stable, the goal is to maintain the current API/ABI for as long as possible unless there is a strong reason not to.
As with any other library, applications should not rely on internal implementation details that may be subject to change.
wimlib wraps up a WIM file in an opaque WIMStruct structure. There are two ways to create such a structure:
A WIMStruct contains zero or more independent directory trees called images. Images may be extracted, added, deleted, exported, and updated using various API functions. (See Extracting WIMs and Modifying WIMs for more details.)
Changes made to a WIM represented by a WIMStruct have no persistent effect until the WIM is actually written to an on-disk file. This can be done using wimlib_write(), but if the WIM was originally opened using wimlib_open_wim(), then wimlib_overwrite() can be used instead. (See Writing and Overwriting WIMs for more details.)
wimlib's API is designed to let you combine functions to accomplish tasks in a flexible way. Here are some example sequences of function calls:
Apply an image from a WIM file, similar to the command-line program wimapply:
Capture an image into a new WIM file, similar to wimcapture:
Append an image to an existing WIM file, similar to wimappend:
Delete an image from an existing WIM file, similar to wimdelete:
Export an image from one WIM file to another, similar to wimexport:
The API also lets you do things the command-line tools don't directly allow. For example, you could make multiple changes to a WIM before efficiently committing the changes with just one call to wimlib_overwrite(). Perhaps you want to both delete an image and add a new one; or perhaps you want to customize an image with wimlib_update_image() after adding it. All these use cases are supported by the API.
After you are done with any WIMStruct, you can call wimlib_free() to free all resources associated with it. Also, when you are completely done with using wimlib in your program, you can call wimlib_global_cleanup() to free any other resources allocated by the library.
Most functions in wimlib return 0 on success and a positive wimlib_error_code value on failure. Use wimlib_get_error_string() to get a string that describes an error code. wimlib also can print error messages to standard error or a custom file when an error occurs, and these may be more informative than the error code; to enable this, call wimlib_set_print_errors(). Please note that this is for convenience only, and some errors can occur without a message being printed. Currently, error messages and strings (as well as all documentation, for that matter) are only available in English.
To support Windows as well as UNIX-like systems, wimlib's API typically takes and returns strings of wimlib_tchar which have a platform-dependent type and encoding.
On Windows, each wimlib_tchar is a 2-byte wchar_t. The encoding is meant to be UTF-16LE. However, unpaired surrogates are permitted because neither Windows nor the NTFS filesystem forbids them in filenames.
On UNIX-like systems, each wimlib_tchar is a 1 byte char. The encoding is meant to be UTF-8. However, for compatibility with Windows-style filenames that are not valid UTF-16LE, surrogate codepoints are permitted. Other multibyte encodings (e.g. ISO-8859-1) or garbage sequences of bytes are not permitted.
See Mounting WIM images.
See Progress Messages.
See Creating and handling non-standalone WIMs.
wimlib supports a special "pipable" WIM format which unfortunately is not compatible with Microsoft's software. To create a pipable WIM, call wimlib_write(), wimlib_write_to_fd(), or wimlib_overwrite() with WIMLIB_WRITE_FLAG_PIPABLE specified. Pipable WIMs are pipable in both directions, so wimlib_write_to_fd() can be used to write a pipable WIM to a pipe, and wimlib_extract_image_from_pipe() can be used to apply an image from a pipable WIM. wimlib can also transparently open and operate on pipable WIM s using a seekable file descriptor using the regular function calls (e.g. wimlib_open_wim(), wimlib_extract_image()).
See the documentation for the –pipable flag of wimcapture for more information about pipable WIMs.
A WIMStruct is not thread-safe and cannot be accessed by multiple threads concurrently, even for "read-only" operations such as extraction. However, users are free to use different WIMStruct's from different threads concurrently. It is even allowed for multiple WIMStruct's to be backed by the same on-disk WIM file, although "overwrites" should never be done in such a scenario.
In addition, several functions change global state and should only be called when a single thread is active in the library. These functions are:
This section documents some technical limitations of wimlib not already described in the documentation for wimlib-imagex.
You are advised to read the README as well as the documentation for wimlib-imagex, since not all relevant information is repeated here in the API documentation.
1.10.0