|
wimlib
|
|
wimlib
|
This is the documentation for the library interface of wimlib 1.4.0, 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 README file.
wimlib uses the GNU autotools, so, on UNIX systems, it should be easy to install with configure && make && sudo make install; however, please see the README for more information about installing it. To use wimlib in a program after installing it, include wimlib.h and link your program with -lwim.
wimlib wraps up a WIM file in an opaque WIMStruct structure. A WIMStruct may represent either a stand-alone WIM or one part of a split WIM.
All functions in wimlib's public API are prefixed with wimlib. Most 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 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.
First before calling any other functions, you should call wimlib_global_init() to initialize the library.
To open an existing WIM, use wimlib_open_wim().
To create a new WIM that initially contains no images, use wimlib_create_new_wim().
To add an image to a WIM file from a directory tree on your filesystem, call wimlib_add_image(). This can be done with a WIMStruct gotten from wimlib_open_wim() or from wimlib_create_new_wim(). On UNIX, wimlib_add_image() can also capture a WIM image directly from a block device containing a NTFS filesystem.
To extract an image from a WIM file, call wimlib_extract_image(). This can be done either to a directory, or, on UNIX, directly to a block device containing a NTFS filesystem.
To extract individual files or directories from a WIM image, rather than a full image, call wimlib_extract_files().
To programatically make changes to a WIM image without mounting it, call wimlib_update_image().
On UNIX, wimlib supports mounting WIM files either read-only or read-write. Mounting is done using wimlib_mount_image() and unmounting is done using wimlib_unmount_image(). Mounting can be done without root privileges because it is implemented using FUSE (Filesystem in Userspace). If wimlib is compiled with the –without-fuse flag, these functions will be available but will fail with WIMLIB_ERR_UNSUPPORTED.
After creating or modifying a WIM file, you can write it to a file using wimlib_write(). Alternatively, if the WIM was originally read from a file (using wimlib_open_wim() rather than wimlib_create_new_wim()), you can use wimlib_overwrite() to overwrite the original file.
Please note: merely by calling wimlib_add_image() or many of the other functions in this library that operate on WIMStruct's, you are not modifying the WIM file on disk. Changes are not saved until you explicitly call wimlib_write() or wimlib_overwrite().
After you are done with the WIM file, use wimlib_free() to free all memory associated with a WIMStruct and close all files associated with it.
When you are completely done with using wimlib in your program, you should call wimlib_global_cleanup().
A number of functions take a pointer to a progress function of type wimlib_progress_func_t. This function will be called periodically during the WIM operation(s) to report on the progress of the operation (for example, how many bytes have been written so far).
wimlib is thread-safe as long as different WIMStruct's are used, except for the following exceptions:
To support Windows as well as UNIX, 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, 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.
This section documents some technical limitations of wimlib not already documented in the man page for wimlib-imagex.
1.8.3.1
