`chkfsys`

Check an entire QNX filesystem for consistency (QNX)

Syntax:

chkfsys [-PefpqrsuvV] [-z zapfile] drive

Options:

-e: If possible, disable drive error correction during check for bad blocks.
-f: Don't fix anything.
-p: Prompt before starting.
-P: Prompt suppression (i.e. fix without asking any questions)
-q: Be quiet.
-r: Rebuild the bitmap without prompts or messages.
-s: Suppress statistics display.
-u: Check filesystem regardless of status recorded on disk.
-v: Be verbose. (Shows files in addition to directories as they are being checked. Slows chkfsys considerably.)
-V: Very verbose display.
-z zapfile: Record pathnames of files which need to be zapped in the specified file. The zapfile must reside on a different filesystem from the one being checked.
drive: The disk to check (e.g. /dev/fd0 or /dev/hd0t77 or /).

The chkfsys utility performs a consistency check of a QNX filesystem on the requested drive. The chkfsys utility will not operate on disk partitions containing non-QNX filesystems (e.g. DOS partitions, QNX2 partitions). In addition, chkfsys must have access to the block special file that the filesystem is contained in. For this reason, chkfsys cannot be used on NFS-mounted QNX filesystems.

For QNX filesystems chkfsys recursively walks the filesystem, checking every file on the disk. During the walk, checks are made on the directory entry of each file and the extents that make up the file. A bitmap is constructed in memory that is consistent with the block allocation of all files and directories on the disk. This bitmap is then compared to the existing one on the disk. If they differ, the user is given the option of replacing the existing bitmap on disk with the one constructed in memory.

By default on systems running QNX 4.23 and later, chkfsys checks an on-disk flag which is maintained by the filesystem that indicates to chkfsys whether or not anything needs to be checked. If the flag is set, chkfsys reports that everything is fine and exits immediately. When you do an orderly shutdown of the system, this flag will always be set (unless an error had occurred in the process). If you shut down the system by powering down, the flag may or may not be set depending on the state of the filesystem at the time. You can force chkfsys to run despite the flag being set by using the -u option.

The chkfsys utility should be used only when the filesystem is stable. There should be NO files open for writing when chkfsys is running.

In the normal mode, chkfsys will prevent its own operation when any files are open for writing on the drive. If chkfsys finds that no files are open for writing on the drive, it will proceed and will also prevent any files from being opened for writing on the drive for the duration of its check.

If you're not doing any fixes (with the -f option), you may check a filesystem with open files, but beware: you may get inconsistent reports in this case.

The chkfsys utility is normally used to recover blocks that were lost through the use of the zap utility. For example:

    zap file1

In this case, chkfsys will report that there are blocks used in the bitmap that are in fact not used by any file. These blocks may be recovered by writing the reconstructed bitmap back to disk. The chkfsys utility will attempt to read each of these blocks, but will not mark bad blocks as available. Any blocks found this way will be added to the /.bad_blks file at the root of the filesystem being checked.

The chkfsys utility will tell you if any files are using blocks that are now known to be bad.

If chkfsys reports that a block is used by more than one file, this could indicate one of two problems:

If bad blocks exist, then this means that the file uses a block that is bad and marked as used in the bitmap.
If there are no known bad blocks, then a multiple allocation of a single block has occurred.

In either case, the file should be saved on another disk (if possible), and the original file should be destroyed with zap. The chkfsys utility should then be run again to update the bitmap, after which the saved file may be restored onto this disk.

In general, whenever the bitmap is replaced, chkfsys should be run a second time to ensure that the filesystem is indeed consistent. To do so you must specify the -u option.

The -f (no fix) option will prevent chkfsys from attempting to make any fixes to the filesystem. The disk will not be opened for write, but only for read. This option lets a user examine the filesystem without requiring other users to stop using the disk or filesystem. Beware, however, that the -f option may report errors that don't really exist (if other users are opening, closing, or growing files during the time that chkfsys is running). Even so, this can be a valuable option for sites that are up and running 24 hours a day, when the system operator carefully evaluates the results. If you see errors that you believe result from current activity, run chkfsys again with the -f option to verify the errors. If you have located errors that require fixing, you should idle the filesystem and run chkfsys without the -f option.

The -p (pause) option is used primarily with floppy disks. You can start chkfsys from a floppy diskette, wait for chkfsys to pause, remove the current disk (which contains the chkfsys command), and then insert another disk you wish to check.

The -q (quiet) option suppresses the display of each filename as that file is checked. This will speed the checking significantly, without loss of information, because chkfsys will show you the name of any files that have errors.

The -r (rebuild) option suppresses the warning message that normally appears at the end of a chkfsys run when the existing bitmap differs from the newly constructed bitmap in memory. When -r is specified, chkfsys will automatically rebuild the bitmap. Note that this option is not effective with the -f (no fix) option.

The -s (no stats) option prevents the display of the statistics message that normally appears at the end of a chkfsys run.

The -v (verbose) option will display information on the checking.

The -P (no prompt) option will cause chkfsys to automatically fix problems encountered without prompting the user before each fix. Note that the -P option won't work with the -f option.

The -z zapfile option is used to record the names of files which should be zapped after chkfsys is finished to the named file, which must be on a different filesystem from the one being checked. When a file is found to use an area of the disk allocated to another file, or when a file uses an area of the disk marked as bad in the bitmap, the files must be zapped and chkfsys run again.

After a power failure

The chkfsys utility may also be run after a system crash or power failure, which may have left some files busy. The utility will make the files "unbusy" and will also make checks to ensure that no damage to the filesystem has occurred. QNX is designed to be immune to this type of damage.

In the event of the loss of a filesystem due to the corruption of the root directory and the bitmap (first few blocks of the disk), you should refer to the QNX System Architecture and Installation & Configuration manuals, and the dinit utility documentation for methods of initializing just those portions of your disk. If only the root block and bitmap are damaged, chkfsys will be able to recover the files in most cases. If the root directory or inode file is damaged (the next areas on the disk), recovery may be possible with the dinit, spatch, and chkfsys utilities. Note that such repair requires intimate knowledge of the filesystem structure. Many users would simply recover lost files from a backup at this point. You shouldn't expect to run into such problems; these are very rare events that we have simply tried to anticipate.

Examples:

Check the filesystem on the QNX partition of a hard disk:

chkfsys /dev/hd0t77

Check the QNX filesystem mounted as the root (/) and automatically rebuild the bitmap:

chkfsys -rs /

Exit status:

0: The filesystem(s) have been checked. An exit status of zero does not indicate that no problems were found. It merely indicates that no irrecoverable errors internal to the chkfsys utility were encountered.
>0: The filesystem(s) may not have been checked. The chkfsys operation may have been interrupted at the request of the user or an internal error (such as running out of memory) may have occurred.