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 unique identifier used by this file’s data stream
• 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

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 and encoded hash and name of the directory entry.

#define J_DREC_LEN_MASK 0x000003ff
#define J_DREC_HASH_MASK 0xfffff400
#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) of the UTF-8 encoded name in the 10 least significant bits and a hash of the name in the most significant bits.
• name: A null-terminated UTF-8 encoded name of the entry

The value for an 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 eight 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