Data Structures
OBSOLETE CONTENT
This wiki has been archived and the content is no longer updated.
This page lists the main on-disk data structures, and how they link with each other (and via which trees). It doesn't document every single field of every structure. Instead, it concentrates on the cross-links between items in the on-disk data structures.
See also: Btree Items, On-disk_Format
Structure references
btrfs_block_group_item
This structure defines the location, properties, and usage of a block group. It is associated with the BLOCK_GROUP_ITEM
. This structure is never used outside of this item.
struct btrfs_block_group_item (24 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
used
|
The space used in this block group. |
8
|
__le64
|
chunk_objectid
|
The objectid of the chunk backing this block group. |
16
|
__le64
|
flags
|
See below. |
Flags
Allocation Type
- The type of storage this block group offers.
SYSTEM
chunks cannot be mixed, butDATA
andMETADATA
chunks can be mixed.
BTRFS_BLOCK_GROUP_DATA [0x1]
BTRFS_BLOCK_GROUP_SYSTEM [0x2]
BTRFS_BLOCK_GROUP_METADATA [0x4]
Replication Policy
- The allocation policy this block group implements. Only one of the following flags may be set in any single block group. It is not possible to combine policies to create nested RAID levels beyond the RAID-10 support offered below. If no flags are specified, the block group is not replicated beyond a single, unstriped copy.
BTRFS_BLOCK_GROUP_RAID0 [0x8]
- Striping (RAID-0)
BTRFS_BLOCK_GROUP_RAID1 [0x10]
- Mirror on a separate device (RAID-1)
BTRFS_BLOCK_GROUP_DUP [0x20]
- Mirror on a single device
BTRFS_BLOCK_GROUP_RAID10 [0x40]
- Striping and mirroring (RAID-10)
BTRFS_BLOCK_GROUP_RAID5 [0x80]
- Parity striping with single-disk fault tolerance (RAID-5)
BTRFS_BLOCK_GROUP_RAID6 [0x100]
- Parity striping with double-disk fault tolerance (RAID-6)
BTRFS_BLOCK_GROUP_RAID1C3 [0x200]
- Mirrored with copies on 3 different devices
BTRFS_BLOCK_GROUP_RAID1C4 [0x400]
- Mirrored with copies on 4 different devices
btrfs_chunk
This structure contains the mapping from a virtualized usable byte range within the backing storage to a set of one or more stripes on individual backing devices. In addition to the mapping, hints on optimal I/O parameters for this chunk. It is associated with CHUNK_ITEM
items.
Although the structure definition only contains one stripe
member, CHUNK_ITEM
items contain as many struct btrfs_stripe
structures as specified in the num_stripes
and sub_stripes
fields.
struct btrfs_chunk (80 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
length
|
Size of this chunk, in bytes. |
8
|
__le64
|
owner
|
Objectid of the root referencing this chunk; Always EXTENT_ROOT .
|
16
|
__le64
|
stripe_len
|
Replication stripe length. |
24
|
__le64
|
type
|
Uses the same flags as btrfs_block_group_item. |
32
|
__le32
|
io_align
|
Optimal I/O alignment for this chunk. |
36
|
__le32
|
io_width
|
Optimal I/O width for this chunk. |
40
|
__le32
|
sector_size
|
Minimal I/O size for this chunk. |
44
|
__le16
|
num_stripes
|
Number of replication stripes. |
46
|
__le16
|
sub_stripes
|
Number of replication sub-stripes (used only for RAID-10). |
48
|
struct btrfs_stripe
|
stripe
|
The first of one or more stripes that map to device extents. |
btrfs_csum_item
No external references
- csum
- Start of a variable-length sequence of [currently 4-byte] checksums, one for each 4k of data, starting at the offset field of the key.
btrfs_dev_extent
This structure is used to map physical extents on an individual backing device to a chunk. This extent may be the only one for a particular chunk or one of several. It is associated with the DEV_ITEM
item. This structure is never used outside of this item.
struct btrfs_dev_extent (48 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
chunk_tree
|
Objectid of the CHUNK_TREE that owns this extent.
Always |
8
|
__le64
|
chunk_objectid
|
Objectid of the CHUNK_ITEM that references this extent.In practice, it will always be |
16
|
__le64
|
chunk_offset
|
Offset of the CHUNK_ITEM that references this extent.
|
24
|
__le64
|
length
|
Length of this extent, in bytes. |
32
|
__u8[16]
|
chunk_tree_uuid
|
UUID of the CHUNK_TREE that owns this extent.
|
It is unclear whether the chunk_tree
and chunk_tree_uuid
fields are a remnant of an early design or included for potential future expansion.
btrfs_dev_item
Represents a complete block device.
- devid
- Matches the devid in the filesystem's list of struct btrfs_devices.
struct btrfs_dev_item (98 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
devid
|
the internal btrfs device id |
8
|
__le64
|
total_bytes
|
size of the device |
16
|
__le64
|
bytes_used
|
bytes used |
24
|
__le32
|
io_align
|
optimal io alignment for this device |
28
|
__le32
|
io_width
|
optimal io width for this device |
32
|
__le32
|
sector_size
|
minimal io size for this device |
36
|
__le64
|
type
|
type and info about this device |
44
|
__le64
|
generation
|
expected generation for this device |
52
|
__le64
|
start_offset
|
starting byte of this partition on the device,
to allow for stripe alignment in the future |
60
|
__le32
|
dev_group
|
grouping information for allocation decisions |
64
|
__u8
|
seek_speed
|
seek speed 0-100 where 100 is fastest |
65
|
__u8
|
bandwidth
|
bandwidth 0-100 where 100 is fastest |
66
|
__u8[16]
|
uuid
|
btrfs generated uuid for this device |
82
|
__u8[16]
|
fsid
|
uuid of FS who owns this device |
btrfs_dev_stats_item
This device item holds various statistics about a device. This item type is contained only in the DEV_TREE
struct btrfs_dev_stats_item (40 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
_le64
|
values[6]
|
Array of stats values. See below |
Stat items
The codes below signify a direct disk I/O failures:
-
BTRFS_DEV_STAT_WRITE_ERRS 0x1
- Number of times we got EIO or EREMOTEIO from lower layers while performing writes
-
BTRFS_DEV_STAT_READ_ERRS 0x2
- Number of times we got EIO or EREMOTEIO from lower layers while performing reads
-
BTRFS_DEV_STAT_FLUSH_ERRS 0x3
- Number of times we got EIO or EREMOTEIO from lower layers while performing data flushes
The codes below indicate an indirect I/O failure:
-
BTRFS_DEV_STAT_CORRUPTION_ERRS 0x4
- checksum error, bytenr error or contents is illegal: this is an indication that the block was damaged during read or write, or written to wrong location or read from wrong location
-
BTRFS_DEV_STAT_GENERATION_ERRS 0x5
- an indication that blocks have not been written
btrfs_dev_replace_item
This item holds necessary information to resume a device replace operation following a crash/suspend. It is contained in DEV_TREE
struct btrfs_dev_replace_item (72 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
src_devid
|
Device id of the source device |
8
|
__le64
|
cursor_left
|
|
16
|
__le64
|
cursor_right
|
|
24
|
__le64
|
cont_reading_from_srcdev_mode
|
|
32
|
__le64
|
replace_state
|
State of replace operation. Can be one of: BTRFS_IOCTL_DEV_REPLACE_STATE_STARTED, BTRFS_IOCTL_DEV_REPLACE_STATE_STARTED,
|
40
|
__le64
|
time_started
|
|
48
|
__le64
|
time_stopped
|
|
56
|
__le64
|
num_write_errors
|
expected generation for this device |
64
|
__le64
|
num_uncorrectable_read_errors
|
btrfs_balance_item
TODO
btrfs_dir_item
This structure represents the header for a directory entry item used for both standard user-visible directories and internal directories used to manage named extended attributes. It is associated with the DIR_ITEM
and XATTR_ITEM
items. This structure is not used outside of these items.
It is immediately followed by the name. If it represents an extended attribute, the attribute data immediately follows the name.
struct btrfs_dir_item (30 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
struct btrfs_disk_key
|
location
|
Key for the INODE_ITEM or ROOT_ITEM associated with this entry. Unused and zeroed out when the entry describes an extended attribute. |
17
|
__le64
|
transid
|
transid of the transaction that created this entry.
|
25
|
__le16
|
data_len
|
Length of the extended attribute associated with this entry.
|
27
|
__le16
|
name_len
|
Length of directory entry name. |
29
|
__u8
|
type
|
See below. |
Types
These directory entry types use the same values as the d_type
field in struct dirent
documented in the readdir(3)
manual page.
-
BTRFS_FT_UNKNOWN = 0
- The target object's type is unknown. Indicates corruption if used.
BTRFS_FT_REG_FILE = 1
- The target object is an
INODE_ITEM
representing a regular file.
BTRFS_FT_DIR = 2
- The target object is an
INODE_ITEM
representing a directory or aROOT_ITEM
that will be presented as a directory.
BTRFS_FT_CHRDEV = 3
- The target object is an
INODE_ITEM
representing a character device node.
BTRFS_FT_BLKDEV = 4
- The target object is an
INODE_ITEM
representing a block device node.
BTRFS_FT_FIFO = 5
- The target object is an
INODE_ITEM
representing a FIFO device node.
BTRFS_FT_SOCK = 6
- The target object is an
INODE_ITEM
representing a socket device node.
BTRFS_FT_SYMLINK = 7
- The target object is an
INODE_ITEM
representing a symbolic link.
This value is used on-disk and internally but is not user-visible.
BTRFS_FT_XATTR = 8
- The entry is an
XATTR_ITEM
.
btrfs_dir_log_item
TODO
struct btrfs_dir_log_item (8 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
end
|
btrfs_extent_data_ref
This structure contains an indirect back reference for a file data extent.
Follows a btrfs_extent_inline_ref
of type BTRFS_EXTENT_DATA_REF_KEY
within an EXTENT_ITEM
item. It is never used separately outside of the item body. Note that this structure is located at the same offset as the offset
member of the btrfs_extent_inline_ref
that it follows.
struct btrfs_extent_data_ref (28 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
root
|
The objectid for the file tree that references this extent. |
8
|
__le64
|
objectid
|
The objectid of the inode that contains the EXTENT_DATA item that references this extent. |
16
|
__le64
|
offset
|
The offset within the file that corresponds to this extent. |
24
|
__le32
|
count
|
The number of references held. |
TODO: Document how count can be > 1 for a single [root, objectid, EXTENT_DATA, offset] item.
btrfs_extent_inline_ref
This structure functions as the header for several types of inline extent back references that are contained in EXTENT_ITEM or METADATA_ITEM items. This structure is never used separately outside of these items.
struct btrfs_extent_inline_ref (9 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
u8
|
type
|
One of 4 key types, listed below. |
1
|
__le64
|
offset
|
Contents depend on type of reference. |
Types
-
BTRFS_TREE_BLOCK_REF_KEY [176]
- The back reference is indirect for a tree block.
offset
contains theobjectid
of the tree root that allocated the block.
BTRFS_SHARED_BLOCK_REF_KEY [182]
- The back reference is shared for a tree block.
offset
contains the byte offset of the node at the next higher level in the tree where this block is located.
BTRFS_EXTENT_DATA_REF_KEY [178]
- The back reference is indirect for a data extent.
offset
is unused and abtrfs_extent_data_ref
structure is located immediately after thetype
field.
BTRFS_SHARED_DATA_REF_KEY [184]
- The back reference is shared for a data extent.
offset
contains the byte offset of the metadata block that contains the EXTENT_DATA item that describes this extent. Immediately following is abtrfs_shared_data_ref
structure containing the reference count.
btrfs_extent_item
This structure functions as the header for extent record items. It is associated with the EXTENT_ITEM
and METADATA_ITEM
types.
One extent record item exists for each extent allocated on a btrfs file system. Each item tracks the number of explicit references to the extent (TODO: document implied references), records whether the extent contains file data or tree metadata and, if the latter, if the item contains a full back reference. It is followed by back reference records for each explicit reference held.
If the item type containing this item is EXTENT_ITEM
and the BTRFS_EXTENT_FLAG_TREE_BLOCK
flag is set, this item will be followed immediately by a btrfs_tree_block_info
. Extent records follow this, as below.
For all item types, a series of variable-length extent records will fill the rest of the item. Each of these records will begin with a btrfs_extent_inline_ref
, with the contents of each record determined by the header's type
field.
struct btrfs_extent_item (24 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
refs
|
The number of explicit references to this extent |
8
|
__le64
|
generation
|
transid of transaction that allocated this extent
|
16
|
__le64
|
flags
|
see below |
Flags
BTRFS_EXTENT_FLAG_DATA [0x1]
- Flag to indicate that the following record refers to a data extent
BTRFS_EXTENT_FLAG_TREE_BLOCK [0x2]
- Flag to indicate that the following record refers to a metadata tree block
BTRFS_BLOCK_FLAG_FULL_BACKREF [0x80]
- Tree block back reference contains a full back reference.
btrfs_extent_ref_v0
btrfs_file_extent_item
Represents a chunk of data on disk belonging to a file. In the fs-trees, the corresponding key is (<inum> EXTENT_DATA <logical offset>). The <logical offset> is in (uncompressed) bytes within the file belonging to inode <inum>.
struct btrfs_file_extent_item (53 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
generation
|
transaction id that created this extent |
8
|
__le64
|
ram_bytes
|
Upper limit on the size of the extent in ram |
16
|
__u8
|
compression
|
Compression type. Can be one of: BTRFS_COMPRESS_NONE (0), BTRFS_COMPRESS_ZLIB (1) and BTRFS_COMPRESS_LZO (2) |
17
|
__u8
|
encryption
|
encryption type, currently always set to 0 |
18
|
__le16
|
other_encoding
|
Currently unused, allows for future expansion. |
20
|
__u8
|
type
|
Type of extent. Can be BTRFS_FILE_EXTENT_INLINE (0), BTRFS_FILE_EXTENT_REG (1) or BTRFS_FILE_EXTENT_PREALLOC (2). For inline extents the file contents immediately follow the type byte. The length of the inline data block equals ram_bytes, alternatively it can be read from the inode or computed as the size stored in the corresponding btrfs_item-structure less the (partial) size of the btrfs_file_extent_item-structure. |
The following fields apply to BTRFS_FILE_EXTENT_REG/BTRFS_FILE_EXTENT_PREALLOC extents only | |||
21
|
__le64
|
disk_bytenr
|
Logical address for the start of the extent data. Note: This is the key.objectid for the corresponding EXTENT_ITEM. |
29
|
__le64
|
disk_num_bytes
|
Number of on-disk bytes of the extent (compressed). Note: This is the key.offset for the corresponding EXTENT_ITEM. |
37
|
__le64
|
offset
|
Offset into the extent item. Number of bytes to skip at the beginning (uncompressed). |
45
|
__le64
|
num_bytes
|
Number of valid bytes within the file extent item (uncompressed). This always reflects the size uncompressed and without encoding. |
btrfs_file_extent_item_v0
TODO
btrfs_free_space_entry
TODO
btrfs_free_space_header
TODO
btrfs_free_space_info
This struct is only used with space_cache v2. Every block group is represented in the free space tree by a free space info item, which stores some accounting information.
It is keyed on (block_group_start, FREE_SPACE_INFO, block_group_length).
struct btrfs_inode_ref (8 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le32
|
extent_count
|
Number of extents that are tracking the free space for this block group |
4
|
__le32
|
flags
|
Flags associated with this free_space_info (current it can be 0 or BTRFS_FREE_SPACE_BITMAP_KEY) |
btrfs_inode_ref
Indexed by (inode_number, BTRFS_INODE_REF_ITEM, parent_inode). Allows you to find the btrfs_dir_item entries or the filename for a given inode. There is one of these for each hard-linked copy of a file.
struct btrfs_inode_ref (10 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
index
|
Index of the inode this item's referencing in the directory |
8
|
__le16
|
name_len
|
length of the name, following this item |
btrfs_inode_extref
TODO
btrfs_inode_item
This structure contains the information typically associated with a UNIX-style inode's stat(2)
data. It is associated with the INODE_ITEM
.
struct btrfs_inode_item (160 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
generation
|
|
8
|
__le64
|
transid
|
|
16
|
__le64
|
size
|
stat.st_size ; Size of the file in bytes.
|
24
|
__le64
|
nbytes
|
stat.st_blocks in byte units. Size allocated to this file, in bytes; Sum of the offset fields of all EXTENT_DATA items for this inode. For directories: 0 .
|
32
|
__le64
|
block_group
|
Unused for normal inodes. Contains byte offset of block group when used as a free space inode. |
40
|
__le32
|
nlink
|
stat.st_nlink ; Count of INODE_REF entries for the inode. When used outside of a file tree, 1 .
|
44
|
__le32
|
uid
|
stat.st_uid
|
48
|
__le32
|
gid
|
stat.st_gid
|
52
|
__le32
|
mode
|
stat.st_mode
|
56
|
__le64
|
rdev
|
stat.st_rdev
|
64
|
__le64
|
flags
|
Inode flags, see below. |
72
|
__le64
|
sequence
|
Sequence number used for NFS compatibility. Initialized to 0 and incremented each time mtime value is changed.
|
80
|
__le64
|
reserved[4]
|
Reserved for future use. |
112
|
struct btrfs_timespec
|
atime
|
stat.st_atime
|
124
|
struct btrfs_timespec
|
ctime
|
stat.st_ctime
|
136
|
struct btrfs_timespec
|
mtime
|
stat.st_mtime
|
148
|
struct btrfs_timespec
|
otime
|
Timestamp of inode creation. |
Flags
NOTE: The unimplemented status of any of these flags was evaluated against Linux 4.11-rc2.
BTRFS_INODE_NODATASUM [0x1]
- Do not perform checksum operations on this inode.
BTRFS_INODE_NODATACOW [0x2]
- Do not perform CoW for data extents on this inode when the reference count is
1
.
BTRFS_INODE_READONLY [0x4]
- Inode is read-only regardless of UNIX permissions or ownership.
- This bit is still checked and returns
EACCES
but there is no way to set it. That suggests that it has been superseded byBTRFS_INODE_IMMUTABLE
.
- This bit is still checked and returns
BTRFS_INODE_NOCOMPRESS [0x8]
- Do not compress this inode.
- This flag may be changed by the kernel as compression ratios change. If the compression ratio for data associated with an inode becomes undesirable, this flag will be set. It may be cleared if the data changes and the compression ratio is favorable again.
BTRFS_INODE_PREALLOC [0x10]
- Inode contains preallocated extents. This instructs the kernel to attempt to avoid CoWing those extents.
BTRFS_INODE_SYNC [0x20]
- Operations on this inode will be performed synchronously.
- This flag is converted to a VFS-level inode flag but is not handled anywhere.
BTRFS_INODE_IMMUTABLE [0x40]
- Inode is read-only regardless of UNIX permissions or ownership. Attempts to modify this inode will result in
EPERM
being returned to the user.
BTRFS_INODE_APPEND [0x80]
- This inode is append-only.
BTRFS_INODE_NODUMP [0x100]
- This inode is not a candidate for dumping using the
dump(8)
program.- This flag will be accepted on all kernels but is not implemented
BTRFS_INODE_NOATIME [0x200]
- Do not update
atime]
when this inode is accessed.
BTRFS_INODE_DIRSYNC [0x400]
- Operations on directory operations will be performed synchronously.
- This flag is converted to a VFS-level inode flag but is not handled anywhere.
BTRFS_INODE_COMPRESS [0x800]
- Compression is enabled on this inode.
btrfs_header
Every tree block (leaf or node) starts with this header.
- bytenr
- virtual address of block
- owner
- the object id of the tree this block belongs to, for example BTRFS_ROOT_TREE_OBJECTID
btrfs_key / btrfs_disk_key
The btrfs_key
is one of the fundamental btrfs data structures. Every item in every tree in the file system is located using its key. The btrfs_key
can be more accurately described as a 3-tuple used to locate any item in any tree in the file system.
btrfs_key
objects only exists in memory and is in CPU byte order. btrfs_disk_key
is identical to btrfs_key
except that objectid
and offset
are in little endian (disk) byte order and are part of the file system on-disk format.
struct btrfs_key and struct btrfs_disk_key (17 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
u64 or __le64
|
objectid
|
The object identifier for this item |
8
|
u8
|
type
|
The type of the item this key describes |
9
|
u64 or __le64
|
offset
|
More accurately described as "third component." It is literally an offset only in some contexts. |
The objectid
field contains a value that is defined by the tree in which it is located. For example, in the EXTENT_TREE, the objectid
contains the starting byte offset of the extent it describes.
The type
field is universal. It always contains the type of the item identified by the key. There are no changes in usage or context that depend on the tree using the key.
The offset
field contains a value that is defined by the item type. For example, keys of type = EXTENT_ITEM
use the offset
to store the size of the extent the item describes. Keys of type = METADATA_ITEM
use the offset
to store the level of the tree where the tree block is located.
btrfs_root_item
This structure holds defines the the root of a btree. It is associated with the ROOT_ITEM type. This structure is never used outside of this item.
struct btrfs_root_item (439 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
struct btrfs_inode_item
|
inode
|
Several fields are initialized but only flags is interpreted at runtime.
|
160
|
__le64
|
generation
|
transid of the transaction that created this root.
|
168
|
__le64
|
root_dirid
|
For file trees, the objectid of the root directory in this tree (always 256 ).
Otherwise, |
176
|
__le64
|
bytenr
|
The disk offset in bytes for the root node of this tree. |
184
|
__le64
|
byte_limit
|
Unused. Always 0 .
|
192
|
__le64
|
bytes_used
|
Unused. |
200
|
__le64
|
last_snapshot
|
The last transid of the transaction that created a snapshot of this root.
|
208
|
__le64
|
flags
|
See below. |
216
|
__le32
|
refs
|
Originally indicated a reference count. In modern usage, it is only 0 or 1 .
|
220
|
struct btrfs_disk_key
|
drop_progress
|
Contains key of last dropped item during subvolume removal or relocation. Zeroed otherwise. |
237
|
__u8
|
drop_level
|
The tree level of the node described in drop_progress .
|
238
|
__u8
|
level
|
The height of the tree rooted at bytenr .
|
The following fields depend on the subvol_uuids+subvol_times features | |||
239
|
__le64
|
generation_v2
|
If equal to generation , indicates validity of the following fields.If the root is modified using an older kernel, this field and generation will become out of sync. This is normal and recoverable.
|
247
|
u8[16]
|
uuid
|
This subvolume's UUID. |
263
|
u8[16]
|
parent_uuid
|
The parent's UUID (for use with send/receive). |
279
|
u8[16]
|
received_uuid
|
The received UUID (for used with send/receive). |
295
|
__le64
|
ctransid
|
The transid of the last transaction that modified this tree, with some exceptions (like the internal caches or relocation).
|
303
|
__le64
|
otransid
|
The transid of the transaction that created this tree.
|
311
|
__le64
|
stransid
|
The transid for the transaction that sent this subvolume. Nonzero for received subvolume.
|
319
|
__le64
|
rtransid
|
The transid for the transaction that received this subvolume. Nonzero for received subvolume.
|
327
|
struct btrfs_timespec
|
ctime
|
Timestamp for ctransid .
|
339
|
struct btrfs_timespec
|
otime
|
Timestamp for otransid .
|
351
|
struct btrfs_timespec
|
stime
|
Timestamp for stransid .
|
363
|
struct btrfs_timespec
|
rtime
|
Timestamp for rtransid .
|
375
|
__le64[8]
|
reserved
|
Reserved for future use. |
Flags
btrfs_root_item.flags
BTRFS_ROOT_SUBVOL_RDONLY [0x1]
- Flag to indicate that this root is read-only.
btrfs_inode_item.flags
- In addition to flags documented at btrfs_inode_item.
-
BTRFS_INODE_ROOT_ITEM_INIT [1 << 31]
- Flag to indicate that the flags and byte_limit flags have been properly initialized.
btrfs_root_ref
References a subvolume fs tree root. Used for both forward and backward root refs. The name of the tree is stored after the end of the struct
struct btrfs_root_ref (18 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
dirid
|
Subtree ID. |
8
|
__le64
|
sequence
|
Directory sequence number of subtree entry |
16
|
__le16
|
name_len
|
Length of subtree name |
This structure contains the count for a shared back reference for a file data extent.
Follows a btrfs_extent_inline_ref of type BTRFS_SHARED_DATA_REF_KEY within an EXTENT_ITEM item. It is never used separately outside of the item body. It immediately follows the btrfs_extent_inline_ref
structure that contains the byte offset of the metadata leaf block that contains the EXTENT_DATA item that references this extent.
struct btrfs_shared_data_ref (4 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le32
|
count
|
Number of references held. |
btrfs_stripe
This structure is used to define the backing device storage that compose a btrfs chunk. It is associated with the CHUNK_ITEM
item. This structure is never used outside of this item.
struct btrfs_stripe (32 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
devid | Device ID that contains this stripe. |
8
|
__le64
|
offset | Location of the start of the stripe, in bytes. Size is determined by the |
16
|
__u8[16]
|
dev_uuid | UUID of the device that contains this stripe. Used to confirm that the correct device has been retrieved. |
The devid
and offset
fields are used to construct a key to retrieve a DEV_ITEM
from the DEV_TREE
. The key takes the following form.
struct btrfs_key | ||
---|---|---|
objectid
|
type
|
offset
|
devid
|
BTRFS_DEV_ITEM_KEY [216]
|
offset
|
btrfs_super_block
The primary superblock is located at 0x1 0000 (6410 KiB). Mirror copies of the superblock are located at physical addresses 0x400 0000 (6410 MiB), 0x40 0000 0000 (25610 GiB), and 0x4 0000 0000 0000 (1 PiB), if these locations are valid. btrfs normally updates all superblocks, but in SSD mode it will update only one at a time. The superblock with the highest generation is used when reading.
Note that btrfs only recognizes disks with a valid 0x1 0000 superblock; otherwise, there would be confusion with other filesystems.
TODO
struct btrfs_super_block | ||||
---|---|---|---|---|
Off | Size | Type | field | Description |
0 | 20 | u8[BTRFS_CSUM_SIZE] | csum | Checksum of everything past this field (from 20 to 1000) |
20 | 10 | u8[BTRFS_FSID_SIZE] | fsid | FS UUID |
30 | 8 | __le64 | bytenr | physical address of this block (different for mirrors) |
38 | 8 | __le64 | flags | |
40 | 8 | __le64 | magic | magic ("_BHRfS_M") |
48 | 8 | __le64 | generation | generation |
50 | 8 | __le64 | root | logical address of the root tree root |
58 | 8 | __le64 | chunck_root |
logical address of the chunk tree root |
60 | 8 | __le64 | log_root | logical address of the log tree root |
68 | 8 | __le64 | log_root_transid | log_root_transid |
70 | 8 | __le64 | total_bytes | total_bytes |
78 | 8 | __le64 | bytes_used | bytes_used |
80 | 8 | __le64 | root_dir_objectid | root_dir_objectid (usually 6) |
88 | 8 | __le64 | num_devices | num_devices |
90 | 4 | __le64 | sectorsize | sectorsize |
94 | 4 | __le64 | nodesize | nodesize |
98 | 4 | __le64 | __unused_leafsize | leafsize |
9c | 4 | __le64 | stripesize | stripesize |
a0 | 4 | __le64 | sys_chunk_array_size | sys_chunk_array_size |
a4 | 8 | __le64 | chunk_root_generation | chunk_root_generation |
ac | 8 | __le64 | compat_flags | compat_flags |
b4 | 8 | __le64 | compat_ro_flags | compat_ro_flags - only implementations that support the flags can write to the filesystem |
bc | 8 | __le64 | incompat_flags | incompat_flags - only implementations that support the flags can use the filesystem |
c4 | 2 | __le64 | csum_type | csum_type - Btrfs currently uses the CRC32c little-endian hash function with seed -1. |
c6 | 1 | u8 | root_level | root_level |
c7 | 1 | u8 | chunk_root_level | chunk_root_level |
c8 | 1 | u8 | log_root_level | log_root_level |
c9 | 62 | btrfs_dev_item | dev_item |
DEV_ITEM data for this device |
12b | 100 | char[BTRFS_LABEL_SIZE] | label | label (may not contain '/' or '\\') |
22b | 8 | __le64 | cache_generation | cache_generation |
233 | 8 | __le64 | uuid_tree+generation | uuid_tree_generation |
23b | f0 | __le64 | reserved[30] | reserved /* future expansion */ |
32b | 800 | u8 | sys_chunk_array[BTRFS_SYSTEM_CHUNK_ARRAY_SIZE] |
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. |
b2b | 2a0 | btrfs_root_backup | super_roots[BTRFS_NUM_BACKUP_ROOTS] | Contain super_roots (4 btrfs_root_backup) |
dcb | 235 | current unused | ||
1000 |
btrfs_timespec
btrfs_tree_block_info
This structure contains the level of tree at which the node described this back reference is located. It contains a field for the first key within the tree block it describes but the field is considered unused.
This structure always follows a struct btrfs_extent_item
within an EXTENT_ITEM
with the BTRFS_EXTENT_FLAG_TREE_BLOCK
flag set and is followed by one or more struct btrfs_extent_inline_ref records
.
Newer file systems with the skinny metadata feature enabled use METADATA_ITEM
items instead, which eliminate the need for this separate structure.
struct btrfs_tree_block_info (18 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
struct btrfs_disk_key
|
|
Although this value may be accurate, it's unused. |
17
|
__u8
|
level
|
Level of the tree that contains this node
|
btrfs_qgroup_status_item
One item per quota tree. Holds information about quota state.
struct btrfs_qgroup_status_item (32 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
version
|
Quota version. Currently always set to 1 (BTRFS_QGROUP_STATUS_VERSION) |
8
|
__le64
|
generation
|
Number updated during every commit. Used to check for inconsistencies |
16
|
__le64
|
flags
|
See below. |
24
|
__le64
|
rescan
|
Used during rescan to record the progress. It contains a logical address. |
Flags
BTRFS_QGROUP_STATUS_FLAG_ON [0x1]
- subvolume quota turned on.
BTRFS_QGROUP_STATUS_FLAG_RESCAN [0x2]
- Signals whether rescan is in progress.
BTRFS_QGROUP_STATUS_FLAG_INCONSISTENT [0x4]
- Turned on when some qgroup entries are known to be out of date, either because the configuration has changed in a certain way that requires rescan or because the fs has been mounted with a non-qgroup-aware version. Turning qouta off and on again makes it inconsistent, too.
btrfs_qgroup_info_item
One item per qgroup. Holds information about number of bytes used by this qgroup.
struct btrfs_qgroup_info_item (40 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
generation
|
Id of transaction that modified this qgroup item |
8
|
__le64
|
rfer
|
Referenced bytes (including shared data) |
16
|
__le64
|
rfer_cmpr
|
Referenced bytes compressed |
24
|
__le64
|
excl
|
Exclusive data referenced |
32
|
__le64
|
excl_cmpr
|
Exclusive compressed bytes |
btrfs_qgroup_limit_item
One item per qgroup (pairs with btrfs_qgroup_info_item). Holds information about enabled limits for a qgroup
struct btrfs_qgroup_limit_item (40 bytes) | |||
---|---|---|---|
offset | type | field | description |
0
|
__le64
|
flags
|
Contains information about enabled limits. See below |
8
|
__le64
|
max_rfer
|
Maximum amount of referenced data allowed |
16
|
__le64
|
max_excl
|
Maximum amount of exclusive data allowed |
24
|
__le64
|
rsv_rfer
|
Unused |
32
|
__le64
|
rsv_excl
|
Unused |
Flags
BTRFS_QGROUP_LIMIT_MAX_RFER [0x1]
- Limit on maximum referenced data enabled
BTRFS_QGROUP_LIMIT_MAX_EXCL [0x2]
- Limit on maximum eclusive data enabled
BTRFS_QGROUP_LIMIT_RSV_RFER [0x4]
- Unused
BTRFS_QGROUP_LIMIT_RSV_EXCL [0x8]
- Unused
BTRFS_QGROUP_LIMIT_RFER_CMPR [0x10]
- Limit on maximum compressed referenced data enabled
BTRFS_QGROUP_LIMIT_EXCL_CMPR [0x20]
- Limit on maximum exclusive compressed data size enabled