<h2 align=center>A program to attempt recovery of an x-file's contents</h2>
<p><dfn>X-Files</dfn> is an image filing system written by
<a href="mailto:andy@wonderworks.co.uk" subject="X-Files">Andy Armstrong</a>. Normal (filecore based) Risc OS filing systems are limited to 10 character leafnames and 77 files per directory. X-Files supports long filenames (up to 256 characters internally) and an unlimited number of files per directory, storing files in an x-file (which in other respects behaves like a "normal" directory).</p>
<p>Unfortunately X-Files is not totally robust, and can occasionally corrupt an x-file, which it will then refuse to open. Sod's law ensures that the data in the x-file is very important and not backed up anywhere else. This is where <code>x-recover</code> comes in; <code>x-recover</code> will <strong>attempt</strong> to make sense of and extract data from corrupted x-files.</p>
<h2 align=center><a name="!warranty">Important: x-recover comes with absolutely <blink>NO WARRANTY</blink></a></h2>
<p>This program is distributed in the hope that it will be useful, but <strong>without any warranty</strong>; without even the implied warranty of <strong>merchantability</strong> or <strong>fitness for a particular purpose</strong>. As <code>x-recover</code> is written in C it almost certainly breaks the rules somewhere, and hence is exhibiting "<dfn>undefined behaviour</dfn>". What this means in English is that it could do anything at all, including, but not limited to:
<ol><li>Working exactly as intended</li>
<li>Trashing your hard disc</li>
<li>Turning Barbara Cartland into a <a href="#goth">goth<sup>*</sup></a></li>
<p><code>x-file</code> is the pathname of the x-file to attempt to recover. <code>x-recover</code> does not check the filetype (so if <code>x-file</code> is not actually an x-file <code>x-recover</code> will generate copious warnings as it discovers this).</p>
<p><code>destination</code> is the pathname a directory (or empty x-file) to write recovered contents into. <code>destination</code> should exist, or use the <a href="#-c"><code>-c</code></a> option to create a new x-file with this name. <code>destination</code> can be omitted if file output is suppressed (<a href="#-g"><code>-g</code></a> or <a href="#-n"><code>-n</code></a> options).</p>
<h3>Options</h3>
<table><tr><th valign=top><a name="-a"><code>-a</code></a></th><td>extract the full chunk <strong>a</strong>llocated to the file, rather than the <a href="#size">length used</a>. Using this option causes the chunktable to be written out with a filename of the form <code>file####</code> [unless file output is suprressed with <a href="#-s"><code>-s</code></a>].</td></tr>
<tr><th valign=top><a name="-c"><code>-c</code></a></th><td><strong>c</strong>reate <code>destination</code> as an x-file if no directory/x-file of this name exists.</td></tr>
<tr><th valign=top><a name="-d"><code>-d</code></a></th><td>Output probable <strong>d</strong>irectories in raw binary form. See <a href="#rawdirs">directories</a>.</td></tr>
<tr><th valign=top><a name="-f"><code>-f</code></a></th><td>write out any <strong>f</strong>ree space between chunks. <code>x-recover -a -d -f -1</code> will output the entire x-file split into chunks, which if concatenated in numerical order will give the original x-file.<a href="#size"><sup>[see size]</sup></a></td></tr>
<tr><th valign=top><a name="-g"><code>-g</code></a></th><td><strong>g</strong>uess the location of the chunktable and the root directory. <code>x-recover</code> simply runs through the file looking areas that resemble the chunktable and the root directory. When used with the <code>-r</code> and <code>-t</code> options this allows recovery even when the file header is corrupted. This option suppresses all disc output.</td></tr>
<tr><th valign=top><a name="-n"><code>-n</code></a></th><td><strong>n</strong>o disc output. Integrity checks and errors are still reported to the screen.</td></tr>
<tr><th valign=top><a name="-r"><code>-r <offset></code></a></th><td>specify the offset of the <strong>r</strong>oot directory in <code>x-file</code>. Useful if the header becomes corrupted - see <a href="#header">header</a>.</td></tr>
<tr><th valign=top><a name="-s"><code>-s</code></a></th><td><strong>s</strong>uppress file output, but still create the directories (and free space) in <code>destination</code>. Mostly used for development purposes to quickly check that things are working without having to wait while files are copied, but <code>x-recover -1 -f -s</code> will only extract directories and free space between directories.</td></tr>
<tr><th valign=top><a name="-t"><code>-t <offset></code></a></th><td>specify the offset of the chunk<strong>t</strong>able in <code>x-file</code>. Useful if the header becomes corrupted - see <a href="#header">header</a>.</td></tr>
<tr><th valign=top><a name="-v"><code>-v</code></a></th><td><strong>v</strong>erbose info. <code>x-recover</code> prints out more information about what it is doing. Use more <code>v</code>s for more verbosity. [currently most verbose is <code>-vvvvv</code>]</td></tr>
<tr><th valign=top><code>-1</code></th><td>Use <a href="#method1"><strong>Method 1</strong></a> to attempt to recover <code>x-file</code>'s contents. The various methods are described below.</td></tr>
<tr><th valign=top><code>-2</code></th><td>Use <a href="#method2"><strong>Method 2</strong></a> to attempt to recover <code>x-file</code>'s contents. Method 2 is the current default.</td></tr>
</table>
<h3>The x-file structure, and how this affects the prognosis</h3>
<p>As the x-file file contains within itself data from other files, it must also store information about the contained files and their data. If an x-file becomes corrupted, it is likely that some of this housekeeping information is lost. The x-file structure is described here - which parts survive determines if recovery is possible, and if so the fidelity achievable.
<tr><td>An x-file starts with a header which contains a signature<!-- (<code>XFIL</code>) -->, version information and pointers to the chunktable and root directory. If the information stored in the header becomes corrupted it is possible to search for the chunktable using the <a href="#-g"><code>-g</code></a> option.</td></tr>
<tr><td>Except for the header all information in the x-file is stored in <dfn>chunks</dfn>. The index containing chunk sizes and positions is stored in the <dfn>chunktable</dfn> - clearly if the chunktable is missing then the x-file is simply an amorphous lump of data (like a corrupt hard disc). Currently <code>x-recover</code> doesn't have the knowledge to identify files from inspection of contents, so if the chunktable is missing automated recovery is not possible as <code>x-recover</code> cannot determine where one file stops and the next starts. If the chunktable is reasonably intact then <a href="#method1">Method 1</a> can be used to extract the contents of each chunk as separate files, but all name, filetype and datestamp information will be lost.</td></tr>
