fusefile.8

   1 .mso www.tmac
   2 .TH fusefile 8
   3 .SH NAME
   4 fusefile \- FUSE file mount for combining file fragments
   5
   6 .SH SYNOPSIS
   7 .B fusefile \fR[\fIfuse-opts\fR] \fBmountpoint\fR \fR[\fIoverlay\fR] \fIfilename/from-to\fR ...
   8
   9 .SH DESCRIPTION
  10
  11 \fBfusefile\fR is FUSE file mount that presents a series of fragments
  12 of other files as a contiguous concatenation. It bind mounts a driver
  13 on top of the file mountpoint to present the nominated file fragments
  14 as a single, contiguous file. It accepts over-writing on the fused
  15 file which gets distributed accordingly to the fragments, but cannot
  16 change size.
  17
  18 An optional overlay file is declared with an
  19 \fB-overlay:\fIfilename\fR argument between the mount point and the
  20 fragments. This file is then set up as an overlay for capturing writes
  21 to the fused file. The overlay file will contain the written fused
  22 file regions, followed by meta data to distinguish between written
  23 content and "holes" (where content comes from the fused fragments).
  24
  25 The fragment arguments include the filename of a source file, and
  26 optionally start and end byte positions. All in all there five
  27 variations:
  28
  29 .TP
  30 \fIfilename\fR or \fIfilename/\fR
  31 include all of the file. A pathname that includes "/" must be ended
  32 with an extra "/" since that last "/" separates the filename from the
  33 range detail.
  34
  35 .TP
  36 \fIfilename/start:end\fR
  37 include the range from the given start to end. Either "start" or "end"
  38 or both may be omitted, to mean the beginning and end of the file
  39 respectively. If "start" or "end" are less than 0 then it means
  40 relative to the end of the file.
  41
  42 .TP
  43 \fIfilename/start+length\fR
  44 include "length" bytes from the given start. A negative "start" means
  45 relative to the end of the file. If "length" is negative or omitted it
  46 means that position relative to the end.
  47
  48 .TP
  49 \fIfilename/start\fR
  50 include bytes from the given start. This is the same as "/start+"
  51
  52 .P
  53 Note that a negative start position is clipped to 0 and a too large
  54 end position  is clipped to the end of the file.
  55
  56 .P
  57 Charater devices are treated as being of any given finite size, but
  58 have size 0 by default. For example, "/dev/zero/:100" means a fragment
  59 of 100 NUL bytes.
  60
  61 .SH EXAMPLES
  62
  63 Insert file "y" into file "x" at position 1200:
  64 .RS
  65 \fB$ fusefile -ononempty x x/:1200 y x/1200:\fR
  66 .RE
  67 The bind mount shadows the original file "x", and presents the
  68 fused file instead.
  69
  70 Make fused file y be a swap of the beginning and end of file "x", at
  71 position 2442:
  72 .RS
  73 \fB$ fusefile y x/2442: x/:2442\fR
  74 .RE
  75
  76 Replace a partition in an image file with a different file
  77 .RS
  78 # Check the partition table
  79 .br
  80 \fB$ partx -oNR,START,SECTORS disk.raw\fR
  81     NR   START  SECTORS
  82      1    2048  2097152
  83      2 2099200   409600
  84      3 2508800 14268383
  85 .br
  86 # Replace partition 2 of 409600 sectors from 2099200 with
  87 .br
  88 # the file "insert.fat" clipped to 409600 sectors.
  89 .br
  90 \fB$ fusefile -ononempty disk.raw \\
  91          disk.raw/0:$(( 2099200*512 )) \\
  92          insert.fat/0:$(( 409600*512 )) \\
  93          disk.raw/$(( (2099200+409600)*512 )):\fR
  94 .RE
  95
  96 Protect raw disk image file with an overlay:
  97 .RS
  98 \fB$ fusefile -ononempty disk.raw -overlay:today disk.raw\fR
  99 .RE
 100 By that set up, the overlay file, "today", will protect the disk image
 101 file, "disk.raw" from changes, and also override the pathname
 102 "disk.raw" to be the fused file.
 103
 104 .SH NOTES
 105
 106 Note that \fBfusefile\fR opens the nominated source file or files
 107 before bind mounting. With the fuse option \fI-ononempty\fR it will
 108 bind over an non-empty file, which may be useful. The source file
 109 descriptors remain open, but the source fragments are not recomputed.
 110 If a source file changes the fused file will present the new content.
 111 If a source is reduced in size, access will be inconsistent.
 112
 113 If the mountpoint file doesn't exist, then \fBfusefile\fR creates it.
 114
 115 Unmounting is done with "\fBfusermount -u\fR \fImountpoint\fR" as
 116 usual.
 117
 118 Using an overlay file makes the fused file writable regardless of the
 119 fused fragments with the overlay file containing any changes to the
 120 original. The overlay file is reusable for subsequent fusing of the
 121 same fragments for reconstructing a prior session with changes.
 122
 123 .SH AUTHOR
 124
 125 Ralph Rönnquist <ralph.ronnquist@gmail.com>.
 126