Important: The information in this document is obsolete and should not be used for new development.
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:
CNID Assignment 1 Parent ID of the root directory 2 Directory ID of the root directory 3 File number of the extents file 4 File number of the catalog file 5 File 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.
- the format of the catalog key used in index and leaf nodes
- the format of the leaf node data records
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 theCatKeyRec
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;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
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.
ckrCName
field always occupies a full 32 bytes and theckrKeyLen
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, theckrKeyLen
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
- Directory records. A directory record contains information about a single directory.
- File records. A file record contains information about a single file.
- Directory thread records. A directory thread record provides a link between a directory and its parent directory. It allows the File Manager to find the name and directory ID of the parent of a given directory.
- File thread records. A file thread record provides a link between a file and its parent directory. It allows the File Manager to find the name and directory ID of the parent of a given file.
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
Field descriptions for the
cdrType
- The type of catalog data record. This field can contain one of four values:
Value Meaning 1 Directory record 2 File record 3 Directory thread record 4 File thread record cdrResrv2
- Reserved.
cdrDirRec
variant
Field descriptions for the
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.
cdrFilRec
variant
Field descriptions for the
filFlags
- File flags. This is interpreted as a bitmap; currently the following bits are defined:
Bit Meaning 0 If set, file is locked and cannot be written to. 1 If set, a file thread record exists for this file. 7 If 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.
cdrThdRec
variant
Field descriptions for the
thdResrv
- Reserved.
thdParID
- The directory ID of the parent of the associated directory.
thdCName
- The name of this directory.
cdrFThdRec
variant
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.
fthdResrv
- Reserved.
fthdParID
- The directory ID of the parent of the associated file.
fthdCName
- The name of this file.