
d64scan - displays and attempts to fix errors/problems in disk images
---------------------------------------------------------------------

usage: ./d64scan <diskimage> <command(s)>

diskimage can be d64, d71, d81 (however, the main focus are d64 images and the
program is not tested with d71 or d81. it might work though =P)

commands:
---------

-dir        show directory and scan files
		reads and displays the directory and opens and reads through
		all files on the diskimage.

		this can be used to locate the following problems:

		- cyclic track/sector links (52,file too large)
		- invalid track/sector links (66,illegal track or sector)
		- sector read errors (only if image has error info)
		- broken BAM to DIR track/sector link (1541/1571 ignores this
		  and always reads directory from 18/1, so this is not a fatal
		  problem)

-rawdir     show directory and output as raw screencode (for use in scripts)

-extdir     show list of all filechains
		shows a list of all files that could be restored by "unformatting"

-bammsg     show BAM message
		displays the normally unused part of the BAM as text, this was
		sometimes used to put small messages there.
		if the message is blank, nothing will be printed.

-map        show BAM and Error Map
		- shows the BAM and error map side by side
		- checks if the number of free blocks on a track matches the bitfield
		  in the BAM

-deformat   create "fixed" image(s) with all filechains
		creates images with all files that can be seen with "-extdir".
		this can be used to restore disks that have accidently been
		deleted, (soft-)formatted or which are otherwise damaged. the
		algorithm used has some advantages/improvements over most (or
		even all?) simelar programs on the c64:
		- it will actually copy the files into new files rather than
		  just recreating the directory, so you won't end up with files
		  that are crosslinked.
		- for the same reason, all files will be truncated at a faulty
		  sector in the filechain and all data that could be read will
		  be saved in a perfectly working file.
		- the original filenames will be restored when they can be found
		- in addition to backtracing the filechain, also all files that
		  previously occured in the directory and all files with a 
		  possible load adress of $0801 will be considered as seperate
		  new files.
		- there are no limits in the number of files that are restored,
		  or in the minimum filelength
		however, the above has some minor backdraws/limitations:
		- since the files will (most likely) end up on a different position
		  on disk, anything that depends on direct track/sector access will
		  no more work with the restored files.
		- REL files and subdirs are not supported by now
		- directory entries that do not link to actual files (so called 
		  "seperators") will be ignored.

-sep        print a seperator line
-cr         print an empty line
		prints an extra blank line _if_ the previous command resulted in
		some output
-name       print image name

-version    print program version and copyright

run d64scan without any arguments to get a short help

have fun,
groepaz@gmx.net

---------------------------------------------------------------------

WANTED:
-------

all kinds of diskimages that make the program misbehave or even crash

Thanks to Winfried Falkenhahn for reporting the directory bug in 0.2

---------------------------------------------------------------------

Batch Processing:
-----------------

this program does not implement any batchprocessing features by itself, but 
instead relies on scripting features of the shell (which is much more flexible).

for those who aren't familiar with making shell scripts (shame on you! =P) here
is a small example of a script that scans all d64 files in a given directory and
writes all output into a logfile:

put the following into a textfile (for example "script.sh")

	#! /bin/bash
	for i in `ls $1/*.d64`; do
		d64scan $i -name -cr -bammsg -cr -dir -cr -extdir -sep >> logfile.txt
	done

(dont forget to make the script executable, for example with "chmod 700 script.sh")

or in cmd.exe syntax for windows: (for example "script.bat")

	for %%i in (%1\*.d64) do d64scan.exe %%i -name -cr -bammsg -cr -dir -cr -extdir -sep >> logfile.txt

the resulting script can be used like this:

	script.sh <directory>

or in windows

	script.bat <directory>

---------------------------------------------------------------------

Changelog:
----------

v0.1 - very incomplete and messy, no options for fixing implemented yet
       uses a work-in-progress version of the diskimage library, so the
       sources might not compile with the latest released version.

v0.2 - added "extended" directory feature
     - added deformat feature
     - in directory also the amount of correctly read blocks/bytes will be
       printed
     - improved output of the -map command
     - added BAM integrity check to dir command

v0.3 - bugfix: the extdir command looped forever when there was a cyclic link
       in the directory
     - bugfix: the last directory sector is now parsed completely
     - new "raw" output mode for use with scripts

---------------------------------------------------------------------

Some Ideas for further functionality (more ideas welcomed!)

- Validate (read through all files and recreate BAM)
	- could possibly be a feature of diskimage.c itself

- clean image (overwrite unused blocks by zeros)

- check if BAM is ok
	- all blocks used by files should be allocated

- combine images (merge several images taken from one disk based on
  the error info stored in them to get one image with less errors)

- compare images (full image, binary compare)
  - check seperatly: directory, BAM

- compare images (file by file)

- when scanning files, also check if they are cross-linked

---------------------------------------------------------------------

License for diskimage library:

diskimage.c and the sample code is released under a slightly modified BSD 
license. In addition I'd appreciate if you let me know if you use it so that 
I can provide a link above, and that you link back to this page from your 
home page. 

Copyright (c) 2003-2006, Per Olofsson
All rights reserved. 

Redistribution and use in source and binary forms, with or without modification, 
are permitted provided that the following conditions are met: 
Redistributions of source code must retain the above copyright notice, this list 
of conditions and the following disclaimer. 
Redistributions in binary form must reproduce the above copyright notice, this 
list of conditions and the following disclaimer in the documentation and/or other 
materials provided with the distribution. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.
