.TH BURPSF 1csound CARL
.SH NAME
burpsf 
\- free space compaction for csound file system
.SH SYNOPSIS
.B burpsf 
filesystem
.SH BRIEF DESCRIPTION
.fi
.B burpsf
squeezes the unused bubbles of freespace into one chunk
by doing a linear compaction.  It first coalesces adjacent free
blocks.  Then it goes from low addresses on the disk to high, copying
files down to fill all the empty spaces.
.sp
.SH FULL DESCRIPTION
The routine first reads into core the entire free list and also all the
sound descriptor files (SDF).  This is because the contiguous files
can be spread across the disk, and as a linear compaction will be
performed, a sound file descriptor (SFD) may have to be put down at one moment
and picked up again later as the disk is bubbled through.
It then copies the SDF structures, creating new disk block pointers
on a new free list which it makes up.  Since the allocation strategy is
linear first-fit, it builds the new list from the beginning of the disk.
It then determines which files appear in different places on the two
lists.
.PP
At this point it
asks you if you want to see the list of files it wants to move, and
the base addresses it wants to move them to.
You should routinely look at this list before actually allowing
\f3burpsf\f1 to do it.
.PP
After previewing the list, it will ask if you wish to proceed.
If the free list looks reasonable,
(the block of free space at the end of the new list should equal the
sum of fragmented free blocks on the old list) then type
.RS .5i
y [return]
.RE
and go get a cup of coffee.  It can take up to 20 minutes for a 300MB
disk if it has to move all the files.
.B burpsf
shows the progress of the compaction, showing the file, the source block
being copied, and the destination.  It also gives an indication of
the time in seconds it will take to copy the file.
.PP
At the end of each block copy, the updated sound descriptor
file that points to that block is written out.  The current copy of the
free list is also written out, with the blocks not yet copied marked
as ALLOCATED.
Thus, if 
.B burpsf
dies while copying, the free list in /<device>/dskcyls will be erroneous,
but the SDF files will be accurate.
Since
.B sfck
can rebuild the free list from the SDF files, this should be
a recoverable situation.
.SH Bad Block Files
If you have isolated bad block files as described in the document
"Managing Bad Blocks on a Csound File System",
.B burpsf
will not try to move them.  Files will be moved around the bad blocks
insofar as they fit.
.SH AUTHOR
Gareth Loy
.SH SEE ALSO
cpsf(1csound),
"Managing Bad Blocks on a Csound File System".
.SH DIAGNOSTICS
You must be a member of the csound super user group to run this program.
If you are not, it will bluntly inform you of that fact and quit forthwith.
It will complain if it fails in coalescing free blocks in advance of
figuring out what to copy.  This shouldn't happen if you've run
.B sfck
first and all was well.
It will also complain and stop if it encounters anything except USED
or UNUSED blocks on the free list, since
.B sfck
should have caught these as well.
If a read or write error is generated copying blocks of a file you will
get the error message: "Aaaarrrggh!".
.B burpsf
then quits.
The thing to do at that point is to rebuild the free list.
Let
.B sfck
do it.  Move the file /<device>/dskcyls to some temporary name and run
.B sfck,
which will notice the absence of dskcyls and regenerate it.
.SH Notice
.PP
Running this program
must
.B ALWAYS
follow on a check of the integrity of the
disk free list via
.B sfck(1csound).
You
.B MUST
correct any errors that occur
there first.
.PP
It is not unwise to have done a dump of the disk first, also.
Theoretically, the worst that can happen is that
a single file is lost if
.B burpsf
dies in the middle of a copy.  Otherwise, the theory is that
.B sfck
can always put the file system back together.
However, with a program that has this much potential for disaster,
it is worth taking precautions.
Its potential for disaster arises from the fact that it touches every
file on the disk.
.SH BUGS
.B burpsf
could be smarter if it first
looked for files of the exact size to fill the holes instead of
moving all files down one after the other, but it took long
.I enough
to write this program!
