Debian Codegraph @

upstream/debian-trixie/man8/btrfs-inspect-internal.8

raw
1 .\" Man page generated from reStructuredText.
2 .
3 .
4 .nr rst2man-indent-level 0
5 .
6 .de1 rstReportMargin
7 \\$1 \\n[an-margin]
8 level \\n[rst2man-indent-level]
9 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
10 -
11 \\n[rst2man-indent0]
12 \\n[rst2man-indent1]
13 \\n[rst2man-indent2]
14 ..
15 .de1 INDENT
16 .\" .rstReportMargin pre:
17 . RS \\$1
18 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
19 . nr rst2man-indent-level +1
20 .\" .rstReportMargin post:
21 ..
22 .de UNINDENT
23 . RE
24 .\" indent \\n[an-margin]
25 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
26 .nr rst2man-indent-level -1
27 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
28 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
29 ..
30 .TH "BTRFS-INSPECT-INTERNAL" "8" "May 18, 2026" "7.0" "BTRFS"
31 .SH NAME
32 btrfs-inspect-internal \- query various internal information
33 .SH SYNOPSIS
34 .sp
35 \fBbtrfs inspect\-internal\fP <subcommand> <args>
36 .SH DESCRIPTION
37 .sp
38 This command group provides an interface to query internal information. The
39 functionality ranges from a simple UI to an ioctl or a more complex query that
40 assembles the result from several internal structures. The latter usually
41 requires calls to privileged ioctls.
42 .SH SUBCOMMAND
43 .INDENT 0.0
44 .TP
45 .B dump\-super [options] <device> [device...]
46 Show btrfs superblock information stored on given devices in textual form.
47 By default the first superblock is printed, more details about all copies or
48 additional backup data can be printed.
49 .sp
50 Besides verification of the filesystem signature, there are no other sanity
51 checks. The superblock checksum status is reported, the device item and
52 filesystem UUIDs are checked and reported.
53 .sp
54 \fBNOTE:\fP
55 .INDENT 7.0
56 .INDENT 3.5
57 The meaning of option \fI\-s\fP has changed in version 4.8 to be consistent
58 with other tools to specify superblock copy rather the offset. The old way still
59 works, but prints a warning. Please update your scripts to use \fI\-\-bytenr\fP
60 instead. The option \fI\-i\fP has been deprecated.
61 .UNINDENT
62 .UNINDENT
63 .sp
64 \fBOptions\fP
65 .INDENT 7.0
66 .TP
67 .B \-f|\-\-full
68 print full superblock information, including the system chunk array and backup roots
69 .TP
70 .B \-a|\-\-all
71 print information about all present superblock copies (cannot be used together
72 with \fI\-s\fP option)
73 .UNINDENT
74 .INDENT 7.0
75 .TP
76 .BI \-i \ <super>
77 (deprecated since 4.8, same behaviour as \fI\-\-super\fP)
78 .TP
79 .BI \-\-bytenr \ <bytenr>
80 specify offset to a superblock in a non\-standard location at \fIbytenr\fP, useful
81 for debugging (disables the \fI\-f\fP option)
82 .sp
83 If there are multiple options specified, only the last one applies.
84 .UNINDENT
85 .INDENT 7.0
86 .TP
87 .B \-F|\-\-force
88 attempt to print the superblock even if a valid BTRFS signature is not found;
89 the result may be completely wrong if the data does not resemble a superblock
90 .TP
91 .B \-s|\-\-super <bytenr>
92 (see compatibility note above)
93 .sp
94 specify which mirror to print, valid values are 0, 1 and 2 and the superblock
95 must be present on the device with a valid signature, can be used together with
96 \fI\-\-force\fP
97 .UNINDENT
98 .TP
99 .B dump\-tree [options] <device> [device...]
100 Dump tree structures from a given device in textual form, expand keys to human
101 readable equivalents where possible.
102 This is useful for analyzing filesystem state or inconsistencies and has
103 a positive educational effect on understanding the internal filesystem structure.
104 .sp
105 \fBNOTE:\fP
106 .INDENT 7.0
107 .INDENT 3.5
108 By default contains file names, consider that if you\(aqre asked
109 to send the dump for analysis and use \fI\-\-hide\-names\fP eventually.
110 Does not contain file data.
111 .UNINDENT
112 .UNINDENT
113 .sp
114 Special characters in file names, xattr names and values are escaped,
115 in the C style like \fB\en\fP and octal encoding \fB\eNNN\fP\&.
116 .sp
117 \fBOptions\fP
118 .INDENT 7.0
119 .TP
120 .B \-e|\-\-extents
121 print only extent\-related information: extent and device trees
122 .TP
123 .B \-d|\-\-device
124 print only device\-related information: tree root, chunk and device trees
125 .TP
126 .B \-r|\-\-roots
127 print only short root node information, i.e. the root tree keys
128 .TP
129 .B \-R|\-\-backups
130 same as \fI\-\-roots\fP plus print backup root info, i.e. the backup root keys and
131 the respective tree root block offset
132 .TP
133 .B \-u|\-\-uuid
134 print only the uuid tree information, empty output if the tree does not exist
135 .UNINDENT
136 .INDENT 7.0
137 .TP
138 .BI \-b \ <block_num>
139 print info of the specified block only, can be specified multiple times
140 .TP
141 .B \-\-follow
142 use with \fI\-b\fP, print all children tree blocks of \fI<block_num>\fP
143 .TP
144 .B \-\-dfs
145 (default up to 5.2)
146 .sp
147 use depth\-first search to print trees, the nodes and leaves are
148 intermixed in the output
149 .TP
150 .B \-\-bfs
151 (default since 5.3)
152 .sp
153 use breadth\-first search to print trees, the nodes are printed before all
154 leaves
155 .TP
156 .B \-\-hide\-names
157 print a placeholder \fIHIDDEN\fP instead of various names, useful for developers to
158 inspect the dump while keeping potentially sensitive information hidden
159 .sp
160 This is:
161 .INDENT 7.0
162 .IP \(bu 2
163 directory entries (files, directories, subvolumes)
164 .IP \(bu 2
165 default subvolume
166 .IP \(bu 2
167 extended attributes (name, value)
168 .IP \(bu 2
169 hardlink names (if stored inside another item or as extended references in standalone items)
170 .UNINDENT
171 .sp
172 \fBNOTE:\fP
173 .INDENT 7.0
174 .INDENT 3.5
175 Lengths are not hidden because they can be calculated from the item size anyway.
176 .UNINDENT
177 .UNINDENT
178 .TP
179 .B \-\-csum\-headers
180 print b\-tree node checksums stored in headers (metadata)
181 .TP
182 .B \-\-csum\-items
183 print checksums stored in checksum items (data)
184 .TP
185 .B \-\-noscan
186 do not automatically scan the system for other devices from the same
187 filesystem, only use the devices provided as the arguments
188 .TP
189 .BI \-t \ <tree_id>
190 print only the tree with the specified ID, where the ID can be numerical or
191 common name in a flexible human readable form
192 .sp
193 The tree id name recognition rules:
194 .INDENT 7.0
195 .IP \(bu 2
196 case does not matter
197 .IP \(bu 2
198 the C source definition, e.g. BTRFS_ROOT_TREE_OBJECTID
199 .IP \(bu 2
200 short forms without BTRFS_ prefix, without _TREE and _OBJECTID suffix, e.g. ROOT_TREE, ROOT
201 .IP \(bu 2
202 convenience aliases, e.g. DEVICE for the DEV tree, CHECKSUM for CSUM
203 .IP \(bu 2
204 unrecognized ID is an error
205 .UNINDENT
206 .UNINDENT
207 .TP
208 .B inode\-resolve [\-v] <ino> <path>
209 (needs root privileges)
210 .sp
211 resolve paths to all files with given inode number \fIino\fP in a given subvolume
212 at \fIpath\fP, i.e. all hardlinks
213 .sp
214 \fBOptions\fP
215 .INDENT 7.0
216 .TP
217 .B \-v
218 (deprecated) alias for global \fI\-v\fP option
219 .UNINDENT
220 .TP
221 .B logical\-resolve [\-Pvo] [\-s <bufsize>] <logical> <path>
222 (needs root privileges)
223 .sp
224 resolve paths to all files at given \fIlogical\fP address in the linear filesystem space
225 .sp
226 \fBOptions\fP
227 .INDENT 7.0
228 .TP
229 .B \-P
230 skip the path resolving and print the inodes instead
231 .TP
232 .B \-o
233 ignore offsets, find all references to an extent instead of a single block.
234 Requires kernel support for the V2 ioctl (added in 4.15). The results might need
235 further processing to filter out unwanted extents by the offset that is supposed
236 to be obtained by other means.
237 .TP
238 .BI \-s \ <bufsize>
239 set internal buffer for storing the file names to \fIbufsize\fP, default is 64KiB,
240 maximum 16MiB. Buffer sizes over 64KiB require kernel support for the V2 ioctl
241 (added in 4.15).
242 .TP
243 .B \-v
244 (deprecated) alias for global \fI\-v\fP option
245 .UNINDENT
246 .TP
247 .B list\-chunks [options] <path>
248 (needs root privileges)
249 .sp
250 Enumerate chunks on all devices. The chunks represent the physical
251 range on devices (not to be confused with block groups that represent
252 the logical ranges, but the terms are often used interchangeably).
253 .sp
254 Example output:
255 .INDENT 7.0
256 .INDENT 3.5
257 .sp
258 .EX
259 Devid PNumber Type/profile PStart Length PEnd LNumber LStart Usage%
260 \-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\- \-\-\-\-\-\-
261 1 1 Data/single 1.00MiB 84.00MiB 85.00MiB 68 191.60GiB 62.77
262 1 2 System/DUP 85.00MiB 32.00MiB 117.00MiB 39 140.17GiB 0.05
263 1 3 System/DUP 117.00MiB 32.00MiB 149.00MiB 40 140.17GiB 0.05
264 1 4 Metadata/DUP 149.00MiB 192.00MiB 341.00MiB 59 188.41GiB 45.00
265 1 5 Metadata/DUP 341.00MiB 192.00MiB 533.00MiB 60 188.41GiB 45.00
266 1 6 Data/single 533.00MiB 1.00GiB 1.52GiB 49 169.91GiB 72.23
267 1 7 Data/single 1.52GiB 16.00MiB 1.54GiB 69 191.68GiB 79.83
268 1 8 Data/single 1.54GiB 1.00GiB 2.54GiB 17 100.90GiB 46.39
269 1 9 Data/single 2.54GiB 1.00GiB 3.54GiB 16 99.90GiB 40.68
270 1 10 Data/single 3.54GiB 1.00GiB 4.54GiB 1 71.40GiB 62.97
271 1 11 Data/single 4.54GiB 1.00GiB 5.54GiB 33 125.04GiB 26.00
272 1 12 Data/single 5.54GiB 1.00GiB 6.54GiB 50 170.91GiB 60.44
273 1 13 Data/single 6.54GiB 512.00MiB 7.04GiB 63 189.16GiB 67.34
274 1 14 Data/single 7.04GiB 1.00GiB 8.04GiB 51 171.91GiB 70.94
275 .EE
276 .UNINDENT
277 .UNINDENT
278 .INDENT 7.0
279 .IP \(bu 2
280 \fIDevid\fP \-\- the device id
281 .IP \(bu 2
282 \fIPNumber\fP \-\- the number of the chunk on the device (in order)
283 .IP \(bu 2
284 \fIType/profile\fP \-\- the chunk type and profile
285 .IP \(bu 2
286 \fIPStart\fP \-\- the chunk start on the device
287 .IP \(bu 2
288 \fILength\fP \-\- the chunk length (same for physical and logical address space)
289 .IP \(bu 2
290 \fIPEnd\fP \-\- the chunk end, effectively \fIPStart + Length\fP
291 .IP \(bu 2
292 \fILNumber\fP \-\- the number of the chunk, in the logical address space of the whole filesystem
293 .IP \(bu 2
294 \fILStart\fP \-\- the chunk start in the logical address space of the whole
295 filesystem, as it\(aqs a single space it\(aqs also called \fIoffset\fP
296 .IP \(bu 2
297 \fIUsage\fP \-\- chunk usage, percentage of used data/metadata of the chunk length
298 .UNINDENT
299 .sp
300 The chunks in the output can be sorted by one or more sorting criteria, evaluated
301 as specified, in the ascending order (or descending when used like \fI\-devid,\-pstart\fP).
302 By default the chunks are sorted by \fIdevid\fP and \fIpstart\fP, this is most
303 convenient for single device filesystems.
304 .sp
305 On multi\-device filesystems it\(aqs up to the user what is preferred as the layout
306 of chunks on e.g. striped profiles (RAID0 etc) cannot be easily represented.
307 A logical view with corresponding underlying structure would be better, but
308 sorting by \fIlstart,devid\fP at least groups devices of the given logical
309 range. Can be also combined with \fIusage\fP\&.
310 .sp
311 This output can provide information for balance filters.
312 .sp
313 \fBOptions\fP
314 .INDENT 7.0
315 .TP
316 .BI \-\-sort \ MODE
317 sort by a column (ascending, prepend \(aq\-\(aq for descending):
318 .sp
319 MODE is a comma separated list of:
320 .INDENT 7.0
321 .INDENT 3.5
322 \fIdevid\fP \- by device id (default, with pstart)
323 .sp
324 \fIpstart\fP \- physical start (relative to the beginning of the device)
325 .sp
326 \fIlstart\fP \- logical offset (in the logical address space)
327 .sp
328 \fIusage\fP \- by chunk usage (percentage)
329 .sp
330 \fIlength\fP \- by chunk length
331 .sp
332 \fItype\fP \- by chunk type (data, metadata, system)
333 .sp
334 \fIprofile\fP \- by chunk profile (single, DUP, RAID0, RAID1, ...)
335 .UNINDENT
336 .UNINDENT
337 .TP
338 .B \-\-raw
339 raw numbers in bytes, without the \fIB\fP suffix
340 .TP
341 .B \-\-human\-readable
342 print human friendly numbers, base 1024, this is the default
343 .TP
344 .B \-\-iec
345 select the 1024 base for the following options, according to the IEC standard
346 .TP
347 .B \-\-si
348 select the 1000 base for the following options, according to the SI standard
349 .TP
350 .B \-\-kbytes
351 show sizes in KiB, or kB with \-\-si
352 .TP
353 .B \-\-mbytes
354 show sizes in MiB, or MB with \-\-si
355 .TP
356 .B \-\-gbytes
357 show sizes in GiB, or GB with \-\-si
358 .TP
359 .B \-\-tbytes
360 show sizes in TiB, or TB with \-\-si
361 .UNINDENT
362 .UNINDENT
363 .INDENT 0.0
364 .TP
365 .B map\-swapfile [options] <file>
366 (needs root privileges)
367 .sp
368 Find device\-specific physical offset of \fIfile\fP that can be used for
369 hibernation. Also verify that the \fIfile\fP is suitable as a swapfile.
370 See also command \fBbtrfs filesystem mkswapfile\fP and the
371 \fI\%Swapfile feature\fP description.
372 .sp
373 \fBNOTE:\fP
374 .INDENT 7.0
375 .INDENT 3.5
376 Do not use \fBfilefrag\fP or \fIFIEMAP\fP ioctl values reported as
377 physical, this is different due to internal filesystem mappings.
378 The hibernation expects offset relative to the physical block device.
379 .UNINDENT
380 .UNINDENT
381 .sp
382 \fBOptions\fP
383 .INDENT 7.0
384 .TP
385 .B \-r|\-\-resume\-offset
386 print only the value suitable as resume offset for file \fB/sys/power/resume_offset\fP
387 .UNINDENT
388 .TP
389 .B min\-dev\-size [options] <path>
390 (needs root privileges)
391 .sp
392 return the minimum size the device can be shrunk to, without performing any
393 resize operation, this may be useful before executing the actual resize operation
394 .sp
395 \fBOptions\fP
396 .INDENT 7.0
397 .TP
398 .BI \-\-id \ <id>
399 specify the device \fIid\fP to query, default is 1 if this option is not used
400 .UNINDENT
401 .UNINDENT
402 .INDENT 0.0
403 .TP
404 .B rootid <path>
405 for a given file or directory, return the containing tree root id, but for a
406 subvolume itself return its own tree id (i.e. subvol id)
407 .sp
408 \fBNOTE:\fP
409 .INDENT 7.0
410 .INDENT 3.5
411 The result is undefined for the so\-called empty subvolumes (identified by
412 inode number 2), but such a subvolume does not contain any files anyway
413 .UNINDENT
414 .UNINDENT
415 .TP
416 .B subvolid\-resolve <subvolid> <path>
417 (needs root privileges)
418 .sp
419 resolve the absolute path of the subvolume id \fIsubvolid\fP
420 .TP
421 .B tree\-stats [options] <device>
422 (needs root privileges)
423 .sp
424 Print sizes and statistics of trees. This takes a device as an argument
425 and not a mount point unlike other commands.
426 .sp
427 \fBNOTE:\fP
428 .INDENT 7.0
429 .INDENT 3.5
430 In case the the filesystem is still mounted it\(aqs possible to
431 run the command but the results may be inaccurate or various
432 errors may be printed in case there are ongoing writes to the
433 filesystem. A warning is printed in such case.
434 .UNINDENT
435 .UNINDENT
436 .sp
437 \fBOptions\fP
438 .INDENT 7.0
439 .TP
440 .B \-b|\-\-raw
441 raw numbers in bytes, without the \fIB\fP suffix
442 .UNINDENT
443 .INDENT 7.0
444 .TP
445 .BI \-t \ <tree_id>
446 print only the tree with the specified ID, where the ID can be numerical or
447 common name in a flexible human readable form
448 .sp
449 The tree id name recognition rules:
450 .INDENT 7.0
451 .IP \(bu 2
452 case does not matter
453 .IP \(bu 2
454 the C source definition, e.g. BTRFS_ROOT_TREE_OBJECTID
455 .IP \(bu 2
456 short forms without BTRFS_ prefix, without _TREE and _OBJECTID suffix, e.g. ROOT_TREE, ROOT
457 .IP \(bu 2
458 convenience aliases, e.g. DEVICE for the DEV tree, CHECKSUM for CSUM
459 .IP \(bu 2
460 unrecognized ID is an error
461 .UNINDENT
462 .TP
463 .B \-\-human\-readable
464 print human friendly numbers, base 1024, this is the default
465 .TP
466 .B \-\-iec
467 select the 1024 base for the following options, according to the IEC standard
468 .TP
469 .B \-\-si
470 select the 1000 base for the following options, according to the SI standard
471 .TP
472 .B \-\-kbytes
473 show sizes in KiB, or kB with \-\-si
474 .TP
475 .B \-\-mbytes
476 show sizes in MiB, or MB with \-\-si
477 .TP
478 .B \-\-gbytes
479 show sizes in GiB, or GB with \-\-si
480 .TP
481 .B \-\-tbytes
482 show sizes in TiB, or TB with \-\-si
483 .UNINDENT
484 .UNINDENT
485 .SH EXIT STATUS
486 .sp
487 \fBbtrfs inspect\-internal\fP returns a zero exit status if it succeeds. Non zero is
488 returned in case of failure.
489 .SH AVAILABILITY
490 .sp
491 \fBbtrfs\fP is part of btrfs\-progs. Please refer to the documentation at
492 \X'tty: link https://btrfs.readthedocs.io'\fI\%https://btrfs.readthedocs.io\fP\X'tty: link'\&.
493 .SH SEE ALSO
494 .sp
495 \fI\%mkfs.btrfs(8)\fP
496 .\" Generated by docutils manpage writer.
497 .