Debian Codegraph @

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