X-Git-Url: https://wimlib.net/git/?p=wimlib;a=blobdiff_plain;f=doc%2Fimagex-mount.1.in;h=beda7c9c777f747fdb92415e13a37346fa83e66d;hp=3bfa26479a6e6556ed256c6768c2bab793ab7428;hb=b3d65ccab09cc7f33380cb5bf43709349d079087;hpb=7b5a88bcb70a3bdb24f3df414e8c71fdb95ee602 diff --git a/doc/imagex-mount.1.in b/doc/imagex-mount.1.in index 3bfa2647..beda7c9c 100644 --- a/doc/imagex-mount.1.in +++ b/doc/imagex-mount.1.in @@ -1,4 +1,4 @@ -.TH IMAGEX "1" "November 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" +.TH IMAGEX "1" "December 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands" .SH NAME imagex-mount, imagex-mountrw, imagex-unmount \- Mount and unmount an image from a WIM archive @@ -7,9 +7,9 @@ imagex-mount, imagex-mountrw, imagex-unmount \- Mount and unmount an image from [--streams-interface=\fIINTERFACE\fR] [--ref="\fIGLOB\fR"] .br \fBimagex mountrw\fR \fIWIMFILE\fR \fIIMAGE\fR \fIDIRECTORY\fR [--check] -[--streams-interface=\fIINTERFACE\fR] +[--streams-interface=\fIINTERFACE\fR] [--staging-dir=\fIDIR\fR] .br -\fBimagex unmount\fR \fIDIRECTORY\fR [--commit] [--check] +\fBimagex unmount\fR \fIDIRECTORY\fR [--commit] [--check] [--rebuild] .SH DESCRIPTION .PP @@ -66,6 +66,9 @@ imagex mount mywim.swm 1 dir --ref="mywim*.swm" If wimlib was configured using the --without-fuse flag, then the \fBimagex mount\fR, \fBimagex mountrw\fR, and \fBimagex unmount\fR commands will not work. +You can mount multiple images from a WIM file read-only at the same time, but +you can only mount one image at a time from a WIM read-write. + All files in the mounted WIM will be accessible regardless of whether there is a security descriptor in the WIM associated with the file or not. New files or directories created in a read-write mounted WIM will be created with no security @@ -74,13 +77,20 @@ descriptor. Although there is support for accessing named data streams (see the to set or get DOS names, file attributes, or security descriptors in a mounted WIM. +By default, changes to a read-write WIM are made in-place by appending to the +WIM. This is nice for big WIM files, since the entire file doesn't have to be +rebuilt to make a small change. But, if you are making many changes to a +read-write mounted WIM, especially deleting large files, it is suggested to +provide the \fB--rebuild\fR option to \fBimagex unmount\fR to force the WIM to +be rebuilt, or else run \fBimagex optimize\fR on the WIM afterwards. + .SH MOUNT OPTIONS + .TP \fB--check\fR When reading the WIM, verify its integrity if it contains an integrity table. .TP \fB--streams-interface\fR=\fIINTERFACE\fR - This option is inspired by the ntfs-3g filesystem driver (see \fBntfs-3g\fR (8)). It controls how alternate data streams, or named data streams, in WIM files are made available. @@ -101,47 +111,54 @@ Please note that named data streams are a somewhat obscure NTFS feature that aren't actually used much, even though they complicate the WIM file format considerably. Normally, all you care about is the default or "unnamed" data stream. - .TP \fB--debug\fR Turn on debugging information printed by the FUSE library, and do not fork into the background. - .TP \fB--ref\fR="\fIGLOB\fR" File glob of additional split WIM parts that are part of the split WIM being mounted. This option is valid for \fBimagex mount\fR but not \fBimagex mountrw\fR. See \fBSPLIT_WIMS\fR. +.TP +\fB--staging-dir\fR=\fIDIR\fR +Store temporary staging files in the directory \fIDIR\fR. Only valid for +\fBimagex mountrw\fR. .SH UNMOUNT OPTIONS + .TP \fB--commit\fR -Recreate the WIM file with the changes that have been made. Has no effect if -the mount is read-only. -.TP 6 +Update the WIM file with the changes that have been made. Has no effect if the +mount is read-only. +.TP \fB--check\fR When writing \fIWIMFILE\fR, include an integrity table. Has no effect if the mount is read-only or if --commit was not specified. +.TP +\fB--rebuild\fR +Rebuild the entire WIM rather than appending any new data to the end of it. +Rebuilding the WIM is slower, but will save a little bit of space that would +otherwise be left as a hole in the WIM. Even more space will be saved if the +read-write mount resulted in streams being deleted from the WIM. Also see +\fBimagex optimize\fR. Has no effect if the mount is read-only or if --commit +was not specified. .SH IMPLEMENTATION DETAILS Since a WIM is an archive and not a filesystem, \fBimagex mountrw\fR creates a -temporary staging directory to contain files that are created or modified. When -the filesystem is unmounted with \fB--commit\fR, the WIM is rebuilt, merging in -the staging files as needed. Then, the temporary staging directory is deleted. - -\fBimagex unmount\fR executes the \fBfusermount\fR (1) program, which should be -installed as part of libfuse, to unmount the filesystem. It then uses a POSIX -message queue (see \fBmq_overview\fR (7)) to communicate with the filesystem -daemon (the instance of \fBimagex\fR that has mounted the WIM image) so that it -can know whether whether changes are to be committed and whether an integrity -table is to be included. A message is then sent from the filesystem daemon to -unmounting process when the unmounting has been completed, and this message -indicates whether the unmounting was successful or not. - -If the filesystem daemon has crashed or been killed, is possible for \fBimagex -unmount\fR to wait a very long time before timing out. A solution to this -problem may be implemented in the future. +temporary staging directory to contain files that are created or modified. This +directory is located in the same directory as \fIWIMFILE\fR by default, but the +location can be set using the \fB--staging-dir\fR option. When the filesystem +is unmounted with \fB--commit\fR, the WIM is modified in-place (or rebuild +completely with \fB--rebuild\fR), merging in the staging files as needed. Then, +the temporary staging directory is deleted. + +\fBimagex unmount\fR runs in a separate process from the process that previously +ran \fBimagex mount\fR, and these two processes communicate using POSIX message +queue. See \fIsrc/mount_image.c\fR in the sources for details. Note: As of wimlib +v1.2.1, \fBimagex unmount\fR correctly fails with an error within a reasonable +amount of time (1 second) if the filesystem daemon is abnormally terminated. .SH SEE ALSO .BR imagex (1)