wimlib
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
wimlib Documentation

This is the documentation for the library interface of wimlib 1.7.2, 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.

Installing

UNIX

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 -lwim.

Windows

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".

Examples

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.

Backwards Compatibility

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.

Basic WIM handling concepts

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:

  1. wimlib_open_wim()
  2. wimlib_add_image()
  3. wimlib_overwrite()

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 underlying file in only one overwrite operation, which is more efficient.

Note: before calling any other function declared in wimlib.h, wimlib_global_init() can (and in some cases, must) be called. See its documentation for more details.

Cleaning up

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.

Error Handling

Most functions in wimlib return 0 on success and a positive error code 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.

Locales and character encodings

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.

Additional information and features

Mounting WIM images

See Mounting WIM images.

Progress Messages

See Progress Messages.

Non-standalone WIMs

See Creating and handling non-standalone WIMs.

Pipable 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 wimlib-imagex capture for more information about pipable WIMs.

Thread Safety

wimlib is thread-safe, with the following exceptions:

Limitations

This section documents some technical limitations of wimlib not already documented in the man page for wimlib-imagex.

More information

You are advised to read the README as well as the manual pages for wimlib-imagex, since not all relevant information is repeated here in the API documentation.