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