Version 1.2.1
[wimlib] / doc / imagex-mount.1.in
index 3f5eb4a..beda7c9 100644 (file)
@@ -1,15 +1,15 @@
-.TH IMAGEX "1" "September 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
+.TH IMAGEX "1" "December 2012" "imagex (wimlib) wimlib @VERSION@" "User Commands"
 .SH NAME
-imagex mount, mountrw, unmount \- Mount and unmount an image from a WIM archive
+imagex-mount, imagex-mountrw, imagex-unmount \- Mount and unmount an image from a WIM archive
 
 .SH SYNOPSIS
 \fBimagex mount\fR \fIWIMFILE\fR \fIIMAGE\fR \fIDIRECTORY\fR [--check]
-[--streams-interface=\fIINTERFACE\fR]
+[--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
@@ -28,25 +28,69 @@ The WIM image can be unmounted using the \fBimagex unmount\fR command.  Changes
 made to a WIM mounted read-write will be discarded unless the \fB--commit\fR
 flag is provided to \fBimagex unmount\fR.
 
+.SH SPLIT WIMS
+
+You may use \fBimagex mount\fR to mount an image from a split WIM read-only.
+However, you may not mount an image from a split WIM read-write.
+
+The \fIWIMFILE\fR argument is used to specify the first part of the split WIM, and
+the \fB--refs\fR="\fIGLOB\fR" option is used to provide a shell-style file glob
+that specifies the additional parts of the split WIM.  \fIGLOB\fR is expected to
+be a single string on the command line, so \fIGLOB\fR must be quoted so that it
+is protected against shell expansion.  \fIGLOB\fR must expand to all parts of
+the split WIM, except optionally the first part which may either omitted or
+included in the glob (but the first part MUST be specified as \fIWIMFILE\fR as
+well).
+
+Here's an example.  The names for the split WIMs usually go something like:
+       
+.RS
+.PP
+.nf
+mywim.swm
+mywim2.swm
+mywim3.swm
+mywim4.swm
+mywim5.swm
+.RE
+
+To mount the first image of this split WIM to the directory "dir", we would do:
+.PP
+.RS
+imagex mount mywim.swm 1 dir --ref="mywim*.swm"
+.RE
+.PP
+
 .SH NOTES
 
 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
-descriptor.
-
-Mounting split WIMs is not yet supported.
+descriptor.  Although there is support for accessing named data streams (see the
+\fB--streams-interface\fR option), it is currently not possible
+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.
@@ -67,41 +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)