Parity Archive - A way to restore missing files in a set.

Copyright (C) 2001  Willem Monsuwe (willem@stack.nl)

The source code can be downloaded from parchive.sourceforge.net
as par-v0.2alpha.tar.gz

This version is released under the GNU Public License.
See the file COPYING (in the source code archive) for details.

File format by Stefan Wehlus -
 initial idea by Tobias Rieper, further suggestions by Kilroy Balore 

Beta release, version 0.9


DESCRIPTION:

This version uses Reed-Solomon coding to make multiple parity volumes from
the same set of files.
What this means is that you can recover as many files as you have recovery
volumes.  Any recovery volumes for that set will do.


TYPICAL EXAMPLE OF USE:

You are uploading a rar-archive, Archive.rar to a newsgroup, split into 40
files.  You decide to make a parity archive with five recovery volumes:

>par add -n5 Archive.PAR Archive.r??

You machine rattles for a minute or two, resulting in one (small)
Archive.PAR file, and five files Archive.P01 - P05.  You upload these.

People download your files, and the Archive.PAR file to check if they
downloaded correctly.  Someone runs par to check if he got all files:

>par check Archive.PAR

It reports that three files are missing, and he would need three parity
volumes to recover them.  He tries to download these, and he gets
Archive.P02, .P04 and .P05.  Then he runs par to recover those files:

>par recover Archive.PAR

His machine rattles for a minute or two, and all his files are restored.


HINT FOR WINDOWS USERS:

If you make a file 'par.bat' which contains the following line:

 par.exe r -- %1

You can associate this with .par files, so it will automatically
recover files from the .par file you doubleclick on.


NOTES:

- This version of par never overwrites an existing file.  It can, however,
move files out of the way (with the -m flag)

- Par will also search for files with different filenames (by the md5
checksum), and can give those files their correct name (with -f)
Searching for missing files could take some time, if there are lots of
files in the directory

- Par will only work with files in the current directory.

- Par can try to recover files using parity volumes from different sources:

>par m

This has a pretty decent chance of working, but it's not guaranteed to work.
It will try to locate every single parity volume in the current directory,
throwing them together to try to recover as many files from them as possible.
If you use this in a large dir, Par might try to open too many files and fail.


REED-SOLOMON CODING:

The file rs.doc contains sort of an explanation on how the encoding works.
Also, all Reed-Solomon related stuff is in one file, rs.c, with a single
interface function.  This should make it easy to write different RS-based
recovery archive programs.

You can look at the following link:
``A Tutorial on Reed-Solomon Coding for Fault-Tolerance in RAID-like Systems''
<http://www.cs.utk.edu/~plank/plank/papers/CS-96-332.html>


TODO:

- Write a better explanation of how Reed-Solomon coding works (see rs.doc)
- Check if it compiles on something like a PPC (non-aligned access issues)


COMPILING:

You're pretty much on your own here.
There's a small Makefile, and the code uses as few special things as possible.
GCC should be able to compile it on most Unices.

It also compiles for MS-DOS, using DJGPP (http://www.delorie.com/djgpp/) and
it's been tested on a Win98SE box.

As this is a testing version, and the spec is going to change soon, not
much effort has been made for portability.