wimlib
Macros | Functions
Writing and Overwriting WIMs

Create or update an on-disk WIM file. More...

Macros

#define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY   0x00000001
 Include an integrity table in the resulting WIM file. More...
 
#define WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY   0x00000002
 Do not include an integrity table in the resulting WIM file. More...
 
#define WIMLIB_WRITE_FLAG_PIPABLE   0x00000004
 Write the WIM as "pipable". More...
 
#define WIMLIB_WRITE_FLAG_NOT_PIPABLE   0x00000008
 Do not write the WIM as "pipable". More...
 
#define WIMLIB_WRITE_FLAG_RECOMPRESS   0x00000010
 When writing data to the WIM file, recompress it, even if the data is already available in the desired compressed form (for example, in a WIM file from which an image has been exported using wimlib_export_image()). More...
 
#define WIMLIB_WRITE_FLAG_FSYNC   0x00000020
 Immediately before closing the WIM file, sync its data to disk. More...
 
#define WIMLIB_WRITE_FLAG_REBUILD   0x00000040
 For wimlib_overwrite(): rebuild the entire WIM file, even if it otherwise could be updated in-place by appending to it. More...
 
#define WIMLIB_WRITE_FLAG_SOFT_DELETE   0x00000080
 For wimlib_overwrite(): override the default behavior after one or more calls to wimlib_delete_image(), which is to rebuild the entire WIM file. More...
 
#define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG   0x00000100
 For wimlib_overwrite(), allow overwriting the WIM file even if the readonly flag (WIM_HDR_FLAG_READONLY) is set in the WIM header. More...
 
#define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS   0x00000200
 Do not include file data already present in other WIMs. More...
 
#define WIMLIB_WRITE_FLAG_STREAMS_OK   0x00000400
 Deprecated; this flag should not be used outside of the library itself. More...
 
#define WIMLIB_WRITE_FLAG_RETAIN_GUID   0x00000800
 For wimlib_write(), retain the WIM's GUID instead of generating a new one. More...
 
#define WIMLIB_WRITE_FLAG_SOLID   0x00001000
 Concatenate files and compress them together, rather than compress each file independently. More...
 
#define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES   0x00002000
 Send WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM file. More...
 
#define WIMLIB_WRITE_FLAG_NO_SOLID_SORT   0x00004000
 Do not consider content similarity when arranging file data for solid compression. More...
 
#define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT   0x00008000
 Since wimlib v1.8.3 and for wimlib_overwrite() only: unsafely compact the WIM file in-place, without appending. More...
 

Functions

int wimlib_overwrite (WIMStruct *wim, int write_flags, unsigned num_threads)
 Commit a WIMStruct to disk, updating its backing file. More...
 
int wimlib_set_output_chunk_size (WIMStruct *wim, uint32_t chunk_size)
 Set a WIMStruct's output compression chunk size. More...
 
int wimlib_set_output_pack_chunk_size (WIMStruct *wim, uint32_t chunk_size)
 Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing solid resources. More...
 
int wimlib_set_output_compression_type (WIMStruct *wim, enum wimlib_compression_type ctype)
 Set a WIMStruct's output compression type. More...
 
int wimlib_set_output_pack_compression_type (WIMStruct *wim, enum wimlib_compression_type ctype)
 Similar to wimlib_set_output_compression_type(), but set the compression type for writing solid resources. More...
 
int wimlib_write (WIMStruct *wim, const wimlib_tchar *path, int image, int write_flags, unsigned num_threads)
 Persist a WIMStruct to a new on-disk WIM file. More...
 
int wimlib_write_to_fd (WIMStruct *wim, int fd, int image, int write_flags, unsigned num_threads)
 Same as wimlib_write(), but write the WIM directly to a file descriptor, which need not be seekable if the write is done in a special pipable WIM format by providing WIMLIB_WRITE_FLAG_PIPABLE in write_flags. More...
 

Detailed Description

Create or update an on-disk WIM file.

wimlib_write() creates a new on-disk WIM file, whereas wimlib_overwrite() updates an existing WIM file. See Basic WIM handling concepts for more information about the API design.

Macro Definition Documentation

◆ WIMLIB_WRITE_FLAG_CHECK_INTEGRITY

#define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY   0x00000001

Include an integrity table in the resulting WIM file.

For WIMStruct's created with wimlib_open_wim(), the default behavior is to include an integrity table if and only if one was present before. For WIMStruct's created with wimlib_create_new_wim(), the default behavior is to not include an integrity table.

◆ WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY

#define WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY   0x00000002

Do not include an integrity table in the resulting WIM file.

This is the default behavior, unless the WIMStruct was created by opening a WIM with an integrity table.

◆ WIMLIB_WRITE_FLAG_PIPABLE

#define WIMLIB_WRITE_FLAG_PIPABLE   0x00000004

Write the WIM as "pipable".

After writing a WIM with this flag specified, images from it can be applied directly from a pipe using wimlib_extract_image_from_pipe(). See the documentation for the –pipable option of wimcapture for more information. Beware: WIMs written with this flag will not be compatible with Microsoft's software.

For WIMStruct's created with wimlib_open_wim(), the default behavior is to write the WIM as pipable if and only if it was pipable before. For WIMStruct's created with wimlib_create_new_wim(), the default behavior is to write the WIM as non-pipable.

◆ WIMLIB_WRITE_FLAG_NOT_PIPABLE

#define WIMLIB_WRITE_FLAG_NOT_PIPABLE   0x00000008

Do not write the WIM as "pipable".

This is the default behavior, unless the WIMStruct was created by opening a pipable WIM.

◆ WIMLIB_WRITE_FLAG_RECOMPRESS

#define WIMLIB_WRITE_FLAG_RECOMPRESS   0x00000010

When writing data to the WIM file, recompress it, even if the data is already available in the desired compressed form (for example, in a WIM file from which an image has been exported using wimlib_export_image()).

WIMLIB_WRITE_FLAG_RECOMPRESS can be used to recompress with a higher compression ratio for the same compression type and chunk size. Simply using the default compression settings may suffice for this, especially if the WIM file was created using another program/library that may not use as sophisticated compression algorithms. Or, wimlib_set_default_compression_level() can be called beforehand to set an even higher compression level than the default.

If the WIM contains solid resources, then WIMLIB_WRITE_FLAG_RECOMPRESS can be used in combination with WIMLIB_WRITE_FLAG_SOLID to prevent any solid resources from being re-used. Otherwise, solid resources are re-used somewhat more liberally than normal compressed resources.

WIMLIB_WRITE_FLAG_RECOMPRESS does not cause recompression of data that would not otherwise be written. For example, a call to wimlib_overwrite() with WIMLIB_WRITE_FLAG_RECOMPRESS will not, by itself, cause already-existing data in the WIM file to be recompressed. To force the WIM file to be fully rebuilt and recompressed, combine WIMLIB_WRITE_FLAG_RECOMPRESS with WIMLIB_WRITE_FLAG_REBUILD.

◆ WIMLIB_WRITE_FLAG_FSYNC

#define WIMLIB_WRITE_FLAG_FSYNC   0x00000020

Immediately before closing the WIM file, sync its data to disk.

This flag forces the function to wait until the data is safely on disk before returning success. Otherwise, modern operating systems tend to cache data for some time (in some cases, 30+ seconds) before actually writing it to disk, even after reporting to the application that the writes have succeeded.

wimlib_overwrite() will set this flag automatically if it decides to overwrite the WIM file via a temporary file instead of in-place. This is necessary on POSIX systems; it will, for example, avoid problems with delayed allocation on ext4.

◆ WIMLIB_WRITE_FLAG_REBUILD

#define WIMLIB_WRITE_FLAG_REBUILD   0x00000040

For wimlib_overwrite(): rebuild the entire WIM file, even if it otherwise could be updated in-place by appending to it.

Any data that existed in the original WIM file but is not actually needed by any of the remaining images will not be included. This can free up space left over after previous in-place modifications to the WIM file.

This flag can be combined with WIMLIB_WRITE_FLAG_RECOMPRESS to force all data to be recompressed. Otherwise, compressed data is re-used if possible.

wimlib_write() ignores this flag.

◆ WIMLIB_WRITE_FLAG_SOFT_DELETE

#define WIMLIB_WRITE_FLAG_SOFT_DELETE   0x00000080

For wimlib_overwrite(): override the default behavior after one or more calls to wimlib_delete_image(), which is to rebuild the entire WIM file.

With this flag, only minimal changes to correctly remove the image from the WIM file will be taken. This can be much faster, but it will result in the WIM file getting larger rather than smaller.

wimlib_write() ignores this flag.

◆ WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG

#define WIMLIB_WRITE_FLAG_IGNORE_READONLY_FLAG   0x00000100

For wimlib_overwrite(), allow overwriting the WIM file even if the readonly flag (WIM_HDR_FLAG_READONLY) is set in the WIM header.

This can be used following a call to wimlib_set_wim_info() with the WIMLIB_CHANGE_READONLY_FLAG flag to actually set the readonly flag on the on-disk WIM file.

wimlib_write() ignores this flag.

◆ WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS

#define WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS   0x00000200

Do not include file data already present in other WIMs.

This flag can be used to write a "delta" WIM after the WIM files on which the delta is to be based were referenced with wimlib_reference_resource_files() or wimlib_reference_resources().

◆ WIMLIB_WRITE_FLAG_STREAMS_OK

#define WIMLIB_WRITE_FLAG_STREAMS_OK   0x00000400

Deprecated; this flag should not be used outside of the library itself.

◆ WIMLIB_WRITE_FLAG_RETAIN_GUID

#define WIMLIB_WRITE_FLAG_RETAIN_GUID   0x00000800

For wimlib_write(), retain the WIM's GUID instead of generating a new one.

wimlib_overwrite() sets this by default, since the WIM remains, logically, the same file.

◆ WIMLIB_WRITE_FLAG_SOLID

#define WIMLIB_WRITE_FLAG_SOLID   0x00001000

Concatenate files and compress them together, rather than compress each file independently.

This is also known as creating a "solid archive". This tends to produce a better compression ratio at the cost of much slower random access.

WIM files created with this flag are only compatible with wimlib v1.6.0 or later, WIMGAPI Windows 8 or later, and DISM Windows 8.1 or later. WIM files created with this flag use a different version number in their header (3584 instead of 68864) and are also called "ESD files".

Note that providing this flag does not affect the "append by default" behavior of wimlib_overwrite(). In other words, wimlib_overwrite() with just WIMLIB_WRITE_FLAG_SOLID can be used to append solid-compressed data to a WIM file that originally did not contain any solid-compressed data. But if you instead want to rebuild and recompress an entire WIM file in solid mode, then also provide WIMLIB_WRITE_FLAG_REBUILD and WIMLIB_WRITE_FLAG_RECOMPRESS.

Currently, new solid resources will, by default, be written using LZMS compression with 64 MiB (67108864 byte) chunks. Use wimlib_set_output_pack_compression_type() and/or wimlib_set_output_pack_chunk_size() to change this. This is independent of the WIM's main compression type and chunk size; you can have a WIM that nominally uses LZX compression and 32768 byte chunks but actually contains LZMS-compressed solid resources, for example. However, if including solid resources, I suggest that you set the WIM's main compression type to LZMS as well, either by creating the WIM with wimlib_create_new_wim(WIMLIB_COMPRESSION_TYPE_LZMS, ...) or by calling wimlib_set_output_compression_type(..., WIMLIB_COMPRESSION_TYPE_LZMS).

This flag will be set by default when writing or overwriting a WIM file that either already contains solid resources, or has had solid resources exported into it and the WIM's main compression type is LZMS.

◆ WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES

#define WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES   0x00002000

Send WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM file.

This is only needed in the unusual case that the library user needs to know exactly when wimlib has read each file for the last time.

◆ WIMLIB_WRITE_FLAG_NO_SOLID_SORT

#define WIMLIB_WRITE_FLAG_NO_SOLID_SORT   0x00004000

Do not consider content similarity when arranging file data for solid compression.

Providing this flag will typically worsen the compression ratio, so only provide this flag if you know what you are doing.

◆ WIMLIB_WRITE_FLAG_UNSAFE_COMPACT

#define WIMLIB_WRITE_FLAG_UNSAFE_COMPACT   0x00008000

Since wimlib v1.8.3 and for wimlib_overwrite() only: unsafely compact the WIM file in-place, without appending.

Existing resources are shifted down to fill holes and new resources are appended as needed. The WIM file is truncated to its final size, which may shrink the on-disk file. This operation cannot be safely interrupted. If the operation is interrupted, then the WIM file will be corrupted, and it may be impossible (or at least very difficult) to recover any data from it. Users of this flag are expected to know what they are doing and assume responsibility for any data corruption that may result.

If the WIM file cannot be compacted in-place because of its structure, its layout, or other requested write parameters, then wimlib_overwrite() fails with WIMLIB_ERR_COMPACTION_NOT_POSSIBLE, and the caller may wish to retry the operation without this flag.

Function Documentation

◆ wimlib_overwrite()

int wimlib_overwrite ( WIMStruct wim,
int  write_flags,
unsigned  num_threads 
)

Commit a WIMStruct to disk, updating its backing file.

There are several alternative ways in which changes may be committed:

  1. Full rebuild: write the updated WIM to a temporary file, then rename the temporary file to the original.
  2. Appending: append updates to the new original WIM file, then overwrite its header such that those changes become visible to new readers.
  3. Compaction: normally should not be used; see WIMLIB_WRITE_FLAG_UNSAFE_COMPACT for details.

Append mode is often much faster than a full rebuild, but it wastes some amount of space due to leaving "holes" in the WIM file. Because of the greater efficiency, wimlib_overwrite() normally defaults to append mode. However, WIMLIB_WRITE_FLAG_REBUILD can be used to explicitly request a full rebuild. In addition, if wimlib_delete_image() has been used on the WIMStruct, then the default mode switches to rebuild mode, and WIMLIB_WRITE_FLAG_SOFT_DELETE can be used to explicitly request append mode.

If this function completes successfully, then no more functions can be called on the WIMStruct other than wimlib_free(). If you need to continue using the WIM file, you must use wimlib_open_wim() to open a new WIMStruct for it.

Parameters
wimPointer to a WIMStruct to commit to its backing file.
write_flagsBitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG.
num_threadsThe number of threads to use for compressing data, or 0 to have the library automatically choose an appropriate number.
Returns
0 on success; a wimlib_error_code value on failure. This function may return most error codes returned by wimlib_write() as well as the following error codes:
Return values
WIMLIB_ERR_ALREADY_LOCKEDAnother process is currently modifying the WIM file.
WIMLIB_ERR_NO_FILENAMEwim is not backed by an on-disk file. In other words, it is a WIMStruct created by wimlib_create_new_wim() rather than wimlib_open_wim().
WIMLIB_ERR_RENAMEThe temporary file to which the WIM was written could not be renamed to the original file.
WIMLIB_ERR_WIM_IS_READONLYThe WIM file is considered read-only because of any of the reasons mentioned in the documentation for the WIMLIB_OPEN_FLAG_WRITE_ACCESS flag.

If a progress function is registered with wim, then it will receive the messages WIMLIB_PROGRESS_MSG_WRITE_STREAMS, WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, and WIMLIB_PROGRESS_MSG_WRITE_METADATA_END.

◆ wimlib_set_output_chunk_size()

int wimlib_set_output_chunk_size ( WIMStruct wim,
uint32_t  chunk_size 
)

Set a WIMStruct's output compression chunk size.

This is the compression chunk size that will be used for writing non-solid resources in subsequent calls to wimlib_write() or wimlib_overwrite(). A larger compression chunk size often results in a better compression ratio, but compression may be slower and the speed of random access to data may be reduced. In addition, some chunk sizes are not compatible with Microsoft software.

Parameters
wimThe WIMStruct for which to set the output chunk size.
chunk_sizeThe chunk size (in bytes) to set. The valid chunk sizes are dependent on the compression type. See the documentation for each wimlib_compression_type constant for more information. As a special case, if chunk_size is specified as 0, then the chunk size will be reset to the default for the currently selected output compression type.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INVALID_CHUNK_SIZEchunk_size was not 0 or a supported chunk size for the currently selected output compression type.

◆ wimlib_set_output_pack_chunk_size()

int wimlib_set_output_pack_chunk_size ( WIMStruct wim,
uint32_t  chunk_size 
)

Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing solid resources.

◆ wimlib_set_output_compression_type()

int wimlib_set_output_compression_type ( WIMStruct wim,
enum wimlib_compression_type  ctype 
)

Set a WIMStruct's output compression type.

This is the compression type that will be used for writing non-solid resources in subsequent calls to wimlib_write() or wimlib_overwrite().

Parameters
wimThe WIMStruct for which to set the output compression type.
ctypeThe compression type to set. If this compression type is incompatible with the current output chunk size, then the output chunk size will be reset to the default for the new compression type.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_INVALID_COMPRESSION_TYPEctype did not specify a valid compression type.

◆ wimlib_set_output_pack_compression_type()

int wimlib_set_output_pack_compression_type ( WIMStruct wim,
enum wimlib_compression_type  ctype 
)

Similar to wimlib_set_output_compression_type(), but set the compression type for writing solid resources.

This cannot be WIMLIB_COMPRESSION_TYPE_NONE.

◆ wimlib_write()

int wimlib_write ( WIMStruct wim,
const wimlib_tchar path,
int  image,
int  write_flags,
unsigned  num_threads 
)

Persist a WIMStruct to a new on-disk WIM file.

This brings in file data from any external locations, such as directory trees or NTFS volumes scanned with wimlib_add_image(), or other WIM files via wimlib_export_image(), and incorporates it into a new on-disk WIM file.

By default, the new WIM file is written as stand-alone. Using the WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS flag, a "delta" WIM can be written instead. However, this function cannot directly write a "split" WIM; use wimlib_split() for that.

Parameters
wimPointer to the WIMStruct being persisted.
pathThe path to the on-disk file to write.
imageNormally, specify WIMLIB_ALL_IMAGES here. This indicates that all images are to be included in the new on-disk WIM file. If for some reason you only want to include a single image, specify the 1-based index of that image instead.
write_flagsBitwise OR of flags prefixed with WIMLIB_WRITE_FLAG.
num_threadsThe number of threads to use for compressing data, or 0 to have the library automatically choose an appropriate number.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTEDA file that had previously been scanned for inclusion in the WIM was concurrently modified.
WIMLIB_ERR_INVALID_IMAGEimage did not exist in wim.
WIMLIB_ERR_INVALID_RESOURCE_HASHA file, stored in another WIM, which needed to be written was corrupt.
WIMLIB_ERR_INVALID_PARAMpath was not a nonempty string, or invalid flags were passed.
WIMLIB_ERR_OPENFailed to open the output WIM file for writing, or failed to open a file whose data needed to be included in the WIM.
WIMLIB_ERR_READFailed to read data that needed to be included in the WIM.
WIMLIB_ERR_RESOURCE_NOT_FOUNDA file data blob that needed to be written could not be found in the blob lookup table of wim. See Creating and handling non-standalone WIMs.
WIMLIB_ERR_WRITEAn error occurred when trying to write data to the new WIM file.

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 data from a WIM file.

If a progress function is registered with wim, then it will receive the messages WIMLIB_PROGRESS_MSG_WRITE_STREAMS, WIMLIB_PROGRESS_MSG_WRITE_METADATA_BEGIN, and WIMLIB_PROGRESS_MSG_WRITE_METADATA_END.

◆ wimlib_write_to_fd()

int wimlib_write_to_fd ( WIMStruct wim,
int  fd,
int  image,
int  write_flags,
unsigned  num_threads 
)

Same as wimlib_write(), but write the WIM directly to a file descriptor, which need not be seekable if the write is done in a special pipable WIM format by providing WIMLIB_WRITE_FLAG_PIPABLE in write_flags.

This can, for example, allow capturing a WIM image and streaming it over the network. See Pipable WIMs for more information about pipable WIMs.

The file descriptor fd will not be closed when the write is complete; the calling code is responsible for this.

Returns
0 on success; a wimlib_error_code value on failure. The possible error codes include those that can be returned by wimlib_write() as well as the following:
Return values
WIMLIB_ERR_INVALID_PARAMfd was not seekable, but WIMLIB_WRITE_FLAG_PIPABLE was not specified in write_flags.