The UNIX File System Debugger -- FSDB
Of the many different debuggers available under UNIX
-- such as
the C language debuggers adb and sdb, dbx, and
CodeView -- one of the least commonly used is fsdb,
file system debugger. The reasons for fsdb's unpopularity
several: it is difficult to use; it does not guard for
and it has no "undo" facility. Despite these
however, fsdb offers some powerful capabilities not
fsdb can be used to resolve file system inconsistencies
fsck might consider fatal. One such example is the "ROOT
INODE NOT DIRECTORY" error. When fsck sees this
it aborts; with fsdb the root inode can be restored,
problems are likely to occur.
fsdb is typically used for correcting filenames that
with invalid or embedded control characters. ( A program
this purpose was written by Rebecca Thomas and published
World, February 1991.)
fsdb can be started with either the block or the character
device name of the file system on which the work needs
to be performed,
as it will work equally well with either device. The
syntax is as
# fsdb /dev/fd148ds9
Once started, fsdb reports on the size of the
file system being examined. It also performs some simple
on startup. For example, if the size of the ILIST is
than the size of the file system, then the superblock
Unlike fsck, fsdb allows you to operate on MOUNTED
file systems. This is because fsdb assumes that you
you are doing and will do whatever you ask of it.
The only command line option for fsdb is "-",
instructs fsdb to disable the bounds checking it performs
startup. The bounds checking can also be disabled after
has started by using the O command.
fsdb is not for the faint of heart. It is not user friendly,
and it doesn't provide many of the expected user amenities:
detailed error messages, etc. To top it all off, many
of the commands
mean one thing when used one way, and something completely
when used another.
fsdb commands operate on the information at an address.
the address to be worked on is not specified in the
the current address is used. The address in use may
be a disk block,
a byte address, or an inode. It should be stressed that
address may have changed depending upon the last command
a read was issued, then the address may have changed
once the read
was completed. (For an overview of fsdb commands, including
its print facility commands, see Table 1).
To see the information on a particular inode, use the
preceded by the number of the inode. Listing 1 shows
how to view the
root inode. Using the mnemonic followed by an equal
sign (as in ln=),
you can change anything in the inode with the exception
of the ct
value (altering the ct value is considered a security
However, you can still change anything, including the
the file, by changing the link count to zero. (For a
list of the mnemonics
used in an fsdb display, see Figure 1.)
As mentioned earlier, fsdb can be used to correct, or
attempt to correct, problems in inodes. The degree of
on the severity of the problem.
For example, if fsck reports that the root inode is
directory type, you can use fsdb's md (or mode)
mnemonic to set the mode to type directory. The legal
modes for System V UNIX are shown in Figure 2. The "XXX"
each of the modes are the permission positions.
Listing 2 shows how to set the damaged root inode back
to type directory.
Note that fsdb responds with the address being changed,
the octal and decimal values it has been changed to.
is perhaps a desperate measure, especially for the root
it is highly likely that there will be many other problems
Displaying directories involves a little more than displaying
First, make sure that you know the inode number of the
want to view (from having tried it, I can assure you
the directory structure using fsdb can be an exercise
Remember where file names are, and what you see in inodes?
have to read the name list for every directory to see
where you were.)
To find the inode number of the directory, use the ls
This command lists the inode number only for the directory,
all of the files in the directory as ls -i would.
# ls -id /u/chris
results in the display
To display the directory, use the command shown in Listing
3. In this
command line, 3392i instructs fsdb to use the inode
number, 3392, as the address, f tells it to print file
and d requests fsdb to print the contents as directory
Notice that fsdb lists a total of 64 slots, whether
all 64 are used. This is because a directory entry under
is 16 bytes long, and 64 entries can fit into one 1024-byte
The print facilities can be terminated at any time by
typing the INTERRUPT
If there are more entries -- that is, if the address
of the second
block (a1) is not zero -- you can use wither of two
to display them. The first is the f1d command, which
the file print facility to print the next block. This
because after part of a file has been printed, the current
in the file is where the print terminated.
You can also use the example from the fsdb manual pages:
This command says that the block address of the current
should be printed (p) listing all (0) entries in directory
Changing Other Inode Values
The most common use for fsdb is to fix corrupted file
that is, names that cannot be read because they contain
or embedded control codes. Before changing anything,
must display the contents of the directory file.
fsdb provides two mnemonics for the items in a directory
the first, dN (where N is the entry number) refers to
the slot in the directory.
Changing the value of the directory slot assigns the
number to the entry.
To assign a new inode to slot 2, you would use
where 13 is the inode to which this directory entry
The second mnemonic allows you to change the name associated
a particular entry:
where N is the entry number and nm indicates
that the name portion of the entry is to be modified.
Note from the
mnemonics list that =" is used to assign a string
string is the new file name.
fsdb will know that the value is a string if the first
is alphabetic, but if you must use numbers or a period
to start the
file name, you will have to use the quotes.
Figure 3 shows two files, test, and testx. In
Using fsdb to Read the Superblock
Listings 4, 5, and 6 demonstrate the commands used to
read the superblock
and show how to interpret the output using the file
as defined in /usr/include/sys/filesys.h.
The output of fsdb as shown in Listing 4 is exactly
user would see when using fsdb. The superblock is from
AT-based system, using SCO XENIX 2.3.4.
To verify the information, and perhaps save yourself
you may want to use the sb.c program in Listing 5, or
version, sb.pl, in Listing 6, both of which will dump
of the superblock from the filesystem specified. Listing
7 shows the
file system structures translation for this Perl program,
Table 2 shows command examples from various manuals.
It is included
to give you a sense of the strange variations into which
can be cast into.
Thomas, Rebecca, and Farrow, Rik. UNIX Administration
System V. New Jersey: Prentice-Hall, 1989.
Ritchie, D.M., and Thompson, K. "The UNIX Time-Sharing
in UNIX System Readings and Applications, Volume 1.
Thompson, K. "UNIX Implementation," in UNIX
and Applications, Volume 1. New Jersey: Prentice-Hall,
Santa Cruz Operation. SCO XENIX Installation and Maintenance
Santa Cruz: SCO, 1989.
AT&T. UNIX System V/386 Release 3.2 System Administrator's
Manual. New Jersey: Prentice-Hall, 1989.
Bach, Maurice. The Design of the UNIX Operating System.
Jersey: Prentice Hall, 1986.
Kernighan, Brian W., and Pike, Rob. The UNIX Programming
New Jersey: Prentice Hall, 1984.
Fiedler, David and Hunter, Bruce. UNIX System Administration.
Indiana: Hayden Books, 1986.
About the Author
Chris Hare is Ottawa Technical Services Manager for
Systems, Inc. He has worked in the UNIX environment
since 1986 and
in 1988 became one the first SCO authorized instructors
He teaches UNIX introductory, system administration,
classes. His current focus is on networking, Perl, and