wimlib
Data Structures | Macros | Enumerations | Functions
Modifying WIMs

Make changes to a WIMStruct, in preparation of persisting the WIMStruct to an on-disk file. More...

Data Structures

struct  wimlib_capture_source
 An array of these structures is passed to wimlib_add_image_multisource() to specify the sources from which to create a WIM image. More...
 
struct  wimlib_add_command
 Data for a WIMLIB_UPDATE_OP_ADD operation. More...
 
struct  wimlib_delete_command
 Data for a WIMLIB_UPDATE_OP_DELETE operation. More...
 
struct  wimlib_rename_command
 Data for a WIMLIB_UPDATE_OP_RENAME operation. More...
 
struct  wimlib_update_command
 Specification of an update to perform on a WIM image. More...
 

Macros

#define WIMLIB_CHANGE_READONLY_FLAG   0x00000001
 Set or unset the "readonly" WIM header flag (WIM_HDR_FLAG_READONLY in Microsoft's documentation), based on the wimlib_wim_info.is_marked_readonly member of the info parameter. More...
 
#define WIMLIB_CHANGE_GUID   0x00000002
 Set the GUID (globally unique identifier) of the WIM file to the value specified in wimlib_wim_info.guid of the info parameter. More...
 
#define WIMLIB_CHANGE_BOOT_INDEX   0x00000004
 Change the bootable image of the WIM to the value specified in wimlib_wim_info.boot_index of the info parameter. More...
 
#define WIMLIB_CHANGE_RPFIX_FLAG   0x00000008
 Change the WIM_HDR_FLAG_RP_FIX flag of the WIM file to the value specified in wimlib_wim_info.has_rpfix of the info parameter. More...
 
#define WIMLIB_ADD_FLAG_NTFS   0x00000001
 UNIX-like systems only: Directly capture an NTFS volume rather than a generic directory. More...
 
#define WIMLIB_ADD_FLAG_DEREFERENCE   0x00000002
 Follow symbolic links when scanning the directory tree. More...
 
#define WIMLIB_ADD_FLAG_VERBOSE   0x00000004
 Call the progress function with the message WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file has been scanned. More...
 
#define WIMLIB_ADD_FLAG_BOOT   0x00000008
 Mark the image being added as the bootable image of the WIM. More...
 
#define WIMLIB_ADD_FLAG_UNIX_DATA   0x00000010
 UNIX-like systems only: Store the UNIX owner, group, mode, and device ID (major and minor number) of each file. More...
 
#define WIMLIB_ADD_FLAG_NO_ACLS   0x00000020
 Do not capture security descriptors. More...
 
#define WIMLIB_ADD_FLAG_STRICT_ACLS   0x00000040
 Fail immediately if the full security descriptor of any file or directory cannot be accessed. More...
 
#define WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE   0x00000080
 Call the progress function with the message WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from capture. More...
 
#define WIMLIB_ADD_FLAG_RPFIX   0x00000100
 Reparse-point fixups: Modify absolute symbolic links (and junctions, in the case of Windows) that point inside the directory being captured to instead be absolute relative to the directory being captured. More...
 
#define WIMLIB_ADD_FLAG_NORPFIX   0x00000200
 Don't do reparse point fixups. More...
 
#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE   0x00000400
 Do not automatically exclude unsupported files or directories from capture, such as encrypted files in NTFS-3G capture mode, or device files and FIFOs on UNIX-like systems when not also using WIMLIB_ADD_FLAG_UNIX_DATA. More...
 
#define WIMLIB_ADD_FLAG_WINCONFIG   0x00000800
 Automatically select a capture configuration appropriate for capturing filesystems containing Windows operating systems. More...
 
#define WIMLIB_ADD_FLAG_WIMBOOT   0x00001000
 Capture image as "WIMBoot compatible". More...
 
#define WIMLIB_ADD_FLAG_NO_REPLACE   0x00002000
 If the add command involves adding a non-directory file to a location at which there already exists a nondirectory file in the image, issue WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file. More...
 
#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION   0x00004000
 Send WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION messages to the progress function. More...
 
#define WIMLIB_ADD_FLAG_SNAPSHOT   0x00008000
 Since wimlib v1.9.0: create a temporary filesystem snapshot of the source directory and add the files from it. More...
 
#define WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED   0x00010000
 Since wimlib v1.9.0: permit the library to discard file paths after the initial scan. More...
 
#define WIMLIB_DELETE_FLAG_FORCE   0x00000001
 Do not issue an error if the path to delete does not exist. More...
 
#define WIMLIB_DELETE_FLAG_RECURSIVE   0x00000002
 Delete the file or directory tree recursively; if not specified, an error is issued if the path to delete is a directory. More...
 
#define WIMLIB_EXPORT_FLAG_BOOT   0x00000001
 If a single image is being exported, mark it bootable in the destination WIM. More...
 
#define WIMLIB_EXPORT_FLAG_NO_NAMES   0x00000002
 Give the exported image(s) no names. More...
 
#define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS   0x00000004
 Give the exported image(s) no descriptions. More...
 
#define WIMLIB_EXPORT_FLAG_GIFT   0x00000008
 This advises the library that the program is finished with the source WIMStruct and will not attempt to access it after the call to wimlib_export_image(), with the exception of the call to wimlib_free(). More...
 
#define WIMLIB_EXPORT_FLAG_WIMBOOT   0x00000010
 Mark each exported image as WIMBoot-compatible. More...
 
#define WIMLIB_UPDATE_FLAG_SEND_PROGRESS   0x00000001
 Send WIMLIB_PROGRESS_MSG_UPDATE_BEGIN_COMMAND and WIMLIB_PROGRESS_MSG_UPDATE_END_COMMAND messages. More...
 

Enumerations

enum  wimlib_update_op { WIMLIB_UPDATE_OP_ADD = 0, WIMLIB_UPDATE_OP_DELETE = 1, WIMLIB_UPDATE_OP_RENAME = 2 }
 The specific type of update to perform. More...
 

Functions

int wimlib_add_empty_image (WIMStruct *wim, const wimlib_tchar *name, int *new_idx_ret)
 Append an empty image to a WIMStruct. More...
 
int wimlib_add_image (WIMStruct *wim, const wimlib_tchar *source, const wimlib_tchar *name, const wimlib_tchar *config_file, int add_flags)
 Add an image to a WIMStruct from an on-disk directory tree or NTFS volume. More...
 
int wimlib_add_image_multisource (WIMStruct *wim, const struct wimlib_capture_source *sources, size_t num_sources, const wimlib_tchar *name, const wimlib_tchar *config_file, int add_flags)
 This function is equivalent to wimlib_add_image() except it allows for multiple sources to be combined into a single WIM image. More...
 
int wimlib_add_tree (WIMStruct *wim, int image, const wimlib_tchar *fs_source_path, const wimlib_tchar *wim_target_path, int add_flags)
 Add the file or directory tree at fs_source_path on the filesystem to the location wim_target_path within the specified image of the wim. More...
 
int wimlib_delete_image (WIMStruct *wim, int image)
 Delete an image, or all images, from a WIMStruct. More...
 
int wimlib_delete_path (WIMStruct *wim, int image, const wimlib_tchar *path, int delete_flags)
 Delete the path from the specified image of the wim. More...
 
int wimlib_export_image (WIMStruct *src_wim, int src_image, WIMStruct *dest_wim, const wimlib_tchar *dest_name, const wimlib_tchar *dest_description, int export_flags)
 Export an image, or all images, from a WIMStruct into another WIMStruct. More...
 
int wimlib_reference_template_image (WIMStruct *wim, int new_image, WIMStruct *template_wim, int template_image, int flags)
 Declare that a newly added image is mostly the same as a prior image, but captured at a later point in time, possibly with some modifications in the intervening time. More...
 
int wimlib_rename_path (WIMStruct *wim, int image, const wimlib_tchar *source_path, const wimlib_tchar *dest_path)
 Rename the source_path to the dest_path in the specified image of the wim. More...
 
int wimlib_set_image_descripton (WIMStruct *wim, int image, const wimlib_tchar *description)
 Change the description of a WIM image. More...
 
int wimlib_set_image_flags (WIMStruct *wim, int image, const wimlib_tchar *flags)
 Change what is stored in the <FLAGS> element in the WIM XML document (usually something like "Core" or "Ultimate"). More...
 
int wimlib_set_image_name (WIMStruct *wim, int image, const wimlib_tchar *name)
 Change the name of a WIM image. More...
 
int wimlib_set_image_property (WIMStruct *wim, int image, const wimlib_tchar *property_name, const wimlib_tchar *property_value)
 Since wimlib v1.8.3: add, modify, or remove a per-image property from the WIM's XML document. More...
 
int wimlib_set_wim_info (WIMStruct *wim, const struct wimlib_wim_info *info, int which)
 Set basic information about a WIM. More...
 
int wimlib_update_image (WIMStruct *wim, int image, const struct wimlib_update_command *cmds, size_t num_cmds, int update_flags)
 Update a WIM image by adding, deleting, and/or renaming files or directories. More...
 

Detailed Description

Make changes to a WIMStruct, in preparation of persisting the WIMStruct to an on-disk file.

Capturing and adding WIM images

As described in Basic WIM handling concepts, capturing a new WIM or appending an image to an existing WIM is a multi-step process, but at its core is wimlib_add_image() or an equivalent function. Normally, wimlib_add_image() takes an on-disk directory tree and logically adds it to a WIMStruct as a new image. However, when supported by the build of the library, there is also a special NTFS volume capture mode (entered when WIMLIB_ADD_FLAG_NTFS is specified) that allows adding the image directly from an unmounted NTFS volume.

Another function, wimlib_add_image_multisource() is also provided. It generalizes wimlib_add_image() to allow combining multiple files or directory trees into a single WIM image in a configurable way.

For maximum customization of WIM image creation, it is also possible to add a completely empty WIM image with wimlib_add_empty_image(), then update it with wimlib_update_image(). (This is in fact what wimlib_add_image() and wimlib_add_image_multisource() do internally.)

Note that some details of how image addition/capture works are documented more fully in the documentation for wimcapture.

Deleting WIM images

wimlib_delete_image() can delete an image from a WIMStruct. But as usual, wimlib_write() or wimlib_overwrite() must be called to cause the changes to be made persistent in an on-disk WIM file.

Exporting WIM images

wimlib_export_image() can copy, or "export", an image from one WIM to another.

Other modifications

wimlib_update_image() can add, delete, and rename files in a WIM image.

wimlib_set_image_property() can change other image metadata.

wimlib_set_wim_info() can change information about the WIM file itself, such as the boot index.

Macro Definition Documentation

◆ WIMLIB_CHANGE_READONLY_FLAG

#define WIMLIB_CHANGE_READONLY_FLAG   0x00000001

Set or unset the "readonly" WIM header flag (WIM_HDR_FLAG_READONLY in Microsoft's documentation), based on the wimlib_wim_info.is_marked_readonly member of the info parameter.

This is distinct from basic file permissions; this flag can be set on a WIM file that is physically writable.

wimlib disallows modifying on-disk WIM files with the readonly flag set. However, wimlib_overwrite() with WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG will override this — and in fact, this is necessary to set the readonly flag persistently on an existing WIM file.

◆ WIMLIB_CHANGE_GUID

#define WIMLIB_CHANGE_GUID   0x00000002

Set the GUID (globally unique identifier) of the WIM file to the value specified in wimlib_wim_info.guid of the info parameter.

◆ WIMLIB_CHANGE_BOOT_INDEX

#define WIMLIB_CHANGE_BOOT_INDEX   0x00000004

Change the bootable image of the WIM to the value specified in wimlib_wim_info.boot_index of the info parameter.

◆ WIMLIB_CHANGE_RPFIX_FLAG

#define WIMLIB_CHANGE_RPFIX_FLAG   0x00000008

Change the WIM_HDR_FLAG_RP_FIX flag of the WIM file to the value specified in wimlib_wim_info.has_rpfix of the info parameter.

This flag generally indicates whether an image in the WIM has been captured with reparse-point fixups enabled. wimlib also treats this flag as specifying whether to do reparse-point fixups by default when capturing or applying WIM images.

◆ WIMLIB_ADD_FLAG_NTFS

#define WIMLIB_ADD_FLAG_NTFS   0x00000001

UNIX-like systems only: Directly capture an NTFS volume rather than a generic directory.

This requires that wimlib was compiled with support for libntfs-3g.

This flag cannot be combined with WIMLIB_ADD_FLAG_DEREFERENCE or WIMLIB_ADD_FLAG_UNIX_DATA.

Do not use this flag on Windows, where wimlib already supports all Windows-native filesystems, including NTFS, through the Windows APIs.

◆ WIMLIB_ADD_FLAG_DEREFERENCE

#define WIMLIB_ADD_FLAG_DEREFERENCE   0x00000002

Follow symbolic links when scanning the directory tree.

Currently only supported on UNIX-like systems.

◆ WIMLIB_ADD_FLAG_VERBOSE

#define WIMLIB_ADD_FLAG_VERBOSE   0x00000004

Call the progress function with the message WIMLIB_PROGRESS_MSG_SCAN_DENTRY when each directory or file has been scanned.

◆ WIMLIB_ADD_FLAG_BOOT

#define WIMLIB_ADD_FLAG_BOOT   0x00000008

Mark the image being added as the bootable image of the WIM.

This flag is valid only for wimlib_add_image() and wimlib_add_image_multisource().

Note that you can also change the bootable image of a WIM using wimlib_set_wim_info().

Note: WIMLIB_ADD_FLAG_BOOT does something different from, and independent from, WIMLIB_ADD_FLAG_WIMBOOT.

◆ WIMLIB_ADD_FLAG_UNIX_DATA

#define WIMLIB_ADD_FLAG_UNIX_DATA   0x00000010

UNIX-like systems only: Store the UNIX owner, group, mode, and device ID (major and minor number) of each file.

In addition, capture special files such as device nodes and FIFOs. Since wimlib v1.11.0, on Linux also capture extended attributes. See the documentation for the –unix-data option to wimcapture for more information.

◆ WIMLIB_ADD_FLAG_NO_ACLS

#define WIMLIB_ADD_FLAG_NO_ACLS   0x00000020

Do not capture security descriptors.

Only has an effect in NTFS-3G capture mode, or in Windows native builds.

◆ WIMLIB_ADD_FLAG_STRICT_ACLS

#define WIMLIB_ADD_FLAG_STRICT_ACLS   0x00000040

Fail immediately if the full security descriptor of any file or directory cannot be accessed.

Only has an effect in Windows native builds. The default behavior without this flag is to first try omitting the SACL from the security descriptor, then to try omitting the security descriptor entirely.

◆ WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE

#define WIMLIB_ADD_FLAG_EXCLUDE_VERBOSE   0x00000080

Call the progress function with the message WIMLIB_PROGRESS_MSG_SCAN_DENTRY when a directory or file is excluded from capture.

This is a subset of the messages provided by WIMLIB_ADD_FLAG_VERBOSE.

◆ WIMLIB_ADD_FLAG_RPFIX

#define WIMLIB_ADD_FLAG_RPFIX   0x00000100

Reparse-point fixups: Modify absolute symbolic links (and junctions, in the case of Windows) that point inside the directory being captured to instead be absolute relative to the directory being captured.

Without this flag, the default is to do reparse-point fixups if WIM_HDR_FLAG_RP_FIX is set in the WIM header or if this is the first image being added.

◆ WIMLIB_ADD_FLAG_NORPFIX

#define WIMLIB_ADD_FLAG_NORPFIX   0x00000200

Don't do reparse point fixups.

See WIMLIB_ADD_FLAG_RPFIX.

◆ WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE

#define WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE   0x00000400

Do not automatically exclude unsupported files or directories from capture, such as encrypted files in NTFS-3G capture mode, or device files and FIFOs on UNIX-like systems when not also using WIMLIB_ADD_FLAG_UNIX_DATA.

Instead, fail with WIMLIB_ERR_UNSUPPORTED_FILE when such a file is encountered.

◆ WIMLIB_ADD_FLAG_WINCONFIG

#define WIMLIB_ADD_FLAG_WINCONFIG   0x00000800

Automatically select a capture configuration appropriate for capturing filesystems containing Windows operating systems.

For example, /pagefile.sys and "/System Volume Information" will be excluded.

When this flag is specified, the corresponding config parameter (for wimlib_add_image()) or member (for wimlib_update_image()) must be NULL. Otherwise, WIMLIB_ERR_INVALID_PARAM will be returned.

Note that the default behavior— that is, when neither WIMLIB_ADD_FLAG_WINCONFIG nor WIMLIB_ADD_FLAG_WIMBOOT is specified and config is NULL— is to use no capture configuration, meaning that no files are excluded from capture.

◆ WIMLIB_ADD_FLAG_WIMBOOT

#define WIMLIB_ADD_FLAG_WIMBOOT   0x00001000

Capture image as "WIMBoot compatible".

In addition, if no capture configuration file is explicitly specified use the capture configuration file $SOURCE/Windows/System32/WimBootCompress.ini if it exists, where $SOURCE is the directory being captured; or, if a capture configuration file is explicitly specified, use it and also place it at /Windows/System32/WimBootCompress.ini in the WIM image.

This flag does not, by itself, change the compression type or chunk size. Before writing the WIM file, you may wish to set the compression format to be the same as that used by WIMGAPI and DISM:

However, "WIMBoot" also works with other XPRESS chunk sizes as well as LZX with 32768 byte chunks.

Note: WIMLIB_ADD_FLAG_WIMBOOT does something different from, and independent from, WIMLIB_ADD_FLAG_BOOT.

Since wimlib v1.8.3, WIMLIB_ADD_FLAG_WIMBOOT also causes offline WIM-backed files to be added as the "real" files rather than as their reparse points, provided that their data is already present in the WIM. This feature can be useful when updating a backing WIM file in an "offline" state.

◆ WIMLIB_ADD_FLAG_NO_REPLACE

#define WIMLIB_ADD_FLAG_NO_REPLACE   0x00002000

If the add command involves adding a non-directory file to a location at which there already exists a nondirectory file in the image, issue WIMLIB_ERR_INVALID_OVERLAY instead of replacing the file.

This was the default behavior before wimlib v1.7.0.

◆ WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION

#define WIMLIB_ADD_FLAG_TEST_FILE_EXCLUSION   0x00004000

Send WIMLIB_PROGRESS_MSG_TEST_FILE_EXCLUSION messages to the progress function.

Note: This method for file exclusions is independent from the capture configuration file mechanism.

◆ WIMLIB_ADD_FLAG_SNAPSHOT

#define WIMLIB_ADD_FLAG_SNAPSHOT   0x00008000

Since wimlib v1.9.0: create a temporary filesystem snapshot of the source directory and add the files from it.

Currently, this option is only supported on Windows, where it uses the Volume Shadow Copy Service (VSS). Using this option, you can create a consistent backup of the system volume of a running Windows system without running into problems with locked files. For the VSS snapshot to be successfully created, your application must be run as an Administrator, and it cannot be run in WoW64 mode (i.e. if Windows is 64-bit, then your application must be 64-bit as well).

◆ WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED

#define WIMLIB_ADD_FLAG_FILE_PATHS_UNNEEDED   0x00010000

Since wimlib v1.9.0: permit the library to discard file paths after the initial scan.

If the application won't use WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES while writing the WIM archive, this flag can be used to allow the library to enable optimizations such as opening files by inode number rather than by path. Currently this only makes a difference on Windows.

◆ WIMLIB_DELETE_FLAG_FORCE

#define WIMLIB_DELETE_FLAG_FORCE   0x00000001

Do not issue an error if the path to delete does not exist.

◆ WIMLIB_DELETE_FLAG_RECURSIVE

#define WIMLIB_DELETE_FLAG_RECURSIVE   0x00000002

Delete the file or directory tree recursively; if not specified, an error is issued if the path to delete is a directory.

◆ WIMLIB_EXPORT_FLAG_BOOT

#define WIMLIB_EXPORT_FLAG_BOOT   0x00000001

If a single image is being exported, mark it bootable in the destination WIM.

Alternatively, if WIMLIB_ALL_IMAGES is specified as the image to export, the image in the source WIM (if any) that is marked as bootable is also marked as bootable in the destination WIM.

◆ WIMLIB_EXPORT_FLAG_NO_NAMES

#define WIMLIB_EXPORT_FLAG_NO_NAMES   0x00000002

Give the exported image(s) no names.

Avoids problems with image name collisions.

◆ WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS

#define WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS   0x00000004

Give the exported image(s) no descriptions.

◆ WIMLIB_EXPORT_FLAG_GIFT

#define WIMLIB_EXPORT_FLAG_GIFT   0x00000008

This advises the library that the program is finished with the source WIMStruct and will not attempt to access it after the call to wimlib_export_image(), with the exception of the call to wimlib_free().

◆ WIMLIB_EXPORT_FLAG_WIMBOOT

#define WIMLIB_EXPORT_FLAG_WIMBOOT   0x00000010

Mark each exported image as WIMBoot-compatible.

Note: by itself, this does change the destination WIM's compression type, nor does it add the file \Windows\System32\WimBootCompress.ini in the WIM image. Before writing the destination WIM, it's recommended to do something like:

wimlib_add_tree(wim, image, L"myconfig.ini",
L"\\Windows\\System32\\WimBootCompress.ini", 0);

◆ WIMLIB_UPDATE_FLAG_SEND_PROGRESS

#define WIMLIB_UPDATE_FLAG_SEND_PROGRESS   0x00000001

Enumeration Type Documentation

◆ wimlib_update_op

The specific type of update to perform.

Enumerator
WIMLIB_UPDATE_OP_ADD 

Add a new file or directory tree to the image.

WIMLIB_UPDATE_OP_DELETE 

Delete a file or directory tree from the image.

WIMLIB_UPDATE_OP_RENAME 

Rename a file or directory tree in the image.

Function Documentation

◆ wimlib_add_empty_image()

int wimlib_add_empty_image ( WIMStruct wim,
const wimlib_tchar name,
int *  new_idx_ret 
)

Append an empty image to a WIMStruct.

The new image will initially contain no files or directories, although if written without further modifications, then a root directory will be created automatically for it.

After calling this function, you can use wimlib_update_image() to add files to the new image. This gives you more control over making the new image compared to calling wimlib_add_image() or wimlib_add_image_multisource().

Parameters
wimPointer to the WIMStruct to which to add the image.
nameName to give the new image. If NULL or empty, the new image is given no name. If nonempty, it must specify a name that does not already exist in wim.
new_idx_retIf non-NULL, the index of the newly added image is returned in this location.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_IMAGE_NAME_COLLISIONThe WIM already contains an image with the requested name.

◆ wimlib_add_image()

int wimlib_add_image ( WIMStruct wim,
const wimlib_tchar source,
const wimlib_tchar name,
const wimlib_tchar config_file,
int  add_flags 
)

Add an image to a WIMStruct from an on-disk directory tree or NTFS volume.

The directory tree or NTFS volume is scanned immediately to load the dentry tree into memory, and file metadata is read. However, actual file data may not be read until the WIMStruct is persisted to disk using wimlib_write() or wimlib_overwrite().

See the documentation for the wimlib-imagex program for more information about the "normal" capture mode versus the NTFS capture mode (entered by providing the flag WIMLIB_ADD_FLAG_NTFS).

Note that no changes are committed to disk until wimlib_write() or wimlib_overwrite() is called.

Parameters
wimPointer to the WIMStruct to which to add the image.
sourceA path to a directory or unmounted NTFS volume that will be captured as a WIM image.
nameName to give the new image. If NULL or empty, the new image is given no name. If nonempty, it must specify a name that does not already exist in wim.
config_filePath to capture configuration file, or NULL. This file may specify, among other things, which files to exclude from capture. See the documentation for wimcapture (–config option) for details of the file format. If NULL, the default capture configuration will be used. Ordinarily, the default capture configuration will result in no files being excluded from capture purely based on name; however, the WIMLIB_ADD_FLAG_WINCONFIG and WIMLIB_ADD_FLAG_WIMBOOT flags modify the default.
add_flagsBitwise OR of flags prefixed with WIMLIB_ADD_FLAG.
Returns
0 on success; a wimlib_error_code value on failure.

This function is implemented by calling wimlib_add_empty_image(), then calling wimlib_update_image() with a single "add" command, so any error code returned by wimlib_add_empty_image() may be returned, as well as any error codes returned by wimlib_update_image() other than ones documented as only being returned specifically by an update involving delete or rename commands.

If a progress function is registered with wim, then it will receive the messages WIMLIB_PROGRESS_MSG_SCAN_BEGIN and WIMLIB_PROGRESS_MSG_SCAN_END. In addition, if WIMLIB_ADD_FLAG_VERBOSE is specified in add_flags, it will receive WIMLIB_PROGRESS_MSG_SCAN_DENTRY.

◆ wimlib_add_image_multisource()

int wimlib_add_image_multisource ( WIMStruct wim,
const struct wimlib_capture_source sources,
size_t  num_sources,
const wimlib_tchar name,
const wimlib_tchar config_file,
int  add_flags 
)

This function is equivalent to wimlib_add_image() except it allows for multiple sources to be combined into a single WIM image.

This is done by specifying the sources and num_sources parameters instead of the source parameter of wimlib_add_image(). The rest of the parameters are the same as wimlib_add_image(). See the documentation for wimcapture for full details on how this mode works.

◆ wimlib_add_tree()

int wimlib_add_tree ( WIMStruct wim,
int  image,
const wimlib_tchar fs_source_path,
const wimlib_tchar wim_target_path,
int  add_flags 
)

Add the file or directory tree at fs_source_path on the filesystem to the location wim_target_path within the specified image of the wim.

This just builds an appropriate wimlib_add_command and passes it to wimlib_update_image().

◆ wimlib_delete_image()

int wimlib_delete_image ( WIMStruct wim,
int  image 
)

Delete an image, or all images, from a WIMStruct.

Note that no changes are committed to disk until wimlib_write() or wimlib_overwrite() is called.

Parameters
wimPointer to the WIMStruct from which to delete the image.
imageThe 1-based index of the image to delete, or WIMLIB_ALL_IMAGES to delete all images.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INVALID_IMAGEimage does not exist in the WIM.

This function can additionally return WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_METADATA_NOT_FOUND, WIMLIB_ERR_READ, or WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for different reasons) to read the metadata resource for an image that needed to be deleted.

If this function fails when image was WIMLIB_ALL_IMAGES, then it's possible that some but not all of the images were deleted.

◆ wimlib_delete_path()

int wimlib_delete_path ( WIMStruct wim,
int  image,
const wimlib_tchar path,
int  delete_flags 
)

Delete the path from the specified image of the wim.

This just builds an appropriate wimlib_delete_command and passes it to wimlib_update_image().

◆ wimlib_export_image()

int wimlib_export_image ( WIMStruct src_wim,
int  src_image,
WIMStruct dest_wim,
const wimlib_tchar dest_name,
const wimlib_tchar dest_description,
int  export_flags 
)

Export an image, or all images, from a WIMStruct into another WIMStruct.

Specifically, if the destination WIMStruct contains n images, then the source image(s) will be appended, in order, starting at destination index n + 1. By default, all image metadata will be exported verbatim, but certain changes can be made by passing appropriate parameters.

wimlib_export_image() is only an in-memory operation; no changes are committed to disk until wimlib_write() or wimlib_overwrite() is called.

A limitation of the current implementation of wimlib_export_image() is that the directory tree of a source or destination image cannot be updated following an export until one of the two images has been freed from memory.

Parameters
src_wimThe WIM from which to export the images, specified as a pointer to the WIMStruct for a standalone WIM file, a delta WIM file, or part 1 of a split WIM. In the case of a WIM file that is not standalone, this WIMStruct must have had any needed external resources previously referenced using wimlib_reference_resources() or wimlib_reference_resource_files().
src_imageThe 1-based index of the image from src_wim to export, or WIMLIB_ALL_IMAGES.
dest_wimThe WIMStruct to which to export the images.
dest_nameFor single-image exports, the name to give the exported image in dest_wim. If left NULL, the name from src_wim is used. For WIMLIB_ALL_IMAGES exports, this parameter must be left NULL; in that case, the names are all taken from src_wim. This parameter is overridden by WIMLIB_EXPORT_FLAG_NO_NAMES.
dest_descriptionFor single-image exports, the description to give the exported image in the new WIM file. If left NULL, the description from src_wim is used. For WIMLIB_ALL_IMAGES exports, this parameter must be left NULL; in that case, the description are all taken from src_wim. This parameter is overridden by WIMLIB_EXPORT_FLAG_NO_DESCRIPTIONS.
export_flagsBitwise OR of flags prefixed with WIMLIB_EXPORT_FLAG.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_DUPLICATE_EXPORTED_IMAGEOne or more of the source images had already been exported into the destination WIM.
WIMLIB_ERR_IMAGE_NAME_COLLISIONOne or more of the names being given to an exported image was already in use in the destination WIM.
WIMLIB_ERR_INVALID_IMAGEsrc_image does not exist in src_wim.
WIMLIB_ERR_METADATA_NOT_FOUNDAt least one of src_wim and dest_wim does not contain image metadata; for example, one of them represents a non-first part of a split WIM.
WIMLIB_ERR_RESOURCE_NOT_FOUNDA file data blob that needed to be exported could not be found in the blob lookup table of src_wim. See Creating and handling non-standalone WIMs.

This function can additionally return WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_METADATA_NOT_FOUND, WIMLIB_ERR_READ, or WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for different reasons) to read the metadata resource for an image in src_wim that needed to be exported.

◆ wimlib_reference_template_image()

int wimlib_reference_template_image ( WIMStruct wim,
int  new_image,
WIMStruct template_wim,
int  template_image,
int  flags 
)

Declare that a newly added image is mostly the same as a prior image, but captured at a later point in time, possibly with some modifications in the intervening time.

This is designed to be used in incremental backups of the same filesystem or directory tree.

This function compares the metadata of the directory tree of the newly added image against that of the old image. Any files that are present in both the newly added image and the old image and have timestamps that indicate they haven't been modified are deemed not to have been modified and have their checksums copied from the old image. Because of this and because WIM uses single-instance streams, such files need not be read from the filesystem when the WIM is being written or overwritten. Note that these unchanged files will still be "archived" and will be logically present in the new image; the optimization is that they don't need to actually be read from the filesystem because the WIM already contains them.

This function is provided to optimize incremental backups. The resulting WIM file will still be the same regardless of whether this function is called. (This is, however, assuming that timestamps have not been manipulated or unmaintained as to trick this function into thinking a file has not been modified when really it has. To partly guard against such cases, other metadata such as file sizes will be checked as well.)

This function must be called after adding the new image (e.g. with wimlib_add_image()), but before writing the updated WIM file (e.g. with wimlib_overwrite()).

Parameters
wimPointer to the WIMStruct containing the newly added image.
new_imageThe 1-based index in wim of the newly added image.
template_wimPointer to the WIMStruct containing the template image. This can be, but does not have to be, the same WIMStruct as wim.
template_imageThe 1-based index in template_wim of the template image.
flagsReserved; must be 0.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INVALID_IMAGEnew_image does not exist in wim or template_image does not exist in template_wim.
WIMLIB_ERR_METADATA_NOT_FOUNDAt least one of wim and template_wim does not contain image metadata; for example, one of them represents a non-first part of a split WIM.
WIMLIB_ERR_INVALID_PARAMIdentical values were provided for the template and new image; or new_image specified an image that had not been modified since opening the WIM.

This function can additionally return WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_METADATA_NOT_FOUND, WIMLIB_ERR_READ, or WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for different reasons) to read the metadata resource for the template image.

◆ wimlib_rename_path()

int wimlib_rename_path ( WIMStruct wim,
int  image,
const wimlib_tchar source_path,
const wimlib_tchar dest_path 
)

Rename the source_path to the dest_path in the specified image of the wim.

This just builds an appropriate wimlib_rename_command and passes it to wimlib_update_image().

◆ wimlib_set_image_descripton()

int wimlib_set_image_descripton ( WIMStruct wim,
int  image,
const wimlib_tchar description 
)

Change the description of a WIM image.

Equivalent to wimlib_set_image_property(wim, image, "DESCRIPTION", description).

Note that "description" is misspelled in the name of this function.

◆ wimlib_set_image_flags()

int wimlib_set_image_flags ( WIMStruct wim,
int  image,
const wimlib_tchar flags 
)

Change what is stored in the <FLAGS> element in the WIM XML document (usually something like "Core" or "Ultimate").

Equivalent to wimlib_set_image_property(wim, image, "FLAGS", flags).

◆ wimlib_set_image_name()

int wimlib_set_image_name ( WIMStruct wim,
int  image,
const wimlib_tchar name 
)

Change the name of a WIM image.

Equivalent to wimlib_set_image_property(wim, image, "NAME", name).

◆ wimlib_set_image_property()

int wimlib_set_image_property ( WIMStruct wim,
int  image,
const wimlib_tchar property_name,
const wimlib_tchar property_value 
)

Since wimlib v1.8.3: add, modify, or remove a per-image property from the WIM's XML document.

This is an alternative to wimlib_set_image_name(), wimlib_set_image_descripton(), and wimlib_set_image_flags() which allows manipulating any simple string property.

Parameters
wimPointer to the WIMStruct for the WIM.
imageThe 1-based index of the image for which to set the property.
property_nameThe name of the image property in the same format documented for wimlib_get_image_property().
Note: if creating a new element using a bracketed index such as "WINDOWS/LANGUAGES/LANGUAGE[2]", the highest index that can be specified is one greater than the number of existing elements with that same name, excluding the index. That means that if you are adding a list of new elements, they must be added sequentially from the first index (1) to the last index (n).
property_valueIf not NULL and not empty, the property is set to this value. Otherwise, the property is removed from the XML document.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_IMAGE_NAME_COLLISIONThe user requested to set the image name (the NAME property), but another image in the WIM already had the requested name.
WIMLIB_ERR_INVALID_IMAGEimage does not exist in wim.
WIMLIB_ERR_INVALID_PARAMproperty_name has an unsupported format, or property_name included a bracketed index that was too high.

◆ wimlib_set_wim_info()

int wimlib_set_wim_info ( WIMStruct wim,
const struct wimlib_wim_info info,
int  which 
)

Set basic information about a WIM.

Parameters
wimPointer to the WIMStruct for a WIM.
infoPointer to a wimlib_wim_info structure that contains the information to set. Only the information explicitly specified in the which flags need be valid.
whichFlags that specify which information to set. This is a bitwise OR of WIMLIB_CHANGE_READONLY_FLAG, WIMLIB_CHANGE_GUID, WIMLIB_CHANGE_BOOT_INDEX, and/or WIMLIB_CHANGE_RPFIX_FLAG.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_IMAGE_COUNTWIMLIB_CHANGE_BOOT_INDEX was specified, but wimlib_wim_info.boot_index did not specify 0 or a valid 1-based image index in the WIM.

◆ wimlib_update_image()

int wimlib_update_image ( WIMStruct wim,
int  image,
const struct wimlib_update_command cmds,
size_t  num_cmds,
int  update_flags 
)

Update a WIM image by adding, deleting, and/or renaming files or directories.

Parameters
wimPointer to the WIMStruct containing the image to update.
imageThe 1-based index of the image to update.
cmdsAn array of wimlib_update_command's that specify the update operations to perform.
num_cmdsNumber of commands in cmds.
update_flagsWIMLIB_UPDATE_FLAG_SEND_PROGRESS or 0.
Returns
0 on success; a wimlib_error_code value on failure. On failure, all update commands will be rolled back, and no visible changes will have been made to wim.
Return values
WIMLIB_ERR_FVE_LOCKED_VOLUMEWindows-only: One of the "add" commands attempted to add files from an encrypted BitLocker volume that hasn't yet been unlocked.
WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCESThere are currently multiple references to the image as a result of a call to wimlib_export_image(). Free one before attempting the update.
WIMLIB_ERR_INVALID_CAPTURE_CONFIGThe contents of a capture configuration file were invalid.
WIMLIB_ERR_INVALID_IMAGEimage did not exist in wim.
WIMLIB_ERR_INVALID_OVERLAYAn add command with WIMLIB_ADD_FLAG_NO_REPLACE specified attempted to replace an existing nondirectory file.
WIMLIB_ERR_INVALID_PARAMAn unknown operation type was provided in the update commands; or unknown or incompatible flags were provided in a flags parameter; or there was another problem with the provided parameters.
WIMLIB_ERR_INVALID_REPARSE_DATAWhile executing an add command, a reparse point had invalid data.
WIMLIB_ERR_IS_DIRECTORYAn add command attempted to replace a directory with a non-directory; or a delete command without WIMLIB_DELETE_FLAG_RECURSIVE attempted to delete a directory; or a rename command attempted to rename a directory to a non-directory.
WIMLIB_ERR_NOTDIRAn add command attempted to replace a non-directory with a directory; or an add command attempted to set the root of the image to a non-directory; or a rename command attempted to rename a directory to a non-directory; or a component of an image path that was used as a directory was not, in fact, a directory.
WIMLIB_ERR_NOTEMPTYA rename command attempted to rename a directory to a non-empty directory; or a rename command would have created a loop.
WIMLIB_ERR_NTFS_3GWhile executing an add command with WIMLIB_ADD_FLAG_NTFS specified, an error occurred while reading data from the NTFS volume using libntfs-3g.
WIMLIB_ERR_OPENFailed to open a file to be captured while executing an add command.
WIMLIB_ERR_OPENDIRFailed to open a directory to be captured while executing an add command.
WIMLIB_ERR_PATH_DOES_NOT_EXISTA delete command without WIMLIB_DELETE_FLAG_FORCE specified was for a WIM path that did not exist; or a rename command attempted to rename a file that does not exist.
WIMLIB_ERR_READWhile executing an add command, failed to read data from a file or directory to be captured.
WIMLIB_ERR_READLINKWhile executing an add command, failed to read the target of a symbolic link, junction, or other reparse point.
WIMLIB_ERR_STATWhile executing an add command, failed to read metadata for a file or directory.
WIMLIB_ERR_UNABLE_TO_READ_CAPTURE_CONFIGA capture configuration file could not be read.
WIMLIB_ERR_UNSUPPORTEDA command had flags provided that are not supported on this platform or in this build of the library.
WIMLIB_ERR_UNSUPPORTED_FILEAn add command with WIMLIB_ADD_FLAG_NO_UNSUPPORTED_EXCLUDE specified discovered a file that was not of a supported type.

This function can additionally return WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_INVALID_METADATA_RESOURCE, WIMLIB_ERR_METADATA_NOT_FOUND, WIMLIB_ERR_READ, or WIMLIB_ERR_UNEXPECTED_END_OF_FILE, all of which indicate failure (for different reasons) to read the metadata resource for an image that needed to be updated.