.TH RAS 1 "1998 Jan 30"
.SH NAME
ras \- redundant archive system
.SH SYNOPSIS
.B ras
.RB [ -r ]
.RB [ -b | -v | -s ]
.RB [ -HF ]
.RB [ -f
.IR segfile "] ..."
.RB [ -n
.IR segcount ]
.RI [ sumfile "] ..."
.br
.B ras -c 
.RB [ -b | -v | -s ]
.RB [ -HF ]
.RB [ -f
.IR segfile "] ..."
.RB [ -n
.IR segcount ]
.RB [ -z
.IR blocksize ]
.RB [ -o
.IR offset ]
.RI [ sumfile [: sumspec "]] ..."
.SH DESCRIPTION
.B 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. 
.PP
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
.B 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.
.SH OPTIONS
.TP
.B \-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.
.TP
.B \-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.
.TP
.B \-b,--brief
Output only a 1-line summary of what's going on to standard output. This
is the default level of verbosity.
.TP
.B \-v,--verbose
Output some more detailed information to standard output.
.TP
.B \-s,--silent
Output nothing to standard output.
.TP
.B \-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 
.B 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 
.BR split (1)
.TP
.B \-n,--segcount segcount
This option allows the segcount to be specified on the command line.  This
option is not normally needed since
.B 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.
.TP
.B \-o,--offset offset
When creating sumfiles, this option causes
.B ras
to start from offset instead of 0 when assigning IDs to sumfiles. See
EXAMPLES below. Ignored when in restore mode.
.TP
.B \-H,--no-header
.B 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 
.B 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.
.sp
If you use this option you must keep track of segcount and the sumfile
IDs yourself. When restoring you must tell
.B 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, 
.B 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.
.sp
In summary, don't use this option unless you really need to get rid of the
5 byte header overhead.
.TP
.B \-F,--no-footer
.B ras
normally appends a 1-byte footer to each sumfile created. This option
suppresses this footer in create mode, and tells 
.B 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.
.sp
The function of the footer is to allow 
.B 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.
.sp
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.
.TP
.B \-z, --block-size blocksize
This option sets the size (in bytes) of the blocks in which 
.B 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.
.TP
.B \-V,--version
Print version information and exit
.TP
.B \-h,--help
Print some help and exit
.SH 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:
.PP
$ ras -c sum0 sum1 sum2
.PP
As above, but there is also a file called xae in the current directory that
we wish to ignore:
.PP
$ ras -c -n4 sum0 sum1 sum2
.PP
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:
.PP
$ ras -c -n4 sum0:15 sum1 sum2
.PP
As above, but we wish sum0 to have ID 45, sum1 to have ID 46 and sum2 to have
ID 47:
.PP
$ ras -cn4 -o45 sum0 sum1 sum2
.PP
As above, but the segfiles are called blk1, blk2, blk3 and blk4.
.PP
$ ras -cn4 -o45 -fblk1 -fblk2 -fblk3 -fblk4 sum0 sum1 sum2
.PP
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.
.PP
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:
.PP
$ ras s?
.PP
As above, but there may be no sumfiles, in which case we wish
.B ras
to exit successfully if all the segfiles are there and to fail if any are
missing.
.PP
$ ras -n5 s?
.PP
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 
.B 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...
.PP
$ ras -c sum0 sum1
.PP
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
.B ras
to regenerate xab and xac from xaa, xad, sum0 and sum1.
.PP
$ ras sum?
.PP
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 
.BR ras )
for splitting a large file across multiple floppies with redundancy.
.SH "SEE ALSO"
rassplit(1), rasmerge(1)
.SH AUTHOR
Nick Cleaton <nick@cleaton.net>