# Copyright (C) 2016 Hans van Kranenburg # # This file is part of the python-btrfs module. # # python-btrfs is free software: you can redistribute it and/or modify # it under the terms of the GNU Lesser General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # python-btrfs is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public License # along with python-btrfs. If not, see . """ 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 :class:`btrfs.ctree.FileSystem` object. """ from collections import namedtuple import array import btrfs import errno import fcntl import os import platform import struct import uuid ULLONG_MAX = (1 << 64) - 1 ULONG_MAX = (1 << 32) - 1 BTRFS_IOCTL_MAGIC = 0x94 _IOC_NRBITS = 8 _IOC_TYPEBITS = 8 # Here's an educated guess of what to do. A more fool-proof way of doing this would # be to make a compiled extension instead, delivering the right values, but... # that hasn't been done yet! arch = platform.machine() if arch in ('x86_64', 'i686', 'i386', 'i586', 'amd64', 'ia64', 'm68k', 'i486') \ or arch.startswith(('aarch64', 'arm', 's390')): _IOC_SIZEBITS = 14 _IOC_DIRBITS = 2 _IOC_NONE = 0 _IOC_WRITE = 1 _IOC_READ = 2 elif arch in ('powerpc', 'alpha') or arch.startswith(('sparc', 'ppc', 'mips')): _IOC_SIZEBITS = 13 _IOC_DIRBITS = 3 _IOC_NONE = 1 _IOC_READ = 2 _IOC_WRITE = 4 elif arch == 'hppa' or arch.startswith('parisc'): _IOC_SIZEBITS = 14 _IOC_DIRBITS = 2 _IOC_NONE = 0 _IOC_WRITE = 2 _IOC_READ = 1 else: raise Exception("Unsupported machine type {}, please report as bug.".format(arch)) _IOC_NRSHIFT = 0 _IOC_TYPESHIFT = _IOC_NRSHIFT + _IOC_NRBITS _IOC_SIZESHIFT = _IOC_TYPESHIFT + _IOC_TYPEBITS _IOC_DIRSHIFT = _IOC_SIZESHIFT + _IOC_SIZEBITS def _IOC(_dir, _type, nr, size): return (_dir << _IOC_DIRSHIFT) | (_type << _IOC_TYPESHIFT) | \ (nr << _IOC_NRSHIFT) | (size << _IOC_SIZESHIFT) def _IO(_type, nr): return _IOC(_IOC_NONE, _type, nr, 0) def _IOR(_type, nr, _struct): return _IOC(_IOC_READ, _type, nr, _struct.size) def _IOW(_type, nr, _struct): return _IOC(_IOC_WRITE, _type, nr, _struct.size) def _IOWR(_type, nr, _struct): return _IOC(_IOC_READ | _IOC_WRITE, _type, nr, _struct.size) DEVICE_PATH_NAME_MAX = 1024 ioctl_fs_info_args = struct.Struct('=QQ16sLLL980x') IOC_FS_INFO = _IOR(BTRFS_IOCTL_MAGIC, 31, ioctl_fs_info_args) class FsInfo(object): """Object representation of struct `btrfs_ioctl_fs_info_args`. :ivar int max_id: Highest device id of currently attached devices. :ivar int num_devices: Amount of devices attached to the filesystem. :ivar uuid.UUID fsid: Filesystem ID. :ivar int nodesize: B-tree node size (same as leaf size). :ivar int sectorsize: Smallest allocatable block size in bytes for storing data. :ivar int clone_alignment: Expected alignment of arguments for clone and deduplication ioctls. .. note:: An object of this type should be retrieved by calling the :func:`~btrfs.ctree.FileSystem.fs_info` function on a :class:`btrfs.ctree.FileSystem` object. """ def __init__(self, buf): self.max_id, self.num_devices, fsid_bytes, self.nodesize, self.sectorsize, \ self.clone_alignment = ioctl_fs_info_args.unpack(buf) self.fsid = uuid.UUID(bytes=fsid_bytes) def __str__(self): return "max_id {0} num_devices {1} fsid {2} nodesize {3} sectorsize {4} " \ "clone_alignment {5}".format(self.max_id, self.num_devices, self.fsid, self.nodesize, self.sectorsize, self.clone_alignment) @staticmethod def _pretty_properties(): return [ (btrfs.utils.pretty_size, 'nodesize'), (btrfs.utils.pretty_size, 'sectorsize'), (btrfs.utils.pretty_size, 'clone_alignment'), ] def fs_info(fd): """Call the `BTRFS_IOC_FS_INFO` ioctl. :param int fd: Open file descriptor to any inode in the filesystem. :returns: A :class:`FsInfo` object. .. note:: This function should usually be used implicitly by calling the :func:`~btrfs.ctree.FileSystem.fs_info` function on a :class:`btrfs.ctree.FileSystem` object. """ buf = bytearray(ioctl_fs_info_args.size) fcntl.ioctl(fd, IOC_FS_INFO, buf) return FsInfo(buf) ioctl_dev_info_args = struct.Struct('=Q16sQQ3032x{0}s'.format(DEVICE_PATH_NAME_MAX)) IOC_DEV_INFO = _IOWR(BTRFS_IOCTL_MAGIC, 30, ioctl_dev_info_args) class DevInfo(object): """Object representation of struct btrfs_ioctl_dev_info_args. :ivar int devid: Device ID. :ivar uuid.UUID uuid: Device UUID. :ivar int bytes_used: Amount of allocated bytes on the device. :ivar int total_bytes: Device size in bytes. :ivar str path: Path to the device node to access this device directly. .. note:: An object of this type should be retrieved by calling the :func:`~btrfs.ctree.FileSystem.dev_info` function on a :class:`btrfs.ctree.FileSystem` object. """ def __init__(self, buf): self.devid, uuid_bytes, self.bytes_used, self.total_bytes, path_bytes = \ ioctl_dev_info_args.unpack(buf) self.path = path_bytes.split(b'\0', 1)[0].decode() self.uuid = uuid.UUID(bytes=uuid_bytes) def __str__(self): return "devid {0} uuid {1} bytes_used {2} total_bytes {3} path {4}".format( self.devid, self.uuid, self.bytes_used, self.total_bytes, self.path) @staticmethod def _pretty_properties(): return [ (btrfs.utils.pretty_size, 'bytes_used'), (btrfs.utils.pretty_size, 'total_bytes'), ] def dev_info(fd, devid): """Call the `BTRFS_IOC_DEV_INFO` ioctl. :param int fd: Open file descriptor to any inode in the filesystem. :param int devid: Device ID of the device to retrieve information about. :returns: A :class:`DevInfo` object. .. note:: This function should usually be used implicitly by calling the :func:`~btrfs.ctree.FileSystem.dev_info` function on a :class:`btrfs.ctree.FileSystem` object. """ buf = bytearray(ioctl_dev_info_args.size) ioctl_dev_info_args.pack_into(buf, 0, devid, b'', 0, 0, b'') fcntl.ioctl(fd, IOC_DEV_INFO, buf) return DevInfo(buf) ioctl_get_dev_stats = struct.Struct('=QQQ5Q968x') IOC_GET_DEV_STATS = _IOWR(BTRFS_IOCTL_MAGIC, 52, ioctl_get_dev_stats) class DevStats(object): """Object representation of struct btrfs_ioctl_get_dev_stats. :ivar int devid: Device ID. :ivar int write_errs: Amount of write errors. :ivar int read_errs: Amount of read errors. :ivar int flush_errs: Amount of flush errors. :ivar int generation_errs: Amount of metadata tree generation mismatch errors. :ivar int corruption_errs: Amount of checksum failures. .. note:: An object of this type should be retrieved by calling the :func:`~btrfs.ctree.FileSystem.dev_stats` function on a :class:`btrfs.ctree.FileSystem` object. """ def __init__(self, buf): self.devid, self.nr_items, self.flags, self.write_errs, self.read_errs, \ self.flush_errs, self.corruption_errs, self.generation_errs = \ ioctl_get_dev_stats.unpack_from(buf) @property def counters(self): return { 'write_errs': self.write_errs, 'read_errs': self.read_errs, 'flush_errs': self.flush_errs, 'corruption_errs': self.corruption_errs, 'generation_errs': self.generation_errs, } def __str__(self): return "devid {0} write_errs {1} read_errs {2} flush_errs {3} corruption_errs {4} " \ "generation_errs {5}".format(self.devid, self.write_errs, self.read_errs, self.flush_errs, self.corruption_errs, self.generation_errs) def dev_stats(fd, devid, reset=False): """Call the `BTRFS_IOC_DEV_STATS` ioctl. :param int fd: Open file descriptor to any inode in the filesystem. :param int devid: Device ID of the device to retrieve information about. :param bool reset: If true, counters are reset to zero. :returns: A :class:`DevStats` object. .. note:: This function should usually be used implicitly by calling the :func:`~btrfs.ctree.FileSystem.dev_stats` function on a :class:`btrfs.ctree.FileSystem` object. """ buf = bytearray(ioctl_get_dev_stats.size) ioctl_get_dev_stats.pack_into(buf, 0, devid, 5, int(reset), 0, 0, 0, 0, 0) fcntl.ioctl(fd, IOC_GET_DEV_STATS, buf) return DevStats(buf) ioctl_space_args = struct.Struct('=2Q') ioctl_space_info = struct.Struct('=3Q') IOC_SPACE_INFO = _IOWR(BTRFS_IOCTL_MAGIC, 20, ioctl_space_args) #: Object representation of struct `btrfs_ioctl_space_args`. SpaceArgs = namedtuple('SpaceArgs', ['space_slots', 'total_spaces']) class SpaceInfo(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'. :ivar int flags: Block group type and profile, e.g. `Data, RAID1`. :ivar int total_bytes: Total amount of allocated bytes for this space. :ivar int used_bytes: Total amount of bytes used. .. note:: A list of objects of this type should be retrieved by calling the :func:`~btrfs.ctree.FileSystem.space_info` function on a :class:`btrfs.ctree.FileSystem` object. """ def __init__(self, buf, pos): self.flags, self.total_bytes, self.used_bytes = ioctl_space_info.unpack_from(buf, pos) self._type = self.flags & \ (btrfs.ctree.BLOCK_GROUP_TYPE_MASK | btrfs.ctree.SPACE_INFO_GLOBAL_RSV) self._profile = self.flags & btrfs.ctree.BLOCK_GROUP_PROFILE_MASK @property def type(self): """Only block group type, e.g. `Data`, from flags.""" return self._type @property def profile(self): """Only block group profile, e.g. `RAID1`, from flags.""" return self._profile def __str__(self): return "{}: total={}, used={}".format( self.flags_str, self.total_bytes_str, self.used_bytes_str) @staticmethod def _pretty_properties(): return [ (btrfs.utils.space_flags_description, 'flags'), (btrfs.utils.space_type_description, 'type'), (btrfs.utils.space_profile_description, 'profile'), (btrfs.utils.pretty_size, 'total_bytes'), (btrfs.utils.pretty_size, 'used_bytes'), ] def _space_args(fd): buf = bytearray(ioctl_space_args.size) fcntl.ioctl(fd, IOC_SPACE_INFO, buf) return SpaceArgs(*ioctl_space_args.unpack(buf)) def space_info(fd): """Call the `BTRFS_IOC_SPACE_INFO` ioctl. :param int fd: Open file descriptor to any inode in the filesystem. :returns: A list of :class:`SpaceInfo` objects. .. note:: This function should usually be used implicitly by calling the :func:`~btrfs.ctree.FileSystem.space_info` function on a :class:`btrfs.ctree.FileSystem` object. """ args = _space_args(fd) buf_size = ioctl_space_args.size + ioctl_space_info.size * args.total_spaces buf = bytearray(buf_size) ioctl_space_args.pack_into(buf, 0, args.total_spaces, 0) fcntl.ioctl(fd, IOC_SPACE_INFO, buf) return [SpaceInfo(buf, pos) for pos in range(ioctl_space_args.size, buf_size, ioctl_space_info.size)] ioctl_search_key = struct.Struct('=Q6QLLL4x32x') ioctl_search_args = struct.Struct('{0}{1}x'.format( btrfs.ctree._struct_format(ioctl_search_key), 4096 - ioctl_search_key.size)) ioctl_search_header = struct.Struct('=3Q2L') IOC_TREE_SEARCH = _IOWR(BTRFS_IOCTL_MAGIC, 17, ioctl_search_args) #: Object representation of struct `btrfs_ioctl_search_header`. SearchHeader = namedtuple('SearchHeader', ['transid', 'objectid', 'offset', 'type', 'len']) def search(fd, tree, min_key=None, max_key=None, min_transid=0, max_transid=ULLONG_MAX, nr_items=None): """Call the `BTRFS_IOC_TREE_SEARCH` ioctl. The `TREE_SEARCH` ioctl allow us to directly read btrfs metadata. :param int fd: Open file descriptor to any inode in the filesystem. :param int tree: 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. :param btrfs.ctree.Key min_key: Minimum key value for items to return. :param btrfs.ctree.Key max_key: Maximum key value for items to return. :param int min_transid: Minimum transaction id for the metadata leaf to have items included. Defaults to 0. :param int max_transid: Maximum transaction id for the metadata leaf to have items included. Defaults to 2**64-1. :param int nr_items: 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. :rtype: Iterator[Tuple[:class:`SearchHeader`, :class:`memoryview`]] """ return _search(fd, tree, min_key, max_key, min_transid, max_transid, nr_items, _v2=False) _ioctl_search_args_v2 = [ ioctl_search_key, struct.Struct('=Q') ] ioctl_search_args_v2 = struct.Struct('=' + ''.join([btrfs.ctree._struct_format(s)[1:] for s in _ioctl_search_args_v2])) IOC_TREE_SEARCH_V2 = _IOWR(BTRFS_IOCTL_MAGIC, 17, ioctl_search_args_v2) def search_v2(fd, tree, min_key=None, max_key=None, min_transid=0, max_transid=ULLONG_MAX, 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. :param int fd: Open file descriptor to any inode in the filesystem. :param int tree: 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. :param btrfs.ctree.Key min_key: Minimum key value for items to return. :param btrfs.ctree.Key max_key: Maximum key value for items to return. :param int min_transid: Minimum transaction id for the metadata leaf to have items included. Defaults to 0. :param int max_transid: Maximum transaction id for the metadata leaf to have items included. Defaults to 2**64-1. :param int nr_items: Maximum amount of items to fetch. Defaults to no limit. :param int buf_size: 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. :rtype: Iterator[Tuple[:class:`SearchHeader`, :class:`memoryview`]] """ return _search(fd, tree, min_key, max_key, min_transid, max_transid, nr_items, buf_size, _v2=True) def _search(fd, tree, min_key=None, max_key=None, min_transid=0, max_transid=ULLONG_MAX, nr_items=None, buf_size=None, _v2=True): if min_key is None: min_key = btrfs.ctree.Key(0, 0, 0) if max_key is None: max_key = btrfs.ctree.Key(ULLONG_MAX, 255, ULLONG_MAX) if nr_items is not None: wanted_nr_items = nr_items result_nr_items = -1 else: wanted_nr_items = ULONG_MAX while True: if _v2: buf = bytearray(ioctl_search_args_v2.size + buf_size) else: buf = bytearray(4096) buf_view = memoryview(buf) pos = 0 ioctl_search_key.pack_into(buf, pos, tree, min_key.objectid, max_key.objectid, min_key.offset, max_key.offset, min_transid, max_transid, min_key.type, max_key.type, wanted_nr_items) pos += ioctl_search_key.size if _v2: _ioctl_search_args_v2[1].pack_into(buf, pos, buf_size) pos += _ioctl_search_args_v2[1].size fcntl.ioctl(fd, IOC_TREE_SEARCH_V2, buf) else: fcntl.ioctl(fd, IOC_TREE_SEARCH, buf) result_nr_items = ioctl_search_key.unpack_from(buf, 0)[9] if result_nr_items > 0: for i in range(result_nr_items): header = SearchHeader(*ioctl_search_header.unpack_from(buf, pos)) pos += ioctl_search_header.size yield header, buf_view[pos:pos+header.len] if nr_items is not None: wanted_nr_items -= 1 if wanted_nr_items == 0: return pos += header.len min_key = btrfs.ctree.Key(header.objectid, header.type, header.offset) min_key += 1 else: return if min_key > max_key: return data_container = struct.Struct('=LLLL') ioctl_logical_ino_args = struct.Struct('=QQ32xQ') IOC_LOGICAL_INO = _IOWR(BTRFS_IOCTL_MAGIC, 36, ioctl_logical_ino_args) inum_offset_root = struct.Struct('=QQQ') #: Inode helper object for `LOGICAL_INO` ioctls results. Inode = namedtuple('Inode', ['inum', 'offset', 'root']) def 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) :param int fd: Open file descriptor to any inode in the filesystem. :param int vaddr: Virtual address to search for. :param int bufsize: Size in bytes. Default value is 4kiB (4096 bytes). Maximum allowed value is 64kiB (65536 bytes). :returns: A list of :class:`Inode` objects and the amount of extra bytes for the provided buffer that would be needed to be able to return all results found. :rtype: Tuple[List[:class:`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. """ return _logical_ino(fd, vaddr, bufsize, _v2=False) def logical_to_ino(*args, **kwargs): """ .. deprecated:: 15 Backwards compatibility function. Use :func:`~btrfs.ioctl.logical_ino` instead. """ return logical_ino(*args, **kwargs) ioctl_logical_ino_args_v2 = struct.Struct('=QQ24xQQ') IOC_LOGICAL_INO_V2 = _IOWR(BTRFS_IOCTL_MAGIC, 59, ioctl_logical_ino_args) LOGICAL_INO_ARGS_IGNORE_OFFSET = 1 << 0 def 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) :param int fd: Open file descriptor to any inode in the filesystem. :param int vaddr: Virtual address to search for. :param int bufsize: Size in bytes. Default value is 4kiB (4096 bytes). Maximum allowed value is 16MiB (16777216 bytes). :param bool ignore_offset: 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 :class:`Inode` objects and the amount of extra bytes for the provided buffer that would be needed to be able to return all results found. :rtype: Tuple[List[:class:`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. """ return _logical_ino(fd, vaddr, bufsize, ignore_offset, _v2=True) def logical_to_ino_v2(*args, **kwargs): """ .. deprecated:: 15 Backwards compatibility function. Use :func:`~btrfs.ioctl.logical_ino_v2` instead. """ return logical_ino_v2(*args, **kwargs) def _logical_ino(fd, vaddr, bufsize=4096, ignore_offset=False, _v2=True): if _v2: bufsize = min(bufsize, 16777216) else: bufsize = min(bufsize, 65536) inodes_buf = array.array(u'B', bytearray(bufsize)) inodes_ptr = inodes_buf.buffer_info()[0] args = bytearray(ioctl_logical_ino_args.size) if _v2: flags = 0 if ignore_offset: flags |= LOGICAL_INO_ARGS_IGNORE_OFFSET ioctl_logical_ino_args_v2.pack_into(args, 0, vaddr, bufsize, flags, inodes_ptr) fcntl.ioctl(fd, IOC_LOGICAL_INO_V2, args) else: ioctl_logical_ino_args.pack_into(args, 0, vaddr, bufsize, inodes_ptr) fcntl.ioctl(fd, IOC_LOGICAL_INO, args) bytes_left, bytes_missing, elem_cnt, elem_missed = data_container.unpack_from(inodes_buf, 0) inodes = [] pos = data_container.size for elem in range(int(elem_cnt//3)): inodes.append(Inode(*inum_offset_root.unpack_from(inodes_buf, pos))) pos += inum_offset_root.size return inodes, bytes_missing INO_LOOKUP_PATH_MAX = 4080 ioctl_ino_lookup_args = struct.Struct('=QQ{}s'.format(INO_LOOKUP_PATH_MAX)) IOC_INO_LOOKUP = _IOWR(BTRFS_IOCTL_MAGIC, 18, ioctl_ino_lookup_args) #: Helper object for `INO_LOOKUP` ioctls results. InoLookupResult = namedtuple('InoLookupResult', ['treeid', 'name_bytes']) def ino_lookup(fd, treeid=0, objectid=btrfs.ctree.FIRST_FREE_OBJECTID): """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/') :param int fd: File descriptor pointing to an inode. :param int treeid: Subvolume tree to search in, or 0 to use the subvolume that contains the inode that fd points to. :param int objectid: Inode number to get the path for. :returns: An :class:`InoLookupResult` tuple with subvolume tree id and filesystem path as bytes. :rtype: :class:`InoLookupResult` """ args = bytearray(ioctl_ino_lookup_args.size) ioctl_ino_lookup_args.pack_into(args, 0, treeid, objectid, b'') fcntl.ioctl(fd, IOC_INO_LOOKUP, args) treeid, _, name_bytes = ioctl_ino_lookup_args.unpack_from(args, 0) return InoLookupResult(treeid, name_bytes.split(b'\0', 1)[0]) BALANCE_ARGS_PROFILES = 1 << 0 BALANCE_ARGS_USAGE = 1 << 1 BALANCE_ARGS_DEVID = 1 << 2 BALANCE_ARGS_DRANGE = 1 << 3 BALANCE_ARGS_VRANGE = 1 << 4 BALANCE_ARGS_LIMIT = 1 << 5 BALANCE_ARGS_LIMIT_RANGE = 1 << 6 BALANCE_ARGS_STRIPES_RANGE = 1 << 7 BALANCE_ARGS_CONVERT = 1 << 8 BALANCE_ARGS_SOFT = 1 << 9 BALANCE_ARGS_USAGE_RANGE = 1 << 10 _balance_args_flags_str_map = { BALANCE_ARGS_PROFILES: 'PROFILES', BALANCE_ARGS_USAGE: 'USAGE', BALANCE_ARGS_DEVID: 'DEVID', BALANCE_ARGS_DRANGE: 'DRANGE', BALANCE_ARGS_VRANGE: 'VRANGE', BALANCE_ARGS_LIMIT: 'LIMIT', BALANCE_ARGS_LIMIT_RANGE: 'LIMIT_RANGE', BALANCE_ARGS_STRIPES_RANGE: 'STRIPES_RANGE', BALANCE_ARGS_CONVERT: 'CONVERT', BALANCE_ARGS_SOFT: 'SOFT', BALANCE_ARGS_USAGE_RANGE: 'USAGE_RANGE', } def _balance_args_flags_str(flags): return btrfs.utils.flags_str(flags, _balance_args_flags_str_map) def _balance_args_profiles_str(profiles): return btrfs.utils.flags_str(profiles, btrfs.ctree._balance_args_profiles_str_map) class BalanceArgs(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. :param int profiles: 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. :param int usage_min: Match block groups with usage equal to or above the given percentage. :param int usage_max: Match block groups with usage under the given percentage. :param int devid: Match block groups whose related Chunk object has a Stripe object using physical space on this device. :param int pstart: Match block groups using physical bytes on a device on or after the given start address. Use this in combination with the `devid` option. :param int pend: Match block groups using physical bytes on a device before the given end address. Use this in combination with the `devid` option. :param int vstart: Match block groups that overlap with the given virtual address, or a higher address. :param int vend: Match block groups that overlap with a virtual address before the given address. :param int target: Target block group profile to convert to. :param int limit_min: Try to process at least this amount of block groups. :param int limit_max: Process at most this amount of block groups. :param int stripes_min: Match block groups which have an associated Chunk object that has at least this amount of related Stripe objects. :param int stripes_max: Match block groups which have an associated Chunk object that has at most this amount of related Stripe objects. :param bool soft: 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: :ivar int flags: 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. """ def __init__(self, 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): self.flags = 0 if profiles is not None: self.flags |= BALANCE_ARGS_PROFILES self.profiles = profiles else: self.profiles = 0 if usage_min is not None: self.flags |= BALANCE_ARGS_USAGE_RANGE self.usage_min = usage_min else: self.usage_min = 0 if usage_max is not None: self.flags |= BALANCE_ARGS_USAGE_RANGE self.usage_max = usage_max else: self.usage_max = 100 if devid is not None: self.flags |= BALANCE_ARGS_DEVID self.devid = devid if pstart is not None: self.flags |= BALANCE_ARGS_DRANGE self.pstart = pstart else: self.pstart = 0 if pend is not None: self.flags |= BALANCE_ARGS_DRANGE self.pend = pend else: self.pend = ULLONG_MAX else: self.devid = 0 self.pstart = 0 self.pend = ULLONG_MAX if vstart is not None: self.flags |= BALANCE_ARGS_VRANGE self.vstart = vstart else: self.vstart = 0 if vend is not None: self.flags |= BALANCE_ARGS_VRANGE self.vend = vend else: self.vend = ULLONG_MAX if target is not None: self.flags |= BALANCE_ARGS_CONVERT self.target = target if soft: self.flags |= BALANCE_ARGS_SOFT self.soft = soft else: self.target = 0 if limit_min is not None: self.flags |= BALANCE_ARGS_LIMIT_RANGE self.limit_min = limit_min else: self.limit_min = 0 if limit_max is not None: self.flags |= BALANCE_ARGS_LIMIT_RANGE self.limit_max = limit_max else: self.limit_max = ULONG_MAX if stripes_min is not None: self.flags |= BALANCE_ARGS_STRIPES_RANGE self.stripes_min = stripes_min else: self.stripes_min = 0 if stripes_max is not None: self.flags |= BALANCE_ARGS_STRIPES_RANGE self.stripes_max = stripes_max else: self.stripes_max = ULONG_MAX def _for_struct(self): return self.profiles, self.usage_min, self.usage_max, self.devid, self.pstart, self.pend, \ self.vstart, self.vend, self.target, self.flags, self.limit_min, self.limit_max, \ self.stripes_min, self.stripes_max def __repr__(self): opts = [] if self.flags & BALANCE_ARGS_PROFILES: opts.append("profiles={:#x}".format(self.profiles)) if self.flags & BALANCE_ARGS_USAGE_RANGE: opts.append("usage_min={}, usage_max={}".format(self.usage_min, self.usage_max)) if self.flags & BALANCE_ARGS_DEVID: opts.append("devid={}".format(self.devid)) if self.flags & BALANCE_ARGS_DRANGE: opts.append("pstart={}, pend={}".format(self.pstart, self.pend)) if self.flags & BALANCE_ARGS_VRANGE: opts.append("vstart={}, vend={}".format(self.vstart, self.vend)) if self.flags & BALANCE_ARGS_CONVERT: opts.append("target={:#x}".format(self.target)) if self.flags & BALANCE_ARGS_LIMIT_RANGE: opts.append("limit_min={}, limit_max={}".format(self.limit_min, self.limit_max)) if self.flags & BALANCE_ARGS_STRIPES_RANGE: opts.append("stripes_min={}, stripes_max={}".format( self.stripes_min, self.stripes_max)) if self.flags & BALANCE_ARGS_SOFT: opts.append("soft=True") return "BalanceArgs({})".format(', '.join(opts)) def __str__(self): opts = [] if self.flags & BALANCE_ARGS_PROFILES: opts.append("profiles={}".format(self.profiles_str)) if self.flags & BALANCE_ARGS_USAGE_RANGE: opts.append("usage={}..{}".format(self.usage_min, self.usage_max)) if self.flags & BALANCE_ARGS_DEVID: opts.append("devid={}".format(self.devid)) if self.flags & BALANCE_ARGS_DRANGE: opts.append("drange={}..{}".format(self.pstart, self.pend)) if self.flags & BALANCE_ARGS_VRANGE: opts.append("vrange={}..{}".format(self.vstart, self.vend)) if self.flags & BALANCE_ARGS_CONVERT: opts.append("target={}".format(self.target_str)) if self.flags & BALANCE_ARGS_LIMIT_RANGE: opts.append("limit={}..{}".format(self.limit_min, self.limit_max)) if self.flags & BALANCE_ARGS_STRIPES_RANGE: opts.append("stripes={}..{}".format(self.stripes_min, self.stripes_max)) if self.flags & BALANCE_ARGS_SOFT: opts.append("soft") return "flags({}) {}".format(self.flags_str, ', '.join(opts)) @staticmethod def _pretty_properties(): return [ (_balance_args_flags_str, 'flags'), (_balance_args_profiles_str, 'profiles'), (_balance_args_profiles_str, 'target'), ] BALANCE_DATA = 1 << 0 BALANCE_SYSTEM = 1 << 1 BALANCE_METADATA = 1 << 2 BALANCE_TYPE_MASK = BALANCE_DATA | BALANCE_SYSTEM | BALANCE_METADATA BALANCE_FORCE = 1 << 3 BALANCE_RESUME = 1 << 4 BALANCE_STATE_RUNNING = 1 << 0 BALANCE_STATE_PAUSE_REQ = 1 << 1 BALANCE_STATE_CANCEL_REQ = 1 << 2 _balance_state_str_map = { BALANCE_STATE_RUNNING: 'RUNNING', BALANCE_STATE_PAUSE_REQ: 'PAUSE_REQ', BALANCE_STATE_CANCEL_REQ: 'CANCEL_REQ', } def _balance_state_str(state): return btrfs.utils.flags_str(state, _balance_state_str_map) # These should actually be without leading underscore, but we also have a # function named balance_progress... _balance_args = struct.Struct('=QLL7Q4L48x') _balance_progress = struct.Struct('=3Q') class BalanceProgress(object): """Object representation of struct `btrfs_balance_progress`. :ivar int state: current state of a running balance operation. When a progress object is returned by :func:`~btrfs.ioctl.balance_v2` after a successful uninterrupted run, the value of state is 0. When obtaining a progress object by calling :func:`~btrfs.ioctl.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. :ivar int expected: Estimated number of block groups that will be relocated to fulfill the request. :ivar int considered: Number of block groups that were inspected to see if they match the requested filters. :ivar int completed: Number of block groups relocated so far. """ def __init__(self, state, expected, considered, completed): self.state = state self.expected = expected self.considered = considered self.completed = completed def __repr__(self): return "BalanceProgress(state={self.state:#x}, expected={self.expected}, " \ "considered={self.considered}, completed={self.completed})".format(self=self) def __str__(self): return "state {self.state_str} expected {self.expected} considered {self.considered} " \ "completed {self.completed}".format(self=self) @staticmethod def _pretty_properties(): return [ (_balance_state_str, 'state'), ] _ioctl_balance_args = [ struct.Struct('=Q'), # 0 - flags - in/out struct.Struct('=Q'), # 1 - state - out _balance_args, # 2 - data - in/out _balance_args, # 3 - meta - in/out _balance_args, # 4 - sys - in/out _balance_progress, # 5 - stat - out struct.Struct('=576x') ] ioctl_balance_args = struct.Struct('=' + ''.join([btrfs.ctree._struct_format(s)[1:] for s in _ioctl_balance_args])) IOC_BALANCE_V2 = _IOWR(BTRFS_IOCTL_MAGIC, 32, ioctl_balance_args) class BalanceError(Exception): """Exception class for balance functionality. A :class:`BalanceError` can be thrown by any of the balance related functions in this module. :ivar int state: 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 :func:`balance_v2` function. :ivar int errno: An errno errorcode that was returned when executing the ioctl call in one of the balance related functions. :ivar str msg: 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. """ def __init__(self, state, msg): self.state = state self.msg = msg @property def errno(self): return self.__context__.errno def __str__(self): return self.msg def 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) :param int fd: Open file descriptor to any inode in the filesystem. :param BalanceArgs data_args: Filters for Data type block groups. :param BalanceArgs meta_args: Filters for Metadata type block groups. :param BalanceArgs sys_args: Filters for System type block groups. :param bool force: When True, this allows converting to a profile with less redundancy. :param bool resume: When True, all args are ignored and we ask the kernel to resume a previous balance operation. :returns: A :class:`BalanceProgress` object, describing the end result. :rtype: :class:`BalanceProgress` :raises: :class:`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 :func:`~btrfs.ioctl.balance_ctl`, or having another balance operation already running. When a :class:`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. """ args = bytearray(ioctl_balance_args.size) if resume: _ioctl_balance_args[0].pack_into(args, 0, BALANCE_RESUME) else: flags = 0 pos = _ioctl_balance_args[0].size pos += _ioctl_balance_args[1].size if data_args is not None: flags |= BALANCE_DATA _balance_args.pack_into(args, pos, *data_args._for_struct()) pos += _balance_args.size if meta_args is not None: flags |= BALANCE_METADATA _balance_args.pack_into(args, pos, *meta_args._for_struct()) pos += _balance_args.size if sys_args is not None: flags |= BALANCE_SYSTEM _balance_args.pack_into(args, pos, *sys_args._for_struct()) if force: flags |= BALANCE_FORCE _ioctl_balance_args[0].pack_into(args, 0, flags) try: fcntl.ioctl(fd, IOC_BALANCE_V2, args) except OSError as oserror: pos = _ioctl_balance_args[0].size state, = _ioctl_balance_args[1].unpack_from(args, pos) errorcode = errno.errorcode[oserror.errno] if oserror.errno == errno.ECANCELED: if state & BALANCE_STATE_PAUSE_REQ: msg = "Balance paused by user" if state & BALANCE_STATE_CANCEL_REQ: msg = "Balance canceled by user" elif oserror.errno == errno.ENOTCONN and resume: msg = "Balance resume failed: Not in progress ({})".format(errorcode) elif oserror.errno == errno.EINPROGRESS: if resume: msg = "Balance resume failed: Already running ({})".format(errorcode) else: msg = "Balance start failed: Already in progress ({})".format(errorcode) else: msg = "Error during balancing, there may be more info in dmesg: {}, " \ "state {}".format(errorcode, _balance_state_str(state)) raise BalanceError(state, msg) from None pos = _ioctl_balance_args[0].size state, = _ioctl_balance_args[1].unpack_from(args, pos) pos = sum(x.size for x in _ioctl_balance_args[:5]) return BalanceProgress(state, *_balance_progress.unpack_from(args, pos)) BALANCE_CTL_PAUSE = 1 BALANCE_CTL_CANCEL = 2 ioctl_balance_ctl_int = struct.Struct('=i') IOC_BALANCE_CTL = _IOW(BTRFS_IOCTL_MAGIC, 33, ioctl_balance_ctl_int) def balance_ctl(fd, cmd): """Call the `BTRFS_IOC_BALANCE_CTL` ioctl. Ask the kernel to pause or cancel a running balance operation. :param int fd: Open file descriptor to any inode in the filesystem. :param int cmd: Balance control command. Available commands (available as attribute of this module) are: - `BALANCE_CTL_PAUSE` - `BALANCE_CTL_CANCEL` :raises: :class:`BalanceError` if there is no balance in progress, or if pausing or cancelling it failed. When a :class:`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. """ try: fcntl.ioctl(fd, IOC_BALANCE_CTL, cmd) except OSError as oserror: errorcode = errno.errorcode[oserror.errno] if cmd == BALANCE_CTL_PAUSE: if oserror.errno == errno.ENOTCONN: msg = "Balance pause failed: Not in progress ({})".format(errorcode) else: msg = "Balance pause failed ({})".format(errorcode) elif cmd == BALANCE_CTL_CANCEL: if oserror.errno == errno.ENOTCONN: msg = "Balance cancel failed: Not in progress ({})".format(errorcode) else: msg = "Balance cancel failed ({})".format(errorcode) raise BalanceError(0, msg) from None IOC_BALANCE_PROGRESS = _IOR(BTRFS_IOCTL_MAGIC, 34, ioctl_balance_args) def balance_progress(fd): """Call the `BTRFS_IOC_BALANCE_PROGRESS` ioctl. Ask the kernel about progress of a running balance operation. :param int fd: Open file descriptor to any inode in the filesystem. :returns: A :class:`BalanceProgress` object, describing the current state of the balance operation. :rtype: :class:`BalanceProgress` :raises: :class:`BalanceError` if there is no balance in progress, or if inquiring about the progress failed. When a :class:`BalanceError` is raised, the following values for the errno attribute can be expected: - errno `ENOTCONN`: There is no balance operation in progress. """ args = bytearray(ioctl_balance_args.size) try: fcntl.ioctl(fd, IOC_BALANCE_PROGRESS, args) except OSError as oserror: pos = _ioctl_balance_args[0].size state, = _ioctl_balance_args[1].unpack_from(args, pos) errorcode = errno.errorcode[oserror.errno] if oserror.errno == errno.ENOTCONN: msg = "No balance found ({})".format(errorcode) else: msg = "Balance progress failed ({})".format(errorcode) raise BalanceError(0, msg) from None pos = _ioctl_balance_args[0].size state, = _ioctl_balance_args[1].unpack_from(args, pos) pos = sum(x.size for x in _ioctl_balance_args[:5]) return BalanceProgress(state, *_balance_progress.unpack_from(args, pos)) ioctl_received_subvol_args = struct.Struct('=16sQQQLQLQ128x') _ioctl_received_subvol_args_in = struct.Struct('=16sQ8xQL148x') _ioctl_received_subvol_args_out_up_to_rtime = struct.Struct('=24xQ12x') IOC_SET_RECEIVED_SUBVOL = _IOWR(BTRFS_IOCTL_MAGIC, 37, ioctl_received_subvol_args) def 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. :param int fd: An open file descriptor to the subvolume root directory (inode 256). :param uuid.UUID uuid: The uuid (a python uuid object) we want to have set as received_uuid. :param int stransid: Generation of the subvolume that was sent. :param btrfs.ctree.TimeSpec stime: Time when the subvolume was sent. Note that the stime field is not set at all by `btrfs receive`. """ args = bytearray(_ioctl_received_subvol_args_in.size) _ioctl_received_subvol_args_in.pack_into(args, 0, received_uuid.bytes, stransid, stime.sec, stime.nsec) fcntl.ioctl(fd, IOC_SET_RECEIVED_SUBVOL, args) rtransid, = _ioctl_received_subvol_args_out_up_to_rtime.unpack_from(args, 0) pos = _ioctl_received_subvol_args_out_up_to_rtime.size rtime = btrfs.ctree.TimeSpec(args[pos:pos+btrfs.ctree.TimeSpec._timespec.size]) return rtransid, rtime IOC_SYNC = _IO(BTRFS_IOCTL_MAGIC, 8) def sync(fd): """Call the `BTRFS_IOC_SYNC` ioctl. The sync ioctl triggers delayed allocations, a btrfs transaction commit and the cleaner kthread. :param int fd: Open file descriptor to any inode in the filesystem. .. note:: This function should usually be used implicitly by calling the :func:`~btrfs.ctree.FileSystem.sync` function on a :class:`btrfs.ctree.FileSystem` object. """ fcntl.ioctl(fd, IOC_SYNC) file_dedupe_range_info = struct.Struct('=qQQl4x') file_dedupe_range = struct.Struct('=QQH6x') FIDEDUPERANGE = _IOWR(BTRFS_IOCTL_MAGIC, 54, file_dedupe_range) FILE_DEDUPE_RANGE_SAME = 0 FILE_DEDUPE_RANGE_DIFFERS = 1 class FileDedupeRangeInfo(object): """Object representation of struct `file_dedupe_range_info`. :param int dest_fd: An open file descriptor to a destination file which should get content deduped. :param int dest_offset: Byte offset in the destination file from where the dedupe operation should happen. After calling :func:`fideduperange`, the object will contain return values of the dedupe operation for this destination file: :ivar int bytes_deduped: Amount of actual bytes at the given offset that could be deduped. :ivar int status: 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. """ def __init__(self, dest_fd, dest_offset): self.dest_fd = dest_fd self.dest_offset = dest_offset self.bytes_deduped = None self.status = None @property def status_str(self): """Pretty string representation for the status attribute.""" if self.status == btrfs.ioctl.FILE_DEDUPE_RANGE_SAME: return "RANGE_SAME" if self.status == FILE_DEDUPE_RANGE_DIFFERS: return "RANGE_DIFFERS" return "ERROR {}: {}".format(self.status, os.strerror(-self.status)) def __str__(self): return "dest_fd {self.dest_fd} dest_offset {self.dest_offset} " \ "bytes_deduped {self.bytes_deduped} status {self.status_str}".format(self=self) def fideduperange(fd, src_offset, src_length, range_infos): """Call the `FIDEDUPERANGE` ioctl. :param int fd: Open file descriptor to a source file. :param int src_offset: Offset in the source file where the source range starts. :param int src_length: Length of the source range. :param range_infos: Information about offsets in destination files. :type range_infos: list of :class:`FileDedupeRangeInfo` """ buf = bytearray(file_dedupe_range.size + file_dedupe_range_info.size * len(range_infos)) file_dedupe_range.pack_into(buf, 0, src_offset, src_length, len(range_infos)) pos = file_dedupe_range.size for info in range_infos: file_dedupe_range_info.pack_into(buf, pos, info.dest_fd, info.dest_offset, 0, 0) pos += file_dedupe_range_info.size fcntl.ioctl(fd, FIDEDUPERANGE, buf) pos = file_dedupe_range.size for info in range_infos: _, _, bytes_deduped, status = file_dedupe_range_info.unpack_from(buf, pos) info.bytes_deduped = bytes_deduped info.status = status pos += file_dedupe_range_info.size ioctl_feature_flags = struct.Struct('=QQQ') IOC_GET_FEATURES = _IOR(BTRFS_IOCTL_MAGIC, 57, ioctl_feature_flags) _feature_compat_str_map = { } def _compat_flags_str(flags): return btrfs.utils.flags_str(flags, _feature_compat_str_map) FEATURE_COMPAT_RO_FREE_SPACE_TREE = 1 << 0 FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID = 1 << 1 FEATURE_COMPAT_RO_BLOCK_GROUP_TREE = 1 << 3 _feature_compat_ro_str_map = { FEATURE_COMPAT_RO_FREE_SPACE_TREE: 'free_space_tree', FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID: 'free_space_tree_valid', FEATURE_COMPAT_RO_BLOCK_GROUP_TREE: 'block_group_tree', } def _compat_ro_flags_str(flags): return btrfs.utils.flags_str(flags, _feature_compat_ro_str_map) FEATURE_INCOMPAT_MIXED_BACKREF = 1 << 0 FEATURE_INCOMPAT_DEFAULT_SUBVOL = 1 << 1 FEATURE_INCOMPAT_MIXED_GROUPS = 1 << 2 FEATURE_INCOMPAT_COMPRESS_LZO = 1 << 3 FEATURE_INCOMPAT_COMPRESS_ZSTD = 1 << 4 FEATURE_INCOMPAT_BIG_METADATA = 1 << 5 FEATURE_INCOMPAT_EXTENDED_IREF = 1 << 6 FEATURE_INCOMPAT_RAID56 = 1 << 7 FEATURE_INCOMPAT_SKINNY_METADATA = 1 << 8 FEATURE_INCOMPAT_NO_HOLES = 1 << 9 _feature_incompat_str_map = { FEATURE_INCOMPAT_MIXED_BACKREF: 'mixed_backref', FEATURE_INCOMPAT_DEFAULT_SUBVOL: 'default_subvol', FEATURE_INCOMPAT_MIXED_GROUPS: 'mixed_groups', FEATURE_INCOMPAT_COMPRESS_LZO: 'compress_lzo', FEATURE_INCOMPAT_COMPRESS_ZSTD: 'compress_zstd', FEATURE_INCOMPAT_BIG_METADATA: 'big_metadata', FEATURE_INCOMPAT_EXTENDED_IREF: 'extended_iref', FEATURE_INCOMPAT_RAID56: 'raid56', FEATURE_INCOMPAT_SKINNY_METADATA: 'skinny_metadata', FEATURE_INCOMPAT_NO_HOLES: 'no_holes', } def _incompat_flags_str(flags): return btrfs.utils.flags_str(flags, _feature_incompat_str_map) class FeatureFlags(object): """Object representation of struct `btrfs_ioctl_feature_flags`. Quoting from linux kernel commit `f2b636e80d`: :ivar int compat_flags: These hold the features that are compatible with older versions of btrfs. :ivar int compat_ro_flags: These flags have features that are compatible with older versions of btrfs if the fs is mounted read only. :ivar int incompat_flags: 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) 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 :func:`~btrfs.ctree.FileSystem.features` function on a :class:`btrfs.ctree.FileSystem` object. """ def __init__(self, compat_flags, compat_ro_flags, incompat_flags): self.compat_flags = compat_flags self.compat_ro_flags = compat_ro_flags self.incompat_flags = incompat_flags @staticmethod def _pretty_properties(): return [ (_compat_flags_str, 'compat_flags'), (_compat_ro_flags_str, 'compat_ro_flags'), (_incompat_flags_str, 'incompat_flags'), ] def get_features(fd): """Call the `BTRFS_IOC_GET_FEATURES` ioctl. :param int fd: Open file descriptor to any inode in the filesystem. :returns: A :class:`FeatureFlags` object. .. note:: This function should usually be used implicitly by calling the :func:`~btrfs.ctree.FileSystem.features` function on a :class:`btrfs.ctree.FileSystem` object. """ buf = bytearray(ioctl_feature_flags.size) fcntl.ioctl(fd, IOC_GET_FEATURES, buf) compat_flags, compat_ro_flags, incompat_flags = ioctl_feature_flags.unpack(buf) return FeatureFlags(compat_flags, compat_ro_flags, incompat_flags) DEFRAG_RANGE_COMPRESS = 1 << 0 #: Flag to enable (re)compression functionality DEFRAG_RANGE_START_IO = 1 << 1 #: Flag to more quickly start writing back data ioctl_defrag_range_args = struct.Struct('=QQQLL16x') IOC_DEFRAG_RANGE = _IOW(BTRFS_IOCTL_MAGIC, 16, ioctl_defrag_range_args) def defrag_range(fd, start=0, length=ULLONG_MAX, 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. :param int fd: Open file descriptor to a regular file or a directory. :param int start: Offset to start the defragmentation at. Defaults to 0. :param int length: Amount of bytes to defrag, from the start position. Defaults to 2**64-1. :param int flags: Flags, mainly to activate the (re)compression functionality. See below for more information. By default, no flags are set. :param int extent_thresh: 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. :param int compress_type: Compression type to use when (re)compressing file content. Use one of the `COMPRESS_*` values from the :class:`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. """ args = bytearray(ioctl_defrag_range_args.size) ioctl_defrag_range_args.pack_into(args, 0, start, length, flags, extent_thresh, compress_type) fcntl.ioctl(fd, IOC_DEFRAG_RANGE, args)