wimlib
Macros | Functions
Creating and handling non-standalone WIMs

Create and handle non-standalone WIMs, such as split and delta WIMs. More...

Macros

#define WIMLIB_REF_FLAG_GLOB_ENABLE   0x00000001
 For wimlib_reference_resource_files(), enable shell-style filename globbing. More...
 
#define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH   0x00000002
 For wimlib_reference_resource_files(), issue an error (WIMLIB_ERR_GLOB_HAD_NO_MATCHES) if a glob did not match any files. More...
 

Functions

int wimlib_join (const wimlib_tchar *const *swms, unsigned num_swms, const wimlib_tchar *output_path, int swm_open_flags, int wim_write_flags)
 Join a split WIM into a stand-alone (one-part) WIM. More...
 
int wimlib_join_with_progress (const wimlib_tchar *const *swms, unsigned num_swms, const wimlib_tchar *output_path, int swm_open_flags, int wim_write_flags, wimlib_progress_func_t progfunc, void *progctx)
 Same as wimlib_join(), but allows specifying a progress function. More...
 
int wimlib_reference_resource_files (WIMStruct *wim, const wimlib_tchar *const *resource_wimfiles_or_globs, unsigned count, int ref_flags, int open_flags)
 Reference file data from other WIM files or split WIM parts. More...
 
int wimlib_reference_resources (WIMStruct *wim, WIMStruct **resource_wims, unsigned num_resource_wims, int ref_flags)
 Similar to wimlib_reference_resource_files(), but operates at a lower level where the caller must open the WIMStruct for each referenced file itself. More...
 
int wimlib_split (WIMStruct *wim, const wimlib_tchar *swm_name, uint64_t part_size, int write_flags)
 Split a WIM into multiple parts. More...
 

Detailed Description

Create and handle non-standalone WIMs, such as split and delta WIMs.

A WIMStruct backed by an on-disk file normally represents a fully standalone WIM archive. However, WIM archives can also be arranged in non-standalone ways, such as a set of on-disk files that together form a single "split WIM" or "delta WIM". Such arrangements are fully supported by wimlib. However, as a result, in such cases a WIMStruct created from one of these on-disk files initially only partially represents the full WIM and needs to, in effect, be logically combined with other WIMStruct's before performing certain operations, such as extracting files with wimlib_extract_image() or wimlib_extract_paths(). This is done by calling wimlib_reference_resource_files() or wimlib_reference_resources(). Note: if you fail to do so, you may see the error code WIMLIB_ERR_RESOURCE_NOT_FOUND; this just indicates that data is not available because the appropriate WIM files have not yet been referenced.

wimlib_write() can create delta WIMs as well as standalone WIMs, but a specialized function (wimlib_split()) is needed to create a split WIM.

Macro Definition Documentation

◆ WIMLIB_REF_FLAG_GLOB_ENABLE

#define WIMLIB_REF_FLAG_GLOB_ENABLE   0x00000001

For wimlib_reference_resource_files(), enable shell-style filename globbing.

Ignored by wimlib_reference_resources().

◆ WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH

#define WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH   0x00000002

For wimlib_reference_resource_files(), issue an error (WIMLIB_ERR_GLOB_HAD_NO_MATCHES) if a glob did not match any files.

The default behavior without this flag is to issue no error at that point, but then attempt to open the glob as a literal path, which of course will fail anyway if no file exists at that path. No effect if WIMLIB_REF_FLAG_GLOB_ENABLE is not also specified. Ignored by wimlib_reference_resources().

Function Documentation

◆ wimlib_join()

int wimlib_join ( const wimlib_tchar *const *  swms,
unsigned  num_swms,
const wimlib_tchar output_path,
int  swm_open_flags,
int  wim_write_flags 
)

Join a split WIM into a stand-alone (one-part) WIM.

Parameters
swmsAn array of strings that gives the filenames of all parts of the split WIM. No specific order is required, but all parts must be included with no duplicates.
num_swmsNumber of filenames in swms.
swm_open_flagsOpen flags for the split WIM parts (e.g. WIMLIB_OPEN_FLAG_CHECK_INTEGRITY).
wim_write_flagsBitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG, which will be used to write the joined WIM.
output_pathThe path to write the joined WIM file to.
Returns
0 on success; a wimlib_error_code value on failure. This function may return most error codes that can be returned by wimlib_open_wim() and wimlib_write(), as well as the following error codes:
Return values
WIMLIB_ERR_SPLIT_INVALIDThe split WIMs do not form a valid WIM because they do not include all the parts of the original WIM, there are duplicate parts, or not all the parts have the same GUID and compression type.

Note: wimlib is generalized enough that this function is not actually needed to join a split WIM; instead, you could open the first part of the split WIM, then reference the other parts with wimlib_reference_resource_files(), then write the joined WIM using wimlib_write(). However, wimlib_join() provides an easy-to-use wrapper around this that has some advantages (e.g. extra sanity checks).

◆ wimlib_join_with_progress()

int wimlib_join_with_progress ( const wimlib_tchar *const *  swms,
unsigned  num_swms,
const wimlib_tchar output_path,
int  swm_open_flags,
int  wim_write_flags,
wimlib_progress_func_t  progfunc,
void *  progctx 
)

Same as wimlib_join(), but allows specifying a progress function.

The progress function will receive the write progress messages, such as WIMLIB_PROGRESS_MSG_WRITE_STREAMS, while writing the joined WIM. In addition, if WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is specified in swm_open_flags, the progress function will receive a series of WIMLIB_PROGRESS_MSG_VERIFY_INTEGRITY messages when each of the split WIM parts is opened.

◆ wimlib_reference_resource_files()

int wimlib_reference_resource_files ( WIMStruct wim,
const wimlib_tchar *const *  resource_wimfiles_or_globs,
unsigned  count,
int  ref_flags,
int  open_flags 
)

Reference file data from other WIM files or split WIM parts.

This function can be used on WIMs that are not standalone, such as split or "delta" WIMs, to load additional file data before calling a function such as wimlib_extract_image() that requires the file data to be present.

Parameters
wimThe WIMStruct for a WIM that contains metadata resources, but is not necessarily "standalone". In the case of split WIMs, this should be the first part, since only the first part contains the metadata resources. In the case of delta WIMs, this should be the delta WIM rather than the WIM on which it is based.
resource_wimfiles_or_globsArray of paths to WIM files and/or split WIM parts to reference. Alternatively, when WIMLIB_REF_FLAG_GLOB_ENABLE is specified in ref_flags, these are treated as globs rather than literal paths. That is, using this function you can specify zero or more globs, each of which expands to one or more literal paths.
countNumber of entries in resource_wimfiles_or_globs.
ref_flagsBitwise OR of WIMLIB_REF_FLAG_GLOB_ENABLE and/or WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH.
open_flagsAdditional open flags, such as WIMLIB_OPEN_FLAG_CHECK_INTEGRITY, to pass to internal calls to wimlib_open_wim() on the reference files.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_GLOB_HAD_NO_MATCHESOne of the specified globs did not match any paths (only with both WIMLIB_REF_FLAG_GLOB_ENABLE and WIMLIB_REF_FLAG_GLOB_ERR_ON_NOMATCH specified in ref_flags).
WIMLIB_ERR_READI/O or permissions error while processing a file glob.

This function can additionally return most values that can be returned by wimlib_open_wim().

◆ wimlib_reference_resources()

int wimlib_reference_resources ( WIMStruct wim,
WIMStruct **  resource_wims,
unsigned  num_resource_wims,
int  ref_flags 
)

Similar to wimlib_reference_resource_files(), but operates at a lower level where the caller must open the WIMStruct for each referenced file itself.

Parameters
wimThe WIMStruct for a WIM that contains metadata resources, but is not necessarily "standalone". In the case of split WIMs, this should be the first part, since only the first part contains the metadata resources.
resource_wimsArray of pointers to the WIMStruct's for additional resource WIMs or split WIM parts to reference.
num_resource_wimsNumber of entries in resource_wims.
ref_flagsReserved; must be 0.
Returns
0 on success; a wimlib_error_code value on failure.

◆ wimlib_split()

int wimlib_split ( WIMStruct wim,
const wimlib_tchar swm_name,
uint64_t  part_size,
int  write_flags 
)

Split a WIM into multiple parts.

Parameters
wimThe WIMStruct for the WIM to split.
swm_nameName of the split WIM (SWM) file to create. This will be the name of the first part. The other parts will, by default, have the same name with 2, 3, 4, ..., etc. appended before the suffix. However, the exact names can be customized using the progress function.
part_sizeThe maximum size per part, in bytes. Unfortunately, it is not guaranteed that this will really be the maximum size per part, because some file resources in the WIM may be larger than this size, and the WIM file format provides no way to split up file resources among multiple WIMs.
write_flagsBitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. These flags will be used to write each split WIM part. Specify 0 here to get the default behavior.
Returns
0 on success; a wimlib_error_code value on failure. This function may return most error codes that can be returned by wimlib_write() as well as the following error codes:
Return values
WIMLIB_ERR_INVALID_PARAMswm_name was not a nonempty string, or part_size was 0.
WIMLIB_ERR_UNSUPPORTEDThe WIM contains solid resources. Splitting a WIM containing solid resources is not supported.

If a progress function is registered with wim, then for each split WIM part that is written it will receive the messages WIMLIB_PROGRESS_MSG_SPLIT_BEGIN_PART and WIMLIB_PROGRESS_MSG_SPLIT_END_PART.