btrfs package
*************


Submodules
==========


btrfs.crc32c module
===================

btrfs.crc32c.crc32c(crc, data)

   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)

   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)

   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)

   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)

   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)

   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.BLOCK_GROUP_TREE_OBJECTID = 11

   Block group 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.ROOT_REF_KEY = 156

   Key type used by "RootRef"

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_RAID1C3 = 512

   Block Group RAID1C3 profile.

btrfs.ctree.BLOCK_GROUP_RAID1C4 = 1024

   Block Group RAID1C4 profile.

btrfs.ctree.BLOCK_GROUP_TYPE_MASK = 7

   All Block Group type bits (data, system, metadata).

btrfs.ctree.BLOCK_GROUP_PROFILE_MASK = 2040

   All Block Group profile bits (raid1, dup, etc…).

btrfs.ctree.COMPRESS_NONE = 0

   no compression at all

btrfs.ctree.COMPRESS_ZLIB = 1

   zlib compression

btrfs.ctree.COMPRESS_LZO = 2

   lzo compression

btrfs.ctree.COMPRESS_ZSTD = 3

   zstd compression

btrfs.ctree.qgroup_level(objectid)

   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)

   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

   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)

   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** (*Union**[**int**, **str**]*) – 64-bit object ID
        number or string representation.

      * **type_** (*Union**[**int**, **str**]*) – 8-bit type number or
        string representation.

      * **offset** (*Union**[**int**, **str**]*) – 64-bit offset
        number or string representation.

   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, 'DIR_ITEM', 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 allowed number. The actual value for a 64
   bit number is still 18446744073709551615, and for 8 bit that’s 255
   of course.

   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)

   Last but not least, the utils module contains the helper function
   "parse_key_string()" to dissect a full text key string:

   Example:

      >>> btrfs.utils.parse_key_string('(535 EXTENT_DATA 0)')
      Key(535, 108, 0)

   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)

   Bases: "Key"

   Object representation of struct *btrfs_disk_key*.

   Objects of this type are used in metadata search results.

class btrfs.ctree.FileSystem(path)

   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()

      Returns:
         General filesystem information.

      Return type:
         "btrfs.ioctl.FsInfo"

   dev_info(devid)

      Parameters:
         **devid** (*int*) – Device ID.

      Returns:
         Device information.

      Return type:
         "btrfs.ioctl.DevInfo"

   dev_stats(devid, reset=False)

      Parameters:
         * **devid** (*int*) – Device ID.

         * **reset** (*bool*) – Reset device error counters to zero.

      Returns:
         Device statistics.

      Return type:
         "btrfs.ioctl.DevStats"

   space_info()

      Returns:
         Space information

      Return type:
         List["btrfs.ioctl.SpaceInfo"]

   search(tree, min_key=None, max_key=None)

      Retrieve all metadata items within a specific range. This is
      basically a thin wrapper around the "search_v2()" with a bit
      limited functionality, but suited for almost all use cases when
      quickly searching around.

      Parameters:
         * **tree** (*int*) – The metadata tree we’re searching in.

         * **min_key** (*btrfs.ctree.Key*) – Minimum key value for
           items to return.

         * **max_key** (*btrfs.ctree.Key*) – Maximum key value for
           items to return.

      Returns:
         Any metadata item found in the search range, as sub class of
         "ItemData", helped by the "btrfs.ctree.classify()" function.

      Return type:
         Iterator["ItemData"]

   devices(min_devid=1, max_devid=18446744073709551615)

      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)

      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)

      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_groups(min_vaddr=0, max_vaddr=18446744073709551615, nr_items=None)

      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:
         Block Group items from the Extent Tree or Block Group Tree

      Return type:
         Iterator["BlockGroupItem"]

   block_group(vaddr, length=None)

      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)

      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()

      Returns:
         The top level subvolume with ID 5, a.k.a. *FS_TREE_OBJECTID*.

      Return type:
         "RootItem"

   subvolumes(min_id=256, max_id=18446744073709551360)

      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()

      Returns:
         ObjectID numbers of orphaned items in the Root tree.

      Return type:
         List[int]

   free_space_extents(min_vaddr=0, max_vaddr=18446744073709551615)

      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()

      Call the btrfs sync kernel function, causing a transaction
      commit.

   features()

      Returns:
         Filesystem Features.

      Return type:
         "btrfs.ioctl.FeatureFlags"

   mixed_groups()

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

      Return type:
         bool

   usage()

      Returns:
         Detailed filesystem usage information.

      Return type:
         "btrfs.fs_usage.FsUsage"

class btrfs.ctree.ItemData(header)

   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.SubItem

   Bases: "object"

class btrfs.ctree.DevItem(header, data)

   Bases: "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)

   Bases: "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 "BlockGroupItem", 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** (List["Stripe"]) – "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)

   Bases: "SubItem"

   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)

   Bases: "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)

   Bases: "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) or *BLOCK_GROUP_TREE_OBJECTID*
     (11)

   * Key objectid: Virtual address.

   * Key type: *BLOCK_GROUP_ITEM_KEY* (192)

   * Key offset: Block Group length.

   If the block_group_tree feature is enabled on the filesystem, these
   items can be found inside the Block Group Tree instead of the
   Extent Tree.

   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)

   Bases: "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_ino()" and "btrfs.ioctl.logical_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)

   Bases: "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)

   Bases: "ExtentDataRef"

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

class btrfs.ctree.SharedDataRef(header, data)

   Bases: "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)

   Bases: "SharedDataRef"

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

class btrfs.ctree.TreeBlockInfo(data)

   Bases: "SubItem"

   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)

   Bases: "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)

   Bases: "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)

   Bases: "TreeBlockRef"

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

class btrfs.ctree.SharedBlockRef(header)

   Bases: "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)

   Bases: "SharedBlockRef"

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

class btrfs.ctree.TimeSpec(data)

   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)

      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)

   Bases: "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)

   Bases: "ItemData", "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)

      Not implemented.

class btrfs.ctree.InodeRef(data, pos)

   Bases: "SubItem"

   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)

   Bases: "ItemData", "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)

      Not implemented.

class btrfs.ctree.InodeExtref(data, pos)

   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)

   Bases: "ItemData", "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)

      Not implemented.

class btrfs.ctree.XAttrItemList(header, data)

   Bases: "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)

   Bases: "SubItem"

   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)

   Bases: "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)

   Bases: "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)

   Bases: "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:
      * **objectid** (*int*) – Tree ID. (taken from the objectid field
        of the item key)

      * **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.RootRef(header, data)

   Bases: "ItemData"

   Object representation of *btrfs_root_ref*.

   The "RootRef" item lives in the root tree, a.k.a. the ‘tree of
   trees’.  It contains information about the place where a subvolume
   is located inside another subvolume.

   * Tree: *ROOT_TREE_OBJECTID* (1).

   * Key objectid: Parent tree ID.

   * Key type: *ROOT_REF_KEY* (156)

   * Key offset: Tree ID of the subvolume.

   Variables:
      * **parent_tree** (*int*) – Containing Tree ID. (taken from the
        objectid field of the item key)

      * **tree** (*int*) – Tree ID of the subvolume. (taken from the
        offset field of the item key)

      * **dirid** (*int*) – Inode number of the containing directory.

      * **sequence** (*int*) – Directory index number in the
        containing directory.

      * **name_len** (*int*) – Amount of bytes used to store the
        filename.

      * **name** (*bytes*) – Filename as bytes.

   When combining this information with a call to the ino_lookup
   ioctl, we can quickly figure out the relative path inside the
   containing subvolume.

   E.g. for (259 ROOT_REF 1052) in the root tree, with dirid 20197,
   sequence 65 and name baz, we can do btrfs.ioctl.ino_lookup(fd, 259,
   20197). The result is e.g. name_bytes=b’foo/bar/’, so the location
   inside the containing subvolume is foo/bar/baz.

   When doing such a thing recursively, the same output as seen in
   btrfs sub list -a can be produced.

   property name_str

      Pretty string representation for the name attribute.

class btrfs.ctree.FileExtentItem(header, data)

   Bases: "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:
      * **objectid** (*int*) – The inode number of the file. (taken
        from the objectid field of the item key).

      * **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)

   Bases: "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)

   Bases: "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)

   Bases: "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)

      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.OrphanItem(header, _)

   Bases: "ItemData"

   Object representation for orphan item information from the root
   tree.

   * Tree: *ROOT_TREE_OBJECTID* (1).

   * Key objectid: *ORPHAN_OBJECTID* (-5).

   * Key type: *ORPHAN_ITEM_KEY* (48).

   * Key offset: objectid of the item in the root tree that is
     orphaned and
        needs to be cleaned up.

   Variables:
      **objectid** (*int*) – objectid of the item in the root tree
      that is orphaned and needs to be cleaned up. (taken from the
      offset field of the item key)

class btrfs.ctree.NotImplementedItem(header, data)

   Bases: "ItemData"

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

class btrfs.ctree.UnknownItem(header, data)

   Bases: "ItemData"

   Placeholder object for metadata item types that are unrecognized.

btrfs.ctree.classify(header, data)

   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
============================

class btrfs.free_space_tree.FreeSpaceExtent(vaddr, length)

   Bases: "object"

   Helper object for listing free space tree extents.

   In the free space tree, information about free space can be stored
   as free space extent item, in which case it has information about a
   single gap of free space. Alternatively, it can be stored in a
   compacted format, as free space bitmap. In that case, to find out
   where the tiny gaps of free space are located, the bitmap needs to
   be unpacked.

   This object serves as a helper when doing so. It 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.

   Variables:
      * **vaddr** (*int*) – Logical address of the start of the free
        space extent.

      * **length** (*int*) – Length of the free space extent.


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)

   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)

   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)

   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)

   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)

   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)

   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, data_metadata_ratio=None, target_profile_metadata=None, target_profile_data=None, target_profile_mixed=None)

   Bases: "object"

   Detailed usage information for a file system.

   When creating an object of this type, the first argument, fs, is
   mandatory. The other arguments can be used to influence the
   simulation to predict free space and unallocatable space with
   explicit hints instead of using information from the current
   filesystem, This is used by the space-calculator program to run the
   simulation starting with a completely empty filesystem.

   Parameters:
      * **fs** (*btrfs.ctree.FileSystem*) – Filesystem to examine.

      * **data_metadata_ratio** (*int*) – Data to metadata ratio to
        use when running the simulation to predict free space and
        unallocatable space.

      * **target_profile_metadata** (*int*) – Explicitly set metadata
        profile to use for new allocations when running the simulation
        to predict free and unallocatable space (not for a mixed
        filesystem).

      * **target_profile_data** (*int*) – Explicitly set data profile
        to use for new allocations when running the simulation to
        predict free and unallocatable space (not for a mixed
        filesystem).

      * **target_profile_mixed** (*int*) – Explicitly set metadata and
        data profile to use for new allocations when running the
        simulation to predict free and unallocatable space (only for a
        mixed filesystem).

   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)

   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)

   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)

   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)

   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)

   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)

   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*.

   space_slots

      Alias for field number 0

   total_spaces

      Alias for field number 1

class btrfs.ioctl.SpaceInfo(buf, pos)

   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)

   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*.

   len

      Alias for field number 4

   objectid

      Alias for field number 1

   offset

      Alias for field number 2

   transid

      Alias for field number 0

   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)

   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)

   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.

   inum

      Alias for field number 0

   offset

      Alias for field number 1

   root

      Alias for field number 2

btrfs.ioctl.logical_ino(fd, vaddr, bufsize=4096)

   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_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(*args, **kwargs)

   Deprecated since version 15: Backwards compatibility function. Use
   "logical_ino()" instead.

btrfs.ioctl.logical_ino_v2(fd, vaddr, bufsize=4096, ignore_offset=False)

   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_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.

btrfs.ioctl.logical_to_ino_v2(*args, **kwargs)

   Deprecated since version 15: Backwards compatibility function. Use
   "logical_ino_v2()" instead.

class btrfs.ioctl.InoLookupResult(treeid, name_bytes)

   Bases: "tuple"

   Helper object for *INO_LOOKUP* ioctls results.

   name_bytes

      Alias for field number 1

   treeid

      Alias for field number 0

btrfs.ioctl.ino_lookup(fd, treeid=0, objectid=256)

   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)

   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)

   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)

   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*) – One of the balance state values, see
        below. This field is only set to a non-zero value when the
        error is raised by the "balance_v2()" function.

      * **errno** (*int*) – An errno errorcode that was returned when
        executing the ioctl call in one of the balance related
        functions.

      * **msg** (*str*) – A message describing the error condition.

   Refer to the docucumentation of the different functions who can
   raise this error for more information about combinations of the
   state and errno numbers that can be expected, and about what they
   mean.

   property errno

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

   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.

   When a "BalanceError" is raised, the following combinations of
   state and errno attributes can be expected:

   * errno *ECANCELED*, state *BALANCE_STATE_PAUSE_REQ*: The balance
     operation was paused because of a user request.

   * errno *ECANCELED*, state *BALANCE_STATE_CANCEL_REQ*: The balance
     operation was aborted because of a user request.

   * errno *ENOTCONN*: A resume was requested, but there was no
     previously paused balance operation.

   * errno *EINPROGRESS*: A resume or start was requested, but there
     is already a balance operation in progress.

btrfs.ioctl.balance_ctl(fd, cmd)

   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.

   When a "BalanceError" is raised, the following values for the errno
   attribute can be expected:

   * errno *ENOTCONN*: There is no balance operation in progress, so
     it cannot be paused or cancelled.

btrfs.ioctl.balance_progress(fd)

   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.

   When a "BalanceError" is raised, the following values for the errno
   attribute can be expected:

   * errno *ENOTCONN*: There is no balance operation in progress.

btrfs.ioctl.set_received_subvol(fd, received_uuid, stransid, stime)

   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)

   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)

   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)

   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)

   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

   * FEATURE_COMPAT_RO_BLOCK_GROUP_TREE

   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.compat_ro_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)

   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.ioctl.DEFRAG_RANGE_COMPRESS = 1

   Flag to enable (re)compression functionality

btrfs.ioctl.DEFRAG_RANGE_START_IO = 2

   Flag to more quickly start writing back data

btrfs.ioctl.defrag_range(fd, start=0, length=18446744073709551615, flags=0, extent_thresh=0, compress_type=0)

   Call the *BTRFS_IOC_DEFRAG_RANGE* ioctl.

   Using the defrag_range function, we can:

   * Defragment (parts of) files (when fd points to a regular file).

   * Defragment subvolume metadata (when fd points to a directory).

   * (Re)compress (parts of) files to a certain compression type.

   Parameters:
      * **fd** (*int*) – Open file descriptor to a regular file or a
        directory.

      * **start** (*int*) – Offset to start the defragmentation at.
        Defaults to 0.

      * **length** (*int*) – Amount of bytes to defrag, from the start
        position. Defaults to 2**64-1.

      * **flags** (*int*) – Flags, mainly to activate the
        (re)compression functionality. See below for more information.
        By default, no flags are set.

      * **extent_thresh** (*int*) – Skip extents larger than this
        value in bytes. Warning: this value might be ignored by kernel
        code, especially for small-ish values. Defaults to 0, which in
        turn means it will be set to the kernel code default value of
        256kiB.

      * **compress_type** (*int*) – Compression type to use when
        (re)compressing file content. Use one of the *COMPRESS_**
        values from the "btrfs.ctree" module, e.g.
        *btrfs.ctree.COMPRESS_ZSTD*.

   Example:

      >>> # In the first 40MiB of the file, try to combine together all
      >>> # extents that have a length of less than a MiB.
      >>> MiB = 2**20
      >>> fd = os.open('defrag_me', os.O_RDONLY)
      >>> btrfs.ioctl.defrag_range(fd, start=0, length=40*MiB, extent_thresh=MiB)

   About using defrag to (re)compress file content:

   * To turn on the (re)compression functionality, provide
     *DEFRAG_RANGE_COMPRESS* as flags. (Internally, this also sets the
     *DEFRAG_RANGE_START_IO* flag and forces extent_thresh to
     2**64-1.)

   * Additionally, specify the target type as compression_type.

   * It is not possible to decompress existing compressed data using
     this function. This is because only a compress_type value greater
     than 0 is considered, while the kernel default value is to use
     ZLIB. IOW, providing value 0 selects ZLIB instead.

   Example:

      >>> MiB = 2**20
      >>> fd = os.open('compress_me', os.O_RDONLY)
      >>> btrfs.ioctl.defrag_range(fd, start=50*MiB, length=25*MiB,
      ...                          flags=btrfs.ioctl.DEFRAG_RANGE_COMPRESS,
      ...                          compress_type=btrfs.ctree.COMPRESS_ZSTD)

   Note: the parameter ‘length’ is called ‘len’ in kernel code, but
   ‘len’ is a reserved keyword in Python.


btrfs.utils module
==================

This module contains miscellaneous 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()

   Discover mountpoints for online btrfs filesystems

   Returns:
      Filesystem paths where btrfs filesystems are mounted.

   Return type:
      List[str]

btrfs.utils.space_type_description(flags)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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)

   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_)

   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)

   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)

   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_)

   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)

   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)

   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
   convenient 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.parse_tree_name(name)

   Convert a tree name to an actual root tree objectid number

   Parameters:
      **name** (*string*) – tree name with optional _tree suffix or
      number formatted as string

   Returns:
      Tree objectid that is valid for the root tree

   Return type:
      int

   Example:

      >>> btrfs.utils.parse_tree_name('EXTENT_TREE')
      2
      >>> btrfs.utils.parse_tree_name('extent_tree')
      2
      >>> btrfs.utils.parse_tree_name('extent')
      2
      >>> btrfs.utils.parse_tree_name('2')
      2
      >>> btrfs.utils.parse_tree_name(2)
      2

btrfs.utils.parse_key_string(key_str)

   Create a Key object from a pretty printed string representation

   Parameters:
      **key_str** (*string*) – String representation of a key, e.g.
      ‘(31832 INODE_REF 31798)’

   Returns:
      A Key object with the parsed values set

   Return type:
      "Key"

   Raises:
      "ValueError" if the key string is an invalid key representation

   The parentheses around the key triplet are optional.

   Example:

      >>> btrfs.utils.parse_key_string('(31832 INODE_REF 31798)')
      Key(31832, 12, 31798)
      >>> btrfs.utils.parse_key_string('(535 EXTENT_DATA 0)')
      Key(535, 108, 0)

btrfs.utils.pretty_print(obj)

   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 object 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.utils.str_print(obj)

   Print the usual str() of an object, but look inside to see if more
   ItemData objects are hidden there. If so, also print their str().

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

   Example:

      >>> with btrfs.FileSystem('/') as fs:
      ...      btrfs.utils.str_print(fs.block_group(63381176320))
      ...
      block group vaddr 63381176320 length 1073741824 flags DATA used 1073741824 used_pct 100


btrfs.volumes module
====================

btrfs.volumes.chunk_length_to_dev_extent_length(flags, num_stripes, chunk_length)

   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)

   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)

   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)

   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)

   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


Module contents
===============
