<refentry id="dcheck">
<refnamediv>
<refname>DCHECK</refname>
<refpurpose>Check Disk File Structure</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>dcheck</command>
<arg choice="opt">
  <option>-opts</option>
</arg>
<arg choice="plain">
  <replaceable>devnam</replaceable>
</arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1><title>Description</title>
<para>
It is possible for sectors on a disk to be marked as being allocated
but in fact are not actually associated with a file or the disk's
free space. This can happen if a disk is removed from a drive while
files are still open, or if a directory which still contains files
is deleted (see <xref linkend="sec3.5"/>). <command>Dcheck</command> is a diagnostic that can be used to
detect this condition, as well as the general integrity of the directory/file linkages.
</para>
<para>
<command>Dcheck</command> is given as a parameter the name of the disk device to be
checked. After verifying and printing some vital file structure
parameters, <command>dcheck</command> follows pointers down the disk's file system tree
to all directories and files on the disk. As it does so, it
verifies the integrity of the file descriptor sectors, reports any
discrepancies in the directory/file linkages, and builds a sector
allocation map from the segment list associated with each file. If
any file descriptor sectors (FDs) describe a segment with a cluster
not within the file structure of the disk, a message is reported
like:
</para>
<screen>
*** Bad FD segment ($xxxxxx-$yyyyyy) for file: <replaceable>pathlist</replaceable>
</screen>
<para>
This indicates that a segment starting at sector xxxxxx and ending
at sector yyyyyy cannot really be on this disk. Because there is a
good chance the entire FD is bad if any of it's segment descriptors
are bad, the allocation map is <emphasis>not</emphasis> updated for corrupt FDs.
</para>
<para>
While building the allocation map, <command>dcheck</command> also makes sure that each
disk cluster appears only once and only once in the file structure.
If this condition is detected, <command>dcheck</command> will display a message like:
</para>
<screen>
Cluster $xxxxxx was previously allocated
</screen>
<para>
This message indicates that cluster xxxxxx has been found at least
once before in the file structure. The message may be printed more
than once if a cluster appears in a segment in more than one file.
</para>
<para>
The newly created allocation map is then compared to the allocation
map stored on the disk, and any differences are reported in messages
like:
</para>
<screen>
Cluster $xxxxxx in allocation map but not in file structure
Cluster $xxxxxx in file structure but not in allocation map
</screen>
<para>
The first message indicates sector number xxxxxx (hexadecimal) was
found not to be part of the file system, but was marked as allocated
in the disk's allocation map. In addition to the causes mentioned
in the first paragraph, some sectors may have been excluded from the
allocation map by the FORMAT program because they were defective or
they may be the last few sectors of the disk, the sum of which was
two small to comprise a cluster.
</para>
<para>
The second message indicates that the cluster starting at sector
xxxxxx is part of the file structure but is <emphasis>not</emphasis>
marked as allocated
in the disk's allocation map. It is possible that this cluster may
be allocated to another file later, overwriting the contents of the
cluster with data from the newly allocated file. Any clusters that
have been reported as &quot;previously allocated&quot; by <command>dcheck</command> as described
above surely have this problem.
</para>
<para>
Available <command>dcheck</command> options are:
</para>

<informaltable frame="none">
<tgroup cols="2">
<colspec colwidth="1.3in"/>
<colspec colwidth="3in"/>
<tbody>
<row>
<entry>-w=<replaceable>path</replaceable></entry>
<entry>pathlist to directory for work files</entry>
</row>
<row>
<entry>-p</entry>
<entry>print pathlists for questionable clusters</entry>
</row>
<row>
<entry>-m</entry>
<entry>save allocation map work files</entry>
</row>
<row>
<entry>-b</entry>
<entry>suppress listing of unused clusters</entry>
</row>
<row>
<entry>-s</entry>
<entry>display count of files and directories only</entry>
</row>
<row>
<entry>-o</entry>
<entry>print <command>dcheck</command>'s valid options</entry>
</row>
</tbody>
</tgroup>
</informaltable>

<para>
The &quot;-s&quot; option causes <command>dcheck</command> to display a count of files and
directories only; only FDs are checked for validity. The &quot;-b&quot; option
suppresses listing of clusters allocated but not in file structure.
The &quot;-p&quot; option causes <command>dcheck</command> to make a second pass through the file
structure printing the pathlists for any clusters that <command>dcheck</command> finds
as &quot;already allocated&quot; or &quot;in file structure but not in allocation
map&quot;. The &quot;-w=&quot; option tells <command>dcheck</command> where to locate it's allocation
map work file(s). The pathlist specified must be a FULL pathlist to
a <emphasis>directory</emphasis>. The directory &quot;/D0&quot; is
used is used if &quot;-w&quot; is not
specified. It  is recommended that this pathlist NOT be located on
the disk being <command>dcheck</command>ed if the disk's file structure integrity is in
doubt.
</para>
<para>
<command>Dcheck</command> builds its disk allocation map in a file called
<replaceable>pathlist</replaceable>/DCHECKppO, where <replaceable>pathlist</replaceable>
is as specified by the
&quot;-w=&quot; option and pp is the process number in hexadecimal. Each bit
in this bitmap file corresponds to a cluster of sectors on the disk.
If the &quot;-p&quot; option appears on the command line, <command>dcheck</command> creates a
second bitmap file (<replaceable>pathlist</replaceable>/DCHECKpp1) that has a bit set for
each cluster <command>dcheck</command> finds as &quot;previously allocated&quot; or &quot;in file
structure but not in allocation map&quot; while building the allocation
map. <command>Dcheck</command> them makes another pass through the directory structure
to determine the pathlists for these questionable clusters. These
bitmap work files may be saved by specifying the &quot;-m&quot; option on the
command line.
</para>
</refsect1>
<refsect1><title>Restrictions</title>
<para>
For best results, <command>dcheck</command> should have exclusive access to the disk
being checked. Otherwise <command>dcheck</command> may be fooled if the disk allocation map
changes while it is building its bitmap file from the
changing file structure.  <command>Dcheck</command> cannot process disks with a directory
depth greater than 39 levels.
</para>
<para>
For more information see: <xref linkend="sec3.10"/>,
<xref linkend="sec3.5"/>,
<command>format</command>,
6.1 of NitrOS-9 Systems Programmer's Manual
</para>
</refsect1>
<refsect1><title>Examples</title>
<screen>
OS9: dcheck /d2   (workfile is on /D0)

Volume - 'My system disk' on device /d2
$009A bytes in allocation map
1 sector per cluster
$0004D0 total sectors on media
Sector $000002 is start of root directory FD
$0010 sectors used for id, allocation map and root directory
Building allocation map work file...
Checking allocation map file...


'My system disk' file structure is intact
1 directory
2 files

OS9: dcheck -mpw=/d2 /d0
Volume - 'System disk' on device /d0
$0046 bytes in allocation map
1 sector per cluster
$00022A total sectors on media
Sector $000002 is start of root directory FD
$0010 sectors used for id, allocation map and root directory
Building allocation map work file...
Cluster $00040 was previously allocated
*** Bad FD segment ($111111-$23A6F0) for file: /d0/test/junky.file
Checking allocation map file...
Cluster $000038 in file structure but not in allocation map
Cluster $00003B in file structure but not in allocation map
Cluster $0001B9 in allocation map but not in file structure
Cluster $0001BB in allocation map but not in file structure

Pathlists for questionable clusters:
Cluster $000038 in path: /d0/OS9boot
Cluster $00003B in path: /d0/OS9boot
Cluster $000040 in path: /d0/OS9boot
Cluster $000040 in path: /d0/test/double.file

1 previously allocated clusters found
2 clusters in file structure but not in allocation map
2 clusters in allocation map but not in file structure
1 bad file descriptor sector

'System disk' file structure is not intact
5 directories
25 files
</screen>
</refsect1>
</refentry>