BTRFS-IOCTL(2)

📦
version 7.3 · 16 versions
, in arch rolling

💖 BTRFS-IOCTL(2) — the btrfs ioctl breakdown, bestie edition 💖

okay so picture this: you're deep in the BTRFS corner of your man pages, section 2, and you just found BTRFS-IOCTL(2). Hiii. Welcome. This is the whole lore drop on how you talk to btrfs directly through ioctl() calls, and ngl it's a lot but we're gonna get through it together fr fr 🦋

✨ NAME ✨

btrfs-ioctl — documentation about btrfs ioctls

btrfs-ioctl — documentation for the ioctl interface to btrfs

(yes bestie, there are two NAME entries up in here, that's just how the page is built, we're not skipping either one 👑)

🌸 DESCRIPTION 🌸

So the ioctl() system call is literally the way you ask a filesystem to do custom stuff — stuff that goes way beyond the standard interfaces, like syscalls and all that. An ioctl is defined by a number plus an associated data structure, and together they implement one feature. Usually these features are things you just can't get in other filesystems. 💅

The way this works over time: the number of ioctls keeps growing, and sometimes one of them gets promoted — it levels up to a VFS-level ioctl once other filesystems adopt the same functionality. Main character energy honestly. And here's the good part: backward compatibility is maintained, so a formerly private ioctl number could totally show up at the VFS level later. ✨

🌈 OVERVIEW 🌈

Every ioctl is defined by a number, and it's paired up with a data structure that carries the extra details. All of them use a file descriptor (fd) as their reference point — and that fd can be the filesystem itself, or a directory inside the filesystem. Either one works, it's giving flexible. 🫶

An ioctl can be used in the following schematic way:

struct btrfs_ioctl_args args;

memset(&args, 0, sizeof(args));
args.key = value;
ret = ioctl(fd, BTRFS_IOC_NUMBER, &args);

okay so let's break that down because it matters:

  • The fd is your entry point into the filesystem. For most ioctls it genuinely does not matter which directory that is. But — a distinction between files and directories sometimes matters, and when it matters, the page says so explicitly. No cap. 🎀
  • The args is the data structure associated with the request. And bestie, it is strongly recommended that you initialize the whole entire structure to zeros, because that's what makes your code future-proof when the ioctl gets further extensions. Not doing that could lead to a mismatch between old userspace and new kernel versions, or the other way around. So. Zero it. 🙈
  • The BTRFS_IOC_NUMBER says which operation should be done on the given arguments.
  • Some ioctls take a specific data structure, some of them share a common one, and there are even no-argument-structure ioctls — those exist too, slay.
  • The data passed to an ioctl can be input, output, or both.

Now, the library libbtrfsutil wraps a few of these ioctls for convenience. Using raw ioctls is not discouraged, it just may be cumbersome — though it does not need an additional library dependency, which is a little iconic ngl. Backward compatibility is guaranteed, and incompatible changes usually lead to a brand new version of the ioctl. Enhancements to existing ioctls can happen, and those depend on additional flags being set.

Zeroed unused space is commonly understood as the mechanism for communicating compatibility between kernel and userspace — which is exactly why zeroing is really important. In exceptional cases that's not enough, and further flags need to be passed to distinguish between a zero that's implicit unused initialization and a zero that's a valid actual value. Those cases are documented. (So read the docs, bestie, don't guess 💀)

And for the fd plumbing: file descriptors of regular files are obtained by int fd = open(), and directories opened as DIR *dir = opendir() can be converted to the corresponding file descriptor by fd = dirfd(dir).

👑 LIST OF IOCTLS 👑

Okay here's the roster, the whole lineup. Each one gets its name, what it does, and what data it takes. 💅

  • BTRFS_IOC_SNAP_CREATE — (obsolete) create a snapshot of a subvolume. Data: struct btrfs_ioctl_vol_args
  • BTRFS_IOC_DEFRAG — (the roster leaves the description and data blank for this one, so we're leaving them blank too ✨)
  • BTRFS_IOC_RESIZE — (also blank in the roster, no description, no data listed)
  • BTRFS_IOC_SCAN_DEV — scan and register a given device path with the filesystem module. Data: struct btrfs_ioctl_vol_args
  • BTRFS_IOC_SYNC — Sync the filesystem, possibly process queued up work. Data: NULL
  • BTRFS_IOC_CLONE — (blank in the roster, no description or data listed)
  • BTRFS_IOC_ADD_DEV — add a device to the filesystem by path. Data: struct btrfs_ioctl_vol_args
  • BTRFS_IOC_RM_DEV — delete a device from the filesystem by path. Data: struct btrfs_ioctl_vol_args
  • BTRFS_IOC_BALANCE — (blank in the roster, no description or data listed)
  • BTRFS_IOC_CLONE_RANGE — (blank in the roster, no description or data listed)
  • BTRFS_IOC_SUBVOL_CREATE — (obsolete) create a subvolume. Data: struct btrfs_ioctl_vol_args
  • BTRFS_IOC_SNAP_DESTROY — (obsolete) delete a subvolume. Data: struct btrfs_ioctl_vol_args
  • BTRFS_IOC_DEFRAG_RANGE — (blank in the roster, no description or data listed)
  • BTRFS_IOC_TREE_SEARCH — (blank in the roster, no description or data listed)
  • BTRFS_IOC_TREE_SEARCH_V2 — (blank in the roster, no description or data listed)
  • BTRFS_IOC_INO_LOOKUP — resolve inode number to path, or lookup containing subvolume id. Data: struct btrfs_ioctl_ino_lookup_args
  • BTRFS_IOC_DEFAULT_SUBVOL — set the default subvolume id. Data: uint64_t
heads up bestie: the ones marked (obsolete) are obsolete in the original roster, BTRFS_IOC_SNAP_CREATE, BTRFS_IOC_SUBVOL_CREATE and BTRFS_IOC_SNAP_DESTROY especially — so don't go building your whole personality around them. 🫶

and that's where part 1 wraps its lil section… but we are SO not done, there's more coming 💖

  • BTRFS_IOC_SPACE_INFO ✨
  • BTRFS_IOC_START_SYNC ✨
  • BTRFS_IOC_WAIT_SYNC ✨
  • BTRFS_IOC_SNAP_CREATE_V2 — bestie this one creates a snapshot of a subvolume 🫶 arg goes in as a struct btrfs_ioctl_vol_args_v2
  • BTRFS_IOC_SUBVOL_CREATE_V2 — and this one creates a subvolume, no cap 🌱 arg is struct btrfs_ioctl_vol_args_v2
  • BTRFS_IOC_SUBVOL_GETFLAGS — get the flags of a subvolume 👑 arg is uint64_t
  • BTRFS_IOC_SUBVOL_SETFLAGS — set the flags of a subvolume 💅 arg is uint64_t
  • BTRFS_IOC_SCRUB 🔥
  • BTRFS_IOC_SCRUB_CANCEL 🔥
  • BTRFS_IOC_SCRUB_PROGRESS 🔥
  • BTRFS_IOC_DEV_INFO — get information about a device 🧚 and like, the good stuff: UUIDs, used size, total size. arg is struct btrfs_ioctl_dev_info_args
  • BTRFS_IOC_FS_INFO — get information about a filesystem 🌈 device count, fsid, ... yes girl the ... is literally there, the manpage is being mysterious. arg is struct btrfs_ioctl_fs_info_args
  • BTRFS_IOC_BALANCE_V2 ⚖️
  • BTRFS_IOC_BALANCE_CTL ⚖️
  • BTRFS_IOC_BALANCE_PROGRESS ⚖️
  • BTRFS_IOC_INO_PATHS 🦋
  • BTRFS_IOC_LOGICAL_INO 🦋
  • BTRFS_IOC_SET_RECEIVED_SUBVOL 🎀
  • BTRFS_IOC_SEND 📤
  • BTRFS_IOC_DEVICES_READY ✅
  • BTRFS_IOC_QUOTA_CTL 💀
  • BTRFS_IOC_QGROUP_ASSIGN 💀
  • BTRFS_IOC_QGROUP_CREATE 💀
  • BTRFS_IOC_QGROUP_LIMIT 💀
  • BTRFS_IOC_QUOTA_RESCAN 💀
  • BTRFS_IOC_QUOTA_RESCAN_STATUS 💀
  • BTRFS_IOC_QUOTA_RESCAN_WAIT 💀
  • BTRFS_IOC_GET_FSLABEL — read the filesystem label 🌸 arg is a char buffer sized BTRFS_LABEL_SIZE, i.e. char buffer[BTRFS_LABEL_SIZE] 🎀
  • BTRFS_IOC_SET_FSLABEL — sets the filesystem label ✨ · takes a char buffer[BTRFS_LABEL_SIZE]
  • BTRFS_IOC_GET_DEV_STATS — (nothing listed for this one in the table, it's giving mysterious 💀)
  • BTRFS_IOC_DEV_REPLACE — (also blank in the table, no arg listed 🙈)
  • BTRFS_IOC_FILE_EXTENT_SAME — (table left this one empty too, no cap)
  • BTRFS_IOC_GET_FEATURES — grabs the features currently set on the filesystem 👑 · takes a struct btrfs_ioctl_feature_flags
  • BTRFS_IOC_SET_FEATURES — sets features on the filesystem 💅 · takes a struct btrfs_ioctl_feature_flags
  • BTRFS_IOC_GET_SUPPORTED_FEATURES — lists all the available filesystem feature sets 🌈 · takes a struct btrfs_ioctl_feature_flags[3]
  • BTRFS_IOC_RM_DEV_V2 — (no description or arg in the table, she's a mystery 🦋)
  • BTRFS_IOC_LOGICAL_INO_V2 — (blank in the table too)
  • BTRFS_IOC_GET_SUBVOL_INFO — gets the info about a subvolume 🎀 · takes a struct btrfs_ioctl_get_subvol_info_args
  • BTRFS_IOC_GET_SUBVOL_ROOTREF — (nothing listed, table said nothing 😭)
  • BTRFS_IOC_INO_LOOKUP_USER — (also blank in the table)
  • BTRFS_IOC_SNAP_DESTROY_V2 — destroys a (snapshot or regular) subvolume 🔥 · takes a struct btrfs_ioctl_vol_args_v2
  • BTRFS_IOC_ENCODED_READ — (no description or arg given, iconic but unhelpful 💀)
  • BTRFS_IOC_ENCODED_WRITE — (blank in the table as well)
  • BTRFS_IOC_SUBVOL_SYNC_WAIT — waits until a deleted subvolume is cleaned up, or queries the state ⏳ · takes a struct btrfs_ioctl_subvol_wait
  • BTRFS_IOC_SHUTDOWN — forces filesystem IO shutdown and flips it to read-only ⚠️ · takes a uint64_t
  • BTRFS_IOC_GET_CSUMS — reads raw checksums from a file range 🧚 · no arg column value listed

okay that's the whole ioctl table done and dusted bestie 💖 keep scrolling, there's more coming ✨

✨ DATA STRUCTURES AND DEFINITIONS ✨

okay bestie, buckle up, because this is where we get into the actual structs and defines. it's giving... a lot. but we're gonna slay this together. 💅

here's the og volume args struct:

          struct btrfs_ioctl_vol_args {
                  __s64 fd;
                  char name[BTRFS_PATH_NAME_MAX + 1];
          };

it's literally just a file descriptor and a name. fd is __s64, name is a char array that can fit BTRFS_PATH_NAME_MAX + 1 characters. simple.

then we got these subvol flags:

          #define BTRFS_SUBVOL_RDONLY                  (1ULL << 1)
          #define BTRFS_SUBVOL_QGROUP_INHERIT          (1ULL << 2)
          #define BTRFS_DEVICE_SPEC_BY_ID              (1ULL << 3)
          #define BTRFS_SUBVOL_SPEC_BY_ID              (1ULL << 4)

these are bit flags, bestie. RDONLY means read-only, QGROUP_INHERIT means inherit qgroups, DEVICE_SPEC_BY_ID means specify device by ID, and SUBVOL_SPEC_BY_ID means specify subvolume by ID. no cap.

then the v2 volume args struct, which is a whole mood:

          struct btrfs_ioctl_vol_args_v2 {
                  __s64 fd;
                  __u64 transid;
                  __u64 flags;
                  union {
                          struct {
                                  __u64 size;
                                  struct btrfs_qgroup_inherit __user *qgroup_inherit;
                          };
                          __u64 unused[4];
                  };
                  union {
                          char name[BTRFS_SUBVOL_NAME_MAX + 1];
                          __u64 devid;
                          __u64 subvolid;
                  };
          };

so it's got fd, transid, flags, and then two unions. the first union is either a struct with size and a pointer to qgroup_inherit, or an array of 4 __u64s called unused. the second union is either a name char array of size BTRFS_SUBVOL_NAME_MAX + 1, or a devid, or a subvolid. choose your fighter. 🎀

now, the compat ro feature flags:

          #define BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE         (1ULL << 0)
          /*
           * Older kernels (< 4.9) on big-endian systems produced broken free space tree
           * bitmaps, and btrfs-progs also used to corrupt the free space tree (versions
           * < 4.7.3).  If this bit is clear, then the free space tree cannot be trusted.
           * btrfs-progs can also intentionally clear this bit to ask the kernel to
           * rebuild the free space tree, however this might not work on older kernels
           * that do not know about this bit. If not sure, clear the cache manually on
           * first mount when booting older kernel versions.
           */
          #define BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID   (1ULL << 1)
          #define BTRFS_FEATURE_COMPAT_RO_VERITY                  (1ULL << 2)
          #define BTRFS_FEATURE_COMPAT_RO_BLOCK_GROUP_TREE        (1ULL << 3)

okay so this comment is important. if BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID is clear, the free space tree cannot be trusted. why? because older kernels (< 4.9) on big-endian systems produced broken free space tree bitmaps, and btrfs-progs < 4.7.3 also corrupted it. btrfs-progs can intentionally clear this bit to ask the kernel to rebuild the free space tree, but that might not work on older kernels that don't know about this bit. if you're not sure, clear the cache manually on first mount when booting older kernel versions. periodt.

then the incompat feature flags, which are a whole parade:

          #define BTRFS_FEATURE_INCOMPAT_MIXED_BACKREF            (1ULL << 0)
          #define BTRFS_FEATURE_INCOMPAT_DEFAULT_SUBVOL           (1ULL << 1)
          #define BTRFS_FEATURE_INCOMPAT_MIXED_GROUPS             (1ULL << 2)
          #define BTRFS_FEATURE_INCOMPAT_COMPRESS_LZO             (1ULL << 3)
          #define BTRFS_FEATURE_INCOMPAT_COMPRESS_ZSTD            (1ULL << 4)
          #define BTRFS_FEATURE_INCOMPAT_BIG_METADATA             (1ULL << 5)
          #define BTRFS_FEATURE_INCOMPAT_EXTENDED_IREF            (1ULL << 6)
          #define BTRFS_FEATURE_INCOMPAT_RAID56                   (1ULL << 7)
          #define BTRFS_FEATURE_INCOMPAT_SKINNY_METADATA          (1ULL << 8)
          #define BTRFS_FEATURE_INCOMPAT_NO_HOLES                 (1ULL << 9)
          #define BTRFS_FEATURE_INCOMPAT_METADATA_UUID            (1ULL << 10)
          #define BTRFS_FEATURE_INCOMPAT_RAID1C34                 (1ULL << 11)
          #define BTRFS_FEATURE_INCOMPAT_ZONED                    (1ULL << 12)
          #define BTRFS_FEATURE_INCOMPAT_EXTENT_TREE_V2           (1ULL << 13)
          #define BTRFS_FEATURE_INCOMPAT_RAID_STRIPE_TREE         (1ULL << 14)
          #define BTRFS_FEATURE_INCOMPAT_SIMPLE_QUOTA             (1ULL << 16)

these are all incompat flags, meaning if you don't understand them, you can't mount. each one is 1ULL << n. icons only.

then the feature flags struct:

          struct btrfs_ioctl_feature_flags {
                  __u64 compat_flags;
                  __u64 compat_ro_flags;
                  __u64 incompat_flags;
          };

just three __u64s. easy.

next, the get subvol info args struct, which is a whole info dump:

          struct btrfs_ioctl_get_subvol_info_args {
                  /* Id of this subvolume */
                  __u64 treeid;

                  /* Name of this subvolume, used to get the real name at mount point */
                  char name[BTRFS_VOL_NAME_MAX + 1];

                  /*
                   * Id of the subvolume which contains this subvolume.
                   * Zero for top-level subvolume or a deleted subvolume.
                   */
                  __u64 parent_id;

                  /*
                   * Inode number of the directory which contains this subvolume.
                   * Zero for top-level subvolume or a deleted subvolume
                   */
                  __u64 dirid;

                  /* Latest transaction id of this subvolume */
                  __u64 generation;

                  /* Flags of this subvolume */
                  __u64 flags;

                  /* UUID of this subvolume */
                  __u8 uuid[BTRFS_UUID_SIZE];

                  /*
                   * UUID of the subvolume of which this subvolume is a snapshot.
                   * All zero for a non-snapshot subvolume.
                   */
                  __u8 parent_uuid[BTRFS_UUID_SIZE];

                  /*
                   * UUID of the subvolume from which this subvolume was received.
                   * All zero for non-received subvolume.
                   */
                  __u8 received_uuid[BTRFS_UUID_SIZE];

                  /* Transaction id indicating when change/create/send/receive happened */
                  __u64 ctransid;
                  __u64 otransid;
                  __u64 stransid;
                  __u64 rtransid;
                  /* Time corresponding to c/o/s/rtransid */
                  struct btrfs_ioctl_timespec ctime;
                  struct btrfs_ioctl_timespec otime;
                  struct btrfs_ioctl_timespec stime;
                  struct btrfs_ioctl_timespec rtime;

                  /* Must be zero */
                  __u64 reserved[8];
          };

this struct is literally the biography of a subvolume. treeid is its ID, name is its name (used to get the real name at mount point), parent_id is the ID of the subvolume that contains it (zero for top-level or deleted), dirid is the inode number of the containing directory (zero for top-level or deleted), generation is the latest transaction ID, flags are its flags, uuid is its UUID, parent_uuid is the UUID of the subvolume it's a snapshot of (all zero if not a snapshot), received_uuid is the UUID of the subvolume it was received from (all zero if not received), then ctransid, otransid, stransid, rtransid are transaction IDs for change/create/send/receive, and ctime, otime, stime, rtime are the corresponding times. reserved[8] must be zero. don't touch it. 🙈

then we have the qgroup inherit defines and structs:

          #define BTRFS_QGROUP_INHERIT_SET_LIMITS         (1ULL << 0)

          struct btrfs_qgroup_inherit {
                  __u64 flags;
                  __u64 num_qgroups;
                  __u64 num_ref_copies;
                  __u64 num_excl_copies;
                  struct btrfs_qgroup_limit lim;
                  __u64 qgroups[];
          };

so BTRFS_QGROUP_INHERIT_SET_LIMITS is a flag. the struct has flags, num_qgroups, num_ref_copies, num_excl_copies, a lim of type struct btrfs_qgroup_limit, and a flexible array qgroups[]. it's giving flexible. 💅

then the qgroup limit defines:

          #define BTRFS_QGROUP_LIMIT_MAX_RFER             (1ULL << 0)
          #define BTRFS_QGROUP_LIMIT_MAX_EXCL             (1ULL << 1)
          #define BTRFS_QGROUP_LIMIT_RSV_RFER             (1ULL << 2)
          #define BTRFS_QGROUP_LIMIT_RSV_EXCL             (1ULL << 3)
          #define BTRFS_QGROUP_LIMIT_RFER_CMPR            (1ULL << 4)
          #define BTRFS_QGROUP_LIMIT_EXCL_CMPR            (1ULL << 5)

these are bit flags for qgroup limits. each one is 1ULL << n.

and the qgroup limit struct:

          struct btrfs_qgroup_limit {
                  __u64 flags;
                  __u64 max_rfer;
                  __u64 max_excl;
                  __u64 rsv_rfer;
                  __u64 rsv_excl;
          };

just five __u64s. flags, max_rfer, max_excl, rsv_rfer, rsv_excl. no cap.

now the device info args struct:

          struct btrfs_ioctl_dev_info_args {
               __u64 devid;                            /* in/out */
               __u8 uuid[BTRFS_UUID_SIZE];             /* in/out */
               __u64 bytes_used;                       /* out */
               __u64 total_bytes;                      /* out */
               /*
                * Optional, out.
                *
                * Showing the fsid of the device, allowing user space to check if this
                * device is a seeding one.
                *
                * Introduced in v6.3, thus user space still needs to check if kernel
                * changed this value.  Older kernel will not touch the values here.
                */
               __u8 fsid[BTRFS_UUID_SIZE];
               __u64 unused[377];                      /* pad to 4k */
               __u8 path[BTRFS_DEVICE_PATH_NAME_MAX];  /* out */
          };

so devid and uuid are in/out, bytes_used and total_bytes are out, fsid is optional out (introduced in v6.3, so user space still needs to check if the kernel changed this value; older kernels will not touch the values here), unused[377] pads to 4k, and path is out. the fsid lets user space check if the device is a seeding one. periodt.

then the fs info flags:

          /* Request information about checksum type and size */
          #define BTRFS_FS_INFO_FLAG_CSUM_INFO                    (1U << 0)
          /* Request information about filesystem generation */
          #define BTRFS_FS_INFO_FLAG_GENERATION                   (1U << 1)
          /* Request information about filesystem metadata UUID */
          #define BTRFS_FS_INFO_FLAG_METADATA_UUID                (1U << 2)

these are flags you can set to request extra info: checksum type and size, filesystem generation, or filesystem metadata UUID. each is 1U << n.

and the fs info args struct:

          struct btrfs_ioctl_fs_info_args {
                  __u64 max_id;                           /* out */
                  __u64 num_devices;                      /* out */
                  __u8 fsid[BTRFS_FSID_SIZE];             /* out */
                  __u32 nodesize;                         /* out */
                  __u32 sectorsize;                       /* out */
                  __u32 clone_alignment;                  /* out */
                  /* See BTRFS_FS_INFO_FLAG_* */
                  __u16 csum_type;                        /* out */
                  __u16 csum_size;                        /* out */
                  __u64 flags;                            /* in/out */
                  __u64 generation;                       /* out */
                  __u8 metadata_uuid[BTRFS_FSID_SIZE];    /* out */
                  __u8 reserved[944];                     /* pad to 1k */
          };

this struct is all the fs info: max_id, num_devices, fsid, nodesize, sectorsize, clone_alignment, csum_type, csum_size (see BTRFS_FS_INFO_FLAG_* for when those are valid), flags is in/out, generation is out, metadata_uuid is out, and reserved[944] pads to 1k. don't touch the reserved, bestie. 😭

then the ino lookup args:

          #define BTRFS_INO_LOOKUP_PATH_MAX               4080

          struct btrfs_ioctl_ino_lookup_args {
                  __u64 treeid;
                  __u64 objectid;
                  char name[BTRFS_INO_LOOKUP_PATH_MAX];
          };

so BTRFS_INO_LOOKUP_PATH_MAX is 4080. the struct has treeid, objectid, and name of size BTRFS_INO_LOOKUP_PATH_MAX. simple.

then the subvol sync defines and struct:

          /* Specify the subvolid. */
          #define BTRFS_SUBVOL_SYNC_WAIT_FOR_ONE         (0)
          /* Wait for all currently queued. */
          #define BTRFS_SUBVOL_SYNC_WAIT_FOR_QUEUED      (1)
          /* Count number of queued subvolumes. */
          #define BTRFS_SUBVOL_SYNC_COUNT                (2)
          /*
           * Read which is the first in the queue (to be cleaned or being cleaned already),
           * or 0 if the queue is empty.
           */
          #define BTRFS_SUBVOL_SYNC_PEEK_FIRST           (3)
          /* Read the last subvolid in the queue, or 0 if the queue is empty. */
          #define BTRFS_SUBVOL_SYNC_PEEK_LAST            (4)

          struct btrfs_ioctl_subvol_wait {
                 __u64 subvolid;
                 __u32 mode;
                 __u32 count;
          };

so these are modes for subvol sync. WAIT_FOR_ONE (0) means specify the subvolid. WAIT_FOR_QUEUED (1) means wait for all currently queued. COUNT (2) means count number of queued subvolumes. PEEK_FIRST (3) means read which is the first in the queue (to be cleaned or being cleaned already), or 0 if the queue is empty. PEEK_LAST (4) means read the last subvolid in the queue, or 0 if the queue is empty. and the struct btrfs_ioctl_subvol_wait has subvolid, mode, and count. slay.

now here's the constant cheat sheet, bestie:

  • BTRFS_UUID_SIZE — 16
  • BTRFS_FSID_SIZE — 16
  • BTRFS_SUBVOL_NAME_MAX — 4039
  • BTRFS_PATH_NAME_MAX — 4087
  • BTRFS_VOL_NAME_MAX — 255
  • BTRFS_LABEL_SIZE — 256
  • BTRFS_FIRST_FREE_OBJECTID — 256

memorize these, they come up everywhere. iykyk. 💖

💅 DETAILED DESCRIPTION 💅

BTRFS_IOC_SNAP_CREATE

okay so this one is a whole note:

Note: obsoleted by BTRFS_IOC_SNAP_CREATE_V2

so like, don't use it? it's been replaced by the v2 version. periodt.

(since: 3.0, obsoleted: 4.0) Create a snapshot of a subvolume.

  • ioctl fd — the file descriptor of the parent directory of the new subvolume (so like, where the baby snapshot is gonna live 💖)
  • ioctl args — struct btrfs_ioctl_vol_args
  • args.fd — a file descriptor of any directory inside the subvolume you wanna snapshot, and bestie listen, it must be on the same filesystem
  • args.name — the name of the subvolume. and okay so the buffer itself can be almost 4KiB, but the file size is limited by Linux VFS to 255 characters and it must not contain a slash ('/'). no sneaky slashes, it's giving "one name only" energy 💅

BTRFS_IOC_SCAN_DEV

Scan and register a given device in the filesystem module, which can be later used for automatic device and filesystem association at mount time. And no, this does not work on files from a mounted filesystem — it operates on the control device. Also it's lowkey chill: you can safely call it repeatedly with the same device path. obsessed. ✨

  • ioctl fd — file descriptor of the control device /dev/btrfs-control
  • ioctl args — struct btrfs_ioctl_vol_args
  • args.fd — ignored 🙈
  • args.name — full path of the device

BTRFS_IOC_SYNC

Sync the filesystem data as the sync() syscall would do, and additionally wake up the internal transaction thread that may trigger actions like subvolume cleaning or queued defragmentation. so it's sync() but with main character energy 👑

  • ioctl fd — file descriptor of any file or directory in the filesystem
  • ioctl args — NULL

BTRFS_IOC_ADD_DEV

Add a given block device to the filesystem. But bestie, heads up: unlike the command btrfs device add, there are no safety checks (like, none for the existence of another filesystem on the device) and no device preparation (like TRIM or zone reset). so use it with care fr fr 😭

This is a filesystem-exclusive operation, and it will fail if there's another one already running — with one exception: when there's a paused balance. ok periodt.

Required permissions: CAP_SYS_ADMIN

  • ioctl fd — file descriptor of any file or directory in the filesystem
  • ioctl args — struct btrfs_ioctl_vol_args
  • args.fd — ignored 🙈
  • args.name — full path of the block device to be added

BTRFS_IOC_RM_DEV

Remove a device from the filesystem specified by its path, or cancel a running device deletion by the special path cancel. two modes, one ioctl, iconic 💅

This is a filesystem-exclusive operation, and it will fail if there's another one already running.

Required permissions: CAP_SYS_ADMIN

  • ioctl fd — file descriptor of any file or directory in the filesystem
  • ioctl args — struct btrfs_ioctl_vol_args
  • args.fd — ignored 🙈
  • args.name — full path of the block device to be deleted, or the string "cancel"

BTRFS_IOC_SUBVOL_CREATE

Note: obsoleted by BTRFS_IOC_SUBVOL_CREATE_V2

(since: 3.0, obsoleted: 4.0) Create a subvolume.

  • ioctl fd — file descriptor of the parent directory of the new subvolume
  • ioctl args — struct btrfs_ioctl_vol_args
  • args.fd — ignored 🙈
  • args.name — name of the subvolume, although the buffer can be almost 4KiB, the file size is limited by Linux VFS to 255 characters and must not contain a slash ('/'). same rules as always, bestie 🎀

BTRFS_IOC_SNAP_DESTROY

Note: obsoleted by BTRFS_IOC_SNAP_DESTROY_V2 💀

(since: 2.6.33, obsoleted: 5.7) — Delete a subvolume. bestie she's retired, she's a legacy icon, but you still gotta know her 💅

  • ioctl fd — the file descriptor of the parent directory of the new subvolume 👀
  • ioctl args — struct btrfs_ioctl_vol_args
  • args.fd — ignored. she's just there. decorative. a little prop 🎀
  • args.name — the name of the subvolume. and like, the buffer can be almost 4KiB, but no cap — Linux VFS limits the file size to 255 characters, and it must not contain a slash (/). no slashes. none. don't even think about it 🚫

🌸 BTRFS_IOC_INO_LOOKUP 🌸

Resolve an inode number to a path (this needs CAP_SYS_ADMIN), or — special case — read the containing subvolume id of a given file (unrestricted, no cap needed for that one). ngl the path name buffer here is shorter than PATH_MAX (4096), so it's totally possible your path gets trimmed because of that. it's giving "short king buffer" 😭

Also implemented by btrfs inspect-internal rootid <#man-inspect-rootid>. iykyk.

So the general case needs CAP_SYS_ADMIN and can resolve any file to its path. The special case for reading the containing subvolume is not restricted:

struct btrfs_ioctl_ino_lookup_args args;

fd = open("file", ...);
args.treeid = 0;
args.objectid = BTRFS_FIRST_FREE_OBJECTID;
ioctl(fd, BTRFS_IOC_INO_LOOKUP, &args);
/* args.treeid now contains the subvolume id */

the way that last comment literally tells you the answer is already in args.treeid 🫶

  • ioctl fd — the file descriptor of the file or directory you're looking up the subvolumeid for 🔍
  • ioctl args — struct btrfs_ioctl_ino_lookup_args
  • args.treeid — the subvolume id to resolve the path against (this one needs CAP_SYS_ADMIN), or 0, in which case the subvolume containing fd gets used instead 💫
  • args.objectid — the inode number to look up; INODE_REF_KEY with that key.objectid, or BTRFS_FIRST_FREE_OBJECTID as the special case that reads only the tree id and clears the args.name buffer ✨
  • args.name — the path relative to the toplevel subvolume, or an empty string 🍓

👑 BTRFS_IOC_DEFAULT_SUBVOL 👑

Sets the given subvolume id as the default one for when you mount the filesystem without the subvol=path or subvolid=id options. she's the main character now, no arguments 💅

  • ioctl fd — the file descriptor of the directory inside which to create the new snapshot
  • ioctl args — the numeric value of the subvolume that's becoming the default (uint64_t) ⭐

🦋 BTRFS_IOC_SNAP_CREATE_V2 🦋

Create a snapshot of a subvolume. iconic behavior, no notes 🌈

  • ioctl fd — the file descriptor of the directory inside which to create the new snapshot
  • ioctl args — struct btrfs_ioctl_vol_args_v2
  • args.fd — the file descriptor of any directory inside the subvolume to snapshot, and it must be on the filesystem 📍
  • args.transid — ignored. again just vibing in the struct 🙈
  • args.flags — any subset of BTRFS_SUBVOL_RDONLY, which makes the new snapshot read-only, or BTRFS_SUBVOL_QGROUP_INHERIT, which applies the qgroup_inherit field 💖
  • args.name — the name, under the ioctl fd, for the new subvolume 👑

🎀 BTRFS_IOC_SUBVOL_CREATE_V2 🎀

(since: 3.6) — bestie, this one makes a subvolume, and it's the ✨deluxe✨ version because you can also specify qgroup inheritance and limits. no cap, it's just the fancier sibling of the plain create call.

here's everything you're feeding it 💖

  • ioctl fd — the file descriptor of the parent directory of the new subvolume (so like, the folder it's gonna be born into)
  • ioctl args — a struct btrfs_ioctl_vol_args_v2
  • args.fd — ignored 🙈
  • args.transid — also ignored 🙈
  • args.flags — the flags to set on the subvolume: BTRFS_SUBVOL_RDONLY for readonly, and BTRFS_SUBVOL_QGROUP_INHERIT if you want the qgroup-related fields to actually be processed
  • args.size — the number of entries in args.qgroup_inherit
  • args.qgroup_inherit — inherit the given qgroups (that's struct btrfs_qgroup_inherit) plus the limits (struct btrfs_qgroup_limit)
  • name — the name of the subvolume. and ok so the buffer can hold almost 4KiB, BUT the file size is limited by Linux VFS to 255 characters and it must not contain a slash ('/'). no slashes, periodt. 💅

🔍 BTRFS_IOC_SUBVOL_GETFLAGS 🔍

Reads the flags of a subvolume. and the returned flags are either 0 or BTRFS_SUBVOL_RDONLY — that's the whole menu, bestie, that's it. 🫶

  • ioctl fd — the file descriptor of the subvolume you want to examine
  • ioctl args — uint64_t

🦋 BTRFS_IOC_SUBVOL_SETFLAGS 🦋

Changes the flags of a subvolume. glow-up time ✨

  • ioctl fd — the file descriptor of the subvolume you're modifying
  • ioctl args — uint64_t, either 0 or BTRFS_SUBVOL_RDONLY

🌸 BTRFS_IOC_GET_FSLABEL 🌸

Reads the label of the filesystem into a given buffer. alternatively you can read it from /sys/fs/btrfs/FSID/label — though, iykyk, that way requires you to already know the FSID of the filesystem. 🙃

  • ioctl fd — file descriptor of any file/directory in the filesystem
  • ioctl args — char buffer[BTRFS_LABEL_SIZE]

✨ BTRFS_IOC_SET_FSLABEL ✨

Sets the label of the filesystem from the given buffer. heads up: the maximum length also accounts for the terminating NUL character 💀. you can also set it by writing to /sys/fs/btrfs/FSID/label, though that requires knowing the FSID of the filesystem — and an explicit commit before the change is permanent.

Required permissions: CAP_SYS_ADMIN

  • ioctl fd — file descriptor of any file/directory in the filesystem
  • ioctl args — char buffer[BTRFS_LABEL_SIZE]

👑 BTRFS_IOC_DEV_INFO 👑

Reads some basic info about a device, and you can ask for it by devid or by device UUID. pick your fighter 💅

  • ioctl fd — file descriptor of any file/directory in the filesystem
  • ioctl args — struct btrfs_ioctl_dev_info_args

🌈 BTRFS_IOC_FS_INFO 🌈

Reads internal information about the filesystem. the data can be exchanged both ways and part of the structure could optionally be filled — so it's giving conversation, not interrogation. the reserved bytes can be used to get a new kind of information in the future 🤫, always depending on the flags that are set.

  • ioctl fd — file descriptor of any file/directory in the filesystem
  • ioctl args — struct btrfs_ioctl_fs_info_args

⭐ BTRFS_IOC_GET_FEATURES ⭐

Gets the actually set feature bits on the filesystem (those bits live in the super block, fr fr). there are three sets related to backward compatibility:

  • incompat — not backward compatible, so mounting on an older kernel will fail 💀
  • compat_ro — backward compatible for read-only mount
  • compat — backward compatible with read-write support, and it's only ever marked as an individual feature, bestie 🫶

The ioctl for this one looks like:

  • ioctl fd — file descriptor of the subvolume to examine
  • ioctl args — struct btrfs_ioctl_feature_flags

If a bit is set then there may be some data structures on the filesystem of the related feature, but not necessarily — so clock that, it's a maybe not a definitely 💅

Some of the features are turned on automatically when used, e.g. compression, or when a balance filter converts to a yet unused block group profile. In some cases the feature can be turned on or off by btrfstune(8) <>.

✨ BTRFS_IOC_SET_FEATURES ✨

Set a feature bit on the filesystem if possible — key phrase, bestie, not everything is gonna be possible 😭 Some features may require extensive changes, new data structures or conversion (like free-space-tree). Bits representing possible existence of data structures related to the feature can be set without actually creating anything, e.g. ZSTD compressed extents. Like, the flag says "hey this could exist" and the kernel goes "bet" and writes nothing. No cap.

  • ioctl fd — file descriptor of the subvolume to examine
  • ioctl args — struct btrfs_ioctl_feature_flags

🌈 BTRFS_IOC_GET_SUPPORTED_FEATURES 🌈

Get the feature sets that the kernel module supports, in three whole groups — it's giving trio energy:

  • supported: (index 0) all supported compat/compat_ro/incompat features
  • safe to set: (index 1) features that can be enabled on a mounted filesystem
  • safe to clear: (index 2) features that can be disabled on a mounted filesystem

The features are also listed in /sys/fs/btrfs/features, so if you're a filesystem-girl you can go read them straight from sysfs 🦋

  • ioctl fd — file descriptor of the subvolume to examine
  • ioctl args — struct btrfs_ioctl_feature_flags[3]

🎀 BTRFS_IOC_GET_SUBVOL_INFO 🎀

Get information about a subvolume. Just vibes and facts about your subvol ✨

  • ioctl fd — file descriptor of the subvolume to examine
  • ioctl args — struct btrfs_ioctl_get_subvol_info_args

👑 BTRFS_IOC_SNAP_DESTROY_V2 👑

Destroy a subvolume, which may or may not be a snapshot. It's the V2 glow-up of destroying things 💀

  • ioctl fd — if flags does not include BTRFS_SUBVOL_SPEC_BY_ID, or if executing in a non-root user namespace, file descriptor of the parent directory containing the subvolume to delete; otherwise, file descriptor of any directory on the same filesystem as the subvolume to delete, but not within the same subvolume
  • ioctl args — struct btrfs_ioctl_vol_args_v2
  • args.fd — ignored (just sitting there, unbothered)
  • args.transid — ignored
  • args.flags — 0 if the name field identifies the subvolume by name in the specified directory, or BTRFS_SUBVOL_SPEC_BY_ID if the subvolid field specifies the ID of the subvolume
  • args.name — only if flags does not contain BTRFS_SUBVOL_SPEC_BY_ID, the name (within the directory identified by fd) of the subvolume to delete
  • args.subvolid — only if flags contains BTRFS_SUBVOL_SPEC_BY_ID, the subvolume ID of the subvolume to delete

🧚 BTRFS_IOC_SUBVOL_SYNC_WAIT 🧚

(since: 6.13) Wait until a deleted subvolume is cleaned, or query the state. Main character energy for cleanup ops 💜

There are several modes of operation, where the most common ones are to wait on a specific subvolume or all currently queued for cleaning. This is utilized e.g. in backup applications that delete subvolumes and wait until they're cleaned to check for remaining space.

The other modes are for flexibility, e.g. for monitoring or checkpoints in the queue of deleted subvolumes, again without the need to use SEARCH_TREE. Lowkey genius honestly.

Notes, bestie, read these fr fr:

  • waiting is interruptible, the timeout is set to 1 second and is not configurable — that's the way it is, periodt
  • repeated calls to the ioctl see a different state, so this is inherently racy when using e.g. the count or peek next/last 🙈

Use cases (definition of constants):

  • a subvolume A was deleted, wait for cleaning (WAIT_FOR_ONE)
  • a bunch of subvolumes were deleted, wait for all (WAIT_FOR_QUEUED or PEEK_LAST + WAIT_FOR_ONE)
  • count how many are queued (not blocking), for monitoring purposes
  • report progress (PEEK_NEXT), may miss some if cleaning is quick
  • own waiting in user space (PEEK_LAST until it's 0)

okay so here's the field-by-field vibe check on struct btrfs_ioctl_subvol_wait, bestie:

  • ioctl fd — file descriptor of any file or directory in the filesystem
  • ioctl args — struct btrfs_ioctl_subvol_wait
  • args.subvolid — depending on the mode, the numeric id of subvolume to wait for, or the one queried by PEEK modes
  • args.mode — mode of operation described above
  • args.count — if mode is set to COUNT, the number of subvolumes queued for cleaning

🛑 BTRFS_IOC_SHUTDOWN 🛑

(since 7.1) Force filesystem IO shutdown and turn it read-only. like, it's over, we're done here, no more writes for you 💀

  • ioctl fd — file descriptor of any file or directory in the filesystem
  • ioctl args — uint64_t, mode described below

The argument is an int with modes affecting flushing of pending writes:

  • BTRFS_SHUTDOWN_FLAGS_DEFAULT (0x0) — choose default (LOGFLUSH mode)
  • BTRFS_SHUTDOWN_FLAGS_LOGFLUSH (0x1) — flush everything, the filesystem is frozen, shut down and thawn (yes bestie, "thawn", we are keeping it exactly as written, no cap 🙈)
  • BTRFS_SHUTDOWN_FLAGS_NOLOGFLUSH (0x2) — shut down the filesystem right away
heads up: NOLOGFLUSH really does mean right away — nothing gets flushed first, so, like, know what you're doing 👀

Additionally the fserror reporting facility is used to notify about the event. so the whole system gets the tea ☕

🌈 AVAILABILITY 🌈

btrfs is part of btrfs-progs. Please refer to the documentation at https://btrfs.readthedocs.io. go read it, it's giving main character energy 📚✨

💜 SEE ALSO 💜

ioctl(2) https://man7.org/linux/man-pages/man2/ioctl.2.html

and that's a wrap on the whole page, bestie 🎀 this was btrfs-progs version 7.3, dated Oct 24, 2026, and honestly? she ate. now go touch some subvolumes, ily, bye 🫶👑

📦 where this page comes from