-fusefile
-========
+# fusefile
+:author: Ralph Ronnquist
+:revdate: Sun, 30 Apr 2023 21:18:34 +1000
+
+This project implements a "fuse" device to mount a concatenation of
+fragments of one or more files as a single file.
+
+The __fused file__ allows writing to fragments (without changing their
+sizes); of course only for writable fragment files. The fused file may
+be set up with an __overlay file__ to capture changes instead of
+writing the underlying fragment files.
+
+====
+This is a usage example to set up a fused file C consisting of files A
+and B:
+----
+$ fusefile C A B
+----
+====
+
+====
+This is an example of tearing down a fused file C:
+----
+$ fusermount -u C
+----
+====
+
+See the +man page+ for usage details and some more examples.
-This project implements a "fuse" device to mount as a single file that
-is a concatenation of fragments of one or more files. By default the
-fused file is read-only.
-
-A writeable fused file is set up by associating the mount with a
-"scratch pad file"
-
-FUSE file mount for combining file fragments.
-
-== SYNOPSIS
- *fusefile* [_fuse options_] *mountpoint* _filename/from-to_ ...
-
-## DESCRIPTION
-
-*fusefile* 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.
-
-The fragment arguments include the filename of a source file, and
-optionally start and end byte positions. All in all there five
-variations:
-
- * __filename__ include all of the file.
-
- * __filename/__ 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.
-
- * __filename/from__ include the file from the given start position, to end.
-
- * __filename/-to__ include the file from beginning to the given end position (not included).
-
- * __filename/from-to__ include the file from the given start position, up to the given end position (not included).
-
- * *pad=*_filename_ 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.
-
-## EXAMPLES
-
-Insert file "y" into file "x" at position 1200:
-
- $ fusefile -ononempty x x/-1200 y x/1200
-The bind mount shadows the original file "x", and presents the
-composite instead.
-
-Make file y be a swap of the beginning and end of file "x", at
-position 2442:
-
- $ fusefile y x/2442 x/-2442
-
-## NOTES
-
-Note that **fusefile** opens the nominated source file(s) before bind
-mounting. With the fuse option __-ononempty__ 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.
-
-If the mountpoint file doesn't exist, then **fusefile** 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.
-
-## AUTHOR
-
-Ralph Rönnquist <ralph.ronnquist@gmail.com>
projects / rrq / fusefile.git / blobdiff