Debian Codegraph @

upstream/debian-trixie/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" "May 18, 2026" "7.0" "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 _
515 T{
516 \fI\%BTRFS_IOC_SHUTDOWN\fP
517 T} T{
518 Force filesystem IO shutdown and turn it read\-only.
519 T} T{
520 uint64_t
521 T}
522 .TE
523 .SH DATA STRUCTURES AND DEFINITIONS
524 .INDENT 0.0
525 .INDENT 3.5
526 .sp
527 .EX
528 struct btrfs_ioctl_vol_args {
529 __s64 fd;
530 char name[BTRFS_PATH_NAME_MAX + 1];
531 };
532 .EE
533 .UNINDENT
534 .UNINDENT
535 .INDENT 0.0
536 .INDENT 3.5
537 .sp
538 .EX
539 #define BTRFS_SUBVOL_RDONLY (1ULL << 1)
540 #define BTRFS_SUBVOL_QGROUP_INHERIT (1ULL << 2)
541 #define BTRFS_DEVICE_SPEC_BY_ID (1ULL << 3)
542 #define BTRFS_SUBVOL_SPEC_BY_ID (1ULL << 4)
543
544 struct btrfs_ioctl_vol_args_v2 {
545 __s64 fd;
546 __u64 transid;
547 __u64 flags;
548 union {
549 struct {
550 __u64 size;
551 struct btrfs_qgroup_inherit __user *qgroup_inherit;
552 };
553 __u64 unused[4];
554 };
555 union {
556 char name[BTRFS_SUBVOL_NAME_MAX + 1];
557 __u64 devid;
558 __u64 subvolid;
559 };
560 };
561 .EE
562 .UNINDENT
563 .UNINDENT
564 .INDENT 0.0
565 .INDENT 3.5
566 .sp
567 .EX
568 #define BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE (1ULL << 0)
569 /*
570 * Older kernels (< 4.9) on big\-endian systems produced broken free space tree
571 * bitmaps, and btrfs\-progs also used to corrupt the free space tree (versions
572 * < 4.7.3). If this bit is clear, then the free space tree cannot be trusted.
573 * btrfs\-progs can also intentionally clear this bit to ask the kernel to
574 * rebuild the free space tree, however this might not work on older kernels
575 * that do not know about this bit. If not sure, clear the cache manually on
576 * first mount when booting older kernel versions.
577 */
578 #define BTRFS_FEATURE_COMPAT_RO_FREE_SPACE_TREE_VALID (1ULL << 1)
579 #define BTRFS_FEATURE_COMPAT_RO_VERITY (1ULL << 2)
580 #define BTRFS_FEATURE_COMPAT_RO_BLOCK_GROUP_TREE (1ULL << 3)
581
582 #define BTRFS_FEATURE_INCOMPAT_MIXED_BACKREF (1ULL << 0)
583 #define BTRFS_FEATURE_INCOMPAT_DEFAULT_SUBVOL (1ULL << 1)
584 #define BTRFS_FEATURE_INCOMPAT_MIXED_GROUPS (1ULL << 2)
585 #define BTRFS_FEATURE_INCOMPAT_COMPRESS_LZO (1ULL << 3)
586 #define BTRFS_FEATURE_INCOMPAT_COMPRESS_ZSTD (1ULL << 4)
587 #define BTRFS_FEATURE_INCOMPAT_BIG_METADATA (1ULL << 5)
588 #define BTRFS_FEATURE_INCOMPAT_EXTENDED_IREF (1ULL << 6)
589 #define BTRFS_FEATURE_INCOMPAT_RAID56 (1ULL << 7)
590 #define BTRFS_FEATURE_INCOMPAT_SKINNY_METADATA (1ULL << 8)
591 #define BTRFS_FEATURE_INCOMPAT_NO_HOLES (1ULL << 9)
592 #define BTRFS_FEATURE_INCOMPAT_METADATA_UUID (1ULL << 10)
593 #define BTRFS_FEATURE_INCOMPAT_RAID1C34 (1ULL << 11)
594 #define BTRFS_FEATURE_INCOMPAT_ZONED (1ULL << 12)
595 #define BTRFS_FEATURE_INCOMPAT_EXTENT_TREE_V2 (1ULL << 13)
596 #define BTRFS_FEATURE_INCOMPAT_RAID_STRIPE_TREE (1ULL << 14)
597 #define BTRFS_FEATURE_INCOMPAT_SIMPLE_QUOTA (1ULL << 16)
598
599 struct btrfs_ioctl_feature_flags {
600 __u64 compat_flags;
601 __u64 compat_ro_flags;
602 __u64 incompat_flags;
603 };
604 .EE
605 .UNINDENT
606 .UNINDENT
607 .INDENT 0.0
608 .INDENT 3.5
609 .sp
610 .EX
611 struct btrfs_ioctl_get_subvol_info_args {
612 /* Id of this subvolume */
613 __u64 treeid;
614
615 /* Name of this subvolume, used to get the real name at mount point */
616 char name[BTRFS_VOL_NAME_MAX + 1];
617
618 /*
619 * Id of the subvolume which contains this subvolume.
620 * Zero for top\-level subvolume or a deleted subvolume.
621 */
622 __u64 parent_id;
623
624 /*
625 * Inode number of the directory which contains this subvolume.
626 * Zero for top\-level subvolume or a deleted subvolume
627 */
628 __u64 dirid;
629
630 /* Latest transaction id of this subvolume */
631 __u64 generation;
632
633 /* Flags of this subvolume */
634 __u64 flags;
635
636 /* UUID of this subvolume */
637 __u8 uuid[BTRFS_UUID_SIZE];
638
639 /*
640 * UUID of the subvolume of which this subvolume is a snapshot.
641 * All zero for a non\-snapshot subvolume.
642 */
643 __u8 parent_uuid[BTRFS_UUID_SIZE];
644
645 /*
646 * UUID of the subvolume from which this subvolume was received.
647 * All zero for non\-received subvolume.
648 */
649 __u8 received_uuid[BTRFS_UUID_SIZE];
650
651 /* Transaction id indicating when change/create/send/receive happened */
652 __u64 ctransid;
653 __u64 otransid;
654 __u64 stransid;
655 __u64 rtransid;
656 /* Time corresponding to c/o/s/rtransid */
657 struct btrfs_ioctl_timespec ctime;
658 struct btrfs_ioctl_timespec otime;
659 struct btrfs_ioctl_timespec stime;
660 struct btrfs_ioctl_timespec rtime;
661
662 /* Must be zero */
663 __u64 reserved[8];
664 };
665 .EE
666 .UNINDENT
667 .UNINDENT
668 .INDENT 0.0
669 .INDENT 3.5
670 .sp
671 .EX
672 #define BTRFS_QGROUP_INHERIT_SET_LIMITS (1ULL << 0)
673
674 struct btrfs_qgroup_inherit {
675 __u64 flags;
676 __u64 num_qgroups;
677 __u64 num_ref_copies;
678 __u64 num_excl_copies;
679 struct btrfs_qgroup_limit lim;
680 __u64 qgroups[];
681 };
682 .EE
683 .UNINDENT
684 .UNINDENT
685 .INDENT 0.0
686 .INDENT 3.5
687 .sp
688 .EX
689 #define BTRFS_QGROUP_LIMIT_MAX_RFER (1ULL << 0)
690 #define BTRFS_QGROUP_LIMIT_MAX_EXCL (1ULL << 1)
691 #define BTRFS_QGROUP_LIMIT_RSV_RFER (1ULL << 2)
692 #define BTRFS_QGROUP_LIMIT_RSV_EXCL (1ULL << 3)
693 #define BTRFS_QGROUP_LIMIT_RFER_CMPR (1ULL << 4)
694 #define BTRFS_QGROUP_LIMIT_EXCL_CMPR (1ULL << 5)
695
696 struct btrfs_qgroup_limit {
697 __u64 flags;
698 __u64 max_rfer;
699 __u64 max_excl;
700 __u64 rsv_rfer;
701 __u64 rsv_excl;
702 };
703 .EE
704 .UNINDENT
705 .UNINDENT
706 .INDENT 0.0
707 .INDENT 3.5
708 .sp
709 .EX
710 struct btrfs_ioctl_dev_info_args {
711 __u64 devid; /* in/out */
712 __u8 uuid[BTRFS_UUID_SIZE]; /* in/out */
713 __u64 bytes_used; /* out */
714 __u64 total_bytes; /* out */
715 /*
716 * Optional, out.
717 *
718 * Showing the fsid of the device, allowing user space to check if this
719 * device is a seeding one.
720 *
721 * Introduced in v6.3, thus user space still needs to check if kernel
722 * changed this value. Older kernel will not touch the values here.
723 */
724 __u8 fsid[BTRFS_UUID_SIZE];
725 __u64 unused[377]; /* pad to 4k */
726 __u8 path[BTRFS_DEVICE_PATH_NAME_MAX]; /* out */
727 };
728 .EE
729 .UNINDENT
730 .UNINDENT
731 .INDENT 0.0
732 .INDENT 3.5
733 .sp
734 .EX
735 /* Request information about checksum type and size */
736 #define BTRFS_FS_INFO_FLAG_CSUM_INFO (1U << 0)
737 /* Request information about filesystem generation */
738 #define BTRFS_FS_INFO_FLAG_GENERATION (1U << 1)
739 /* Request information about filesystem metadata UUID */
740 #define BTRFS_FS_INFO_FLAG_METADATA_UUID (1U << 2)
741
742 struct btrfs_ioctl_fs_info_args {
743 __u64 max_id; /* out */
744 __u64 num_devices; /* out */
745 __u8 fsid[BTRFS_FSID_SIZE]; /* out */
746 __u32 nodesize; /* out */
747 __u32 sectorsize; /* out */
748 __u32 clone_alignment; /* out */
749 /* See BTRFS_FS_INFO_FLAG_* */
750 __u16 csum_type; /* out */
751 __u16 csum_size; /* out */
752 __u64 flags; /* in/out */
753 __u64 generation; /* out */
754 __u8 metadata_uuid[BTRFS_FSID_SIZE]; /* out */
755 __u8 reserved[944]; /* pad to 1k */
756 };
757 .EE
758 .UNINDENT
759 .UNINDENT
760 .INDENT 0.0
761 .INDENT 3.5
762 .sp
763 .EX
764 #define BTRFS_INO_LOOKUP_PATH_MAX 4080
765
766 struct btrfs_ioctl_ino_lookup_args {
767 __u64 treeid;
768 __u64 objectid;
769 char name[BTRFS_INO_LOOKUP_PATH_MAX];
770 };
771 .EE
772 .UNINDENT
773 .UNINDENT
774 .INDENT 0.0
775 .INDENT 3.5
776 .sp
777 .EX
778 /* Specify the subvolid. */
779 #define BTRFS_SUBVOL_SYNC_WAIT_FOR_ONE (0)
780 /* Wait for all currently queued. */
781 #define BTRFS_SUBVOL_SYNC_WAIT_FOR_QUEUED (1)
782 /* Count number of queued subvolumes. */
783 #define BTRFS_SUBVOL_SYNC_COUNT (2)
784 /*
785 * Read which is the first in the queue (to be cleaned or being cleaned already),
786 * or 0 if the queue is empty.
787 */
788 #define BTRFS_SUBVOL_SYNC_PEEK_FIRST (3)
789 /* Read the last subvolid in the queue, or 0 if the queue is empty. */
790 #define BTRFS_SUBVOL_SYNC_PEEK_LAST (4)
791
792 struct btrfs_ioctl_subvol_wait {
793 __u64 subvolid;
794 __u32 mode;
795 __u32 count;
796 };
797 .EE
798 .UNINDENT
799 .UNINDENT
800 .TS
801 box center;
802 l|l.
803 T{
804 Constant name
805 T} T{
806 Value
807 T}
808 _
809 T{
810 BTRFS_UUID_SIZE
811 T} T{
812 16
813 T}
814 _
815 T{
816 BTRFS_FSID_SIZE
817 T} T{
818 16
819 T}
820 _
821 T{
822 BTRFS_SUBVOL_NAME_MAX
823 T} T{
824 4039
825 T}
826 _
827 T{
828 BTRFS_PATH_NAME_MAX
829 T} T{
830 4087
831 T}
832 _
833 T{
834 BTRFS_VOL_NAME_MAX
835 T} T{
836 255
837 T}
838 _
839 T{
840 BTRFS_LABEL_SIZE
841 T} T{
842 256
843 T}
844 _
845 T{
846 BTRFS_FIRST_FREE_OBJECTID
847 T} T{
848 256
849 T}
850 .TE
851 .SH DETAILED DESCRIPTION
852 .SS BTRFS_IOC_SNAP_CREATE
853 .sp
854 \fBNOTE:\fP
855 .INDENT 0.0
856 .INDENT 3.5
857 obsoleted by \fI\%BTRFS_IOC_SNAP_CREATE_V2\fP
858 .UNINDENT
859 .UNINDENT
860 .sp
861 \fI(since: 3.0, obsoleted: 4.0)\fP Create a snapshot of a subvolume.
862 .TS
863 box center;
864 l|l.
865 T{
866 Field
867 T} T{
868 Description
869 T}
870 _
871 T{
872 ioctl fd
873 T} T{
874 file descriptor of the parent directory of the new subvolume
875 T}
876 _
877 T{
878 ioctl args
879 T} T{
880 \fI\%struct btrfs_ioctl_vol_args\fP
881 T}
882 _
883 T{
884 args.fd
885 T} T{
886 file descriptor of any directory inside the subvolume to snapshot,
887 must be on the same filesystem
888 T}
889 _
890 T{
891 args.name
892 T} T{
893 name of the subvolume, although the buffer can be almost 4KiB, the file
894 size is limited by Linux VFS to 255 characters and must not contain a slash
895 (\(aq/\(aq)
896 T}
897 .TE
898 .SS BTRFS_IOC_SCAN_DEV
899 .sp
900 Scan and register a given device in the filesystem module, which can be later
901 used for automatic device and filesystem association at mount time. This
902 operates on the control device, not files from a mounted filesystem.
903 Can be safely called repeatedly with same device path.
904 .TS
905 box center;
906 l|l.
907 T{
908 Field
909 T} T{
910 Description
911 T}
912 _
913 T{
914 ioctl fd
915 T} T{
916 file descriptor of the control device \fB/dev/btrfs\-control\fP
917 T}
918 _
919 T{
920 ioctl args
921 T} T{
922 \fI\%struct btrfs_ioctl_vol_args\fP
923 T}
924 _
925 T{
926 args.fd
927 T} T{
928 ignored
929 T}
930 _
931 T{
932 args.name
933 T} T{
934 full path of the device
935 T}
936 .TE
937 .SS BTRFS_IOC_SYNC
938 .sp
939 Sync the filesystem data as would \fBsync()\fP syscall do, additionally
940 wake up the internal transaction thread that may trigger actions like
941 subvolume cleaning or queued defragmentation.
942 .TS
943 box center;
944 l|l.
945 T{
946 Field
947 T} T{
948 Description
949 T}
950 _
951 T{
952 ioctl fd
953 T} T{
954 file descriptor of any file or directory in the filesystem
955 T}
956 _
957 T{
958 ioctl args
959 T} T{
960 NULL
961 T}
962 .TE
963 .SS BTRFS_IOC_ADD_DEV
964 .sp
965 Add a given block device to the filesystem. Unlike the command \fBbtrfs device add\fP
966 there\(aqs are no safety checks (like existence of another filesystem on the
967 device), device preparation (like TRIM or zone reset), so use it with care.
968 .sp
969 This is a filesystem\-exclusive operation and it will fail if there\(aqs another
970 one already running, with one exception, when there\(aqs a paused balance.
971 .sp
972 Required permissions: CAP_SYS_ADMIN
973 .TS
974 box center;
975 l|l.
976 T{
977 Field
978 T} T{
979 Description
980 T}
981 _
982 T{
983 ioctl fd
984 T} T{
985 file descriptor of any file or directory in the filesystem
986 T}
987 _
988 T{
989 ioctl args
990 T} T{
991 \fI\%struct btrfs_ioctl_vol_args\fP
992 T}
993 _
994 T{
995 args.fd
996 T} T{
997 ignored
998 T}
999 _
1000 T{
1001 args.name
1002 T} T{
1003 full path of the block device to be added
1004 T}
1005 .TE
1006 .SS BTRFS_IOC_RM_DEV
1007 .sp
1008 Remove a device from the filesystem specified by it\(aqs path, or cancel
1009 a running device deletion by special path \fBcancel\fP\&.
1010 .sp
1011 This is a filesystem\-exclusive operation and it will fail if there\(aqs another
1012 one already running.
1013 .sp
1014 Required permissions: CAP_SYS_ADMIN
1015 .TS
1016 box center;
1017 l|l.
1018 T{
1019 Field
1020 T} T{
1021 Description
1022 T}
1023 _
1024 T{
1025 ioctl fd
1026 T} T{
1027 file descriptor of any file or directory in the filesystem
1028 T}
1029 _
1030 T{
1031 ioctl args
1032 T} T{
1033 \fI\%struct btrfs_ioctl_vol_args\fP
1034 T}
1035 _
1036 T{
1037 args.fd
1038 T} T{
1039 ignored
1040 T}
1041 _
1042 T{
1043 args.name
1044 T} T{
1045 full path of the block device to be deleted or string \fI\(dqcancel\(dq\fP
1046 T}
1047 .TE
1048 .SS BTRFS_IOC_SUBVOL_CREATE
1049 .sp
1050 \fBNOTE:\fP
1051 .INDENT 0.0
1052 .INDENT 3.5
1053 obsoleted by \fI\%BTRFS_IOC_SUBVOL_CREATE_V2\fP
1054 .UNINDENT
1055 .UNINDENT
1056 .sp
1057 \fI(since: 3.0, obsoleted: 4.0)\fP Create a subvolume.
1058 .TS
1059 box center;
1060 l|l.
1061 T{
1062 Field
1063 T} T{
1064 Description
1065 T}
1066 _
1067 T{
1068 ioctl fd
1069 T} T{
1070 file descriptor of the parent directory of the new subvolume
1071 T}
1072 _
1073 T{
1074 ioctl args
1075 T} T{
1076 \fI\%struct btrfs_ioctl_vol_args\fP
1077 T}
1078 _
1079 T{
1080 args.fd
1081 T} T{
1082 ignored
1083 T}
1084 _
1085 T{
1086 args.name
1087 T} T{
1088 name of the subvolume, although the buffer can be almost 4KiB, the file
1089 size is limited by Linux VFS to 255 characters and must not contain a slash
1090 (\(aq/\(aq)
1091 T}
1092 .TE
1093 .SS BTRFS_IOC_SNAP_DESTROY
1094 .sp
1095 \fBNOTE:\fP
1096 .INDENT 0.0
1097 .INDENT 3.5
1098 obsoleted by \fI\%BTRFS_IOC_SNAP_DESTROY_V2\fP
1099 .UNINDENT
1100 .UNINDENT
1101 .sp
1102 \fI(since: 2.6.33, obsoleted: 5.7)\fP Delete a subvolume.
1103 .TS
1104 box center;
1105 l|l.
1106 T{
1107 Field
1108 T} T{
1109 Description
1110 T}
1111 _
1112 T{
1113 ioctl fd
1114 T} T{
1115 file descriptor of the parent directory of the new subvolume
1116 T}
1117 _
1118 T{
1119 ioctl args
1120 T} T{
1121 \fI\%struct btrfs_ioctl_vol_args\fP
1122 T}
1123 _
1124 T{
1125 args.fd
1126 T} T{
1127 ignored
1128 T}
1129 _
1130 T{
1131 args.name
1132 T} T{
1133 name of the subvolume, although the buffer can be almost 4KiB, the file
1134 size is limited by Linux VFS to 255 characters and must not contain a slash
1135 (\(aq/\(aq)
1136 T}
1137 .TE
1138 .SS BTRFS_IOC_INO_LOOKUP
1139 .sp
1140 Resolve inode number to a path (requires CAP_SYS_ADMIN), or read a containing
1141 subvolume id of the given file (unrestricted, special case). The size of the
1142 path name buffer is shorter than \fIPATH_MAX\fP (4096), it\(aqs possible that the path
1143 is trimmed due to that. Also implemented by
1144 \fI\%btrfs inspect\-internal rootid\fP\&.
1145 .sp
1146 The general case needs CAP_SYS_ADMIN and can resolve any file to its path.
1147 The special case for reading the containing subvolume is not restricted:
1148 .INDENT 0.0
1149 .INDENT 3.5
1150 .sp
1151 .EX
1152 struct btrfs_ioctl_ino_lookup_args args;
1153
1154 fd = open(\(dqfile\(dq, ...);
1155 args.treeid = 0;
1156 args.objectid = BTRFS_FIRST_FREE_OBJECTID;
1157 ioctl(fd, BTRFS_IOC_INO_LOOKUP, &args);
1158 /* args.treeid now contains the subvolume id */
1159 .EE
1160 .UNINDENT
1161 .UNINDENT
1162 .TS
1163 box center;
1164 l|l.
1165 T{
1166 Field
1167 T} T{
1168 Description
1169 T}
1170 _
1171 T{
1172 ioctl fd
1173 T} T{
1174 file descriptor of the file or directory to lookup the subvolumeid
1175 T}
1176 _
1177 T{
1178 ioctl args
1179 T} T{
1180 \fI\%struct btrfs_ioctl_ino_lookup_args\fP
1181 T}
1182 _
1183 T{
1184 args.treeid
1185 T} T{
1186 subvolume id against which the path should be resolved (needs
1187 CAP_SYS_ADMIN), or 0 so the subvolume containing \fIfd\fP will be used
1188 T}
1189 _
1190 T{
1191 args.objectid
1192 T} T{
1193 inode number to lookup, \fIINODE_REF_KEY\fP with that key.objectid, or
1194 \fI\%BTRFS_FIRST_FREE_OBJECTID\fP as special case to
1195 read only the tree id and clear the \fIargs.name\fP buffer
1196 T}
1197 _
1198 T{
1199 args.name
1200 T} T{
1201 path relative to the toplevel subvolume, or empty string
1202 T}
1203 .TE
1204 .SS BTRFS_IOC_DEFAULT_SUBVOL
1205 .sp
1206 Set the given subvolume id as the default one when mounting the filesystem
1207 without \fIsubvol=path\fP or \fIsubvolid=id\fP options.
1208 .TS
1209 box center;
1210 l|l.
1211 T{
1212 Field
1213 T} T{
1214 Description
1215 T}
1216 _
1217 T{
1218 ioctl fd
1219 T} T{
1220 file descriptor of the directory inside which to create the new snapshot
1221 T}
1222 _
1223 T{
1224 ioctl args
1225 T} T{
1226 numeric value of subvolume to become default (uint64_t)
1227 T}
1228 .TE
1229 .SS BTRFS_IOC_SNAP_CREATE_V2
1230 .sp
1231 Create a snapshot of a subvolume.
1232 .TS
1233 box center;
1234 l|l.
1235 T{
1236 Field
1237 T} T{
1238 Description
1239 T}
1240 _
1241 T{
1242 ioctl fd
1243 T} T{
1244 file descriptor of the directory inside which to create the new snapshot
1245 T}
1246 _
1247 T{
1248 ioctl args
1249 T} T{
1250 \fI\%struct btrfs_ioctl_vol_args_v2\fP
1251 T}
1252 _
1253 T{
1254 args.fd
1255 T} T{
1256 file descriptor of any directory inside the subvolume to snapshot,
1257 must be on the filesystem
1258 T}
1259 _
1260 T{
1261 args.transid
1262 T} T{
1263 ignored
1264 T}
1265 _
1266 T{
1267 args.flags
1268 T} T{
1269 any subset of \fIBTRFS_SUBVOL_RDONLY\fP to make the new snapshot read\-only,
1270 or \fIBTRFS_SUBVOL_QGROUP_INHERIT\fP to apply the \fIqgroup_inherit\fP field
1271 T}
1272 _
1273 T{
1274 args.name
1275 T} T{
1276 the name, under the ioctl fd, for the new subvolume
1277 T}
1278 .TE
1279 .SS BTRFS_IOC_SUBVOL_CREATE_V2
1280 .sp
1281 \fI(since: 3.6)\fP Create a subvolume, qgroup inheritance and limits can be specified.
1282 .TS
1283 box center;
1284 l|l.
1285 T{
1286 Field
1287 T} T{
1288 Description
1289 T}
1290 _
1291 T{
1292 ioctl fd
1293 T} T{
1294 file descriptor of the parent directory of the new subvolume
1295 T}
1296 _
1297 T{
1298 ioctl args
1299 T} T{
1300 \fI\%struct btrfs_ioctl_vol_args_v2\fP
1301 T}
1302 _
1303 T{
1304 args.fd
1305 T} T{
1306 ignored
1307 T}
1308 _
1309 T{
1310 args.transid
1311 T} T{
1312 ignored
1313 T}
1314 _
1315 T{
1316 args.flags
1317 T} T{
1318 flags to set on the subvolume, \fBBTRFS_SUBVOL_RDONLY\fP for readonly,
1319 \fBBTRFS_SUBVOL_QGROUP_INHERIT\fP if the qgroup related fields should be
1320 processed
1321 T}
1322 _
1323 T{
1324 args.size
1325 T} T{
1326 number of entries in \fBargs.qgroup_inherit\fP
1327 T}
1328 _
1329 T{
1330 args.qgroup_inherit
1331 T} T{
1332 inherit the given qgroups
1333 (\fI\%struct btrfs_qgroup_inherit\fP) and
1334 limits (\fI\%struct btrfs_qgroup_limit\fP)
1335 T}
1336 _
1337 T{
1338 name
1339 T} T{
1340 name of the subvolume, although the buffer can be almost 4KiB, the file
1341 size is limited by Linux VFS to 255 characters and must not contain a
1342 slash (\(aq/\(aq)
1343 T}
1344 .TE
1345 .SS BTRFS_IOC_SUBVOL_GETFLAGS
1346 .sp
1347 Read the flags of a subvolume. The returned flags are either 0 or
1348 \fIBTRFS_SUBVOL_RDONLY\fP\&.
1349 .TS
1350 box center;
1351 l|l.
1352 T{
1353 Field
1354 T} T{
1355 Description
1356 T}
1357 _
1358 T{
1359 ioctl fd
1360 T} T{
1361 file descriptor of the subvolume to examine
1362 T}
1363 _
1364 T{
1365 ioctl args
1366 T} T{
1367 uint64_t
1368 T}
1369 .TE
1370 .SS BTRFS_IOC_SUBVOL_SETFLAGS
1371 .sp
1372 Change the flags of a subvolume.
1373 .TS
1374 box center;
1375 l|l.
1376 T{
1377 Field
1378 T} T{
1379 Description
1380 T}
1381 _
1382 T{
1383 ioctl fd
1384 T} T{
1385 file descriptor of the subvolume to modify
1386 T}
1387 _
1388 T{
1389 ioctl args
1390 T} T{
1391 uint64_t, either 0 or \fIBTRFS_SUBVOL_RDONLY\fP
1392 T}
1393 .TE
1394 .SS BTRFS_IOC_GET_FSLABEL
1395 .sp
1396 Read the label of the filesystem into a given buffer. Alternatively it
1397 can be read from \fB/sys/fs/btrfs/FSID/label\fP though it requires to
1398 know the FSID of the filesystem.
1399 .TS
1400 box center;
1401 l|l.
1402 T{
1403 Field
1404 T} T{
1405 Description
1406 T}
1407 _
1408 T{
1409 ioctl fd
1410 T} T{
1411 file descriptor of any file/directory in the filesystem
1412 T}
1413 _
1414 T{
1415 ioctl args
1416 T} T{
1417 char buffer[\fI\%BTRFS_LABEL_SIZE\fP]
1418 T}
1419 .TE
1420 .SS BTRFS_IOC_SET_FSLABEL
1421 .sp
1422 Set the label of filesystem from given buffer. The maximum length also accounts
1423 for terminating NUL character. Alternatively it can be also set by writing to
1424 \fB/sys/fs/btrfs/FSID/label\fP though it requires to know the FSID of the
1425 filesystem (and an explicit commit before the change is permanent).
1426 .sp
1427 Required permissions: CAP_SYS_ADMIN
1428 .TS
1429 box center;
1430 l|l.
1431 T{
1432 Field
1433 T} T{
1434 Description
1435 T}
1436 _
1437 T{
1438 ioctl fd
1439 T} T{
1440 file descriptor of any file/directory in the filesystem
1441 T}
1442 _
1443 T{
1444 ioctl args
1445 T} T{
1446 char buffer[\fI\%BTRFS_LABEL_SIZE\fP]
1447 T}
1448 .TE
1449 .SS BTRFS_IOC_DEV_INFO
1450 .sp
1451 Read some basic information about a device, requested by the \fIdevid\fP or \fIdevice UUID\fP\&.
1452 .TS
1453 box center;
1454 l|l.
1455 T{
1456 Field
1457 T} T{
1458 Description
1459 T}
1460 _
1461 T{
1462 ioctl fd
1463 T} T{
1464 file descriptor of any file/directory in the filesystem
1465 T}
1466 _
1467 T{
1468 ioctl args
1469 T} T{
1470 \fI\%struct btrfs_ioctl_dev_info_args\fP
1471 T}
1472 .TE
1473 .SS BTRFS_IOC_FS_INFO
1474 .sp
1475 Read internal information about the filesystem. The data can be exchanged
1476 both ways and part of the structure could be optionally filled. The reserved
1477 bytes can be used to get new kind of information in the future, always
1478 depending on the flags set.
1479 .TS
1480 box center;
1481 l|l.
1482 T{
1483 Field
1484 T} T{
1485 Description
1486 T}
1487 _
1488 T{
1489 ioctl fd
1490 T} T{
1491 file descriptor of any file/directory in the filesystem
1492 T}
1493 _
1494 T{
1495 ioctl args
1496 T} T{
1497 \fI\%struct btrfs_ioctl_fs_info_args\fP
1498 T}
1499 .TE
1500 .SS BTRFS_IOC_GET_FEATURES
1501 .sp
1502 Get the actually set feature bits on the filesystem (the bits are stored in the
1503 super block). There are three sets related to backward compatibility:
1504 .INDENT 0.0
1505 .IP \(bu 2
1506 incompat: not backward compatible, mount on older kernel will fail.
1507 .IP \(bu 2
1508 compat_ro: backward compatible for read\-only mount.
1509 .IP \(bu 2
1510 compat: backward compatible with read\-write support, only marked as as individual feature.
1511 .UNINDENT
1512 .TS
1513 box center;
1514 l|l.
1515 T{
1516 Field
1517 T} T{
1518 Description
1519 T}
1520 _
1521 T{
1522 ioctl fd
1523 T} T{
1524 file descriptor of the subvolume to examine
1525 T}
1526 _
1527 T{
1528 ioctl args
1529 T} T{
1530 \fI\%struct btrfs_ioctl_feature_flags\fP
1531 T}
1532 .TE
1533 .sp
1534 If a bit is set then there may be some data structures on the filesystem of the
1535 related feature, but not necessarily.
1536 .sp
1537 Some of the features are turned on automatically when used,
1538 e.g. compression or when a balance filter converts to yet unused block group
1539 profile. In some cases the feature can be turned on or off by \fI\%btrfstune(8)\fP\&.
1540 .SS BTRFS_IOC_SET_FEATURES
1541 .sp
1542 Set a feature bit on the filesystem if possible. Some features may require
1543 extensive changes, new data structures or conversion (like free\-space\-tree).
1544 Bits representing possible existence of data structures related to the feature
1545 can be set without actually creating anything, e.g. ZSTD compressed extents.
1546 .TS
1547 box center;
1548 l|l.
1549 T{
1550 Field
1551 T} T{
1552 Description
1553 T}
1554 _
1555 T{
1556 ioctl fd
1557 T} T{
1558 file descriptor of the subvolume to examine
1559 T}
1560 _
1561 T{
1562 ioctl args
1563 T} T{
1564 \fI\%struct btrfs_ioctl_feature_flags\fP
1565 T}
1566 .TE
1567 .SS BTRFS_IOC_GET_SUPPORTED_FEATURES
1568 .sp
1569 Get feature sets supported by the kernel module, in three groups:
1570 .INDENT 0.0
1571 .IP \(bu 2
1572 supported: (index 0) all supported compat/compat_ro/incompat features
1573 .IP \(bu 2
1574 safe to set: (index 1) features that can be enabled on a mounted filesystem
1575 .IP \(bu 2
1576 safe to clear: (index 2) features that can be disabled on a mounted filesystem
1577 .UNINDENT
1578 .sp
1579 The features are also listed in \fB/sys/fs/btrfs/features\fP\&.
1580 .TS
1581 box center;
1582 l|l.
1583 T{
1584 Field
1585 T} T{
1586 Description
1587 T}
1588 _
1589 T{
1590 ioctl fd
1591 T} T{
1592 file descriptor of the subvolume to examine
1593 T}
1594 _
1595 T{
1596 ioctl args
1597 T} T{
1598 \fI\%struct btrfs_ioctl_feature_flags[3]\fP
1599 T}
1600 .TE
1601 .SS BTRFS_IOC_GET_SUBVOL_INFO
1602 .sp
1603 Get information about a subvolume.
1604 .TS
1605 box center;
1606 l|l.
1607 T{
1608 Field
1609 T} T{
1610 Description
1611 T}
1612 _
1613 T{
1614 ioctl fd
1615 T} T{
1616 file descriptor of the subvolume to examine
1617 T}
1618 _
1619 T{
1620 ioctl args
1621 T} T{
1622 \fI\%struct btrfs_ioctl_get_subvol_info_args\fP
1623 T}
1624 .TE
1625 .SS BTRFS_IOC_SNAP_DESTROY_V2
1626 .sp
1627 Destroy a subvolume, which may or may not be a snapshot.
1628 .TS
1629 box center;
1630 l|l.
1631 T{
1632 Field
1633 T} T{
1634 Description
1635 T}
1636 _
1637 T{
1638 ioctl fd
1639 T} T{
1640 if \fIflags\fP does not include \fIBTRFS_SUBVOL_SPEC_BY_ID\fP, or if executing
1641 in a non\-root user namespace, file descriptor of the parent directory
1642 containing the subvolume to delete; otherwise, file descriptor of any
1643 directory on the same filesystem as the subvolume to delete, but not
1644 within the same subvolume
1645 T}
1646 _
1647 T{
1648 ioctl args
1649 T} T{
1650 \fI\%struct btrfs_ioctl_vol_args_v2\fP
1651 T}
1652 _
1653 T{
1654 args.fd
1655 T} T{
1656 ignored
1657 T}
1658 _
1659 T{
1660 args.transid
1661 T} T{
1662 ignored
1663 T}
1664 _
1665 T{
1666 args.flags
1667 T} T{
1668 0 if the \fIname\fP field identifies the subvolume by name in the specified
1669 directory, or \fIBTRFS_SUBVOL_SPEC_BY_ID\fP if the \fIsubvolid\fP field
1670 specifies the ID of the subvolume
1671 T}
1672 _
1673 T{
1674 args.name
1675 T} T{
1676 only if \fIflags\fP does not contain \fIBTRFS_SUBVOL_SPEC_BY_ID\fP, the name
1677 (within the directory identified by \fIfd\fP) of the subvolume to delete
1678 T}
1679 _
1680 T{
1681 args.subvolid
1682 T} T{
1683 only if \fIflags\fP contains \fIBTRFS_SUBVOL_SPEC_BY_ID\fP, the subvolume ID of
1684 the subvolume to delete
1685 T}
1686 .TE
1687 .SS BTRFS_IOC_SUBVOL_SYNC_WAIT
1688 .sp
1689 \fI(since: 6.13)\fP Wait until a deleted subvolume is cleaned or query the state.
1690 .sp
1691 There are several modes of operation, where the most common ones are to
1692 wait on a specific subvolume or all currently queued for cleaning. This
1693 is utilized e.g. in backup applications that delete subvolumes and wait
1694 until they\(aqre cleaned to check for remaining space.
1695 .sp
1696 The other modes are for flexibility, e.g. for monitoring or checkpoints in the
1697 queue of deleted subvolumes, again without the need to use SEARCH_TREE.
1698 .sp
1699 Notes:
1700 .INDENT 0.0
1701 .IP \(bu 2
1702 waiting is interruptible, the timeout is set to 1 second and is not
1703 configurable
1704 .IP \(bu 2
1705 repeated calls to the ioctl see a different state, so this is inherently racy
1706 when using e.g. the count or peek next/last
1707 .UNINDENT
1708 .sp
1709 Use cases (\fI\%definition of constants\fP):
1710 .INDENT 0.0
1711 .IP \(bu 2
1712 a subvolume A was deleted, wait for cleaning (WAIT_FOR_ONE)
1713 .IP \(bu 2
1714 a bunch of subvolumes were deleted, wait for all (WAIT_FOR_QUEUED or
1715 PEEK_LAST + WAIT_FOR_ONE)
1716 .IP \(bu 2
1717 count how many are queued (not blocking), for monitoring purposes
1718 .IP \(bu 2
1719 report progress (PEEK_NEXT), may miss some if cleaning is quick
1720 .IP \(bu 2
1721 own waiting in user space (PEEK_LAST until it\(aqs 0)
1722 .UNINDENT
1723 .TS
1724 box center;
1725 l|l.
1726 T{
1727 Field
1728 T} T{
1729 Description
1730 T}
1731 _
1732 T{
1733 ioctl fd
1734 T} T{
1735 file descriptor of any file or directory in the filesystem
1736 T}
1737 _
1738 T{
1739 ioctl args
1740 T} T{
1741 \fI\%struct btrfs_ioctl_subvol_wait\fP
1742 T}
1743 _
1744 T{
1745 args.subvolid
1746 T} T{
1747 Depending on the mode, the numeric id of subvolume to wait for, or
1748 the one queried by \fIPEEK\fP modes
1749 T}
1750 _
1751 T{
1752 args.mode
1753 T} T{
1754 mode of operation described above
1755 T}
1756 _
1757 T{
1758 args.count
1759 T} T{
1760 if \fImode\fP is set to \fICOUNT\fP the number of subvolumes queued for cleaning
1761 T}
1762 .TE
1763 .SS BTRFS_IOC_SHUTDOWN
1764 .sp
1765 \fI(since 7.1)\fP Force filesystem IO shutdown and turn it read\-only.
1766 .TS
1767 box center;
1768 l|l.
1769 T{
1770 Field
1771 T} T{
1772 Description
1773 T}
1774 _
1775 T{
1776 ioctl fd
1777 T} T{
1778 file descriptor of any file or directory in the filesystem
1779 T}
1780 _
1781 T{
1782 ioctl args
1783 T} T{
1784 uint64_t, mode described below
1785 T}
1786 .TE
1787 .sp
1788 The argument is an int with modes affecting flushing of pending writes:
1789 .INDENT 0.0
1790 .IP \(bu 2
1791 \fIBTRFS_SHUTDOWN_FLAGS_DEFAULT\fP (0x0) \- choose default (\fILOGFLUSH\fP mode)
1792 .IP \(bu 2
1793 \fIBTRFS_SHUTDOWN_FLAGS_LOGFLUSH\fP (0x1) \- flush everything, the filesystem is
1794 frozen, shut down and thawn
1795 .IP \(bu 2
1796 \fIBTRFS_SHUTDOWN_FLAGS_NOLOGFLUSH\fP (0x2) \- shut down the filesystem right away
1797 .UNINDENT
1798 .sp
1799 Additionally the \fIfserror\fP reporting facility is used to notify about the
1800 event.
1801 .SH AVAILABILITY
1802 .sp
1803 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
1804 \X'tty: link https://btrfs.readthedocs.io'\fI\%https://btrfs.readthedocs.io\fP\X'tty: link'\&.
1805 .SH SEE ALSO
1806 .sp
1807 \X'tty: link https://man7.org/linux/man-pages/man2/ioctl.2.html'\fI\%ioctl(2)\fP\X'tty: link'
1808 .\" Generated by docutils manpage writer.
1809 .