
                        DiscKnight Command Line Use
	                ===========================


DiscKnight 1.38 (15-Jan-2002)
Copyright (C) 2002 The ARM CLub


Purpose
-------

Checks and fixes FileCore E and E+ (RISC OS 4) format hard discs.

See !DiscKnght.Guide for desktop use.


Syntax
------

Usage: DiscKnight [options] <filing system name> <disc number>

The filing system name must be entered in the case it appears in Filer windows,
i.e. SCSI not scsi or Scsi

Where options are:-

-h or -? Display command syntax.

-v       Verbose output, display progress information.

-m       Show the map contents. For each zone, all objects, free space blocks
         and defects are shown, with the bit offset within the zone,
	 corresponding disc addresses and lengths. 

-l       Show the file list. All directories and file are displayed with
         their SIN's, lengths, and the location of their disc chunks.

-t       Show table of free space block and sizes.

-s       Show statistics on disc usage. The number and size of objects,
         free space blocks, file, directories are given. Plus the amount
	 of wastage to the granularity of the map and the minimum file
	 allocation size.

-p       <Tracks> <heads> <sectors per track> [<Start Track>]

         Supply disc parameters. In the event of a corruption of the disc
         shape parameters in the boot block, the first three parameters can
         be supplied which will allow DiscKnight to find the appropriate
         information in the disc map to repair the disc. The tracks, heads
         and sectors values can be found by running the disc formatting
         program (HFORM for ADFS), and selecting the drive causing the values
         to be displayed. *** DO NOT *** proceed with reformatting.
         
         Even if the exact values are not know, choosing values of 15 for
         heads and 63 for sectors, and a number of tracks which when
         multiplied together with heads, sector and a sector size of 512,
         give the approximate size of the disc, should be sufficient for
         DiscKnight to find the disc map. However some filing systems will
         give errors if the correct values are not used, so supply the -na
         option.
         
         If the disc is partitioned into more than one drive, and the filing
         system cannot find the second or subsequent partitions, the option
         start track paramter can be supplied. To use first perform a check
         with the -v flag on the first partition to display the tracks, heads
         and sectors values. Then still using the drive number of the first
         partition use -p <tracks of the 2nd partition (approximate if not
         known)> <heads from 1st> <sectors from 1st> <tracks from 1st>. For
         the subsequent partitions use the sum total of previous tracks
         as the start track. Note: DiscKnight cannot repair the partition
         information but can repair the partitions contents and copy off files
         to another disc using the -b option.
         
-k       <File ID>

         Kill an object (file or directory), for use with otherwise
         undeletable objects. Must be used in conjunction with the -f option.

         Use the -l option to show files and find the file ID which is the the
         SIN number minus the last two digits.

         Use when attempting to remove with a directory path longer than
         256 characters, kill a directory in the middle of the path (<200
         characters). The shortened path will then be deletable, and the
         additional directories will be recovered to Lost+Found.
         
-c       Create files from all free space area on the disc (Must be used in
         conjunction with the -f option)
         
         This option can be used to recover deleted files. NOTE: there is no
         guarentee that the files will still be on the disc as FileCore can
         auto compact the space that they used as soon as they are deleted.
         Plus you will have to indentify your real files which can be contained
         in the potentially thousands of untyped files created in Lost+Found
         using the procedured detailed in after fixing below. 
         
         If there are a lot of free space blocks, the Lost+Found directory
         may become full before they are all converted to files, especially
         on an E format disc. In which case rename Lost+Found and run again.
	
-f       Fix errors (not available in the Read Only Version)

         Only use once DiscKnight has been run without this flag, and
         reported that the disc has errors, but is fixable.
         ALWAYS use the undo option below.

-u       <undo filename>

         Save undo information to a file.
         
	 **** DO NOT SAVE TO THE DISC BEING FIXED ****
  
         By saving undo information you can restore the disc to its current
         state, should the current version DiscKnight not be able to fully
         repair the disc. A later version my be able to recover the disc.

-r       <undo filename>

         Restore the disc from undo file.

         NOTE: Do not use this feature if you have made any modification to the
	 disc between saving the undo file and restoring, or data may be
         irrevocably lost.

-x       <filename>

         Extract all relevant disc information to a file, including the boot
         block, map and directories, in a format suitable for use with the
         -d option below. Ensure the file is on another disc than the one
         being checks, or to a RAM disc of at least 8MB
         
         Use this option to send information on disc for remote analysis by the
         author should you encounter a problem that DiscKnight does not fix.
         Ensure you compress this file with an !SparkFS or other archiving
         program, or !Squash, before emailing to address at the bottom of this
         file.
         
-b       <source directory> <destination directory>

         Enables all files below the source directory (use $ for the entire
         disc) to be backed up to the destination directory on a second disc.

         Can be used where a defect on a crtical area of the disc prevents
         DiscKnight from being able to write repaired information back to the
         disc so that the operating system can read it. 
         
-n<op>   Disable a particular DiscKnight operation:-
         -na     Disable use of alternative disc record when using -p
         -nb     Disable use of the boot block information when using -p
         -ne     Disable the routine removal of excess file fragments
         -no     Disable checking of files and directories
         -nu     Disable check for undo file matching the boot block - CAUTION!
         -nr     Disable recovery of orphaned files
         -ns     Disable minimum disc size constraints, can be used to check
                 F/F+ format floppy discs. Use -nb as well for E/E+ format.

Development options (use at your own risk):-

-g       <filename>

         Generate a file containing data altered by fixing with the -f option,
         in a format that can be restored on to a disc with the -r option.
         This is only useful when working with a disc image using the -d
         option. NOTE the disc/file is still repaired in addition to outputting
         the data.

-d       <filename>

         Work from FileCore disc image given in the next parameter. The format
         is either the entire disc as a raw sector dump (up to 2GB), or the
         output from the -x option above. 


Usage
-----

First ensure that you have shut down all applications which may open files on
the disc in question. If in doubt re-boot the machine with shift held down and
only run DiscKnight. Secondly, dismount the drive to be checked or fixed from 
the discs iconbar menu, unless it is all ready inaccessible due to errors. If 
this is not done, spurious errors may be reported.

Run DiscKnight initially without the -f flag to check the disk. The -v -l -m
-t and -s flags may be given to display additional information. At the end of
any output DiscKnight will display one of the following messages.

"Disc is good"
        
        The disc passed all tests and no further action is needed.
        NOTE: If *checkmap does not report "Map Good" contact the author.

"Disc is bad, N faults found"
"Run a repair (-f and -u flags) to fix"

        Problems were encountered with the disc, note any warnings given
        which may suggest that the disc is of a later format than the
        program understands.
        
        
        Always check the output from DiscKnight very carefully, if looks like
        DiscKnight was not able to read the disc, denoted by lines starting
        with '!' an describing read errors, or an extremely high number of
        faults are reported, it is unlikely that a repair will be successful
        and you should contact DiscKnight support at the address below.

"Errors prevent completion of checking"

        Lack of memory or physical disc errors prevented DiscKnight from
        finishing the checks. If due lack of memory, ensure at least 5MB is
        free before re-running for E+ discs, or 3MB for E discs. 

        Examine the output for lines beginning with a '*' which may describe
        actions to perform or addition parameters to be given to DiscKnight
        on subsequent runs. See the syntax section for the parameter
        mentioned.
        
        NOTE: If DiscKnight reports errors when reading or writing to the
              disc, Please contact the DiscKnight support at the address at
              the end of this document.

"DiscKnight is unable to fix these problems"

        Either the disc is very seriously damaged, or the disc's format is
        later than DiscKnight expects. A more recent version of this program
        may be able to solve some of these problems. Please contact the
        DiscKnight support at the address at the end of this document.

If the disc was bad, run again with the -f flag, and the use use of
-u <filename> to save an undo file (to another disc) is highly recommended.

On completion the message "Disc repaired" will be displayed, unless a problem
occurred. In which case further runs may be required after performing an
action required by the program. (Remember to save a separate undo file
for each run).

Run DiscKnight again without the -f or -u flags, and if "Disc is good" is not
displayed run with -r <undo file> to restore the disc contents and contract
the author for further information. (If multiple undo files were created,
restore them in the REVERSE order they were created in).

After fixing a Lost+Found directory may have been created in the root
directory, which will contain any objects in the map, which were not
referenced by a directory. On old format hard discs more than one Lost+Found
directory (with numeric suffixes) may be created if there are more than 77
files to recover.

Where possible sub-directories and their files will be recovered intact, but
files in the Lost+Found will have no file type information, and may contain
more than one recovered file, or junk proceeding or follow a file. The
contents should be examined in an editor to see if they contain anything
important, and if so this data can be saved out to another file with the
appropriate type. Always move any files recovered in Lost+Found elsewhere,
and delete the directory after use, or some additional disc space will be
remain tired up. 

If the contents of a directory have become irrecoverably scrambled,
DiscKnight will be forced to clear the entries. Most of the lost files will
then be recovered to the Lost+Found directory as described above. However any
files shared in the directory allocation will be amalgamated into a single
file called 'Recovered' in the directory itself. It is likely that this will
contain many small files such as !Boot and !Run, which will have to be
extracted manually with an editor.

NOTE: After recovering a badly corrupted map, some files may have junk
appended or prepended to them, this will also need to be removed manually.


DiscKnight Technical Details
----------------------------

DiscKnight checks and corrects the following.

Boot Block:

  *  Defect List checksums, for first and second (large disc) list. 
     NOTE: currently no attempt is made to validate the defect locations,
     or check them against the map information.
  *  Boot block Disc record fields in acceptable ranges
     *  Sector size
     *  Sectors per track
     *  Number of disc heads
     *  Disc density
     *  Map spare bits in zone
     *  Large File Allocation Unit
     *  Disc size
     *  Big disc flag
     *  FileCore version flag
     *  Map ID length
     *  Number of map zones
     *  Root directory location
     *  Sharing size granularity
     NOTE: if any of these fields are incorrect, DiscKnight must be run again
           with the -p option to specify the correct disc shape parameters
     *  Finding of the map disc record from user supplied disc shape parameters
     *  Finding of the boot block on in accessible partitions
     *  Boot block checksum.


Disc Map:

  *  Map zone check bytes and zone cross checks
  *  Restore from good copy of map 1 or 2
  *  Comparison of map disc record against boot block disc record
     *  Sector size
     *  Sectors per track
     *  Number of disc heads
     *  Disc density
     *  Map spare bits in zone
     *  Large File Allocation Unit
     *  Boot option
     *  Sector Skew
     *  Low sector info
     *  Disc size
     *  Big disc flag
     *  FileCore version flag
     *  Map ID length
     *  Number of map zones
     *  Root directory location
     *  Sharing size granularity
  *  Boot block and map objects exist and are the correct size
  *  Zone free space chain start
  *  Fragment termination bit
  *  Free space chain integrity
  *  Last free space block recovery
  *  Headless object fragments
  *  Fragments are a whole number of sectors
  *  Check for end of disc marker correct for disc size

Disc Objects:

  *  Missing root directory found or rebuilt
  *  Oversized files truncated to size allocated by the map.
  *  Multiple directory entries for same map object removed.
  *  Multiple directory entries for same shared sector removed.
  *  Objects referenced in directories but not in map removed.
  *  Objects conflicting over shared sectors removed
  *  Recovery of map objects not referenced by directories
     *  Files and directories recovered to $.Lost+Found
     *  Sub-directory hierarchies re-linked if possible
  *  Excess fragments removed from files and directories
  *  Disc objects can be killed without errors from the OS.

Directories:

  All:

  *  Directory checksums
  *  Start and end sequence numbers
  *  Start and end check names
  *  Reserved areas clear
  *  Parent SIN matches parent directory
  *  Directory name matches parent directory entry
  *  Entry SIN valid
  *  Directory sort order correct

  Big directories:

  *  Valid size
  *  Version number
  *  Directory name length valid
  *  Directory name extended if required
  *  Child directory name matched against parent directory
  *  Name heap size valid
  *  Entry name valid (pointer, length and termination)
  *  Entry backup SIN matches primary
  *  Directory sort order correct


Contact Information
-------------------
DiscKnight is distributed by The ARM Club (http://www.armclub.org.uk/),
registered users may obtain support via:-

Email: DiscKnight@armclub.org.uk
Phone: 07010 709849 (charged at Flextel rates).
Post : The ARM Club, Merton Court, 38 Knoll Road, Sidcup Kent, DA14 4QA

Please quote your serial number and the program version number (displayed
whenever DiscKnight is run) in all correspondance. 

