Debian Codegraph @

upstream/debian-unstable/man8/btrfs-filesystem.8

raw
1 .\" Man page generated from reStructuredText
2 .\" by the Docutils 0.22.4 manpage writer.
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-FILESYSTEM" "8" "May 10, 2026" "7.0" "BTRFS"
32 .SH NAME
33 btrfs-filesystem \- command group that primarily does work on the whole filesystems
34 .SH SYNOPSIS
35 .sp
36 \fBbtrfs filesystem\fP <subcommand> <args>
37 .SH DESCRIPTION
38 .sp
39 \fBbtrfs filesystem\fP is used to perform several whole filesystem level tasks,
40 including all the regular filesystem operations like resizing, space stats,
41 label setting/getting, and defragmentation. There are other whole filesystem
42 tasks like scrub or balance that are grouped in separate commands (btrfs\-scrub(8) \%<>, btrfs\-balance(8) \%<>).
43 .SH SUBCOMMAND
44 .INDENT 0.0
45 .TP
46 .B df [options] <path>
47 Show a terse summary information about allocation of block group types of a given
48 mount point. The original purpose of this command was a debugging helper. The
49 output needs to be further interpreted and is not suitable for quick overview.
50 .sp
51 An example with description:
52 .INDENT 7.0
53 .IP \(bu 2
54 device size: \fI1.9TiB\fP, one device, no RAID
55 .IP \(bu 2
56 filesystem size: \fI1.9TiB\fP
57 .IP \(bu 2
58 created with: \fBmkfs.btrfs \-d single \-m single\fP
59 .UNINDENT
60 .INDENT 7.0
61 .INDENT 3.5
62 .sp
63 .EX
64 $ btrfs filesystem df /path
65 Data, single: total=1.15TiB, used=1.13TiB
66 System, single: total=32.00MiB, used=144.00KiB
67 Metadata, single: total=12.00GiB, used=6.45GiB
68 GlobalReserve, single: total=512.00MiB, used=0.00B
69 .EE
70 .UNINDENT
71 .UNINDENT
72 .INDENT 7.0
73 .IP \(bu 2
74 \fIData\fP, \fISystem\fP and \fIMetadata\fP are separate block group types.
75 \fIGlobalReserve\fP is an artificial and internal emergency space, see
76 below.
77 .IP \(bu 2
78 \fIsingle\fP \-\- the allocation profile, defined at mkfs time
79 .IP \(bu 2
80 \fItotal\fP \-\- sum of space reserved for all allocation profiles of the
81 given type, i.e. all Data/single. Note that it\(aqs not total size of
82 filesystem.
83 .IP \(bu 2
84 \fIused\fP \-\- sum of used space of the above, i.e. file extents, metadata blocks
85 .UNINDENT
86 .sp
87 \fIGlobalReserve\fP is an artificial and internal emergency space. It is used e.g.
88 when the filesystem is full. Its \fItotal\fP size is dynamic based on the
89 filesystem size, usually not larger than 512MiB, \fIused\fP may fluctuate.
90 .sp
91 The GlobalReserve is a portion of Metadata. In case the filesystem metadata is
92 exhausted, \fIGlobalReserve/total + Metadata/used = Metadata/total\fP\&. Otherwise
93 there appears to be some unused space of Metadata.
94 .sp
95 \fBOptions\fP
96 .INDENT 7.0
97 .TP
98 .B \-b|\-\-raw
99 raw numbers in bytes, without the \fIB\fP suffix
100 .TP
101 .B \-h|\-\-human\-readable
102 print human friendly numbers, base 1024, this is the default
103 .UNINDENT
104 .INDENT 7.0
105 .TP
106 .B \-H
107 print human friendly numbers, base 1000
108 .TP
109 .B \-\-iec
110 select the 1024 base for the following options, according to the IEC standard
111 .TP
112 .B \-\-si
113 select the 1000 base for the following options, according to the SI standard
114 .UNINDENT
115 .INDENT 7.0
116 .TP
117 .B \-k|\-\-kbytes
118 show sizes in KiB, or kB with \-\-si
119 .TP
120 .B \-m|\-\-mbytes
121 show sizes in MiB, or MB with \-\-si
122 .TP
123 .B \-g|\-\-gbytes
124 show sizes in GiB, or GB with \-\-si
125 .TP
126 .B \-t|\-\-tbytes
127 show sizes in TiB, or TB with \-\-si
128 .UNINDENT
129 .sp
130 If conflicting options are passed, the last one takes precedence.
131 .UNINDENT
132 .INDENT 0.0
133 .TP
134 .B defragment [options] <file>|<dir> [<file>|<dir>...]
135 Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer.
136 .sp
137 If \fI\-r\fP is passed, files in \fIdir\fP will be defragmented recursively (not
138 descending to subvolumes, mount points and directory symlinks).
139 The start position and the number of bytes to defragment can be specified by
140 start and length using \fI\-s\fP and \fI\-l\fP options below.
141 Extents bigger than value given by \fI\-t\fP will be skipped, otherwise this value
142 is used as a target extent size, but is only advisory and may not be reached
143 if the free space is too fragmented.
144 Use 0 to take the kernel default, which is 256KiB but may change in the future.
145 You can also turn on compression in defragment operations.
146 .sp
147 \fBWarning:\fP
148 .INDENT 7.0
149 .INDENT 3.5
150 Defragmenting with Linux kernel versions < 3.9 or ≥ 3.14\-rc2 as well as
151 with Linux stable kernel versions ≥ 3.10.31, ≥ 3.12.12 or ≥ 3.13.4 will break up
152 the reflinks of COW data (for example files copied with \fBcp \-\-reflink\fP,
153 snapshots or de\-duplicated data).
154 This may cause considerable increase of space usage depending on the broken up
155 reflinks.
156 .UNINDENT
157 .UNINDENT
158 .sp
159 \fBNote:\fP
160 .INDENT 7.0
161 .INDENT 3.5
162 Directory arguments without \fI\-r\fP do not defragment files recursively but will
163 defragment certain internal trees (extent tree and the subvolume tree). This has been
164 confusing and could be removed in the future.
165 .UNINDENT
166 .UNINDENT
167 .sp
168 For \fIstart\fP, \fIlen\fP, \fIsize\fP it is possible to append
169 units designator: \fIK\fP, \fIM\fP, \fIG\fP, \fIT\fP, \fIP\fP, or \fIE\fP, which represent
170 KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).
171 .sp
172 \fBOptions\fP
173 .INDENT 7.0
174 .TP
175 .B \-c[<algo>]
176 compress file contents while defragmenting. Optional argument selects the compression
177 algorithm, \fIzlib\fP (default), \fIlzo\fP or \fIzstd\fP\&. Currently it\(aqs not possible to select no
178 compression. See also section \fIEXAMPLES\fP\&.
179 .TP
180 .B \-L|\-\-level <level>
181 Since kernel 6.15 the compression can also take the level parameter which will be used
182 only for the defragmentation and overrides the eventual mount option compression level.
183 Valid levels depend on the compression algorithms: \fIzlib\fP
184 1..9, \fIlzo\fP does not have any levels, \fIzstd\fP the standard levels 1..15 and also the
185 realtime \-1..\-15.
186 .UNINDENT
187 .INDENT 7.0
188 .TP
189 .B \-\-nocomp
190 Do not compress while defragmenting, uncompress extents if needed.
191 .TP
192 .B \-r
193 defragment files recursively in given directories, does not descend to
194 subvolumes or mount points
195 .TP
196 .B \-f
197 flush data for each file before going to the next file.
198 .sp
199 This will limit the amount of dirty data to current file, otherwise the amount
200 accumulates from several files and will increase system load. This can also lead
201 to ENOSPC if there\(aqs too much dirty data to write and it\(aqs not possible to make
202 the reservations for the new data (i.e. how the COW design works).
203 .UNINDENT
204 .INDENT 7.0
205 .TP
206 .B \-s <start>[kKmMgGtTpPeE]
207 defragmentation will start from the given offset, default is beginning of a file
208 .TP
209 .B \-l <len>[kKmMgGtTpPeE]
210 defragment only up to \fIlen\fP bytes, default is the file size
211 .TP
212 .B \-t <size>[kKmMgGtTpPeE]
213 target extent size, do not touch extents bigger than \fIsize\fP, default: 32MiB
214 .sp
215 The value is only advisory and the final size of the extents may differ,
216 depending on the state of the free space and fragmentation or other internal
217 logic. Reasonable values are from tens to hundreds of megabytes.
218 .UNINDENT
219 .INDENT 7.0
220 .TP
221 .BI \-\-step \ SIZE
222 Perform defragmentation in the range in SIZE steps and flush (\fI\-f\fP) after each one.
223 The range is default (the whole file) or given by \fI\-s\fP and \fI\-l\fP, split into
224 the steps or done in one go if the step is larger. Minimum range size is 256KiB.
225 With verbosity options the progress of defragmentation will be also printed.
226 .TP
227 .B \-v
228 (deprecated) alias for global \fI\-v\fP option
229 .UNINDENT
230 .TP
231 .B du [options] <path> [<path>..]
232 Calculate disk usage of the target files using FIEMAP. For individual
233 files, it will report a count of total bytes, and exclusive (not
234 shared) bytes. We also calculate a \(aqset shared\(aq value which is
235 described below.
236 .sp
237 Each argument to \fBbtrfs filesystem du\fP will have a \fIset shared\fP value
238 calculated for it. We define each \fIset\fP as those files found by a
239 recursive search of an argument (recursion descends to subvolumes but not
240 mount points). The \fIset shared\fP value then is a sum of all shared space
241 referenced by the set.
242 .sp
243 \fIset shared\fP takes into account overlapping shared extents, hence it
244 isn\(aqt as simple as adding up shared extents.
245 .sp
246 \fBOptions\fP
247 .INDENT 7.0
248 .TP
249 .B \-s|\-\-summarize
250 display only a total for each argument
251 .UNINDENT
252 .INDENT 7.0
253 .TP
254 .B \-\-raw
255 raw numbers in bytes, without the \fIB\fP suffix.
256 .TP
257 .B \-\-human\-readable
258 print human friendly numbers, base 1024, this is the default
259 .TP
260 .B \-\-iec
261 select the 1024 base for the following options, according to the IEC standard.
262 .TP
263 .B \-\-si
264 select the 1000 base for the following options, according to the SI standard.
265 .TP
266 .B \-\-kbytes
267 show sizes in KiB, or kB with \-\-si.
268 .TP
269 .B \-\-mbytes
270 show sizes in MiB, or MB with \-\-si.
271 .TP
272 .B \-\-gbytes
273 show sizes in GiB, or GB with \-\-si.
274 .TP
275 .B \-\-tbytes
276 show sizes in TiB, or TB with \-\-si.
277 .UNINDENT
278 .UNINDENT
279 .INDENT 0.0
280 .TP
281 .B label [<device>|<mountpoint>] [<newlabel>]
282 Show or update the label of a filesystem. This works on a mounted filesystem or
283 a filesystem image.
284 .sp
285 The \fInewlabel\fP argument is optional. Current label is printed if the argument
286 is omitted.
287 .sp
288 \fBNote:\fP
289 .INDENT 7.0
290 .INDENT 3.5
291 The maximum allowable length shall be less than 256 chars and must not contain
292 a newline. The trailing newline is stripped automatically.
293 .UNINDENT
294 .UNINDENT
295 .TP
296 .B mkswapfile [\-s size] file
297 Create a new file that\(aqs suitable and formatted as a swapfile. Default
298 size is 2GiB, fixed page size 4KiB, minimum size is 40KiB.
299 .sp
300 A swapfile must be created in a specific way: NOCOW and preallocated.
301 Subvolume containing a swapfile cannot be snapshotted and blocks of an
302 activated swapfile cannot be balanced.
303 .sp
304 Swapfile creation can be achieved by standalone commands too. Activation
305 needs to be done by command swapon(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:swapon\:.8\:.html>\&. See also command
306 \fBbtrfs inspect\-internal map\-swapfile\fP
307 and the Swapfile feature \%<> description.
308 .sp
309 \fBNote:\fP
310 .INDENT 7.0
311 .INDENT 3.5
312 The command is a simplified version of \(aqmkswap\(aq, if you want to set
313 label, page size, or other parameters please use \(aqmkswap\(aq proper.
314 .UNINDENT
315 .UNINDENT
316 .sp
317 \fBOptions\fP
318 .INDENT 7.0
319 .TP
320 .B \-s|\-\-size SIZE
321 Create swapfile of a given size SIZE (accepting k/m/g/e/p
322 suffix).
323 .TP
324 .B \-U|\-\-uuid UUID
325 specify UUID to use, or a special value: clear (all zeros), random,
326 time (time\-based random)
327 .UNINDENT
328 .UNINDENT
329 .INDENT 0.0
330 .TP
331 .B resize [options] [<devid>:][+/\-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>
332 Resize a mounted filesystem identified by \fIpath\fP\&. A particular device
333 can be resized by specifying a \fIdevid\fP\&.
334 .sp
335 \fBNote:\fP
336 .INDENT 7.0
337 .INDENT 3.5
338 To resize a file containing a BTRFS image, please use the \-\-offline flag.
339 .UNINDENT
340 .UNINDENT
341 .sp
342 The \fIdevid\fP can be found in the output of \fBbtrfs filesystem show\fP and
343 defaults to 1 if not specified.
344 The \fIsize\fP parameter specifies the new size of the filesystem.
345 If the prefix \fI+\fP or \fI\-\fP is present the size is increased or decreased
346 by the quantity \fIsize\fP\&.
347 If no units are specified, bytes are assumed for \fIsize\fP\&.
348 Optionally, the size parameter may be suffixed by one of the following
349 unit designators: \fIK\fP, \fIM\fP, \fIG\fP, \fIT\fP, \fIP\fP, or \fIE\fP, which represent
350 KiB, MiB, GiB, TiB, PiB, or EiB, respectively (case does not matter).
351 .sp
352 If \fImax\fP is passed, the filesystem will occupy all available space on the
353 device respecting \fIdevid\fP (remember, devid 1 by default).
354 .sp
355 The resize command does not manipulate the size of underlying
356 partition. If you wish to enlarge/reduce a filesystem, you must make sure you
357 expand the partition before enlarging the filesystem and shrink the
358 partition after reducing the size of the filesystem. This can be done using
359 fdisk(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:fdisk\:.8\:.html> or parted(8) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man8/\:parted\:.8\:.html> to delete the existing partition and recreate
360 it with the new desired size. When recreating the partition make sure to use
361 the same starting partition offset as before.
362 .sp
363 The size of the portion that the filesystem uses of an underlying device can be
364 determined via the \fBbtrfs filesystem show \-\-raw\fP command on the
365 filesystem’s mount point (where it’s given for each \fIdevid\fP after the string
366 \fIsize\fP or via the \fBbtrfs inspect\-internal dump\-super\fP command on the
367 specific device (where it’s given as the value of \fIdev_item.total_bytes\fP, which
368 is not to be confused with \fItotal_bytes\fP).
369 The value is also the address of the first byte not used by the
370 filesystem.
371 .sp
372 Growing is usually instant as it only updates the size. However, shrinking could
373 take a long time if there are data in the device area that\(aqs beyond the new
374 end. Relocation of the data takes time.
375 .sp
376 Note that there\(aqs a lower limit on the new size (either specified
377 as an absolute size or difference) that is checked by kernel and
378 rejected eventually as invalid. Lower values will print a warning but
379 still pass the request to kernel. The currently known value is 256MiB.
380 .sp
381 See also section \fIEXAMPLES\fP\&.
382 .sp
383 \fBOptions\fP
384 .INDENT 7.0
385 .TP
386 .B \-\-enqueue
387 wait if there\(aqs another exclusive operation running, otherwise continue
388 .TP
389 .B \-\-offline
390 resize an unmounted (offline) filesystem
391 .sp
392 \fBWarning:\fP
393 .INDENT 7.0
394 .INDENT 3.5
395 The offline resize functionality currently
396 supports \fBonly increasing\fP the size of \fBsingle\-device\fP
397 filesystems. IOW, shrinking and multi\-device filesystems are
398 \fBnot supported\fP with this option.
399 .UNINDENT
400 .UNINDENT
401 .sp
402 For filesystems stored in regular files, the file will be
403 truncated to the new size as part of the resize operation.
404 This flag is cannot be used together with with \-\-enqueue since
405 offline resizing is synchronous.
406 .UNINDENT
407 .TP
408 .B show [options] [<path>|<uuid>|<device>|<label>]
409 Show the btrfs filesystem with some additional info about devices and space
410 allocation.
411 .sp
412 If no option none of \fIpath\fP/\fIuuid\fP/\fIdevice\fP/\fIlabel\fP is passed, information
413 about all the BTRFS filesystems is shown, both mounted and unmounted.
414 .sp
415 \fBOptions\fP
416 .INDENT 7.0
417 .TP
418 .B \-m|\-\-mounted
419 probe kernel for mounted BTRFS filesystems
420 .TP
421 .B \-d|\-\-all\-devices
422 scan all devices under \fB/dev\fP, otherwise the devices list is extracted from the
423 \fB/proc/partitions\fP file. This is a fallback option if there\(aqs no device node
424 manager (like udev) available in the system.
425 .UNINDENT
426 .INDENT 7.0
427 .TP
428 .B \-\-raw
429 raw numbers in bytes, without the \fIB\fP suffix
430 .TP
431 .B \-\-human\-readable
432 print human friendly numbers, base 1024, this is the default
433 .TP
434 .B \-\-iec
435 select the 1024 base for the following options, according to the IEC standard
436 .TP
437 .B \-\-si
438 select the 1000 base for the following options, according to the SI standard
439 .TP
440 .B \-\-kbytes
441 show sizes in KiB, or kB with \-\-si
442 .TP
443 .B \-\-mbytes
444 show sizes in MiB, or MB with \-\-si
445 .TP
446 .B \-\-gbytes
447 show sizes in GiB, or GB with \-\-si
448 .TP
449 .B \-\-tbytes
450 show sizes in TiB, or TB with \-\-si
451 .UNINDENT
452 .TP
453 .B commit\-stats
454 Print number of commits and time stats since mount. This is also available
455 in \fB/sys/fs/btrfs/FSID/commit_stats\fP\&. The stats are not persistent
456 and are collected since mount of the filesystem, one of them can be reset
457 to zero (\fIMax commit duration\fP).
458 .INDENT 7.0
459 .INDENT 3.5
460 .sp
461 .EX
462 UUID: bd18ebe1\-7e1d\-414f\-a3d5\-2644388b51cc
463 Commit stats since mount:
464 Total commits: 1133
465 Last commit duration: 0ms
466 Max commit duration: 10ms
467 Total time spent in commit: 4543ms
468 .EE
469 .UNINDENT
470 .UNINDENT
471 .sp
472 \fBOptions\fP
473 .INDENT 7.0
474 .TP
475 .B \-z|\-\-reset
476 print stats and reset \(aqmax_commit_ms\(aq (needs root)
477 .UNINDENT
478 .TP
479 .B sync <path>
480 Force a sync of the filesystem at \fIpath\fP, similar to the sync(1) \%<https://\:man7\:.org/\:linux/\:man-pages/\:man1/\:sync\:.1\:.html> command. In
481 addition, it starts cleaning of deleted subvolumes. To wait for the subvolume
482 deletion to complete use the \fBbtrfs subvolume sync\fP command.
483 .TP
484 .B usage [options] <path> [<path>...]
485 Show detailed information about internal filesystem usage. This is supposed to
486 replace the \fBbtrfs filesystem df\fP command in the long run.
487 .sp
488 The level of detail can differ if the command is run under a regular or the
489 root user (due to use of restricted ioctl). For both there\(aqs a summary section
490 with information about space usage:
491 .INDENT 7.0
492 .INDENT 3.5
493 .sp
494 .EX
495 $ btrfs filesystem usage /path
496 WARNING: cannot read detailed chunk info, RAID5/6 numbers will be incorrect, run as root
497 Overall:
498 Device size: 1.82TiB
499 Device allocated: 1.17TiB
500 Device unallocated: 669.99GiB
501 Device missing: 0.00B
502 Device slack: 1.00GiB
503 Used: 1.14TiB
504 Free (estimated): 692.57GiB (min: 692.57GiB)
505 Free (statfs, df) 692.57GiB
506 Data ratio: 1.00
507 Metadata ratio: 1.00
508 Global reserve: 512.00MiB (used: 0.00B)
509 Multiple profiles: no
510 .EE
511 .UNINDENT
512 .UNINDENT
513 .INDENT 7.0
514 .IP \(bu 2
515 \fIDevice size\fP \-\- sum of raw device capacity available to the
516 filesystem, note that this may not be the same as the total device
517 size (the difference is accounted as slack)
518 .IP \(bu 2
519 \fIDevice allocated\fP \-\- sum of total space allocated for
520 data/metadata/system profiles, this also accounts space reserved but
521 not yet used for extents
522 .IP \(bu 2
523 \fIDevice unallocated\fP \-\- the remaining unallocated space for future
524 allocations (difference of the above two numbers)
525 .IP \(bu 2
526 \fIDevice missing\fP \-\- sum of capacity of all missing devices
527 .IP \(bu 2
528 \fIDevice slack\fP \-\- sum of slack space on all devices (difference
529 between entire device size and the space occupied by filesystem)
530 .IP \(bu 2
531 \fIUsed\fP \-\- sum of the used space of data/metadata/system profiles, not
532 including the reserved space
533 .IP \(bu 2
534 \fIFree (estimated)\fP \-\- approximate size of the remaining free space
535 usable for data, including currently allocated space and estimating
536 the usage of the unallocated space based on the block group profiles,
537 the \fImin\fP is the lower bound of the estimate in case multiple
538 profiles are present
539 .IP \(bu 2
540 \fIFree (statfs, df)\fP \-\- the amount of space available for data as
541 reported by the \fBstatfs/statvfs\fP syscall, also returned as \fIAvail\fP in the
542 output of \fBdf\fP\&. The value is calculated in a different way and may
543 not match the estimate in some cases (e.g. multiple profiles).
544 .IP \(bu 2
545 \fIData ratio\fP \-\- ratio of total space for data including redundancy or
546 parity to the effectively usable data space, e.g. single is 1.0, RAID1
547 is 2.0 and for RAID5/6 it depends on the number of devices
548 .IP \(bu 2
549 \fIMetadata ratio\fP \-\- ditto, for metadata
550 .IP \(bu 2
551 \fIGlobal reserve\fP \-\- portion of metadata currently used for global
552 block reserve, used for emergency purposes (like deletion on a full
553 filesystem)
554 .IP \(bu 2
555 \fIMultiple profiles\fP \-\- what block group types (data, metadata) have
556 more than one profile (single, raid1, ...), see btrfs(5) \%<> section
557 FILESYSTEMS WITH MULTIPLE PROFILES \%<#\:man-btrfs5-filesystem-with-multiple-profiles>\&.
558 .UNINDENT
559 .sp
560 And on a zoned filesystem there are two more lines in the \fIDevice\fP section:
561 .INDENT 7.0
562 .INDENT 3.5
563 .sp
564 .EX
565 Device zone unusable: 5.13GiB
566 Device zone size: 256.00MiB
567 .EE
568 .UNINDENT
569 .UNINDENT
570 .INDENT 7.0
571 .IP \(bu 2
572 \fIDevice zone unusable\fP \-\- sum of of space that\(aqs been used in the
573 past but now is not due to COW and not referenced anymore, the chunks
574 have to be reclaimed and zones reset to make it usable again
575 .IP \(bu 2
576 \fIDevice zone size\fP \-\- the reported zone size of the host\-managed
577 device, same for all devices
578 .UNINDENT
579 .sp
580 The root user will also see stats broken down by block group types:
581 .INDENT 7.0
582 .INDENT 3.5
583 .sp
584 .EX
585 Data,single: Size:1.15TiB, Used:1.13TiB (98.26%)
586 /dev/sdb 1.15TiB
587
588 Metadata,single: Size:12.00GiB, Used:6.45GiB (53.75%)
589 /dev/sdb 12.00GiB
590
591 System,single: Size:32.00MiB, Used:144.00KiB (0.44%)
592 /dev/sdb 32.00MiB
593
594 Unallocated:
595 /dev/sdb 669.99GiB
596 .EE
597 .UNINDENT
598 .UNINDENT
599 .sp
600 \fIData\fP is block group type, \fIsingle\fP is block group profile, \fISize\fP is total
601 size occupied by this type, \fIUsed\fP is the actually used space, the percent is
602 ratio of \fIUsed/Size\fP\&. The \fIUnallocated\fP is remaining space.
603 .sp
604 \fBOptions\fP
605 .INDENT 7.0
606 .TP
607 .B \-b|\-\-raw
608 raw numbers in bytes, without the \fIB\fP suffix
609 .TP
610 .B \-h|\-\-human\-readable
611 print human friendly numbers, base 1024, this is the default
612 .UNINDENT
613 .INDENT 7.0
614 .TP
615 .B \-H
616 print human friendly numbers, base 1000
617 .TP
618 .B \-\-iec
619 select the 1024 base for the following options, according to the IEC standard
620 .TP
621 .B \-\-si
622 select the 1000 base for the following options, according to the SI standard
623 .UNINDENT
624 .INDENT 7.0
625 .TP
626 .B \-k|\-\-kbytes
627 show sizes in KiB, or kB with \-\-si
628 .TP
629 .B \-m|\-\-mbytes
630 show sizes in MiB, or MB with \-\-si
631 .TP
632 .B \-g|\-\-gbytes
633 show sizes in GiB, or GB with \-\-si
634 .TP
635 .B \-t|\-\-tbytes
636 show sizes in TiB, or TB with \-\-si
637 .UNINDENT
638 .INDENT 7.0
639 .TP
640 .B \-T
641 show data in tabular format
642 .UNINDENT
643 .sp
644 If conflicting options are passed, the last one takes precedence.
645 .UNINDENT
646 .SH EXAMPLES
647 .sp
648 \fB$ btrfs filesystem defrag \-v \-r dir/\fP
649 .sp
650 Recursively defragment files under \fBdir/\fP, print files as they are processed.
651 The file names will be printed in batches, similarly the amount of data triggered
652 by defragmentation will be proportional to last N printed files. The system dirty
653 memory throttling will slow down the defragmentation but there can still be a lot
654 of IO load and the system may stall for a moment.
655 .sp
656 \fB$ btrfs filesystem defrag \-v \-r \-f dir/\fP
657 .sp
658 Recursively defragment files under \fBdir/\fP, be verbose and wait until all blocks
659 are flushed before processing next file. You can note slower progress of the
660 output and lower IO load (proportional to currently defragmented file).
661 .sp
662 \fB$ btrfs filesystem defrag \-v \-r \-f \-clzo dir/\fP
663 .sp
664 Recursively defragment files under \fBdir/\fP, be verbose, wait until all blocks are
665 flushed and force file compression.
666 .sp
667 \fB$ btrfs filesystem defrag \-v \-r \-t 64M dir/\fP
668 .sp
669 Recursively defragment files under \fBdir/\fP, be verbose and try to merge extents
670 to be about 64MiB. As stated above, the success rate depends on actual free
671 space fragmentation and the final result is not guaranteed to meet the target
672 even if run repeatedly.
673 .sp
674 \fB$ btrfs filesystem resize \-1G /path\fP
675 .sp
676 \fB$ btrfs filesystem resize 1:\-1G /path\fP
677 .sp
678 Shrink size of the filesystem\(aqs device id 1 by 1GiB. The first syntax expects a
679 device with id 1 to exist, otherwise fails. The second is equivalent and more
680 explicit. For a single\-device filesystem it\(aqs typically not necessary to
681 specify the devid though.
682 .sp
683 \fB$ btrfs filesystem resize max /path\fP
684 .sp
685 \fB$ btrfs filesystem resize 1:max /path\fP
686 .sp
687 Let\(aqs assume that devid 1 exists and the filesystem does not occupy the whole
688 block device, e.g. it has been enlarged and we want to grow the filesystem. By
689 simply using \fImax\fP as size we will achieve that.
690 .sp
691 \fBNote:\fP
692 .INDENT 0.0
693 .INDENT 3.5
694 There are two ways to minimize the filesystem on a given device. The
695 \fBbtrfs inspect\-internal min\-dev\-size\fP command, or iteratively shrink in steps.
696 .UNINDENT
697 .UNINDENT
698 .SH EXIT STATUS
699 .sp
700 \fBbtrfs filesystem\fP returns a zero exit status if it succeeds. Non zero is
701 returned in case of failure.
702 .SH AVAILABILITY
703 .sp
704 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
705 \%<https://\:btrfs\:.readthedocs\:.io>\&.
706 .SH SEE ALSO
707 .sp
708 btrfs\-subvolume(8) \%<>,
709 mkfs.btrfs(8) \%<>
710 .\" End of generated man page.