1BTRFS-INSPECT-INTERNAL(8) BTRFS BTRFS-INSPECT-INTERNAL(8)
2
6 btrfs-inspect-internal - query various internal information
7
9 btrfs inspect-internal <subcommand> <args>
10
12 This command group provides an interface to query internal information.
13 The functionality ranges from a simple UI to an ioctl or a more complex
14 query that assembles the result from several internal structures. The
15 latter usually requires calls to privileged ioctls.
16
18 dump-super [options] <device> [device...]
19 Show btrfs superblock information stored on given devices in
20 textual form. By default the first superblock is printed, more
21 details about all copies or additional backup data can be
22 printed.
23 Besides verification of the filesystem signature, there are no
25 other sanity checks. The superblock checksum status is reported,
26 the device item and filesystem UUIDs are checked and reported.
27 NOTE:
29 The meaning of option -s has changed in version 4.8 to be
30 consistent with other tools to specify superblock copy rather
31 the offset. The old way still works, but prints a warning.
32 Please update your scripts to use --bytenr instead. The op‐
33 tion -i has been deprecated.
34 Options
36 -f|--full
38 print full superblock information, including the system
39 chunk array and backup roots
40 -a|--all
42 print information about all present superblock copies
43 (cannot be used together with -s option)
44 -i <super>
46 (deprecated since 4.8, same behaviour as --super)
47 --bytenr <bytenr>
49 specify offset to a superblock in a non-standard location
50 at bytenr, useful for debugging (disables the -f option)
51 If there are multiple options specified, only the last
53 one applies.
54 -F|--force
56 attempt to print the superblock even if a valid BTRFS
57 signature is not found; the result may be completely
58 wrong if the data does not resemble a superblock
59 -s|--super <bytenr>
61 (see compatibility note above)
62 specify which mirror to print, valid values are 0, 1 and
64 2 and the superblock must be present on the device with a
65 valid signature, can be used together with --force
66 dump-tree [options] <device> [device...]
68 Dump tree structures from a given device in textual form, expand
69 keys to human readable equivalents where possible. This is use‐
70 ful for analyzing filesystem state or inconsistencies and has a
71 positive educational effect on understanding the internal
72 filesystem structure.
73 NOTE:
75 Contains file names, consider that if you're asked to send
76 the dump for analysis. Does not contain file data.
77 Options
79 -e|--extents
81 print only extent-related information: extent and device
82 trees
83 -d|--device
85 print only device-related information: tree root, chunk
86 and device trees
87 -r|--roots
89 print only short root node information, i.e. the root
90 tree keys
91 -R|--backups
93 same as --roots plus print backup root info, i.e. the
94 backup root keys and the respective tree root block off‐
95 set
96 -u|--uuid
98 print only the uuid tree information, empty output if the
99 tree does not exist
100 -b <block_num>
102 print info of the specified block only, can be specified
103 multiple times
104 --follow
106 use with -b, print all children tree blocks of
107 <block_num>
108 --dfs (default up to 5.2)
110 use depth-first search to print trees, the nodes and
112 leaves are intermixed in the output
113 --bfs (default since 5.3)
115 use breadth-first search to print trees, the nodes are
117 printed before all leaves
118 --hide-names
120 print a placeholder HIDDEN instead of various names, use‐
121 ful for developers to inspect the dump while keeping po‐
122 tentially sensitive information hidden
123 This is:
125 • directory entries (files, directories, subvolumes)
127 • default subvolume
129 • extended attributes (name, value)
131 • hardlink names (if stored inside another item or as ex‐
133 tended references in standalone items)
134 NOTE:
136 Lengths are not hidden because they can be calculated
137 from the item size anyway.
138 --csum-headers
140 print b-tree node checksums stored in headers (metadata)
141 --csum-items
143 print checksums stored in checksum items (data)
144 --noscan
146 do not automatically scan the system for other devices
147 from the same filesystem, only use the devices provided
148 as the arguments
149 -t <tree_id>
151 print only the tree with the specified ID, where the ID
152 can be numerical or common name in a flexible human read‐
153 able form
154 The tree id name recognition rules:
156 • case does not matter
158 • the C source definition, e.g. BTRFS_ROOT_TREE_OBJECTID
160 • short forms without BTRFS_ prefix, without _TREE and
162 _OBJECTID suffix, e.g. ROOT_TREE, ROOT
163 • convenience aliases, e.g. DEVICE for the DEV tree,
165 CHECKSUM for CSUM
166 • unrecognized ID is an error
168 inode-resolve [-v] <ino> <path>
170 (needs root privileges)
171 resolve paths to all files with given inode number ino in a
173 given subvolume at path, i.e. all hardlinks
174 Options
176 -v (deprecated) alias for global -v option
178 logical-resolve [-Pvo] [-s <bufsize>] <logical> <path>
180 (needs root privileges)
181 resolve paths to all files at given logical address in the lin‐
183 ear filesystem space
184 Options
186 -P skip the path resolving and print the inodes instead
188 -o ignore offsets, find all references to an extent instead
190 of a single block. Requires kernel support for the V2
191 ioctl (added in 4.15). The results might need further
192 processing to filter out unwanted extents by the offset
193 that is supposed to be obtained by other means.
194 -s <bufsize>
196 set internal buffer for storing the file names to buf‐
197 size, default is 64KiB, maximum 16MiB. Buffer sizes over
198 64Kib require kernel support for the V2 ioctl (added in
199 4.15).
200 -v (deprecated) alias for global -v option
202 map-swapfile [options] <file>
204 (needs root privileges)
205 Find device-specific physical offset of file that can be used
207 for hibernation. Also verify that the file is suitable as a
208 swapfile. See also command btrfs filesystem mkswapfile and the
209 Swapfile feature description.
210 NOTE:
212 Do not use filefrag or FIEMAP ioctl values reported as physi‐
213 cal, this is different due to internal filesystem mappings.
214 The hibernation expects offset relative to the physical block
215 device.
216 Options
218 -r|--resume-offset
220 print only the value suitable as resume offset for file
221 /sys/power/resume_offset
222 min-dev-size [options] <path>
224 (needs root privileges)
225 return the minimum size the device can be shrunk to, without
227 performing any resize operation, this may be useful before exe‐
228 cuting the actual resize operation
229 Options
231 --id <id>
233 specify the device id to query, default is 1 if this op‐
234 tion is not used
235 rootid <path>
237 for a given file or directory, return the containing tree root
238 id, but for a subvolume itself return its own tree id (i.e. sub‐
239 vol id)
240 NOTE:
242 The result is undefined for the so-called empty subvolumes
243 (identified by inode number 2), but such a subvolume does not
244 contain any files anyway
245 subvolid-resolve <subvolid> <path>
247 (needs root privileges)
248 resolve the absolute path of the subvolume id subvolid
250 tree-stats [options] <device>
252 (needs root privileges)
253 Print sizes and statistics of trees. This takes a device as an
255 argument and not a mount point unlike other commands.
256 NOTE:
258 In case the the filesystem is still mounted it's possible to
259 run the command but the results may be inaccurate or various
260 errors may be printed in case there are ongoing writes to the
261 filesystem. A warning is printed in such case.
262 Options
264 -b Print raw numbers in bytes.
266
268 btrfs inspect-internal returns a zero exit status if it succeeds. Non
269 zero is returned in case of failure.
270
272 btrfs is part of btrfs-progs. Please refer to the documentation at
273 https://btrfs.readthedocs.io.
274
276 mkfs.btrfs(8)
2776.6.2 Nov 24, 2023 BTRFS-INSPECT-INTERNAL(8)