wimlib
Macros | Functions
Mounting WIM images

Mount and unmount WIM images. More...

Macros

#define WIMLIB_MOUNT_FLAG_READWRITE   0x00000001
 Mount the WIM image read-write rather than the default of read-only. More...
 
#define WIMLIB_MOUNT_FLAG_DEBUG   0x00000002
 Enable FUSE debugging by passing the -d option to fuse_main(). More...
 
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE   0x00000004
 Do not allow accessing named data streams in the mounted WIM image. More...
 
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR   0x00000008
 Access named data streams in the mounted WIM image through extended file attributes named "user.X", where X is the name of a data stream. More...
 
#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS   0x00000010
 Access named data streams in the mounted WIM image by specifying the file name, a colon, then the name of the data stream. More...
 
#define WIMLIB_MOUNT_FLAG_UNIX_DATA   0x00000020
 Support UNIX owners, groups, modes, and special files. More...
 
#define WIMLIB_MOUNT_FLAG_ALLOW_OTHER   0x00000040
 Allow other users to see the mounted filesystem. More...
 
#define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY   0x00000001
 Provide WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image. More...
 
#define WIMLIB_UNMOUNT_FLAG_COMMIT   0x00000002
 Commit changes to the read-write mounted WIM image. More...
 
#define WIMLIB_UNMOUNT_FLAG_REBUILD   0x00000004
 Provide WIMLIB_WRITE_FLAG_REBUILD when committing the WIM image. More...
 
#define WIMLIB_UNMOUNT_FLAG_RECOMPRESS   0x00000008
 Provide WIMLIB_WRITE_FLAG_RECOMPRESS when committing the WIM image. More...
 
#define WIMLIB_UNMOUNT_FLAG_FORCE   0x00000010
 In combination with WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM image, forces all file descriptors to the open WIM image to be closed before committing it. More...
 
#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE   0x00000020
 In combination with WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM image, causes the modified image to be committed to the WIM file as a new, unnamed image appended to the archive. More...
 

Functions

int wimlib_mount_image (WIMStruct *wim, int image, const wimlib_tchar *dir, int mount_flags, const wimlib_tchar *staging_dir)
 Mount an image from a WIM file on a directory read-only or read-write. More...
 
int wimlib_unmount_image (const wimlib_tchar *dir, int unmount_flags)
 Unmount a WIM image that was mounted using wimlib_mount_image(). More...
 
int wimlib_unmount_image_with_progress (const wimlib_tchar *dir, int unmount_flags, wimlib_progress_func_t progfunc, void *progctx)
 Same as wimlib_unmount_image(), but allows specifying a progress function. More...
 

Detailed Description

Mount and unmount WIM images.

On Linux, wimlib supports mounting images from WIM files either read-only or read-write. To mount an image, call wimlib_mount_image(). To unmount an image, call wimlib_unmount_image(). Mounting can be done without root privileges because it is implemented using FUSE (Filesystem in Userspace).

If wimlib is compiled using the –without-fuse flag, these functions will be available but will fail with WIMLIB_ERR_UNSUPPORTED.

Note: if mounting is unsupported, wimlib still provides another way to modify a WIM image (wimlib_update_image()).

Macro Definition Documentation

◆ WIMLIB_MOUNT_FLAG_READWRITE

#define WIMLIB_MOUNT_FLAG_READWRITE   0x00000001

Mount the WIM image read-write rather than the default of read-only.

◆ WIMLIB_MOUNT_FLAG_DEBUG

#define WIMLIB_MOUNT_FLAG_DEBUG   0x00000002

Enable FUSE debugging by passing the -d option to fuse_main().

◆ WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE

#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE   0x00000004

Do not allow accessing named data streams in the mounted WIM image.

◆ WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR

#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_XATTR   0x00000008

Access named data streams in the mounted WIM image through extended file attributes named "user.X", where X is the name of a data stream.

This is the default mode.

◆ WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS

#define WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_WINDOWS   0x00000010

Access named data streams in the mounted WIM image by specifying the file name, a colon, then the name of the data stream.

◆ WIMLIB_MOUNT_FLAG_UNIX_DATA

#define WIMLIB_MOUNT_FLAG_UNIX_DATA   0x00000020

Support UNIX owners, groups, modes, and special files.

◆ WIMLIB_MOUNT_FLAG_ALLOW_OTHER

#define WIMLIB_MOUNT_FLAG_ALLOW_OTHER   0x00000040

Allow other users to see the mounted filesystem.

This passes the allow_other option to fuse_main().

◆ WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY

#define WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY   0x00000001

Provide WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image.

Ignored if WIMLIB_UNMOUNT_FLAG_COMMIT not also specified.

◆ WIMLIB_UNMOUNT_FLAG_COMMIT

#define WIMLIB_UNMOUNT_FLAG_COMMIT   0x00000002

Commit changes to the read-write mounted WIM image.

If this flag is not specified, changes will be discarded.

◆ WIMLIB_UNMOUNT_FLAG_REBUILD

#define WIMLIB_UNMOUNT_FLAG_REBUILD   0x00000004

Provide WIMLIB_WRITE_FLAG_REBUILD when committing the WIM image.

Ignored if WIMLIB_UNMOUNT_FLAG_COMMIT not also specified.

◆ WIMLIB_UNMOUNT_FLAG_RECOMPRESS

#define WIMLIB_UNMOUNT_FLAG_RECOMPRESS   0x00000008

Provide WIMLIB_WRITE_FLAG_RECOMPRESS when committing the WIM image.

Ignored if WIMLIB_UNMOUNT_FLAG_COMMIT not also specified.

◆ WIMLIB_UNMOUNT_FLAG_FORCE

#define WIMLIB_UNMOUNT_FLAG_FORCE   0x00000010

In combination with WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM image, forces all file descriptors to the open WIM image to be closed before committing it.

Without WIMLIB_UNMOUNT_FLAG_COMMIT or with a read-only mounted WIM image, this flag has no effect.

◆ WIMLIB_UNMOUNT_FLAG_NEW_IMAGE

#define WIMLIB_UNMOUNT_FLAG_NEW_IMAGE   0x00000020

In combination with WIMLIB_UNMOUNT_FLAG_COMMIT for a read-write mounted WIM image, causes the modified image to be committed to the WIM file as a new, unnamed image appended to the archive.

The original image in the WIM file will be unmodified.

Function Documentation

◆ wimlib_mount_image()

int wimlib_mount_image ( WIMStruct wim,
int  image,
const wimlib_tchar dir,
int  mount_flags,
const wimlib_tchar staging_dir 
)

Mount an image from a WIM file on a directory read-only or read-write.

Parameters
wimPointer to the WIMStruct containing the image to be mounted. This WIMStruct must have a backing file.
imageThe 1-based index of the image to mount. This image cannot have been previously modified in memory.
dirThe path to an existing empty directory on which to mount the image.
mount_flagsBitwise OR of flags prefixed with WIMLIB_MOUNT_FLAG. Use WIMLIB_MOUNT_FLAG_READWRITE to request a read-write mount instead of a read-only mount.
staging_dirIf non-NULL, the name of a directory in which a temporary directory for storing modified or added files will be created. Ignored if WIMLIB_MOUNT_FLAG_READWRITE is not specified in mount_flags. If left NULL, the staging directory is created in the same directory as the backing WIM file. The staging directory is automatically deleted when the image is unmounted.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_ALREADY_LOCKEDAnother process is currently modifying the WIM file.
WIMLIB_ERR_FUSEA non-zero status code was returned by fuse_main().
WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCESThere are currently multiple references to the image as a result of a call to wimlib_export_image(). Free one before attempting the read-write mount.
WIMLIB_ERR_INVALID_IMAGEimage does not exist in wim.
WIMLIB_ERR_INVALID_PARAMwim was NULL; or dir was NULL or an empty string; or an unrecognized flag was specified in mount_flags; or the image has already been modified in memory (e.g. by wimlib_update_image()).
WIMLIB_ERR_MKDIRWIMLIB_MOUNT_FLAG_READWRITE was specified in mount_flags, but the staging directory could not be created.
WIMLIB_ERR_WIM_IS_READONLYWIMLIB_MOUNT_FLAG_READWRITE was specified in mount_flags, but 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.
WIMLIB_ERR_UNSUPPORTEDMounting is not supported in this build of the library.

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

The ability to mount WIM images is implemented using FUSE (Filesystem in UserSpacE). Depending on how FUSE is set up on your system, this function may work as normal users in addition to the root user.

Mounting WIM images is not supported if wimlib was configured –without-fuse. This includes Windows builds of wimlib; WIMLIB_ERR_UNSUPPORTED will be returned in such cases.

Calling this function daemonizes the process, unless WIMLIB_MOUNT_FLAG_DEBUG was specified or an early error occurs.

It is safe to mount multiple images from the same WIM file read-only at the same time, but only if different WIMStruct's are used. It is not safe to mount multiple images from the same WIM file read-write at the same time.

To unmount the image, call wimlib_unmount_image(). This may be done in a different process.

◆ wimlib_unmount_image()

int wimlib_unmount_image ( const wimlib_tchar dir,
int  unmount_flags 
)

Unmount a WIM image that was mounted using wimlib_mount_image().

When unmounting a read-write mounted image, the default behavior is to discard changes to the image. Use WIMLIB_UNMOUNT_FLAG_COMMIT to cause the image to be committed.

Parameters
dirThe directory on which the WIM image is mounted.
unmount_flagsBitwise OR of flags prefixed with WIMLIB_UNMOUNT_FLAG.
Returns
0 on success; a wimlib_error_code value on failure.
Return values
WIMLIB_ERR_NOT_A_MOUNTPOINTThere is no WIM image mounted on the specified directory.
WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSYThe read-write mounted image cannot be committed because there are file descriptors open to it, and WIMLIB_UNMOUNT_FLAG_FORCE was not specified.
WIMLIB_ERR_MQUEUECould not create a POSIX message queue.
WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNTThe image was mounted by a different user.
WIMLIB_ERR_UNSUPPORTEDMounting is not supported in this build of the library.

Note: you can also unmount the image by using the umount() system call, or by using the umount or fusermount programs. However, you need to call this function if you want changes to be committed.

◆ wimlib_unmount_image_with_progress()

int wimlib_unmount_image_with_progress ( const wimlib_tchar dir,
int  unmount_flags,
wimlib_progress_func_t  progfunc,
void *  progctx 
)

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

The progress function will receive a WIMLIB_PROGRESS_MSG_UNMOUNT_BEGIN message. In addition, if changes are committed from a read-write mount, the progress function will receive WIMLIB_PROGRESS_MSG_WRITE_STREAMS messages.