<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>BFS-tools - Documentation</title>
</head>
<body bgcolor=white link="black" vlink="#333333">
<table border=0 cellspacing=0 cellpadding=0><tr><td width="160" bgcolor="#eeeeee" valign=top>
	<table border=0 cellpadding=0 cellspacing=0> <tr><td height="15"></td></tr></table>
	<div align=center>
	<img src="images/slogo.png" alt="pinc Software">
	</div>
	<table border=0 cellpadding=0 cellspacing=0> <tr><td height="30"></td></tr></table>
	<ul>
		<li><a href="#intro">Introduction</a></li><p></p>
		<li><a href="#bfsinfo">bfsinfo</a></li>
		<li><a href="#bfswhich">bfswhich</a></li>
		<li><a href="#chkindex">chkindex</a></li>
		<li><a href="#recover">recover</a></li>
		<li><a href="#copy_to_bfs_image">copy_to_bfs_image</a></li>
		<p></p>
		<li><a href="#tips">Tips & Tricks</a></li>
		<li><a href="#issues">Known Issues</a></li>
		<li><a href="#history">History</a></li>
		<li><a href="#author">Author</a></li>
		<li><a href="#disclaimer">Disclaimer</a></li>
	</ul>
</td><td width=10>&nbsp;</td>
<td valign=top>
<p>
<table border=0 cellspacing=0 cellpadding=0><tr>
<td><img src="images/bfstools.png"></td><td><b><font size="+6">&nbsp;BFS-tools 0.7.6</font></b><font size="+3"> (May 25th, 2004)</font></td>
</tr></table>
<br>
<font size=1>Copyright &copy;2001-2004 pinc Software. All Rights Reserved</font>
</p>
<hr>
<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="intro">Introduction</a></h1></td>
	<td align=right><font size="+2"><a href="#bfsinfo">&darr;</a>&nbsp;</font></td>
</tr></table>
<p>
	This is a collection of some command line BFS tools. Most programs are currently
	non-destructive - for example, that means that you can't repair an unmountable
	volume, but you may be able to copy all files left to another disk.
</p>
<p>
	The following tools are included:
	<ul>
		<li><b><a href="#bfsinfo">bfsinfo</a></b> you can use this program to get some
			information about the underlying structure of your BFS disk.</li>
		<li><b><a href="#bfswhich">bfswhich</a></b> can tell you which file covers
			the specified location.</li>
		<li><b><a href="#chkindex">chkindex</a></b> can be used to check the integrity
			and validity of the indices on your BFS disk.</li>
		<li><b><a href="#recover">recover</a></b> is the most complex program of the
			collection - it can be used to recover data on corrupt BFS disks which you
			can't even mount.</li>
		<li><b><a href="#copy_to_bfs_image">copy_to_bfs_image</a></b> is currently the
			only destructive tool. It allows you to copy files to BFS volumes that
			are not mounted; don't mind, it really has a useful purpose.</li>
	</ul>
</p>
<p>
	I began writing the <b>recover</b> tool because I really needed such a tool - I
	had a defective memory stick in my computer, which rarely produced crashes, but
	even a memory test program couldn't find any faults (don't trust the c't ram checker
	- it's probably to slow to be able to trigger such errors).
</p>
<p>
	Since I played around with some betas at that time, I didn't realize it at first,
	but after one of these crashes, I couldn't boot into BeOS anymore. After having
	booted from a CD, I was confrontated with 3 unmountable BFS partitions on two
	different harddisks - needless to say, that I used to backup the files on the other
	harddisk first; my latest CD backup was some month old.
</p>
<p>
	Luckily, I had bought a copy of <i>"Practical File System Design With The Be File System"</i>
	written by BFS creator Dominic Giampaolo himself a couple of weeks before (it has been
	published by <i>Morgan &amp; Kaufmann</i>. So I backed out from the real world for some
	time, sitting in front of my other computer, and wrote an early version of <b>recover</b>
	which repaired my backup &amp; mp3 partition, and recovered almost all files from my main
	partition some time later - I never doubted that I could recover my data (that was a bit
	na&iuml;ve, yes), but since there were several 1,000 blocks overwritten with some strange
	pattern, I had much luck that I didn't lose anything really important (just some mail and
	the latest version of BeMail, which I found as a gcc temp file on the disk some time later :-).
</p>
<p>
	You may wonder why I have disabled the repair capabilities from <b>recover</b>; it's just
	not that mature, that you could just run that program to fix every disk out there - the
	drawback is that you need some space to recover your data; I needed to kill my QNX, and
	Linux partitions for this. But I know people; they would first try the desctructive way,
	and if that couldn't help, they would just try to recover their files - which may work
	not that good anymore, because of the failed repair process earlier. But with the upcoming
	releases I will also include really destructive programs, too, for your convenience.
</p>
<p>
	Enough of boring stories, the following is a description of the tools I extracted from
	the codebase. At some point in the future, you may also find some GUI applications here,
	but not now, I am sorry.
</p>
<hr>
<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="bfsinfo">bfsinfo</a></h1></td>
	<td align=right><font size="+2"><a href="#bfswhich">&darr;</a><a href="#intro">&uarr;</a></font></td>
</tr></table>
<p>
	<b><i>Synopsis:</i></b> <b>bfsinfo</b> <b>[-srib]</b> <i>device</i> <b>[</b><i>allocation_group start</i><b>]</b>
</p>
<p>
	<b><i>Description:</i></b> With <b>bfsinfo</b> you can have a look at the
	underlaying data structures in your BFS disk.<br>
	You can dump the disk's super block which holds some general information
	about the disk (its size, etc.), every i-node you know the location of,
	and the B+Tree that holds the directory and indices data.
</p>
<p>
	<b><i>Options:</i></b>
	<ul>
		<li><b>-s</b> dumps the whole super block structure, instead of just some info</li>
		<li><b>-r</b> dumps the disk's root inode structure</li>
		<li><b>-i</b> dumps an arbitrary inode structure - this needs the allocation group
			and start parameters</li>
		<li><b>-b</b> dumps the whole B+Tree of a directory, this also needs the allocation
			group and start parameters. Note that not every node of the tree can be dumped
			nicely, so it's just normal that there are some strange looking ones in there</li>
	</ul>
</p>
<p>
	<b><i>Examples:</i></b><br><br>
	To get general idea about a disk:
	<pre><b>&gt; bfsinfo /dev/disk/ide/ata/0/master/0/0_1</b></pre>
		
	Then you know that the root directory is at (8,0), and you want to dump
	its contents:
	<pre><b>&gt; bfsinfo -ib /dev/disk/ide/ata/0/master/0/0_1 8 0</b></pre>
	<code>8,0</code> would also be accepted, or even
	<pre><b>&gt; bfsinfo -ib /boot 524288</b></pre>
	if the block run (8,0) is on that block on your boot disk.
	<p>
	Note: you can insert the real path to your partition or image file, the
	mount point (i.e. /boot/) to specify a particular disk. You can use the
	<b>df</b> command to learn which device serves which disk where.
</p>
<hr>
<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="bfswhich">bfswhich</a></h1></td>
	<td align=right><font size="+2"><a href="#chkindex">&darr;</a><a href="#bfsinfo">&uarr;</a></font></td>
</tr></table>
<p>
	<b><i>Synopsis:</i></b> <b>bfswhich</b> <i>device</i> <i>allocation_group start</i>
</p>
<p>
	<b><i>Description:</i></b> <b>bfswhich</b> scans all files on disk and can tell
	you which is covering the block you specified in the arguments.<br>
	Note, scanning the whole disk takes some time. For example, you can use this 
	tool in combination with <b>chkbfs</b> to find out which files claiming the
	same space on disk (if that error has been reported).
</p>
<p>
	<b><i>Options:</i></b>
	<ul>
		<li><i>none</i></li>
	</ul>
</p>
<p>
	<b><i>Examples:</i></b><br><br>
	To find out which file covers the block 1234567 on your boot disk:
	<pre><b>&gt; bfswhich /boot 1234567</b></pre>
	To specify the block or block run, you have the same possibilities as the
	<a href="#bfsinfo">bfsinfo</a> command provides.
</p>
<hr>
<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="chkindex">chkindex</a></h1></td>
	<td align=right><font size="+2"><a href="#recover">&darr;</a><a href="#bfswhich">&uarr;</a></font></td>
</tr></table>
<p>
	<b><i>Synopsis:</i></b> <b>chkindex</b> <b>[-ifa]</b> <b>[</b><i>index_name</i><b>]</b>
</p>
<p>
	<b><i>Description:</i></b> With <b>chkindex</b> you can validate the indices on
	your disk and check if they are covering all the files they should.<br>
	It will check if the B+Tree structure itself is okay or not, if there are any
	files in the index that don't exist anymore on disk (which happens sometimes,
	but that doesn't harm your system in any way - and those files won't even be
	visible from a query).<br>
	Furthermore, it will check if the index has the complete file table indexed,
	and it will print out every file that's missing - this check can take a lot
	of time. To add missing files to an index, you can use the
	<b><a href="http://www.bebits.com/app/2033">reindex</a></b>
	tool, which is available separately, and for free.<br>
	It's usage is not like the other tools, but it's more or less the same as the
	<b>mkindex</b>, <b>lsindex</b> commands that are part of BeOS.
</p>
<p>
	<b><i>Options:</i></b>
	<ul>
		<li><b>-i</b> disables to check for non-existing files in the index</li>
		<li><b>-f</b> do not check if all the files are in the index</li>
		<li><b>-a</b> check all indices on disk - when you are specifying that
			option, you don't need the <i>index_name</i> parameter anymore. Note
			that this check can be really slow, depending on how many files are
			on the partition and how many files are in the different indices.</li>
	</ul>
</p>
<p>
	<b><i>Examples:</i></b><br><br>
	First, we have to change the directory to one which is on the disk we want
	to operate on:
	<pre><b>&gt; cd /mp3s/</b></pre>
	<pre><b>&gt; chkindex Audio:Artist</b></pre>
	The last call will perform a full check of that index, which will probably
	take some minutes. However, the following call will need much more time:
	<pre><b>&gt; chkindex -a</b></pre>
	This will perform a full check on all indices on that disk. The output of
</p>

<hr>

<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="recover">recover</a></h1></td>
	<td align=right><font size="+2"><a href="#copy_to_bfs_image">&darr;</a><a href="#chkindex">&uarr;</a></font></td>
</tr></table>
<p>
	<b><i>Synopsis:</i></b> <b>recover</b> <b>[-id]</b> <b>[-r [</b><i>start_offset</i><b>] [</b><i>end_offset</i><b>]]</b> <i>device</i> <b>[</b><i>recover_target_path</i><b>]</b>
</p>
<p>
	<b><i>Description:</i></b> The <i>device</i> parameter is the most important one: that's the defective BFS
	partition where you want to recover files from, it doesn't even have to be a
	real device, it can also be an image file.<br>
	The program will first try to recreate the disk's super block if necessary, to
	be able to work with that disk. After this, it will scan the whole disk (even
	the log area) for inodes which are all collected.<br>
	Then, the whole disk structure will be checked and rebuilt when required. It
	will try to recreate missing anchors, and it is so smart to look if any of
	them were mirrored the log area, and it will scan through the name index to
	be able to determine the name for every file, as many as possible.<br>
	If you have selected a <i>recover_target_path</i> it will recreate the disk
	structure under that path, and will copy all files including their attributes
	to that target.
</p>
<p>
	<b><i>Options:</i></b>
	<ul>
		<li><b>-i</b> recreate all indices on target disk</li>
		<li><b>-d</b> dump missing and recreated i-node structures</li>
		<li><b>-r</b> operates on the raw disk - the whole disk will be scanned
			for BFS disks first, you will then be able to choose one of those.
			If you know approximately where your partition has been on disk, you
			can use the <i>start_offset</i> and <i>end_offset</i> parameters which
			define the range that will be scanned in bytes.<br>
			Note, this option needs much time to scan the disk.</li>
	</ul>
</p>
<p>
	<b><i>Examples:</i></b>
	The following command will copy all files of <i>"Broken-System.image"</i> under
	<i>/boot/home/recovered/</i>:
	<pre><b>&gt; recover Broken-System.image /boot/home/recovered</b></pre>
	If there is a directory <i>"home"</i> in the root of the image file, and it can
	be recovered, then it will be created in <i>/boot/home/recovered/home</i>.
</p>

<hr>

<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="copy_to_bfs_image">copy_to_bfs_image</a></h1></td>
	<td align=right><font size="+2"><a href="#tips">&darr;</a><a href="#recover">&uarr;</a></font></td>
</tr></table>
<p>
	<b><i>Synopsis:</i></b> <b>copy_to_bfs_image</b> <b>[-p]</b> <i>source_files</i> <b>[</b><i>...</i><b>]</b> <i>target_path</i>
</p>
<p>
	<b><i>Description:</i></b>
	This command allows you to copy files to an unmounted disk image. The image must
	not only be not mounted, you also have to make sure that all caches have been
	written back. It can be used to work around the BeOS cache consistency problem
	for image files; i.e. if you are needing files on a BFS image to work with them
	in an application like Bochs, you can use it to copy your files, and you won't
	need to reboot in order to have a consistent image.
</p>
<p>
	If you have the partition on disk, there is no need to use this tool and you
	can safely mount the partition to copy the files.
</p>
<p>
	<b><i>Options:</i></b>
	<ul>
		<li><b>-p</b> The target path will be created if necessary</li>
	</ul>
</p>
<p>
	<b><i>Examples:</i></b>
	Copy a new boot loader to a BFS image called <i>"openbeos.image"</i>:
	<pre><b>&gt; copy_to_bfs_image openbeos.image zbeos beos/system/</b></pre>
	If the path <i>"beos/system"</i> doesn't yet exist on the image, you should
	use the <b>-p</b> option in order to create it automatically.
</p>

<hr>

<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="tips">Tips & Tricks</a></h1></td>
	<td align=right><font size="+2"><a href="#issues">&darr;</a><a href="#copy_to_bfs_image">&uarr;</a></font></td>
</tr></table>

	<h3>Specifying the Volume to work on</h3>
<p>
	As written above, almost all tools allow you to specify the volume in different
	ways, for example:

	<dl><dt><pre><b>&gt; bfsinfo /dev/disk/ide/ata/0/master/0/0_1</b></pre></dt>
		<dd><i>(by device name)</i></dd>
		<dt><pre><b>&gt; bfsinfo /boot</b></pre></dt>
		<dd><i>(by mount point)</i></dd>
		<dt><pre><b>&gt; bfsinfo bfs.image</b></pre></dt>
		<dd><i>(by path to an image)</i></dd>
	</dl>
	Any exceptions are part of the documentation of the tool in question. <b>recover</b>
	also allows you to work on raw disks, while <b>copy_to_bfs_image</b> only supports
	image files.
</p>
<p>
	If you are issuing any of the above commands on mounted volumes, you should
	make sure that all caches have been written back to the device, or they may
	not be able to work correctly. Issuing a <b>sync</b> command should do for
	real on-disk partitions.
</p>

	<h3>List of Devices</h3>
<p>
	To get a list of the devices of all mounted volumes, you can issue
	the <b>df</b> command:

	<pre><b>&gt; df
Mount            Type     Total    Free     Flags   Device
---------------- -------- -------- -------- ------- --------------------------
/                rootfs          0        0 ------W
/dev             devfs           0        0 ------W
/pipe            pipefs          0        0 ------W
/boot            bfs      10490444  1387620 QAM-P-W /dev/disk/ide/ata/0/master/0/0_1
/video           bfs      48933990  9463226 QAM-P-W /dev/disk/ide/ata/0/master/0/0_3
/audio           bfs      62918572 11204642 QAM-P-W /dev/disk/ide/ata/0/slave/0/0_1
</b></pre>

	Note, you will only see the mounted volumes using this command, and your
	output of <b>df</b> will likely differ. To work on one of these partitions,
	you can specify their mount point (i.e. <i>/audio</i>) or the device they
	are on.
</p>
	<h3>Which device/partition?</h3>
<p>
	If you need to access disks that are currently not mounted, or cannot be
	mounted anymore, you normally need to provide a path like
	<i>/dev/disk/ide/ata/0/master/0/0_1</i> to the command you're interested
	in working on the disk (if it's a real disk and not only a disk image).
	That path determines how and where the hard drive is connected to your
	computer (ide/ata/0/master/0 means something like: primary IDE controller,
	hard disk jumpered as master (or even cable select)). In that directory,
	the whole disk will be exported as <i>raw</i>, while the partitions will
	be enumerated (0_1, 0_2, ...).
</p>
	<h3>Partition is not there?</h3>
<p>
	Unfortunately, BeOS will normally not publish the partitions of unmounted
	volumes in the device tree. However, you can force it to do that by issuing
	the following command:
	
	<pre><b>&gt; mountvolume -publishall</b></pre>
	
	If the partition is still not visible in the correct directory (or no partition
	at all), it's likely that the partition table has been messed up. That could
	even mean good news, though, as your partition might be completely okay -
	but recovering it might be more difficult. You can use the <i>raw</i> option
	of <b>recover</b> to detect all BFS partitions on the disk.
</p>
<p>
	In this case, if you have a spare hard drive, you might want to try to create
	a partition big enough to hold your affected BFS partition, and copy it over
	using the <b>dd</b> command like this:
	
	<pre><b>&gt; dd if=[</b>old-partition<b>] of=[</b>new-partition<b>] bs=1M count=[</b>size of the partition in MB<b>]</b></pre>
	
	Also helpful is the option <code><b>seek=[</b>block<b>]</b></code> to start at the block
	your partition starts on the disk - you might have to use a block size of 512
	(as in <code><b>bs=512</b></code>) to get to the correct location, though. Don't forget
	to multiply the argument to the <code><b>count</b></code> option based on the block
	size as well in that case.
</p>

<hr>

<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="issues">Known Issues</a></h1></td>
	<td align=right><font size="+2"><a href="#history">&darr;</a><a href="#tips">&uarr;</a></font></td>
</tr></table>
<p>
	The <b>recover</b> tool currently needs much memory - during recovery of
	my 4 GB partition with about 70,000 files, it needed about 100 MB RAM.
	This will be heavily reduced in later releases (at least optionally, as
	this will also slow down the operation a bit).
</p>

<hr>

<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="history">History</a></h1></td>
	<td align=right><font size="+2"><a href="#author">&darr;</a><a href="#issues">&uarr;</a></font></td>
</tr></table>
<p>
	<b>Version 0.7.6, May 25th, 2004</b>
	<ul>
		<li>Added <b>copy_to_bfs_image</b> tool</li>
		<li>internal improvements</li>
	</ul>

	<b>Version 0.7.5, September 28th, 2003</b>
	<ul>
		<li>added new tool <b>bfswhich</b></li>
		<li>the tools now accept more ways to identify a disk (like the mount point)</li>
		<li><b>bfsinfo</b> recognizes different representations to specify the block number</li>
		<li>improved <b>bfsinfo</b> output</li>
		<li><b>recover</b> now can work on raw devices (where the partition table is corrupted)</li>
		<li>improved documentation</li>
	</ul>

	<b>Version 0.7.0, March 6th, 2002</b>
	<ul>
		<li>initial release</li>
	</ul>
</p>
<hr>
<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="author">Author &amp; Address</a></h1></td>
	<td align=right><font size="+2"><a href="#disclaimer">&darr;</a><a href="#issues">&uarr;</a></font></td>
</tr></table>
The Address for bug-reports, ideas and other hopefully useful things:
<dl><dt><b>Letter/Parcel post:</b></dt>
<dd>pinc Software / Axel D&ouml;rfler</dd>
<dd>Lange Stra&szlig;e 4a</dd>
<dd>49080 Osnabr&uuml;ck</dd>
<dd>Germany</dd>
</dl>
<dl><dt><b>eMail-Address:</b></dt>
<dd>axeld@pinc-software.de (Axel D&ouml;rfler)</dd>
</dl>
<dl><dt><b>WWW:</b></dt>
<dd><a href="http://www.pinc-software.de/en_frames.html">http://www.pinc-software.de</a></dd>
</dl>
If you want to send small donations or cards - be welcome :)
<p>
<hr>
<table border=0 cellspacing=0 cellpadding=0 width="95%"><tr>
	<td><h1><a name="disclaimer">Copyright &amp; Disclaimer</a></h1></td>
	<td align=right><font size="+2"><a href="#author">&uarr;</a></font></td>
</tr></table>
The package is copyrighted &copy;2001-2004 by Axel D&ouml;rfler. All rights reserved.
<p>
You are allowed to copy it to other free- &amp; shareware-pools as long as
this documentation is included and you are not following any commercial
interests.
</p>
<p>
The collection is currently distributed as giftware - if it rescued some precious
data, or you are just so happy with it, you may consider to donate me some money,
hardware, or cakes :-). Further releases may also be distributed commercially.
</p>
<p>
You may freely use this product as is. However, no warranty is given on any part of its
functionality. In no event shall the author be liable for any damages it caused.
</p>
<hr>
<font size=1>Copyright &copy;2001-2004 pinc Software. All Rights Reserved</font>
</td></tr></table>
</body>
</html>
