sv nb en en en en en en en en en en en en en en en en fr en en en en en en en en en it en fr it de en en fr en en en ca zh sv lmo en en en en en zh zh ro en fi en fr uk id el en en ru en ca en en en en en en en en pt en en en en en en zh en en en en en en en en en en da en en en en en en en en en en en en en fr de en fr en de fr sv fr de en fr en en en en en en en fr ro en fr de de en en en en en es en en en en en en de hu en de en si si fr fr de en fr fr az en fr it ca fr fr en fr fr en nl fr en de fr en fr fr th da fr en fr fr da da fr ka fr fr en da de en fr de en fr de en hi de sv vi de ru pt fr en nl fr en en fr en en fr en ceb sv en uk en en en en en en en th gu fr en pt da en pt fr en oc fr en nb cs en fr cs en en hu en en fr en en bn en bn en en en en en de hu en de en si si fr fr de en fr fr en az tr en de en en en si en fr fr de en nl fr de en de de de en fr en de en pt en en en en en en en en fr en en fr fr de en fr fr de en en en bn he he he hbs_lat en en en ca en en en en en fr en en fr de de en de de de en fr en bn nl ca hbs_lat ca en en hbs_lat en en en es en en en en en en en en en en en nb en en en nb en en en nb en en en en en en en ca en ca en en ka en en nb en en en en en en en en en en en nb en en nb en en en en en es en en ca es en en en en en en en en it es en en es en en en en en es it es en es fr es en it es en da en hu es en es en sv en en en en nb en en en fr en en en en en da en en en en en en en fr de en fr sv de km en de it en ckb en sv en en en en en en en fr de en fr fr de en en sv de km en de it en fa en lmo en en en en nb en en en hbs_lat en en en en en en en en en en zh en en zh en en ro en en en en nb en en en ky en en en en en en en uk en en id en en en en en en en fr de en fr fr de en en en de en fr en de en en sv de en fr en de en de en en en en en en de fr de en en fr de en de fr de en en fr de en fr en el en en en en en en en nb en en en hbs_lat en en en en en en en ceb en en en en es en fr en en en en nb en en en hbs_lat en en en en en pt en en en en nb en en en zh en en en en en en en en en en en zh es en en en en en en en fr de en fr en en en en en en en fr de en fr de de en en en en en en en nb en en en en en en en en en en en en en en en en en fr de en fr fr ms en en fr de en nb fr de en de en si en fr fr es en en en en en en fr de en fr fr de en en fr de en nb de de fr en de de fr de de de en de fr de en en fr de en fr fr de en en de de en en en de en fr en de en fr en si en fr en si si fr en en en da en en en en mn es en en en en en en en en en en en en en en en en en en en en en en en
Aside from the superblock, Btrfs consists entirely of several trees. The trees use copy-on-write. Trees are stored in nodes, each of with belong to a level in the b-tree structure. Internal nodes contain references to other internal nodes on the next level, or to leaf nodes then the level reaches zero. Leaf nodes contain various types of data structures, depending on the tree.
Btrfs makes a distinction between logical and physical addresses. Logical addresses are used in the filesystem structures, while physical addresses are simply byte offsets on a disk. One logical address may correspond to physical addresses on any number of disks, depending on RAID settings. The chunk tree is used to convert from logical addresses to physical addresses; the dev tree can be used for the reverse.
For bootstrapping purposes, the superblock contains a subset of the chunk tree, specifically it contains "chunk items" for all system chunks. The superblock also contains a logical reference to root nodes in the root and chunk trees, which can then be used to locate all the other trees and data stored.
Note that the fields are unsigned, so object ID −1 will be treated as ffffffffffffffff and sorted to the end of the tree. Since Btrfs uses little‐endian, a simple byte‐by‐byte comparison of KEYs will not work.
Object ID. Each tree has its own set of Object IDs.
Offset. The meaning depends on the item type.
Number of seconds since 1970-01-01T00:00:00Z.
Number of nanoseconds since the beginning of the second.
The primary superblock is located at 0x1 0000 (6410 KiB). Mirror copies of the superblock are located at physical addresses 0x400 0000 (6410 MiB) and 0x40 0000 0000 (25610 GiB), if these locations are valid. Superblock copies are updated simultaneously. During mount btrfs' kernel module reads only the first super block (at 64k), if an error is detected mounting fails.
Note that btrfs only recognizes disks with a valid 0x1 0000 superblock; otherwise, there would be confusion with other filesystems.
Checksum of everything past this field (from 20 to 1000)
physical address of this block (different for mirrors)
logical address of the root tree root
logical address of the chunk tree root
compat_ro_flags - only implementations that support the flags can write to the filesystem
incompat_flags - only implementations that support the flags can use the filesystem
csum_type - Btrfs currently uses the CRC32c little-endian hash function with seed -1.
DEV_ITEM data for this device
sys_chunk_array:(n bytes valid) Contains (KEY, CHUNK_ITEM) pairs for all SYSTEM chunks. This is needed to bootstrap the mapping from logical addresses to physical.
This is the data stored at the start of every node. The data following it depends on whether it is an internal or leaf node, both of which are described below.
Checksum of everything after this field (from 20 to the end of the node)
Logical address of this node
Backref. Rev.: always 1 (MIXED) for new filesystems; 0 (OLD) indicates an old filesystem.
The ID of the tree that contains this node
Level (0 for leaf nodes)
In internal nodes, the node header is followed by a number of key pointers.
In leaf nodes, the node header is followed by a number of items. The items' data is stored at the end of the node, and the contents of the item data depends on the item type stored in the key.
data offset relative to end of header (65)
The root tree holds ROOT_ITEMs, ROOT_REFs, and ROOT_BACKREFs for every tree other than itself. It is used to find the other trees and to determine the subvolume structure. It also holds the items for the root tree directory. The logical address of the root tree is stored in the superblock.
There are several well-known objectids that refer to internal trees.
All root objectids between BTRFS_FIRST_FREE_OBJECTID = 256ULL and BTRFS_LAST_FREE_OBJECTID = -256ULL refer to file trees.
Otherwise, the objectid should be considered reserved for internal use.
The object id that refers to the ROOT_TREE itself.
The objectid that refers to the EXTENT_TREE.
The objectid that refers to the root of the CHUNK_TREE
The objectid that refers to the root of the DEV_TREE.
The objectid that refers to the global FS_TREE root.
The objectid that refers to the CSUM_TREE.
The objectid that refers to the QUOTA_TREE.
The objectid that refers to the UUID_TREE.
The objectid that refers to the FREE_SPACE_TREE.
The objectid that refers to the TREE_LOG tree.
The objectid that refers to the TREE_RELOC tree.
The objectid that refers to the DATA_RELOC tree.
The following are well-known objectids within the ROOT_TREE that do not refer to other trees.
The objectid that refers to the directory within the root tree. If it exists, it will have the usual items used to implement a directory associated with it.
There will only be a single entry called default that points to a key to be used as the root directory on the file system instead of the FS_TREE.
The objectid used for orphan root tracking.
Developer note: If implementing a feature that requires a new objectid in the reserved range, you must reserve the objectid via the mailing list before posting your code for general use. This is a disk format change.
Removing a root is a multi-step process that may involve many transactions. References to every extent used by the tree must be decremented and, if they hit zero, the extents must be released. It is possible that the system crashes, loses power, or otherwise encounters an error during root removal. Without additional information, the file system could ultimately contain partially removed roots, which would make it inconsistent. When a root is removed, it performs several small operations in a single transaction in preparation for removal. This process should be familiar to those with an understanding of how orphans work when an inode is unlinked on any UNIX-style file system.
Unlink the root from the directory that contains it.
Initialize the drop_progress and drop_level fields and set the refs field to 0 in the ROOT_ITEM.
If an orphan key for this root has not already been inserted into the tree, insert one.
Remove the UUID entries for this root and any associated received root from the UUID_TREE.
Ultimately, the cleaner thread handles the reference count adjustments and, once that is complete, the root has been successfully removed and it removes the orphan key for that root. As the cleaner progresses, the drop_progress and drop_level fields are updated to reflect the most recently processed item.
This process may be interrupted at any time and it must be recoverable. The orphan key is how btrfs avoids inconsistencies when that occurs. The orphan key is located in the ROOT_TREE and is of the following form.
objectid of the root to be removed
There is no item body associated with this key. All required information is contained within the key itself and the ROOT_ITEM associated with the objectid contained in offset
When the file system is mounted again after failure, the ROOT_TREE is searched for all orphan keys and the process is resumed for each one using the drop_progress and drop_level fields in the ROOT_ITEM.
Pointed to by ROOT
The chunk tree holds all DEV_ITEMs and CHUNK_ITEMs, making it possible to determine the device(s) and physical address(es) corresponding to a given logical address. It is therefore crucial for access to the contents of the filesystem.
The chunk tree resides entirely in SYSTEM block groups, and will therefore be accessible from the CHUNK_ITEM array in the Superblock. It also has an entry in the ROOT tree.
This objectid indicates the first available objectid in this CHUNK_TREE. In practice, it is the only objectid used in the tree. The offset field of the key is the only component used to distinguish separate CHUNK_ITEM items.
The dev tree holds all DEV_EXTENTs, making it possible to determine the logical address corresponding to a given physical address. This is necessary when shrinking or removing devices. The dev tree has an entry in the root tree.
Holds INODE_ITEMs, INODE_REFs, DIR_ITEMs, DIR_INDEXen, XATTR_ITEMs, EXTENT_DATAs for a filesystem
Pointed to by ROOT
The root tree directory is stored in the root tree. It has an INODE_ITEM and a DIR_ITEM with name "default" pointing to the FS tree. There is also a corresponding INODE_REF, but no DIR_INDEX. The objectid of the root tree directory is stored in the superblock, but is currently always 6.
The checksum tree contains all the EXTENT_CSUMs. It has an entry in the root tree.
Just a copy of another tree
Holds 100 INODE_ITEM 0
Holds 100 INODE_REF 100 0:'..'
Pointed to by ROOT
INODE_ITEM items are located primarily in file trees but are also found in the ROOT_TREE to implement the free space cache (v1).
objectid (Used as inode number)
Contains the stat information for an inode; see stat(2).
INODE_ITEM items contain a single btrfs_inode_item structure.
From an inode to a name in a directory.
index in the directory
name in the directory
This structure can be repeated...?
(inode_id, hash of name [using directory object ID as seed]) TODO
From an inode to a name in a directory. Used if the regarding INODE_REF array ran out of space. This item requires the EXTENDED_IREF feature.
index in the directory
name in the directory
This structure can be repeated...?
XATTR_ITEM items are only located in file trees.
objectid of owning inode
XATTR_ITEM items contain extended attributes. Each name is hashed using the name hash and that value is used in the key for locating the entry quickly. Each XATTR_ITEM item contains one or more extended attributes with names represented by the same hash. All extended attributes that share the same name hash must fit in a single leaf.
XATTR_ITEM items consist of a series of one or more extended attribute entries with names that share a hash value. Each entry consists of a btrfs_dir_item structure immediately followed by the name and the attribute data. The length of each name is contained in btrfs_dir_item.name_len. The data payload begins immediately after the name. The data payload length is contained in btrfs_dir_item.data_len. btrfs_dir_item.data_len.location is unused and must be zeroed. btrfs_dir_item.type contains a shorthand value referring to the type of item to which an entry refers it must always be be BTRFS_FT_XATTR when used to describe an extended attribute.
When there is more than one entry for a single hash value, the offset of each entry must be calculating using the lengths of the preceding entries including names and data.
For more details, please see: struct btrfs_dir_item and DIR_ITEM.
(-5, objid of orphan inode) TODO
(directory_id, first offset) TODO
The log is considered authoritative for ([first offset, end offset)] 0 8 UINT end offset
(directory_id, first offset) TODO
DIR_ITEM items are only located in file trees.
objectid of owning inode
DIR_ITEM items contain directory entries. Each name is hashed using the name hash and that value is used in the key for locating the entry quickly. Each DIR_ITEM item contains one or more directory entries with names represented by the same hash. All directory entries that share the same name hash must fit in a single leaf.
DIR_ITEM items consist of a series of one or more directory entries with names that share a hash value. Each entry consists of a btrfs_dir_item structure immediately followed by the name. The length of each name is contained in btrfs_dir_item.name_len. The location of the item to which this entry refers is contained in btrfs_dir_item.location and must refer to a valid item in the same file tree. btrfs_dir_item.type contains a shorthand value referring to the type of item to which an entry refers. It will never be BTRFS_FT_XATTR when used in a standard directory. btrfs_dir_item.data_len is unused and must be 0
When there is more than one entry for a single hash value, the offset of each entry must be calculating using the lengths of the preceding entries including names.
For more details, please see: struct btrfs_dir_item.
(parent objectid, 60, index in parent)
Allows looking up an item in a directory by index. Indices start at 2 (because of "." and ".."); removed files can cause "holes" in the index space. DIR_INDEXen have the same contents as DIR_ITEMs, but may contain only one entry.
(inode id, 6c, offset in file) TODO
The contents of a file.
(n) size of decoded extent
compression (0=none, 1=zlib, 2=LZO)
type (0=inline, 1=regular, 2=prealloc)
If the extent is inline, the remaining item bytes are the data bytes (n bytes in case no compression/encryption/other encoding is used).
Otherwise, the structure continues:
(ea) logical address of extent. If this is zero, the extent is sparse and consists of all zeroes.
(es) size of extent
(o) offset within the extent
(s) logical number of bytes in file
ea and es must exactly match an EXTENT_ITEM. If the es bytes of data at logical address ea are decoded, n bytes will result. The file's data contains the s bytes at offset o within the decoded bytes. In the simplest, uncompressed case, o=0 and n=es=s, so the file's data simply contains the n bytes at logical address ea.
(-a, logical address?) TODO
Contains one or more checksums of the type in the superblock for adjacent blocks starting at logical address (blocksize).
ROOT_ITEM items are only located in the ROOT_TREE.
objectid of root (TODO: document reserved objectids)
0 for normal subvolume.
Otherwise, transid of the transaction that created the snapshot.
A fundamental component of btrfs is the btree. ROOT_ITEM items define the location and parameters of the root of a btree.
ROOT_ITEM items contain a single btrfs_root_item structure.
(subtree id, 90, tree id) TODO
Same content as ROOT_REF.
ROOT_REF items are only located in the ROOT_TREE.
(tree id, subtree id) TODO
0 8 UINT ID of directory in [tree id] that contains the subtree 8 8 UINT Sequence (index in tree) (even, starting at 2?) 10 2 UINT (n) 12 n ASCII name
EXTENT_ITEM items are only located in the EXTENT_TREE.
byte offset for start of extent
size of extent, in bytes
EXTENT_ITEM items describe the space allocated for metadata tree nodes and leafs as well as data extents. The space is allocated from block groups that define the appropriate regions. In addition to functioning as basic allocation records, EXTENT_ITEM items also contain back references that can be used to repair the file system or resolve extent ownership back to a set of one or more file trees. Although EXTENT_ITEM items can be used to describe both DATA and TREE_BLOCK extents, newer file systems with the skinny metadata feature enabled at mkfs time use METADATA_ITEM items to represent metadata instead.
EXTENT_ITEM items begin with the btrfs_extent_item structure and are followed by records that are defined by the flags field in that structure.
METADATA_ITEM items are only located in the EXTENT_TREE.
byte offset for start of extent
level of block in the metadata tree that contains it
METADATA_ITEM items describe the space allocated for metadata tree nodes and leafs. The space is allocated from block groups that define metadata regions. In addition to functioning as basic allocation records, METADATA_ITEM items also contain back references that can be used to repair the file system or resolve extent ownership back to a set of one or more file trees.
METADATA_ITEM items begin with the btrfs_extent_item structure and are followed by records that are defined by the flags field in that structure.
(logical address, b0, root object id) TODO
0 8 UINT offset (the object ID of the tree)
(logical address, b2, hash of first three fields) TODO
0 8 UINT root objectid (id of tree contained in) 8 8 UINT object id (owner) 10 8 UINT offset (in the file data) 18 4 UINT count (always 1?)
(logical address, b6, parent) TODO
(logical address, b8, parent) TODO
BLOCK_GROUP_ITEM items are only found in the EXTENT_TREE.
Starting offset in the space defined by the EXTENT_TREE.
Size of the block group, in bytes
While the EXTENT_TREE defines the address space used for extent allocations for the entire file system, block groups allocate and define the parameters within that space. Every EXTENT_ITEM or METADATA_ITEM that describes an extent in use by the file system is apportioned from allocated block groups. Each block group can represent space used for SYSTEM objects (e.g. the CHUNK_TREE and primary super block), METADATA trees and items, or DATA extents. It is possible to combine METADATA and DATA allocations within a single block group, though it is not recommended. This mixed allocation policy is typically only seen on file systems smaller than approximately 10 GiB in size.
BTRFS_BLOCK_GROUP items contain a single struct btrfs_block_group_item.
(device id, cc, physical address) TODO
Maps from physical address to logical.
chunk tree (always 3)
chunk oid (always 256?)
(1, device id) TODO
Contains information about one device.
number of bytes used
minimal I/O size (sector size)
(100, logical address) TODO
Maps logical address to physical. 0 8 UINT size of chunk (bytes) 8 8 OBJID root referencing this chunk (2) 10 8 UINT stripe length 18 8 UINT type (same as flags for block group?) 20 4 UINT optimal io alignment 24 4 UINT optimal io width 28 4 UINT minimal io size (sector size) 2c 2 UINT number of stripes 2e 2 UINT sub stripes 30 Stripes follow (for each number of stripes): 0 8 OBJID device id 8 8 UINT offset 10 10 UUID device UUID 20