diff options
Diffstat (limited to 'misc/par2cmdline/par2.1')
| -rw-r--r-- | misc/par2cmdline/par2.1 | 284 |
1 files changed, 284 insertions, 0 deletions
diff --git a/misc/par2cmdline/par2.1 b/misc/par2cmdline/par2.1 new file mode 100644 index 0000000000..b10f5e7f09 --- /dev/null +++ b/misc/par2cmdline/par2.1 @@ -0,0 +1,284 @@ +.\" +.\" par2(1) +.\" +.\" Copyright (C) 2004 Andres Salomon +.TH par2 1 "May 2004" +.SH NAME +par2 \- PAR 2.0 compatible file verification and repair tool. +.SH SYNOPSIS +.B par2 +c(reate) [options] <par2 file> [files] +.br +.B par2 +v(erify) [options] <par2 file> [files] +.br +.B par2 +r(epair) [options] <par2 file> [files] +.br + +.br + Or: +.br + +.br +.B par2create +[options] <par2 file> [files] +.br +.B par2verify +[options] <par2 file> [files] +.br +.B par2repair +[options] <par2 file> [files] +.SH DESCRIPTION +par2 is a program for creating and using PAR2 files to detect +damage in data files and repair them if necessary. It can be used with +any kind of file. +.SH OPTIONS +.TP +.B -b<n> +Set the Block-Count +.TP +.B -s<n> +Set the Block-Size (Don't use both -b and -s) +.TP +.B -r<n> +Level of Redundancy (%) +.TP +.B -c<n> +Recovery block count (don't use both -r and -c) +.TP +.B -f<n> +First Recovery-Block-Number +.TP +.B -u +Uniform recovery file sizes +.TP +.B -l +Limit size of recovery files (Don't use both -u and -l) +.TP +.B -n<n> +Number of recovery files (Don't use both -n and -l) +.TP +.B -m<n> +Memory (in MB) to use +.TP +.B -v [-v] +Be more verbose +.TP +.B -q [-q] +Be more quiet (-qq gives silence) +.TP +.B -- +Treat all remaining CommandLine as filenames +.TP +.BR +.SH EXAMPLES + +With PAR 2.0 you can create PAR2 recovery files for as few as 1 or as many as +32768 files. If you wanted to create PAR1 recovery files for a single file +you are forced to split the file into muliple parts and RAR is frequently +used for this purpose. You do NOT need to split files with PAR 2.0. + +To create PAR 2 recovery files for a single data file (e.g. one called +test.mpg), you can use the following command: + + par2 create test.mpg + +If test.mpg is an 800 MB file, then this will create a total of 8 PAR2 files +with the following filenames (taking roughly 6 minutes on a PC with a +1500MHz CPU): + + test.mpg.par2 - This is an index file for verification only + test.mpg.vol00+01.par2 - Recovery file with 1 recovery block + test.mpg.vol01+02.par2 - Recovery file with 2 recovery blocks + test.mpg.vol03+04.par2 - Recovery file with 4 recovery blocks + test.mpg.vol07+08.par2 - Recovery file with 8 recovery blocks + test.mpg.vol15+16.par2 - Recovery file with 16 recovery blocks + test.mpg.vol31+32.par2 - Recovery file with 32 recovery blocks + test.mpg.vol63+37.par2 - Recovery file with 37 recovery blocks + +The test.mpg.par2 file is 39 KB in size and the other files vary in size from +443 KB to 15 MB. + +These par2 files will enable the recovery of up to 100 errors totalling 40 MB +of lost or damaged data from the original test.mpg file when it and the par2 +files are posted on UseNet. + +When posting on UseNet it is recommended that you use the "-s" option to set +a blocksize that is equal to the Article size that you will use to post the +data file. If you wanted to post the test.mpg file using an article size +of 300 KB then the command you would type is: + + par2 create -s307200 test.mpg + +This will create 9 PAR2 files instead of 8, and they will be capable of +correcting up to 134 errors totalling 40 MB. It will take roughly 8 minutes +to create the recovery files this time. + +In both of these two examples, the total quantity of recovery data created +was 40 MB (which is 5% of 800 MB). If you wish to create a greater or lesser +quantity of recovery data, you can use the "-r" option. + +To create 10% recovery data instead of the default of 5% and also to use a +block size of 300 KB, you would use the following command: + + par2 create -s307200 -r10 test.mpg + +This would also create 9 PAR2 files, but they would be able to correct up to +269 errors totalling 80 MB. Since twice as much recovery data is created, it +will take about 16 minutes to do so with a 1500MHz CPU. + +The "-u" and "-n" options can be used to control exactly how many recovery +files are created and how the recovery blocks are distributed amoungst them. +They do not affect the total quantity of recovery data created. + +The "-f" option is used when you create additional recovery data. + +e.g. If you have already created 10% and want another 5% then you migh use +the following command: + + par2 create -s307200 -r5 -f300 test.mpg + +This specifies the same block size (which is a requirement for additional +recovery files), 5% recovery data, and a first block number of 300. + +The "-m" option controls how much memory par2 uses. It defaults to +16 MB unless you override it. + +CREATING PAR2 FILES FOR MULTIPLE DATA FILES + +When creating PAR2 recovery files form multiple data files, you must specify +the base filename to use for the par2 files and the names of all of the data +files. + +If test.mpg had been split into multiple RAR files, then you could use: + + par2 create test.mpg.rar.par2 test.mpg.part*.rar + +The files filename "test.mpg.rar.par2" says what you want the par2 files to +be called and "test.mpg.part*.rar" should select all of the RAR files. + +VERIFYING AND REPAIRING + +When using par2 recovery files to verify or repair the data files from +which they were created, you only need to specify the filename of one +of the par2 files to par2. + +e.g.: + + par2 verify test.mpg.par2 + +This tells par2 to use the information in test.mpg.par2 to verify the +data files. + +par2 will automatically search for the other par2 files that were +created and use the information they contain to determine the filenames +of the original data files and then to verify them. + +If all of the data files are ok, then par2 will report that repair +will not be required. + +If any of the data files are missing or damaged, par2 will report +the details of what it has found. If the recovery files contain enough +recovery blocks to repair the damage, you will be told that repair is +possible. Otherwise you will be told exactly how many recovery blocks +will be required in order to repair. + +To carry out a repair use the following command: + + par2 repair test.mpg.par2 + +This tells par2 to verify and if possible repair any damaged or +missing files. If a repair is carried out, then each file which is +repaired will be re-verified to confirm that the repair was successful. + +MISSNAMED AND INCOMPLETE DATA FILES + +If any of the recovery files or data files have the wrong filename, then +par2 will not automatically find and scan them. + +To have par2 scan such files, you must include them on the command +line when attempting to verify or repair. + +e.g.: + + par2 r test.mpg.par2 other.mpg + +This tells par2 to scan the file called other.mpg to see if it +contains any data belonging to the original data files. + +If one of the extra files specified in this way is an exact match +for a data file, then the repair process will rename the file so that +it has the correct filename. + +Because par2 is designed to be able to find good data within a +damaged file, it can do the same with incomplete files downloaded from +UseNet. If some of the articles for a file are missing, you should still +download the file and save it to disk for par2 to scan. If you +do this then you may find that you can carry out a repair in a situation +where you would not otherwise have sufficient recovery data. + +You can have par2 scan all files that are in the current directory +using a command such as: + + par2 r test.mpg.par2 * + +WHAT TO DO WHEN YOU ARE TOLD YOU NEED MORE RECOVERY BLOCKS + +If par2 determines that any of the data files are damaged or +missing and finds that there is insufficient recovery data to effect +a repair, you will be told that you need a certain number of recovery +blocks. You can obtain these by downloading additional recovery files. + +In order to make things easy, par2 files have filenames that tell you +exactly how many recovery blocks each one contains. + +Assuming that the following command was used to create recovery data: + + par2 c -b1000 -r5 test.mpg + +Then the recovery files that are created would be called: + + test.mpg.par2 + test.mpg.vol00+01.par2 + test.mpg.vol01+02.par2 + test.mpg.vol03+04.par2 + test.mpg.vol07+08.par2 + test.mpg.vol15+16.par2 + test.mpg.vol31+19.par2 + +The first file in this list does not contain any recovery data, it only +contains information sufficient to verify the data files. + +Each of the other files contains a different number of recovery blocks. +The number after the '+' sign is the number of recovery blocks and the +number preceding the '+' sign is the block number of the first recovery +block in that file. + +If par2 told you that you needed 10 recovery blocks, then you would +need "test.mpg.vol01+02.par2" and "test.mpg.vol07+08.par". You might of course +choose to fetch "test.mpg.vol15+16.par2" instead (in which case you would have +an extra 6 recovery blocks which would not be used for the repair). + +.SH NOTES + +This version of par2 does not support recording path information for +files. Whilst you can create recovery files for files from multiple locations, +it will expect all files to be in the current directory when verifying and +repairing. This limitation will be corrected in an update. + +.SH REED SOLOMON CODING + +PAR2 uses Reed Solomon Coding to perform its calculations. For details of this +coding technique try 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> + +.SH AUTHOR +.br +.B par2 +was written by Peter Brian Clements <peterbclements@users.sourceforge.net>. + +This man page was contributed by Andres Salomon <dilinger@voxel.net> +for the Debian GNU/Linux system (but may be used by others). |