1libpar2 is a library for par2, extracted from par2cmdline 0.4. It depends on libsigc++. 2 3To install, use the classic 4 -> ./configure 5 -> make 6 -> make install 7 8 9 10By default, the lib will install in /usr/local/lib, so you need to be sure that your ld is well configured: 11 12 -> Edit your /etc/ld.so.conf, and check that there is a line "/usr/local/lib" (if it is not present, add it) 13 -> execute 'ldconfig' 14 15 16 17 18 19par2cmdline README follows : 20 21------------------------------------------------------------- 22 23par2cmdline is a PAR 2.0 compatible file verification and repair tool. 24 25See http://parchive.sourceforge.net for details of PAR 2.0 specification 26and discussion of all things PAR. 27 28WHAT EXACTLY IS PAR2CMDLINE? 29 30par2cmdline is a program for creating and using PAR2 files to detect 31damage in data files and repair them if necessary. It can be used with 32any kind of file. 33 34WHY IS PAR 2.0 better than PAR 1.0? 35 36 * It is not necessary to split a single large file into many equally 37 size small files (although you can still do so if you wish). 38 39 * There is no loss of efficiency when operating on multiple files 40 of different sizes. 41 42 * It is possible to repair damaged files (using exactly the amount of 43 recovery data that corresponds to the amount of damage), rather than 44 requiring the complete reconstruction of the damaged file. 45 46 * Recovery files may be of different sizes making it possible to 47 obtain exactly the amount of recovery data required to carry out 48 a repair. 49 50 * Because damaged data files are still useable during the recovery 51 process, less recovery data is required to achieve a successfull 52 repair. It is not therefore necessary to create as much recovery 53 data in the first place to achieve the same level of protection. 54 55 * You can protect up to 32768 files rather than the 256 that PAR 1.0 56 is limited to. 57 58 * Damaged or incomplete recovery files can also be used during the 59 recovery process in the same way that damaged data files can. 60 61 * You require less recovery data to provide the same level of protection 62 from damage compared with PAR 1.0. 63 64DOES PAR 2.0 HAVE ANY DISSADVANTAGES? 65 66Yes, there is one dissadvantage: 67 68 * All PAR 2.0 program will take somewhat longer to create recovery 69 files than a PAR 1.0 program does. 70 71This dissadvantage is considerably mitigated by the fact that you don't 72need to create as much recovery data in the first place to provide the 73same level of protection against loss and damage. 74 75COMPILING PAR2CMDLINE 76 77You should have received par2cmdline in the form of source code which 78you can compile on your computer. You may optionally have received a 79pre-compiled version of the program for your operating system. 80 81If you have only downloaded a precompiled executable, then the source 82code should be available from the same location that you downloaded the 83executable from. 84 85If you have MS Visual Studio .NET, then just open the par2cmdline.sln 86file and compile. You should then copy par2cmdline.exe to an appropriate 87location that is on your path. 88 89To compile on Linux and other unix variants use the following commands: 90 91 ./configure 92 make 93 make check 94 make install 95 96See INSTALL for full details of how to use the "configure" script. 97 98USING PAR2CMDLINE 99 100The command line parameters for par2cmdline are as follow: 101 102 par2 c(reate) [options] <par2 file> [files] 103 par2 v(erify) [options] <par2 file> [files] 104 par2 r(epair) [options] <par2 file> [files] 105 106 Also: 107 108 par2create [options] <par2 file> [files] 109 par2verify [options] <par2 file> [files] 110 par2repair [options] <par2 file> [files] 111 112 Options: 113 114 -b<n> : Set the Block-Count 115 -s<n> : Set the Block-Size (Don't use both -b and -s) 116 -r<n> : Level of Redundancy (%) 117 -c<n> : Recovery block count (don't use both -r and -c) 118 -f<n> : First Recovery-Block-Number 119 -u : Uniform recovery file sizes 120 -l : Limit size of recovery files (Don't use both -u and -l) 121 -n<n> : Number of recovery files (Don't use both -n and -l) 122 -m<n> : Memory (in MB) to use 123 -v [-v]: Be more verbose 124 -q [-q]: Be more quiet (-qq gives silence) 125 -- : Treat all remaining CommandLine as filenames 126 127If you wish to create par2 files for a single source file, you may leave 128out the name of the par2 file from the command line. par2cmdline will then 129assume that you wish to base the filenames for the par2 files on the name 130of the source file. 131 132You may also leave off the .par2 file extension when verifying and repairing. 133 134CREATING PAR2 FILES 135 136With PAR 2.0 you can create PAR2 recovery files for as few as 1 or as many as 13732768 files. If you wanted to create PAR1 recovery files for a single file 138you are forced to split the file into muliple parts and RAR is frequently 139used for this purpose. You do NOT need to split files with PAR 2.0. 140 141To create PAR 2 recovery files for a single data file (e.g. one called 142test.mpg), you can use the following command: 143 144 par2 create test.mpg 145 146If test.mpg is an 800 MB file, then this will create a total of 8 PAR2 files 147with the following filenames (taking roughly 6 minutes on a PC with a 1481500MHz CPU): 149 150 test.mpg.par2 - This is an index file for verification only 151 test.mpg.vol00+01.par2 - Recovery file with 1 recovery block 152 test.mpg.vol01+02.par2 - Recovery file with 2 recovery blocks 153 test.mpg.vol03+04.par2 - Recovery file with 4 recovery blocks 154 test.mpg.vol07+08.par2 - Recovery file with 8 recovery blocks 155 test.mpg.vol15+16.par2 - Recovery file with 16 recovery blocks 156 test.mpg.vol31+32.par2 - Recovery file with 32 recovery blocks 157 test.mpg.vol63+37.par2 - Recovery file with 37 recovery blocks 158 159The test.mpg.par2 file is 39 KB in size and the other files vary in size from 160443 KB to 15 MB. 161 162These par2 files will enable the recovery of up to 100 errors totalling 40 MB 163of lost or damaged data from the original test.mpg file when it and the par2 164files are posted on UseNet. 165 166When posting on UseNet it is recommended that you use the "-s" option to set 167a blocksize that is equal to the Article size that you will use to post the 168data file. If you wanted to post the test.mpg file using an article size 169of 300 KB then the command you would type is: 170 171 par2 create -s307200 test.mpg 172 173This will create 9 PAR2 files instead of 8, and they will be capable of 174correcting up to 134 errors totalling 40 MB. It will take roughly 8 minutes 175to create the recovery files this time. 176 177In both of these two examples, the total quantity of recovery data created 178was 40 MB (which is 5% of 800 MB). If you wish to create a greater or lesser 179quantity of recovery data, you can use the "-r" option. 180 181To create 10% recovery data instead of the default of 5% and also to use a 182block size of 300 KB, you would use the following command: 183 184 par2 create -s307200 -r10 test.mpg 185 186This would also create 9 PAR2 files, but they would be able to correct up to 187269 errors totalling 80 MB. Since twice as much recovery data is created, it 188will take about 16 minutes to do so with a 1500MHz CPU. 189 190The "-u" and "-n" options can be used to control exactly how many recovery 191files are created and how the recovery blocks are distributed amoungst them. 192They do not affect the total quantity of recovery data created. 193 194The "-f" option is used when you create additional recovery data. 195 196e.g. If you have already created 10% and want another 5% then you migh use 197the following command: 198 199 par2 create -s307200 -r5 -f300 test.mpg 200 201This specifies the same block size (which is a requirement for additional 202recovery files), 5% recovery data, and a first block number of 300. 203 204The "-m" option controls how much memory par2cmdline uses. It defaults to 20516 MB unless you override it. 206 207CREATING PAR2 FILES FOR MULTIPLE DATA FILES 208 209When creating PAR2 recovery files form multiple data files, you must specify 210the base filename to use for the par2 files and the names of all of the data 211files. 212 213If test.mpg had been split into multiple RAR files, then you could use: 214 215 par2 create test.mpg.rar.par2 test.mpg.part*.rar 216 217The files filename "test.mpg.rar.par2" says what you want the par2 files to 218be called and "test.mpg.part*.rar" should select all of the RAR files. 219 220VERIFYING AND REPAIRING 221 222When using par2 recovery files to verify or repair the data files from 223which they were created, you only need to specify the filename of one 224of the par2 files to par2cmdline. 225 226e.g.: 227 228 par2 verify test.mpg.par2 229 230This tells par2cmdline to use the information in test.mpg.par2 to verify the 231data files. 232 233par2cmdline will automatically search for the other par2 files that were 234created and use the information they contain to determine the filenames 235of the original data files and then to verify them. 236 237If all of the data files are ok, then par2cmdline will report that repair 238will not be required. 239 240If any of the data files are missing or damaged, par2cmdline will report 241the details of what it has found. If the recovery files contain enough 242recovery blocks to repair the damage, you will be told that repair is 243possible. Otherwise you will be told exactly how many recovery blocks 244will be required in order to repair. 245 246To carry out a repair use the following command: 247 248 par2 repair test.mpg.par2 249 250This tells par2cmdline to verify and if possible repair any damaged or 251missing files. If a repair is carried out, then each file which is 252repaired will be re-verified to confirm that the repair was successful. 253 254MISSNAMED AND INCOMPLETE DATA FILES 255 256If any of the recovery files or data files have the wrong filename, then 257par2cmdline will not automatically find and scan them. 258 259To have par2cmdline scan such files, you must include them on the command 260line when attempting to verify or repair. 261 262e.g.: 263 264 par2 r test.mpg.par2 other.mpg 265 266This tells par2cmdline to scan the file called other.mpg to see if it 267contains any data belonging to the original data files. 268 269If one of the extra files specified in this way is an exact match 270for a data file, then the repair process will rename the file so that 271it has the correct filename. 272 273Because par2cmdline is designed to be able to find good data within a 274damaged file, it can do the same with incomplete files downloaded from 275UseNet. If some of the articles for a file are missing, you should still 276download the file and save it to disk for par2cmdline to scan. If you 277do this then you may find that you can carry out a repair in a situation 278where you would not otherwise have sufficient recovery data. 279 280You can have par2cmdline scan all files that are in the current directory 281using a command such as: 282 283 par2 r test.mpg.par2 * 284 285WHAT TO DO WHEN YOU ARE TOLD YOU NEED MORE RECOVERY BLOCKS 286 287If par2cmdline determines that any of the data files are damaged or 288missing and finds that there is insufficient recovery data to effect 289a repair, you will be told that you need a certain number of recovery 290blocks. You can obtain these by downloading additional recovery files. 291 292In order to make things easy, par2 files have filenames that tell you 293exactly how many recovery blocks each one contains. 294 295Assuming that the following command was used to create recovery data: 296 297 par2 c -b1000 -r5 test.mpg 298 299Then the recovery files that are created would be called: 300 301 test.mpg.par2 302 test.mpg.vol00+01.par2 303 test.mpg.vol01+02.par2 304 test.mpg.vol03+04.par2 305 test.mpg.vol07+08.par2 306 test.mpg.vol15+16.par2 307 test.mpg.vol31+19.par2 308 309The first file in this list does not contain any recovery data, it only 310contains information sufficient to verify the data files. 311 312Each of the other files contains a different number of recovery blocks. 313The number after the '+' sign is the number of recovery blocks and the 314number preceding the '+' sign is the block number of the first recovery 315block in that file. 316 317If par2cmdline told you that you needed 10 recovery blocks, then you would 318need "test.mpg.vol01+02.par2" and "test.mpg.vol07+08.par". You might of course 319choose to fetch "test.mpg.vol15+16.par2" instead (in which case you would have 320an extra 6 recovery blocks which would not be used for the repair). 321 322NOTES 323 324This version of par2cmdline does not support recording path information for 325files. Whilst you can create recovery files for files from multiple locations, 326it will expect all files to be in the current directory when verifying and 327repairing. This limitation will be corrected in an update. 328 329REED SOLOMON CODING 330 331PAR2 uses Reed Solomon Coding to perform its calculations. For details of this 332coding technique try the following link: 333 334``A Tutorial on Reed-Solomon Coding for Fault-Tolerance in RAID-like Systems'' 335<http://www.cs.utk.edu/~plank/plank/papers/CS-96-332.html> 336