APFS (Apple File System)

APFS is Apple’s current file system for macOS (since 10.13), iOS, iPadOS, watchOS and tvOS. It is a copy-on-write container design with space sharing, snapshots, clones and native encryption, and it is also used on Fusion Drives. Apple has published a reference but not every feature is documented.

Overview

An APFS container has a container superblock (NXSB) whose checkpoint area points to the container object map; each volume is a separate volume superblock (APSB) with its own object map, root tree and extent tree. Almost everything is a B-tree object with a Fletcher-64 checksum, identified by object ID and transaction ID. Features include snapshots, clones, space sharing, encryption and sparse files.

History

  • Announced at WWDC 2016.
  • Shipped on iOS 10.3 (2017) and macOS High Sierra (2017), where it replaced HFS+ on flash storage.

Structures

Offsets are in bytes from the start of the structure named in each heading. Field names are descriptive and are not an official specification. Fixed-width integers are shown as u/i (unsigned/signed) followed by bit width and byte order.

Key

OffsetSizeTypeFieldNotes
_toc + index * 8 + 22u16 LE/BELength
_toc + index * 42u16 LE/BEOffset
_toc + index * 82u16 LE/BEOffset

Parse

OffsetSizeTypeFieldNotes
0x184u32 LE/BEType
0x202u16 LE/BEFlags
0x222u16 LE/BELevel
0x244u32 LE/BECount
0x282u16 LE/BETable Offset
0x2A2u16 LE/BETable Length
info4u32 LE/BETree Flags
info + 84u32 LE/BETree Key Size
info + 124u32 LE/BETree Value Size

Value

OffsetSizeTypeFieldNotes
_toc + index * 4 + 22u16 LE/BEOffset
_toc + index * 8 + 42u16 LE/BEOffset
_toc + index * 8 + 62u16 LE/BELength

Lookup Uncached

OffsetSizeTypeFieldNotes
0x08u64 LE/BEKey Oid
0x88u64 LE/BEKey Xid

Lookup Uncached

OffsetSizeTypeFieldNotes
0x04u32 LE/BEFlags
0x44u32 LE/BE–
0x88u64 LE/BE–

Apfs Record

OffsetSizeTypeFieldNotes
0x08u64 LE/BEObject Id
0x08u64 LE/BERecord Type

Is Valid Superblock

OffsetSizeTypeFieldNotes
0x184u32 LE/BE–
0x204u32 LE/BE–

List Snapshots

OffsetSizeTypeFieldNotes
0x88u64 LE/BESuperblock Address
0x108u64 LE/BECreated
0x302u16 LE/BEName Length

Load

OffsetSizeTypeFieldNotes
0x108u64 LE/BEXid
NxBlockCount8u64 LE/BEBlock Count
NxBlockSize4u32 LE/BE–
NxFusionMtOid8u64 LE/BEFusion Middle Tree Address
NxFusionWbcBase8u64 LE/BEFusion Write Back Cache
NxFusionWbcBlocks8u64 LE/BEFusion Write Back Cache
NxIncompatFeatures8u64 LE/BEIncompatible Features
NxMaxFileSystems4u32 LE/BEAx Volumes
NxOmapOid8u64 LE/BEOmap
NxFsOid + i * 88u64 LE/BEOid

Open

OffsetSizeTypeFieldNotes
0x108u64 LE/BE–
NxXpDescBase8u64 LE/BEDescriptor Base
NxXpDescBlocks4u32 LE/BEDescriptor Blocks

Read Block Size

OffsetSizeTypeFieldNotes
0x204u32 LE/BE–
NxBlockSize4u32 LE/BEBlock Size

Read Object

OffsetSizeTypeFieldNotes
0x88u64 LE/BE–
0x184u32 LE/BEType

Parse

OffsetSizeTypeFieldNotes
0x108u64 LE/BEXid
0x204u32 LE/BE–
ApfsFextTreeOid8u64 LE/BEFext Tree Oid
ApfsFextTreeType4u32 LE/BEFext Tree Type
ApfsFsAllocCount8u64 LE/BEAllocated Blocks
ApfsFsFlags8u64 LE/BEFs Flags
ApfsFsIndex4u32 LE/BEIndex
ApfsIncompatFeatures8u64 LE/BEIncompatible Features
ApfsLastModTime8u64 LE/BELast Modified
ApfsNumDirectories8u64 LE/BEDirectory Count
ApfsNumFiles8u64 LE/BEFile Count
ApfsNumSnapshots8u64 LE/BESnapshot Count
ApfsNumSymlinks8u64 LE/BESymlink Count
ApfsOmapOid8u64 LE/BEOmap Oid
ApfsRole2u16 LE/BERole
ApfsRootTreeOid8u64 LE/BERoot Tree Oid
ApfsRootTreeType4u32 LE/BERoot Tree Type
ApfsSnapMetaTreeOid8u64 LE/BESnap Meta Tree Oid
ApfsSnapMetaTreeType4u32 LE/BESnap Meta Tree Type

Extents For

OffsetSizeTypeFieldNotes
0x08u64 LE/BE–
0x88u64 LE/BE–

Load Inode

OffsetSizeTypeFieldNotes
0x08u64 LE/BEParent Id
0x88u64 LE/BEPrivate Id
0x108u64 LE/BECreated
0x188u64 LE/BEOdified
0x208u64 LE/BEChanged
0x288u64 LE/BEAccessed
0x308u64 LE/BEInternal Flags
0x384u32 LE/BELinks Or Children
0x444u32 LE/BEBsd Flags
0x484u32 LE/BEOwner
0x4C4u32 LE/BEGroup
0x502u16 LE/BEOde

Parse Inode Fields

OffsetSizeTypeFieldNotes
0x02u16 LE/BECount
4 + i * 4 + 22u16 LE/BESize

Parse Inode Fields

OffsetSizeTypeFieldNotes
0x08u64 LE/BEData Size
0x88u64 LE/BEAllocated Size

Try Parse Directory Entry

OffsetSizeTypeFieldNotes
0x84u32 LE/BE–
0x82u16 LE/BE–

Try Parse Directory Entry

OffsetSizeTypeFieldNotes
0x08u64 LE/BEFile Id
0x88u64 LE/BEDate Added
0x102u16 LE/BEEntry Type

Try Parse Xattr

OffsetSizeTypeFieldNotes
0x08u64 LE/BEStream Id
0x88u64 LE/BEStream Size

Try Parse Xattr

OffsetSizeTypeFieldNotes
0x02u16 LE/BEFlags
0x22u16 LE/BEData Length

Probe

OffsetSizeTypeFieldNotes
0x184u32 LE/BEValid
NxBlockCount8u64 LE/BEBlock Count

Other fields read

Read inOffsetSizeTypeFieldNotes
Key Id0x08u64 LE/BEValue
Value0x08u64 LE/BE–
Apfs Object Map0x308u64 LE/BETree Addressom_tree_oid (physical)
Lookup Uncached0x08u64 LE/BE–
Open0x108u64 LE/BE–
Extents For0x88u64 LE/BE–
Try Parse Xattr0x82u16 LE/BEName Length
Probe0x204u32 LE/BE–
Verifyi4u32 LE–

Constants

Apfs Const

NameValueTypeNotes
NxMagic0x4253584Euint“NXSB”
ApfsMagic0x42535041uint“APSB”

obj_phys_t

NameValueTypeNotes
ObjHeaderSize32int
ObjTypeMask0x0000FFFFuint
ObjStorageTypeMask0xC0000000uint
ObjPhysical0x40000000uint
TypeNxSuperblock0x01uint
TypeBTree0x02uint
TypeBTreeNode0x03uint
TypeOmap0x0Buint
TypeFs0x0Duint

Container superblock (nx_superblock_t) offsets

NameValueTypeNotes
NxBlockSize36int
NxBlockCount40int
NxIncompatFeatures64int
NxUuid72int
NxXpDescBlocks104int
NxXpDescBase112int
NxOmapOid160int
NxMaxFileSystems180int
NxFsOid184int
NxMaxVolumes100int
NxIncompatFusion0x100ulong

Fusion fields of nx_superblock_t

NameValueTypeNotes
NxFusionUuid1280int
NxFusionMtOid1352int
NxFusionWbcBase1368int
NxFusionWbcBlocks1376int
FusionTier2ByteAddress0x4000000000000000ulong

fusion_mt_val_t flags

NameValueTypeNotes
FusionMtDirty0x1uint

btree_node_phys_t

NameValueTypeNotes
BTreeNodeDataOffset56int
BTreeInfoSize40int
BtnRoot0x1ushort
BtnLeaf0x2ushort
BtnFixedKvSize0x4ushort
BTreePhysical0x10uint
NoOffset0xFFFFushort

omap_val_t flags

NameValueTypeNotes
OmapValDeleted0x1uint
OmapValEncrypted0x4uint

File-system records (j_key_t)

NameValueTypeNotes
ObjIdMask0x0FFFFFFFFFFFFFFFulong
ObjTypeShift60int
JTypeSnapMetadata1int
JTypeInode3int
JTypeXattr4int
JTypeSiblingLink5int
JTypeFileExtent8int
JTypeDirRec9int
RootDirInode2ulong

j_inode_val_t

NameValueTypeNotes
InodeFixedSize92int
InoExtTypeName4byte
InoExtTypeDstream8byte
InoExtTypeSparseBytes13byte
ModeTypeMask0xF000ushort
ModeFifo0x1000ushort
ModeCharDevice0x2000ushort
ModeDirectory0x4000ushort
ModeBlockDevice0x6000ushort
ModeRegular0x8000ushort
ModeSymlink0xA000ushort
ModeSocket0xC000ushort
BsdImmutable0x2uint
BsdCompressed0x20uint
BsdHidden0x8000uint
InodeIsSparse0x200ulong

j_drec_val_t

NameValueTypeNotes
DrecTypeMask0xFint
DtDirectory4int
DrecHashedLengthMask0x3FFuint

j_xattr_val_t

NameValueTypeNotes
XattrDataStream0x1ushort
XattrDataEmbedded0x2ushort
XattrSymlink“com.apple.fs.symlink”string
XattrDecmpfs“com.apple.decmpfs”string
XattrResourceFork“com.apple.ResourceFork”string
ResourceForkStreamName“rsrc”string

j_file_extent_val_t

NameValueTypeNotes
FileExtentLengthMask0x00FFFFFFFFFFFFFFulong

apfs_superblock_t offsets

NameValueTypeNotes
ApfsFsIndex36int
ApfsIncompatFeatures56int
ApfsFsAllocCount88int
ApfsRootTreeType116int
ApfsSnapMetaTreeType124int
ApfsOmapOid128int
ApfsRootTreeOid136int
ApfsSnapMetaTreeOid152int
ApfsNumFiles184int
ApfsNumDirectories192int
ApfsNumSymlinks200int
ApfsNumSnapshots216int
ApfsVolUuid240int
ApfsLastModTime256int
ApfsFsFlags264int
ApfsFormattedBy272int
ApfsVolName704int
ApfsVolNameSize256int
ApfsRole964int
ApfsFextTreeOid1032int
ApfsFextTreeType1040int
FsUnencrypted0x1ulong
IncompatCaseInsensitive0x1ulong
IncompatNormalizationInsensitive0x8ulong
IncompatSealedVolume0x20ulong

Apfs Checksum

NameValueTypeNotes
Modulus0xFFFFFFFFulong

Implementation limits

ClassNameValueNotes
Apfs B TreeMaxDepth16
Apfs Object MapMaxDepth16
Apfs Object MapMaxCacheEntries65536
Apfs ContainerMaxCachedNodes8192
Apfs ContainerMaxDescriptorBlocks1 << 16
Apfs Fusion DeviceMaxChunk1024 * 1024
Apfs Fusion Middle TreeMaxRecords8_000_000
Apfs ConstMinBlockSize4096
Apfs ConstMaxBlockSize65536
Structures and constants were extracted from the implementation. Prose sections are a summary from public sources; verify details before relying on them.