Inode and Directory Records

Each APFS file system entry has both an inode and directory record. The inode record stores metadata such as the entry’s timestamps, ownership, type, and permissions (among others). Directory records store information about where the entry is stored within the file system’s hierarchy. A single inode may be referenced by more than one directory record, meaning the same file or folder may be present at multiple paths in the file system, as is the case with hard links.

Inode Records

The first record stored for each file system entry in a File System Tree should be an inode record. The key for an inode record only consists of the standard j_key_t structure with the “type” identified as APFS_TYPE_INODE.

// FS-Tree key for inode records
typedef struct j_inode_key {
    j_key_t hdr; // 0x00
} j_inode_key_t; // 0x08

• hdr: The record’s header

The value for an inode record is variable sized to account for any extended fields that may be stored after the record.

// Type Aliases
typedef uint16_t mode_t;
typedef uint32_t uid_t;
typedef uint32_t gid_t;
typedef uint32_t cp_key_class_t;

// FS-Tree value for inode records
typedef struct j_inode_val {
    uint64_t parent_id;                      // 0x00 
    uint64_t private_id;                     // 0x08
    uint64_t create_time;                    // 0x10
    uint64_t mod_time;                       // 0x18
    uint64_t change_time;                    // 0x20
    uint64_t access_time;                    // 0x28
    uint64_t internal_flags;                 // 0x30
    union {
        int32_t nchildren;                   // 0x38
        int32_t nlink;                       // 0x38
    };
    cp_key_class_t default_protection_class; // 0x3C
    uint32_t write_generation_counter;       // 0x40
    uint32_t bsd_flags;                      // 0x44
    uid_t owner;                             // 0x48
    gid_t group;                             // 0x4C
    mode_t mode;                             // 0x50
    uint16_t pad1;                           // 0x52
    uint64_t uncompressed_size;              // 0x54
    uint8_t xfields[];                       // 0x5C
} j_inode_val_t;

• parent_id: The identifier of the file system record for the parent directory
• private_id: The identifier used by this file’s data stream; for an inode with no data stream, it equals the inode’s own object identifier
• create_time: The time that this record was created
• mod_time: The time that this record was last modified
• change_time: The time that this record’s attributes were last modified
• access_time: The time that this record was last accessed
• internal_flags: The inode’s flags
• nchildren: The number of directory entries
• nlink: The number of hard links whose target is this inode
• default_protection_class: The default protection class for this inode
• write_generation_counter: A monotonically increasing counter that’s incremented each time this inode or its data is modified
• bsd_flags: The inode’s BSD flags
• owner: The user identifier of the inode’s owner
• group: The group identifier of the inode’s group
• mode: The file’s mode
• pad1: reserved
• uncompressed_size: The size of the file without compression
• xfields: The inode’s extended fields

Inode Flags

Three compound flag masks are also useful for understanding flag inheritance:

• INODE_INHERITED_INTERNAL_FLAGS (MAINTAIN_DIR_STATS | SNAPSHOT_COW_EXEMPTION | MAINTAIN_SPECULATIVE_TELEMETRY): Flags that new inodes inherit from their parent directory.
• INODE_CLONED_INTERNAL_FLAGS (HAS_RSRC_FORK | NO_RSRC_FORK | HAS_FINDER_INFO | SNAPSHOT_COW_EXEMPTION): Flags that propagate from a source inode to its clone.

Directory Records

Every folder in the file system will store a directory record for each of its children. A directory record’s key begins with the standard key header with the “type” encoded as APFS_TYPE_DIR_REC followed by an encoded hash and name of the directory entry.

#define J_DREC_LEN_MASK 0x000003ff
#define J_DREC_HASH_MASK 0xfffffc00
#define J_DREC_HASH_SHIFT 10

// A directory record key
typedef struct j_drec_hashed_key {
    j_key_t hdr;                // 0x00
    uint32_t name_len_and_hash; // 0x08
    uint8_t name[0];            // 0x0C
} j_drec_hashed_key_t;

• hdr: The record’s header
• name_len_and_hash: Encodes the length (in bytes, including the trailing null character) of the UTF-8 encoded name in the 10 least significant bits and a 22-bit hash of the name in the upper bits.
• name: A null-terminated UTF-8 encoded name of the entry

The value for a directory record is variable sized to account for any extended fields that may be stored after the record.

typedef struct j_drec_val {
    uint64_t file_id;    // 0x00
    uint64_t date_added; // 0x08
    uint16_t flags;      // 0x10
    uint8_t xfields[];   // 0x12
} j_drec_val_t;

• file_id: The identifier of the inode that this directory entry represents
• date_added: The time that this directory entry was added to the directory
• flags: The directory entry’s flags
• xfields: The directory entry’s extended fields

Directory Entry Flags

Directory Entry File Types

The four least significant bits of the directory record flags encode the type of the directory entry as defined below.

Extended Fields

Both inode and directory records contain an optional set of extended fields that are used to store additional information. To check if a directory entry or inode has extended fields, the structure size can be compared to the recorded size in the table of contents entry for the file-system record. If the recorded size is different from the structure’s size, then extended fields are present.

Both the j_drec_val_t and j_inode_val_t structures have a field called xfields that stores the extended field data. The xfields field consists of three parts: an xf_blob_t header that indicates the number of extended fields and their size, an array of x_field_t instances that provide the type and size of each extended field, and an array of the extended field data itself, which is aligned to eight-byte boundaries.

The xf_blob_t header is stored directly after the value structure.

// A collection of extended attributes.
typedef struct xf_blob {
    uint16_t xf_num_exts;  // 0x00
    uint16_t xf_used_data; // 0x02
    uint8_t xf_data[];     // 0x04
} xf_blob_t;

• xf_num_exts: The number of extended fields
• xf_used_data: The amount of space (in bytes) used to store the xfields
• xf_data: The extended fields

An x_field_t array is stored at the end of the xf_blob_t header. There is one entry for each extended field.

// An extended field's metadata.
typedef struct x_field {
    uint8_t x_type;  // 0x00
    uint8_t x_flags; // 0x01
    uint16_t x_size; // 0x02
} x_field_t;         // 0x04

• x_type: The extended field’s data type
• x_flags: The extended field’s flags
• x_size: The size, in bytes, of the data stored in the extended field

The data for the extended fields is stored after the x_field_t array. Importantly, this data is stored in the same order as the x_field_t array and is aligned on eight-byte boundaries. The padding bytes are not included in the x_size field. The type of this data depends on the type of the extended field.

Extended Field Types (Inode Records)

Extended Field Types (Directory Records)

Extended Field Flags

Directory Statistics

Directories with the INODE_MAINTAIN_DIR_STATS flag store a separate directory statistics record (type APFS_TYPE_DIR_STATS) in the File System Tree. This record provides aggregate information about the directory and all its descendants.

typedef struct j_dir_stats_key {
    j_key_t hdr; // 0x00
} j_dir_stats_key_t; // 0x08

• hdr: The record’s header. The object identifier is the directory’s inode number.

typedef struct j_dir_stats_val {
    uint64_t num_children; // 0x00
    uint64_t total_size;   // 0x08
    uint64_t chained_key;  // 0x10
    uint64_t gen_count;    // 0x18
} j_dir_stats_val_t;       // 0x20

• num_children: The total number of files and directories in this directory and its descendants (recursive count)
• total_size: The total size, in bytes, of all files in this directory and its descendants. A hard-linked file contributes to total_size for each directory it appears in.
• chained_key: The parent directory’s file-system object identifier. This forms a chain that allows propagating size changes up the directory hierarchy.
• gen_count: A monotonically increasing counter incremented each time this directory or its children are modified

The INODE_DIR_STATS_ORIGIN flag distinguishes directories that explicitly have stats enabled from those that inherited it. The chained_key field allows size and count updates to propagate up the directory tree when files are created, deleted, or resized.

Directory Record Hash Computation

The name_len_and_hash field in j_drec_hashed_key_t stores a precomputed hash used for efficient directory entry lookups. This hash is present on all volumes with APFS_INCOMPAT_CASE_INSENSITIVE or APFS_INCOMPAT_NORMALIZATION_INSENSITIVE set (which includes all default macOS and iOS volumes).

The hash is computed as follows:

1. Start with the filename as a null-terminated UTF-8 string.
2. Normalize the string using canonical decomposition (NFD). If the volume has APFS_INCOMPAT_NORMALIZATION_INSENSITIVE set, also apply Unicode case folding during normalization.
3. Represent the normalized filename as a sequence of UTF-32 code points (4 bytes each, little-endian). Do not include the null terminator.
4. Compute the CRC-32C hash of the UTF-32 data with an initial CRC value of 0xFFFFFFFF.
5. Complement the bits of the hash (XOR with 0xFFFFFFFF).
6. Keep only the low 22 bits.

This hash enables the B-Tree to quickly narrow down candidate entries without performing full Unicode normalization on every comparison. During lookups, the name_len_and_hash field is compared numerically first; only entries with matching hashes proceed to a full byte-by-byte name comparison.

On case-insensitive volumes, two filenames that differ only in case (e.g., README.md and readme.md) produce the same hash and are treated as the same entry. The case folding in step 2 ensures this.

Conclusion

Inode and directory records form the core of the APFS file system hierarchy. Together with extended fields and directory statistics, they provide efficient metadata access for both individual files and aggregate directory information.

Find an issue or technical inaccuracy in this post? Please file an issue so that it may be corrected.