|
wimlib
|
Macros | |
| #define | WIMLIB_WRITE_FLAG_CHECK_INTEGRITY 0x00000001 |
| Include an integrity table in the resulting WIM file. | |
| #define | WIMLIB_WRITE_FLAG_NO_CHECK_INTEGRITY 0x00000002 |
| Do not include an integrity table in the resulting WIM file. | |
| #define | WIMLIB_WRITE_FLAG_PIPABLE 0x00000004 |
| Write the WIM as "pipable". | |
| #define | WIMLIB_WRITE_FLAG_NOT_PIPABLE 0x00000008 |
| Do not write the WIM as "pipable". | |
| #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()). | |
| #define | WIMLIB_WRITE_FLAG_FSYNC 0x00000020 |
| Immediately before closing the WIM file, sync its data to disk. | |
| #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. | |
| #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. | |
| #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. | |
| #define | WIMLIB_WRITE_FLAG_SKIP_EXTERNAL_WIMS 0x00000200 |
| Do not include file data already present in other WIMs. | |
| #define | WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 |
| Deprecated; this flag should not be used outside of the library itself. | |
| #define | WIMLIB_WRITE_FLAG_RETAIN_GUID 0x00000800 |
| For wimlib_write(), retain the WIM's GUID instead of generating a new one. | |
| #define | WIMLIB_WRITE_FLAG_SOLID 0x00001000 |
| Concatenate files and compress them together, rather than compress each file independently. | |
| #define | WIMLIB_WRITE_FLAG_SEND_DONE_WITH_FILE_MESSAGES 0x00002000 |
| Send WIMLIB_PROGRESS_MSG_DONE_WITH_FILE messages while writing the WIM file. | |
| #define | WIMLIB_WRITE_FLAG_NO_SOLID_SORT 0x00004000 |
| Do not consider content similarity when arranging file data for solid compression. | |
| #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. | |
Functions | |
| WIMLIBAPI int | wimlib_overwrite (WIMStruct *wim, int write_flags, unsigned num_threads) |
| Commit a WIMStruct to disk, updating its backing file. | |
| WIMLIBAPI int | wimlib_set_output_chunk_size (WIMStruct *wim, uint32_t chunk_size) |
| Set a WIMStruct's output compression chunk size. | |
| WIMLIBAPI 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. | |
| WIMLIBAPI int | wimlib_set_output_compression_type (WIMStruct *wim, enum wimlib_compression_type ctype) |
| Set a WIMStruct's output compression type. | |
| WIMLIBAPI 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. | |
| WIMLIBAPI 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. | |
| WIMLIBAPI 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. | |
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.
| #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.
| #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.
| #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.
| #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.
| #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.
| #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.
| #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.
| #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.
| #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.
| #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().
| #define WIMLIB_WRITE_FLAG_STREAMS_OK 0x00000400 |
Deprecated; this flag should not be used outside of the library itself.
| #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.
| #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.
| #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.
| #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.
| #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.
Commit a WIMStruct to disk, updating its backing file.
There are several alternative ways in which changes may be committed:
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.
| wim | Pointer to a WIMStruct to commit to its backing file. |
| write_flags | Bitwise OR of relevant flags prefixed with WIMLIB_WRITE_FLAG. |
| num_threads | The number of threads to use for compressing data, or 0 to have the library automatically choose an appropriate number. |
| WIMLIB_ERR_ALREADY_LOCKED | Another process is currently modifying the WIM file. |
| WIMLIB_ERR_NO_FILENAME | wim 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_RENAME | The temporary file to which the WIM was written could not be renamed to the original file. |
| WIMLIB_ERR_WIM_IS_READONLY | The 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.
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.
| wim | The WIMStruct for which to set the output chunk size. |
| chunk_size | The 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. |
| WIMLIB_ERR_INVALID_CHUNK_SIZE | chunk_size was not 0 or a supported chunk size for the currently selected output compression type. |
Similar to wimlib_set_output_chunk_size(), but set the chunk size for writing solid resources.
| WIMLIBAPI 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().
| wim | The WIMStruct for which to set the output compression type. |
| ctype | The 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. |
| WIMLIB_ERR_INVALID_COMPRESSION_TYPE | ctype did not specify a valid compression type. |
| WIMLIBAPI 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.
| WIMLIBAPI 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.
| wim | Pointer to the WIMStruct being persisted. |
| path | The path to the on-disk file to write. |
| image | Normally, 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_flags | Bitwise OR of flags prefixed with WIMLIB_WRITE_FLAG. |
| num_threads | The number of threads to use for compressing data, or 0 to have the library automatically choose an appropriate number. |
| WIMLIB_ERR_CONCURRENT_MODIFICATION_DETECTED | A file that had previously been scanned for inclusion in the WIM was concurrently modified. |
| WIMLIB_ERR_INVALID_IMAGE | image did not exist in wim. |
| WIMLIB_ERR_INVALID_RESOURCE_HASH | A file, stored in another WIM, which needed to be written was corrupt. |
| WIMLIB_ERR_INVALID_PARAM | path was not a nonempty string, or invalid flags were passed. |
| WIMLIB_ERR_OPEN | Failed 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_READ | Failed to read data that needed to be included in the WIM. |
| WIMLIB_ERR_RESOURCE_NOT_FOUND | A 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_WRITE | An 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.
| WIMLIBAPI 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.
| WIMLIB_ERR_INVALID_PARAM | fd was not seekable, but WIMLIB_WRITE_FLAG_PIPABLE was not specified in write_flags. |
1.10.0