Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Files /
Chapter 2 - File Manager / Data Organization on Volumes


Catalog Files

The File Manager uses a file called the catalog file to maintain information about the hierarchy of files and directories on a volume. A catalog file is organized as a B*-tree file and hence consists of a header node, index nodes, leaf nodes, and (if necessary) map nodes. The allocation block number of the first file extent of the catalog file (and hence of the file's header node) is stored in the MDB; when the volume is mounted, that information is copied into that volume's volume control block. From the header node, the File Manager can obtain the node number of the catalog file's root node; from the root node, the File Manager can find the entire catalog file.

Each node of the catalog file is assigned a unique catalog node ID (CNID). For directories, the CNID is the directory ID; for files, it's the file ID. For any given file or directory, the parent ID is the CNID of the parent directory. The first 16 CNIDs are reserved for use by Apple Computer, Inc., and include the following standard assignments:
CNIDAssignment
1Parent ID of the root directory
2Directory ID of the root directory
3File number of the extents file
4File number of the catalog file
5File number of the bad allocation block file

You need to know only two things about a catalog file in addition to the information given earlier in this chapter in "B*-Trees":

These formats are described in the following two sections.

Catalog File Keys

The key that the File Manager uses to navigate the catalog file is simple: for a given file or directory, the key consists principally of the name of that file or directory and its parent directory ID. With the exception of a volume reference number (which is not needed here), this mirrors the standard way to specify a file or directory with the high-level HFS routines. You can describe a catalog file key using a record of the CatKeyRec data type.

TYPE CatKeyRec    =              {catalog key record}
RECORD
   ckrKeyLen:     SignedByte;    {key length}
   ckrResrv1:     SignedByte;    {reserved}
   ckrParID:      LongInt;       {parent directory ID}
   ckrCName:      Str31;         {catalog node name}
END;
Field Description
ckrKeyLen
The length (in bytes) of the rest of the key. The value in this field does not include the byte occupied by the field itself. If this field contains 0, the key indicates a deleted record.
ckrResrv1
Reserved.
ckrParID
The catalog node ID of the parent directory.
ckrCName
The name of the file or directory whose catalog entry is to be found. This field is padded with null characters if necessary to have the next record data or pointer begin on a word boundary.
You should pay special attention to the fact that the catalog key differs slightly depending on whether it occurs in a record in an index node or a leaf node. If the key occurs in a pointer record (hence in an index node), the ckrCName field always occupies a full 32 bytes and the ckrKeyLen field always contains the value $25.

If, however, the catalog file key occurs in a data record (hence in a leaf node), then the ckrCName field varies in length; it occupies only the number of bytes required to hold the file or directory name, suitably padded so that the data following it begins on a word boundary. In that case, the ckrKeyLen field varies as well and may contain values from $7 to $25.

Catalog File Data Records

A catalog file leaf node can contain four different types of records:

Each record is defined by a variant of the CatDataType data type.

TYPE CatDataType  =  (cdrDirRec, cdrFilRec, cdrThdRec,
                      cdrFThdRec);
TYPE CatDataRec   =           {catalog data records}
RECORD
   cdrType:       SignedByte; {record type}
   cdrResrv2:     SignedByte; {reserved}
CASE CatDataType OF
cdrDirRec:                    {directory record}
  (dirFlags:      Integer;    {directory flags}
   dirVal:        Integer;    {directory valence}
   dirDirID:      LongInt;    {directory ID}
   dirCrDat:      LongInt;    {date and time of creation}
   dirMdDat:      LongInt;    {date and time of last modification}
   dirBkDat:      LongInt;    {date and time of last backup}
   dirUsrInfo:    DInfo;      {Finder information}
   dirFndrInfo:   DXInfo;     {additional Finder information}
   dirResrv:      ARRAY[1..4] OF LongInt);
                              {reserved}
cdrFilRec:                    {file record}
  (filFlags:      SignedByte; {file flags}
   filTyp:        SignedByte; {file type}
   filUsrWds:     FInfo;      {Finder information}
   filFlNum:      LongInt;    {file ID}
   filStBlk:      Integer;    {first alloc. blk. of data fork}
   filLgLen:      LongInt;    {logical EOF of data fork}
   filPyLen:      LongInt;    {physical EOF of data fork}
   filRStBlk:     Integer;    {first alloc. blk. of resource fork}
   filRLgLen:     LongInt;    {logical EOF of resource fork}
   filRPyLen:     LongInt;    {physical EOF of resource fork}
   filCrDat:      LongInt;    {date and time of creation}
   filMdDat:      LongInt;    {date and time of last modification}
   filBkDat:      LongInt;    {date and time of last backup}
   filFndrInfo:   FXInfo;     {additional Finder information}
   filClpSize:    Integer;    {file clump size}
   filExtRec:     ExtDataRec; {first data fork extent record}
   filRExtRec:    ExtDataRec; {first resource fork extent record}
   filResrv:      LongInt);   {reserved}
cdrThdRec:                    {directory thread record}
  (thdResrv:      ARRAY[1..2] OF LongInt;
                              {reserved}
   thdParID:      LongInt;    {parent ID for this directory}
   thdCName:      Str31);     {name of this directory}
cdrFThdRec:                   {file thread record}
  (fthdResrv:     ARRAY[1..2] OF LongInt;
                              {reserved}
   fthdParID:     LongInt;    {parent ID for this file}
   fthdCName:     Str31);     {name of this file}
END;
The first two fields of a catalog data record are common to all four variants. Each variant also includes its own unique fields.

Field descriptions common to all variants

cdrType
The type of catalog data record. This field can contain one of four values:
 ValueMeaning
 1Directory record
 2File record
 3Directory thread record
 4File thread record
cdrResrv2
Reserved.
Field descriptions for the cdrDirRec variant

dirFlags
Directory flags.
dirVal
The directory valence (the number of files in this directory).
dirDirID
The directory ID.
dirCrDat
The date and time this directory was created.
dirMdDat
The date and time this directory was last modified.
dirBkDat
The date and time this directory was last backed up.
dirUsrInfo
Information used by the Finder.
dirFndrInfo
Additional information used by the Finder.
dirResrv
Reserved.
Field descriptions for the cdrFilRec variant

filFlags
File flags. This is interpreted as a bitmap; currently the following bits are defined:
 BitMeaning
 0If set, file is locked and cannot be written to.
 1If set, a file thread record exists for this file.
 7If set, the file record is used.
filTyp
The file type. This field should always contain 0.
filUsrWds
The file's Finder information.
filFlNum
The file ID.
filStBlk
The first allocation block of the data fork.
filLgLen
The logical EOF of the data fork.
filPyLen
The physical EOF of the data fork.
filRStBlk
The first allocation block of the resource fork.
filRLgLen
The logical EOF of the resource fork.
filRPyLen
The physical EOF of the resource fork.
filCrDat
The date and time this file was created.
filMdDat
The date and time this file was last modified.
filBkDat
The date and time this file was last backed up.
filFndrInfo
Additional information used by the Finder.
filClpSize
The file clump size.
filExtRec
The first extent record of the file's data fork.
filRExtRec
The first extent record of the file's resource fork.
filResrv
Reserved.
Field descriptions for the cdrThdRec variant

thdResrv
Reserved.
thdParID
The directory ID of the parent of the associated directory.
thdCName
The name of this directory.
Field descriptions for the cdrFThdRec variant

fthdResrv
Reserved.
fthdParID
The directory ID of the parent of the associated file.
fthdCName
The name of this file.
As you can see, a file thread record is exactly the same as a directory thread record except that the associated object is a file, not a directory.


Previous Book Contents Book Index Next

© Apple Computer, Inc.
2 JUL 1996