1.\" Copyright (c) 1982, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
--- 15 unchanged lines hidden (view full) ---
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" $FreeBSD: head/sbin/fsck_ffs/SMM.doc/3.t 96707 2002-05-16 04:10:46Z trhodes $
33.\" @(#)3.t 8.1 (Berkeley) 6/5/93
34.\"
35.ds RH Fixing corrupted filesystems
36.NH
37Fixing corrupted filesystems
38.PP
39A filesystem
40can become corrupted in several ways.
41The most common of these ways are
42improper shutdown procedures
43and hardware failures.
44.PP
45File systems may become corrupted during an
46.I "unclean halt" .
47This happens when proper shutdown
48procedures are not observed,
49physically write-protecting a mounted filesystem,
50or a mounted filesystem is taken off-line.
51The most common operator procedural failure is forgetting to
52.I sync
53the system before halting the CPU.
54.PP
55File systems may become further corrupted if proper startup
56procedures are not observed, e.g.,
57not checking a filesystem for inconsistencies,
58and not repairing inconsistencies.
59Allowing a corrupted filesystem to be used (and, thus, to be modified
60further) can be disastrous.
61.PP
62Any piece of hardware can fail at any time.
63Failures
64can be as subtle as a bad block
65on a disk pack, or as blatant as a non-functional disk-controller.
66.NH 2
67Detecting and correcting corruption
--- 14 unchanged lines hidden (view full) ---
82.I fsck_ffs
83reports the inconsistency for the operator to
84chose a corrective action.
85.PP
86A quiescent\(dd
87.FS
88\(dd I.e., unmounted and not being written on.
89.FE
90filesystem may be checked for structural integrity
91by performing consistency checks on the
92redundant data intrinsic to a filesystem.
93The redundant data is either read from
94the filesystem,
95or computed from other known values.
96The filesystem
97.B must
98be in a quiescent state when
99.I fsck_ffs
100is run,
101since
102.I fsck_ffs
103is a multi-pass program.
104.PP
105In the following sections,
106we discuss methods to discover inconsistencies
107and possible corrective actions
108for the cylinder group blocks, the inodes, the indirect blocks, and
109the data blocks containing directory entries.
110.NH 2
111Super-block checking
112.PP
113The most commonly corrupted item in a filesystem
114is the summary information
115associated with the super-block.
116The summary information is prone to corruption
117because it is modified with every change to the file
118system's blocks or inodes,
119and is usually corrupted
120after an unclean halt.
121.PP
--- 6 unchanged lines hidden (view full) ---
128The file-system size and layout information
129are the most critical pieces of information for
130.I fsck_ffs .
131While there is no way to actually check these sizes,
132since they are statically determined by
133.I newfs ,
134.I fsck_ffs
135can check that these sizes are within reasonable bounds.
136All other filesystem checks require that these sizes be correct.
137If
138.I fsck_ffs
139detects corruption in the static parameters of the default super-block,
140.I fsck_ffs
141requests the operator to specify the location of an alternate super-block.
142.NH 2
143Free block checking
144.PP
145.I Fsck_ffs
146checks that all the blocks
147marked as free in the cylinder group block maps
148are not claimed by any files.
149When all the blocks have been initially accounted for,
150.I fsck_ffs
151checks that
152the number of free blocks
153plus the number of blocks claimed by the inodes
154equals the total number of blocks in the filesystem.
155.PP
156If anything is wrong with the block allocation maps,
157.I fsck_ffs
158will rebuild them,
159based on the list it has computed of allocated blocks.
160.PP
161The summary information associated with the super-block
162counts the total number of free blocks within the filesystem.
163.I Fsck_ffs
164compares this count to the
165number of free blocks it found within the filesystem.
166If the two counts do not agree, then
167.I fsck_ffs
168replaces the incorrect count in the summary information
169by the actual free-block count.
170.PP
171The summary information
172counts the total number of free inodes within the filesystem.
173.I Fsck_ffs
174compares this count to the number
175of free inodes it found within the filesystem.
176If the two counts do not agree, then
177.I fsck_ffs
178replaces the incorrect count in the
179summary information by the actual free-inode count.
180.NH 2
181Checking the inode state
182.PP
183An individual inode is not as likely to be corrupted as
184the allocation information.
185However, because of the great number of active inodes,
186a few of the inodes are usually corrupted.
187.PP
188The list of inodes in the filesystem
189is checked sequentially starting with inode 2
190(inode 0 marks unused inodes;
191inode 1 is saved for future generations)
192and progressing through the last inode in the filesystem.
193The state of each inode is checked for
194inconsistencies involving format and type,
195link count,
196duplicate blocks,
197bad blocks,
198and inode size.
199.PP
200Each inode contains a mode word.
--- 12 unchanged lines hidden (view full) ---
213.NH 2
214Inode links
215.PP
216Each inode counts the
217total number of directory entries
218linked to the inode.
219.I Fsck_ffs
220verifies the link count of each inode
221by starting at the root of the filesystem,
222and descending through the directory structure.
223The actual link count for each inode
224is calculated during the descent.
225.PP
226If the stored link count is non-zero and the actual
227link count is zero,
228then no directory entry appears for the inode.
229If this happens,
--- 44 unchanged lines hidden (view full) ---
274.I fsck_ffs
275prompts the operator to clear both inodes.
276The operator must decide which one should be kept
277and which one should be cleared.
278.PP
279.I Fsck_ffs
280checks the range of each block number claimed by an inode.
281If the block number is
282lower than the first data block in the filesystem,
283or greater than the last data block,
284then the block number is a
285.I "bad block number" .
286Many bad blocks in an inode are usually caused by
287an indirect block that was not written to the filesystem,
288a condition which can only occur if there has been a hardware failure.
289If an inode contains bad block numbers,
290.I fsck_ffs
291prompts the operator to clear it.
292.NH 2
293Inode data size
294.PP
295Each inode contains a count of the number of data blocks
--- 33 unchanged lines hidden (view full) ---
329.I Fsck_ffs
330can only check the validity of directory data blocks.
331.PP
332Each directory data block is checked for
333several types of inconsistencies.
334These inconsistencies include
335directory inode numbers pointing to unallocated inodes,
336directory inode numbers that are greater than
337the number of inodes in the filesystem,
338incorrect directory inode numbers for ``\fB.\fP'' and ``\fB..\fP'',
339and directories that are not attached to the filesystem.
340If the inode number in a directory data block
341references an unallocated inode,
342then
343.I fsck_ffs
344will remove that directory entry.
345Again,
346this condition can only arise when there has been a hardware failure.
347.PP
--- 37 unchanged lines hidden (view full) ---
385If there are multiple hard links to a directory,
386the first one encountered is considered the real parent
387to which ``\fB..\fP'' should point;
388\fIfsck_ffs\fP recommends deletion for the subsequently discovered names.
389.NH 2
390File system connectivity
391.PP
392.I Fsck_ffs
393checks the general connectivity of the filesystem.
394If directories are not linked into the filesystem, then
395.I fsck_ffs
396links the directory back into the filesystem in the
397.I lost+found
398directory.
399This condition only occurs when there has been a hardware failure.
400.ds RH "References"
401.SH
402\s+2Acknowledgements\s0
403.PP
404I thank Bill Joy, Sam Leffler, Robert Elz and Dennis Ritchie
405for their suggestions and help in implementing the new filesystem.
406Thanks also to Robert Henry for his editorial input to
407get this document together.
408Finally we thank our sponsors,
409the National Science Foundation under grant MCS80-05144,
410and the Defense Advance Research Projects Agency (DoD) under
411Arpa Order No. 4031 monitored by Naval Electronic System Command under
412Contract No. N00039-82-C-0235. (Kirk McKusick, July 1983)
413.PP
--- 40 unchanged lines hidden ---
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
--- 15 unchanged lines hidden (view full) ---
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" $FreeBSD: head/sbin/fsck_ffs/SMM.doc/3.t 96707 2002-05-16 04:10:46Z trhodes $
33.\" @(#)3.t 8.1 (Berkeley) 6/5/93
34.\"
35.ds RH Fixing corrupted filesystems
36.NH
37Fixing corrupted filesystems
38.PP
39A filesystem
40can become corrupted in several ways.
41The most common of these ways are
42improper shutdown procedures
43and hardware failures.
44.PP
45File systems may become corrupted during an
46.I "unclean halt" .
47This happens when proper shutdown
48procedures are not observed,
49physically write-protecting a mounted filesystem,
50or a mounted filesystem is taken off-line.
51The most common operator procedural failure is forgetting to
52.I sync
53the system before halting the CPU.
54.PP
55File systems may become further corrupted if proper startup
56procedures are not observed, e.g.,
57not checking a filesystem for inconsistencies,
58and not repairing inconsistencies.
59Allowing a corrupted filesystem to be used (and, thus, to be modified
60further) can be disastrous.
61.PP
62Any piece of hardware can fail at any time.
63Failures
64can be as subtle as a bad block
65on a disk pack, or as blatant as a non-functional disk-controller.
66.NH 2
67Detecting and correcting corruption
--- 14 unchanged lines hidden (view full) ---
82.I fsck_ffs
83reports the inconsistency for the operator to
84chose a corrective action.
85.PP
86A quiescent\(dd
87.FS
88\(dd I.e., unmounted and not being written on.
89.FE
90filesystem may be checked for structural integrity
91by performing consistency checks on the
92redundant data intrinsic to a filesystem.
93The redundant data is either read from
94the filesystem,
95or computed from other known values.
96The filesystem
97.B must
98be in a quiescent state when
99.I fsck_ffs
100is run,
101since
102.I fsck_ffs
103is a multi-pass program.
104.PP
105In the following sections,
106we discuss methods to discover inconsistencies
107and possible corrective actions
108for the cylinder group blocks, the inodes, the indirect blocks, and
109the data blocks containing directory entries.
110.NH 2
111Super-block checking
112.PP
113The most commonly corrupted item in a filesystem
114is the summary information
115associated with the super-block.
116The summary information is prone to corruption
117because it is modified with every change to the file
118system's blocks or inodes,
119and is usually corrupted
120after an unclean halt.
121.PP
--- 6 unchanged lines hidden (view full) ---
128The file-system size and layout information
129are the most critical pieces of information for
130.I fsck_ffs .
131While there is no way to actually check these sizes,
132since they are statically determined by
133.I newfs ,
134.I fsck_ffs
135can check that these sizes are within reasonable bounds.
136All other filesystem checks require that these sizes be correct.
137If
138.I fsck_ffs
139detects corruption in the static parameters of the default super-block,
140.I fsck_ffs
141requests the operator to specify the location of an alternate super-block.
142.NH 2
143Free block checking
144.PP
145.I Fsck_ffs
146checks that all the blocks
147marked as free in the cylinder group block maps
148are not claimed by any files.
149When all the blocks have been initially accounted for,
150.I fsck_ffs
151checks that
152the number of free blocks
153plus the number of blocks claimed by the inodes
154equals the total number of blocks in the filesystem.
155.PP
156If anything is wrong with the block allocation maps,
157.I fsck_ffs
158will rebuild them,
159based on the list it has computed of allocated blocks.
160.PP
161The summary information associated with the super-block
162counts the total number of free blocks within the filesystem.
163.I Fsck_ffs
164compares this count to the
165number of free blocks it found within the filesystem.
166If the two counts do not agree, then
167.I fsck_ffs
168replaces the incorrect count in the summary information
169by the actual free-block count.
170.PP
171The summary information
172counts the total number of free inodes within the filesystem.
173.I Fsck_ffs
174compares this count to the number
175of free inodes it found within the filesystem.
176If the two counts do not agree, then
177.I fsck_ffs
178replaces the incorrect count in the
179summary information by the actual free-inode count.
180.NH 2
181Checking the inode state
182.PP
183An individual inode is not as likely to be corrupted as
184the allocation information.
185However, because of the great number of active inodes,
186a few of the inodes are usually corrupted.
187.PP
188The list of inodes in the filesystem
189is checked sequentially starting with inode 2
190(inode 0 marks unused inodes;
191inode 1 is saved for future generations)
192and progressing through the last inode in the filesystem.
193The state of each inode is checked for
194inconsistencies involving format and type,
195link count,
196duplicate blocks,
197bad blocks,
198and inode size.
199.PP
200Each inode contains a mode word.
--- 12 unchanged lines hidden (view full) ---
213.NH 2
214Inode links
215.PP
216Each inode counts the
217total number of directory entries
218linked to the inode.
219.I Fsck_ffs
220verifies the link count of each inode
221by starting at the root of the filesystem,
222and descending through the directory structure.
223The actual link count for each inode
224is calculated during the descent.
225.PP
226If the stored link count is non-zero and the actual
227link count is zero,
228then no directory entry appears for the inode.
229If this happens,
--- 44 unchanged lines hidden (view full) ---
274.I fsck_ffs
275prompts the operator to clear both inodes.
276The operator must decide which one should be kept
277and which one should be cleared.
278.PP
279.I Fsck_ffs
280checks the range of each block number claimed by an inode.
281If the block number is
282lower than the first data block in the filesystem,
283or greater than the last data block,
284then the block number is a
285.I "bad block number" .
286Many bad blocks in an inode are usually caused by
287an indirect block that was not written to the filesystem,
288a condition which can only occur if there has been a hardware failure.
289If an inode contains bad block numbers,
290.I fsck_ffs
291prompts the operator to clear it.
292.NH 2
293Inode data size
294.PP
295Each inode contains a count of the number of data blocks
--- 33 unchanged lines hidden (view full) ---
329.I Fsck_ffs
330can only check the validity of directory data blocks.
331.PP
332Each directory data block is checked for
333several types of inconsistencies.
334These inconsistencies include
335directory inode numbers pointing to unallocated inodes,
336directory inode numbers that are greater than
337the number of inodes in the filesystem,
338incorrect directory inode numbers for ``\fB.\fP'' and ``\fB..\fP'',
339and directories that are not attached to the filesystem.
340If the inode number in a directory data block
341references an unallocated inode,
342then
343.I fsck_ffs
344will remove that directory entry.
345Again,
346this condition can only arise when there has been a hardware failure.
347.PP
--- 37 unchanged lines hidden (view full) ---
385If there are multiple hard links to a directory,
386the first one encountered is considered the real parent
387to which ``\fB..\fP'' should point;
388\fIfsck_ffs\fP recommends deletion for the subsequently discovered names.
389.NH 2
390File system connectivity
391.PP
392.I Fsck_ffs
393checks the general connectivity of the filesystem.
394If directories are not linked into the filesystem, then
395.I fsck_ffs
396links the directory back into the filesystem in the
397.I lost+found
398directory.
399This condition only occurs when there has been a hardware failure.
400.ds RH "References"
401.SH
402\s+2Acknowledgements\s0
403.PP
404I thank Bill Joy, Sam Leffler, Robert Elz and Dennis Ritchie
405for their suggestions and help in implementing the new filesystem.
406Thanks also to Robert Henry for his editorial input to
407get this document together.
408Finally we thank our sponsors,
409the National Science Foundation under grant MCS80-05144,
410and the Defense Advance Research Projects Agency (DoD) under
411Arpa Order No. 4031 monitored by Naval Electronic System Command under
412Contract No. N00039-82-C-0235. (Kirk McKusick, July 1983)
413.PP
--- 40 unchanged lines hidden ---