NAME

fscheck − perform consistency check on file system

SYNOPSIS

fscheck -dev device -part partition [options]

OPTIONS

−dev deviceDevice is the root name of a device, i.e. rxy0, rsd1, rsb0

−part partition
Partition is a letter indicating a partition, i.e. a, b, c, d, e, f, g. 

−dir devDirDevDir is an alternate directory in which to find the device file named by concatenating Device and Partition.  The default directory name is “/dev/“. 

−initialPart firstPartName
firstPartName is the name of the initial partition on the disk which contains basic disk geometry information.  The default is partition “a”. 

−writeWrite the disk when errors are encountered and fixed.  The default is to not write the disk. 

−silentDon’t say anything unless there is an error. 

−verboseOutput verbose information about errors.  The default is to print out terse information. 

−incVersionIf the domain was not written back properly on system shutdown then all version numbers will be incremented. 

−fixRootRe-create a missing or corrupted root directory. 

−clearClear the domain number field stored in the summary sector. 

−hostID idUpdate the host ID in the disk header. If id is not 0 then it is used as the host id to put in the header. If id equals 0 then one of two values are used as the host id.  If the device server is the local host then the kernel’s internal idea of its host id is used, otherwise the device server’s id is used. 

−badBlockInitialize the bad block file descriptor. 

−outputFile outputFile
All output to stdout and stderr is also appended to outputFile. 

−bufferSize size
Set the size of the buffer associated with outputFile to size bytes.  Default is to use whatever buffer is provided by the stdio library.  This option has no effect if the −outputFile option is not used. 

−rootPartThis option controls the output to a file. If the −outputFile option is not given then this option has no effect.  Otherwise, the output is stored in a buffer and only written to the file when the program exits.  This allows the output to be written to a file on the partition being checked (usually the output is written to the root partition).  The file IO in this case is very primative and restrictive. The output file must be in the root directory and must exist prior to running fscheck.  If the size of the output exceeds the size of the file or if it exceeds the size of the direct data blocks then it will be truncated. If the output exceeds the size of the internal buffer it will be truncated (see −bufferSize ).  If the output is smaller than the size of the file, the remaining part of the file will be filled with null characters.  Any file produced by this option will have a decimal number in the first line which represents the number of bytes in the file. This is used by fscheck to calculate the starting point for appending.  The output file can be reset by either setting the first number to 0 or by overwriting the file with null characters. 

−heapLimit size
Program will not allocate more than size bytes of memory. Default is to allocate as much as is needed. 

−deleteIf a data block is shared by more than one file, delete it from all but one of the files. The default is to make a copy of the block for each file sharing the original. 

−readBlock count
Read count blocks at a time when reading the file descriptors. Currently this does not provide better performance due to limitations in the disk interface library.

−debugPrint out debugging information. 

−bitmapVerbose
Print out lots and lots of information about errors in the bitmaps.

−numReboot count
Number of consecutive times to reboot before returning a warning indication.

−clearFixCount
Clear consecutive fix counter.
 

DESCRIPTION

This program will perform a consistency check on a file system.  By default it will report inconsistencies but won’t repair them.  If the −write option is used then it will repair any inconsistencies by modifying the disk as necessary. 

This program performs the following consistency checks:

1.It makes sure that the file descriptor allocation bit map agrees with the status information kept in each file descriptor.  If necessary it will correct the bit map. 

2.It confirms that data-block and indirect-block pointers are valid.  If a pointer is invalid then the pointer is set to NIL and the file size is adjusted as necessary to reflect the new size of the file. 

3.It recreates the data block allocation bit map based on information in the file descriptors and indirect blocks. 

4.It checks for blocks that are allocated to more than one file.  If a block is multiply allocated then copies of the block are made and all but one of the files is corrected to use a copy.  If the −delete option is given, or if only a subset of the fragments in a block are shared, then the block is given to the lowest numbered file descriptor and it is removed from all other files that reference it.  A special case is made of block 0. This block belongs to the root directory and is copied (or deleted) for all other files even if the root directory is corrupted or doesn’t exist. 

5.It verifies that directories are of the proper format.  In order to patch a directory, names may be deleted, the directory may be truncated, or in the worst case the directory may be turned into a normal file. 

6.It puts unreferenced files into the lost+found directory.  The name of each file in the lost+found directory is the file’s file descriptor number. 

7.It corrects link counts and block counts in each file descriptor. 

8.It checks that indirect blocks contain valid pointers. If the pointers are invalid and the block is part of a file then a hole is created, otherwise if the block is part of a directory then the directory is truncated. 

9.It checks that each file descriptor contains a valid magic number. If this is not the case then the file descriptor is cleared and marked as unused in the bitmap. 

10.It recreates the root directory if it is corrupted and the −fixRoot option is given. 

By default only terse information is given about the errors in the file system.  Only the first error per file is reported.  If the −verbose option is given then more verbose information will be given.  If the −bitmapVerbose option is given then differences between the bitmaps on disk and the recreated bitmaps are printed. Since the bitmaps on disk are not kept current use of this option is likely to produce lots of output. 

The fscheck program will also perform other actions depending on the options that are specified.  If the −incVersion option is given then flags in the file system header are checked to see if the file system was safely written back when it was detached or the system went down.  If it is determined that the file system was not safely written back then the version numbers for all files in the file system are incremented.  This will cause all reopens of files because of recovery to fail. 

If the −fixRoot option is given the root directory will be recreated if it has become corrupted.  If the root is recreated, then any directories that have the root directory as their parent will be inserted into the root with their file descriptor number as their name.  Any files that used to be in the root directory will be placed in lost+found.  Fscheck assumes that data block 0 belongs to the root directory and will allocate this block to the directory when reconstructing it.  The −fixRoot option requires reading the root directory twice, hence it cannot be used without the −write option. 

The −clear option should be used if the domain number field should be cleared from the summary sector.  Each file system that is attached is given a domain number under which it can be identified.  When a file system is attached, the system will try to attach it with the same domain number that it was attached under last time.  This is required to allow clients of the file system to recover when the file system is reattached.  If the domain number field is cleared from the summary sector, then the system will attach the file system under a domain number of the system’s choosing. 

The −hostID option will force the system to update the host id in the file system header.  If the device under which the file system is being attached is generic then the id of the host on which fscheck is run is used.  Otherwise the host id specified by the device file is used.  The default is not to modify the host id. 

The −badBlock option will initialize the file descriptor which points to bad disk blocks.  Initializing it will clear out any pointers to bad blocks that are currently in the file descriptor. 

The −heapLimit option can be used to place an upper limit on the size of the program heap. This can be used to prevent paging, since paging cannot be done at the point in the boot sequence when fscheck is run.  If fscheck cannot complete checking the disk because of the limit then it will do as much as it can.  This should allow multiple runs of fscheck to completely check the disk.  The limit is only an approximation of how large fscheck will grow, since the program stack is not restricted. Therefore the limit should be set as high as possible but it should not be set to the boundary at which paging will occur.  If it is set too small then fscheck may not be able to run at all. Note that the bufferSize and readBlock options will affect the amount of heap required.  As a rule of thumb, the amount of heap space needed by fscheck is proportional to the disk size and the amount of errors on the disk.  A heap limit of 1 Mb should be sufficient for all but the most extreme cases. 

Each time fscheck runs and finds an error in a partition, a counter on disk is incremented. The value of this counter is the number of consecutive times fscheck has run on the partition and corrected an error.  If the counter exceeds the value given by the −numReboot option (default 4) and if fscheck corrects an error, then fscheck will return EXIT_NOREBOOT instead of the standard soft error indication.  This allows higher level software to avoid infinite reboot loops. 

The −clearFixCount option resets the consecutive counter to 0. 

Finally, the −output, −bufferSize and −noFlush options control the output from fscheck. The −output option allows the output from fscheck to be put into a file as well as printed on stdout and stderr.  The −bufferSize option sets the size of the IO buffer associated with the output file.  The −noFlush option prevents the buffer from being flushed until the disk has been checked and corrected.  This allows the output to be written to the disk being checked.  If the output exceeds the size of the buffer then it is truncated to the buffer size.  If the buffer size is exceeded in the middle of an output string, then remainder of the string will wrap over the beginning of the buffer. 

EXIT CODES

Fscheck has a large number of exit codes.  Positive values indicate that some sort of error occurred that requires fscheck be run again, although an exit code of 1 indicates that the filesystem was corrupted but was successfully corrected.  Negative error codes indicate that a serious error occurred that requires user action before fscheck can be run again. 

0No errors occurred and no errors were fixed in the filesystem. 

1Errors were fixed in the filesystem. 

2Fscheck ran out of memory before it was able to completely check the disk. Rerunning with the same heap limit should allow fscheck to finish. 

3Errors were fixed in the filesystem and the number of consecutive times fscheck has fixed this partition exceeds the limit. 

-1An unspecified hard error occurred. 

-2A disk read failed. 

-3A disk write failed. 

-4There was a problem with one of the arguments. 

-5The heap limit is too small for fscheck to run. The heap limit must be made larger before rerunning fscheck. 

-6The disk is full so that duplicate blocks cannot be copied. Either delete some stuff or rerun using the −delete option. 

BUGS/FEATURES

Indirect blocks are always marked as in use in the bitmap, even if they contain invalid entries. This is because the block may be in use by another file and cannot be marked as free. 

The −fixRoot option cannot be used without the −write option. 

KEYWORDS

file system, disk

Sprite version 1.0  —  February 15, 1990