home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / mag_discs / 17 / fsck / fsck_help < prev    next >
Text File  |  1995-06-11  |  20KB  |  420 lines
  1. fsck (1.22) - map fixer and analyst
  2.  
  3. NOTE: this program is SHAREWARE. Read the !SHAREWARE file for more info.
  4.  
  5. fsck is a disc utility that fixes the map of an E-Format disc (hard or
  6. floppy) if it is corrupted for some obscure reasons. fsck can also report
  7. some informations about the way the files are allocated (such as the bytes
  8. lost because of sectors boundaries) and eventually print a detailed
  9. description of the map and directories organization.
  10. fsck can also be considered as a replace of the *CheckMap command because it
  11. is faster, less prone to crash and can give useful informations on the files
  12. allocation.
  13.  
  14.  
  15. Usage
  16. -----
  17.  
  18. fsck [-options] [-d lostdir] [-l logfile] [pathname]
  19. Most used options:
  20.   -s   calculate statistics
  21.   -f   try to fix map if broken
  22.   -l   print the results in "logfile"
  23. Less used options:
  24.   -h   print help informations
  25.   -d   link broken part of map in directory "lostdir"
  26.   -v   print files location (-vv print also files position in zones)
  27.   -D   just display disc information recorded in the map header
  28.   -q   don't display disc information (quiet mode)
  29.   -c   produce output like *CheckMap
  30.   -m   ask the user to eventually move files instead of changing map
  31.   -n   don't try to recognise directories
  32.  
  33. The default directory where files are linked is "$.lost+found".
  34. If 'pathname' is not specified, the current disc is analysed.
  35. If 'pathname' is not a root directory (eg. ADFS::0.$.Library), fsck checks
  36. only that directory and so it cannot tell you if the map is good or broken.
  37. This could be useful if you want to know the statistics of a single directory
  38. instead of the whole disc. If the -f option is used, the disc is scanned from
  39. the root directory, regardless of 'pathname'.
  40. The -m and -n options used together cause fsck 1.20 or later to work like
  41. fsck 1.13 or earlier.
  42.  
  43.  
  44. What it does (or tries to do...)
  45. --------------------------------
  46.  
  47. fsck scans the directory tree and checks the map to see if every file
  48. registered in the map actually exists in a directory. If not, it creates that
  49. file in a directory so that you will be able to delete it in the normal way.
  50. If the file was originally a directory, fsck tries to relink it
  51. reconstructing the directory name and content. Even if you want to keep the
  52. relinked files or directories, you should copy them and delete the original
  53. one, because there is the risk that your map will be corrupted again,
  54. especially if you try to change them.
  55. Apart from directories and their content, the re-linked files are usually
  56. longer than the original lost file because fsck always links whole sectors
  57. (and there is no way to know the original length), their filenames are random
  58. and filetypes always &FFF (Text).
  59.  
  60. Using the -m option, fsck could tell you that an ID is regularly allocated
  61. for another file and you have to delete it (moving the file to another
  62. directory isn't enough, you have to copy it and delete the original) and run
  63. fsck again. Without this option, fsck will change the ID in the map and
  64. rewrite it to disc. The -m option is in fact only useful if you prefer not to
  65. modify your map: anyway, remember that moving files on a corrupted disc can
  66. be quite dangerous and can eventually corrupt other parts of the disc.
  67. Sometimes the disc may be so corrupted that you will need to run fsck more
  68. than once, the program itself will tell you if a re-run is needed.
  69.  
  70.  
  71. The logfile
  72. -----------
  73.  
  74. Using the logfile (-l) option is generally really useful: if something
  75. strange happens, the author will be more helpful if he can see exactly what
  76. happened and you don't even have to try to explain what happened when you run
  77. fsck, the logfile is usually enough!
  78. The logfile contains exactly what it is printed to the screen: unless you use
  79. the -v option it will be really small (nearly 2K on a good map or nearly 10K
  80. on a quite corrupted one).
  81. You cannot save the logfile to the disc to analyse.
  82. If a file with the same name of the logfile already exists, the new data will
  83. be attached at the end of it: in this way, you can attach together two or
  84. more logfiles.
  85.  
  86.  
  87. fsck and Risc PC
  88. ----------------
  89.  
  90. fsck and CheckMap are no more equivalent on Risc PCs! In fact, Acorn changed
  91. some behaviours of the FileCore module in RISC OS 3.50 so that it can now
  92. cope with over-allocated files (ie. files that have allocated more space than
  93. they need). This sort of files on old version of RISC OS causes CheckMap to
  94. say "Map inconsistent" and if you try to delete such files you will lose some
  95. space. On RISC OS 3.50 CheckMap no more says "Map inconsistent" if
  96. over-allocated files are the only map problem and deleting them no more
  97. causes lost space. Compliment Acorn!
  98. fsck still reports map corruptions in this case (on every version of RISC OS)
  99. since an over-allocated file can be considered a problem (think at a 100K
  100. file that uses up 10Mb of disc space and you will understand what I mean!).
  101. Anyway, on a Risc PC, using the -m option you can be able to discover such
  102. files and you can fix the disc (assuming that your map is corrupted only
  103. because of over-allocated files) just moving them.
  104. Remember that using the -f option fsck can cure the disc without moving any
  105. file on every version of RISC OS.
  106.  
  107.  
  108. Return values
  109. -------------
  110.  
  111. This paragraph can be interesting only for programmers who want to write
  112. some program/frontend that has to interface with fsck.
  113.  
  114. fsck returns to RISC OS a value that is 0 only if fsck was able to scan the
  115. disc and the map is good, otherwise it returns 1.
  116. fsck also sets the numeric system variable fsck$ReturnCode to a value that
  117. can be more helpful to determine why fsck failed or 0 if the map was good.
  118. The value is formed by the following bits:
  119.  
  120. enum {
  121.   return_MAPGOOD          = 0x00000000,   /* the map is good (!) */
  122.  
  123.   return_MAP_BROKEN       = 0x00000001,   /* the map is broken, fsck -f should fix it */
  124.   return_MAP_FIXED        = 0x00000002,   /* the map was broken but has been fixed */
  125.   return_MAP_UNFIXABLE    = 0x00000004,   /* the map seems to be unfixable... */
  126.   return_NEED_ELIMINATE   = 0x00000010,   /* need eliminate to fix the map */
  127.   return_NEED_HARDFIX     = 0x00000020,   /* need hardfix to fix the map */
  128.   return_NO_ACTION        = 0x00000100,   /* no useful action performed (eg. fsck -h) */
  129.   return_PARAM_ERROR      = 0x00000200,   /* bad input parameters */
  130.   return_WRONG_FS         = 0x00000400,   /* wrong file system name, disc name, number, etc. */
  131.   return_IO_ERROR         = 0x00000800,   /* error while reading/writing disc, directories, etc. */
  132.   return_MEMORY_FULL      = 0x00001000    /* not enough free memory */
  133. };
  134.  
  135. You can expect that every possible conbination of that values is returned (ie.
  136. &30 means that both 'eliminate' and 'hardfix' are needed) even if generally
  137. only one error number is returned.
  138. If you are writing a 'C' program that has to call fsck you can use something
  139. like this:
  140.  
  141.  if (system("fsck ...")==0) {
  142.    /* map good */
  143.  }
  144.  else {
  145.    /* some problem occurred (not necessairily map broken!) */
  146.    /* check fsck$ReturnCode for more informations */
  147.  }
  148.  
  149. If you don't want (or can't) check the return status you just check the value
  150. of fsck$ReturnCode.
  151.  
  152.  
  153. Notes
  154. -----
  155.  
  156. fsck is 20-30% faster than CheckMap (actually, up to 50% faster on big and
  157. full drives!). If you really like CheckMap's output instead of fsck's one,
  158. you can use the -c option so that fsck will print the directory tree as it
  159. proceeds with the scan. You can eventually include the following alias in
  160. your boot sequence so that you can still write 'CheckMap' even if 'fsck' is
  161. the command actually executed (fsck should be reachable via Run$Path, for
  162. example, put it in the Library directory):
  163. Set Alias$CheckMap "fsck -c "       [try "fsck -s " for a more useful output]
  164.  
  165. Anyway, fsck can also be used to show the "Free space chunks
  166. statistics" or to calculate some statistics about the files allocation using
  167. the -s option (not in conjunction with -c, though).
  168. The "Free space chunks statistics" are always shown unless the -q or -c
  169. options have been specified: in general, with a high number of (small) free
  170. space chunks, RISC OS will be slower when saving files because it will try to
  171. do an auto-Compact and (this is my personal opinion) there will be more
  172. possibility for your disc to become corrupted. So, I think that in this case
  173. you need to Compact your disc, eventually more than once, to try to lower the
  174. number of free space chunks and to increase their size.
  175.  
  176. Remember that it is better if you close all the open files on the disc that
  177. fsck is examining (ie. don't *spool on it!!). If you run fsck in a TaskWindow
  178. remember to avoid any save of data on that disc while fsck is running because
  179. this will have VERY VERY DANGEROUS consequences if you use the -f option!!!
  180. If some file is corrupted, fsck will tell you to eliminate it before trying
  181. to fix the disc (if you were already trying to fix the disc the fixing will be
  182. disabled): before this, try to load the file and if RISC OS doesn't hang you
  183. could be able to save the file somewhere before deleting the original.
  184.  
  185.  
  186. Disclaimer
  187. ----------
  188.  
  189. Even if fsck *can* write to the map, this is generally not dangerous since it
  190. only modifies the IDs of the lost files. Anyway, you are adviced to use
  191. hardfix to save the disc data before using fsck, so that you will be able to
  192. restore it in case something goes wrong. If the relinked files are (for some
  193. mysterious reason) unreadable or undeletable you should just use eliminate on
  194. them and your disc should be as corrupted as before.
  195.  
  196. Anyway, modifying the disc map and the directory tree can always be
  197. dangerous: if fsck corrupts your disc (or if the disc becomes corrupted when
  198. you start writing to it after using fsck), I am sorry for you but I AM NOT
  199. RESPONSIBLE for any loss of data on your discs, so use fsck at your own risk.
  200. As you can see from the list below, fsck worked on many discs and it never
  201. corrupted anything. Sometimes, I intentionally corrupt my disc to see if the
  202. new versions work and never experienced any problem!
  203.  
  204. Finally, remember that unless you specify the -f option, fsck will not write
  205. to your disc and you are encouraged to make a backup copy of your important
  206. data and to save the disc data using hardfix before running fsck -f.
  207.  
  208.  
  209. Limitations
  210. -----------
  211.  
  212. fsck can't fix seriously damaged discs alone: in this case it will ask you to
  213. run eliminate or hardfix to fix what it can't.
  214.  
  215.  
  216. Bugs
  217. ----
  218.  
  219. Sometimes, on heavily damaged disc, you need to run fsck more than once even
  220. if it doesn't tell you to do so.
  221. fsck could have problems with RISCiX partitioned discs: it works with the
  222. only RISCiX partitioned disc I tried it on, but I cannot be sure it will work
  223. on yours, too. If you have such a disc and fsck reports strange errors (or
  224. says to run hardfix to fix it) please mail me the logfile and (more important)
  225. the disc data saved by hardfix.
  226.  
  227.  
  228. Results achieved up to now
  229. --------------------------
  230.  
  231. If you run fsck on your corrupted HD, please let me know! If it wasn't able
  232. to fix it, I'll try to modify it to cope with your problem. If you want to
  233. stay anonymous tell me not to include your name!
  234.  
  235. Positive results:
  236.  1) some 800K ADFS floppy (used during development).
  237.  2) 100Mb IDE (ICS interface) partitioned in 84Mb/16Mb (both partitions
  238.     fixed). Owner: Sergio Monesi (ie. me!)
  239.  3) 100Mb IDE (ICS interface). Owner: Cristian Ghezzi
  240.  4) 314Mb SCSI (Serial Port Alpha SCSI interface). Owner: K. Bailey
  241.  5) 60Mb IDE (A4 portable). Owner: G. Castagno
  242.  6) 48Mb SCSI (Oak 16 Bit interface). Owner: A.M. Baardholt
  243.  7) 40Mb ST506. Owner: A. Goodfellow
  244.  8) 80Mb IDE (A5000). Owner: Julian Wright
  245.  9) 240Mb SCSI (HCCS 8 bit interface) partitioned in 2*120Mb. Owner: Kai
  246.     Schlichting.
  247. 10) 245Mb IDE (A5000). Owner: H. M.
  248. 11) 80Mb IDE (A5000). Owner: Mike Henry
  249. 12) 121Mb SCSI (Lingenuity SCSI interface). Owner: R. Z.
  250. 13) 100Mb SCSI (Oak interface). Owner: JP Hendrix
  251. 14) 60Mb IDE (A4 portable). Owner: J. Wallace
  252. 15) 122Mb SCSI (Atomwide Parallel/SCSI interface). Owner: J. Wallace
  253. 16) 80Mb IDE (A5000). Owner: P. Callan
  254. 17) 240Mb SCSI (Morley Cached interface). Owner: P. Callan
  255. 18) 80Mb SCSI (Morley Cached interface). Owner: P. Callan
  256. 19) Some 45Mb Syquest Removable cartridges. Owner: P. Callan (this poor dude
  257.     has a lot of discs, all of them were broken, now successfully fixed!!)
  258. 20) 40Mb ST506. Owner: G. Riley
  259. 21) 40Mb IDE (Serial Port interface). Owner: G. Riley
  260. 22) 40Mb ST506. Owner: M. Ferrari
  261. 23) 240Mb IDE (A5000). Owner: E. Pfarr
  262. 24) 200Mb SCSI. Owner: S. Williams
  263. 25) 500Mb SCSI. Owner: S. Williams
  264. 26) 314Mb SCSI (Morley interface). Owner: Cy Booker
  265. 27) 60Mb IDE (A4 portable). Owner: M. Stephens
  266. 28) 105Mb SCSI (HCCS 8 bit interface). Owner. S. Huber
  267. 29) 20Mb IDE (Watford interface). Owner: S. Pollard
  268. 30) 57Mb SCSI (Lingenuity interface). Owner: M. Grimminck
  269. 31) 170Mb IDE (A5000). Owner: M. Ebourne
  270. 32) 40Mb ST506. Owner: M. Attenborough
  271. 33) 120Mb IDE (ICS interface). Owner: J. Haslam
  272. 34) 170Mb SCSI (Oak 16 Bit interface). Owner: P. Spencer
  273. 35) 116Mb IDE (Desktop Projects interface). Owner: A.D. Hodgkinson
  274. 36) 420Mb IDE (A5000). Owner: E. Pronk
  275. 37) 210Mb IDE (Risc PC). Owner: E. Hughes
  276. 38) 105Mb IDE (ICS interface). Owner: C. Whitehead
  277. 39) 200Mb SCSI (Acorn Interface). Owner: A. Malara
  278. 40) 120Mb IDE (A5000). Owner: B. Bommer
  279. 41) 105Mb IDE Syquest Removable cartridge (A5000). Owner: B. Bommer
  280. 42) 52Mb SCSI (Lingenuity interface). Owner: Kjetil Bernhard Thomassen
  281. 43) 122Mb SCSI (Lingenuity interface). Owner: P. Gillham
  282. 44) 120Mb SCSI (A540). Owner: D.A. Crossley
  283. 45) 48Mb SCSI (Oak 16 Bit interface). Owner: R. McMinn
  284. 46) 32Mb SCSI (Lingenuity interface). Owner: P. Chambers
  285. 47) 210Mb IDE (Risc PC). Owner: C. McEvoy
  286. 48) 80Mb IDE (Evolution 16 Bit). Owner: E. Furtner
  287.  
  288. Probably many other discs have been fixed but their owner didn't contacted
  289. me...
  290.  
  291. Negative results:
  292.  No negative results till now.
  293.  
  294.  
  295. History
  296. -------
  297.  
  298. 1.00   First fully working version. Released only via e-mail.
  299. 1.01   Fixed a bug concerning filing system names. Added -D option. Now fsck
  300.        generally needs only one run to fix a heavily corrupted disc. Added
  301.        eliminate program.
  302. 1.02   Changed again the method to check filing system names (Thanks to
  303.        Keith Bailey). Added percentages in statistics. Checks boot block
  304.        checksum and shows defect list.
  305. 1.03   Now it is possible to scan a single directory instead of the whole
  306.        disc. You can specify 'relative' pathnames (eg. @.Examples) instead
  307.        of full paths (Thanks to Julian Wright). At the end of the scan fsck
  308.        will tell you which files should be eventually deleted. Added
  309.        statistics about fragmented files and free blocks sizes. Changed the
  310.        'F's and 'D's with a rotating wheel... Added -q and -l options.
  311. 1.04   Cured a serious bug that has always been present but never caused
  312.        problems (until 1.03). Added ImageFSFix check and -I option. Now fsck
  313.        understands RISCiX partitions.
  314. 1.10   RISCiX partitions are now fully supported (ie. mapped out). First
  315.        version distributed as SHAREWARE.
  316. 1.11   Added -a option. The logfile is appended to the end of the file if it
  317.        already exists and now it contains the creation date. Great speed
  318.        increase (up to 2 times faster without -s and 5 times faster with
  319.        -s!!!). Now fsck is just 25% slower than *CheckMap (or 2 times slower
  320.        with -s)! Added the note about "Free space chunks statistics" (see
  321.        the section Notes).
  322. 1.12   Another speed improvement (just 10%)! fsck isn't yet as fast as
  323.        *CheckMap but I'm working on it ;-) Fixed a possible dangerous
  324.        behaviour of -a option. Added a warning for HD boot blocks marked as
  325.        defect. Slowed down the wheel. Added files MapExpl and StatsHelp.
  326. 1.13   Faster again (15% with -s, 3% without)!! Now statistics are just a bit
  327.        slower than normal mode. Automatic creation of lostdir. More messages
  328.        at the end of the process that can help to understand what happened
  329.        (ie. the disc is fixed, fixable, unfixable, etc.) and more helpful
  330.        error messages (no more "Can't find 'AD::0.$': incorrect FS") if the
  331.        floppy drive is empty!
  332. 1.20   Completely rewritten! As you would expect: *FASTER* (this is
  333.        probably the maximum achievable speed with the structure of fsck, so
  334.        don't expect further significant improvements!). Now fsck is 20-30%
  335.        faster than *CheckMap, even with statistics enabled! Directory
  336.        recognition added (see the "What it does" secton). No more files to
  337.        move (so many people complained about this)! Added -m and -n options
  338.        to 'simulate' 1.13 version. Added -c option to simulate CheckMap (!).
  339.        Removed the obsolescent -a option. Fixed problems with ImageFSFix
  340.        module and removed -I option. If some file has allocation problems,
  341.        the name of the file is reported together with the error, so that you
  342.        can use 'eliminate' to remove it. Fixed a lot of bugs, some more
  343.        sensible messages and more consistent way to print some value. Added
  344.        new statistics about files that must be fragmented. Modified command
  345.        line behaviour: if no 'pathname' is given, fsck scans the current
  346.        disc (as CheckMap does). Added 'hardfix' program. Added '!QuickFix'
  347.        and '!Intro' files. Modified most of this help file, removed the "Can
  348.        a serious filing system corrupt discs?" section that contained only my
  349.        (debatable) opinions and added "fsck and Risc PC" section.
  350. 1.21   Fixed some minor bug and added some error trapping. Added and
  351.        documented a sensible return code and the system variable
  352.        fsck$ReturnCode. Fixed some bugs in the directory relinking feature.
  353. 1.22   Fixed bug that caused problems when relinking directories that share
  354.        sectors with other files to relink. Fixed problems related to non-ADFS
  355.        partitions. Fixed a bug that caused wrong IDs to be relinked in very
  356.        infrequent cases. Removed the limit on the number of IDs to relink
  357.        (ie. no more "Too many IDs to relink" errors).
  358.  
  359.  
  360. Thanks go to:
  361. -------------
  362.  
  363. - Keith Bailey who discovered that the first 3 versions of fsck were
  364.   completely useless on his SCSI!! The 4th version finally fixed his
  365.   map problems (twice!). Thanks for the comment about the clock too! :-)
  366. - Adam Goodfellow and Atle Mjelde Baardholt for the beta-testing.
  367. - Hans Ole Rafaelsen who tried fsck on 1.6Mb floppies.
  368. - Julian Wright for his beta-testing, suggestions, PRM docs, bugs-report and
  369.   interest.
  370. - Ernest Ong who suggested me to write a map-corruptor program to test fsck:
  371.   'eliminate' is ready, now I am working on 'corrupter' ;-)
  372. - Cristian Ghezzi who let me play with his RISCiX partitioned SCSI for a
  373.   whole day to discover some stupid fsck bug. He also let me intentionally
  374.   corrupt his ST506 disc to test the new directory recognition feature...
  375. - Andreas Schubert (Platon) who tried fsck on his Risc PC.
  376. - Kai Schlichting who said that fsck was one of the most useful 'Unix ports'
  377.   for RISC OS, a program that the Acorn world really needed. Kai has been
  378.   the first who sent me 'something' to register!
  379. - Mike Henry who has been the first who sent me some pounds to register
  380.   (actually he sent me 10 pounds instead of the 5 I ask!).
  381. - Dag Haakon Myrdal for his suggestions and accurate bug report.
  382. - Martin J. Ebourne for his (initially negative but now generally positive)
  383.   comments and support.
  384. - Simon Middleton who pushed me to finish the new version (1.20) so that he
  385.   could include it in his PD/ShareWare CD-ROM.
  386. - Jason Williams (and all the other collaborators) for DeskLib: the new
  387.   versions of fsck use some small part of DeskLib and the new sources
  388.   structure is really similar to DeskLib's one.
  389. - the person who spread on Internet a document describing the E-Format
  390.   structure.
  391. - Mohsen Alshayef for his !ArcTools, a very useful utility that allowed
  392.   me to search in the ROM FileCore module for some code...
  393.  
  394.  
  395. Conditions of use
  396. -----------------
  397.  
  398. fsck can only be distributed with the complete fsck suite.
  399. Read the !SHAREWARE file for the conditions of use and distribution of the
  400. whole package.
  401.  
  402.  
  403. I can be contacted at the following address:
  404.  
  405. Sergio Monesi
  406. Via Trento e Trieste 30
  407. 20046 Biassono (MI)
  408. Italy
  409.  
  410. E-mail address:
  411. pel0015@cdc8g5.cdc.polimi.it
  412. If you don't receive a reply (or if the message is bounced) I can also be
  413. contacted at:
  414. sergio@freebsd.first.gmd.de
  415. or:
  416. sergio@phantom.com
  417.  
  418. WWW:
  419. http://cdc8g5.cdc.polimi.it/~pel0015/
  420.