This is the documentation for the library interface of wimlib 1.8.1, a C library for creating, modifying, extracting, and mounting files in the Windows Imaging 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 http://sourceforge.net/projects/wimlib/files. 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
Download the Windows binary distribution with the appropriate architecture (i686 or x86_64 — also called "x86" and "amd64" respectively) from http://sourceforge.net/projects/wimlib/files. Link your program with the libwim-15.dll file. Make sure to also download the source code so you can get wimlib.h, as it is not included in the binary distribution. If you need to access the DLL from other programming languages, note that the calling convention is "cdecl".
Several examples are located in the examples directory of the source distribution.
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 API/ABI compatible with old releases, except when the libtool "age" is reset. This most recently occurred for the v1.4.0 (libwim7), v1.5.0 (libwim9), and v1.7.0 (libwim15) releases. However, the library is becoming increasingly stable, and the goal is to maintain the current API/ABI for as long as possible unless there is a strong reason not to. Even for the v1.7.0 release (libwim15), the changes were fairly limited.
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: wimlib_open_wim(), which opens a WIM file and creates a WIMStruct representing it, and wimlib_create_new_wim(), which creates a new WIMStruct that initially contains no images and does not yet have a backing on-disk file. See Creating and Opening WIMs for more details.
A WIM file, represented by a WIMStruct, contains zero or more images. Images can be extracted (or "applied") using wimlib_extract_image(), added (or "captured" or "appended") using wimlib_add_image(), deleted using wimlib_delete_image(), exported using wimlib_export_image(), and updated or modified using wimlib_update_image(). However, 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 Extracting WIMs, Modifying WIMs, and Writing and Overwriting WIMs for more details.
Note that with this WIMStruct abstraction, performing many tasks on WIM files is a multi-step process. For example, to add, or "append" an image to an existing stand-alone WIM file in a way similar to wimlib-imagex append, you must call the following functions:
This design is very much on purpose as it makes the library more useful in general by allowing functions to be composed in different ways. For example, you can make multiple changes to a WIM and commit them all to the backing file in only one overwrite operation, which is more efficient.
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 itself when an error happens, 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 are in a platform-dependent encoding.
On Windows, each wimlib_tchar is 2 bytes and is the same as a "wchar_t", and the encoding is UTF-16LE.
On UNIX-like systems, each wimlib_tchar is 1 byte and is simply a "char", and the encoding is the locale-dependent multibyte encoding. I recommend you set your locale to a UTF-8 capable locale to avoid any issues. Also, by default, wimlib on UNIX will assume the locale is UTF-8 capable unless you call wimlib_global_init() after having set your desired locale.
See Mounting WIM images.
See Progress Messages.
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 wimlib-imagex capture 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.