wimlib.h File Reference

#include <stdio.h>
#include <stddef.h>
#include <stdbool.h>

Go to the source code of this file.

Defines
#define	WIMLIB_MOUNT_FLAG_READWRITE   0x1
	Mount the WIM read-write.
#define	WIMLIB_MOUNT_FLAG_DEBUG   0x2
	For debugging only.
#define	WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY   0x1
	Include an integrity table in the new WIM being written during the unmount.
#define	WIMLIB_UNMOUNT_FLAG_COMMIT   0x2
	Unless this flag is given, changes to a mounted WIM are discarded.
#define	WIMLIB_WRITE_FLAG_CHECK_INTEGRITY   0x1
	Include an integrity table in the new WIM file.
#define	WIMLIB_WRITE_FLAG_SHOW_PROGRESS   0x2
	Print progress information when writing the integrity table.
#define	WIMLIB_ADD_IMAGE_FLAG_BOOT   0x1
	Mark the image being added as the bootable image of the WIM.
#define	WIMLIB_EXPORT_FLAG_BOOT   0x1
	See documentation for wimlib_export_image().
#define	WIMLIB_OPEN_FLAG_CHECK_INTEGRITY   0x1
	Verify the integrity of the WIM if an integrity table is present.
#define	WIMLIB_OPEN_FLAG_SHOW_PROGRESS   0x2
	Print progress information when verifying integrity table.
#define	WIM_NO_IMAGE   0
	Used to indicate that no WIM image is currently selected.
#define	WIM_ALL_IMAGES   (-1)
	Used to specify all images in the WIM.
Typedefs
typedef struct WIMStruct	WIMStruct
	Opaque structure that represents a WIM file.
Enumerations
enum	wim_link_type { WIM_LINK_TYPE_HARD = 0, WIM_LINK_TYPE_SYMBOLIC = 1, WIM_LINK_TYPE_NONE = 2 }
	Specifies the way in which identical files are linked when extracting image(s) from the WIM. More...
enum	wim_compression_type { WIM_COMPRESSION_TYPE_INVALID = -1, WIM_COMPRESSION_TYPE_NONE = 0, WIM_COMPRESSION_TYPE_LZX = 1, WIM_COMPRESSION_TYPE_XPRESS = 2 }
	Specifies the compression type of a WIM file. More...
enum	wimlib_error_code {   WIMLIB_ERR_SUCCESS = 0, WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE, WIMLIB_ERR_DECOMPRESSION, WIMLIB_ERR_DELETE_STAGING_DIR,   WIMLIB_ERR_FORK, WIMLIB_ERR_FUSE, WIMLIB_ERR_FUSERMOUNT, WIMLIB_ERR_IMAGE_COUNT,   WIMLIB_ERR_IMAGE_NAME_COLLISION, WIMLIB_ERR_INTEGRITY, WIMLIB_ERR_INVALID_CHUNK_SIZE, WIMLIB_ERR_INVALID_COMPRESSION_TYPE,   WIMLIB_ERR_INVALID_DENTRY, WIMLIB_ERR_INVALID_HEADER_SIZE, WIMLIB_ERR_INVALID_IMAGE, WIMLIB_ERR_INVALID_INTEGRITY_TABLE,   WIMLIB_ERR_INVALID_PARAM, WIMLIB_ERR_INVALID_RESOURCE_SIZE, WIMLIB_ERR_LINK, WIMLIB_ERR_MKDIR,   WIMLIB_ERR_MQUEUE, WIMLIB_ERR_NOMEM, WIMLIB_ERR_NOTDIR, WIMLIB_ERR_NOT_A_WIM_FILE,   WIMLIB_ERR_NO_FILENAME, WIMLIB_ERR_OPEN, WIMLIB_ERR_OPENDIR, WIMLIB_ERR_READ,   WIMLIB_ERR_RENAME, WIMLIB_ERR_SPLIT, WIMLIB_ERR_STAT, WIMLIB_ERR_TIMEOUT,   WIMLIB_ERR_UNKNOWN_VERSION, WIMLIB_ERR_UNSUPPORTED, WIMLIB_ERR_WRITE, WIMLIB_ERR_XML }
	Possible values of the error code returned by many functions in wimlib. More...
Functions
int	wimlib_add_image (WIMStruct *wim, const char *dir, const char *name, const char *description, const char *flags_element, int flags)
	Adds an image to a WIM file from a directory tree on disk.
int	wimlib_create_new_wim (int ctype, WIMStruct **wim_ret)
	Creates a WIMStruct for a new WIM file.
int	wimlib_delete_image (WIMStruct *wim, int image)
	Deletes an image, or all images, from a WIM file.
int	wimlib_export_image (WIMStruct *src_wim, int src_image, WIMStruct *dest_wim, const char *dest_name, const char *dest_description, int flags)
	Copies an image, or all the images, from a WIM file, into another WIM file.
int	wimlib_extract_image (WIMStruct *wim, int image)
	Extracts an image, or all images, from a WIM file.
int	wimlib_extract_xml_data (WIMStruct *wim, FILE *fp)
	Extracts the XML data for a WIM file to a file stream.
void	wimlib_free (WIMStruct *wim)
	Frees all memory allocated for a WIMStruct and closes all files associated with it.
int	wimlib_get_boot_idx (const WIMStruct *wim)
	Finds which image in a WIM is bootable.
int	wimlib_get_compression_type (const WIMStruct *wim)
	Gets the compression type used in the WIM.
const char *	wimlib_get_compression_type_string (int ctype)
	Converts a compression type enumeration value into a string.
const char *	wimlib_get_error_string (enum wimlib_error_code code)
	Converts an error code into a string describing it.
const char *	wimlib_get_image_description (const WIMStruct *wim, int image)
	Returns the description of the specified image.
const char *	wimlib_get_image_name (const WIMStruct *wim, int image)
	Returns the name of the specified image.
int	wimlib_get_num_images (const WIMStruct *wim)
	Gets the number of images contained in the WIM.
bool	wimlib_has_integrity_table (const WIMStruct *wim)
	Returns true if the WIM has an integrity table.
bool	wimlib_image_name_in_use (const WIMStruct *wim, const char *name)
	Determines if an image name is already used by some image in the WIM.
int	wimlib_mount (WIMStruct *wim, int image, const char *dir, int flags)
	Mounts an image in a WIM file on a directory read-only or read-write.
int	wimlib_open_wim (const char *wim_file, int flags, WIMStruct **wim_ret)
	Opens a WIM file and creates a WIMStruct for it.
int	wimlib_overwrite (WIMStruct *wim, int flags)
	Overwrites the file that the WIM was originally read from, with changes made.
int	wimlib_overwrite_xml_and_header (WIMStruct *wim, int flags)
	Updates the header and XML data of the WIM file, without the need to write out the entire WIM to a temporary file as in wimlib_write().
void	wimlib_print_available_images (const WIMStruct *wim, int image)
	Prints information about one image, or all images, contained in a WIM.
int	wimlib_print_files (WIMStruct *wim, int image)
	Prints the full paths to all files contained in an image, or all images, in a WIM file.
void	wimlib_print_header (const WIMStruct *wim)
	Prints detailed information from the header of a WIM file.
void	wimlib_print_lookup_table (WIMStruct *wim)
	Prints the lookup table of a WIM file.
int	wimlib_print_metadata (WIMStruct *wim, int image)
	Prints the metadata of the specified image in a WIM file.
void	wimlib_print_wim_information (const WIMStruct *wim)
	Prints some basic information about a WIM file.
int	wimlib_resolve_image (WIMStruct *wim, const char *image_name_or_num)
	Translates a string specifying the name or number of an image in the WIM into the number of the image.
int	wimlib_set_boot_idx (WIMStruct *wim, int boot_idx)
	Sets which image in the WIM is marked as bootable.
int	wimlib_set_image_descripton (WIMStruct *wim, int image, const char *description)
	Changes the description of an image in the WIM.
int	wimlib_set_image_name (WIMStruct *wim, int image, const char *name)
	Changes the name of an image in the WIM.
int	wimlib_set_link_type (WIMStruct *wim, int link_type)
	Sets the link type to use when extracting files from a WIM.
int	wimlib_set_memory_allocator (void *(*malloc_func)(size_t), void(*free_func)(void *), void *(*realloc_func)(void *, size_t))
	Set the functions that wimlib uses to allocate and free memory.
int	wimlib_set_print_errors (bool show_messages)
	Sets whether wimlib is to print error messages to stderr when a function fails or not.
void	wimlib_set_verbose (WIMStruct *wim, bool verbose)
	Sets whether wimlib is to be verbose when extracting files from a WIM or when creating an image from a directory (i.e.
int	wimlib_set_output_dir (WIMStruct *wim, const char *dir)
	Sets and creates the directory to which files are to be extracted when extracting files from the WIM.
int	wimlib_unmount (const char *dir, int flags)
	Unmounts a WIM image that was mounted using wimlib_mount().
int	wimlib_write (WIMStruct *wim, const char *path, int image, int flags)
	Writes the WIM to a file.

---

Define Documentation

#define WIM_ALL_IMAGES   (-1)

Used to specify all images in the WIM.

#define WIM_NO_IMAGE   0

Used to indicate that no WIM image is currently selected.

#define WIMLIB_ADD_IMAGE_FLAG_BOOT   0x1

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

#define WIMLIB_EXPORT_FLAG_BOOT   0x1

See documentation for wimlib_export_image().

#define WIMLIB_MOUNT_FLAG_DEBUG   0x2

For debugging only.

(This passes the -d flag to fuse_main()).

#define WIMLIB_MOUNT_FLAG_READWRITE   0x1

Mount the WIM read-write.

#define WIMLIB_OPEN_FLAG_CHECK_INTEGRITY   0x1

Verify the integrity of the WIM if an integrity table is present.

#define WIMLIB_OPEN_FLAG_SHOW_PROGRESS   0x2

Print progress information when verifying integrity table.

#define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY   0x1

Include an integrity table in the new WIM being written during the unmount.

Ignored for read-only mounts.

#define WIMLIB_UNMOUNT_FLAG_COMMIT   0x2

Unless this flag is given, changes to a mounted WIM are discarded.

Ignored for read-only mounts.

#define WIMLIB_WRITE_FLAG_CHECK_INTEGRITY   0x1

Include an integrity table in the new WIM file.

#define WIMLIB_WRITE_FLAG_SHOW_PROGRESS   0x2

Print progress information when writing the integrity table.

---

Typedef Documentation

typedef struct WIMStruct WIMStruct

Opaque structure that represents a WIM file.

---

Enumeration Type Documentation

enum wim_compression_type

Specifies the compression type of a WIM file.

Enumerator:

WIM_COMPRESSION_TYPE_INVALID	An invalid compression type.
WIM_COMPRESSION_TYPE_NONE	The WIM does not include any compressed resources.
WIM_COMPRESSION_TYPE_LZX	Compressed resources in the WIM use LZX compression.
WIM_COMPRESSION_TYPE_XPRESS	Compressed resources in the WIM use XPRESS compression.

enum wim_link_type

Specifies the way in which identical files are linked when extracting image(s) from the WIM.

Enumerator:

WIM_LINK_TYPE_HARD	Hard link identical files when extracting files from the WIM.
WIM_LINK_TYPE_SYMBOLIC	Symbolic link identical files when extracting files from the WIM.
WIM_LINK_TYPE_NONE	Do not create links when extracting identical files from the WIM (default).

enum wimlib_error_code

Possible values of the error code returned by many functions in wimlib.

See the documentation for each wimlib function to see specifically what error codes can be returned by a given function, and what they mean.

Enumerator:

WIMLIB_ERR_SUCCESS
WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE
WIMLIB_ERR_DECOMPRESSION
WIMLIB_ERR_DELETE_STAGING_DIR
WIMLIB_ERR_FORK
WIMLIB_ERR_FUSE
WIMLIB_ERR_FUSERMOUNT
WIMLIB_ERR_IMAGE_COUNT
WIMLIB_ERR_IMAGE_NAME_COLLISION
WIMLIB_ERR_INTEGRITY
WIMLIB_ERR_INVALID_CHUNK_SIZE
WIMLIB_ERR_INVALID_COMPRESSION_TYPE
WIMLIB_ERR_INVALID_DENTRY
WIMLIB_ERR_INVALID_HEADER_SIZE
WIMLIB_ERR_INVALID_IMAGE
WIMLIB_ERR_INVALID_INTEGRITY_TABLE
WIMLIB_ERR_INVALID_PARAM
WIMLIB_ERR_INVALID_RESOURCE_SIZE
WIMLIB_ERR_LINK
WIMLIB_ERR_MKDIR
WIMLIB_ERR_MQUEUE
WIMLIB_ERR_NOMEM
WIMLIB_ERR_NOTDIR
WIMLIB_ERR_NOT_A_WIM_FILE
WIMLIB_ERR_NO_FILENAME
WIMLIB_ERR_OPEN
WIMLIB_ERR_OPENDIR
WIMLIB_ERR_READ
WIMLIB_ERR_RENAME
WIMLIB_ERR_SPLIT
WIMLIB_ERR_STAT
WIMLIB_ERR_TIMEOUT
WIMLIB_ERR_UNKNOWN_VERSION
WIMLIB_ERR_UNSUPPORTED
WIMLIB_ERR_WRITE
WIMLIB_ERR_XML

---

Function Documentation

int wimlib_add_image	(	WIMStruct *	wim,
		const char *	dir,
		const char *	name,
		const char *	description,
		const char *	flags_element,
		int	flags
	)

Adds an image to a WIM file from a directory tree on disk.

The directory tree is read immediately for the purpose of constructing a directory entry tree in-memory. Also, all files are read to calculate their SHA1 message digests. However, because the directory tree may contain a very large amount of data, the files themselves are not read into memory permanently, and instead references to their paths saved. This means that the directory tree must not be modified, other than by adding entirely new files or directories, before executing a call to wimlib_write() or wimlib_overwrite(). Otherwise, wimlib_write() may fail or incorrect files may be included in the WIM written by wimlib_write().

Parameters:

wim	Pointer to the WIMStruct for a WIM file to which the image will be added.
dir	A path to a directory in the outside filesystem. It will become the root directory for the WIM image.
name	The name to give the image. This must be non-NULL.
description	The description to give the image. This parameter may be left NULL, in which case no description is given to the image.
flags_element	What to put in the <FLAGS> element for the image's XML data. This parameter may be left NULL, in which case no <FLAGS> element is given to the image.
flags	If set to WIMLIB_ADD_IMAGE_FLAG_BOOT, change the image in wim marked as bootable to the one being added. Otherwise, leave the boot index unchanged.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_IMAGE_NAME_COLLISION	There is already an image named name in w.
WIMLIB_ERR_INVALID_PARAM	dir was NULL, name was NULL, or name was the empty string.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_NOTDIR	dir is not a directory.
WIMLIB_ERR_OPEN	Failed to open a file or directory in the directory tree rooted at dir.
WIMLIB_ERR_READ	Failed to read a file in the directory tree rooted at dir.
WIMLIB_ERR_STAT	Failed obtain the metadata for a file or directory in the directory tree rooted at dir.

int wimlib_create_new_wim	(	int	ctype,
		WIMStruct **	wim_ret
	)

Creates a WIMStruct for a new WIM file.

Parameters:

ctype	The type of compression to be used in the new WIM file. Must be WIM_COMPRESSION_TYPE_NONE, WIM_COMPRESSION_TYPE_LZX, or WIM_COMPRESSION_TYPE_XPRESS.
wim_ret	On success, a pointer to an opaque WIMStruct for the new WIM file is written to the memory location pointed to by this paramater. The WIMStruct must be freed using using FREE() when finished with it.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_INVALID_COMPRESSION_TYPE	ctype was not WIM_COMPRESSION_TYPE_NONE, WIM_COMPRESSION_TYPE_LZX, or WIM_COMPRESSION_TYPE_XPRESS.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.

int wimlib_delete_image	(	WIMStruct *	wim,
		int	image
	)

Deletes an image, or all images, from a WIM file.

All file resources referenced by the image(s) being deleted are removed from the WIM if they are not referenced by any other images in the WIM.

Parameters:

wim	Pointer to the WIMStruct for the WIM file that contains the image(s) being deleted.
image	The number of the image to delete, or WIM_ALL_IMAGES to delete all images.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_DECOMPRESSION	Could not decompress the metadata resource for image.
WIMLIB_ERR_INVALID_DENTRY	A directory entry in the metadata resource for image in the WIM is invalid.
WIMLIB_ERR_INVALID_IMAGE	image does not exist in the WIM and is not WIM_ALL_IMAGES.
WIMLIB_ERR_INVALID_RESOURCE_SIZE	The metadata resource for image in the WIM is invalid.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_READ	Could not read the metadata resource for image from the WIM.

int wimlib_export_image	(	WIMStruct *	src_wim,
		int	src_image,
		WIMStruct *	dest_wim,
		const char *	dest_name,
		const char *	dest_description,
		int	flags
	)

Copies an image, or all the images, from a WIM file, into another WIM file.

Parameters:

src_wim	Pointer to the WIMStruct for a WIM file that contains the image(s) being exported.
src_image	The image to export from src_wim. Can be the number of an image, or WIM_ALL_IMAGES to export all images.
dest_wim	Pointer to the WIMStruct for a WIM filethat will receive the images being exported.
dest_name	The name to give the exported image in the new WIM file. If left NULL, the name from src_wim is used. This parameter must be left NULL if src_image is WIM_ALL_IMAGES and src_wim contains more than one image; in that case, the names are all taken from the src_wim.
dest_description	The description to give the exported image in the new WIM file. If left NULL, the description from the src_wim is used. This parameter must be left NULL if src_image is WIM_ALL_IMAGES and src_wim contains more than one image; in that case, the descriptions are all taken from src_wim.
flags	WIMLIB_EXPORT_FLAG_BOOT if the image being exported is to be made bootable, or 0 if which image is marked as bootable in the destination WIM is to be left unchanged. If src_image is WIM_ALL_IMAGES and there are multiple images in src_wim, specifying WIMLIB_EXPORT_FLAG_BOOT is valid only if one of the exported images is currently marked as bootable in src_wim; if that is the case, then that image is marked as bootable in the destination WIM.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_DECOMPRESSION	Could not decompress the metadata resource for src_image in src_wim
WIMLIB_ERR_IMAGE_NAME_COLLISION	One or more of the names being given to an exported image was already in use in the destination WIM.
WIMLIB_ERR_INVALID_DENTRY	A directory entry in the metadata resource for src_image in src_wim is invalid.
WIMLIB_ERR_INVALID_IMAGE	src_image does not exist in src_wim.
WIMLIB_ERR_INVALID_PARAM	WIMLIB_EXPORT_FLAG_BOOT was specified in flags, src_image was WIM_ALL_IMAGES, src_wim contains multiple images, and no images in src_wim are marked as bootable; or dest_name and/or dest_description were non-NULL, src_image was WIM_ALL_IMAGES, and src_wim contains multiple images.
WIMLIB_ERR_INVALID_RESOURCE_SIZE	The metadata resource for src_image in src_wim is invalid.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_READ	Could not read the metadata resource for src_image from src_wim.

int wimlib_extract_image	(	WIMStruct *	wim,
		int	image
	)

Extracts an image, or all images, from a WIM file.

The output directory must have been previously set with wimlib_set_output_dir().

The link type used for extracted files is that specified by a previous call to wimlib_set_link_type(), or WIM_LINK_TYPE_NONE by default.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image	The image to extract. Can be the number of an image, or WIM_ALL_IMAGES to specify that all images are to be extracted.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_DECOMPRESSION	Could not decompress a resource (file or metadata) for image in wim.
WIMLIB_ERR_INVALID_DENTRY	A directory entry in the metadata resource for image in wim is invalid.
WIMLIB_ERR_INVALID_RESOURCE_SIZE	A resource (file or metadata) for image in wim is invalid.
WIMLIB_ERR_LINK	Failed to create a symbolic link or a hard link.
WIMLIB_ERR_MKDIR	Failed create a needed directory.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_NOTDIR	wimlib_set_output_dir() has not been successfully called on wim.
WIMLIB_ERR_OPEN	Could not open one of the files being extracted for writing.
WIMLIB_ERR_READ	A unexpected end-of-file or read error occurred when trying to read data from the WIM file associated with wim.
WIMLIB_ERR_WRITE	Failed to write a file being extracted.

int wimlib_extract_xml_data	(	WIMStruct *	wim,
		FILE *	fp
	)

Extracts the XML data for a WIM file to a file stream.

Every WIM file includes a string of XML that describes the images contained in the WIM.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
fp	stdout, or a FILE* opened for writing, to extract the data to.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_WRITE

Failed to completely write the XML data to fp.

void wimlib_free

(

WIMStruct *

wim

)

Frees all memory allocated for a WIMStruct and closes all files associated with it.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.

Returns:

This function has no return value.

int wimlib_get_boot_idx

(

const WIMStruct *

wim

)

Finds which image in a WIM is bootable.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.

Returns:

0 if no image is marked as bootable, or the number of the image marked as bootable (numbered starting at 1).

int wimlib_get_compression_type

(

const WIMStruct *

wim

)

Gets the compression type used in the WIM.

Parameters:

wim	Pointer to the WIMStruct for a WIM file

Returns:

WIM_COMPRESSION_TYPE_NONE, WIM_COMPRESSION_TYPE_LZX, or WIM_COMPRESSION_TYPE_XPRESS.

const char* wimlib_get_compression_type_string

(

int

ctype

)

Converts a compression type enumeration value into a string.

Parameters:

ctype

WIM_COMPRESSION_TYPE_NONE, WIM_COMPRESSION_TYPE_LZX, WIM_COMPRESSION_TYPE_XPRESS, or another value.

Returns:

A statically allocated string: "None", "LZX", "XPRESS", or "Invalid", respectively.

const char* wimlib_get_error_string

(

enum wimlib_error_code

code

)

Converts an error code into a string describing it.

Parameters:

code	The error code returned by one of wimlib's functions.

Returns:

Pointer to a statically allocated string describing the error code, or NULL if the error code is not valid.

const char* wimlib_get_image_description	(	const WIMStruct *	wim,
		int	image
	)

Returns the description of the specified image.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image	The number of the image, numbered starting at 1.

Returns:

The description of the image, or NULL if there is no such image, or NULL if the specified image has no description.

const char* wimlib_get_image_name	(	const WIMStruct *	wim,
		int	image
	)

Returns the name of the specified image.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image	The number of the image, numbered starting at 1.

Returns:

The name of the image, or NULL if there is no such image.

int wimlib_get_num_images

(

const WIMStruct *

wim

)

Gets the number of images contained in the WIM.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.

Returns:

The number of images contained in the WIM file.

bool wimlib_has_integrity_table

(

const WIMStruct *

wim

)

Returns true if the WIM has an integrity table.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.

Returns:

true if the WIM has an integrity table; false otherwise.

bool wimlib_image_name_in_use	(	const WIMStruct *	wim,
		const char *	name
	)

Determines if an image name is already used by some image in the WIM.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
name	The name to check.

Returns:

true if there is already an image in wim named name; false if there is no image named name in wim.

int wimlib_mount	(	WIMStruct *	wim,
		int	image,
		const char *	dir,
		int	flags
	)

Mounts an image in a WIM file on a directory read-only or read-write.

A daemon will be forked to service the filesystem.

If the mount is read-write, modifications to the WIM are staged in a staging directory.

wimlib_mount() currently cannot be used with multiple WIMStruct's without intervening wimlib_unmount()s. If there was a way to have libfuse pass a pointer to user data to each FUSE callback, then this would be possible, but there doesn't seem to be a way to do this currently.

Parameters:

wim	Pointer to the WIMStruct for the WIM file to be mounted.
image	The number of the image to mount, numbered from 1. It must be an existing, single image.
dir	The path to an existing directory to mount the image on.
flags	Bitwise OR of the flags WIMLIB_MOUNT_FLAG_READWRITE or WIMLIB_MOUNT_FLAG_DEBUG. If WIMLIB_MOUNT_FLAG_READWRITE is not given, the WIM is mounted read-only.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_DECOMPRESSION	Could not decompress the metadata resource for image in wim.
WIMLIB_ERR_FUSE	A non-zero status was returned by fuse_main().
WIMLIB_ERR_INVALID_DENTRY	A directory entry in the metadata resource for image in wim is invalid.
WIMLIB_ERR_INVALID_IMAGE	image does not specify an existing, single image in wim.
WIMLIB_ERR_INVALID_RESOURCE_SIZE	The metadata resource for image in wim is invalid.
WIMLIB_ERR_MKDIR	WIMLIB_MOUNT_FLAG_READWRITE was specified in flags, but the staging directory could not be created.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_NOTDIR	Could not determine the current working directory.
WIMLIB_ERR_READ	An unexpected end-of-file or read error occurred when trying to read data from the WIM file associated with wim.

int wimlib_open_wim	(	const char *	wim_file,
		int	flags,
		WIMStruct **	wim_ret
	)

Opens a WIM file and creates a WIMStruct for it.

Parameters:

wim_file	The path to the WIM file to open.
flags	Bitwise OR of WIMLIB_OPEN_FLAG_CHECK_INTEGRITY and/or WIMLIB_OPEN_FLAG_SHOW_PROGRESS. If WIMLIB_OPEN_FLAG_CHECK_INTEGRITY is given, the integrity table of the WIM, if it exists, is checked, and the function will fail with an WIMLIB_ERR_INTEGRITY status if any of the computed SHA1 message digests of the WIM do not exactly match the corresponding message digests given in the integrity table. If WIMLIB_OPEN_FLAG_SHOW_PROGRESS is given, progress information will be shown if the integrity of the WIM is checked.
wim_ret	On success, a pointer to an opaque WIMStruct for the opened WIM file is written to the memory location pointed to by this parameter. The WIMStruct must be freed using using FREE() when finished with it.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_COMPRESSED_LOOKUP_TABLE	The lookup table of wim_file is compressed. Support for this can be added to wimlib if needed, but it appears to be the case that the lookup table is never compressed.
WIMLIB_ERR_IMAGE_COUNT	The number of metadata resources found in the WIM did not match the image count given in the WIM header, or the number of <IMAGE> elements in the XML data for the WIM did not match the image count given in the WIM header.
WIMLIB_ERR_INTEGRITY	WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in flags and wim_file contains an integrity table, but the SHA1 message digest for a chunk of the WIM does not match the corresponding message digest given in the integrity table.
WIMLIB_ERR_INVALID_CHUNK_SIZE	Resources in wim_file are compressed, but the chunk size is not 32768.
WIMLIB_ERR_INVALID_COMPRESSION_TYPE	The header of wim_file says that resources in the WIM are compressed, but the header flag indicating LZX or XPRESS compression is not set.
WIMLIB_ERR_INVALID_HEADER_SIZE	The length field of the WIM header is not 208.
WIMLIB_ERR_INVALID_INTEGRITY_TABLE	WIMLIB_OPEN_FLAG_CHECK_INTEGRITY was specified in flags and wim_file contains an integrity table, but the integrity table is invalid.
WIMLIB_ERR_NOMEM	Failed to allocated needed memory.
WIMLIB_ERR_NOT_A_WIM_FILE	wim_file does not begin with the expected magic characters.
WIMLIB_ERR_OPEN	Failed to open the file wim_file for reading.
WIMLIB_ERR_READ	An unexpected end-of-file or read error occurred when trying to read data from wim_file.
WIMLIB_ERR_SPLIT	wim_file is a split WIM. wimlib does not support this kind of WIM.
WIMLIB_ERR_UNKNOWN_VERSION	A number other than 0x10d00 is written in the version field of the WIM header of wim_file.
WIMLIB_ERR_XML	The XML data for wim_file is invalid.

int wimlib_overwrite	(	WIMStruct *	wim,
		int	flags
	)

Overwrites the file that the WIM was originally read from, with changes made.

The new WIM is written to a temporary file and then renamed to the original file after it is has been completely written. The temporary file currently is made in the same directory as the original WIM file.

Note that it is not possible for this function to delete the original file before having written the new file because it is very likely that file resources in the new WIM file need to be retrieved from the old WIM file.

After this function returns, wim must be freed using FREE(). Any further actions on wim before doing this are undefined.

Parameters:

wim	Pointer to the WIMStruct for the WIM file to write. There may have been in-memory changes made to it, which are then reflected in the output file.
flags	Bitwise OR of WIMLIB_WRITE_FLAG_CHECK_INTEGRITY and/or WIMLIB_WRITE_FLAG_SHOW_PROGRESS.

Returns:

0 on success; nonzero on error. This function may return any value returned by wimlib_write() as well as the following error codes:

Return values:

WIMLIB_ERR_NO_FILENAME	wim corresponds to a WIM created with wimlib_create_new_wim() rather than a WIM read with wimlib_open_wim().
WIMLIB_ERR_RENAME	The temporary file that the WIM was written to could not be renamed to the original filename of wim.

int wimlib_overwrite_xml_and_header	(	WIMStruct *	wim,
		int	flags
	)

Updates the header and XML data of the WIM file, without the need to write out the entire WIM to a temporary file as in wimlib_write().

This function must only be used if no files, directories, or images have been added, removed, or changed in the WIM. It must be used when only the boot index or the name or description of image(s) has been changed.

After this function returns, wim must be freed using FREE(). Any further actions on wim before doing this are undefined.

Parameters:

wim	Pointer to the WIMStruct for the WIM file to overwrite.
flags	Bitwise OR of WIMLIB_WRITE_FLAG_CHECK_INTEGRITY and/or WIMLIB_WRITE_FLAG_SHOW_PROGRESS.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_NO_FILENAME	wim corresponds to a WIM created with wimlib_create_new_wim() rather than a WIM read with wimlib_open_wim().
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_OPEN	The WIM file associated with wim could not be re-opened read-write.
WIMLIB_ERR_READ	WIMLIB_WRITE_FLAG_CHECK_INTEGRITY was specified in flags, but data from the WIM file associated with wim could not be read to compute the SHA1 message digests, or the old integrity table (if it existed) could not be read.
WIMLIB_ERR_WRITE	Failed to write the WIM header, the XML data, or the integrity table to the WIM file associated with wim.

void wimlib_print_available_images	(	const WIMStruct *	wim,
		int	image
	)

Prints information about one image, or all images, contained in a WIM.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image	The image about which to print information. Can be the number of an image, or WIM_ALL_IMAGES to print information about all images in the WIM.

Returns:

This function has no return value.

int wimlib_print_files	(	WIMStruct *	wim,
		int	image
	)

Prints the full paths to all files contained in an image, or all images, in a WIM file.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image	Which image to print files for. Can be the number of an image, or WIM_ALL_IMAGES to print the files contained in all images.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_DECOMPRESSION	The metadata resource for one of the specified images could not be decompressed.
WIMLIB_ERR_INVALID_DENTRY	A directory entry in the metadata resource for one of the specified images is invaled.
WIMLIB_ERR_INVALID_IMAGE	image does not specify a valid image in wim, and is not WIM_ALL_IMAGES.
WIMLIB_ERR_INVALID_RESOURCE_SIZE	The metadata resource for one of the specified images is invalid.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_READ	An unexpected read error or end-of-file occurred when reading the metadata resource for one of the specified images.

void wimlib_print_header

(

const WIMStruct *

wim

)

Prints detailed information from the header of a WIM file.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.

Returns:

This function has no return value.

void wimlib_print_lookup_table

(

WIMStruct *

wim

)

Prints the lookup table of a WIM file.

The lookup table maps SHA1 message digests, as found in the directory entry tree in the WIM file, to file resources in the WIM file. This table includes one entry for each unique file in the WIM, so it can be quite long. There is only one lookup table per WIM.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.

Returns:

This function has no return value.

int wimlib_print_metadata	(	WIMStruct *	wim,
		int	image
	)

Prints the metadata of the specified image in a WIM file.

The metadata consists of the security data as well as the directory entry tree, and each image has its own metadata.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image	Which image to print the metadata for. Can be the number of an image, or WIM_ALL_IMAGES to print the metadata for all images in the WIM.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_DECOMPRESSION	The metadata resource for one of the specified images could not be decompressed.
WIMLIB_ERR_INVALID_DENTRY	A directory entry in the metadata resource for one of the specified images is invaled.
WIMLIB_ERR_INVALID_IMAGE	image does not specify a valid image in wim, and is not WIM_ALL_IMAGES.
WIMLIB_ERR_INVALID_RESOURCE_SIZE	The metadata resource for one of the specified images is invalid.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_READ	An unexpected read error or end-of-file occurred when reading the metadata resource for one of the specified images.

void wimlib_print_wim_information

(

const WIMStruct *

wim

)

Prints some basic information about a WIM file.

All information printed by this function is also printed by wimlib_print_header(), but wimlib_print_wim_information() prints some of this information more concisely and in a more readable form.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.

Returns:

This function has no return value.

int wimlib_resolve_image	(	WIMStruct *	wim,
		const char *	image_name_or_num
	)

Translates a string specifying the name or number of an image in the WIM into the number of the image.

The images are numbered starting at 1.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image_name_or_num	A string specifying which image. If it begins with a number, it is taken to be a string specifying the image number. Otherwise, it is taken to be the name of an image, as specified in the XML data for the WIM file. It also may be the keyword "all", which will resolve to WIM_ALL_IMAGES.

Returns:

If the string resolved to a single existing image, the number of that image, counting starting at 1, is returned. If the keyword "all" was specified, WIM_ALL_IMAGES is returned. Otherwise, WIM_NO_IMAGE is returned.

int wimlib_set_boot_idx	(	WIMStruct *	wim,
		int	boot_idx
	)

Sets which image in the WIM is marked as bootable.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
boot_idx	The number of the image to mark as bootable, or 0 to mark no image as bootable.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_INVALID_IMAGE

boot_idx does not specify an existing image in wim, and it was not 0.

int wimlib_set_image_descripton	(	WIMStruct *	wim,
		int	image,
		const char *	description
	)

Changes the description of an image in the WIM.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image	The number of the image for which to change the description.
description	The new description to give the image. It may be NULL, which indicates that the image is to be given no description.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_INVALID_IMAGE	image does not specify a single existing image in wim.
WIMLIB_ERR_NOMEM	Failed to allocate the memory needed to duplicate the description string.

int wimlib_set_image_name	(	WIMStruct *	wim,
		int	image,
		const char *	name
	)

Changes the name of an image in the WIM.

Parameters:

wim	Pointer to the WIMStruct for a WIM file.
image	The number of the image for which to change the name.
name	The new name to give the image. It must not be NULL.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_IMAGE_NAME_COLLISION	There is already an image named name in wim.
WIMLIB_ERR_INVALID_PARAM	name was NULL or the empty string.
WIMLIB_ERR_INVALID_IMAGE	image does not specify a single existing image in wim.
WIMLIB_ERR_NOMEM	Failed to allocate the memory needed to duplicate the name string.

int wimlib_set_link_type	(	WIMStruct *	wim,
		int	link_type
	)

Sets the link type to use when extracting files from a WIM.

This applies when extracting one image as well as when extracting all images. Cross-image links may save a lot of space because it is common for files to be referenced multiple times in WIM files. By default, the link type used for extraction is WIM_LINK_TYPE_NONE, meaning that links are not created.

Parameters:

wim	Pointer to the WIMStruct for a WIM file
link_type	WIM_LINK_TYPE_NONE, WIM_LINK_TYPE_SYMBOLIC, or WIM_LINK_TYPE_HARD.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_INVALID_PARAM

link_type was not WIM_LINK_TYPE_NONE, WIM_LINK_TYPE_SYMBOLIC, or WIM_LINK_TYPE_HARD.

int wimlib_set_memory_allocator	(	void *(*)(size_t)	malloc_func,
		void(*)(void *)	free_func,
		void *(*)(void *, size_t)	realloc_func
	)

Set the functions that wimlib uses to allocate and free memory.

These settings are global and not per-WIM.

The default is to use the default malloc() and free() from the C library.

Parameters:

malloc_func	A function equivalent to malloc() that wimlib will use to allocate memory. If NULL, the allocator function is set back to the default malloc() from the C library.
free_func	A function equivalent to free() that wimlib will use to free memory. If NULL, the free function is set back to the default free() from the C library.
realloc_func	A function equivalent to realloc() that wimlib will use to reallocate memory. If NULL, the free function is set back to the default realloc() from the C library.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_UNSUPPORTED

wimlib was compiled with the --without-custom-memory-allocator flag, so custom memory allocators are unsupported.

int wimlib_set_output_dir	(	WIMStruct *	wim,
		const char *	dir
	)

Sets and creates the directory to which files are to be extracted when extracting files from the WIM.

Parameters:

wim	Pointer to the WIMStruct for the WIM file.
dir	The name of the directory to extract files to.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_INVALID_PARAM	dir was NULL.
WIMLIB_ERR_MKDIR	dir does not already exist and it could not created.
WIMLIB_ERR_NOMEM	Failed to allocate the memory needed to duplicate the dir string.

int wimlib_set_print_errors

(

bool

show_messages

)

Sets whether wimlib is to print error messages to stderr when a function fails or not.

These error messages may provide information that cannot be determined only from the error code that is returned.

This setting is global and not per-WIM.

By default, error messages are not printed.

Parameters:

show_messages

true if error messages are to be printed; false if error messages are not to be printed.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_UNSUPPORTED

show_messages was true, but wimlib was compiled with the --without-error-messages option. Therefore, error messages cannot be shown.

void wimlib_set_verbose	(	WIMStruct *	wim,
		bool	verbose
	)

Sets whether wimlib is to be verbose when extracting files from a WIM or when creating an image from a directory (i.e.

whether it will print all affected files or not.) This is a per-WIM parameter.

Parameters:

wim	Pointer to the WIMStruct for the WIM file.
verbose	Whether wimlib is to be verbose when extracting files from wim using wimlib_extract_image() or when adding an image to wim using wimlib_add_image().

Returns:

This function has no return value.

int wimlib_unmount	(	const char *	dir,
		int	flags
	)

Unmounts a WIM image that was mounted using wimlib_mount().

Blocks until it is known whether the mount succeeded or failed.

To perform this operation, the process calling wimlib_unmount() communicates with the process that had called wimlib_mount().

There is currently a design problem with this function because it is hard to know whether the filesystem daemon is still working or whether it has crashed, has been killed, or has reached an infinite loop. However, ideally there should be no infinite loops or crashes in the code, so this wouldn't be much of a problem. Currently, a timeout of 600 seconds (so long because WIMs can be very large) is implemented so that this function will not wait forever before returning failure.

Parameters:

dir	The directory that the WIM image was mounted on.
flags	Bitwise OR of the flags WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY or WIMLIB_UNMOUNT_FLAG_COMMIT. Neither of these flags affect read-only mounts.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_DELETE_STAGING_DIR	The filesystem daemon was unable to remove the staging directory and the temporary files that it contains.
WIMLIB_ERR_FORK	Could not fork() the process.
WIMLIB_ERR_FUSERMOUNT	The fusermount program could not be executed or exited with a failure status.
WIMLIB_ERR_MQUEUE	Could not open a POSIX message queue to communicate with the filesystem daemon servicing the mounted filesystem, could not send a message through the queue, or could not receive a message through the queue.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_OPEN	The filesystem daemon could not open a temporary file for writing the new WIM.
WIMLIB_ERR_TIMEOUT	600 seconds elapsed while waiting for the filesystem daemon to notify the process of its exit status, so the WIM file probably was not written successfully.
WIMLIB_ERR_READ	A read error occurred when the filesystem daemon tried to a file from the staging directory
WIMLIB_ERR_RENAME	The filesystem daemon failed to rename the newly written WIM file to the original WIM file.
WIMLIB_ERR_WRITE	A write error occurred when the filesystem daemon was writing to the new WIM file, or the filesystem daemon was unable to flush changes that had been made to files in the staging directory.

int wimlib_write	(	WIMStruct *	wim,
		const char *	path,
		int	image,
		int	flags
	)

Writes the WIM to a file.

Parameters:

wim	Pointer to the WIMStruct for a WIM file. There may have been in-memory changes made to it, which are then reflected in the output file.
path	The path to the file to write the WIM to.
image	The image inside the WIM to write. Use WIM_ALL_IMAGES to include all images.
flags	Bitwise OR of WIMLIB_WRITE_FLAG_CHECK_INTEGRITY and/or WIMLIB_WRITE_FLAG_SHOW_PROGRESS. If WIMLIB_WRITE_FLAG_CHECK_INTEGRITY is given, an integrity table is included in the WIM being written. If WIMLIB_WRITE_FLAG_SHOW_PROGRESS is given, the progress of the calculation of the integrity table is shown.

Returns:

0 on success; nonzero on error.

Return values:

WIMLIB_ERR_DECOMPRESSION	Failed to decompress a metadata or file resource in wim.
WIMLIB_ERR_INVALID_DENTRY	A directory entry in the metadata resource for image in wim is invalid.
WIMLIB_ERR_INVALID_IMAGE	image does not specify a single existing image in wim, and is not WIM_ALL_IMAGES.
WIMLIB_ERR_INVALID_RESOURCE_SIZE	The metadata resource for image in wim is invalid.
WIMLIB_ERR_NOMEM	Failed to allocate needed memory.
WIMLIB_ERR_OPEN	Failed to open path for writing, or some file resources in wim refer to files in the outside filesystem, and one of these files could not be opened for reading.
WIMLIB_ERR_READ	An error occurred when trying to read data from the WIM file associated with wim, or some file resources in wim refer to files in the outside filesystem, and a read error occurred when reading one of these files.