Loading...
Searching...
No Matches
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.
#define | WIMLIB_MOUNT_FLAG_DEBUG 0x00000002
| Enable FUSE debugging by passing the `-d` option to `fuse_main()`.
#define | WIMLIB_MOUNT_FLAG_STREAM_INTERFACE_NONE 0x00000004
| Do not allow accessing named data streams in the mounted WIM image.
#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.
#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.
#define | WIMLIB_MOUNT_FLAG_UNIX_DATA 0x00000020
| Support UNIX owners, groups, modes, and special files.
#define | WIMLIB_MOUNT_FLAG_ALLOW_OTHER 0x00000040
| Allow other users to see the mounted filesystem.
#define | WIMLIB_UNMOUNT_FLAG_CHECK_INTEGRITY 0x00000001
| Provide WIMLIB_WRITE_FLAG_CHECK_INTEGRITY when committing the WIM image.
#define | WIMLIB_UNMOUNT_FLAG_COMMIT 0x00000002
| Commit changes to the read-write mounted WIM image.
#define | WIMLIB_UNMOUNT_FLAG_REBUILD 0x00000004
| Provide WIMLIB_WRITE_FLAG_REBUILD when committing the WIM image.
#define | WIMLIB_UNMOUNT_FLAG_RECOMPRESS 0x00000008
| Provide WIMLIB_WRITE_FLAG_RECOMPRESS when committing the WIM image.
#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.
#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.

## Functions

WIMLIBAPI 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.
WIMLIBAPI int | wimlib_unmount_image (const wimlib_tchar *dir, int unmount_flags)
| Unmount a WIM image that was mounted using wimlib_mount_image().
WIMLIBAPI 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.

## 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()

WIMLIBAPI 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

  wim | Pointer to the WIMStruct containing the image to be mounted. This WIMStruct must have a backing file.
  image | The 1-based index of the image to mount. This image cannot have been previously modified in memory.
  dir | The path to an existing empty directory on which to mount the image.
  mount_flags | Bitwise 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_dir | If 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_LOCKED | Another process is currently modifying the WIM file.
  WIMLIB_ERR_FUSE | A non-zero status code was returned by `fuse_main()`.
  WIMLIB_ERR_IMAGE_HAS_MULTIPLE_REFERENCES | There 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_IMAGE | `image` does not exist in `wim`.
  WIMLIB_ERR_INVALID_PARAM | `wim` 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_MKDIR | WIMLIB_MOUNT_FLAG_READWRITE was specified in `mount_flags`, but the staging directory could not be created.
  WIMLIB_ERR_WIM_IS_READONLY | WIMLIB_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_UNSUPPORTED | Mounting 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()

WIMLIBAPI 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

  dir | The directory on which the WIM image is mounted.
  unmount_flags | Bitwise 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_MOUNTPOINT | There is no WIM image mounted on the specified directory.
  WIMLIB_ERR_MOUNTED_IMAGE_IS_BUSY | The 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_MQUEUE | Could not create a POSIX message queue.
  WIMLIB_ERR_NOT_PERMITTED_TO_UNMOUNT | The image was mounted by a different user.
  WIMLIB_ERR_UNSUPPORTED | Mounting 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()

WIMLIBAPI 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.