Legacy Document

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

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:
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":

the format of the catalog key used in index and leaf nodes
the format of the leaf node data records

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:

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.

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: Value Meaning 1 Directory record 2 File record 3 Directory thread record 4 File 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: 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.
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.

	Value	Meaning
	1	Directory record
	2	File record
	3	Directory thread record
	4	File thread record

	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.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

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