ras adds m extra files to a set of n files, such that the contents of the n
original files can be regenerated from any n of the n+m original files and
extra files. It works for any values of n and m so long as n+m<=256. The
extra files will normally be 6 bytes larger than the largest of the
original files, but they can be made the same size as the largest segfile.
The original files are termed "segment files" or "segfiles", and n (the
number of segfiles that existed before any were lost) is termed the
"segcount". The extra files created by
ras are termed "sumfiles", and m (the number of sumfiles created) is termed the
"sumcount". Each sumfile has an ID, an integer from 0 to 255-segcount.
There's not much point having 2 sumfiles with the same ID, since they
would contain the same information ... you would essentially have 2 copies
of the same sumfile.
OPTIONS
-r,--restore
Restore mode, restore any missing segfiles using the sumfiles specified on
the command line. If there are surplus sumfiles (i.e. more than the number
of missing segfiles) then only the first few will be used unless some of the
first few turn out have the same IDs. This is the default mode of operation.
-c,--create-sums
Create mode, create the sumfiles specified on the command line. The sumfile
arguments may be simply filenames, in which case the first one will be
created with ID 0, the second one will be created with ID 1, and so on.
The sumfile arguments can optionally include a sumspec (a number specifying
the ID to use) separated from the sumfile filename by a ":". The sumfile
filename, the colon and the sumspec should be a single argument with no
spaces.
-b,--brief
Output only a 1-line summary of what's going on to standard output. This
is the default level of verbosity.
-v,--verbose
Output some more detailed information to standard output.
-s,--silent
Output nothing to standard output.
-f,--filename segfile
Use repeatedly to set the names to be used for segfiles, for example
"-fseg1 -fseg2 -fseg3" if there are 3 segfiles named seg1, seg2 and seg3.
By default
ras uses "xaa", "xab", "xac", ..., "xay", "xaz", "xba", "xbb", ... as the names
of the segfiles. This convention was chosen because it's the same as that
used by the GNU version of
split(1)
-n,--segcount segcount
This option allows the segcount to be specified on the command line. This
option is not normally needed since
ras can determine the segcount by testing for the existence of segfiles
when creating sumfiles, and by looking at the header of one of the sumfiles
when restoring segfiles.
-o,--offset offset
When creating sumfiles, this option causes
ras to start from offset instead of 0 when assigning IDs to sumfiles. See
EXAMPLES below. Ignored when in restore mode.
-H,--no-header
ras normally outputs a 5-byte header to each sumfile generated, consisting of
the characters "SU8", a byte specifying segcount, and a byte specifying
the ID of the sumfile. In create mode this option suppresses the writing
of the header. In restore mode this option tells
ras not to expect to find a header. If you use this option to create
some sumfiles then you must also use it when using those sumfiles to
restore segfiles. You can't mix sumfiles with headers and sumfiles without
headers.
If you use this option you must keep track of segcount and the sumfile
IDs yourself. When restoring you must tell
ras how many segments there are (using the -n option, above) and ensure that
the names of the sumfiles reflect their ID values. For example,
under the -H option,
ras will assume a sumfile called "sum_45" has an ID of 45. Note that it takes
the first block of digits that it finds in the sumfile name, so a sumfile
called "s0er_34" will be treated as having an ID of 0, not 34.
In summary, don't use this option unless you really need to get rid of the
5 byte header overhead.
-F,--no-footer
ras normally appends a 1-byte footer to each sumfile created. This option
suppresses this footer in create mode, and tells
ras not to expect to find it in restore mode. If you use this option to create
some sumfiles then you must also use it when using those sumfiles to
restore segfiles. You can't mix sumfiles with footers and sumfiles without
footers.
The function of the footer is to allow
ras to handle segfiles of differing lengths correctly. If you don't have the footer,
then if any segfile smaller than the largest is lost and restored, it will get
padded with zeros to the length of the largest segfile. If all the segfiles
are the same size, of course, this won't matter.
If you use both the -H and the -F options, then the sumfiles will be exactly
the same size as the largest of the segfiles.
-z, --block-size blocksize
This option sets the size (in bytes) of the blocks in which
ras processes data. This option has no effect on the data that's output,
it's provided for performance tweaking only. The default block size is
1024 bytes.
-V,--version
Print version information and exit
-h,--help
Print some help and exit
EXAMPLES
To generate sumfiles named sum0, sum1 and sum2 of segfiles named xaa, xab,
xac and xad in the current directory, using sumfile IDs 0, 1 and 2:
$ ras -c sum0 sum1 sum2
As above, but there is also a file called xae in the current directory that
we wish to ignore:
$ ras -c -n4 sum0 sum1 sum2
As above, but we wish sum0 to have an ID of 15, sum1 to have an ID of 1, and
sum2 to have an ID of 2:
$ ras -c -n4 sum0:15 sum1 sum2
As above, but we wish sum0 to have ID 45, sum1 to have ID 46 and sum2 to have
ID 47:
$ ras -cn4 -o45 sum0 sum1 sum2
As above, but the segfiles are called blk1, blk2, blk3 and blk4.
Note that we still need the -n4 in that last example, since we haven't
specified the name of the 5th segfile, so it stays at the default of
xae, which exists.
We want to restore 2 missing segfiles from a set of 5 named xaa, xab, xac,
xad and xae using whichever of the sumfiles named s0, s1, s2, s3 and s4 are
available:
$ ras s?
As above, but there may be no sumfiles, in which case we wish
ras to exit successfully if all the segfiles are there and to fail if any are
missing.
$ ras -n5 s?
Now for a slightly longer example: suppose we have a large file that we
wish to transport between two machines using 1.44Mb floppy discs. I'm
assuming that we've already compressed it, added a checksum and split it
into 1400000-byte chunks. The checksum is advisable because it's possible
that there's a bug in
ras that will silently corrupt the data. So, for example, we have three files of
size 1400000 bytes (called xaa, xab and xac) and a file of size 800000 bytes
called xad. We could put these on 4 floppies, but instead we choose to have
some redundancy, and use 6 floppies such that any 4 of the 6 will suffice.
We create 2 sumfiles...
$ ras -c sum0 sum1
Now we have 2 extra files, sum0 and sum1, both of size 1400006 bytes.
We add individual checksums to each of our 6 files and copy them to 6 floppies.
Suppose that when we get to the destination machine, we find that the floppies
holding xab and xac are corrupt. We can use
ras to regenerate xab and xac from xaa, xad, sum0 and sum1.
$ ras sum?
And finally we concatenate xa[abcd], check the checksum and so on. For a
more concrete example see the shell scripts rassplit and rasmerge,
(distributed with
ras ) for splitting a large file across multiple floppies with redundancy.