1xfs_db(8) System Manager's Manual xfs_db(8)
2
6 xfs_db - debug an XFS filesystem
7
9 xfs_db [ -c cmd ] ... [ -i|r|x|F ] [ -f ] [ -l logdev ] [ -p progname ]
10 device
11 xfs_db -V
12
14 xfs_db is used to examine an XFS filesystem. Under rare circumstances
15 it can also be used to modify an XFS filesystem, but that task is nor‐
16 mally left to xfs_repair(8) or to scripts such as xfs_admin(8) that run
17 xfs_db.
18
20 -c cmd xfs_db commands may be run interactively (the default) or as
21 arguments on the command line. Multiple -c arguments may be
22 given. The commands are run in the sequence given, then the pro‐
23 gram exits.
24 -f Specifies that the filesystem image to be processed is stored in
26 a regular file at device (see the mkfs.xfs(8) -d file option).
27 This might happen if an image copy of a filesystem has been made
28 into an ordinary file with xfs_copy(8).
29 -F Specifies that we want to continue even if the superblock magic
31 is not correct. For use in xfs_metadump.
32 -i Allows execution on a mounted filesystem, provided it is mounted
34 read-only. Useful for shell scripts which must only operate on
35 filesystems in a guaranteed consistent state (either unmounted
36 or mounted read-only). These semantics are slightly different to
37 that of the -r option.
38 -l logdev
40 Specifies the device where the filesystems external log resides.
41 Only for those filesystems which use an external log. See the
42 mkfs.xfs(8) -l option, and refer to xfs(5) for a detailed
43 description of the XFS log.
44 -p progname
46 Set the program name to progname for prompts and some error mes‐
47 sages, the default value is xfs_db.
48 -r Open device or filename read-only. This option is required if
50 the filesystem is mounted. It is only necessary to omit this
51 flag if a command that changes data (write, blocktrash, crc) is
52 to be used.
53 -x Specifies expert mode. This enables the (write, blocktrash, crc
55 invalidate/revalidate) commands.
56 -V Prints the version number and exits.
58
60 xfs_db commands can be broken up into two classes. Most commands are
61 for the navigation and display of data structures in the filesystem.
62 Other commands are for scanning the filesystem in some way.
63 Commands which are used to navigate the filesystem structure take argu‐
65 ments which reflect the names of filesystem structure fields. There
66 can be multiple field names separated by dots when the underlying
67 structures are nested, as in C. The field names can be indexed (as an
68 array index) if the underlying field is an array. The array indices
69 can be specified as a range, two numbers separated by a dash.
70 xfs_db maintains a current address in the filesystem. The granularity
72 of the address is a filesystem structure. This can be a filesystem
73 block, an inode or quota (smaller than a filesystem block), or a direc‐
74 tory block (could be larger than a filesystem block). There are a
75 variety of commands to set the current address. Associated with the
76 current address is the current data type, which is the structural type
77 of this data. Commands which follow the structure of the filesystem
78 always set the type as well as the address. Commands which examine
79 pieces of an individual file (inode) need the current inode to be set,
80 this is done with the inode command.
81 The current address/type information is actually maintained in a stack
83 that can be explicitly manipulated with the push, pop, and stack com‐
84 mands. This allows for easy examination of a nested filesystem struc‐
85 ture. Also, the last several locations visited are stored in a ring
86 buffer which can be manipulated with the forward, back, and ring com‐
87 mands.
88 XFS filesystems are divided into a small number of allocation groups.
90 xfs_db maintains a notion of the current allocation group which is
91 manipulated by some commands. The initial allocation group is 0.
92
94 Many commands have extensive online help. Use the help command for more
95 details on any command.
96 a See the addr command.
98 ablock filoff
100 Set current address to the offset filoff (a filesystem block
101 number) in the attribute area of the current inode.
102 addr [field-expression]
104 Set current address to the value of the field-expression. This
105 is used to "follow" a reference in one structure to the object
106 being referred to. If no argument is given, the current address
107 is printed.
108 agf [agno]
110 Set current address to the AGF block for allocation group agno.
111 If no argument is given, use the current allocation group.
112 agfl [agno]
114 Set current address to the AGFL block for allocation group agno.
115 If no argument is given, use the current allocation group.
116 agi [agno]
118 Set current address to the AGI block for allocation group agno.
119 If no argument is given, use the current allocation group.
120 b See the back command.
122 back Move to the previous location in the position ring.
124 blockfree
126 Free block usage information collected by the last execution of
127 the blockget command. This must be done before another blockget
128 command can be given, presumably with different arguments than
129 the previous one.
130 blockget [-npvs] [-b bno] ... [-i ino] ...
132 Get block usage and check filesystem consistency. The informa‐
133 tion is saved for use by a subsequent blockuse, ncheck, or
134 blocktrash command.
135 -b is used to specify filesystem block numbers about which
137 verbose information should be printed.
138 -i is used to specify inode numbers about which verbose
140 information should be printed.
141 -n is used to save pathnames for inodes visited, this is
143 used to support the xfs_ncheck(8) command. It also means
144 that pathnames will be printed for inodes that have prob‐
145 lems. This option uses a lot of memory so is not enabled
146 by default.
147 -p causes error messages to be prefixed with the filesystem
149 name being processed. This is useful if several copies of
150 xfs_db are run in parallel.
151 -s restricts output to severe errors only. This is useful if
153 the output is too long otherwise.
154 -v enables verbose output. Messages will be printed for
156 every block and inode processed.
157 blocktrash [-z] [-o offset] [-n count] [-x min] [-y max] [-s seed]
159 [-0|1|2|3] [-t type] ...
160 Trash randomly selected filesystem metadata blocks. Trashing
161 occurs to randomly selected bits in the chosen blocks. This
162 command is available only in debugging versions of xfs_db. It
163 is useful for testing xfs_repair(8).
164 -0 | -1 | -2 | -3
166 These are used to set the operating mode for blocktrash.
167 Only one can be used: -0 changed bits are cleared; -1
168 changed bits are set; -2 changed bits are inverted; -3
169 changed bits are randomized.
170 -n supplies the count of block-trashings to perform (default
172 1).
173 -o supplies the bit offset at which to start trashing the
175 block. If the value is preceded by a '+', the trashing
176 will start at a randomly chosen offset that is larger
177 than the value supplied. The default is to randomly
178 choose an offset anywhere in the block.
179 -s supplies a seed to the random processing.
181 -t gives a type of blocks to be selected for trashing. Mul‐
183 tiple -t options may be given. If no -t options are given
184 then all metadata types can be trashed.
185 -x sets the minimum size of bit range to be trashed. The
187 default value is 1.
188 -y sets the maximum size of bit range to be trashed. The
190 default value is 1024.
191 -z trashes the block at the top of the stack. It is not
193 necessary to run blockget if this option is supplied.
194 blockuse [-n] [-c count]
196 Print usage for current filesystem block(s). For each block,
197 the type and (if any) inode are printed.
198 -c specifies a count of blocks to process. The default value
200 is 1 (the current block only).
201 -n specifies that file names should be printed. The prior
203 blockget command must have also specified the -n option.
204 bmap [-a] [-d] [block [len]]
206 Show the block map for the current inode. The map display can
207 be restricted to an area of the file with the block and len
208 arguments. If block is given and len is omitted then 1 is
209 assumed for len.
210 The -a and -d options are used to select the attribute or data
212 area of the inode, if neither option is given then both areas
213 are shown.
214 btdump [-a] [-i]
216 If the cursor points to a btree node, dump the btree from that
217 block downward. If instead the cursor points to an inode, dump
218 the data fork block mapping btree if there is one. If the cur‐
219 sor points to a directory or extended attribute btree node, dump
220 that. By default, only records stored in the btree are dumped.
221 -a If the cursor points at an inode, dump the extended
223 attribute block mapping btree, if present.
224 -i Dump all keys and pointers in intermediate btree nodes,
226 and all records in leaf btree nodes.
227 check See the blockget command.
229 convert type number [type number] ... type
231 Convert from one address form to another. The known types, with
232 alternate names, are:
233 agblock or agbno (filesystem block within an allocation
234 group)
235 agino or aginode (inode number within an allocation group)
236 agnumber or agno (allocation group number)
237 bboff or daddroff (byte offset in a daddr)
238 blkoff or fsboff or agboff (byte offset in a agblock or
239 fsblock)
240 byte or fsbyte (byte address in filesystem)
241 daddr or bb (disk address, 512-byte blocks)
242 fsblock or fsb or fsbno (filesystem block, see the fsblock
243 command)
244 ino or inode (inode number)
245 inoidx or offset (index of inode in filesystem block)
246 inooff or inodeoff (byte offset in inode)
247 Only conversions that "make sense" are allowed. The compound
249 form (with more than three arguments) is useful for conversions
250 such as convert agno ag agbno agb fsblock.
251 crc [-i|-r|-v]
253 Invalidates, revalidates, or validates the CRC (checksum) field
254 of the current structure, if it has one. This command is avail‐
255 able only on CRC-enabled filesystems. With no argument, valida‐
256 tion is performed. Each command will display the resulting CRC
257 value and state.
258 -i Invalidate the structure's CRC value (incrementing it by
260 one), and write it to disk.
261 -r Recalculate the current structure's correct CRC value,
263 and write it to disk.
264 -v Validate and display the current value and state of the
266 structure's CRC.
267 daddr [d]
269 Set current address to the daddr (512 byte block) given by d.
270 If no value for d is given, the current address is printed,
271 expressed as a daddr. The type is set to data (uninterpreted).
272 dblock filoff
274 Set current address to the offset filoff (a filesystem block
275 number) in the data area of the current inode.
276 debug [flagbits]
278 Set debug option bits. These are used for debugging xfs_db. If
279 no value is given for flagbits, print the current debug option
280 bits. These are for the use of the implementor.
281 dquot [-g|-p|-u] id
283 Set current address to a group, project or user quota block for
284 the given ID. Defaults to user quota.
285 echo [arg] ...
287 Echo the arguments to the output.
288 f See the forward command.
290 forward
292 Move forward to the next entry in the position ring.
293 frag [-adflqRrv]
295 Get file fragmentation data. This prints information about frag‐
296 mentation of file data in the filesystem (as opposed to fragmen‐
297 tation of freespace, for which see the freesp command). Every
298 file in the filesystem is examined to see how far from ideal its
299 extent mappings are. A summary is printed giving the totals.
300 -v sets verbosity, every inode has information printed for
302 it. The remaining options select which inodes and
303 extents are examined. If no options are given then all
304 are assumed set, otherwise just those given are enabled.
305 -a enables processing of attribute data.
307 -d enables processing of directory data.
309 -f enables processing of regular file data.
311 -l enables processing of symbolic link data.
313 -q enables processing of quota file data.
315 -R enables processing of realtime control file data.
317 -r enables processing of realtime file data.
319 freesp [-bcds] [-A alignment] [-a ag] ... [-e i] [-h h1] ... [-m m]
321 Summarize free space for the filesystem. The free blocks are
322 examined and totalled, and displayed in the form of a histogram,
323 with a count of extents in each range of free extent sizes.
324 -A reports only free extents with starting blocks aligned to
326 alignment blocks.
327 -a adds ag to the list of allocation groups to be processed.
329 If no -a options are given then all allocation groups are
330 processed.
331 -b specifies that the histogram buckets are binary-sized,
333 with the starting sizes being the powers of 2.
334 -c specifies that freesp will search the by-size (cnt) space
336 Btree instead of the default by-block (bno) space Btree.
337 -d specifies that every free extent will be displayed.
339 -e specifies that the histogram buckets are equal-sized,
341 with the size specified as i.
342 -h specifies a starting block number for a histogram bucket
344 as h1. Multiple -h's are given to specify the complete
345 set of buckets.
346 -m specifies that the histogram starting block numbers are
348 powers of m. This is the general case of -b.
349 -s specifies that a final summary of total free extents,
351 free blocks, and the average free extent size is printed.
352 fsb See the fsblock command.
354 fsblock [fsb]
356 Set current address to the fsblock value given by fsb. If no
357 value for fsb is given the current address is printed, expressed
358 as an fsb. The type is set to data (uninterpreted). XFS
359 filesystem block numbers are computed ((agno << agshift) |
360 agblock) where agshift depends on the size of an allocation
361 group. Use the convert command to convert to and from this form.
362 Block numbers given for file blocks (for instance from the bmap
363 command) are in this form.
364 fsmap [ start ] [ end ]
366 Prints the mapping of disk blocks used by an XFS filesystem.
367 The map lists each extent used by files, allocation group meta‐
368 data, journalling logs, and static filesystem metadata, as well
369 as any regions that are unused. All blocks, offsets, and
370 lengths are specified in units of 512-byte blocks, no matter
371 what the filesystem's block size is. The optional start and end
372 arguments can be used to constrain the output to a particular
373 range of disk blocks.
374 fuzz [-c] [-d] field action
376 Write garbage into a specific structure field on disk. Expert
377 mode must be enabled to use this command. The operation happens
378 immediately; there is no buffering.
379 The fuzz command can take the following actions against a field:
381 zeroes
383 Clears all bits in the field.
384 ones
386 Sets all bits in the field.
387 firstbit
389 Flips the first bit in the field. For a scalar value,
390 this is the highest bit.
391 middlebit
393 Flips the middle bit in the field.
394 lastbit
396 Flips the last bit in the field. For a scalar value,
397 this is the lowest bit.
398 add Adds a small value to a scalar field.
400 sub Subtracts a small value from a scalar field.
402 random
404 Randomizes the contents of the field.
405 The following switches affect the write behavior:
407 -c Skip write verifiers and CRC recalculation; allows
409 invalid data to be written to disk.
410 -d Skip write verifiers but perform CRC recalculation;
412 allows invalid data to be written to disk to test detec‐
413 tion of invalid data.
414 hash string
416 Prints the hash value of string using the hash function of the
417 XFS directory and attribute implementation.
418 help [command]
420 Print help for one or all commands.
421 info Displays selected geometry information about the filesystem.
423 The output will have the same format that mkfs.xfs(8) prints
424 when creating a filesystem or xfs_info(8) prints when querying a
425 filesystem.
426 inode [inode#]
428 Set the current inode number. If no inode# is given, print the
429 current inode number.
430 label [label]
432 Set the filesystem label. The filesystem label can be used by
433 mount(8) instead of using a device special file. The maximum
434 length of an XFS label is 12 characters - use of a longer label
435 will result in truncation and a warning will be issued. If no
436 label is given, the current filesystem label is printed.
437 log [stop | start filename]
439 Start logging output to filename, stop logging, or print the
440 current logging status.
441 logres Print transaction reservation size information for each transac‐
443 tion type. This makes it easier to find discrepancies in the
444 reservation calculations between xfsprogs and the kernel, which
445 will help when diagnosing minimum log size calculation errors.
446 metadump [-egow] filename
448 Dumps metadata to a file. See xfs_metadump(8) for more informa‐
449 tion.
450 ncheck [-s] [-i ino] ...
452 Print name-inode pairs. A blockget -n command must be run first
453 to gather the information.
454 -i specifies an inode number to be printed. If no -i options
456 are given then all inodes are printed.
457 -s specifies that only setuid and setgid files are printed.
459 p See the print command.
461 pop Pop location from the stack.
463 print [field-expression] ...
465 Print field values. If no argument is given, print all fields
466 in the current structure.
467 push [command]
469 Push location to the stack. If command is supplied, set the cur‐
470 rent location to the results of command after pushing the old
471 location.
472 q See the quit command.
474 quit Exit xfs_db.
476 ring [index]
478 Show position ring (if no index argument is given), or move to a
479 specific entry in the position ring given by index.
480 sb [agno]
482 Set current address to SB header in allocation group agno. If
483 no agno is given, use the current allocation group number.
484 source source-file
486 Process commands from source-file. source commands can be
487 nested.
488 stack View the location stack.
490 type [type]
492 Set the current data type to type. If no argument is given,
493 show the current data type. The possible data types are: agf,
494 agfl, agi, attr, bmapbta, bmapbtd, bnobt, cntbt, data, dir,
495 dir2, dqblk, inobt, inode, log, refcntbt, rmapbt, rtbitmap,
496 rtsummary, sb, symlink and text. See the TYPES section below
497 for more information on these data types.
498 uuid [uuid | generate | rewrite | restore]
500 Set the filesystem universally unique identifier (UUID). The
501 filesystem UUID can be used by mount(8) instead of using a
502 device special file. The uuid can be set directly to the
503 desired UUID, or it can be automatically generated using the
504 generate option. These options will both write the UUID into
505 every copy of the superblock in the filesystem. On a CRC-
506 enabled filesystem, this will set an incompatible superblock
507 flag, and the filesystem will not be mountable with older ker‐
508 nels. This can be reverted with the restore option, which will
509 copy the original UUID back into place and clear the incompati‐
510 ble flag as needed. rewrite copies the current UUID from the
511 primary superblock to all secondary copies of the superblock.
512 If no argument is given, the current filesystem UUID is printed.
513 version [feature | versionnum features2]
515 Enable selected features for a filesystem (certain features can
516 be enabled on an unmounted filesystem, after mkfs.xfs(8) has
517 created the filesystem). Support for unwritten extents can be
518 enabled using the extflg option. Support for version 2 log for‐
519 mat can be enabled using the log2 option. Support for extended
520 attributes can be enabled using the attr1 or attr2 option. Once
521 enabled, extended attributes cannot be disabled, but the user
522 may toggle between attr1 and attr2 at will (older kernels may
523 not support the newer version).
524 If no argument is given, the current version and feature bits
526 are printed. With one argument, this command will write the
527 updated version number into every copy of the superblock in the
528 filesystem. If two arguments are given, they will be used as
529 numeric values for the versionnum and features2 bits respec‐
530 tively, and their string equivalent reported (but no modifica‐
531 tions are made).
532 write [-c|-d] [field value] ...
534 Write a value to disk. Specific fields can be set in structures
535 (struct mode), or a block can be set to data values (data mode),
536 or a block can be set to string values (string mode, for symlink
537 blocks). The operation happens immediately: there is no buffer‐
538 ing.
539 Struct mode is in effect when the current type is structural,
541 i.e. not data. For struct mode, the syntax is "write field
542 value".
543 Data mode is in effect when the current type is data. In this
545 case the contents of the block can be shifted or rotated left or
546 right, or filled with a sequence, a constant value, or a random
547 value. In this mode write with no arguments gives more informa‐
548 tion on the allowed commands.
549 -c Skip write verifiers and CRC recalculation; allows
551 invalid data to be written to disk.
552 -d Skip write verifiers but perform CRC recalculation. This
554 allows invalid data to be written to disk to test detec‐
555 tion of invalid data. (This is not possible for some
556 types.)
557
559 This section gives the fields in each structure type and their mean‐
560 ings. Note that some types of block cover multiple actual structures,
561 for instance directory blocks.
562 agf The AGF block is the header for block allocation information;
564 it is in the second 512-byte block of each allocation group.
565 The following fields are defined:
566 magicnum AGF block magic number, 0x58414746 ('XAGF').
567 versionnum version number, currently 1.
568 seqno sequence number starting from 0.
569 length size in filesystem blocks of the allocation
570 group. All allocation groups except the last
571 one of the filesystem have the superblock's
572 agblocks value here.
573 bnoroot block number of the root of the Btree holding
574 free space information sorted by block num‐
575 ber.
576 cntroot block number of the root of the Btree holding
577 free space information sorted by block count.
578 bnolevel number of levels in the by-block-number
579 Btree.
580 cntlevel number of levels in the by-block-count Btree.
581 flfirst index into the AGFL block of the first active
582 entry.
583 fllast index into the AGFL block of the last active
584 entry.
585 flcount count of active entries in the AGFL block.
586 freeblks count of blocks represented in the freespace
587 Btrees.
588 longest longest free space represented in the
589 freespace Btrees.
590 btreeblks number of blocks held in the AGF Btrees.
591 agfl The AGFL block contains block numbers for use of the block
593 allocator; it is in the fourth 512-byte block of each alloca‐
594 tion group. Each entry in the active list is a block number
595 within the allocation group that can be used for any purpose
596 if space runs low. The AGF block fields flfirst, fllast, and
597 flcount designate which entries are currently active. Entry
598 space is allocated in a circular manner within the AGFL
599 block. Fields defined:
600 bno array of all block numbers. Even those which
601 are not active are printed.
602 agi The AGI block is the header for inode allocation information;
604 it is in the third 512-byte block of each allocation group.
605 Fields defined:
606 magicnum AGI block magic number, 0x58414749 ('XAGI').
607 versionnum version number, currently 1.
608 seqno sequence number starting from 0.
609 length size in filesystem blocks of the allocation
610 group.
611 count count of inodes allocated.
612 root block number of the root of the Btree holding
613 inode allocation information.
614 level number of levels in the inode allocation
615 Btree.
616 freecount count of allocated inodes that are not in
617 use.
618 newino last inode number allocated.
619 dirino unused.
620 unlinked an array of inode numbers within the alloca‐
621 tion group. The entries in the AGI block are
622 the heads of lists which run through the
623 inode next_unlinked field. These inodes are
624 to be unlinked the next time the filesystem
625 is mounted.
626 attr An attribute fork is organized as a Btree with the actual
628 data embedded in the leaf blocks. The root of the Btree is
629 found in block 0 of the fork. The index (sort order) of the
630 Btree is the hash value of the attribute name. All the
631 blocks contain a blkinfo structure at the beginning, see type
632 dir for a description. Nonleaf blocks are identical in format
633 to those for version 1 and version 2 directories, see type
634 dir for a description. Leaf blocks can refer to "local" or
635 "remote" attribute values. Local values are stored directly
636 in the leaf block. Leaf blocks contain the following fields:
637 hdr header containing a blkinfo structure info
638 (magic number 0xfbee), a count of active
639 entries, usedbytes total bytes of names and
640 values, the firstused byte in the name area,
641 holes set if the block needs compaction, and
642 array freemap as for dir leaf blocks.
643 entries array of structures containing a hashval,
644 nameidx (index into the block of the name),
645 and flags incomplete, root, and local.
646 nvlist array of structures describing the attribute
647 names and values. Fields always present: val‐
648 uelen (length of value in bytes), namelen,
649 and name. Fields present for local values:
650 value (value string). Fields present for
651 remote values: valueblk (fork block number of
652 containing the value).
653 Remote values are stored in an independent block in the
655 attribute fork. Prior to v5, value blocks had no structure,
656 but in v5 they acquired a header structure with the following
657 fields:
658 magic attr3 remote block magic number, 0x5841524d
659 ('XARM').
660 offset Byte offset of this data block within the
661 overall attribute value.
662 bytes Number of bytes stored in this block.
663 crc Checksum of the attribute block contents.
664 uuid Filesystem UUID.
665 owner Inode that owns this attribute value.
666 bno Block offset of this block within the inode's
667 attribute fork.
668 lsn Log serial number of the last time this block
669 was logged.
670 data The attribute value data.
671 bmapbt Files with many extents in their data or attribute fork will
673 have the extents described by the contents of a Btree for
674 that fork, instead of being stored directly in the inode.
675 Each bmap Btree starts with a root block contained within the
676 inode. The other levels of the Btree are stored in filesys‐
677 tem blocks. The blocks are linked to sibling left and right
678 blocks at each level, as well as by pointers from parent to
679 child blocks. Each block contains the following fields:
680 magic bmap Btree block magic number, 0x424d4150
681 ('BMAP').
682 level level of this block above the leaf level.
683 numrecs number of records or keys in the block.
684 leftsib left (logically lower) sibling block, 0 if
685 none.
686 rightsib right (logically higher) sibling block, 0 if
687 none.
688 recs [leaf blocks only] array of extent records.
689 Each record contains startoff, startblock,
690 blockcount, and extentflag (1 if the extent
691 is unwritten).
692 keys [non-leaf blocks only] array of key records.
693 These are the first key value of each block
694 in the level below this one. Each record con‐
695 tains startoff.
696 ptrs [non-leaf blocks only] array of child block
697 pointers. Each pointer is a filesystem block
698 number to the next level in the Btree.
699 bnobt There is one set of filesystem blocks forming the by-block-
701 number allocation Btree for each allocation group. The root
702 block of this Btree is designated by the bnoroot field in the
703 corresponding AGF block. The blocks are linked to sibling
704 left and right blocks at each level, as well as by pointers
705 from parent to child blocks. Each block has the following
706 fields:
707 magic BNOBT block magic number, 0x41425442
708 ('ABTB').
709 level level number of this block, 0 is a leaf.
710 numrecs number of data entries in the block.
711 leftsib left (logically lower) sibling block, 0 if
712 none.
713 rightsib right (logically higher) sibling block, 0 if
714 none.
715 recs [leaf blocks only] array of freespace
716 records. Each record contains startblock and
717 blockcount.
718 keys [non-leaf blocks only] array of key records.
719 These are the first value of each block in
720 the level below this one. Each record con‐
721 tains startblock and blockcount.
722 ptrs [non-leaf blocks only] array of child block
723 pointers. Each pointer is a block number
724 within the allocation group to the next level
725 in the Btree.
726 cntbt There is one set of filesystem blocks forming the by-block-
728 count allocation Btree for each allocation group. The root
729 block of this Btree is designated by the cntroot field in the
730 corresponding AGF block. The blocks are linked to sibling
731 left and right blocks at each level, as well as by pointers
732 from parent to child blocks. Each block has the following
733 fields:
734 magic CNTBT block magic number, 0x41425443
735 ('ABTC').
736 level level number of this block, 0 is a leaf.
737 numrecs number of data entries in the block.
738 leftsib left (logically lower) sibling block, 0 if
739 none.
740 rightsib right (logically higher) sibling block, 0 if
741 none.
742 recs [leaf blocks only] array of freespace
743 records. Each record contains startblock and
744 blockcount.
745 keys [non-leaf blocks only] array of key records.
746 These are the first value of each block in
747 the level below this one. Each record con‐
748 tains blockcount and startblock.
749 ptrs [non-leaf blocks only] array of child block
750 pointers. Each pointer is a block number
751 within the allocation group to the next level
752 in the Btree.
753 data User file blocks, and other blocks whose type is unknown,
755 have this type for display purposes in xfs_db. The block
756 data is displayed in hexadecimal format.
757 dir A version 1 directory is organized as a Btree with the direc‐
759 tory data embedded in the leaf blocks. The root of the Btree
760 is found in block 0 of the file. The index (sort order) of
761 the Btree is the hash value of the entry name. All the blocks
762 contain a blkinfo structure at the beginning with the follow‐
763 ing fields:
764 forw next sibling block.
765 back previous sibling block.
766 magic magic number for this block type.
767 The non-leaf (node) blocks have the following fields:
768 hdr header containing a blkinfo structure info
769 (magic number 0xfebe), the count of active
770 entries, and the level of this block above
771 the leaves.
772 btree array of entries containing hashval and
773 before fields. The before value is a block
774 number within the directory file to the child
775 block, the hashval is the last hash value in
776 that block.
777 The leaf blocks have the following fields:
778 hdr header containing a blkinfo structure info
779 (magic number 0xfeeb), the count of active
780 entries, namebytes (total name string bytes),
781 holes flag (block needs compaction), and
782 freemap (array of base, size entries for free
783 regions).
784 entries array of structures containing hashval,
785 nameidx (byte index into the block of the
786 name string), and namelen.
787 namelist array of structures containing inumber and
788 name.
789 dir2 A version 2 directory has four kinds of blocks. Data blocks
791 start at offset 0 in the file. There are two kinds of data
792 blocks: single-block directories have the leaf information
793 embedded at the end of the block, data blocks in multi-block
794 directories do not. Node and leaf blocks start at offset
795 32GiB (with either a single leaf block or the root node
796 block). Freespace blocks start at offset 64GiB. The node
797 and leaf blocks form a Btree, with references to the data in
798 the data blocks. The freespace blocks form an index of long‐
799 est free spaces within the data blocks.
800 A single-block directory block contains the following fields:
802 bhdr header containing magic number 0x58443242
803 ('XD2B') and an array bestfree of the longest
804 3 free spaces in the block (offset, length).
805 bu array of union structures. Each element is
806 either an entry or a freespace. For entries,
807 there are the following fields: inumber,
808 namelen, name, and tag. For freespace, there
809 are the following fields: freetag (0xffff),
810 length, and tag. The tag value is the byte
811 offset in the block of the start of the entry
812 it is contained in.
813 bleaf array of leaf entries containing hashval and
814 address. The address is a 64-bit word offset
815 into the file.
816 btail tail structure containing the total count of
817 leaf entries and stale count of unused leaf
818 entries.
819 A data block contains the following fields:
820 dhdr header containing magic number 0x58443244
821 ('XD2D') and an array bestfree of the longest
822 3 free spaces in the block (offset, length).
823 du array of union structures as for bu.
824 Leaf blocks have two possible forms. If the Btree consists of
825 a single leaf then the freespace information is in the leaf
826 block, otherwise it is in separate blocks and the root of the
827 Btree is a node block. A leaf block contains the following
828 fields:
829 lhdr header containing a blkinfo structure info
830 (magic number 0xd2f1 for the single leaf
831 case, 0xd2ff for the true Btree case), the
832 total count of leaf entries, and stale count
833 of unused leaf entries.
834 lents leaf entries, as for bleaf.
835 lbests [single leaf only] array of values which rep‐
836 resent the longest freespace in each data
837 block in the directory.
838 ltail [single leaf only] tail structure containing
839 bestcount count of lbests.
840 A node block is identical to that for types attr and dir.
841 A freespace block contains the following fields:
843 fhdr header containing magic number 0x58443246
844 ('XD2F'), firstdb first data block number
845 covered by this freespace block, nvalid num‐
846 ber of valid entries, and nused number of
847 entries representing real data blocks.
848 fbests array of values as for lbests.
849 dqblk The quota information is stored in files referred to by the
851 superblock uquotino and pquotino fields. Each filesystem
852 block in a quota file contains a constant number of quota
853 entries. The quota entry size is currently 136 bytes, so with
854 a 4KiB filesystem block size there are 30 quota entries per
855 block. The dquot command is used to locate these entries in
856 the filesystem. The file entries are indexed by the user or
857 project identifier to determine the block and offset. Each
858 quota entry has the following fields:
859 magic magic number, 0x4451 ('DQ').
860 version version number, currently 1.
861 flags flags, values include 0x01 for user quota,
862 0x02 for project quota.
863 id user or project identifier.
864 blk_hardlimit absolute limit on blocks in use.
865 blk_softlimit preferred limit on blocks in use.
866 ino_hardlimit absolute limit on inodes in use.
867 ino_softlimit preferred limit on inodes in use.
868 bcount blocks actually in use.
869 icount inodes actually in use.
870 itimer time when service will be refused if soft
871 limit is violated for inodes.
872 btimer time when service will be refused if soft
873 limit is violated for blocks.
874 iwarns number of warnings issued about inode
875 limit violations.
876 bwarns number of warnings issued about block
877 limit violations.
878 rtb_hardlimit absolute limit on realtime blocks in use.
879 rtb_softlimit preferred limit on realtime blocks in use.
880 rtbcount realtime blocks actually in use.
881 rtbtimer time when service will be refused if soft
882 limit is violated for realtime blocks.
883 rtbwarns number of warnings issued about realtime
884 block limit violations.
885 inobt There is one set of filesystem blocks forming the inode allo‐
887 cation Btree for each allocation group. The root block of
888 this Btree is designated by the root field in the correspond‐
889 ing AGI block. The blocks are linked to sibling left and
890 right blocks at each level, as well as by pointers from par‐
891 ent to child blocks. Each block has the following fields:
892 magic INOBT block magic number, 0x49414254
893 ('IABT').
894 level level number of this block, 0 is a leaf.
895 numrecs number of data entries in the block.
896 leftsib left (logically lower) sibling block, 0 if
897 none.
898 rightsib right (logically higher) sibling block, 0 if
899 none.
900 recs [leaf blocks only] array of inode records.
901 Each record contains startino allocation-
902 group relative inode number, freecount count
903 of free inodes in this chunk, and free bit‐
904 map, LSB corresponds to inode 0.
905 keys [non-leaf blocks only] array of key records.
906 These are the first value of each block in
907 the level below this one. Each record con‐
908 tains startino.
909 ptrs [non-leaf blocks only] array of child block
910 pointers. Each pointer is a block number
911 within the allocation group to the next level
912 in the Btree.
913 inode Inodes are allocated in "chunks" of 64 inodes each. Usually a
915 chunk is multiple filesystem blocks, although there are cases
916 with large filesystem blocks where a chunk is less than one
917 block. The inode Btree (see inobt above) refers to the inode
918 numbers per allocation group. The inode numbers directly
919 reflect the location of the inode block on disk. Use the
920 inode command to point xfs_db to a specific inode. Each inode
921 contains four regions: core, next_unlinked, u, and a. core
922 contains the fixed information. next_unlinked is separated
923 from the core due to journaling considerations, see type agi
924 field unlinked. u is a union structure that is different in
925 size and format depending on the type and representation of
926 the file data ("data fork"). a is an optional union struc‐
927 ture to describe attribute data, that is different in size,
928 format, and location depending on the presence and represen‐
929 tation of attribute data, and the size of the u data
930 ("attribute fork"). xfs_db automatically selects the proper
931 union members based on information in the inode.
932 The following are fields in the inode core:
934 magic inode magic number, 0x494e ('IN').
935 mode mode and type of file, as described in
936 chmod(2), mknod(2), and stat(2).
937 version inode version, 1 or 2.
938 format format of u union data (0: xfs_dev_t, 1:
939 local file - in-inode directory or symlink,
940 2: extent list, 3: Btree root, 4: unique id
941 [unused]).
942 nlinkv1 number of links to the file in a version 1
943 inode.
944 nlinkv2 number of links to the file in a version 2
945 inode.
946 projid_lo owner's project id (low word; version 2 inode
947 only). projid_hi owner's project id (high
948 word; version 2 inode only).
949 uid owner's user id.
950 gid owner's group id.
951 atime time last accessed (seconds and nanoseconds).
952 mtime time last modified.
953 ctime time created or inode last modified.
954 size number of bytes in the file.
955 nblocks total number of blocks in the file including
956 indirect and attribute.
957 extsize basic/minimum extent size for the file.
958 nextents number of extents in the data fork.
959 naextents number of extents in the attribute fork.
960 forkoff attribute fork offset in the inode, in 64-bit
961 words from the start of u.
962 aformat format of a data (1: local attribute data, 2:
963 extent list, 3: Btree root).
964 dmevmask DMAPI event mask.
965 dmstate DMAPI state information.
966 newrtbm file is the realtime bitmap and is "new" for‐
967 mat.
968 prealloc file has preallocated data space after EOF.
969 realtime file data is in the realtime subvolume.
970 gen inode generation number.
971 The following fields are in the u data fork union:
972 bmbt bmap Btree root. This looks like a bmapbtd
973 block with redundant information removed.
974 bmx array of extent descriptors.
975 dev dev_t for the block or character device.
976 sfdir shortform (in-inode) version 1 directory.
977 This consists of a hdr containing the parent
978 inode number and a count of active entries in
979 the directory, followed by an array list of
980 hdr.count entries. Each such entry contains
981 inumber, namelen, and name string.
982 sfdir2 shortform (in-inode) version 2 directory.
983 This consists of a hdr containing a count of
984 active entries in the directory, an i8count
985 of entries with inumbers that don't fit in a
986 32-bit value, and the parent inode number,
987 followed by an array list of hdr.count
988 entries. Each such entry contains namelen, a
989 saved offset used when the directory is con‐
990 verted to a larger form, a name string, and
991 the inumber.
992 symlink symbolic link string value.
993 The following fields are in the a attribute fork union if it
994 exists:
995 bmbt bmap Btree root, as above.
996 bmx array of extent descriptors.
997 sfattr shortform (in-inode) attribute values. This
998 consists of a hdr containing a totsize (total
999 size in bytes) and a count of active entries,
1000 followed by an array list of hdr.count
1001 entries. Each such entry contains namelen,
1002 valuelen, root flag, name, and value.
1003 log Log blocks contain the journal entries for XFS. It's not
1005 useful to examine these with xfs_db, use xfs_logprint(8)
1006 instead.
1007 refcntbt There is one set of filesystem blocks forming the reference
1009 count Btree for each allocation group. The root block of this
1010 Btree is designated by the refcntroot field in the corre‐
1011 sponding AGF block. The blocks are linked to sibling left
1012 and right blocks at each level, as well as by pointers from
1013 parent to child blocks. Each block has the following fields:
1014 magic REFC block magic number, 0x52334643 ('R3FC').
1015 level level number of this block, 0 is a leaf.
1016 numrecs number of data entries in the block.
1017 leftsib left (logically lower) sibling block, 0 if
1018 none.
1019 rightsib right (logically higher) sibling block, 0 if
1020 none.
1021 recs [leaf blocks only] array of reference count
1022 records. Each record contains startblock,
1023 blockcount, and refcount.
1024 keys [non-leaf blocks only] array of key records.
1025 These are the first value of each block in
1026 the level below this one. Each record con‐
1027 tains startblock.
1028 ptrs [non-leaf blocks only] array of child block
1029 pointers. Each pointer is a block number
1030 within the allocation group to the next level
1031 in the Btree.
1032 rmapbt There is one set of filesystem blocks forming the reverse
1034 mapping Btree for each allocation group. The root block of
1035 this Btree is designated by the rmaproot field in the corre‐
1036 sponding AGF block. The blocks are linked to sibling left
1037 and right blocks at each level, as well as by pointers from
1038 parent to child blocks. Each block has the following fields:
1039 magic RMAP block magic number, 0x524d4233 ('RMB3').
1040 level level number of this block, 0 is a leaf.
1041 numrecs number of data entries in the block.
1042 leftsib left (logically lower) sibling block, 0 if
1043 none.
1044 rightsib right (logically higher) sibling block, 0 if
1045 none.
1046 recs [leaf blocks only] array of reference count
1047 records. Each record contains startblock,
1048 blockcount, owner, offset, attr_fork,
1049 bmbt_block, and unwritten.
1050 keys [non-leaf blocks only] array of double-key
1051 records. The first ("low") key contains the
1052 first value of each block in the level below
1053 this one. The second ("high") key contains
1054 the largest key that can be used to identify
1055 any record in the subtree. Each record con‐
1056 tains startblock, owner, offset, attr_fork,
1057 and bmbt_block.
1058 ptrs [non-leaf blocks only] array of child block
1059 pointers. Each pointer is a block number
1060 within the allocation group to the next level
1061 in the Btree.
1062 rtbitmap If the filesystem has a realtime subvolume, then the rbmino
1064 field in the superblock refers to a file that contains the
1065 realtime bitmap. Each bit in the bitmap file controls the
1066 allocation of a single realtime extent (set == free). The
1067 bitmap is processed in 32-bit words, the LSB of a word is
1068 used for the first extent controlled by that bitmap word. The
1069 atime field of the realtime bitmap inode contains a counter
1070 that is used to control where the next new realtime file will
1071 start.
1072 rtsummary If the filesystem has a realtime subvolume, then the rsumino
1074 field in the superblock refers to a file that contains the
1075 realtime summary data. The summary file contains a two-dimen‐
1076 sional array of 16-bit values. Each value counts the number
1077 of free extent runs (consecutive free realtime extents) of a
1078 given range of sizes that starts in a given bitmap block.
1079 The size ranges are binary buckets (low size in the bucket is
1080 a power of 2). There are as many size ranges as are neces‐
1081 sary given the size of the realtime subvolume. The first
1082 dimension is the size range, the second dimension is the
1083 starting bitmap block number (adjacent entries are for the
1084 same size, adjacent bitmap blocks).
1085 sb There is one sb (superblock) structure per allocation group.
1087 It is the first disk block in the allocation group. Only the
1088 first one (block 0 of the filesystem) is actually used; the
1089 other blocks are redundant information for xfs_repair(8) to
1090 use if the first superblock is damaged. Fields defined:
1091 magicnum superblock magic number, 0x58465342 ('XFSB').
1092 blocksize filesystem block size in bytes.
1093 dblocks number of filesystem blocks present in the
1094 data subvolume.
1095 rblocks number of filesystem blocks present in the
1096 realtime subvolume.
1097 rextents number of realtime extents that rblocks con‐
1098 tain.
1099 uuid unique identifier of the filesystem.
1100 logstart starting filesystem block number of the log
1101 (journal). If this value is 0 the log is
1102 "external".
1103 rootino root inode number.
1104 rbmino realtime bitmap inode number.
1105 rsumino realtime summary data inode number.
1106 rextsize realtime extent size in filesystem blocks.
1107 agblocks size of an allocation group in filesystem
1108 blocks.
1109 agcount number of allocation groups.
1110 rbmblocks number of realtime bitmap blocks.
1111 logblocks number of log blocks (filesystem blocks).
1112 versionnum filesystem version information. This value
1113 is currently 1, 2, 3, or 4 in the low 4 bits.
1114 If the low bits are 4 then the other bits
1115 have additional meanings. 1 is the original
1116 value. 2 means that attributes were used. 3
1117 means that version 2 inodes (large link
1118 counts) were used. 4 is the bitmask version
1119 of the version number. In this case, the
1120 other bits are used as flags (0x0010:
1121 attributes were used, 0x0020: version 2
1122 inodes were used, 0x0040: quotas were used,
1123 0x0080: inode cluster alignment is in force,
1124 0x0100: data stripe alignment is in force,
1125 0x0200: the shared_vn field is used, 0x1000:
1126 unwritten extent tracking is on, 0x2000: ver‐
1127 sion 2 directories are in use).
1128 sectsize sector size in bytes, currently always 512.
1129 This is the size of the superblock and the
1130 other header blocks.
1131 inodesize inode size in bytes.
1132 inopblock number of inodes per filesystem block.
1133 fname obsolete, filesystem name.
1134 fpack obsolete, filesystem pack name.
1135 blocklog log2 of blocksize.
1136 sectlog log2 of sectsize.
1137 inodelog log2 of inodesize.
1138 inopblog log2 of inopblock.
1139 agblklog log2 of agblocks (rounded up).
1140 rextslog log2 of rextents.
1141 inprogress mkfs.xfs(8) or xfs_copy(8) aborted before
1142 completing this filesystem.
1143 imax_pct maximum percentage of filesystem space used
1144 for inode blocks.
1145 icount number of allocated inodes.
1146 ifree number of allocated inodes that are not in
1147 use.
1148 fdblocks number of free data blocks.
1149 frextents number of free realtime extents.
1150 uquotino user quota inode number.
1151 pquotino project quota inode number; this is currently
1152 unused.
1153 qflags quota status flags (0x01: user quota account‐
1154 ing is on, 0x02: user quota limits are
1155 enforced, 0x04: quotacheck has been run on
1156 user quotas, 0x08: project quota accounting
1157 is on, 0x10: project quota limits are
1158 enforced, 0x20: quotacheck has been run on
1159 project quotas).
1160 flags random flags. 0x01: only read-only mounts are
1161 allowed.
1162 shared_vn shared version number (shared readonly
1163 filesystems).
1164 inoalignmt inode chunk alignment in filesystem blocks.
1165 unit stripe or RAID unit.
1166 width stripe or RAID width.
1167 dirblklog log2 of directory block size (filesystem
1168 blocks).
1169 symlink Symbolic link blocks are used only when the symbolic link
1171 value does not fit inside the inode. The block content is
1172 just the string value. Bytes past the logical end of the
1173 symbolic link value have arbitrary values.
1174 text User file blocks, and other blocks whose type is unknown,
1176 have this type for display purposes in xfs_db. The block
1177 data is displayed in two columns: Hexadecimal format and
1178 printable ASCII chars.
1179
1181 Many messages can come from the check (blockget) command. If the
1182 filesystem is completely corrupt, a core dump might be produced instead
1183 of the message
1184 device is not a valid filesystem
1185 If the filesystem is very large (has many files) then check might run
1187 out of memory. In this case the message
1188 out of memory
1189 is printed.
1190 The following is a description of the most likely problems and the
1192 associated messages. Most of the diagnostics produced are only mean‐
1193 ingful with an understanding of the structure of the filesystem.
1194 agf_freeblks n, counted m in ag a
1196 The freeblocks count in the allocation group header for alloca‐
1197 tion group a doesn't match the number of blocks counted free.
1198 agf_longest n, counted m in ag a
1200 The longest free extent in the allocation group header for allo‐
1201 cation group a doesn't match the longest free extent found in
1202 the allocation group.
1203 agi_count n, counted m in ag a
1205 The allocated inode count in the allocation group header for
1206 allocation group a doesn't match the number of inodes counted in
1207 the allocation group.
1208 agi_freecount n, counted m in ag a
1210 The free inode count in the allocation group header for alloca‐
1211 tion group a doesn't match the number of inodes counted free in
1212 the allocation group.
1213 block a/b expected inum 0 got i
1215 The block number is specified as a pair (allocation group num‐
1216 ber, block in the allocation group). The block is used multiple
1217 times (shared), between multiple inodes. This message usually
1218 follows a message of the next type.
1219 block a/b expected type unknown got y
1221 The block is used multiple times (shared).
1222 block a/b type unknown not expected
1224
1226 mkfs.xfs(8), xfs_admin(8), xfs_copy(8), xfs_logprint(8), xfs_metad‐
1227 ump(8), xfs_ncheck(8), xfs_repair(8), mount(8), chmod(2), mknod(2),
1228 stat(2), xfs(5).
1229 xfs_db(8)