`chkfsys`

Check an entire QNX 4 filesystem for consistency (QNX)

You must be root to run this utility.

Syntax:

When running on QNX 4:

chkfsys [-fpPqrsuvV] [-z zapfile] drive

When running on QNX Neutrino:

chkfsys [-fpPqrsuvV] [-z zapfile] mountpoint

Or:

chkfsys [-fpPqrsuvV] [-z zapfile] -m drive

Options:

-f: Don't fix anything.
-m: (QNX Neutrino only) No mountpoint; the path specified is a raw device/partition.
-p: Prompt before starting.
-P: Suppress prompting (i.e. fix without asking any questions).
-q: Be quiet.
-r: Rebuild the bitmap without prompts or messages.
-s: Suppress the display of statistics.
-u: Check the filesystem, regardless of the status recorded on the disk.
-v: Be verbose. (Shows files in addition to directories as they're being checked. Slows chkfsys considerably.)
-V: Very verbose display.
-z zapfile: Record pathnames of files that 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, /dev/hd0t77).
mountpoint: (QNX Neutrino only) The filesystem mountpoint of the drive (e.g. /).

The chkfsys utility performs a consistency check of a QNX 4 filesystem on the requested drive. The chkfsys utility doesn't operate on disk partitions containing non-QNX filesystems (e.g. DOS partitions, QNX 2 partitions). In addition, chkfsys must have access to the block special file that the filesystem is contained in. For this reason, chkfsys can't 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's 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, chkfsys checks an on-disk flag that's 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 is always 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 use the -u option to force chkfsys to run even if the flag is set.

The chkfsys utility should be used only when the filesystem is stable. There should be NO files open for writing when chkfsys is running. If you make any repairs, remount the filesystem by slaying and restarting the disk driver.

In the normal mode, chkfsys prevents 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 proceeds and also prevents any files from being opened for writing on the drive for the duration of its check.

If you aren't 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. When zap has been used, chkfsys reports 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 attempts to read each of these blocks, but doesn't mark bad blocks as available. Any blocks found this way are added to the /.bad_blks file at the root of the filesystem being checked.

The chkfsys utility tells 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's 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 the zap utility. 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 prevents chkfsys from attempting to make any fixes to the filesystem. The disk isn't 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 speeds up the checking significantly, without loss of information, because chkfsys shows 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 automatically rebuilds the bitmap. Note that this option isn't 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 displays information on the checking.

The -P (no prompt) option causes chkfsys to automatically fix problems encountered without prompting the user before each fix. However, there are some serious errors (disk IO error or corruption of a high level directory) for which the fix may be to remove a directory (and all its hierarchy/contents). This may not be a prudent action to undertake without user confirmation. In such a situation -P will print an error message and exit. If you wish chkfsys to continue unattended in all circumstances, you can specify this as "-PP".

The -z zapfile option is used to record, in the named file, the names of files that should be zapped after chkfsys is finished. The zapfile 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 makes the files "unbusy" and also makes 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 Neutrino System Architecture, 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 is 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 just 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've tried to anticipate.

Examples:

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

chkfsys /hd

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 doesn't 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.