Debian Codegraph @

upstream/mageia-cauldron/man2/btrfs-ioctl.2

raw
1 '\" t
2 .\" Man page generated from reStructuredText.
3 .
4 .
5 .nr rst2man-indent-level 0
6 .
7 .de1 rstReportMargin
8 \\$1 \\n[an-margin]
9 level \\n[rst2man-indent-level]
10 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
11 -
12 \\n[rst2man-indent0]
13 \\n[rst2man-indent1]
14 \\n[rst2man-indent2]
15 ..
16 .de1 INDENT
17 .\" .rstReportMargin pre:
18 . RS \\$1
19 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
20 . nr rst2man-indent-level +1
21 .\" .rstReportMargin post:
22 ..
23 .de UNINDENT
24 . RE
25 .\" indent \\n[an-margin]
26 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
27 .nr rst2man-indent-level -1
28 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
29 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
30 ..
31 .TH "BTRFS-IOCTL" "2" "Mar 10, 2026" "6.19" "BTRFS"
32 .SH NAME
33 btrfs-ioctl \- documentation about btrfs ioctls
34 .SH NAME
35 .sp
36 btrfs\-ioctl \- documentation for the ioctl interface to btrfs
37 .SH DESCRIPTION
38 .sp
39 The ioctl() system call is a way how to request custom actions performed on a
40 filesystem beyond the standard interfaces (like syscalls). An ioctl is
41 specified by a number and an associated data structure that implement a
42 feature, usually not available in other filesystems. The number of ioctls grows
43 over time and in some cases get promoted to a VFS\-level ioctl once other
44 filesystems adopt the functionality. Backward compatibility is maintained
45 and a formerly private ioctl number could become available on the VFS level.
46 .SH OVERVIEW
47 .sp
48 The ioctls are defined by a number and associated with a data structure that
49 contains further information. All ioctls use file descriptor (\fIfd\fP) as a reference
50 point, it could be the filesystem or a directory inside the filesystem.
51 .sp
52 An ioctl can be used in the following schematic way:
53 .INDENT 0.0
54 .INDENT 3.5
55 .sp
56 .EX
57 struct btrfs_ioctl_args args;
58
59 memset(&args, 0, sizeof(args));
60 args.key = value;
61 ret = ioctl(fd, BTRFS_IOC_NUMBER, &args);
62 .EE
63 .UNINDENT
64 .UNINDENT
65 .sp
66 The \fIfd\fP is the entry point to the filesystem and for most ioctls it does not
67 matter which directory is that. A distinction between files and directories sometimes
68 matter, when it matters it\(aqs explicitly mentioned. The \fIargs\fP is the
69 associated data structure for the request. It\(aqs strongly recommended to
70 initialize the whole structure to zeros as this is future\-proof when the ioctl
71 gets further extensions. Not doing that could lead to mismatch of old userspace
72 and new kernel versions, or vice versa. The \fIBTRFS_IOC_NUMBER\fP is says which
73 operation should be done on the given arguments. Some ioctls take a specific
74 data structure, some of them share a common one, no argument structure ioctls
75 exist too. The data passed to an ioctl can be input, output or both.
76 .sp
77 The library \fIlibbtrfsutil\fP wraps a few ioctls for convenience. Using raw ioctls
78 is not discouraged but may be cumbersome though it does not need additional
79 library dependency. Backward compatibility is guaranteed and incompatible
80 changes usually lead to a new version of the ioctl. Enhancements of existing
81 ioctls can happen and depend on additional flags to be set. Zeroed unused
82 space is commonly understood as a mechanism to communicate the compatibility
83 between kernel and userspace and thus \fIzeroing is really important\fP\&. In exceptional
84 cases this is not enough and further flags need to be passed to distinguish
85 between zero as implicit unused initialization and a valid zero value. Such
86 cases are documented.
87 .sp
88 File descriptors of regular files are obtained by \fBint fd = open()\fP, directories
89 opened as \fBDIR *dir = opendir()\fP can be converted to the corresponding
90 file descriptor by \fBfd = dirfd(dir)\fP\&.
91 .SH LIST OF IOCTLS
92 .TS
93 box center;
94 l|l|l.
95 T{
96 Name
97 T} T{
98 Description
99 T} T{
100 Data
101 T}
102 _
103 T{
104 \fI\%BTRFS_IOC_SNAP_CREATE\fP
105 T} T{
106 (obsolete) create a snapshot of a subvolume
107 T} T{
108 \fI\%struct btrfs_ioctl_vol_args\fP
109 T}
110 _
111 T{
112 BTRFS_IOC_DEFRAG
113 T} T{
114 T} T{
115 T}
116 _
117 T{
118 BTRFS_IOC_RESIZE
119 T} T{
120 T} T{
121 T}
122 _
123 T{
124 \fI\%BTRFS_IOC_SCAN_DEV\fP
125 T} T{
126 scan and register a given device path with filesystem module
127 T} T{
128 \fI\%struct btrfs_ioctl_vol_args\fP
129 T}
130 _
131 T{
132 \fI\%BTRFS_IOC_SYNC\fP
133 T} T{
134 Sync the filesystem, possibly process queued up work
135 T} T{
136 NULL
137 T}
138 _
139 T{
140 BTRFS_IOC_CLONE
141 T} T{
142 T} T{
143 T}
144 _
145 T{
146 \fI\%BTRFS_IOC_ADD_DEV\fP
147 T} T{
148 add a device to the filesystem by path
149 T} T{
150 \fI\%struct btrfs_ioctl_vol_args\fP
151 T}
152 _
153 T{
154 \fI\%BTRFS_IOC_RM_DEV\fP
155 T} T{
156 delete a device from the filesystem by path
157 T} T{
158 \fI\%struct btrfs_ioctl_vol_args\fP
159 T}
160 _
161 T{
162 BTRFS_IOC_BALANCE
163 T} T{
164 T} T{
165 T}
166 _
167 T{
168 BTRFS_IOC_CLONE_RANGE
169 T} T{
170 T} T{
171 T}
172 _
173 T{
174 \fI\%BTRFS_IOC_SUBVOL_CREATE\fP
175 T} T{
176 (obsolete) create a subvolume
177 T} T{
178 \fI\%struct btrfs_ioctl_vol_args\fP
179 T}
180 _
181 T{
182 \fI\%BTRFS_IOC_SNAP_DESTROY\fP
183 T} T{
184 (obsolete) delete a subvolume
185 T} T{
186 \fI\%struct btrfs_ioctl_vol_args\fP
187 T}
188 _
189 T{
190 BTRFS_IOC_DEFRAG_RANGE
191 T} T{
192 T} T{
193 T}
194 _
195 T{
196 BTRFS_IOC_TREE_SEARCH
197 T} T{
198 T} T{
199 T}
200 _
201 T{
202 BTRFS_IOC_TREE_SEARCH_V2
203 T} T{
204 T} T{
205 T}
206 _
207 T{
208 \fI\%BTRFS_IOC_INO_LOOKUP\fP
209 T} T{
210 resolve inode number to path, or lookup containing subvolume id
211 T} T{
212 \fI\%struct btrfs_ioctl_ino_lookup_args\fP
213 T}
214 _
215 T{
216 \fI\%BTRFS_IOC_DEFAULT_SUBVOL\fP
217 T} T{
218 set the default subvolume id
219 T} T{
220 uint64_t
221 T}
222 _
223 T{
224 BTRFS_IOC_SPACE_INFO
225 T} T{
226 T} T{
227 T}
228 _
229 T{
230 BTRFS_IOC_START_SYNC
231 T} T{
232 T} T{
233 T}
234 _
235 T{
236 BTRFS_IOC_WAIT_SYNC
237 T} T{
238 T} T{
239 T}
240 _
241 T{
242 \fI\%BTRFS_IOC_SNAP_CREATE_V2\fP
243 T} T{
244 create a snapshot of a subvolume
245 T} T{
246 \fI\%struct btrfs_ioctl_vol_args_v2\fP
247 T}
248 _
249 T{
250 \fI\%BTRFS_IOC_SUBVOL_CREATE_V2\fP
251 T} T{
252 create a subvolume
253 T} T{
254 \fI\%struct btrfs_ioctl_vol_args_v2\fP
255 T}
256 _
257 T{
258 \fI\%BTRFS_IOC_SUBVOL_GETFLAGS\fP
259 T} T{
260 get flags of a subvolume
261 T} T{
262 uint64_t
263 T}
264 _
265 T{
266 \fI\%BTRFS_IOC_SUBVOL_SETFLAGS\fP
267 T} T{
268 set flags of a subvolume
269 T} T{
270 uint64_t
271 T}
272 _
273 T{
274 BTRFS_IOC_SCRUB
275 T} T{
276 T} T{
277 T}
278 _
279 T{
280 BTRFS_IOC_SCRUB_CANCEL
281 T} T{
282 T} T{
283 T}
284 _
285 T{
286 BTRFS_IOC_SCRUB_PROGRESS
287 T} T{
288 T} T{
289 T}
290 _
291 T{
292 \fI\%BTRFS_IOC_DEV_INFO\fP
293 T} T{
294 get information about a device (UUIDs, used size, total size)
295 T} T{
296 \fI\%struct btrfs_ioctl_dev_info_args\fP
297 T}
298 _
299 T{
300 \fI\%BTRFS_IOC_FS_INFO\fP
301 T} T{
302 get information about filesystem (device count, fsid, ...)
303 T} T{
304 \fI\%struct btrfs_ioctl_fs_info_args\fP
305 T}
306 _
307 T{
308 BTRFS_IOC_BALANCE_V2
309 T} T{
310 T} T{
311 T}
312 _
313 T{
314 BTRFS_IOC_BALANCE_CTL
315 T} T{
316 T} T{
317 T}
318 _
319 T{
320 BTRFS_IOC_BALANCE_PROGRESS
321 T} T{
322 T} T{
323 T}
324 _
325 T{
326 BTRFS_IOC_INO_PATHS
327 T} T{
328 T} T{
329 T}
330 _
331 T{
332 BTRFS_IOC_LOGICAL_INO
333 T} T{
334 T} T{
335 T}
336 _
337 T{
338 BTRFS_IOC_SET_RECEIVED_SUBVOL
339 T} T{
340 T} T{
341 T}
342 _
343 T{
344 BTRFS_IOC_SEND
345 T} T{
346 T} T{
347 T}
348 _
349 T{
350 BTRFS_IOC_DEVICES_READY
351 T} T{
352 T} T{
353 T}
354 _
355 T{
356 BTRFS_IOC_QUOTA_CTL
357 T} T{
358 T} T{
359 T}
360 _
361 T{
362 BTRFS_IOC_QGROUP_ASSIGN
363 T} T{
364 T} T{
365 T}
366 _
367 T{
368 BTRFS_IOC_QGROUP_CREATE
369 T} T{
370 T} T{
371 T}
372 _
373 T{
374 BTRFS_IOC_QGROUP_LIMIT
375 T} T{
376 T} T{
377 T}
378 _
379 T{
380 BTRFS_IOC_QUOTA_RESCAN
381 T} T{
382 T} T{
383 T}
384 _
385 T{
386 BTRFS_IOC_QUOTA_RESCAN_STATUS
387 T} T{
388 T} T{
389 T}
390 _
391 T{
392 BTRFS_IOC_QUOTA_RESCAN_WAIT
393 T} T{
394 T} T{
395 T}
396 _
397 T{
398 \fI\%BTRFS_IOC_GET_FSLABEL\fP
399 T} T{
400 read filesystem label
401 T} T{
402 char buffer[\fI\%BTRFS_LABEL_SIZE\fP]
403 T}
404 _
405 T{
406 \fI\%BTRFS_IOC_SET_FSLABEL\fP
407 T} T{
408 set the filesystem label
409 T} T{
410 char buffer[\fI\%BTRFS_LABEL_SIZE\fP]
411 T}
412 _
413 T{
414 BTRFS_IOC_GET_DEV_STATS
415 T} T{
416 T} T{
417 T}
418 _
419 T{
420 BTRFS_IOC_DEV_REPLACE
421 T} T{
422 T} T{
423 T}
424 _
425 T{
426 BTRFS_IOC_FILE_EXTENT_SAME
427 T} T{
428 T} T{
429 T}
430 _
431 T{
432 \fI\%BTRFS_IOC_GET_FEATURES\fP
433 T} T{
434 get features set on the filesystem
435 T} T{
436 \fI\%struct btrfs_ioctl_feature_flags\fP
437 T}
438 _
439 T{
440 \fI\%BTRFS_IOC_SET_FEATURES\fP
441 T} T{
442 set features on the filesystem
443 T} T{
444 \fI\%struct btrfs_ioctl_feature_flags\fP
445 T}
446 _
447 T{
448 \fI\%BTRFS_IOC_GET_SUPPORTED_FEATURES\fP
449 T} T{
450 get available filesystem feature sets
451 T} T{
452 \fI\%struct btrfs_ioctl_feature_flags[3]\fP
453 T}
454 _
455 T{
456 BTRFS_IOC_RM_DEV_V2
457 T} T{
458 T} T{
459 T}
460 _
461 T{
462 BTRFS_IOC_LOGICAL_INO_V2
463 T} T{
464 T} T{
465 T}
466 _
467 T{
468 \fI\%BTRFS_IOC_GET_SUBVOL_INFO\fP
469 T} T{
470 get information about a subvolume
471 T} T{
472 \fI\%struct btrfs_ioctl_get_subvol_info_args\fP
473 T}
474 _
475 T{
476 BTRFS_IOC_GET_SUBVOL_ROOTREF
477 T} T{
478 T} T{
479 T}
480 _
481 T{
482 BTRFS_IOC_INO_LOOKUP_USER
483 T} T{
484 T} T{
485 T}
486 _
487 T{
488 \fI\%BTRFS_IOC_SNAP_DESTROY_V2\fP
489 T} T{
490 destroy a (snapshot or regular) subvolume
491 T} T{
492 \fI\%struct btrfs_ioctl_vol_args_v2\fP
493 T}
494 _
495 T{
496 BTRFS_IOC_ENCODED_READ
497 T} T{
498 T} T{
499 T}
500 _
501 T{
502 BTRFS_IOC_ENCODED_WRITE
503 T} T{
504 T} T{
505 T}
506 _
507 T{
508 \fI\%BTRFS_IOC_SUBVOL_SYNC_WAIT\fP
509 T} T{
510 Wait until a deleted subvolume is cleaned or query the state.
511 T} T{
512 \fI\%struct btrfs_ioctl_subvol_wait\fP
513 T}
514 .TE
515 .SH DATA STRUCTURES AND DEFINITIONS
516 .INDENT 0.0
517 .INDENT 3.5
518 .sp
519 .EX
520 struct btrfs_ioctl_vol_args {
521 __s64 fd;
522 char name[BTRFS_PATH_NAME_MAX + 1];
523 };
524 .EE
525 .UNINDENT
526 .UNINDENT
527 .INDENT 0.0
528 .INDENT 3.5
529 .sp
530 .EX
531 #define BTRFS_SUBVOL_RDONLY (1ULL << 1)
532 #define BTRFS_SUBVOL_QGROUP_INHERIT (1ULL << 2)
533 #define BTRFS_DEVICE_SPEC_BY_ID (1ULL << 3)
534 #define BTRFS_SUBVOL_SPEC_BY_ID (1ULL << 4)
535
536 struct btrfs_ioctl_vol_args_v2 {
537 __s64 fd;
538 __u64 transid;
539 __u64 flags;
540 union {
541 struct {
542 __u64 size;
543 struct btrfs_qgroup_inherit __user *qgroup_inherit;
544 };
545 __u64 unused[4];
546 };
547 union {
548 char name[BTRFS_SUBVOL_NAME_MAX + 1];
549 __u64 devid;
550 __u64 subvolid;
551 };
552 };
553 .EE
554 .UNINDENT
555 .UNINDENT
556 .INDENT 0.0
557 .INDENT 3.5
558 .sp
559 .EX
560 #define BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE (1ULL << 0)
561 /*
562 * Older kernels (< 4.9) on big\-endian systems produced broken free space tree
563 * bitmaps, and btrfs\-progs also used to corrupt the free space tree (versions
564 * < 4.7.3). If this bit is clear, then the free space tree cannot be trusted.
565 * btrfs\-progs can also intentionally clear this bit to ask the kernel to
566 * rebuild the free space tree, however this might not work on older kernels
567 * that do not know about this bit. If not sure, clear the cache manually on
568 * first mount when booting older kernel versions.
569 */
570 #define BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID (1ULL << 1)
571 #define BTRFS_FEATURE_COMPAT_RO_VERITY (1ULL << 2)
572 #define BTRFS_FEATURE_COMPAT_RO_BLOCK_GROUP_TREE (1ULL << 3)
573
574 #define BTRFS_FEATURE_INCOMPAT_MIXED_BACKREF (1ULL << 0)
575 #define BTRFS_FEATURE_INCOMPAT_DEFAULT_SUBVOL (1ULL << 1)
576 #define BTRFS_FEATURE_INCOMPAT_MIXED_GROUPS (1ULL << 2)
577 #define BTRFS_FEATURE_INCOMPAT_COMPRESS_LZO (1ULL << 3)
578 #define BTRFS_FEATURE_INCOMPAT_COMPRESS_ZSTD (1ULL << 4)
579 #define BTRFS_FEATURE_INCOMPAT_BIG_METADATA (1ULL << 5)
580 #define BTRFS_FEATURE_INCOMPAT_EXTENDED_IREF (1ULL << 6)
581 #define BTRFS_FEATURE_INCOMPAT_RAID56 (1ULL << 7)
582 #define BTRFS_FEATURE_INCOMPAT_SKINNY_METADATA (1ULL << 8)
583 #define BTRFS_FEATURE_INCOMPAT_NO_HOLES (1ULL << 9)
584 #define BTRFS_FEATURE_INCOMPAT_METADATA_UUID (1ULL << 10)
585 #define BTRFS_FEATURE_INCOMPAT_RAID1C34 (1ULL << 11)
586 #define BTRFS_FEATURE_INCOMPAT_ZONED (1ULL << 12)
587 #define BTRFS_FEATURE_INCOMPAT_EXTENT_TREE_V2 (1ULL << 13)
588 #define BTRFS_FEATURE_INCOMPAT_RAID_STRIPE_TREE (1ULL << 14)
589 #define BTRFS_FEATURE_INCOMPAT_SIMPLE_QUOTA (1ULL << 16)
590
591 struct btrfs_ioctl_feature_flags {
592 __u64 compat_flags;
593 __u64 compat_ro_flags;
594 __u64 incompat_flags;
595 };
596 .EE
597 .UNINDENT
598 .UNINDENT
599 .INDENT 0.0
600 .INDENT 3.5
601 .sp
602 .EX
603 struct btrfs_ioctl_get_subvol_info_args {
604 /* Id of this subvolume */
605 __u64 treeid;
606
607 /* Name of this subvolume, used to get the real name at mount point */
608 char name[BTRFS_VOL_NAME_MAX + 1];
609
610 /*
611 * Id of the subvolume which contains this subvolume.
612 * Zero for top\-level subvolume or a deleted subvolume.
613 */
614 __u64 parent_id;
615
616 /*
617 * Inode number of the directory which contains this subvolume.
618 * Zero for top\-level subvolume or a deleted subvolume
619 */
620 __u64 dirid;
621
622 /* Latest transaction id of this subvolume */
623 __u64 generation;
624
625 /* Flags of this subvolume */
626 __u64 flags;
627
628 /* UUID of this subvolume */
629 __u8 uuid[BTRFS_UUID_SIZE];
630
631 /*
632 * UUID of the subvolume of which this subvolume is a snapshot.
633 * All zero for a non\-snapshot subvolume.
634 */
635 __u8 parent_uuid[BTRFS_UUID_SIZE];
636
637 /*
638 * UUID of the subvolume from which this subvolume was received.
639 * All zero for non\-received subvolume.
640 */
641 __u8 received_uuid[BTRFS_UUID_SIZE];
642
643 /* Transaction id indicating when change/create/send/receive happened */
644 __u64 ctransid;
645 __u64 otransid;
646 __u64 stransid;
647 __u64 rtransid;
648 /* Time corresponding to c/o/s/rtransid */
649 struct btrfs_ioctl_timespec ctime;
650 struct btrfs_ioctl_timespec otime;
651 struct btrfs_ioctl_timespec stime;
652 struct btrfs_ioctl_timespec rtime;
653
654 /* Must be zero */
655 __u64 reserved[8];
656 };
657 .EE
658 .UNINDENT
659 .UNINDENT
660 .INDENT 0.0
661 .INDENT 3.5
662 .sp
663 .EX
664 #define BTRFS_QGROUP_INHERIT_SET_LIMITS (1ULL << 0)
665
666 struct btrfs_qgroup_inherit {
667 __u64 flags;
668 __u64 num_qgroups;
669 __u64 num_ref_copies;
670 __u64 num_excl_copies;
671 struct btrfs_qgroup_limit lim;
672 __u64 qgroups[];
673 };
674 .EE
675 .UNINDENT
676 .UNINDENT
677 .INDENT 0.0
678 .INDENT 3.5
679 .sp
680 .EX
681 #define BTRFS_QGROUP_LIMIT_MAX_RFER (1ULL << 0)
682 #define BTRFS_QGROUP_LIMIT_MAX_EXCL (1ULL << 1)
683 #define BTRFS_QGROUP_LIMIT_RSV_RFER (1ULL << 2)
684 #define BTRFS_QGROUP_LIMIT_RSV_EXCL (1ULL << 3)
685 #define BTRFS_QGROUP_LIMIT_RFER_CMPR (1ULL << 4)
686 #define BTRFS_QGROUP_LIMIT_EXCL_CMPR (1ULL << 5)
687
688 struct btrfs_qgroup_limit {
689 __u64 flags;
690 __u64 max_rfer;
691 __u64 max_excl;
692 __u64 rsv_rfer;
693 __u64 rsv_excl;
694 };
695 .EE
696 .UNINDENT
697 .UNINDENT
698 .INDENT 0.0
699 .INDENT 3.5
700 .sp
701 .EX
702 struct btrfs_ioctl_dev_info_args {
703 __u64 devid; /* in/out */
704 __u8 uuid[BTRFS_UUID_SIZE]; /* in/out */
705 __u64 bytes_used; /* out */
706 __u64 total_bytes; /* out */
707 /*
708 * Optional, out.
709 *
710 * Showing the fsid of the device, allowing user space to check if this
711 * device is a seeding one.
712 *
713 * Introduced in v6.3, thus user space still needs to check if kernel
714 * changed this value. Older kernel will not touch the values here.
715 */
716 __u8 fsid[BTRFS_UUID_SIZE];
717 __u64 unused[377]; /* pad to 4k */
718 __u8 path[BTRFS_DEVICE_PATH_NAME_MAX]; /* out */
719 };
720 .EE
721 .UNINDENT
722 .UNINDENT
723 .INDENT 0.0
724 .INDENT 3.5
725 .sp
726 .EX
727 /* Request information about checksum type and size */
728 #define BTRFS_FS_INFO_FLAG_CSUM_INFO (1U << 0)
729 /* Request information about filesystem generation */
730 #define BTRFS_FS_INFO_FLAG_GENERATION (1U << 1)
731 /* Request information about filesystem metadata UUID */
732 #define BTRFS_FS_INFO_FLAG_METADATA_UUID (1U << 2)
733
734 struct btrfs_ioctl_fs_info_args {
735 __u64 max_id; /* out */
736 __u64 num_devices; /* out */
737 __u8 fsid[BTRFS_FSID_SIZE]; /* out */
738 __u32 nodesize; /* out */
739 __u32 sectorsize; /* out */
740 __u32 clone_alignment; /* out */
741 /* See BTRFS_FS_INFO_FLAG_* */
742 __u16 csum_type; /* out */
743 __u16 csum_size; /* out */
744 __u64 flags; /* in/out */
745 __u64 generation; /* out */
746 __u8 metadata_uuid[BTRFS_FSID_SIZE]; /* out */
747 __u8 reserved[944]; /* pad to 1k */
748 };
749 .EE
750 .UNINDENT
751 .UNINDENT
752 .INDENT 0.0
753 .INDENT 3.5
754 .sp
755 .EX
756 #define BTRFS_INO_LOOKUP_PATH_MAX 4080
757
758 struct btrfs_ioctl_ino_lookup_args {
759 __u64 treeid;
760 __u64 objectid;
761 char name[BTRFS_INO_LOOKUP_PATH_MAX];
762 };
763 .EE
764 .UNINDENT
765 .UNINDENT
766 .INDENT 0.0
767 .INDENT 3.5
768 .sp
769 .EX
770 /* Specify the subvolid. */
771 #define BTRFS_SUBVOL_SYNC_WAIT_FOR_ONE (0)
772 /* Wait for all currently queued. */
773 #define BTRFS_SUBVOL_SYNC_WAIT_FOR_QUEUED (1)
774 /* Count number of queued subvolumes. */
775 #define BTRFS_SUBVOL_SYNC_COUNT (2)
776 /*
777 * Read which is the first in the queue (to be cleaned or being cleaned already),
778 * or 0 if the queue is empty.
779 */
780 #define BTRFS_SUBVOL_SYNC_PEEK_FIRST (3)
781 /* Read the last subvolid in the queue, or 0 if the queue is empty. */
782 #define BTRFS_SUBVOL_SYNC_PEEK_LAST (4)
783
784 struct btrfs_ioctl_subvol_wait {
785 __u64 subvolid;
786 __u32 mode;
787 __u32 count;
788 };
789 .EE
790 .UNINDENT
791 .UNINDENT
792 .TS
793 box center;
794 l|l.
795 T{
796 Constant name
797 T} T{
798 Value
799 T}
800 _
801 T{
802 BTRFS_UUID_SIZE
803 T} T{
804 16
805 T}
806 _
807 T{
808 BTRFS_FSID_SIZE
809 T} T{
810 16
811 T}
812 _
813 T{
814 BTRFS_SUBVOL_NAME_MAX
815 T} T{
816 4039
817 T}
818 _
819 T{
820 BTRFS_PATH_NAME_MAX
821 T} T{
822 4087
823 T}
824 _
825 T{
826 BTRFS_VOL_NAME_MAX
827 T} T{
828 255
829 T}
830 _
831 T{
832 BTRFS_LABEL_SIZE
833 T} T{
834 256
835 T}
836 _
837 T{
838 BTRFS_FIRST_FREE_OBJECTID
839 T} T{
840 256
841 T}
842 .TE
843 .SH DETAILED DESCRIPTION
844 .SS BTRFS_IOC_SNAP_CREATE
845 .sp
846 \fBNOTE:\fP
847 .INDENT 0.0
848 .INDENT 3.5
849 obsoleted by \fI\%BTRFS_IOC_SNAP_CREATE_V2\fP
850 .UNINDENT
851 .UNINDENT
852 .sp
853 \fI(since: 3.0, obsoleted: 4.0)\fP Create a snapshot of a subvolume.
854 .TS
855 box center;
856 l|l.
857 T{
858 Field
859 T} T{
860 Description
861 T}
862 _
863 T{
864 ioctl fd
865 T} T{
866 file descriptor of the parent directory of the new subvolume
867 T}
868 _
869 T{
870 ioctl args
871 T} T{
872 \fI\%struct btrfs_ioctl_vol_args\fP
873 T}
874 _
875 T{
876 args.fd
877 T} T{
878 file descriptor of any directory inside the subvolume to snapshot,
879 must be on the same filesystem
880 T}
881 _
882 T{
883 args.name
884 T} T{
885 name of the subvolume, although the buffer can be almost 4KiB, the file
886 size is limited by Linux VFS to 255 characters and must not contain a slash
887 (\(aq/\(aq)
888 T}
889 .TE
890 .SS BTRFS_IOC_SCAN_DEV
891 .sp
892 Scan and register a given device in the filesystem module, which can be later
893 used for automatic device and filesystem association at mount time. This
894 operates on the control device, not files from a mounted filesystem.
895 Can be safely called repeatedly with same device path.
896 .TS
897 box center;
898 l|l.
899 T{
900 Field
901 T} T{
902 Description
903 T}
904 _
905 T{
906 ioctl fd
907 T} T{
908 file descriptor of the control device \fB/dev/btrfs\-control\fP
909 T}
910 _
911 T{
912 ioctl args
913 T} T{
914 \fI\%struct btrfs_ioctl_vol_args\fP
915 T}
916 _
917 T{
918 args.fd
919 T} T{
920 ignored
921 T}
922 _
923 T{
924 args.name
925 T} T{
926 full path of the device
927 T}
928 .TE
929 .SS BTRFS_IOC_SYNC
930 .sp
931 Sync the filesystem data as would \fBsync()\fP syscall do, additionally
932 wake up the internal transaction thread that may trigger actions like
933 subvolume cleaning or queued defragmentation.
934 .TS
935 box center;
936 l|l.
937 T{
938 Field
939 T} T{
940 Description
941 T}
942 _
943 T{
944 ioctl fd
945 T} T{
946 file descriptor of any file or directory in the filesystem
947 T}
948 _
949 T{
950 ioctl args
951 T} T{
952 NULL
953 T}
954 .TE
955 .SS BTRFS_IOC_ADD_DEV
956 .sp
957 Add a given block device to the filesystem. Unlike the command \fBbtrfs device add\fP
958 there\(aqs are no safety checks (like existence of another filesystem on the
959 device), device preparation (like TRIM or zone reset), so use it with care.
960 .sp
961 This is a filesystem\-exclusive operation and it will fail if there\(aqs another
962 one already running, with one exception, when there\(aqs a paused balance.
963 .sp
964 Required permissions: CAP_SYS_ADMIN
965 .TS
966 box center;
967 l|l.
968 T{
969 Field
970 T} T{
971 Description
972 T}
973 _
974 T{
975 ioctl fd
976 T} T{
977 file descriptor of any file or directory in the filesystem
978 T}
979 _
980 T{
981 ioctl args
982 T} T{
983 \fI\%struct btrfs_ioctl_vol_args\fP
984 T}
985 _
986 T{
987 args.fd
988 T} T{
989 ignored
990 T}
991 _
992 T{
993 args.name
994 T} T{
995 full path of the block device to be added
996 T}
997 .TE
998 .SS BTRFS_IOC_RM_DEV
999 .sp
1000 Remove a device from the filesystem specified by it\(aqs path, or cancel
1001 a running device deletion by special path \fBcancel\fP\&.
1002 .sp
1003 This is a filesystem\-exclusive operation and it will fail if there\(aqs another
1004 one already running.
1005 .sp
1006 Required permissions: CAP_SYS_ADMIN
1007 .TS
1008 box center;
1009 l|l.
1010 T{
1011 Field
1012 T} T{
1013 Description
1014 T}
1015 _
1016 T{
1017 ioctl fd
1018 T} T{
1019 file descriptor of any file or directory in the filesystem
1020 T}
1021 _
1022 T{
1023 ioctl args
1024 T} T{
1025 \fI\%struct btrfs_ioctl_vol_args\fP
1026 T}
1027 _
1028 T{
1029 args.fd
1030 T} T{
1031 ignored
1032 T}
1033 _
1034 T{
1035 args.name
1036 T} T{
1037 full path of the block device to be deleted or string \fI\(dqcancel\(dq\fP
1038 T}
1039 .TE
1040 .SS BTRFS_IOC_SUBVOL_CREATE
1041 .sp
1042 \fBNOTE:\fP
1043 .INDENT 0.0
1044 .INDENT 3.5
1045 obsoleted by \fI\%BTRFS_IOC_SUBVOL_CREATE_V2\fP
1046 .UNINDENT
1047 .UNINDENT
1048 .sp
1049 \fI(since: 3.0, obsoleted: 4.0)\fP Create a subvolume.
1050 .TS
1051 box center;
1052 l|l.
1053 T{
1054 Field
1055 T} T{
1056 Description
1057 T}
1058 _
1059 T{
1060 ioctl fd
1061 T} T{
1062 file descriptor of the parent directory of the new subvolume
1063 T}
1064 _
1065 T{
1066 ioctl args
1067 T} T{
1068 \fI\%struct btrfs_ioctl_vol_args\fP
1069 T}
1070 _
1071 T{
1072 args.fd
1073 T} T{
1074 ignored
1075 T}
1076 _
1077 T{
1078 args.name
1079 T} T{
1080 name of the subvolume, although the buffer can be almost 4KiB, the file
1081 size is limited by Linux VFS to 255 characters and must not contain a slash
1082 (\(aq/\(aq)
1083 T}
1084 .TE
1085 .SS BTRFS_IOC_SNAP_DESTROY
1086 .sp
1087 \fBNOTE:\fP
1088 .INDENT 0.0
1089 .INDENT 3.5
1090 obsoleted by \fI\%BTRFS_IOC_SNAP_DESTROY_V2\fP
1091 .UNINDENT
1092 .UNINDENT
1093 .sp
1094 \fI(since: 2.6.33, obsoleted: 5.7)\fP Delete a subvolume.
1095 .TS
1096 box center;
1097 l|l.
1098 T{
1099 Field
1100 T} T{
1101 Description
1102 T}
1103 _
1104 T{
1105 ioctl fd
1106 T} T{
1107 file descriptor of the parent directory of the new subvolume
1108 T}
1109 _
1110 T{
1111 ioctl args
1112 T} T{
1113 \fI\%struct btrfs_ioctl_vol_args\fP
1114 T}
1115 _
1116 T{
1117 args.fd
1118 T} T{
1119 ignored
1120 T}
1121 _
1122 T{
1123 args.name
1124 T} T{
1125 name of the subvolume, although the buffer can be almost 4KiB, the file
1126 size is limited by Linux VFS to 255 characters and must not contain a slash
1127 (\(aq/\(aq)
1128 T}
1129 .TE
1130 .SS BTRFS_IOC_INO_LOOKUP
1131 .sp
1132 Resolve inode number to a path (requires CAP_SYS_ADMIN), or read a containing
1133 subvolume id of the given file (unrestricted, special case). The size of the
1134 path name buffer is shorter than \fIPATH_MAX\fP (4096), it\(aqs possible that the path
1135 is trimmed due to that. Also implemented by
1136 \fI\%btrfs inspect\-internal rootid\fP\&.
1137 .sp
1138 The general case needs CAP_SYS_ADMIN and can resolve any file to its path.
1139 The special case for reading the containing subvolume is not restricted:
1140 .INDENT 0.0
1141 .INDENT 3.5
1142 .sp
1143 .EX
1144 struct btrfs_ioctl_ino_lookup_args args;
1145
1146 fd = open(\(dqfile\(dq, ...);
1147 args.treeid = 0;
1148 args.objectid = BTRFS_FIRST_FREE_OBJECTID;
1149 ioctl(fd, BTRFS_IOC_INO_LOOKUP, &args);
1150 /* args.treeid now contains the subvolume id */
1151 .EE
1152 .UNINDENT
1153 .UNINDENT
1154 .TS
1155 box center;
1156 l|l.
1157 T{
1158 Field
1159 T} T{
1160 Description
1161 T}
1162 _
1163 T{
1164 ioctl fd
1165 T} T{
1166 file descriptor of the file or directory to lookup the subvolumeid
1167 T}
1168 _
1169 T{
1170 ioctl args
1171 T} T{
1172 \fI\%struct btrfs_ioctl_ino_lookup_args\fP
1173 T}
1174 _
1175 T{
1176 args.treeid
1177 T} T{
1178 subvolume id against which the path should be resolved (needs
1179 CAP_SYS_ADMIN), or 0 so the subvolume containing \fIfd\fP will be used
1180 T}
1181 _
1182 T{
1183 args.objectid
1184 T} T{
1185 inode number to lookup, \fIINODE_REF_KEY\fP with that key.objectid, or
1186 \fI\%BTRFS_FIRST_FREE_OBJECTID\fP as special case to
1187 read only the tree id and clear the \fIargs.name\fP buffer
1188 T}
1189 _
1190 T{
1191 args.name
1192 T} T{
1193 path relative to the toplevel subvolume, or empty string
1194 T}
1195 .TE
1196 .SS BTRFS_IOC_DEFAULT_SUBVOL
1197 .sp
1198 Set the given subvolume id as the default one when mounting the filesystem
1199 without \fIsubvol=path\fP or \fIsubvolid=id\fP options.
1200 .TS
1201 box center;
1202 l|l.
1203 T{
1204 Field
1205 T} T{
1206 Description
1207 T}
1208 _
1209 T{
1210 ioctl fd
1211 T} T{
1212 file descriptor of the directory inside which to create the new snapshot
1213 T}
1214 _
1215 T{
1216 ioctl args
1217 T} T{
1218 numeric value of subvolume to become default (uint64_t)
1219 T}
1220 .TE
1221 .SS BTRFS_IOC_SNAP_CREATE_V2
1222 .sp
1223 Create a snapshot of a subvolume.
1224 .TS
1225 box center;
1226 l|l.
1227 T{
1228 Field
1229 T} T{
1230 Description
1231 T}
1232 _
1233 T{
1234 ioctl fd
1235 T} T{
1236 file descriptor of the directory inside which to create the new snapshot
1237 T}
1238 _
1239 T{
1240 ioctl args
1241 T} T{
1242 \fI\%struct btrfs_ioctl_vol_args_v2\fP
1243 T}
1244 _
1245 T{
1246 args.fd
1247 T} T{
1248 file descriptor of any directory inside the subvolume to snapshot,
1249 must be on the filesystem
1250 T}
1251 _
1252 T{
1253 args.transid
1254 T} T{
1255 ignored
1256 T}
1257 _
1258 T{
1259 args.flags
1260 T} T{
1261 any subset of \fIBTRFS_SUBVOL_RDONLY\fP to make the new snapshot read\-only,
1262 or \fIBTRFS_SUBVOL_QGROUP_INHERIT\fP to apply the \fIqgroup_inherit\fP field
1263 T}
1264 _
1265 T{
1266 args.name
1267 T} T{
1268 the name, under the ioctl fd, for the new subvolume
1269 T}
1270 .TE
1271 .SS BTRFS_IOC_SUBVOL_CREATE_V2
1272 .sp
1273 \fI(since: 3.6)\fP Create a subvolume, qgroup inheritance and limits can be specified.
1274 .TS
1275 box center;
1276 l|l.
1277 T{
1278 Field
1279 T} T{
1280 Description
1281 T}
1282 _
1283 T{
1284 ioctl fd
1285 T} T{
1286 file descriptor of the parent directory of the new subvolume
1287 T}
1288 _
1289 T{
1290 ioctl args
1291 T} T{
1292 \fI\%struct btrfs_ioctl_vol_args_v2\fP
1293 T}
1294 _
1295 T{
1296 args.fd
1297 T} T{
1298 ignored
1299 T}
1300 _
1301 T{
1302 args.transid
1303 T} T{
1304 ignored
1305 T}
1306 _
1307 T{
1308 args.flags
1309 T} T{
1310 flags to set on the subvolume, \fBBTRFS_SUBVOL_RDONLY\fP for readonly,
1311 \fBBTRFS_SUBVOL_QGROUP_INHERIT\fP if the qgroup related fields should be
1312 processed
1313 T}
1314 _
1315 T{
1316 args.size
1317 T} T{
1318 number of entries in \fBargs.qgroup_inherit\fP
1319 T}
1320 _
1321 T{
1322 args.qgroup_inherit
1323 T} T{
1324 inherit the given qgroups
1325 (\fI\%struct btrfs_qgroup_inherit\fP) and
1326 limits (\fI\%struct btrfs_qgroup_limit\fP)
1327 T}
1328 _
1329 T{
1330 name
1331 T} T{
1332 name of the subvolume, although the buffer can be almost 4KiB, the file
1333 size is limited by Linux VFS to 255 characters and must not contain a
1334 slash (\(aq/\(aq)
1335 T}
1336 .TE
1337 .SS BTRFS_IOC_SUBVOL_GETFLAGS
1338 .sp
1339 Read the flags of a subvolume. The returned flags are either 0 or
1340 \fIBTRFS_SUBVOL_RDONLY\fP\&.
1341 .TS
1342 box center;
1343 l|l.
1344 T{
1345 Field
1346 T} T{
1347 Description
1348 T}
1349 _
1350 T{
1351 ioctl fd
1352 T} T{
1353 file descriptor of the subvolume to examine
1354 T}
1355 _
1356 T{
1357 ioctl args
1358 T} T{
1359 uint64_t
1360 T}
1361 .TE
1362 .SS BTRFS_IOC_SUBVOL_SETFLAGS
1363 .sp
1364 Change the flags of a subvolume.
1365 .TS
1366 box center;
1367 l|l.
1368 T{
1369 Field
1370 T} T{
1371 Description
1372 T}
1373 _
1374 T{
1375 ioctl fd
1376 T} T{
1377 file descriptor of the subvolume to modify
1378 T}
1379 _
1380 T{
1381 ioctl args
1382 T} T{
1383 uint64_t, either 0 or \fIBTRFS_SUBVOL_RDONLY\fP
1384 T}
1385 .TE
1386 .SS BTRFS_IOC_GET_FSLABEL
1387 .sp
1388 Read the label of the filesystem into a given buffer. Alternatively it
1389 can be read from \fB/sys/fs/btrfs/FSID/label\fP though it requires to
1390 know the FSID of the filesystem.
1391 .TS
1392 box center;
1393 l|l.
1394 T{
1395 Field
1396 T} T{
1397 Description
1398 T}
1399 _
1400 T{
1401 ioctl fd
1402 T} T{
1403 file descriptor of any file/directory in the filesystem
1404 T}
1405 _
1406 T{
1407 ioctl args
1408 T} T{
1409 char buffer[\fI\%BTRFS_LABEL_SIZE\fP]
1410 T}
1411 .TE
1412 .SS BTRFS_IOC_SET_FSLABEL
1413 .sp
1414 Set the label of filesystem from given buffer. The maximum length also accounts
1415 for terminating NUL character. Alternatively it can be also set by writing to
1416 \fB/sys/fs/btrfs/FSID/label\fP though it requires to know the FSID of the
1417 filesystem (and an explicit commit before the change is permanent).
1418 .sp
1419 Required permissions: CAP_SYS_ADMIN
1420 .TS
1421 box center;
1422 l|l.
1423 T{
1424 Field
1425 T} T{
1426 Description
1427 T}
1428 _
1429 T{
1430 ioctl fd
1431 T} T{
1432 file descriptor of any file/directory in the filesystem
1433 T}
1434 _
1435 T{
1436 ioctl args
1437 T} T{
1438 char buffer[\fI\%BTRFS_LABEL_SIZE\fP]
1439 T}
1440 .TE
1441 .SS BTRFS_IOC_DEV_INFO
1442 .sp
1443 Read some basic information about a device, requested by the \fIdevid\fP or \fIdevice UUID\fP\&.
1444 .TS
1445 box center;
1446 l|l.
1447 T{
1448 Field
1449 T} T{
1450 Description
1451 T}
1452 _
1453 T{
1454 ioctl fd
1455 T} T{
1456 file descriptor of any file/directory in the filesystem
1457 T}
1458 _
1459 T{
1460 ioctl args
1461 T} T{
1462 \fI\%struct btrfs_ioctl_dev_info_args\fP
1463 T}
1464 .TE
1465 .SS BTRFS_IOC_FS_INFO
1466 .sp
1467 Read internal information about the filesystem. The data can be exchanged
1468 both ways and part of the structure could be optionally filled. The reserved
1469 bytes can be used to get new kind of information in the future, always
1470 depending on the flags set.
1471 .TS
1472 box center;
1473 l|l.
1474 T{
1475 Field
1476 T} T{
1477 Description
1478 T}
1479 _
1480 T{
1481 ioctl fd
1482 T} T{
1483 file descriptor of any file/directory in the filesystem
1484 T}
1485 _
1486 T{
1487 ioctl args
1488 T} T{
1489 \fI\%struct btrfs_ioctl_fs_info_args\fP
1490 T}
1491 .TE
1492 .SS BTRFS_IOC_GET_FEATURES
1493 .sp
1494 Get the actually set feature bits on the filesystem (the bits are stored in the
1495 super block). There are three sets related to backward compatibility:
1496 .INDENT 0.0
1497 .IP \(bu 2
1498 incompat: not backward compatible, mount on older kernel will fail.
1499 .IP \(bu 2
1500 compat_ro: backward compatible for read\-only mount.
1501 .IP \(bu 2
1502 compat: backward compatible with read\-write support, only marked as as individual feature.
1503 .UNINDENT
1504 .TS
1505 box center;
1506 l|l.
1507 T{
1508 Field
1509 T} T{
1510 Description
1511 T}
1512 _
1513 T{
1514 ioctl fd
1515 T} T{
1516 file descriptor of the subvolume to examine
1517 T}
1518 _
1519 T{
1520 ioctl args
1521 T} T{
1522 \fI\%struct btrfs_ioctl_feature_flags\fP
1523 T}
1524 .TE
1525 .sp
1526 If a bit is set then there may be some data structures on the filesystem of the
1527 related feature, but not necessarily.
1528 .sp
1529 Some of the features are turned on automatically when used,
1530 e.g. compression or when a balance filter converts to yet unused block group
1531 profile. In some cases the feature can be turned on or off by \fI\%btrfstune(8)\fP\&.
1532 .SS BTRFS_IOC_SET_FEATURES
1533 .sp
1534 Set a feature bit on the filesystem if possible. Some features may require
1535 extensive changes, new data structures or conversion (like free\-space\-tree).
1536 Bits representing possible existence of data structures related to the feature
1537 can be set without actually creating anything, e.g. ZSTD compressed extents.
1538 .TS
1539 box center;
1540 l|l.
1541 T{
1542 Field
1543 T} T{
1544 Description
1545 T}
1546 _
1547 T{
1548 ioctl fd
1549 T} T{
1550 file descriptor of the subvolume to examine
1551 T}
1552 _
1553 T{
1554 ioctl args
1555 T} T{
1556 \fI\%struct btrfs_ioctl_feature_flags\fP
1557 T}
1558 .TE
1559 .SS BTRFS_IOC_GET_SUPPORTED_FEATURES
1560 .sp
1561 Get feature sets supported by the kernel module, in three groups:
1562 .INDENT 0.0
1563 .IP \(bu 2
1564 supported: (index 0) all supported compat/compat_ro/incompat features
1565 .IP \(bu 2
1566 safe to set: (index 1) features that can be enabled on a mounted filesystem
1567 .IP \(bu 2
1568 safe to clear: (index 2) features that can be disabled on a mounted filesystem
1569 .UNINDENT
1570 .sp
1571 The features are also listed in \fB/sys/fs/btrfs/features\fP\&.
1572 .TS
1573 box center;
1574 l|l.
1575 T{
1576 Field
1577 T} T{
1578 Description
1579 T}
1580 _
1581 T{
1582 ioctl fd
1583 T} T{
1584 file descriptor of the subvolume to examine
1585 T}
1586 _
1587 T{
1588 ioctl args
1589 T} T{
1590 \fI\%struct btrfs_ioctl_feature_flags[3]\fP
1591 T}
1592 .TE
1593 .SS BTRFS_IOC_GET_SUBVOL_INFO
1594 .sp
1595 Get information about a subvolume.
1596 .TS
1597 box center;
1598 l|l.
1599 T{
1600 Field
1601 T} T{
1602 Description
1603 T}
1604 _
1605 T{
1606 ioctl fd
1607 T} T{
1608 file descriptor of the subvolume to examine
1609 T}
1610 _
1611 T{
1612 ioctl args
1613 T} T{
1614 \fI\%struct btrfs_ioctl_get_subvol_info_args\fP
1615 T}
1616 .TE
1617 .SS BTRFS_IOC_SNAP_DESTROY_V2
1618 .sp
1619 Destroy a subvolume, which may or may not be a snapshot.
1620 .TS
1621 box center;
1622 l|l.
1623 T{
1624 Field
1625 T} T{
1626 Description
1627 T}
1628 _
1629 T{
1630 ioctl fd
1631 T} T{
1632 if \fIflags\fP does not include \fIBTRFS_SUBVOL_SPEC_BY_ID\fP, or if executing
1633 in a non\-root user namespace, file descriptor of the parent directory
1634 containing the subvolume to delete; otherwise, file descriptor of any
1635 directory on the same filesystem as the subvolume to delete, but not
1636 within the same subvolume
1637 T}
1638 _
1639 T{
1640 ioctl args
1641 T} T{
1642 \fI\%struct btrfs_ioctl_vol_args_v2\fP
1643 T}
1644 _
1645 T{
1646 args.fd
1647 T} T{
1648 ignored
1649 T}
1650 _
1651 T{
1652 args.transid
1653 T} T{
1654 ignored
1655 T}
1656 _
1657 T{
1658 args.flags
1659 T} T{
1660 0 if the \fIname\fP field identifies the subvolume by name in the specified
1661 directory, or \fIBTRFS_SUBVOL_SPEC_BY_ID\fP if the \fIsubvolid\fP field
1662 specifies the ID of the subvolume
1663 T}
1664 _
1665 T{
1666 args.name
1667 T} T{
1668 only if \fIflags\fP does not contain \fIBTRFS_SUBVOL_SPEC_BY_ID\fP, the name
1669 (within the directory identified by \fIfd\fP) of the subvolume to delete
1670 T}
1671 _
1672 T{
1673 args.subvolid
1674 T} T{
1675 only if \fIflags\fP contains \fIBTRFS_SUBVOL_SPEC_BY_ID\fP, the subvolume ID of
1676 the subvolume to delete
1677 T}
1678 .TE
1679 .SS BTRFS_IOC_SUBVOL_SYNC_WAIT
1680 .sp
1681 \fI(since: 6.13)\fP Wait until a deleted subvolume is cleaned or query the state.
1682 .sp
1683 There are several modes of operation, where the most common ones are to
1684 wait on a specific subvolume or all currently queued for cleaning. This
1685 is utilized e.g. in backup applications that delete subvolumes and wait
1686 until they\(aqre cleaned to check for remaining space.
1687 .sp
1688 The other modes are for flexibility, e.g. for monitoring or checkpoints in the
1689 queue of deleted subvolumes, again without the need to use SEARCH_TREE.
1690 .sp
1691 Notes:
1692 .INDENT 0.0
1693 .IP \(bu 2
1694 waiting is interruptible, the timeout is set to 1 second and is not
1695 configurable
1696 .IP \(bu 2
1697 repeated calls to the ioctl see a different state, so this is inherently racy
1698 when using e.g. the count or peek next/last
1699 .UNINDENT
1700 .sp
1701 Use cases (\fI\%definition of constants\fP):
1702 .INDENT 0.0
1703 .IP \(bu 2
1704 a subvolume A was deleted, wait for cleaning (WAIT_FOR_ONE)
1705 .IP \(bu 2
1706 a bunch of subvolumes were deleted, wait for all (WAIT_FOR_QUEUED or
1707 PEEK_LAST + WAIT_FOR_ONE)
1708 .IP \(bu 2
1709 count how many are queued (not blocking), for monitoring purposes
1710 .IP \(bu 2
1711 report progress (PEEK_NEXT), may miss some if cleaning is quick
1712 .IP \(bu 2
1713 own waiting in user space (PEEK_LAST until it\(aqs 0)
1714 .UNINDENT
1715 .TS
1716 box center;
1717 l|l.
1718 T{
1719 Field
1720 T} T{
1721 Description
1722 T}
1723 _
1724 T{
1725 ioctl fd
1726 T} T{
1727 file descriptor of any file or directory in the filesystem
1728 T}
1729 _
1730 T{
1731 ioctl args
1732 T} T{
1733 \fI\%struct btrfs_ioctl_subvol_wait\fP
1734 T}
1735 _
1736 T{
1737 args.subvolid
1738 T} T{
1739 Depending on the mode, the numeric id of subvolume to wait for, or
1740 the one queried by \fIPEEK\fP modes
1741 T}
1742 _
1743 T{
1744 args.mode
1745 T} T{
1746 mode of operation described above
1747 T}
1748 _
1749 T{
1750 args.count
1751 T} T{
1752 if \fImode\fP is set to \fICOUNT\fP the number of subvolumes queued for cleaning
1753 T}
1754 .TE
1755 .SH AVAILABILITY
1756 .sp
1757 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
1758 \X'tty: link https://btrfs.readthedocs.io'\fI\%https://btrfs.readthedocs.io\fP\X'tty: link'\&.
1759 .SH SEE ALSO
1760 .sp
1761 \X'tty: link https://man7.org/linux/man-pages/man2/ioctl.2.html'\fI\%ioctl(2)\fP\X'tty: link'
1762 .\" Generated by docutils manpage writer.
1763 .