btrfs-ioctl - Man Page

btrfs-ioctl - documentation for the ioctl interface to btrfs

The ioctl() system call is a way how to request custom actions performed on a filesystem beyond the standard interfaces (like syscalls).  An ioctl is specified by a number and an associated data structure that implement a feature, usually not available in other filesystems. The number of ioctls grows over time and in some cases get promoted to a VFS-level ioctl once other filesystems adopt the functionality. Backward compatibility is maintained and a formerly private ioctl number could become available on the VFS level.

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

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

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;
        };
};

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];
};

#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[];
};

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

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

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

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 */
};

#define BTRFS_INO_LOOKUP_PATH_MAX               4080

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

The ioctls are defined by a number and associated with a data structure that contains further information. All ioctls use file descriptor (fd) as a reference point, it could be the filesystem or a directory inside the filesystem.

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

The 'fd' is the entry point to the filesystem and for most ioctls it does not matter which file or directory is that. Where it matters it's explicitly mentioned. The 'args' is the associated data structure for the request. It's strongly recommended to initialize the whole structure to zeros as this is future-proof when the ioctl gets further extensions. Not doing that could lead to mismatch of old userspace and new kernel versions, or vice versa. The 'BTRFS_IOC_NUMBER' is says which operation should be done on the given arguments. Some ioctls take a specific data structure, some of them share a common one, no argument structure ioctls exist too.

The library libbtrfsutil wraps a few ioctls for convenience. Using raw ioctls is not discouraged but may be cumbersome though it does not need additional library dependency. Backward compatibility is guaranteed and incompatible changes usually lead to a new version of the ioctl. Enhancements of existing ioctls can happen and depend on additional flags to be set. Zeroed unused space is commonly understood as a mechanism to communicate the compatibility between kernel and userspace and thus zeroing is really important. In exceptional cases this is not enough and further flags need to be passed to distinguish between zero as implicit unused initialization and a valid zero value. Such cases are documented.

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

btrfs is part of btrfs-progs.  Please refer to the documentation at https://btrfs.readthedocs.io.

ioctl(2)

btrfs(5).