.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
-.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
-\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 an
+\fB-overlay:\fIfilename\fR 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:
+
.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
-\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
-\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
-\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
-\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
-composite instead.
+fused file instead.
-Make file y be a swap of the beginning and end of file "x", at position 2442:
+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
+\fB$ fusefile y x/2442: x/:2442\fR
.RE
+Replace a partition in an image file with a different file
+.RS
+# Check the partition table
+.br
+\fB$ partx -oNR,START,SECTORS disk.raw\fR
+ NR START SECTORS
+ 1 2048 2097152
+ 2 2099200 409600
+ 3 2508800 14268383
+.br
+# Replace partition 2 of 409600 sectors from 2099200 with
+.br
+# the file "insert.fat" clipped to 409600 sectors.
+.br
+\fB$ fusefile -ononempty disk.raw \\
+ disk.raw/0:$(( 2099200*512 )) \\
+ insert.fat/0:$(( 409600*512 )) \\
+ disk.raw/$(( (2099200+409600)*512 )):\fR
+.RE
+
+Protect raw disk image file with an overlay:
+.RS
+\fB$ fusefile -ononempty disk.raw -overlay:today disk.raw\fR
+.RE
+By that 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
-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.
-When a "pad" file is used, it is updated as a simple archive where
-each write event is a new member appended at the end. Each "pad"
-member has a prefix of two newline-terminated text lines telling the
-insertion position and the member size (both as ascii decimal digits),
-before the actual insertion event content.
+Unmounting is done with "\fBfusermount -u\fR \fImountpoint\fR" as
+usual.
+
+Using an overlay file makes the fused file writable regardless of the
+fused fragments 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 with changes.
.SH AUTHOR
-Ralph Rönnquist <ralph.ronnquist@gmail.com>
+Ralph Rönnquist <ralph.ronnquist@gmail.com>.
+
projects / rrq / fusefile.git / blobdiff