btrfs package¶

Submodules¶

btrfs.crc32c module¶

btrfs.crc32c.crc32c(crc, data)[source]¶

General crc32c function. You likely don’t need to call this one, but use one of the more specific helpers in this module.

Parameters

crc (int) – Seed value.
data (bytes) – Bytes to checksum.

Returns

A 32 bit checksum.

Return type

int

btrfs.crc32c.crc32c_data(data)[source]¶

Compute the checksum for a sectorsize block of bytes. These are the kind of checksum that go into the CSUM tree.

Parameters: data (bytes) – A single disk block of data.
Returns: Btrfs checksum for the data.
Return type: int

btrfs.crc32c.name_hash(name)[source]¶

The name hash function is used to compute a crc32c of a filename. The resulting value is used in the offset field of they key of a DirItem object in subvolume trees.

By searching for the numeric value, a file with a certain name can quickly be found without searching the whole directory content.

Parameters: name (bytes) – File name as bytes. For convenience, if a unicode string is provided, it will be encoded as utf-8.
Returns: A btrfs name hash.
Return type: int

Example:

>>> btrfs.crc32c.name_hash('mouton')
3786996654

btrfs.crc32c.extref_hash(parent_objectid, name)[source]¶

The extref_hash function uses the crc32c code with the inode number of the containing directory, and a filename to compute the offset field for the key of an InodeExtref objects.

Parameters

parent_objectid (int) – ObjectID of the containing directory.
name (bytes) – File name as bytes. For convenience, if a unicode string is provided, it will be encoded as utf-8.

Returns

A btrfs extref hash.

Return type

int

Example:

>>> btrfs.crc32c.extref_hash(256, 'mouton')
1903957879

btrfs.ctree module¶

This module contains Python object representations for btrfs metadata items.

Additionally, the helper FileSystem provides a convenient way to start exploring an online btrfs filesystem.

btrfs.ctree.U8(n)[source]¶

Parameters: n (int) – Any number.
Returns: Unsigned 8 bit number.
Return type: int

Example:

>>> btrfs.ctree.U8(64)
64
>>> btrfs.ctree.U8(-1)
255
>>> btrfs.ctree.U8(0x4000)
0

btrfs.ctree.ULL(n)[source]¶

Parameters: n (int) – Any number.
Returns: Unsigned 64 bit number.
Return type: int

Example:

>>> btrfs.ctree.ULL(64)
64
>>> btrfs.ctree.ULL(-1)
18446744073709551615
>>> btrfs.ctree.ULL(0x4000)
16384

btrfs.ctree.ROOT_TREE_OBJECTID = 1¶: Root tree

btrfs.ctree.EXTENT_TREE_OBJECTID = 2¶: Extent tree

btrfs.ctree.CHUNK_TREE_OBJECTID = 3¶: Chunk tree

btrfs.ctree.DEV_TREE_OBJECTID = 4¶: Device tree

btrfs.ctree.FS_TREE_OBJECTID = 5¶: Top level subvolume tree

btrfs.ctree.ROOT_TREE_DIR_OBJECTID = 6¶: Used in the root tree to store default subvolume information.

btrfs.ctree.CSUM_TREE_OBJECTID = 7¶: Checksum tree

btrfs.ctree.QUOTA_TREE_OBJECTID = 8¶: Quota tree

btrfs.ctree.UUID_TREE_OBJECTID = 9¶: Subvolume UUID tree

btrfs.ctree.FREE_SPACE_TREE_OBJECTID = 10¶: Free space tree

btrfs.ctree.DEV_STATS_OBJECTID = 0¶: Object ID of device statistics in the Device tree.

btrfs.ctree.BALANCE_OBJECTID = 18446744073709551612¶: Object ID to store balance status. (-4)

btrfs.ctree.ORPHAN_OBJECTID = 18446744073709551611¶: Object ID to store orphans that need cleaning. (-5)

btrfs.ctree.EXTENT_CSUM_OBJECTID = 18446744073709551606¶: Object ID used for checksum items. (-10)

btrfs.ctree.FREE_SPACE_OBJECTID = 18446744073709551605¶: Object ID for free space cache v1 items. (-11)

btrfs.ctree.FIRST_FREE_OBJECTID = 256¶: First available Object ID for subvolume trees.

btrfs.ctree.LAST_FREE_OBJECTID = 18446744073709551360¶: Last available Object ID for subvolume trees. (-256)

btrfs.ctree.FIRST_CHUNK_TREE_OBJECTID = 256¶: Object ID for Chunk objects in the Chunk tree.

btrfs.ctree.DEV_ITEMS_OBJECTID = 1¶: Object ID for Device items in the Device tree.

btrfs.ctree.INODE_ITEM_KEY = 1¶: Key type used by InodeItem

btrfs.ctree.INODE_REF_KEY = 12¶: Key type used by InodeRefList

btrfs.ctree.XATTR_ITEM_KEY = 24¶: Key type used by XAttrItemList

btrfs.ctree.ORPHAN_ITEM_KEY = 48¶: Key type used to track orphaned roots.

btrfs.ctree.DIR_ITEM_KEY = 84¶: Key type used by DirItemList

btrfs.ctree.DIR_INDEX_KEY = 96¶: Key type used by DirIndex

btrfs.ctree.EXTENT_DATA_KEY = 108¶: Key type used by FileExtentItem

btrfs.ctree.EXTENT_CSUM_KEY = 128¶: Key type used for checksum items.

btrfs.ctree.ROOT_ITEM_KEY = 132¶: Key type used by RootItem

btrfs.ctree.EXTENT_ITEM_KEY = 168¶: Key type used by ExtentItem

btrfs.ctree.METADATA_ITEM_KEY = 169¶: Key type used by MetaDataItem

btrfs.ctree.TREE_BLOCK_REF_KEY = 176¶: Key type used by TreeBlockRef

btrfs.ctree.EXTENT_DATA_REF_KEY = 178¶: Key type used by ExtentDataRef

btrfs.ctree.SHARED_BLOCK_REF_KEY = 182¶: Key type used by SharedBlockRef

btrfs.ctree.SHARED_DATA_REF_KEY = 184¶: Key type used by SharedDataRef

btrfs.ctree.BLOCK_GROUP_ITEM_KEY = 192¶: Key type used by BlockGroupItem

btrfs.ctree.FREE_SPACE_INFO_KEY = 198¶: Key type used by FreeSpaceInfo

btrfs.ctree.FREE_SPACE_EXTENT_KEY = 199¶: Key type used by FreeSpaceExtent

btrfs.ctree.FREE_SPACE_BITMAP_KEY = 200¶: Key type used by FreeSpaceBitmap

btrfs.ctree.DEV_EXTENT_KEY = 204¶: Key type used by DevExtent

btrfs.ctree.DEV_ITEM_KEY = 216¶: Key type used by DevItem

btrfs.ctree.CHUNK_ITEM_KEY = 228¶: Key type used by Chunk

btrfs.ctree.BALANCE_ITEM_KEY = 248¶: Balance status item key. Replaced by TEMPORARY_ITEM_KEY.

btrfs.ctree.TEMPORARY_ITEM_KEY = 248¶: Key for various short term persistent stored items.

btrfs.ctree.DEV_STATS_KEY = 249¶: Device statistics key. Replaced by PERSISTENT_ITEM_KEY.

btrfs.ctree.PERSISTENT_ITEM_KEY = 249¶: Key for various long term persistent stored items.

btrfs.ctree.BLOCK_GROUP_SINGLE = 0¶: Block Group single type. Does not exist in kernel code.

btrfs.ctree.BLOCK_GROUP_DATA = 1¶: Block Group DATA type.

btrfs.ctree.BLOCK_GROUP_SYSTEM = 2¶: Block Group SYSTEM type.

btrfs.ctree.BLOCK_GROUP_METADATA = 4¶: Block Group METADATA type.

btrfs.ctree.BLOCK_GROUP_RAID0 = 8¶: Block Group RAID0 profile.

btrfs.ctree.BLOCK_GROUP_RAID1 = 16¶: Block Group RAID1 profile.

btrfs.ctree.BLOCK_GROUP_DUP = 32¶: Block Group DUP profile.

btrfs.ctree.BLOCK_GROUP_RAID10 = 64¶: Block Group RAID10 profile.

btrfs.ctree.BLOCK_GROUP_RAID5 = 128¶: Block Group RAID5 profile.

btrfs.ctree.BLOCK_GROUP_RAID6 = 256¶: Block Group RAID6 profile.

btrfs.ctree.BLOCK_GROUP_TYPE_MASK = 7¶: All Block Group type bits (data, system, metadata).

btrfs.ctree.BLOCK_GROUP_PROFILE_MASK = 504¶: All Block Group profile bits (raid1, dup, etc…).

btrfs.ctree.qgroup_level(objectid)[source]¶

Helper to get qgroup level from a qgroup relation objectid.

Parameters: objectid (int) – 64-bit object ID field.
Returns: qgroup level.
Return type: int

btrfs.ctree.qgroup_subvid(objectid)[source]¶

Helper to get qgroup subvolume ID from a qgroup relation objectid.

Parameters: objectid (int) – 64-bit object ID field.
Returns: qgroup subvolume ID.
Return type: int

exception btrfs.ctree.ItemNotFoundError[source]¶

Bases: IndexError

Helper exception for lookup convenience functions.

If a convenience function on a btrfs.ctree.FileSystem object is supposed to return exactly one object at a specific location, and no object is found, this type of exception is raised.

An example is the block_group() helper, which raises this error if no block group item is found at the exact specified location.

class btrfs.ctree.Key(objectid, type_, offset)[source]¶

Bases: object

Btrfs metadata trees have a key space of 136-bit numbers.

A full 136-bit tree key is composed as:: (objectid << 72) + (type << 64) + offset

Parameters

objectid (int) – 64-bit object ID field.
type_ (int) – 8-bit type field.
offset (int) – 64-bit offset field.

Key objects support sorting and simple addition and subtraction. Also, when subtracting 1 from a zero key, the value wraps around to the largest value possible, vice versa.

Example:

>>> key1 = btrfs.ctree.Key(425, btrfs.ctree.DIR_ITEM_KEY, 17818406)
>>> key1
Key(425, 84, 17818406)
>>> str(key1)
'(425 DIR_ITEM 17818406)'
>>> key2 = btrfs.ctree.Key(442, btrfs.ctree.EXTENT_DATA_KEY, 0)
>>> key2 > key1
True

>>> min_key = btrfs.ctree.Key(0, 0, 0)
>>> min_key
Key(0, 0, 0)
>>> str(min_key)
'(0 0 0)'
>>> min_key - 1
Key(18446744073709551615, 255, 18446744073709551615)
>>> str(min_key - 1)
'(-1 255 -1)'

The -1 value in the string representation is just a convenience way to write the maximum 64 bit number. The actual value is still 18446744073709551615.

For example, when setting up a minimum and maximum key for a metadata search, the arithmetic that can be done helps quickly defining the maximum value. The next example shows the key range for finding all intormation about an inode in a filesystem tree:

Example:

>>> inum = 31337
>>> min_key = btrfs.ctree.Key(inum, 0, 0)
>>> max_key = btrfs.ctree.Key(inum + 1, 0, 0) - 1
>>>
>>> min_key
Key(31337, 0, 0)
>>> max_key
Key(31337, 255, 18446744073709551615)

property objectid¶: Key Object ID

property type¶: Key Type

property offset¶: Key Offset

property key¶: Full numeric 136-bit key value.

class btrfs.ctree.DiskKey(data)[source]¶

Bases: btrfs.ctree.Key

Object representation of struct btrfs_disk_key.

Objects of this type are used in metadata search results.

class btrfs.ctree.FileSystem(path)[source]¶

Bases: object

The FileSystem object is a bit of a spider in the web of this library. It contains a lot of convenience methods providing quick access to all kinds of functionality.

Parameters

path (str) – Path to the mounted filesystem.

Variables

path (str) – The filesystem path used to initialize this object.
fsid (uuid.UUID) – Filesystem ID.
nodesize (int) – B-tree node size (same as leaf size).
sectorsize (int) – Smallest allocatable block size in bytes for storing data.

The fsid, nodesize and sectorsize values are cached from a call to fs_info() when initializing the object.

It is highly recommended to use the built in context manager. Doing so prevents leaking the internal open file descriptor.

Example:

>>> with btrfs.ctree.FileSystem('/') as fs:
...     print(fs.top_level().generation)
...
3382004

fs_info()[source]¶

Returns: General filesystem information.
Return type: btrfs.ioctl.FsInfo

dev_info(devid)[source]¶

Parameters: devid (int) – Device ID.
Returns: Device information.
Return type: btrfs.ioctl.DevInfo

dev_stats(devid, reset=False)[source]¶

Parameters

devid (int) – Device ID.
reset (bool) – Reset device error counters to zero.

Returns

Device statistics.

Return type

btrfs.ioctl.DevStats

space_info()[source]¶

Returns: Space information
Return type: List[btrfs.ioctl.SpaceInfo]

devices(min_devid=1, max_devid=18446744073709551615)[source]¶

Parameters

min_devid (int) – Lowest Device ID to search for.
max_devid (int) – Highest Device ID to search for.

Returns

Device Items from the Chunk tree.

Return type

Iterator[DevItem]

chunks(min_vaddr=0, max_vaddr=18446744073709551615, nr_items=None)[source]¶

Parameters

min_vaddr (int) – Lowest virtual address to search for.
max_vaddr (int) – Highest virtual address to search for.
nr_items (int) – Maximum amount of items to return. Defaults to no limit.

Returns

Chunk items from the Chunk tree.

Return type

Iterator[Chunk]

dev_extents(min_devid=1, max_devid=18446744073709551615)[source]¶

Parameters

min_devid (int) – Lowest Device ID to search for.
max_devid (int) – Highest Device ID to search for.

Returns

Device Extent Items from the Device tree.

Return type

Iterator[DevExtent]

block_group(vaddr, length=None)[source]¶

Parameters

vaddr (int) – Starting virtual address of the block group.
length (int) – Block group length (optional). If this information is already known, it can be used to construct an exact match for the search key.

Returns

Block Group Item

Return type

BlockGroupItem

Raises

ItemNotFoundError if no Block Group Item can be found at the address.

extents(min_vaddr=0, max_vaddr=18446744073709551615, load_data_refs=False, load_metadata_refs=False)[source]¶

Parameters

min_vaddr (int) – Lowest virtual address to search for.
max_vaddr (int) – Highest virtual address to search for.
load_data_refs (bool) – Parse and load backreference information for data extents.
load_metadata_refs (bool) – Parse and load backreference information for metadata extents.

Returns

Extent and MetaData Items from the Extent tree

Return type

Iterator[Union[ExtentItem, MetaDataItem]]

The ‘refs’ are backreference information. These sub items are stored inside the ExtentItem and MetaDataItem Items, and overflow to separately indexed items. When dealing with search results in user space, these backreferences are of little use to us, since the search API only allows us to search in tree leaves. So, they’re ignored by default.

top_level()[source]¶

Returns: The top level subvolume with ID 5, a.k.a. FS_TREE_OBJECTID.
Return type: RootItem

subvolumes(min_id=256, max_id=18446744073709551360)[source]¶

Parameters

min_id (int) – Lowest subvolume ID to search for.
max_id (int) – Highest subvolume ID to search for.

Returns

Root Items from the Root tree, containing subvolume information.

Return type

Iterator[RootItem]

orphan_subvol_ids()[source]¶

Returns: ObjectID numbers of orphaned items in the Root tree.
Return type: List[int]

free_space_extents(min_vaddr=0, max_vaddr=18446744073709551615)[source]¶

Parameters

min_vaddr (int) – Minimum virtual address when searching for free space.
max_vaddr (int) – Maximum virtual address when searching for free space.

Returns

Free space extent information from the Free Space Tree.

Return type

Iterator[btrfs.free_space_tree.FreeSpaceExtent]

Note

The Free Space Tree can contain both Free Space Extent Items and Free Space Bitmap Items, which contain a more compact representation of free space extents. This helper function will transparently unpack these bitmaps and return one type of helper object, the FreeSpaceExtent object.

sync()[source]¶: Call the btrfs sync kernel function, causing a transaction commit.

features()[source]¶

Returns: Filesystem Features.
Return type: btrfs.ioctl.FeatureFlags

mixed_groups()[source]¶

Returns: True if this filesystem used mixed block groups with metadata and data in the same block groups, else False.
Return type: bool

usage()[source]¶

Returns: Detailed filesystem usage information.
Return type: btrfs.fs_usage.FsUsage

class btrfs.ctree.ItemData(header)[source]¶

Bases: object

ItemData is a base class for all tree item types.

Variables: key – Key under which this item is stored in the tree.

class btrfs.ctree.DevItem(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_dev_item.

A DevItem contains information about a single block device that is attached to the filesystem.

Tree: CHUNK_TREE_OBJECTID (3)
Key objectid: DEV_ITEMS_OBJECTID (1)
Key type: DEV_ITEM_KEY (216)
Key offset: Device ID.

Variables

devid (int) – Device ID.
total_bytes (int) – Total amount of bytes.
bytes_used (int) – Total amount of allocated bytes.
io_align (int) – Not used, set to same value as sector_size.
io_width (int) – Not used, set to same value as sector_size.
sector_size (int) – Smallest IO block size to use.
type (int) – Not used
generation (int) – Not used
start_offset (int) – Not used
dev_group (int) – Not used
seek_speed (int) – Not used
bandwidth (int) – Not used
uuid (uuid.UUID) – Device UUID.
fsid (uuid.UUID) – Filesystem ID.

class btrfs.ctree.Chunk(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_chunk.

A Chunk is a piece of virtual address space. A Chunk has a 1 to 1 relationship to a BlockGroup, and a 1 to many relationship with a fixed amount of Stripe objects.

Tree: CHUNK_TREE_OBJECTID (3)
Key objectid: FIRST_CHUNK_TREE_OBJECTID (256)
Key type: CHUNK_ITEM_KEY (228)
Key offset: Virtual address.

Variables

vaddr (int) – Virtual address where the Chunk starts (taken from the offset field of the item key).
length (int) – Chunk length in bytes,
owner (int) – Extent tree the chunk belongs to. Not used, always 2 now.
stripe_len (int) – Hardcoded to BTRFS_STRIPE_LEN, which is 64kiB.
type (int) – Block group flags for the corresponding block group. So, a Chunk type contains both Block Group type and profile.
io_align (int) – Not used, see stripe_len.
io_width (int) – Not used, see stripe_len.
sector_size (int) – Smallest IO block size to use.
num_stripes (int) – Amount of Stripe (or, also the amount of Device Extent) objects related to this Chunk.
sub_stripes (int) – A hack for RAID10. For RAID10 this value is 2, otherwise 1.
stripes – Stripe Items that are stored inside this Chunk Item.

property io_align_str¶: Pretty string representation for the io_align attribute.

property io_width_str¶: Pretty string representation for the io_width attribute.

property length_str¶: Pretty string representation for the length attribute.

property sector_size_str¶: Pretty string representation for the sector_size attribute.

property stripe_len_str¶: Pretty string representation for the stripe_len attribute.

property type_str¶: Pretty string representation for the type attribute.

class btrfs.ctree.Stripe(data)[source]¶

Bases: object

Object representation of struct btrfs_stripe.

A list of Stripe items is hidden inside the Chunk item and each of them contains information that points to the beginning of a Device Extent, which is an actual allocated piece of physical disk space in which data ends up that is written to the virtual address space of the Chunk.

Variables

devid (int) – Device ID of the device that holds the Device Extent.
offset (int) – Physical address on the device where the Device Extent starts.
uuid (uuid.UUID) – Device UUID of the device with the above listed devid.

class btrfs.ctree.DevExtent(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_dev_extent.

The Device Extent is a range of physical address space allocated from one of the attached devices and used by a Chunk to store data.

Tree: DEV_TREE_OBJECTID (4)
Key objectid: Device ID.
Key type: DEV_EXTENT_KEY (204)
Key offset: Physical address.

Variables

devid (int) – Device ID of the device that holds this Device Extent (taken from the objectid field of the item key).
paddr (int) – Physical address on the device where the Device Extent starts (taken from the offset field of the item key).
chunk_tree (int) – Chunk tree the device extent belongs to. This is always 3 now.
chunk_offset (int) – Virtual address of the related Chunk.
length (int) – Length in physical bytes.
chunk_tree_uuid (uuid.UUID) – UUID of the chunk tree that this Device Extent belongs to. This is currently always the UUID of tree 3.

property vaddr¶: Alias for the chunk_offset attribute.

property length_str¶: Pretty string representation for the length attribute.

class btrfs.ctree.BlockGroupItem(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_block_group_item.

The Block Group has a 1 to 1 relationship with a Chunk and tracks some usage information about a range of virtual address space.

Tree: EXTENT_TREE_OBJECTID (2)
Key objectid: Virtual address.
Key type: BLOCK_GROUP_ITEM_KEY (192)
Key offset: Block Group length.

Variables

vaddr (int) – Virtual address where the Bock Group starts (taken from the objectid field of the item key).
length (int) – Block Group length in bytes (taken from the offset field of the item key).
used (int) – Amount of bytes used by Extents in the Block Group.
chunk_objectid (int) – Object ID of the Chunk this Block Group relates to. Currently always 256.
flags (int) – Type and profile for this Block Group. e.g. 0x11, which is DATA|RAID1.

property used_pct¶: Convenience property that calculates the percentage of usage.

property flags_str¶: Pretty string representation for the flags attribute.

property length_str¶: Pretty string representation for the length attribute.

property used_str¶: Pretty string representation for the used attribute.

class btrfs.ctree.ExtentItem(header, data, load_data_refs=True, load_metadata_refs=True)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_extent_item.

An ExtentItem lives in the Extent Tree and tracks information about a piece of virtual address space that is in use. A FileExtentItem object from a subvolume tree can point to it, to let us know a file in the filesystem uses part of this extent.

Tree: EXTENT_TREE_OBJECTID (2)
Key objectid: Virtual address.
Key type: EXTENT_ITEM_KEY (168)
Key offset: Extent length.

If the skinny_metadata feature is enabled in the filesystem, then metadata extents are stored separately as MetaDataItem.

An ExtentItem includes inline backreference items. In the kernel, this information is used to be able to find out which different inodes in subvolume trees are using data from this extent. For us, in userspace, this information is not very relevant, since we cannot look into B-tree nodes using the kernel search API. So, by default the backreference information is ignored when creating these kind of objects from a metadata search.

Instead, to find out who is referencing data from an extent, the btrfs.ioctl.logical_to_ino() and btrfs.ioctl.logical_to_ino_v2() functions can be used.

Variables

vaddr (int) – Virtual address where the Extent starts (taken from the objectid field of the item key).
length (int) – Length of the extent in bytes (taken from the offset field of the item key).
refs (int) – Amount of explicit references to this extent.
generation (int) – Generation of the filesystem when this extent was created.
flags (int) – Some flags describing which type of extent this is.

The flags are an or-ed combination of one or more of the following values (available as attribute of this module):

EXTENT_FLAG_DATA: This extent contains data.
EXTENT_FLAG_TREE_BLOCK: This extent contains a metadata tree block.
BLOCK_FLAG_FULL_BACKREF: The tree block backreference contains a full back reference.

When backreference information is being loaded, there are a few additional lists present in this object. Also, when using the FileSystem.extents() helper to retrieve extent information, then separately stored backreference items which do not fit into the extent item itself any more are also appended to these lists:

If the extent is a data extent, then this object contains:

Variables

extent_data_refs (List[Union[InlineExtentDataRef, ExtentDataRef]]) – Indirect back references.
shared_data_refs (List[Union[InlineSharedDataRef, SharedDataRef]]) – Shared back references.

If the extent is a metadata tree block, then this object contains:

Variables

tree_block_refs (List[Union[InlineTreeBlockRef, TreeBlockRef]]) – Tree block backreferences.
shared_block_refs (List[Union[InlineSharedBlockRef, SharedBlockRef]]) – Shared tree block backreferences.

Further documentation of backreferences is out of scope for this module. Please refer to the btrfs wiki about resolving extent backreferences for more information.

property flags_str¶: Pretty string representation for the flags attribute.

class btrfs.ctree.ExtentDataRef(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_extent_data_ref.

Documentation of this item is out of scope for this module. Please refer to the btrfs wiki about resolving extent backreferences for more information.

Tree: EXTENT_TREE_OBJECTID (2)
Key type: EXTENT_DATA_REF_KEY (178)

Variables

root (int) – root
objectid (int) – objectid
offset (int) – offset
count (int) – count

class btrfs.ctree.InlineExtentDataRef(data)[source]¶

Bases: btrfs.ctree.ExtentDataRef

Identical content to ExtentDataRef, but the backreference was inlined in the extent item.

class btrfs.ctree.SharedDataRef(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_shared_data_ref.

Documentation of this item is out of scope for this module. Please refer to the btrfs wiki about resolving extent backreferences for more information.

Tree: EXTENT_TREE_OBJECTID (2)
Key type: SHARED_DATA_REF_KEY (184)

Variables

parent (int) – parent
count (int) – count

class btrfs.ctree.InlineSharedDataRef(data)[source]¶

Bases: btrfs.ctree.SharedDataRef

Identical content to SharedDataRef, but the backreference was inlined in the extent item.

class btrfs.ctree.TreeBlockInfo(data)[source]¶

Bases: object

Object representation of struct btrfs_tree_block_info.

Documentation of this item is out of scope for this module. Please refer to the btrfs wiki about resolving extent backreferences for more information.

Variables

key (Key) – key
level (int) – level

class btrfs.ctree.MetaDataItem(header, data, load_refs=True)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_metadata_item.

A MetaDataItem lives in the Extent Tree and tracks information about a piece of virtual address space that is in use to store a metadata tree block.

Tree: EXTENT_TREE_OBJECTID (2)
Key objectid: Virtual address.
Key type: METADATA_ITEM_KEY (169)
Key offset: Extent length.

If the skinny_metadata filesystem feature is enabled, metadata extents are tracked using this item type, which encodes all necessecary data in a more compact way than using a regular extent item.

Variables

vaddr (int) – Virtual address where the Extent starts (taken from the objectid field of the item key).
skinny_level (int) – Tree level. field of the item key).
refs (int) – Amount of explicit references to this extent.
generation (int) – Generation of the filesystem when this extent was created.
flags (int) – See below.

The flags are an or-ed combination of one or more of the following values (available as attribute of this module):

EXTENT_FLAG_TREE_BLOCK: This extent contains a metadata tree block.
BLOCK_FLAG_FULL_BACKREF: The tree block backreference contains a full back reference.

When backreference information is being loaded, there are a few additional lists present in this object. Also, when using the FileSystem.extents() helper to retrieve extent information, then separately stored backreference items which do not fit into the extent item itself any more are also appended to these lists:

Variables

tree_block_refs (List[Union[InlineTreeBlockRef, TreeBlockRef]]) – Tree block backreferences.
shared_block_refs (List[Union[InlineSharedBlockRef, SharedBlockRef]]) – Shared tree block backreferences.

Further documentation of backreferences is out of scope for this module. Please refer to the btrfs wiki about resolving extent backreferences for more information.

property flags_str¶: Pretty string representation for the flags attribute.

class btrfs.ctree.TreeBlockRef(header)[source]¶

Bases: btrfs.ctree.ItemData

Tree block reference

Documentation of this item is out of scope for this module. Please refer to the btrfs wiki about resolving extent backreferences for more information.

Tree: EXTENT_TREE_OBJECTID (2)
Key type: TREE_BLOCK_REF_KEY (176)

Variables: root (int) – root

class btrfs.ctree.InlineTreeBlockRef(root)[source]¶

Bases: btrfs.ctree.TreeBlockRef

Identical content to TreeBlockRef, but the backreference was inlined in the extent item.

class btrfs.ctree.SharedBlockRef(header)[source]¶

Bases: btrfs.ctree.ItemData

Shared tree block reference

Documentation of this item is out of scope for this module. Please refer to the btrfs wiki about resolving extent backreferences for more information.

Tree: EXTENT_TREE_OBJECTID (2)
Key type: SHARED_BLOCK_REF_KEY (182)

Variables: parent (int) – parent

class btrfs.ctree.InlineSharedBlockRef(parent)[source]¶

Bases: btrfs.ctree.SharedBlockRef

Identical content to SharedBlockRef, but the backreference was inlined in the extent item.

class btrfs.ctree.TimeSpec(data)[source]¶

Bases: object

Object representation of struct btrfs_timespec.

The TimeSpec type of item is used embedded in other metadata items when a time value needs to be stored. Examples are the mtime, ctime etc fields in an inode item.

It’s also possible to create objects of this type manually. To do so, use the static from_values() helper function. (The regular object constructor is reserved for the code parsing metadata items from search queries.)

Variables

sec (int) – seconds
nsec (int) – nanoseconds

Example:

>>> my_time = btrfs.ctree.TimeSpec.from_values(1546280270, 4044945)
>>> my_time.sec
1546280270
>>> my_time.nsec
4044945
>>> my_time.iso8601
'2018-12-31T18:17:50.404495'

static from_values(sec, nsec)[source]¶

Create a Timespec object

Parameters

sec (int) – seconds
nsec (int) – nanoseconds

property iso8601¶: Return the timestamp as ISO8601 formatted string.

class btrfs.ctree.InodeItem(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_inode_item.

The inode item stores information of a single file or directory. Not the name, because a file can have multiple names.

Tree: FS_TREE_OBJECTID (5) or any other subvolume tree.
Key objectid: Inode number.
Key type: INODE_ITEM_KEY (1)
Key offset: 0

Variables

objectid (int) – The inode number. (taken from the objectid field of the item key).
generation (int) – Generation of the filesystem when the inode was created.
transid (int) – Generation of the filesystem when the inode was last changed.
size (int) – File size in bytes.
nbytes (int) – Allocated disk blocks for this file in bytes.
block_group (int) – Only used for free space cache v1, for which it’s the related block group virtual address.
nlink (int) – Amount of hardlinks the file has.
uid (int) – Numerical user id of the owner of the file.
gid (int) – Numerical group id of the owner of the file.
mode (int) – File permissions.
rdev (int) – Major and minor device numbers for special files.
flags (int) – Inode flags, see below.
sequence (int) – Sequence number for NFS.
atime (TimeSpec) – Time of last access.
ctime (TimeSpec) – Time of last file metadata change. Also updated when file contents change.
mtime (TimeSpec) – Time of last modification to file contents.
otime (TimeSpec) – Time of file birth.

The flags are an or-ed combination of one or more of the following values (available as attribute of this module):

INODE_NODATASUM
INODE_NODATACOW
INODE_READONLY
INODE_NOCOMPRESS
INODE_PREALLOC
INODE_SYNC
INODE_IMMUTABLE
INODE_APPEND
INODE_NODUMP
INODE_NOATIME
INODE_DIRSYNC
INODE_COMPRESS

property flags_str¶: Pretty string representation for the flags attribute.

property mode_str¶: Pretty string representation for the mode attribute.

class btrfs.ctree.InodeRefList(header, data)[source]¶

Bases: btrfs.ctree.ItemData, collections.abc.MutableSequence

A collection of struct btrfs_inode_ref indexed under a single tree key.

A InodeRefList is a list of InodeRef objects which contain information about every name the inode is known under in a single directory. So, when we already know the inode number of a file, we can find in which places it has hardlinks pointing at it.

Tree: FS_TREE_OBJECTID (5) or any other subvolume tree.
Key objectid: Inode number.
Key type: INODE_REF_KEY (12)
Key offset: Inode number of the containing directory.

This class is a helper that does not exist in Btrfs itself.

Besides acting as an immutable list of InodeRef objects, there are some additional attributes:

Variables

objectid (int) – Inode number of the file. (taken from the objectid field of the item key)
parent_objectid (int) – Inode number of the containing directory. (taken from the offset field of the item key)

insert(index, value)[source]¶: Not implemented.

class btrfs.ctree.InodeRef(data, pos)[source]¶

Bases: object

Object representation of struct btrfs_inode_ref.

Also see InodeRefList.

Variables

index (int) – Directory index number in the containing directory. Refer to the parent_objectid attribute of the InodeRefList object that contains this InodeRef to find the inode number of the directory.
name_len (int) – Amount of bytes used to store the filename.
name (bytes) – Filename as bytes.

property name_str¶: Pretty string representation for the name attribute.

class btrfs.ctree.InodeExtrefList(header, data)[source]¶

Bases: btrfs.ctree.ItemData, collections.abc.MutableSequence

A collection of struct btrfs_inode_extref indexed under a single tree key.

A InodeExtrefList is a list of InodeExtref objects. By default, names under which a file is known are stored in the InodeRefList of InodeRef. However, if a file has so many hardlinks that that item would become bigger than a metadata page, the rest of the items are stored separately.

Tree: FS_TREE_OBJECTID (5) or any other subvolume tree.
Key objectid: Inode number.
Key type: INODE_EXTREF_KEY (13)
Key offset: extref_hash() of the filename.

The InodeExtref item is a list because multiple different filenames can end up having the same crc32 value.

This class is a helper that does not exist in Btrfs itself.

Besides acting as an immutable list of InodeExtRef objects, there are some additional attributes:

Variables

objectid (int) – Inode number of the file. (taken from the objectid field of the item key)
extref_hash (int) – extref_hash() of the filename. (taken from the offset field of the item key)

insert(index, value)[source]¶: Not implemented.

class btrfs.ctree.InodeExtref(data, pos)[source]¶

Bases: object

Object representation of struct btrfs_inode_extref.

Also see InodeExtrefList.

Variables

parent_objectid (int) – Inode number of the containing directory.
index (int) – Directory index number in the containing directory.
name_len (int) – Amount of bytes used to store the filename.
name (bytes) – Filename as bytes.

property name_str¶: Pretty string representation for the name attribute.

class btrfs.ctree.DirItemList(header, data)[source]¶

Bases: btrfs.ctree.ItemData, collections.abc.MutableSequence

A collection of struct btrfs_dir_item indexed under a single tree key.

A DirItemList is a list of DirItem objects. Based on a filename hash, they point to the inode item for the corresponding file. Since multiple different filenames can end up having the same name hash, this item can contain multiple DirItem objects.

Tree: FS_TREE_OBJECTID (5) or any other subvolume tree.
Key objectid: Inode number of the directory.
Key type: DIR_ITEM_KEY (84)
Key offset: name_hash() of the filename.

This class is a helper that does not exist in Btrfs itself.

Besides acting as an immutable list of DirItem objects, there are some additional attributes:

Variables

objectid (int) – Inode number of the directory. (taken from the objectid field of the item key)
name_hash (int) – name_hash() of the filename. (taken from the offset field of the item key)

insert(index, value)[source]¶: Not implemented.

class btrfs.ctree.XAttrItemList(header, data)[source]¶

Bases: btrfs.ctree.DirItemList

A collection of struct btrfs_dir_item, used to store extended attributes and indexed under a single tree key.

An XAttrItemList is a list of XAttrItem objects, which contain key value pairs in the name and data fields of the dir_item struct. Since multiple different keys can end up having the same name hash, this item can contain multiple XAttrItem objects.

Tree: FS_TREE_OBJECTID (5) or any other subvolume tree.
Key objectid: Inode number of a file on which the xattr is set.
Key type: XATTR_ITEM_KEY (24)
Key offset: name_hash() of the key.

This class is a helper that does not exist in Btrfs itself.

Besides acting as an immutable list of XAttrItem objects, there are some additional attributes:

Variables

objectid (int) – Inode number of a file on which the xattr is set. (taken from the objectid field of the item key)
name_hash (int) – name_hash() of the xattr key. (taken from the offset field of the item key)

class btrfs.ctree.DirItem(data, pos)[source]¶

Bases: object

Object representation of struct btrfs_dir_item.

Based on the name hash of a filename, this object directly points to the inode item for the corresponding file. Using this mapping allows quick file access when the name is known, even in directories with a large amount of files in them.

Also see DirItemList.

Variables

location (DiskKey) – Key of the file inode item.
transid (int) – Generation of the filesystem when this item was created.
data_len (int) – Not used, always 0.
name_len (int) – Amount of bytes used to store the filename.
type (int) – File type that is represented by the inode item that is being referenced.
name (bytes) – Filename as bytes.

File type is one of the following values (available as attribute of this module):

FT_UNKNOWN
FT_REG_FILE
FT_DIR
FT_CHRDEV
FT_BLKDEV
FT_FIFO
FT_SOCK
FT_SYMLINK
FT_XATTR
FT_MAX

property data_str¶: Pretty string representation for the data attribute.

property name_str¶: Pretty string representation for the name attribute.

property type_str¶: Pretty string representation for the type attribute.

class btrfs.ctree.XAttrItem(data, pos)[source]¶

Bases: btrfs.ctree.DirItem

Object representation of struct btrfs_dir_item, used to store extended attribute information.

This object contains a key and value for an extended attribute on a file. It reuses the dir_item data structure.

Also see XattrItemList.

Variables

transid (int) – Generation of the filesystem when this item was created.
name_len (int) – Amount of bytes used to store the key.
data_len (int) – Amount of bytes used to store the value.
name (bytes) – Key as bytes.
data (bytes) – Value as bytes.

property data_str¶: Pretty string representation for the data attribute.

property name_str¶: Pretty string representation for the name attribute.

property type_str¶: Pretty string representation for the type attribute.

class btrfs.ctree.DirIndex(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_dir_item, but used to store filenames ordered on directory index.

The DirIndex objects list the contents of a directory in the order in which items were added.

Tree: FS_TREE_OBJECTID (5) or any other subvolume tree.
Key objectid: Inode number of the directory.
Key type: DIR_INDEX_KEY (96)
Key offset: Index in the directory.

Variables

objectid (int) – Inode number of the directory. (taken from the objectid field of the item key)
index (int) – Index in the directory. (taken from the offset field of the item key)
location (DiskKey) – Key of the file inode item.
transid (int) – Generation of the filesystem when this item was created.
data_len (int) – Not used, always 0.
name_len (int) – Amount of bytes used to store the filename.
type (int) – File type that is represented by the inode item that is being referenced.
name (bytes) – Filename as bytes.

File type is one of the following values (available as attribute of this module):

FT_UNKNOWN
FT_REG_FILE
FT_DIR
FT_CHRDEV
FT_BLKDEV
FT_FIFO
FT_SOCK
FT_SYMLINK
FT_XATTR
FT_MAX

property name_str¶: Pretty string representation for the name attribute.

property type_str¶: Pretty string representation for the type attribute.

class btrfs.ctree.RootItem(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_root_item.

The RootItem lives in the root tree, a.k.a. the ‘tree of trees’. It contains information about the root metadata node of another tree.

Tree: ROOT_TREE_OBJECTID (1).
Key objectid: Tree ID.
Key type: ROOT_ITEM_KEY (132)
Key offset: Index in the directory.

Variables

inode (InodeItem) – Embedded inode item. Only the flags field of it is used.
generation (int) – Generation of the filesystem when this root was created.
root_dirid (int) – Objectid for the root directory in a subvolume tree (always 256 in that case). 0 for other trees.
bytenr (int) – Virtual address of the root node of this tree.
byte_limit (int) – Not used
bytes_used (int) – Not used
last_snapshot (int) – The generation of the filesystem when the most recent snapshot of a subvolume was made.
flags (int) – See below.
refs (int) – Not used, either 0 or 1.
drop_progress (DiskKey) – Key of the last removed item during cleanup of a removed subvolume.
drop_level (int) – The tree level of the metadata node or leaf that contains the key from drop_progress.
level (int) – The height of the tree that this root item refers to.

The flags are an or-ed combination of one or more of the following values (available as attribute of this module):

ROOT_SUBVOL_RDONLY: The subvolume is read only.

The following fields were introduced in Linux 3.6. Btrfs would still allow using the filesystem with an older kernel, but if the content of generation_v2 does not match generation, all new fields would be invalidated:

Variables

generation_v2 (int) – Same value as generation.
uuid (uuid.UUID) – Subvolume UUID.
parent_uuid (uuid.UUID) – Subvolume UUID that this subvolume is a snapshot of.
received_uuid (uuid.UUID) – Subvolume UUID of the subvolume that this subvolume was duplicated from using send/receive.
ctransid (int) – Generation when the tree was last modified.
otransid (int) – Generation when the tree was created.
stransid (int) – Generation of the filesystem from which a subvolume was sent. Only used if this is a received subvolume.
rtransid (int) – Generation of this filesystem when the subvolume was received.
ctime (TimeSpec) – Timestamp for ctransid.
otime (TimeSpec) – Timestamp for otransid.
stime (TimeSpec) – Timestamp for stransid.
rtime (TimeSpec) – Timestamp for rtransid.

property flags_str¶: Pretty string representation for the flags attribute.

class btrfs.ctree.FileExtentItem(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of btrfs_file_extent_item.

For every piece of a file, the FileExtentItem points to the data extent where the actual data is stored. A FileExtentItem does not have to reference a complete extent. It can also use part of it.

Tree: FS_TREE_OBJECTID (5) or any other subvolume tree.
Key objectid: Inode number of the file.
Key type: EXTENT_DATA_KEY (108)
Key offset: Logical offset in the file where the referenced data appears.

Variables

logical_offset (int) – Logical offset in the file where the referenced data appears. (taken from the offset field of the item key).
generation (int) – Generation of the filesystem when this file extent was created.
ram_bytes (int) – Upper limit on the memory needed in bytes to store the extent after decompression.
compression (int) – Compression type, see below.

The compression field can have one of the following values (available as attribute of this module):

COMPRESS_NONE
COMPRESS_ZLIB
COMPRESS_LZO
COMPRESS_ZSTD

Variables

encryption (int) – Not used Encryption type, always 0.
other_encoding (int) – Not used
type (int) – Type of extent, see below.

The extent type can be one of the following:

FILE_EXTENT_INLINE: This is an inline extent. The data is stored inside
the metadata leaf, right after the type field.
FILE_EXTENT_REG: This is a regular extent.
FILE_EXTENT_PREALLOC: Preallocated extent (for which no actual data is
written yet).

If the extent type is FILE_EXTENT_INLINE, the following fields are not available:

Variables

disk_bytenr (int) – Virtual address of the data extent we reference a range from.
disk_num_bytes (int) – Size of the data extent we reference a range from.
offset (int) – The offset inside the data extent where the data we need starts.
num_bytes (int) – The amount of bytes to be used from that offset onwards.

This means that (disk_bytenr EXTENT_ITEM disk_num_bytes) is the tree key of the extent item in the extent tree. Also, remember that these numbers will always be multiples of disk block sizes, because that’s how it gets cowed. We don’t just use 1 or 2 bytes from another extent.

property compression_str¶: Pretty string representation for the compression attribute.

property type_str¶: Pretty string representation for the type attribute.

class btrfs.ctree.FreeSpaceInfo(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation of struct btrfs_free_space_info.

The free space tree contains a free space info item for every block group.

Tree: FREE_SPACE_TREE_OBJECTID (10).
Key objectid: Virtual address.
Key type: FREE_SPACE_INFO_KEY (198)
Key offset: Block Group length.

Variables

vaddr (int) – Virtual address. (taken from the objectid field of the item key)
length (int) – Block Group length. (taken from the offset field of the item key)
extent_count (int) – Amount of free space extents in the Block Group.
flags (int) – A flag indicating if the free space for this Block Group is stored as bitmap. The flag is FREE_SPACE_USING_BITMAPS, available as attribute of this module.

property flags_str¶: Pretty string representation for the flags attribute.

property length_str¶: Pretty string representation for the length attribute.

class btrfs.ctree.FreeSpaceExtent(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation for free space extent information.

Tree: FREE_SPACE_TREE_OBJECTID (10).
Key objectid: Virtual address of the start of the free space.
Key type: FREE_SPACE_EXTENT_KEY (199)
Key offset: Length of the free space.

Note that this metadata object type does not have actual item data. All needed information is encoded in the item key.

Variables

vaddr (int) – Virtual address of the start of the free space. (taken from the objectid field of the item key)
length (int) – Length of the free space. (taken from the offset field of the item key)

property length_str¶: Pretty string representation for the length attribute.

class btrfs.ctree.FreeSpaceBitmap(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Object representation for free space bitmap information.

Tree: FREE_SPACE_TREE_OBJECTID (10).
Key objectid: Virtual address of the start of the free space bitmap.
Key type: FREE_SPACE_BITMAP_KEY (200)
Key offset: Length of the covered virtual address space.

Variables

vaddr (int) – Virtual address of the start of the free space bitmap. (taken from the objectid field of the item key)
length (int) – Length of the covered virtual address space. (taken from the offset field of the item key)
bitmap (bytes) – The free space bitmap.

unpack(sectorsize)[source]¶

Unpack the free space bitmap.

Parameters: sectorsize (int) – sectorsize property of the filesystem.
Returns: A generator of btrfs.free_space_tree.FreeSpaceExtent tuples.
Return type: Iterator[btrfs.free_space_tree.FreeSpaceExtent]

class btrfs.ctree.NotImplementedItem(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Placeholder object for metadata item types that have not been implemented yet.

class btrfs.ctree.UnknownItem(header, data)[source]¶

Bases: btrfs.ctree.ItemData

Placeholder object for metadata item types that are unrecognized.

btrfs.ctree.classify(header, data)[source]¶

Convenience function to automatically convert an item header and data into one of the object types in this module.

Parameters

header (btrfs.ioctl.SearchHeader) – Search header.
data (bytes) – Item data.

Returns

Object representing the metadata item.

Return type

Subclass of ItemData

Example:

>>> with btrfs.FileSystem('/') as fs:
...     chunk_tree_objects = btrfs.ioctl.search_v2(fs.fd, 3)
...     btrfs.utils.pretty_print(
...         (btrfs.ctree.classify(header, data)
...          for header, data in chunk_tree_objects)
...     )

The search function returns a generator, which we name chunk_tree_objects. The pretty printer can handle any iterable, so the above fragment will, in a ‘streaming’ way, dump the chunk tree on the screen.

btrfs.free_space_tree module¶

This module contains a small helper, which is used by the unpack() function of a btrfs.ctree.FreeSpaceBitmap. It’s also used by the free_space_extents() convenience method of a btrfs.ctree.FileSystem object for generating a simple stream of free space extent info transparently unpacking bitmaps.

class btrfs.free_space_tree.FreeSpaceExtent(vaddr, length)¶

Bases: tuple

property length¶: Alias for field number 1

property vaddr¶: Alias for field number 0

btrfs.fs_usage module¶

This module provides advanced usage reporting for a btrfs filesystem.

By calling the usage() function on a btrfs.ctree.FileSystem object, an FsUsage object is returned that can be inspected.

Example:

>>> import btrfs
>>> with btrfs.FileSystem('/') as fs:
...     usage = fs.usage()
...     btrfs.utils.pretty_print(usage)

Note

If you’re not yet familiar with it, btrfs terminology can be quite confusing.

Here’s just an example: In btrfs terminology, a ‘space’ is the collection of all block groups that have identical type and profile flags. For example, Metadata, DUP is a ‘space’. The word ‘space’ is also used for the distinction between ‘physical address space’ and ‘virtual address space’.

class btrfs.fs_usage.DevSpaceUsage(devid, flags)[source]¶

Bases: object

Physical usage details for a single space per device.

For example, a Data, DUP chunk of 1GiB results in a 2GiB allocation of physical bytes on the device. A Data, RAID5 chunk of 3GiB, allocated over 4 devices results in a 1GiB allocation on each device, with 256MiB reserved for parity.

Variables

flags (int) – Block group type and profile, e.g. Data, RAID1.
devid (int) – Device ID
allocated (int) – Total amount of allocated physical bytes.
parity (int) – Amount of allocated physical bytes reserved for parity.

Note

Objects of this type are provided as part of an FsUsage object.

property allocated_str¶: Pretty string representation for the allocated attribute.

property flags_str¶: Pretty string representation for the flags attribute.

property parity_str¶: Pretty string representation for the parity attribute.

class btrfs.fs_usage.DevUsage(device)[source]¶

Bases: object

Physical usage details for a device.

Variables

devid (int) – Device ID
total (int) – Total amount of bytes.
allocated (int) – Total amount of allocated bytes.
dev_space_usage (dict of DevSpaceUsage) – Allocated and parity bytes per space for this device, indexed by space flags.
unallocatable (int) – Physical bytes that are not allocatable because of unbalanced device sizes.
unallocatable_reclaimable (int) – Physical bytes that are not allocatable because of unbalanced allocations.

Note

Objects of this type are provided as part of an FsUsage object.

property allocated_str¶: Pretty string representation for the allocated attribute.

property total_str¶: Pretty string representation for the total attribute.

property unallocatable_hard_str¶: Pretty string representation for the unallocatable_hard attribute.

property unallocatable_reclaimable_str¶: Pretty string representation for the unallocatable_reclaimable attribute.

property unallocatable_soft_str¶: Pretty string representation for the unallocatable_soft attribute.

property unallocated_str¶: Pretty string representation for the unallocated attribute.

class btrfs.fs_usage.RawSpaceUsage(space)[source]¶

Bases: object

Physical usage details per space.

For example, if the Metadata, RAID1 space has a 2GiB size in terms of virtual addressing, in which 768MiB is used, then the allocated physical size is 4GiB and amount of physical bytes used is 1.5GiB. A Data, RAID6 space of 8GiB, consisting of two 4GiB block groups (virtual address space), each distributed over 6 devices, will occupy 2*(4+2) = 12 GiB physical allocated bytes and have 4GiB of allocated bytes reserved for parity blocks.

Variables

flags (int) – Block group type and profile, e.g. Data, RAID1.
allocated (int) – Total amount of allocated bytes.
parity (int) – Total amount of allocated bytes reserved for parity blocks.
used (int) – Total amount of physical bytes used.

Note

Objects of this type are provided as part of an FsUsage object.

property allocated_str¶: Pretty string representation for the allocated attribute.

property flags_str¶: Pretty string representation for the flags attribute.

property parity_str¶: Pretty string representation for the parity attribute.

property used_str¶: Pretty string representation for the used attribute.

class btrfs.fs_usage.BlockGroupTypeUsage(block_group_type)[source]¶

Bases: object

Physical usage details per block group type.

Totals per block group type (System, Data, Metadata, or, Data+Metadata for mixed mode), disregarding the block group profile (Single, RAID1, etc).

Variables

type (int) – Block group type, e.g. Metadata.
allocated (int) – Total amount of allocated bytes.
parity (int) – Total amount of allocated bytes reserved for parity blocks.
used (int) – Total amount of physical bytes used.

Note

Objects of this type are provided as part of an FsUsage object.

property allocated_str¶: Pretty string representation for the allocated attribute.

property parity_str¶: Pretty string representation for the parity attribute.

property type_str¶: Pretty string representation for the type attribute.

property used_str¶: Pretty string representation for the used attribute.

class btrfs.fs_usage.VirtualSpaceUsage(space)[source]¶

Bases: object

Virtual usage per space.

Variables

flags (int) – Block group type and profile, e.g. Data, RAID1.
total (int) – Total amount of allocated bytes for this space.
used (int) – Total amount of virtual bytes used.

Note

Objects of this type are provided as part of an FsUsage object.

property flags_str¶: Pretty string representation for the flags attribute.

property total_str¶: Pretty string representation for the total attribute.

property used_str¶: Pretty string representation for the used attribute.

class btrfs.fs_usage.VirtualBlockGroupTypeUsage(block_group_type)[source]¶

Bases: object

Virtual address space usage per block group type.

Totals for the virtual address space per block group type (System, Data, Metadata, or, Data+Metadata for mixed mode), disregarding the block group profile (Single, RAID1, etc).

Variables

flags (int) – Block group type, e.g. Metadata.
total (int) – Total amount of allocated bytes.
used (int) – Total amount of virtual bytes used.
unused (int) – Amount of allocated but unused virtual bytes.

Note

Objects of this type are provided as part of an FsUsage object.

property total_str¶: Pretty string representation for the total attribute.

property type_str¶: Pretty string representation for the type attribute.

property unused_str¶: Pretty string representation for the unused attribute.

property used_str¶: Pretty string representation for the used attribute.

class btrfs.fs_usage.FsUsage(fs)[source]¶

Bases: object

Detailed usage information for a file system.

Target block group profiles (used for new chunk allocations):

Variables

target_profile_system (int) – Profile for new System chunk allocations.
target_profile_metadata (int) – Profile for new Metadata chunk allocations (not for a mixed filesystem).
target_profile_data (int) – Profile for new Data chunk allocations (not for a mixed filesystem).
target_profile_mixed (int) – Profile for new Data+Metadata chunk allocations (only for a mixed filesystem).

Usage details for the physical address space:

Variables

total (int) – Total amount of physical bytes in the filesystem.
allocated (int) – Total amount of allocated physical bytes.
parity (int) – Total amount of allocated bytes reserved for parity blocks.
dev_usage (dict of DevUsage) – Physical usage details per device, indexed by Device ID.
block_group_type_usage (dict of BlockGroupTypeUsage) – Physical usage details per block group type, indexed by block group type.
raw_space_usage (dict of RawSpaceUsage) – Physical usage details per space, indexed by space flags.

Usage details for the virtual address space:

Variables

virtual_total (int) – Total amount of virtual address space.
virtual_used (int) – Total amount of bytes used inside the virtual address space.
virtual_block_group_type_usage (dict of VirtualBlockGroupTypeUsage) – Virtual address space usage per block group type, indexed by block group type.
virtual_space_usage (dict of VirtualSpaceUsage) – Virtual usage per space, indexed by space flags.

Allocatable space information:

The soft unallocatable amount of bytes is the currently unallocatable part of the physical bytes on attached devices because the allocations in the filesystem are unbalanced. This value is estimated by extrapolating the current usage pattern and simulating new chunk allocations using the current target allocation profiles. By doing so, we also discover how much extra virtual address space these allocations would result in.

Variables

unallocatable_soft (int) – Unallocatable physical disk space because of unbalanced allocations.
estimated_allocatable_virtual_metadata (int) – Estimated amount of virtual address space bytes that can be added by allocating physical bytes for metadata, based on the current usage pattern (not for a mixed filesystem).
estimated_allocatable_virtual_data (int) – Estimated amount of virtual address space bytes that can be added by allocating physical bytes for data, based on the current usage pattern (not for a mixed filesystem).
estimated_allocatable_virtual_mixed (int) – Estimated amount of virtual address space bytes that can be added by allocating physical bytes for metadata and data,, based on the current usage pattern (only for a mixed filesystem).

The hard unallocatable amount of bytes is the amount of physical bytes that cannot be used for allocations, because of having different sizes of devices attached. These values are unallocatable disk space that remains after trying to simulate data and metadata allocations in a ratio similar to current usage, starting with all disks being empty.

Variables

unallocatable_hard (int) – Unallocatable physical disk space because of unbalanced device sizes.
estimated_full_allocatable_virtual_metadata (int) – Estimated amount of virtual address space bytes for metadata, in case of optimally balanced allocations. (not for a mixed filesystem).
estimated_full_allocatable_virtual_data (int) – Estimated amount of virtual address space bytes for data, in case of optimally balanced allocations. (not for a mixed filesystem).
estimated_full_allocatable_virtual_mixed (int) – Estimated amount of virtual address space bytes for metadata and data, in case of optimally balanced allocations. (only for a mixed filesystem).

The difference between soft and hard unallocatable bytes is the amount of physical disk space that can be reclaimed for allocations when rebalancing the filesystem.

Variables: unallocatable_reclaimable (int) – Unallocatable physical bytes that can be reclaimed when balancing the filesystem.

Some other totals for convenience:

Variables

allocatable (int) – The total amount of physical bytes that are allocatable in this filesystem. I.e. total size minus unallocatable_soft.
allocatable_left (int) – The amount of allocatable physical bytes remaining, until the filesystem will report being out of space, given current usage pattern and target profiles.

By combining the unused virtual space in already allocated chunks and estimated allocatable virtual bytes, we get actual numbers of estimated free space. I.e., what we would like df to show us.

Variables

free_metadata (int) – Estimated virtual space left to use for metadata (not for a mixed filesystem).
free_data (int) – Estimated virtual space left to use for data (not for a mixed filesystem).
free_mixed (int) – Estimated virtual space left to use for metadata and data (only for a mixed filesystem).

property allocatable_left_str¶: Pretty string representation for the allocatable_left attribute.

property allocatable_str¶: Pretty string representation for the allocatable attribute.

property allocated_str¶: Pretty string representation for the allocated attribute.

property estimated_allocatable_virtual_data_str¶: Pretty string representation for the estimated_allocatable_virtual_data attribute.

property estimated_allocatable_virtual_metadata_str¶: Pretty string representation for the estimated_allocatable_virtual_metadata attribute.

property estimated_allocatable_virtual_mixed_str¶: Pretty string representation for the estimated_allocatable_virtual_mixed attribute.

property estimated_full_allocatable_virtual_data_str¶: Pretty string representation for the estimated_full_allocatable_virtual_data attribute.

property estimated_full_allocatable_virtual_metadata_str¶: Pretty string representation for the estimated_full_allocatable_virtual_metadata attribute.

property estimated_full_allocatable_virtual_mixed_str¶: Pretty string representation for the estimated_full_allocatable_virtual_mixed attribute.

property free_data_str¶: Pretty string representation for the free_data attribute.

property free_metadata_str¶: Pretty string representation for the free_metadata attribute.

property free_mixed_str¶: Pretty string representation for the free_mixed attribute.

property parity_str¶: Pretty string representation for the parity attribute.

property target_profile_data_str¶: Pretty string representation for the target_profile_data attribute.

property target_profile_metadata_str¶: Pretty string representation for the target_profile_metadata attribute.

property target_profile_mixed_str¶: Pretty string representation for the target_profile_mixed attribute.

property target_profile_system_str¶: Pretty string representation for the target_profile_system attribute.

property total_str¶: Pretty string representation for the total attribute.

property unallocatable_hard_str¶: Pretty string representation for the unallocatable_hard attribute.

property unallocatable_reclaimable_str¶: Pretty string representation for the unallocatable_reclaimable attribute.

property unalloctable_soft_str¶: Pretty string representation for the unalloctable_soft attribute.

property virtual_total_str¶: Pretty string representation for the virtual_total attribute.

property virtual_used_str¶: Pretty string representation for the virtual_used attribute.

btrfs.ioctl module¶

This module contains the implementation of the calling side of several kernel ioctl functions, as well as Python object representations of related C structs.

For convenience reasons, many of the functions can be called implicitly by calling utility functions on a btrfs.ctree.FileSystem object.

class btrfs.ioctl.FsInfo(buf)[source]¶

Bases: object

Object representation of struct btrfs_ioctl_fs_info_args.

Variables

max_id (int) – Highest device id of currently attached devices.
num_devices (int) – Amount of devices attached to the filesystem.
fsid (uuid.UUID) – Filesystem ID.
nodesize (int) – B-tree node size (same as leaf size).
sectorsize (int) – Smallest allocatable block size in bytes for storing data.
clone_alignment (int) – Expected alignment of arguments for clone and deduplication ioctls.

Note

An object of this type should be retrieved by calling the fs_info() function on a btrfs.ctree.FileSystem object.

property clone_alignment_str¶: Pretty string representation for the clone_alignment attribute.

property nodesize_str¶: Pretty string representation for the nodesize attribute.

property sectorsize_str¶: Pretty string representation for the sectorsize attribute.

btrfs.ioctl.fs_info(fd)[source]¶

Call the BTRFS_IOC_FS_INFO ioctl.

Parameters: fd (int) – Open file descriptor to any inode in the filesystem.
Returns: A FsInfo object.

Note

This function should usually be used implicitly by calling the fs_info() function on a btrfs.ctree.FileSystem object.

class btrfs.ioctl.DevInfo(buf)[source]¶

Bases: object

Object representation of struct btrfs_ioctl_dev_info_args.

Variables

devid (int) – Device ID.
uuid (uuid.UUID) – Device UUID.
bytes_used (int) – Amount of allocated bytes on the device.
total_bytes (int) – Device size in bytes.
path (str) – Path to the device node to access this device directly.

Note

An object of this type should be retrieved by calling the dev_info() function on a btrfs.ctree.FileSystem object.

property bytes_used_str¶: Pretty string representation for the bytes_used attribute.

property total_bytes_str¶: Pretty string representation for the total_bytes attribute.

btrfs.ioctl.dev_info(fd, devid)[source]¶

Call the BTRFS_IOC_DEV_INFO ioctl.

Parameters

fd (int) – Open file descriptor to any inode in the filesystem.
devid (int) – Device ID of the device to retrieve information about.

Returns

A DevInfo object.

Note

This function should usually be used implicitly by calling the dev_info() function on a btrfs.ctree.FileSystem object.

class btrfs.ioctl.DevStats(buf)[source]¶

Bases: object

Object representation of struct btrfs_ioctl_get_dev_stats.

Variables

devid (int) – Device ID.
write_errs (int) – Amount of write errors.
read_errs (int) – Amount of read errors.
flush_errs (int) – Amount of flush errors.
generation_errs (int) – Amount of metadata tree generation mismatch errors.
corruption_errs (int) – Amount of checksum failures.

Note

An object of this type should be retrieved by calling the dev_stats() function on a btrfs.ctree.FileSystem object.

property counters¶

btrfs.ioctl.dev_stats(fd, devid, reset=False)[source]¶

Call the BTRFS_IOC_DEV_STATS ioctl.

Parameters

fd (int) – Open file descriptor to any inode in the filesystem.
devid (int) – Device ID of the device to retrieve information about.
reset (bool) – If true, counters are reset to zero.

Returns

A DevStats object.

Note

This function should usually be used implicitly by calling the dev_stats() function on a btrfs.ctree.FileSystem object.

class btrfs.ioctl.SpaceArgs(space_slots, total_spaces)¶

Bases: tuple

Object representation of struct btrfs_ioctl_space_args.

property space_slots¶: Alias for field number 0

property total_spaces¶: Alias for field number 1

class btrfs.ioctl.SpaceInfo(buf, pos)[source]¶

Bases: object

Object representation of struct btrfs_ioctl_space_info.

In btrfs terminology, a ‘space’ is the collection of all block groups that have identical type and profile flags. For example, Metadata, DUP is a ‘space’.

Variables

flags (int) – Block group type and profile, e.g. Data, RAID1.
total_bytes (int) – Total amount of allocated bytes for this space.
used_bytes (int) – Total amount of bytes used.

Note

A list of objects of this type should be retrieved by calling the space_info() function on a btrfs.ctree.FileSystem object.

property type¶: Only block group type, e.g. Data, from flags.

property profile¶: Only block group profile, e.g. RAID1, from flags.

property flags_str¶: Pretty string representation for the flags attribute.

property profile_str¶: Pretty string representation for the profile attribute.

property total_bytes_str¶: Pretty string representation for the total_bytes attribute.

property type_str¶: Pretty string representation for the type attribute.

property used_bytes_str¶: Pretty string representation for the used_bytes attribute.

btrfs.ioctl.space_info(fd)[source]¶

Call the BTRFS_IOC_SPACE_INFO ioctl.

Parameters: fd (int) – Open file descriptor to any inode in the filesystem.
Returns: A list of SpaceInfo objects.

Note

This function should usually be used implicitly by calling the space_info() function on a btrfs.ctree.FileSystem object.

class btrfs.ioctl.SearchHeader(transid, objectid, offset, type, len)¶

Bases: tuple

Object representation of struct btrfs_ioctl_search_header.

property len¶: Alias for field number 4

property objectid¶: Alias for field number 1

property offset¶: Alias for field number 2

property transid¶: Alias for field number 0

property type¶: Alias for field number 3

btrfs.ioctl.search(fd, tree, min_key=None, max_key=None, min_transid=0, max_transid=18446744073709551615, nr_items=None)[source]¶

Call the BTRFS_IOC_TREE_SEARCH ioctl.

The TREE_SEARCH ioctl allow us to directly read btrfs metadata.

Parameters

fd (int) – Open file descriptor to any inode in the filesystem.
tree (int) – The tree we’re searching in. 1 is the tree of tree roots, 2 is the extent tree, etc… A special tree_id value of 0 will cause a search in the subvolume tree that the inode which is passed to the ioctl is part of.
min_key (btrfs.ctree.Key) – Minimum key value for items to return.
max_key (btrfs.ctree.Key) – Maximum key value for items to return.
min_transid (int) – Minimum transaction id for the metadata leaf to have items included. Defaults to 0.
max_transid (int) – Maximum transaction id for the metadata leaf to have items included. Defaults to 2**64-1.
nr_items (int) – Maximum amount of items to fetch. Defaults to no limit.

Returns

An iterator over search results, containing a search header and the item data per item.

Return type

Iterator[Tuple[SearchHeader, memoryview]]

btrfs.ioctl.search_v2(fd, tree, min_key=None, max_key=None, min_transid=0, max_transid=18446744073709551615, nr_items=None, buf_size=16384)[source]¶

Call the BTRFS_IOC_TREE_SEARCH_V2 ioctl.

The TREE_SEARCH_V2 ioctl allow us to directly read btrfs metadata.

Unlike TREE_SEARCH, it allows to use a bigger buffer than 4096 bytes for results. This makes it possible to retrieve individual metadata items that are bigger than 4kiB, or get more results from a single lookup for efficiency reasons.

Parameters

fd (int) – Open file descriptor to any inode in the filesystem.
tree (int) – The tree we’re searching in. 1 is the tree of tree roots, 2 is the extent tree, etc… A special tree_id value of 0 will cause a search in the subvolume tree that the inode which is passed to the ioctl is part of.
min_key (btrfs.ctree.Key) – Minimum key value for items to return.
max_key (btrfs.ctree.Key) – Maximum key value for items to return.
min_transid (int) – Minimum transaction id for the metadata leaf to have items included. Defaults to 0.
max_transid (int) – Maximum transaction id for the metadata leaf to have items included. Defaults to 2**64-1.
nr_items (int) – Maximum amount of items to fetch. Defaults to no limit.
buf_size (int) – Buffer size in bytes that will be used for search results.

Returns

An iterator over search results, containing a search header and the item data per item.

Return type

Iterator[Tuple[SearchHeader, memoryview]]

class btrfs.ioctl.Inode(inum, offset, root)¶

Bases: tuple

Inode helper object for LOGICAL_INO ioctls results.

property inum¶: Alias for field number 0

property offset¶: Alias for field number 1

property root¶: Alias for field number 2

btrfs.ioctl.logical_to_ino(fd, vaddr, bufsize=4096)[source]¶

Call the BTRFS_IOC_LOGICAL_INO ioctl.

The LOGICAL_INO ioctl helps us converting a virtual address into a list of inode numbers of files that use the data extent at that specific address.

Example:

>>> import btrfs
>>> with btrfs.FileSystem('/') as fs:
...     btrfs.ioctl.logical_to_ino(fs.fd, 607096483840)
([Inode(inum=4686948, offset=0, root=259),
  Inode(inum=4686948, offset=0, root=2104)], 0)

Parameters

fd (int) – Open file descriptor to any inode in the filesystem.
vaddr (int) – Virtual address to search for.
bufsize (int) – Size in bytes. Default value is 4kiB (4096 bytes). Maximum allowed value is 64kiB (65536 bytes).

Returns

A list of Inode objects and the amount of extra bytes for the provided buffer that would be needed to be able to return all results found.

Return type

Tuple[List[Inode], int]

The default buffer size, 4kiB, can store 170 results. The maximum buffer size, 64kiB, can store 2730 results. If a large buffer size is needed, then use the logical ino v2 ioctl, which was introduced in Linux kernel 4.15.

Also, if the requested virtual address points to a disk block that is part of a larger extent, but there’s no inode that references exactly this block in the extent, there will be no results. To get a list of inodes that reference any block in the extent, use the logical ino v2 ioctl instead, while setting the ignore_offset flag.

btrfs.ioctl.logical_to_ino_v2(fd, vaddr, bufsize=4096, ignore_offset=False)[source]¶

Call the BTRFS_IOC_LOGICAL_INO_V2 ioctl.

The LOGICAL_INO_V2 ioctl helps us converting a virtual address into a list of inode numbers of files that use the data extent at that specific address.

Example:

>>> import btrfs
>>> with btrfs.FileSystem('/') as fs:
...     btrfs.ioctl.logical_to_ino_v2(fs.fd, 607096483840)
([Inode(inum=4686948, offset=0, root=259),
  Inode(inum=4686948, offset=0, root=2104)], 0)

Parameters

fd (int) – Open file descriptor to any inode in the filesystem.
vaddr (int) – Virtual address to search for.
bufsize (int) – Size in bytes. Default value is 4kiB (4096 bytes). Maximum allowed value is 16MiB (16777216 bytes).
ignore_offset (bool) – If ignore_offset is set to True, the results returned will list all inodes that reference any disk block from the extent the virtual address is part of.

Returns

A list of Inode objects and the amount of extra bytes for the provided buffer that would be needed to be able to return all results found.

Return type

Tuple[List[Inode], int]

The default buffer size, 4kiB can store 170 results. To get additional results, retry the call with a larger buffer, adding the amount of bytes that was reported to be additionally needed.

class btrfs.ioctl.InoLookupResult(treeid, name_bytes)¶

Bases: tuple

Helper object for INO_LOOKUP ioctls results.

property name_bytes¶: Alias for field number 1

property treeid¶: Alias for field number 0

btrfs.ioctl.ino_lookup(fd, treeid=0, objectid=256)[source]¶

Call the BTRFS_IOC_INO_LOOKUP ioctl.

The INO_LOOKUP ioctl returns the containing subvolume tree id and the relative path inside that subvolume of the first listed path for an inode number.

Example:

>>> import btrfs
>>> import os
>>> fd = os.open('/', os.O_RDONLY)
>>> btrfs.ioctl.ino_lookup(fd, objectid=4686948)
InoLookupResult(treeid=259, name_bytes=b'bin/bash/')

Parameters

fd (int) – File descriptor pointing to an inode.
treeid (int) – Subvolume tree to search in, or 0 to use the subvolume that contains the inode that fd points to.
objectid (int) – Inode number to get the path for.

Returns

An InoLookupResult tuple with subvolume tree id and filesystem path as bytes.

Return type

InoLookupResult

class btrfs.ioctl.BalanceArgs(profiles=None, usage_min=None, usage_max=None, devid=None, pstart=None, pend=None, vstart=None, vend=None, target=None, limit_min=None, limit_max=None, stripes_min=None, stripes_max=None, soft=False)[source]¶

Bases: object

Object representation of struct btrfs_balance_args.

When calling the balance ioctl, we have to pass filters that define which subset of block groups in the filesystem we want to rewrite.

Example:

>>> args = btrfs.ioctl.BalanceArgs(vstart=115993477120,
        vend=191155404800, limit_min=2, limit_max=2)
>>> print(args)
flags(VRANGE|LIMIT_RANGE) vrange=115993477120..191155404800, limit=2..2
>>> args
BalanceArgs(vstart=115993477120, vend=191155404800, limit_min=2,
            limit_max=2)

When defining multiple filter criteria, they all have to match for a block group to be processed by the balance run.

The balance ioctl accepts three of these BalanceArgs at the same time, one for data, one for metadata and one for the system type.

Parameters

profiles (int) – Match block groups having either of the given profiles. A single value of or-ed together block group profile constants. E.g. BLOCK_GROUP_RAID1 | BLOCK_GROUP_DUP. Note that there is no BLOCK_GROUP_SINGLE, since the single profile uses the value zero. For choosing the single profile here, use the AVAIL_ALLOC_BIT_SINGLE constant that is available in the btrfs.ctree module.
usage_min (int) – Match block groups with usage equal to or above the given percentage.
usage_max (int) – Match block groups with usage under the given percentage.
devid (int) – Match block groups whose related Chunk object has a Stripe object using physical space on this device.
pstart (int) – Match block groups using physical bytes on a device on or after the given start address. Use this in combination with the devid option.
pend (int) – Match block groups using physical bytes on a device before the given end address. Use this in combination with the devid option.
vstart (int) – Match block groups that overlap with the given virtual address, or a higher address.
vend (int) – Match block groups that overlap with a virtual address before the given address.
target (int) – Target block group profile to convert to.
limit_min (int) – Try to process at least this amount of block groups.
limit_max (int) – Process at most this amount of block groups.
stripes_min (int) – Match block groups which have an associated Chunk object that has at least this amount of related Stripe objects.
stripes_max (int) – Match block groups which have an associated Chunk object that has at most this amount of related Stripe objects.
soft (bool) – When set, skip matching block groups that already have the target profile when doing a conversion.

The arguments given when creating a BalanceArgs object are available as attributes on the resulting object, together with a flags field:

Variables: flags (int) – Flags denoting which filter options are set.

The flags are an or-ed combination of one or more of the following values (available as attribute of this module):

BALANCE_ARGS_PROFILES
BALANCE_ARGS_USAGE
BALANCE_ARGS_DEVID
BALANCE_ARGS_DRANGE
BALANCE_ARGS_VRANGE
BALANCE_ARGS_LIMIT
BALANCE_ARGS_LIMIT_RANGE
BALANCE_ARGS_STRIPES_RANGE
BALANCE_ARGS_CONVERT
BALANCE_ARGS_SOFT
BALANCE_ARGS_USAGE_RANGE

Note

This class does not implement single usage and limit values, and is thus incompatible with a Linux kernel older than v4.4.

property flags_str¶: Pretty string representation for the flags attribute.

property profiles_str¶: Pretty string representation for the profiles attribute.

property target_str¶: Pretty string representation for the target attribute.

class btrfs.ioctl.BalanceProgress(state, expected, considered, completed)[source]¶

Bases: object

Object representation of struct btrfs_balance_progress.

Variables: state (int) – current state of a running balance operation.

When a progress object is returned by balance_v2() after a successful uninterrupted run, the value of state is 0.

When obtaining a progress object by calling balance_progress(), the possible state values (available as attribute of this module) are:

BALANCE_STATE_RUNNING: Balance is running.
BALANCE_STATE_PAUSE_REQ: Balance is running, but a pause is requested.
BALANCE_STATE_CANCEL_REQ: Balance is running, but cancel is requested.

Variables

expected (int) – Estimated number of block groups that will be relocated to fulfill the request.
considered (int) – Number of block groups that were inspected to see if they match the requested filters.
completed (int) – Number of block groups relocated so far.

property state_str¶: Pretty string representation for the state attribute.

exception btrfs.ioctl.BalanceError(state, msg)[source]¶

Bases: Exception

Exception class for balance functionality.

A BalanceError can be thrown by any of the balance related functions in this module.

Variables

state (int) – Probably one of the balance state values, see below.
msg (str) – A message describing the error condition.

Availalable balance state values (available as attribute of this module) are:

BALANCE_STATE_RUNNING
BALANCE_STATE_PAUSE_REQ
BALANCE_STATE_CANCEL_REQ

property errno¶

btrfs.ioctl.balance_v2(fd, data_args=None, meta_args=None, sys_args=None, force=False, resume=False)[source]¶

Call the BTRFS_IOC_BALANCE_V2 ioctl.

Ask the kernel to relocate block groups.

Example:

>>> import btrfs
>>> args = btrfs.ioctl.BalanceArgs(vstart=115993477120,
        vend=191155404800, limit_min=2, limit_max=2)
>>> with btrfs.FileSystem('/') as fs:
...     btrfs.ioctl.balance_v2(fs.fd, data_args=args)
...
BalanceProgress(state=0x0, expected=2, considered=466, completed=2)

Parameters

fd (int) – Open file descriptor to any inode in the filesystem.
data_args (BalanceArgs) – Filters for Data type block groups.
meta_args (BalanceArgs) – Filters for Metadata type block groups.
sys_args (BalanceArgs) – Filters for System type block groups.
force (bool) – When True, this allows converting to a profile with less redundancy.
resume (bool) – When True, all args are ignored and we ask the kernel to resume a previous balance operation.

Returns

A BalanceProgress object, describing the end result.

Return type

BalanceProgress

Raises

BalanceError, in case the balance operation does not exit in a clean way. Possible reasons include pausing or canceling the balance operation by a separate call to balance_ctl(), or having another balance operation already running.

btrfs.ioctl.balance_ctl(fd, cmd)[source]¶

Call the BTRFS_IOC_BALANCE_CTL ioctl.

Ask the kernel to pause or cancel a running balance operation.

Parameters

fd (int) – Open file descriptor to any inode in the filesystem.
cmd (int) – Balance control command.

Available commands (available as attribute of this module) are:

BALANCE_CTL_PAUSE
BALANCE_CTL_CANCEL

Raises: BalanceError if there is no balance in progress, or if pausing or cancelling it failed.

btrfs.ioctl.balance_progress(fd)[source]¶

Call the BTRFS_IOC_BALANCE_PROGRESS ioctl.

Ask the kernel about progress of a running balance operation.

Parameters: fd (int) – Open file descriptor to any inode in the filesystem.
Returns: A BalanceProgress object, describing the current state of the balance operation.
Return type: BalanceProgress
Raises: BalanceError if there is no balance in progress, or if inquiring about the progress failed.

btrfs.ioctl.set_received_subvol(fd, received_uuid, stransid, stime)[source]¶

Call the BTRFS_IOC_SET_RECEIVED_SUBVOL ioctl.

This function allows setting information about a sent subvolume after a receive operation.

Using this functionality it is possible to manually change relationships between sent and received subvolumes, removing safeguards and tricking btrfs into accepting certain incremental send and receive operations.

Use with caution, as it is also possible to cause subsequent btrfs receive to try doing wildly invalid things as result.

Parameters

fd (int) – An open file descriptor to the subvolume root directory (inode 256).
uuid (uuid.UUID) – The uuid (a python uuid object) we want to have set as received_uuid.
stransid (int) – Generation of the subvolume that was sent.
stime (btrfs.ctree.TimeSpec) – Time when the subvolume was sent.

Note that the stime field is not set at all by btrfs receive.

btrfs.ioctl.sync(fd)[source]¶

Call the BTRFS_IOC_SYNC ioctl.

The sync ioctl triggers delayed allocations, a btrfs transaction commit and the cleaner kthread.

Parameters: fd (int) – Open file descriptor to any inode in the filesystem.

Note

This function should usually be used implicitly by calling the sync() function on a btrfs.ctree.FileSystem object.

class btrfs.ioctl.FileDedupeRangeInfo(dest_fd, dest_offset)[source]¶

Bases: object

Object representation of struct file_dedupe_range_info.

Parameters

dest_fd (int) – An open file descriptor to a destination file which should get content deduped.
dest_offset (int) – Byte offset in the destination file from where the dedupe operation should happen.

After calling fideduperange(), the object will contain return values of the dedupe operation for this destination file:

Variables

bytes_deduped (int) – Amount of actual bytes at the given offset that could be deduped.
status (int) – One of the two status codes mentioned below (available as attribute of this module) or a negative number, which means it’s a standard errno integer value from the kernel.

FILE_DEDUPE_RANGE_SAME: The source range provided was identical to the data at the destination offset and could be deduped.
FILE_DEDUPE_RANGE_DIFFERS: Data in the destination was not matching, and the range could not be deduped.

property status_str¶: Pretty string representation for the status attribute.

btrfs.ioctl.fideduperange(fd, src_offset, src_length, range_infos)[source]¶

Call the FIDEDUPERANGE ioctl.

Parameters

fd (int) – Open file descriptor to a source file.
src_offset (int) – Offset in the source file where the source range starts.
src_length (int) – Length of the source range.
range_infos (list of FileDedupeRangeInfo) – Information about offsets in destination files.

class btrfs.ioctl.FeatureFlags(compat_flags, compat_ro_flags, incompat_flags)[source]¶

Bases: object

Object representation of struct btrfs_ioctl_feature_flags.

Quoting from linux kernel commit f2b636e80d:

Variables

compat_flags (int) – These hold the features that are compatible with older versions of btrfs.
compat_ro_flags (int) – These flags have features that are compatible with older versions of btrfs if the fs is mounted read only.
incompat_flags (int) – This has features that are incompatible with older versions of btrfs.

Compat flags are currently not used.

Known compat_ro flags (available as attribute of this module) are:

FEATURE_COMPAT_RO_FREE_SPACE_TREE
FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID

Known incompat_flags (available as attribute of this module) are:

FEATURE_INCOMPAT_MIXED_BACKREF
FEATURE_INCOMPAT_DEFAULT_SUBVOL
FEATURE_INCOMPAT_MIXED_GROUPS
FEATURE_INCOMPAT_COMPRESS_LZO
FEATURE_INCOMPAT_COMPRESS_ZSTD
FEATURE_INCOMPAT_BIG_METADATA
FEATURE_INCOMPAT_EXTENDED_IREF
FEATURE_INCOMPAT_RAID56
FEATURE_INCOMPAT_SKINNY_METADATA
FEATURE_INCOMPAT_NO_HOLES

Example:

>>> import btrfs
>>> with btrfs.FileSystem('/') as fs:
...     features = fs.features()
...
>>> btrfs.utils.pretty_print(features)
<btrfs.ioctl.FeatureFlags>
compat_flags: none
compat_ro_flags: free_space_tree|free_space_tree_valid
incompat_flags: mixed_backref|default_subvol|compress_lzo|big_metadata|extended_iref
>>> features.incompat_flags & btrfs.ioctl.FEATURE_INCOMPAT_MIXED_GROUPS
0
>>> features.incompat_flags & btrfs.ioctl.FEATURE_COMPAT_RO_FREE_SPACE_TREE
1

Note

An object of this type should be retrieved by calling the features() function on a btrfs.ctree.FileSystem object.

property compat_flags_str¶: Pretty string representation for the compat_flags attribute.

property compat_ro_flags_str¶: Pretty string representation for the compat_ro_flags attribute.

property incompat_flags_str¶: Pretty string representation for the incompat_flags attribute.

btrfs.ioctl.get_features(fd)[source]¶

Call the BTRFS_IOC_GET_FEATURES ioctl.

Parameters: fd (int) – Open file descriptor to any inode in the filesystem.
Returns: A FeatureFlags object.

Note

This function should usually be used implicitly by calling the features() function on a btrfs.ctree.FileSystem object.

btrfs.utils module¶

This module contains miscellanious collection of things, like the pretty_print() function which provides a quick readable textual dump of most of the object types in this library. Besides that, some functions to pretty print and parse size strings and some other stuff.

btrfs.utils.mounted_filesystem_paths()[source]¶

Discover mountpoints for online btrfs filesystems

Returns: Filesystem paths where btrfs filesystems are mounted.
Return type: List[str]

btrfs.utils.space_type_description(flags)[source]¶

Parameters: flags (int) – Space flags.
Returns: String representation of the space type only.
Return type: str

Example:

>>> btrfs.utils.space_type_description(0x14)
'Metadata'

btrfs.utils.space_profile_description(flags)[source]¶

Parameters: flags (int) – Space flags.
Returns: String representation of the space profile only.
Return type: str

Example:

>>> btrfs.utils.space_profile_description(0x14)
'RAID1'

btrfs.utils.space_flags_description(flags)[source]¶

Parameters: flags (int) – Space flags.
Returns: String representation of the space type and profile.
Return type: str

Example:

>>> btrfs.utils.space_flags_description(0x14)
'Metadata, RAID1'

btrfs.utils.pretty_size(size, unit=None, binary=True)[source]¶

Parameters

size (int) – Size in bytes.
unit (str) – Target unit to display the size in. One of ‘kMGTPE’.
binary (bool) – If True, use base 1024, else base 1000.

Example:

>>> btrfs.utils.pretty_size(1610612736, unit='G')
'1.50GiB'

btrfs.utils.parse_pretty_size(size_str)[source]¶

Parse pretty printed size strings.

This is the opposite of the pretty_size() function, but not 100%.

Parameters: size_str (str) – String literal to be parsed.
Raises: ValueError – If the input cannot be parsed as pretty size.

Example:

>>> btrfs.utils.parse_pretty_size('234MB')
234000000
>>> btrfs.utils.parse_pretty_size('234MiB')
245366784
>>> btrfs.utils.parse_pretty_size('234TB')
234000000000000
>>> btrfs.utils.parse_pretty_size('234TiB')
257285720899584
>>> btrfs.utils.parse_pretty_size('1048576')
1048576

btrfs.utils.flags_str(flags, flags_str_map)[source]¶

Generic helper to convert flags to a description.

This function is used by more specific helper functions below. You probably don’t need to call it directly.

Parameters

flags (int) – Flags.
flags_str_map (dict(int, str)) – Mapping from flag bit value to description.

btrfs.utils.block_group_flags_str(flags)[source]¶

Parameters: flags (int) – Block Group flags.
Returns: String representation of the block group type and profile.
Return type: str

Example:

>>> btrfs.utils.block_group_flags_str(0x14)
'METADATA|RAID1'

btrfs.utils.block_group_type_str(flags)[source]¶

Parameters: flags (int) – Block Group flags.
Returns: String representation of the block group type only.
Return type: str

Example:

>>> btrfs.utils.block_group_type_str(0x14)
'METADATA'

btrfs.utils.block_group_profile_str(flags)[source]¶

Parameters: flags (int) – Block Group flags.
Returns: String representation of the block group profile only.
Return type: str

Example:

>>> btrfs.utils.block_group_profile_str(0x14)
'RAID1'

btrfs.utils.extent_flags_str(flags)[source]¶

Parameters: flags (int) – ExtentItem flags.
Returns: String representation of the extent item flags.
Return type: str

Example:

>>> btrfs.utils.extent_flags_str(0x102)
'TREE_BLOCK|FULL_BACKREF'

btrfs.utils.inode_mode_str(mode)[source]¶

Parameters: mode (int) – File mode as number.
Returns: String representation of file mode in octal format.
Return type: str

Example:

>>> btrfs.utils.inode_mode_str(16877)
'040755'

btrfs.utils.inode_flags_str(flags)[source]¶

Parameters: flags (int) – InodeItem flags.
Returns: String representation of the inode item flags.
Rytpe: str

Example:

>>> btrfs.utils.inode_flags_str(72)
'NOCOMPRESS|IMMUTABLE'

btrfs.utils.dir_item_type_str(type_)[source]¶

Parameters: type (int) – DirItem type.
Returns: String representation of DirItem type.
Return type: str

Example:

>>> btrfs.utils.dir_item_type_str(4)
'BLKDEV'

btrfs.utils.root_item_flags_str(flags)[source]¶

Parameters: flags (int) – RootItem flags.
Returns: String representation of RootItem flags.
Return type: str

Example:

>>> btrfs.utils.root_item_flags_str(1)
'RDONLY'

btrfs.utils.compress_type_str(compression)[source]¶

Parameters: compression (int) – FileExtentItem compression type.
Returns: String representation of compression type.
Return type: str

Example:

>>> btrfs.utils.compress_type_str(3)
'zstd'

btrfs.utils.file_extent_type_str(type_)[source]¶

Parameters: type (int) – FileExtentItem type.
Returns: String representation of FileExtentItem type.
Return type: str

Example:

>>> btrfs.utils.file_extent_type_str(0)
'inline'

btrfs.utils.free_space_info_flags_str(flags)[source]¶

Parameters: flags (int) – FreeSpaceInfo flags.
Returns: String representation of FreeSpaceInfo flags.
Return type: str

Example:

>>> btrfs.utils.free_space_info_flags_str(1)
'bitmaps'

btrfs.utils.embedded_text_for_str(text)[source]¶

Parameters: text (bytes) – bytes from a name of data field of an object from the btrfs.ctree.DirItem family.
Returns: String representation of the bytes.
Return type: str

This function is not intended to be used for anything else than a convienient way of displaying filenames and xattr keys and values in the pretty printer.

Example:

>>> name_bytes = b'\xce\xbc\xce\xbf\xcf\x85\xcf\x84\xce\xbf\xce\xbd'
>>> btrfs.utils.embedded_text_for_str(name_bytes)
"utf-8 'μουτον'"

btrfs.utils.pretty_print(obj)[source]¶

The pretty printer dumps content of objects on the screen. It is mainly designed to work with objects from the btrfs library. It is also possible to provide a lists of objects, or a generator, or even nested structures.

Parameters: obj (anything goes) – An objects to pretty print, or a collection of them.

Example:

>>> import btrfs
>>> with btrfs.FileSystem('/') as fs:
...     btrfs.utils.pretty_print(fs.block_group(1687427219456))
...
<btrfs.ctree.BlockGroupItem (1687427219456 BLOCK_GROUP_ITEM 1073741824)>
vaddr: 1687427219456 (key objectid)
length: 1.00GiB (key offset)
flags: DATA
chunk_objectid: 256
used: 960.50MiB

btrfs.volumes module¶

btrfs.volumes.chunk_length_to_dev_extent_length(flags, num_stripes, chunk_length)[source]¶

Given information about a Chunk, calculate the length of DevExtent objects that store the Chunk data.

For example, a Data, RAID6 block group of 8GiB, distributed over 6 devices, will occupy 2GiB * (4+2) = 12 GiB physical allocated bytes since it has 4GiB of allocated bytes reserved for parity:

Example:

>>> btrfs.utils.pretty_size(
...     btrfs.volumes.chunk_length_to_dev_extent_length(
...         btrfs.ctree.BLOCK_GROUP_RAID6, 6, 8 * btrfs.utils.SZ_1G))
'2.00GiB'

btrfs.volumes.chunk_to_dev_extent_length(chunk)[source]¶

Given a Chunk object, calculate the length of DevExtent objects that store the chunk data.

Example:

>>> with btrfs.FileSystem('/') as fs:
...     chunk = list(fs.chunks(min_vaddr=3250585600, nr_items=1))[0]
...     print(chunk)
...     dev_extent_length = btrfs.volumes.chunk_to_dev_extent_length(chunk)
...     print("device extent length is {}".format(
...         btrfs.utils.pretty_size(dev_extent_length)))
...
chunk vaddr 3250585600 type DATA|RAID5 length 2147483648 num_stripes 3
device extent length is 1.00GiB

btrfs.volumes.dev_extent_length_to_chunk_length(flags, num_stripes, stripe_size)[source]¶

This function simply reverses the calculation of Chunk length to DevExtent length.

Example:

>>> btrfs.utils.pretty_size(
...     btrfs.volumes.dev_extent_length_to_chunk_length(
...         btrfs.ctree.BLOCK_GROUP_RAID6, 6, 2 * btrfs.utils.SZ_1G))
'8.00GiB'

btrfs.volumes.chunk_to_raw_parity_bytes(chunk)[source]¶

Given a Chunk object, calculate how many bytes are reserved for storing parity data for RAID56 profiles.

This number is relevant to understand how much raw disk space that is allocated but not used is actually not usable for data, because it’s reserved for parity.

Example:

>>> with btrfs.FileSystem('/mnt/tutorial') as fs:
...  chunk = list(fs.chunks(min_vaddr=3250585600, nr_items=1))[0]
...  print(chunk)
...  parity_bytes = btrfs.volumes.chunk_to_raw_parity_bytes(chunk)
...  print("amount of raw parity bytes: {}".format(
...      btrfs.utils.pretty_size(parity_bytes)))
...
chunk vaddr 3250585600 type DATA|RAID5 length 2147483648 num_stripes 3
amount of raw parity bytes: 1.00GiB

btrfs.volumes.block_group_profile_ncopies(flags)[source]¶

This function returns how many times the actual data is replicated on disk given block group flags as input. E.g. for RAID1 this is 2, but for RAID5, this is just 1. The actual data is stored once in case of RAID5, and the redundancy is done using parity blocks, not data itself.

Example:

>>> btrfs.volumes.block_group_profile_ncopies(btrfs.ctree.BLOCK_GROUP_RAID10)
2

btrfs package¶

Submodules¶

btrfs.crc32c module¶

btrfs.ctree module¶

btrfs.free_space_tree module¶

btrfs.fs_usage module¶

btrfs.ioctl module¶

btrfs.utils module¶

btrfs.volumes module¶

Module contents¶

Table of Contents

Related Topics

This Page