The Datafile PD-CD 3/PDCD_3.iso/utilities/utilsf/fsck/fsck_help

Text File | 1995-01-31 | 19.7 KB | 413 lines

fsck (1.21) - map fixer and analyst

NOTE: this program is SHAREWARE. Read the !SHAREWARE file for more info.

fsck is a disc utility that fixes the map of an E-Format disc (hard or
floppy) if it is corrupted for some obscure reasons. fsck can also report
some informations about the way the files are allocated (such as the bytes
lost because of sectors boundaries) and eventually print a detailed
description of the map and directories organization.
fsck can also be considered as a replace of the *CheckMap command because it
is faster, less prone to crash and can give useful informations on the files
allocation.


Usage
-----

fsck [-options] [-d lostdir] [-l logfile] [pathname]
Most used options:
  -s   calculate statistics
  -f   try to fix map if broken
  -l   print the results in "logfile"
Less used options:
  -h   print help informations
  -d   link broken part of map in directory "lostdir"
  -v   print files location (-vv print also files position in zones)
  -D   just display disc information recorded in the map header
  -q   don't display disc information (quiet mode)
  -c   produce output like *CheckMap
  -m   ask the user to eventually move files instead of changing map
  -n   don't try to recognise directories

The default directory where files are linked is "$.lost+found".
If 'pathname' is not specified, the current disc is analysed.
If 'pathname' is not a root directory (eg. ADFS::0.$.Library), fsck checks
only that directory and so it cannot tell you if the map is good or broken.
This could be useful if you want to know the statistics of a single directory
instead of the whole disc. If the -f option is used, the disc is scanned from
the root directory, regardless of 'pathname'.
The -m and -n options used together cause fsck 1.20 or later to work like
fsck 1.13 or earlier.


What it does (or tries to do...)
--------------------------------

fsck scans the directory tree and checks the map to see if every file
registered in the map actually exists in a directory. If not, it creates that
file in a directory so that you will be able to delete it in the normal way.
If the file was originally a directory, fsck tries to relink it
reconstructing the directory name and content. Even if you want to keep the
relinked files or directories, you should copy them and delete the original
one, because there is the risk that your map will be corrupted again,
especially if you try to change them.
Apart from directories and their content, the re-linked files are usually
longer than the original lost file because fsck always links whole sectors
(and there is no way to know the original length), their filenames are random
and filetypes always &FFF (Text).

Using the -m option, fsck could tell you that an ID is regularly allocated
for another file and you have to delete it (moving the file to another
directory isn't enough, you have to copy it and delete the original) and run
fsck again. Without this option, fsck will change the ID in the map and
rewrite it to disc. The -m option is in fact only useful if you prefer not to
modify your map: anyway, remember that moving files on a corrupted disc can
be quite dangerous and can eventually corrupt other parts of the disc.
Sometimes the disc may be so corrupted that you will need to run fsck more
than once, the program itself will tell you if a re-run is needed.


The logfile
-----------

Using the logfile (-l) option is generally really useful: if something
strange happens, the author will be more helpful if he can see exactly what
happened and you don't even have to try to explain what happened when you run
fsck, the logfile is usually enough!
The logfile contains exactly what it is printed to the screen: unless you use
the -v option it will be really small (nearly 2K on a good map or nearly 10K
on a quite corrupted one).
You cannot save the logfile to the disc to analyse.
If a file with the same name of the logfile already exists, the new data will
be attached at the end of it: in this way, you can attach together two or
more logfiles.


fsck and Risc PC
----------------

fsck and CheckMap are no more equivalent on Risc PCs! In fact, Acorn changed
some behaviours of the FileCore module in RISC OS 3.50 so that it can now
cope with over-allocated files (ie. files that have allocated more space than
they need). This sort of files on old version of RISC OS causes CheckMap to
say "Map inconsistent" and if you try to delete such files you will lose some
space. On RISC OS 3.50 CheckMap no more says "Map inconsistent" if
over-allocated files are the only map problem and deleting them no more
causes lost space. Compliment Acorn!
fsck still reports map corruptions in this case (on every version of RISC OS)
since an over-allocated file can be considered a problem (think at a 100K
file that uses up 10Mb of disc space and you will understand what I mean!).
Anyway, on a Risc PC, using the -m option you can be able to discover such
files and you can fix the disc (assuming that your map is corrupted only
because of over-allocated files) just moving them.
Remember that using the -f option fsck can cure the disc without moving any
file on every version of RISC OS.


Return values
-------------

This paragraph can be interesting only for programmers who want to write
some program/frontend that has to interface with fsck.

fsck returns to RISC OS a value that is 0 only if fsck was able to scan the
disc and the map is good, otherwise it returns 1.
fsck also sets the numeric system variable fsck$ReturnCode to a value that
can be more helpful to determine why fsck failed or 0 if the map was good.
The value is formed by the following bits:

enum {
  return_MAPGOOD          = 0x00000000,   /* the map is good (!) */

  return_MAP_BROKEN       = 0x00000001,   /* the map is broken, fsck -f should fix it */
  return_MAP_FIXED        = 0x00000002,   /* the map was broken but has been fixed */
  return_MAP_UNFIXABLE    = 0x00000004,   /* the map seems to be unfixable... */
  return_NEED_ELIMINATE   = 0x00000010,   /* need eliminate to fix the map */
  return_NEED_HARDFIX     = 0x00000020,   /* need hardfix to fix the map */
  return_NO_ACTION        = 0x00000100,   /* no useful action performed (eg. fsck -h) */
  return_PARAM_ERROR      = 0x00000200,   /* bad input parameters */
  return_WRONG_FS         = 0x00000400,   /* wrong file system name, disc name, number, etc. */
  return_IO_ERROR         = 0x00000800,   /* error while reading/writing disc, directories, etc. */
  return_MEMORY_FULL      = 0x00001000    /* not enough free memory */
};

You can expect that every possible conbination of that values is returned (ie.
&30 means that both 'eliminate' and 'hardfix' are needed) even if generally
only one error number is returned.
If you are writing a 'C' program that has to call fsck you can use something
like this:

 if (system("fsck ...")==0) {
   /* map good */
 }
 else {
   /* some problem occurred (not necessairily map broken!) */
   /* check fsck$ReturnCode for more informations */
 }

If you don't want (or can't) check the return status you just check the value
of fsck$ReturnCode.


Notes
-----

fsck is 20-30% faster than CheckMap (actually, up to 50% faster on big and
full drives!). If you really like CheckMap's output instead of fsck's one,
you can use the -c option so that fsck will print the directory tree as it
proceeds with the scan. You can eventually include the following alias in
your boot sequence so that you can still write 'CheckMap' even if 'fsck' is
the command actually executed (fsck should be reachable via Run$Path, for
example, put it in the Library directory):
Set Alias$CheckMap "fsck -c "       [try "fsck -s " for a more useful output]

Anyway, fsck can also be used to show the "Free space chunks
statistics" or to calculate some statistics about the files allocation using
the -s option (not in conjunction with -c, though).
The "Free space chunks statistics" are always shown unless the -q or -c
options have been specified: in general, with a high number of (small) free
space chunks, RISC OS will be slower when saving files because it will try to
do an auto-Compact and (this is my personal opinion) there will be more
possibility for your disc to become corrupted. So, I think that in this case
you need to Compact your disc, eventually more than once, to try to lower the
number of free space chunks and to increase their size.

Remember that it is better if you close all the open files on the disc that
fsck is examining (ie. don't *spool on it!!). If you run fsck in a TaskWindow
remember to avoid any save of data on that disc while fsck is running because
this will have VERY VERY DANGEROUS consequences if you use the -f option!!!
If some file is corrupted, fsck will tell you to eliminate it before trying
to fix the disc (if you were already trying to fix the disc the fixing will be
disabled): before this, try to load the file and if RISC OS doesn't hang you
could be able to save the file somewhere before deleting the original.


Disclaimer
----------

Even if fsck *can* write to the map, this is generally not dangerous since it
only modifies the IDs of the lost files. Anyway, you are adviced to use
hardfix to save the disc data before using fsck, so that you will be able to
restore it in case something goes wrong. If the relinked files are (for some
mysterious reason) unreadable or undeletable you should just use eliminate on
them and your disc should be as corrupted as before.

Anyway, modifying the disc map and the directory tree can always be
dangerous: if fsck corrupts your disc (or if the disc becomes corrupted when
you start writing to it after using fsck), I am sorry for you but I AM NOT
RESPONSIBLE for any loss of data on your discs, so use fsck at your own risk.
As you can see from the list below, fsck worked on many discs and it never
corrupted anything. Sometimes, I intentionally corrupt my disc to see if the
new versions work and never experienced any problem!

Finally, remember that unless you specify the -f option, fsck will not write
to your disc and you are encouraged to make a backup copy of your important
data and to save the disc data using hardfix before running fsck -f.


Limitations
-----------

fsck can't fix seriously damaged discs alone: in this case it will ask you to
run eliminate or hardfix to fix what it can't.


Bugs
----

It seems that sometimes fsck produces strange "Bad drive" errors: this
probably has been cured but if you encounter this sort of problem, please
contact the author sending a logfile and the saved disc data (using hardfix).
Sometimes, on heavily damaged disc, you need to run fsck more than once even
if it doesn't tell you to do so.
fsck could have problems with RISCiX partitioned discs: it works with the
only RISCiX partitioned disc I tried it on, but I cannot be sure it will work
on yours, too. If you have such a disc and fsck reports strange errors (or
say to run hardfix to fix it) please mail me the logfile and (more important)
the disc data saved by hardfix.
Generally, if the disc contains a non-ADFS partition, fsck will report a
defect at the end of the last zone: don't worry, the defect is actually the
beginning of the non-ADFS partition, just ignore it.


Results achieved up to now
--------------------------

If you run fsck on your corrupted HD, please let me know! If it wasn't able
to fix it, I'll try to modify it to cope with your problem. If you want to
stay anonymous tell me not to include your name.

Positive results:
 1) some 800K ADFS floppy (used during development).
 2) 100Mb IDE (ICS interface) partitioned in 84Mb/16Mb (both partitions
    fixed). Owner: Sergio Monesi (ie. me!)
 3) 100Mb IDE (ICS interface). Owner: Cristian Ghezzi
 4) 314Mb SCSI (Serial Port Alpha SCSI interface). Owner: K. Bailey
 5) 60Mb IDE (A4 portable). Owner: G. Castagno
 6) 48Mb SCSI (Oak 16 Bit interface). Owner: A.M. Baardholt
 7) 40Mb ST506. Owner: A. Goodfellow
 8) 80Mb IDE (A5000). Owner: Julian Wright
 9) 240Mb SCSI (HCCS 8 bit interface) partitioned in 2*120Mb. Owner: Kai
    Schlichting.
10) 245Mb IDE (A5000). Owner: H. M.
11) 80Mb IDE (A5000). Owner: Mike Henry
12) 121Mb SCSI (Lingenuity SCSI interface). Owner: R. Z.
13) 100Mb SCSI (Oak interface). Owner: JP Hendrix
14) 60Mb IDE (A4 portable). Owner: J. Wallace
15) 122Mb SCSI (Atomwide Parallel/SCSI interface). Owner: J. Wallace
16) 80Mb IDE (A5000). Owner: P. Callan
17) 240Mb SCSI (Morley Cached interface). Owner: P. Callan
18) 80Mb SCSI (Morley Cached interface). Owner: P. Callan
19) Some 45Mb Syquest Removable cartridges. Owner: P. Callan (this poor dude
    has a lot of discs, all of them were broken, now successfully fixed!!)
20) 40Mb ST506. Owner: G. Riley
21) 40Mb IDE (Serial Port interface). Owner: G. Riley
22) 40Mb ST506. Owner: M. Ferrari
23) 240Mb IDE (A5000). Owner: E. Pfarr
24) 200Mb SCSI. Owner: S. Williams
25) 500Mb SCSI. Owner: S. Williams
26) 314Mb SCSI (Morley interface). Owner: Cy Booker
27) 60Mb IDE (A4 portable). Owner: M. Stephens
28) 105Mb SCSI (HCCS 8 bit interface). Owner. S. Huber
29) 20Mb IDE (Watford interface). Owner: S. Pollard
30) 57Mb SCSI (Lingenuity interface). Owner: M. Grimminck
31) 170Mb IDE (A5000). Owner: M. Ebourne
32) 40Mb ST506. Owner: M. Attenborough
33) 120Mb IDE (ICS interface). Owner: J. Haslam
34) 170Mb SCSI (Oak 16 Bit interface). Owner: P. Spencer
35) 116Mb IDE (Desktop Projects interface). Owner: A.D. Hodgkinson
36) 420Mb IDE (A5000). Owner: E. Pronk
37) 210Mb IDE (Risc PC): Owner: E. Hughes
38) 105Mb IDE (ICS interface): Owner: C. Whitehead
39) 200Mb SCSI (Acorn Interface): Owner: A. Malara
40) 120Mb IDE (A5000). Owner: B. Bommer
41) 105Mb IDE Syquest Removable cartridge (A5000). Owner: B. Bommer
42) 52Mb SCSI (Lingenuity interface). Owner: Kjetil Bernhard Thomassen
43) 122Mb SCSI (Lingenuity interface). Owner: P. Gillham

Probably many other discs have been fixed but their owner didn't contacted
me...

Negative results:
 No negative results till now.


History
-------

1.00   First fully working version. Released only via e-mail.
1.01   Fixed a bug concerning filing system names. Added -D option. Now fsck
       generally needs only one run to fix a heavily corrupted disc. Added
       eliminate program.
1.02   Changed again the method to check filing system names (Thanks to
       Keith Bailey). Added percentages in statistics. Checks boot block
       checksum and shows defect list.
1.03   Now it is possible to scan a single directory instead of the whole
       disc. You can specify 'relative' pathnames (eg. @.Examples) instead
       of full paths (Thanks to Julian Wright). At the end of the scan fsck
       will tell you which files should be eventually deleted. Added
       statistics about fragmented files and free blocks sizes. Changed the
       'F's and 'D's with a rotating wheel... Added -q and -l options.
1.04   Cured a serious bug that has always been present but never caused
       problems (until 1.03). Added ImageFSFix check and -I option. Now fsck
       understands RISCiX partitions.
1.10   RISCiX partitions are now fully supported (ie. mapped out). First
       version distributed as SHAREWARE.
1.11   Added -a option. The logfile is appended to the end of the file if it
       already exists and now it contains the creation date. Great speed
       increase (up to 2 times faster without -s and 5 times faster with
       -s!!!). Now fsck is just 25% slower than *CheckMap (or 2 times slower
       with -s)! Added the note about "Free space chunks statistics" (see
       the section Notes).
1.12   Another speed improvement (just 10%)! fsck isn't yet as fast as
       *CheckMap but I'm working on it ;-) Fixed a possible dangerous
       behaviour of -a option. Added a warning for HD boot blocks marked as
       defect. Slowed down the wheel. Added files MapExpl and StatsHelp.
1.13   Faster again (15% with -s, 3% without)!! Now statistics are just a bit
       slower than normal mode. Automatic creation of lostdir. More messages
       at the end of the process that can help to understand what happened
       (ie. the disc is fixed, fixable, unfixable, etc.) and more helpful
       error messages (no more "Can't find 'AD::0.$': incorrect FS") if the
       floppy drive is empty!
1.20   Completely rewritten! As you would expect: *FASTER* (this is
       probably the maximum achievable speed with the structure of fsck, so
       don't expect further significant improvements!). Now fsck is 20-30%
       faster than *CheckMap, even with statistics enabled! Directory
       recognition added (see the "What it does" secton). No more files to
       move (so many people complained about this)! Added -m and -n options
       to 'simulate' 1.13 version. Added -c option to simulate CheckMap (!).
       Removed the obsolescent -a option. Fixed problems with ImageFSFix
       module and removed -I option. If some file has allocation problems,
       the name of the file is reported together with the error, so that you
       can use 'eliminate' to remove it. Fixed a lot of bugs, some more
       sensible messages and more consistent way to print some value. Added
       new statistics about files that must be fragmented. Modified command
       line behaviour: if no 'pathname' is given, fsck scans the current
       disc (as CheckMap does). Added 'hardfix' program. Added '!QuickFix'
       and '!Intro' files. Modified most of this help file, removed the "Can
       a serious filing system corrupt discs?" section that contained only my
       (debatable) opinions and added "fsck and Risc PC" section.
1.21   Fixed some minor bug and added some error trapping. Added and
       documented a sensible return code and the system variable
       fsck$ReturnCode. Fixed some bugs in the directory relinking feature.


Thanks go to:
-------------

- Keith Bailey who discovered that the first 3 versions of fsck were
  completely useless on his SCSI!! The 4th version finally fixed his
  map problems (twice!). Thanks for the comment about the clock too! :-)
- Adam Goodfellow and Atle Mjelde Baardholt for the beta-testing.
- Hans Ole Rafaelsen who tried fsck on 1.6Mb floppies.
- Julian Wright for his beta-testing, suggestions, PRM docs, bugs-report and
  interest.
- Ernest Ong who suggested me to write a map-corruptor program to test fsck:
  'eliminate' is ready, now I am working on 'corrupter' ;-)
- Cristian Ghezzi who let me play with his RISCiX partitioned SCSI for a
  whole day to discover some stupid fsck bug. He also let me intentionally
  corrupt his ST506 disc to test the new directory recognition feature...
- Andreas Schubert (Platon) who tried fsck on his Risc PC.
- Kai Schlichting who said that fsck was one of the most useful 'Unix ports'
  for RISC OS, a program that the Acorn world really needed. Kai has been
  the first who sent me 'something' to register!
- Mike Henry who has been the first who sent me some pounds to register
  (actually he sent me 10 pounds instead of the 5 I ask!).
- Dag Haakon Myrdal for his suggestions and accurate bug report.
- Martin J. Ebourne for his (initially negative but now generally positive)
  comments!
- Simon Middleton who pushed me to finish the new version (1.20) so that he
  could include it in his PD/ShareWare CD-ROM.
- Jason Williams (and all the other collaborators) for DeskLib: the new
  versions of fsck use some small part of DeskLib and the new sources
  structure is really similar to DeskLib's one.
- the person who spread on Internet a document describing the E-Format
  structure.
- Mohsen Alshayef for his !ArcTools, a very useful utility that allowed
  me to search in the ROM FileCore module for some code...


Conditions of use
-----------------

fsck can only be distributed with the complete fsck suite.
Read the !SHAREWARE file for the conditions of use and distribution of the
whole package.


I can be contacted at the following address:

Sergio Monesi
Via Trento e Trieste 30
20046 Biassono (MI)
Italy

E-mail address:
[e-mail]
If you don't receive a reply (or if the message is bounced) I can also be
contacted at:
[e-mail]
or:
[e-mail]