Debian Codegraph @

upstream/debian-unstable/man2/btrfs-ioctl.2

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