version update

[rrq/fusefile.git] / fusefile.8

diff --git a/fusefile.8 b/fusefile.8
index 7051d94aa5277aee40ce2bf6070d685f5e5e5eb0..183a362bce8c42bff4b27764ba01a4930625b37e 100644 (file)
--- a/fusefile.8
+++ b/fusefile.8
@@ -1,80 +1,102 @@
 .mso www.tmac
 .TH fusefile 8
 .SH NAME
 .mso www.tmac
 .TH fusefile 8
 .SH NAME

-fusefile \- FUSE file mount for combining file fragments read-only
+fusefile \- FUSE file mount for combining file fragments

 
 .SH SYNOPSIS
 
 .SH SYNOPSIS

-.B fusefile \fR[fuse options\fR] \fBmountpoint\fR \fIfilename/from-to\fR ...
+.B fusefile \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...

 
 .SH DESCRIPTION
 
 
 .SH DESCRIPTION
 

-\fBfusefile\fR is FUSE file mount that presents a series of fragments of
-other files as a contiguous concatenation. It bind mounts a driver on
-top of the file mountpoint to present the nominated file fragments as
-a single, contiguous file.
+\fBfusefile\fR is FUSE file mount that presents a series of fragments
+of other files as a contiguous concatenation. It bind mounts a driver
+on top of the file mountpoint to present the nominated file fragments
+as a single, contiguous file. It accepts over-writing on the fused
+file which gets distributed accordingly to the fragments, but cannot
+change size.
+
+An optional overlay file is declared with the "-overlay:filename"
+argument between the mount point and the fragments. This file is then
+set up as an overlay for capturing writes to the fused file. The
+overlay file will contain the written fused file regions, followed by
+meta data to distinguish between written content and "holes" (where
+content comes from the fused fragments).

 
 The fragment arguments include the filename of a source file, and
 optionally start and end byte positions. All in all there five
 variations:
 
 The fragment arguments include the filename of a source file, and
 optionally start and end byte positions. All in all there five
 variations:

+

 .TP
 .TP

-\fIfilename\fR
-include all of the file.
-.TP
-\fIfilename/\fR
-include all of the file named with "/" in the pathname. This case
-requires a final "/", since the last "/" separates the filename from
-the position details.
-.TP
-\fIfilename/from\fR
-include the file from the given start position, to end.
+\fIfilename\fR or \fIfilename/\fR
+include all of the file. A pathname that includes "/" must be ended
+with an extra "/" since that last "/" separates the filename from the
+range detail.
+

 .TP
 .TP

-\fIfilename/-to\fR
-include the file from beginning to the given end position (not
-included).
+\fIfilename/start:end\fR
+include the range from the given start to end. Either "start" or "end"
+or both may be omitted, to mean the beginning and end of the file
+respectively. If "start" or "end" are less than 0 then it means
+relative to the end of the file.
+

 .TP
 .TP

-\fIfilename/from-to\fR
-include the file from the given start position, up to the given end
-position (not included).
+\fIfilename/start+length\fR
+include "length" bytes from the given start. A negative "start" means
+relative to the end of the file. If "length" is negative or omitted it
+means that position relative to the end.
+

 .TP
 .TP

-\fBpad=\fIfilename\fR
+\fIfilename/start\fR
+include bytes from the given start. This is the same as "/start+"
+
+.P
+Note that a negative start position is clipped to 0 and a too large
+end position  is clipped to the end of the file.

 
 

-when this is given as first argument, the fused file is set up as a
-writable random-access file, where the write events are captured
-appended to the nominated "pad" file. The new content is inserted into
-the fused file but not the original files, and fragments are split up
-and adjusted as needed so as to make the write events appear as
-insertions inteo the fused file.
+.P
+Charater devices are treated as being of any given finite size, but
+have size 0 by default. For example, "/dev/zero/:100" means a fragment
+of 100 NUL bytes.

 
 .SH EXAMPLES
 
 Insert file "y" into file "x" at position 1200:
 .RS
 
 .SH EXAMPLES
 
 Insert file "y" into file "x" at position 1200:
 .RS

-\fB$ fusefile -ononempty x x/-1200 y x/1200\fR
+\fB$ fusefile -ononempty x x/:1200 y x/1200:\fR

 .RE
 The bind mount shadows the original file "x", and presents the
 .RE
 The bind mount shadows the original file "x", and presents the

-composite instead.
+fused file instead.
+
+Make fused file y be a swap of the beginning and end of file "x", at
+position 2442:
+.RS
+\fB$ fusefile y x/2442: x/:2442\fR
+.RE

 
 

-Make file y be a swap of the beginning and end of file "x", at position 2442:
+Protect raw disk image file with an overlay:

 .RS
 .RS

-\fB$ fusefile y x/2442 x/-2442\fR
+\fB# fusefile -ononempty disk.raw -overlay:today disk.raw

 .RE
 .RE

+By this set up, the overlay file, "today", will protect the disk image
+file, "disk.raw" from changes, and also override the pathname
+"disk.raw" to be the fused file.

 
 .SH NOTES
 
 
 .SH NOTES
 

-Note that \fBfusefile\fR opens the nominated source file(s) before bind
-mounting. With the fuse option \fI-ononempty\fR it will bind over an
-non-empty file, which may be useful. The source file descriptors
-remain open, but the source fragments are not recomputed. If a source
-file changes or reduces in size, anything may happen.
+Note that \fBfusefile\fR opens the nominated source file or files
+before bind mounting. With the fuse option \fI-ononempty\fR it will
+bind over an non-empty file, which may be useful. The source file
+descriptors remain open, but the source fragments are not recomputed.
+If a source file changes the fused file will present the new content.
+If a source is reduced in size, access will be inconsistent.

 
 If the mountpoint file doesn't exist, then \fBfusefile\fR creates it,
 and removes it when unmounted.
 
 
 If the mountpoint file doesn't exist, then \fBfusefile\fR creates it,
 and removes it when unmounted.
 

-When a "pad" file is used, it is updated as an "ar" archive where each
-write event is a new member appended at the end. The "pad" member has
-two additional, newline-terminated text lines with the insertion
-position and the member size (ascii decimal digits), before the actual
-insertion event content.
+Using an overlay file makes the fused file writable regardless of the
+fused fragemnts with the overlay file containing any changes to the
+original. The overlay file is reusable for subsequent fusing of the
+same fragments for reconstructing a prior session.

 
 .SH AUTHOR
 
 
 .SH AUTHOR