@@ -25,91 +25,130 @@ DATA STRUCTURES AND DEFINITIONS
2525
2626.. code-block :: c
2727
28- struct btrfs_ioctl_vol_args {
29- __s64 fd;
30- char name[BTRFS_PATH_NAME_MAX + 1];
31- };
28+ struct btrfs_ioctl_vol_args {
29+ __s64 fd;
30+ char name[BTRFS_PATH_NAME_MAX + 1];
31+ };
3232
3333struct_btrfs_ioctl_vol_args_v2 :
3434
3535.. code-block :: c
3636
37- struct btrfs_ioctl_vol_args_v2 {
38- __s64 fd;
39- __u64 transid;
40- __u64 flags;
41- union {
42- struct {
43- __u64 size;
44- struct btrfs_qgroup_inherit __user *qgroup_inherit;
45- };
46- __u64 unused[4];
47- };
48- union {
49- char name[BTRFS_SUBVOL_NAME_MAX + 1];
50- __u64 devid;
51- __u64 subvolid;
52- };
53- };
37+ #define BTRFS_SUBVOL_RDONLY (1ULL << 1)
38+ #define BTRFS_SUBVOL_QGROUP_INHERIT (1ULL << 2)
39+ #define BTRFS_DEVICE_SPEC_BY_ID (1ULL << 3)
40+ #define BTRFS_SUBVOL_SPEC_BY_ID (1ULL << 4)
41+
42+ struct btrfs_ioctl_vol_args_v2 {
43+ __s64 fd;
44+ __u64 transid;
45+ __u64 flags;
46+ union {
47+ struct {
48+ __u64 size;
49+ struct btrfs_qgroup_inherit __user *qgroup_inherit;
50+ };
51+ __u64 unused[4];
52+ };
53+ union {
54+ char name[BTRFS_SUBVOL_NAME_MAX + 1];
55+ __u64 devid;
56+ __u64 subvolid;
57+ };
58+ };
5459
5560struct_btrfs_ioctl_get_subvol_info_args :
5661
5762.. code-block :: c
5863
59- struct btrfs_ioctl_get_subvol_info_args {
60- /* Id of this subvolume */
61- __u64 treeid;
62-
63- /* Name of this subvolume, used to get the real name at mount point */
64- char name[BTRFS_VOL_NAME_MAX + 1];
65-
66- /*
67- * Id of the subvolume which contains this subvolume.
68- * Zero for top-level subvolume or a deleted subvolume.
69- */
70- __u64 parent_id;
71-
72- /*
73- * Inode number of the directory which contains this subvolume.
74- * Zero for top-level subvolume or a deleted subvolume
75- */
76- __u64 dirid;
77-
78- /* Latest transaction id of this subvolume */
79- __u64 generation;
80-
81- /* Flags of this subvolume */
82- __u64 flags;
83-
84- /* UUID of this subvolume */
85- __u8 uuid[BTRFS_UUID_SIZE];
86-
87- /*
88- * UUID of the subvolume of which this subvolume is a snapshot.
89- * All zero for a non-snapshot subvolume.
90- */
91- __u8 parent_uuid[BTRFS_UUID_SIZE];
92-
93- /*
94- * UUID of the subvolume from which this subvolume was received.
95- * All zero for non-received subvolume.
96- */
97- __u8 received_uuid[BTRFS_UUID_SIZE];
98-
99- /* Transaction id indicating when change/create/send/receive happened */
100- __u64 ctransid;
101- __u64 otransid;
102- __u64 stransid;
103- __u64 rtransid;
104- /* Time corresponding to c/o/s/rtransid */
105- struct btrfs_ioctl_timespec ctime;
106- struct btrfs_ioctl_timespec otime;
107- struct btrfs_ioctl_timespec stime;
108- struct btrfs_ioctl_timespec rtime;
109-
110- /* Must be zero */
111- __u64 reserved[8];
112- };
64+ struct btrfs_ioctl_get_subvol_info_args {
65+ /* Id of this subvolume */
66+ __u64 treeid;
67+
68+ /* Name of this subvolume, used to get the real name at mount point */
69+ char name[BTRFS_VOL_NAME_MAX + 1];
70+
71+ /*
72+ * Id of the subvolume which contains this subvolume.
73+ * Zero for top-level subvolume or a deleted subvolume.
74+ */
75+ __u64 parent_id;
76+
77+ /*
78+ * Inode number of the directory which contains this subvolume.
79+ * Zero for top-level subvolume or a deleted subvolume
80+ */
81+ __u64 dirid;
82+
83+ /* Latest transaction id of this subvolume */
84+ __u64 generation;
85+
86+ /* Flags of this subvolume */
87+ __u64 flags;
88+
89+ /* UUID of this subvolume */
90+ __u8 uuid[BTRFS_UUID_SIZE];
91+
92+ /*
93+ * UUID of the subvolume of which this subvolume is a snapshot.
94+ * All zero for a non-snapshot subvolume.
95+ */
96+ __u8 parent_uuid[BTRFS_UUID_SIZE];
97+
98+ /*
99+ * UUID of the subvolume from which this subvolume was received.
100+ * All zero for non-received subvolume.
101+ */
102+ __u8 received_uuid[BTRFS_UUID_SIZE];
103+
104+ /* Transaction id indicating when change/create/send/receive happened */
105+ __u64 ctransid;
106+ __u64 otransid;
107+ __u64 stransid;
108+ __u64 rtransid;
109+ /* Time corresponding to c/o/s/rtransid */
110+ struct btrfs_ioctl_timespec ctime;
111+ struct btrfs_ioctl_timespec otime;
112+ struct btrfs_ioctl_timespec stime;
113+ struct btrfs_ioctl_timespec rtime;
114+
115+ /* Must be zero */
116+ __u64 reserved[8];
117+ };
118+
119+ struct_btrfs_qgroup_inherit :
120+
121+ .. code-block :: c
122+
123+ #define BTRFS_QGROUP_INHERIT_SET_LIMITS (1ULL << 0)
124+
125+ struct btrfs_qgroup_inherit {
126+ __u64 flags;
127+ __u64 num_qgroups;
128+ __u64 num_ref_copies;
129+ __u64 num_excl_copies;
130+ struct btrfs_qgroup_limit lim;
131+ __u64 qgroups[];
132+ };
133+
134+ struct_btrfs_qgroup_limit :
135+
136+ .. code-block :: c
137+
138+ #define BTRFS_QGROUP_LIMIT_MAX_RFER (1ULL << 0)
139+ #define BTRFS_QGROUP_LIMIT_MAX_EXCL (1ULL << 1)
140+ #define BTRFS_QGROUP_LIMIT_RSV_RFER (1ULL << 2)
141+ #define BTRFS_QGROUP_LIMIT_RSV_EXCL (1ULL << 3)
142+ #define BTRFS_QGROUP_LIMIT_RFER_CMPR (1ULL << 4)
143+ #define BTRFS_QGROUP_LIMIT_EXCL_CMPR (1ULL << 5)
144+
145+ struct btrfs_qgroup_limit {
146+ __u64 flags;
147+ __u64 max_rfer;
148+ __u64 max_excl;
149+ __u64 rsv_rfer;
150+ __u64 rsv_excl;
151+ };
113152
114153list-table ::
115154 :header-rows: 1
@@ -150,7 +189,7 @@ The 'BTRFS_IOC_NUMBER' is says which operation should be done on the given
150189arguments. Some ioctls take a specific data structure, some of them share a
151190common one, no argument structure ioctls exist too.
152191
153- The library ' libbtrfsutil' wraps a few ioctls for convenience. Using raw ioctls
192+ The library * libbtrfsutil * wraps a few ioctls for convenience. Using raw ioctls
154193is not discouraged but may be cumbersome though it does not need additional
155194library dependency. Backward compatibility is guaranteed and incompatible
156195changes usually lead to a new version of the ioctl. Enhancements of existing
@@ -174,8 +213,8 @@ LIST OF IOCTLS
174213 - (obsolete) create a subvolume
175214 - :ref: `struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args> `
176215 * - BTRFS_IOC_SNAP_CREATE
177- -
178- -
216+ - (obsolete) create a snapshot of a subvolume
217+ - :ref: ` struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args> `
179218 * - BTRFS_IOC_DEFRAG
180219 -
181220 -
@@ -185,9 +224,9 @@ LIST OF IOCTLS
185224 * - BTRFS_IOC_SCAN_DEV
186225 -
187226 -
188- * - BTRFS_IOC_SYNC
189- -
190- -
227+ * - :ref: ` BTRFS_IOC_SYNC<BTRFS_IOC_SYNC> `
228+ - Sync the filesystem, possibly process queued up work
229+ - NULL
191230 * - BTRFS_IOC_CLONE
192231 -
193232 -
@@ -375,6 +414,50 @@ BTRFS_IOC_SUBVOL_CREATE
375414 size is limited by Linux VFS to 255 characters and must not contain a slash
376415 ('/')
377416
417+ BTRFS_IOC_SNAP_CREATE
418+ ~~~~~~~~~~~~~~~~~~~~~
419+
420+ .. note ::
421+ obsoleted by :ref: `BTRFS_IOC_SNAP_CREATE_V2<BTRFS_IOC_SNAP_CREATE_V2> `
422+
423+ *(since: 3.0, obsoleted: 4.0) * Create a snapshot of a subvolume.
424+
425+ .. list-table ::
426+ :header-rows: 1
427+
428+ * - Field
429+ - Description
430+ * - ioctl fd
431+ - file descriptor of the parent directory of the new subvolume
432+ * - ioctl args
433+ - :ref: `struct btrfs_ioctl_vol_args<struct_btrfs_ioctl_vol_args> `
434+ * - args.fd
435+ - file descriptor of any directory inside the subvolume to snapshot,
436+ must be on the same filesystem
437+ * - args.name
438+ - name of the subvolume, although the buffer can be almost 4k, the file
439+ size is limited by Linux VFS to 255 characters and must not contain a slash
440+ ('/')
441+
442+ .. _BTRFS_IOC_SYNC :
443+
444+ BTRFS_IOC_SYNC
445+ ~~~~~~~~~~~~~~
446+
447+ Sync the filesystem data as would ``sync() `` syscall do, additionally
448+ wake up the internal transaction thread that may trigger actions like
449+ subvolume cleaning or queued defragmentation.
450+
451+ .. list-table ::
452+ :header-rows: 1
453+
454+ * - Field
455+ - Description
456+ * - ioctl fd
457+ - file descriptor of any file or directory in the filesystem
458+ * - ioctl args
459+ - NULL
460+
378461.. _BTRFS_IOC_SNAP_CREATE_V2 :
379462
380463BTRFS_IOC_SNAP_CREATE_V2
@@ -392,7 +475,8 @@ Create a snapshot of a subvolume.
392475 * - ioctl args
393476 - :ref: `struct btrfs_ioctl_vol_args_v2<struct_btrfs_ioctl_vol_args_v2> `
394477 * - args.fd
395- - file descriptor of any directory inside the subvolume to snapshot
478+ - file descriptor of any directory inside the subvolume to snapshot,
479+ must be on the filesystem
396480 * - args.transid
397481 - ignored
398482 * - args.flags
@@ -406,7 +490,7 @@ Create a snapshot of a subvolume.
406490BTRFS_IOC_SUBVOL_CREATE_V2
407491~~~~~~~~~~~~~~~~~~~~~~~~~~
408492
409- *(since: 3.6) * Create a subvolume, qgroup inheritance can be specified.
493+ *(since: 3.6) * Create a subvolume, qgroup inheritance and limits can be specified.
410494
411495.. list-table ::
412496 :header-rows: 1
@@ -422,17 +506,19 @@ BTRFS_IOC_SUBVOL_CREATE_V2
422506 * - args.transid
423507 - ignored
424508 * - args.flags
425- - ignored
509+ - flags to set on the subvolume, ``BTRFS_SUBVOL_RDONLY `` for readonly,
510+ ``BTRFS_SUBVOL_QGROUP_INHERIT `` if the qgroup related fileds should be
511+ processed
426512 * - args.size
427- - ...
513+ - number of entries in `` args.qgroup_inherit ``
428514 * - args.qgroup_inherit
429- - ...
515+ - inherit the given qgroups
516+ (:ref: `struct btrfs_qgroup_inherit<struct_btrfs_qgroup_inherit> `) and
517+ limits (:ref: `struct btrfs_qgroup_limit<struct_btrfs_qgroup_limit> `)
430518 * - name
431519 - name of the subvolume, although the buffer can be almost 4k, the file
432520 size is limited by Linux VFS to 255 characters and must not contain a
433521 slash ('/')
434- * - devid
435- - ...
436522
437523.. _BTRFS_IOC_SUBVOL_GETFLAGS :
438524
0 commit comments