Document data corruption possibilities/impossibilities
authorEric Biggers <ebiggers3@gmail.com>
Tue, 20 Nov 2012 06:36:48 +0000 (00:36 -0600)
committerEric Biggers <ebiggers3@gmail.com>
Tue, 20 Nov 2012 06:36:48 +0000 (00:36 -0600)
doc/imagex-capture.1.in
doc/imagex-export.1.in
doc/imagex-info.1.in

index a9ea44804d312e6bb507e2ca2bd6840c9138b846..1647f7a1c2ceb4b9a5d18a58651c6d50775b1d35 100644 (file)
@@ -120,9 +120,9 @@ threads will not be used, regardless of this parameter, since no compression
 needs to be done in this case.
 .TP
 \fB--rebuild\fR
-For \fBimagex append\fR: rebuild the entire WIM rather than appending an image
-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.  Also see \fBimagex
+For \fBimagex append\fR: rebuild the entire WIM rather than appending the 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.  Also see \fBimagex
 optimize\fR.
 .TP
 \fB--flags\fR=\fIEDITIONID\fR
@@ -200,6 +200,13 @@ type, and \fBimagex\fR always enforces this.
 stream chunk size of 32768.  The only WIMs I've seen that are different from
 this are some pre-Vista WIMs that had a different version number.
 
+Unless --rebuild is specified, aborting an \fBimagex append\fR command mid-way
+through has a small chance of corrupting the WIM file.  However, a precaution is
+taken against this, so it should be very unlikely.  In the event of an aborted
+\fBimagex append\fR, \fBimagex optimize\fR may be run to remove extra data that
+may have been partially appended to the physical WIM file but not yet
+incorporated into the structure of the WIM.
+
 .SH EXAMPLES
 Create a new WIM 'mywim.wim' from the directory 'somedir', using LZX compression and
 including an integrity table:
index 0c13577de7404b361c39d7f250ea52d20d9c4c1f..ff76516e02291dc9085e10fdd09eaf8cea1b7b13 100644 (file)
@@ -70,9 +70,9 @@ done in these cases.
 .TP
 \fB--rebuild\fR
 When exporting image(s) to an existing WIM: rebuild the entire WIM rather than
-appending an image 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.
-Also see \fBimagex optimize\fR.
+appending 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.  Also see
+\fBimagex optimize\fR.
 .TP
 \fB--ref\fR="\fIGLOB\fR"
 File glob of additional split WIM parts that are part of the split WIM being
@@ -110,6 +110,15 @@ imagex export mywim.swm 1 other.wim --ref="mywim*.swm"
 .RE
 .PP
 
+.SH NOTES
+
+Unless --rebuild is specified, aborting an \fBimagex export\fR command mid-way
+through has a small chance of corrupting the destination WIM file.  However, a
+precaution is taken against this, so it should be very unlikely.  In the event
+of an aborted \fBimagex export\fR, \fBimagex optimize\fR can be run to remove
+extra data that may have been partially appended to the physical destination WIM
+file but not yet incorporated into the structure of the WIM.
+
 .SH EXAMPLES
 Export the second image of 'boot.wim' to the new WIM file 'new.wim', and
 change the compression type to maximum, if it wasn't maximum already:
index 970828126aca1710a781c8cf5d83dae85700085a..153221859988704fc3f4dc12ee1413917a56fe0f 100644 (file)
@@ -25,14 +25,17 @@ Changes to the WIM are made if \fINEW_NAME\fR and/or \fB--boot\fR are specified.
 \fIIMAGE_NUM\fR or \fIIMAGE_NAME\fR, while \fINEW_DESC\fR is taken to be its new
 description. \fINEW_DESC\fR defaults to the old description if it is not given.
 
-Since none of these changes require changing the WIM's file resources, metadata
-resources, or stream lookup table, they can be done very quickly by only
-re-writing the header and XML data.  It will only take significant time if
-\fB--check\fR is specified for a WIM that had no integrity checks before.
-
 \fBimagex info\fR does not support modifying a split WIM, although you may
 display information about one.
 
+.SH NOTES
+
+Aborting an \fBimagex info\fR command that modifies \fIWIMFILE\fR is unlikely to
+result in corruption of \fIWIMFILE\fR.  If \fBimagex info\fR is aborted while
+the integrity table is being calculated (with --check), the WIM should be in a
+consistent state with any previous changes to the bootable index, new, or
+description of the specified index committed.
+
 .SH OPTIONS
 .TP 6
 \fB--boot\fR