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) is to be
52 used.
53 -x Specifies expert mode. This enables the write and blocktrash
55 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 check See the blockget command.
216 convert type number [type number] ... type
218 Convert from one address form to another. The known types, with
219 alternate names, are:
220 agblock or agbno (filesystem block within an allocation
221 group)
222 agino or aginode (inode number within an allocation group)
223 agnumber or agno (allocation group number)
224 bboff or daddroff (byte offset in a daddr)
225 blkoff or fsboff or agboff (byte offset in a agblock or
226 fsblock)
227 byte or fsbyte (byte address in filesystem)
228 daddr or bb (disk address, 512-byte blocks)
229 fsblock or fsb or fsbno (filesystem block, see the fsblock
230 command)
231 ino or inode (inode number)
232 inoidx or offset (index of inode in filesystem block)
233 inooff or inodeoff (byte offset in inode)
234 Only conversions that "make sense" are allowed. The compound
236 form (with more than three arguments) is useful for conversions
237 such as convert agno ag agbno agb fsblock.
238 daddr [d]
240 Set current address to the daddr (512 byte block) given by d.
241 If no value for d is given, the current address is printed,
242 expressed as a daddr. The type is set to data (uninterpreted).
243 dblock filoff
245 Set current address to the offset filoff (a filesystem block
246 number) in the data area of the current inode.
247 debug [flagbits]
249 Set debug option bits. These are used for debugging xfs_db. If
250 no value is given for flagbits, print the current debug option
251 bits. These are for the use of the implementor.
252 dquot [-g|-p|-u] id
254 Set current address to a group, project or user quota block for
255 the given ID. Defaults to user quota.
256 echo [arg] ...
258 Echo the arguments to the output.
259 f See the forward command.
261 forward
263 Move forward to the next entry in the position ring.
264 frag [-adflqRrv]
266 Get file fragmentation data. This prints information about frag‐
267 mentation of file data in the filesystem (as opposed to fragmen‐
268 tation of freespace, for which see the freesp command). Every
269 file in the filesystem is examined to see how far from ideal its
270 extent mappings are. A summary is printed giving the totals.
271 -v sets verbosity, every inode has information printed for
273 it. The remaining options select which inodes and
274 extents are examined. If no options are given then all
275 are assumed set, otherwise just those given are enabled.
276 -a enables processing of attribute data.
278 -d enables processing of directory data.
280 -f enables processing of regular file data.
282 -l enables processing of symbolic link data.
284 -q enables processing of quota file data.
286 -R enables processing of realtime control file data.
288 -r enables processing of realtime file data.
290 freesp [-bcds] [-a ag] ... [-e i] [-h h1] ... [-m m]
292 Summarize free space for the filesystem. The free blocks are
293 examined and totalled, and displayed in the form of a histogram,
294 with a count of extents in each range of free extent sizes.
295 -a adds ag to the list of allocation groups to be processed.
297 If no -a options are given then all allocation groups are
298 processed.
299 -b specifies that the histogram buckets are binary-sized,
301 with the starting sizes being the powers of 2.
302 -c specifies that freesp will search the by-size (cnt) space
304 Btree instead of the default by-block (bno) space Btree.
305 -d specifies that every free extent will be displayed.
307 -e specifies that the histogram buckets are equal-sized,
309 with the size specified as i.
310 -h specifies a starting block number for a histogram bucket
312 as h1. Multiple -h's are given to specify the complete
313 set of buckets.
314 -m specifies that the histogram starting block numbers are
316 powers of m. This is the general case of -b.
317 -s specifies that a final summary of total free extents,
319 free blocks, and the average free extent size is printed.
320 fsb See the fsblock command.
322 fsblock [fsb]
324 Set current address to the fsblock value given by fsb. If no
325 value for fsb is given the current address is printed, expressed
326 as an fsb. The type is set to data (uninterpreted). XFS
327 filesystem block numbers are computed ((agno << agshift) |
328 agblock) where agshift depends on the size of an allocation
329 group. Use the convert command to convert to and from this form.
330 Block numbers given for file blocks (for instance from the bmap
331 command) are in this form.
332 hash string
334 Prints the hash value of string using the hash function of the
335 XFS directory and attribute implementation.
336 help [command]
338 Print help for one or all commands.
339 inode [inode#]
341 Set the current inode number. If no inode# is given, print the
342 current inode number.
343 label [label]
345 Set the filesystem label. The filesystem label can be used by
346 mount(8) instead of using a device special file. The maximum
347 length of an XFS label is 12 characters - use of a longer label
348 will result in truncation and a warning will be issued. If no
349 label is given, the current filesystem label is printed.
350 log [stop | start filename]
352 Start logging output to filename, stop logging, or print the
353 current logging status.
354 metadump [-egow] filename
356 Dumps metadata to a file. See xfs_metadump(8) for more informa‐
357 tion.
358 ncheck [-s] [-i ino] ...
360 Print name-inode pairs. A blockget -n command must be run first
361 to gather the information.
362 -i specifies an inode number to be printed. If no -i options
364 are given then all inodes are printed.
365 -s specifies that only setuid and setgid files are printed.
367 p See the print command.
369 pop Pop location from the stack.
371 print [field-expression] ...
373 Print field values. If no argument is given, print all fields
374 in the current structure.
375 push [command]
377 Push location to the stack. If command is supplied, set the cur‐
378 rent location to the results of command after pushing the old
379 location.
380 q See the quit command.
382 quit Exit xfs_db.
384 ring [index]
386 Show position ring (if no index argument is given), or move to a
387 specific entry in the position ring given by index.
388 sb [agno]
390 Set current address to SB header in allocation group agno. If
391 no agno is given, use the current allocation group number.
392 source source-file
394 Process commands from source-file. source commands can be
395 nested.
396 stack View the location stack.
398 type [type]
400 Set the current data type to type. If no argument is given,
401 show the current data type. The possible data types are: agf,
402 agfl, agi, attr, bmapbta, bmapbtd, bnobt, cntbt, data, dir,
403 dir2, dqblk, inobt, inode, log, rtbitmap, rtsummary, sb, symlink
404 and text. See the TYPES section below for more information on
405 these data types.
406 uuid [uuid | generate | rewrite | restore]
408 Set the filesystem universally unique identifier (UUID). The
409 filesystem UUID can be used by mount(8) instead of using a
410 device special file. The uuid can be set directly to the
411 desired UUID, or it can be automatically generated using the
412 generate option. These options will both write the UUID into
413 every copy of the superblock in the filesystem. On a CRC-
414 enabled filesystem, this will set an incompatible superblock
415 flag, and the filesystem will not be mountable with older ker‐
416 nels. This can be reverted with the restore option, which will
417 copy the original UUID back into place and clear the incompati‐
418 ble flag as needed. rewrite copies the current UUID from the
419 primary superblock to all secondary copies of the superblock.
420 If no argument is given, the current filesystem UUID is printed.
421 version [feature | versionnum features2]
423 Enable selected features for a filesystem (certain features can
424 be enabled on an unmounted filesystem, after mkfs.xfs(8) has
425 created the filesystem). Support for unwritten extents can be
426 enabled using the extflg option. Support for version 2 log for‐
427 mat can be enabled using the log2 option. Support for extended
428 attributes can be enabled using the attr1 or attr2 option. Once
429 enabled, extended attributes cannot be disabled, but the user
430 may toggle between attr1 and attr2 at will (older kernels may
431 not support the newer version).
432 If no argument is given, the current version and feature bits
434 are printed. With one argument, this command will write the
435 updated version number into every copy of the superblock in the
436 filesystem. If two arguments are given, they will be used as
437 numeric values for the versionnum and features2 bits respec‐
438 tively, and their string equivalent reported (but no modifica‐
439 tions are made).
440 write [-c] [field value] ...
442 Write a value to disk. Specific fields can be set in structures
443 (struct mode), or a block can be set to data values (data mode),
444 or a block can be set to string values (string mode, for symlink
445 blocks). The operation happens immediately: there is no buffer‐
446 ing.
447 Struct mode is in effect when the current type is structural,
449 i.e. not data. For struct mode, the syntax is "write field
450 value".
451 Data mode is in effect when the current type is data. In this
453 case the contents of the block can be shifted or rotated left or
454 right, or filled with a sequence, a constant value, or a random
455 value. In this mode write with no arguments gives more informa‐
456 tion on the allowed commands.
457 -c Skip write verifiers and CRC recalculation; allows
459 invalid data to be written to disk.
460
462 This section gives the fields in each structure type and their mean‐
463 ings. Note that some types of block cover multiple actual structures,
464 for instance directory blocks.
465 agf The AGF block is the header for block allocation information;
467 it is in the second 512-byte block of each allocation group.
468 The following fields are defined:
469 magicnum AGF block magic number, 0x58414746 ('XAGF').
470 versionnum version number, currently 1.
471 seqno sequence number starting from 0.
472 length size in filesystem blocks of the allocation
473 group. All allocation groups except the last
474 one of the filesystem have the superblock's
475 agblocks value here.
476 bnoroot block number of the root of the Btree holding
477 free space information sorted by block num‐
478 ber.
479 cntroot block number of the root of the Btree holding
480 free space information sorted by block count.
481 bnolevel number of levels in the by-block-number
482 Btree.
483 cntlevel number of levels in the by-block-count Btree.
484 flfirst index into the AGFL block of the first active
485 entry.
486 fllast index into the AGFL block of the last active
487 entry.
488 flcount count of active entries in the AGFL block.
489 freeblks count of blocks represented in the freespace
490 Btrees.
491 longest longest free space represented in the
492 freespace Btrees.
493 btreeblks number of blocks held in the AGF Btrees.
494 agfl The AGFL block contains block numbers for use of the block
496 allocator; it is in the fourth 512-byte block of each alloca‐
497 tion group. Each entry in the active list is a block number
498 within the allocation group that can be used for any purpose
499 if space runs low. The AGF block fields flfirst, fllast, and
500 flcount designate which entries are currently active. Entry
501 space is allocated in a circular manner within the AGFL
502 block. Fields defined:
503 bno array of all block numbers. Even those which
504 are not active are printed.
505 agi The AGI block is the header for inode allocation information;
507 it is in the third 512-byte block of each allocation group.
508 Fields defined:
509 magicnum AGI block magic number, 0x58414749 ('XAGI').
510 versionnum version number, currently 1.
511 seqno sequence number starting from 0.
512 length size in filesystem blocks of the allocation
513 group.
514 count count of inodes allocated.
515 root block number of the root of the Btree holding
516 inode allocation information.
517 level number of levels in the inode allocation
518 Btree.
519 freecount count of allocated inodes that are not in
520 use.
521 newino last inode number allocated.
522 dirino unused.
523 unlinked an array of inode numbers within the alloca‐
524 tion group. The entries in the AGI block are
525 the heads of lists which run through the
526 inode next_unlinked field. These inodes are
527 to be unlinked the next time the filesystem
528 is mounted.
529 attr An attribute fork is organized as a Btree with the actual
531 data embedded in the leaf blocks. The root of the Btree is
532 found in block 0 of the fork. The index (sort order) of the
533 Btree is the hash value of the attribute name. All the
534 blocks contain a blkinfo structure at the beginning, see type
535 dir for a description. Nonleaf blocks are identical in format
536 to those for version 1 and version 2 directories, see type
537 dir for a description. Leaf blocks can refer to "local" or
538 "remote" attribute values. Local values are stored directly
539 in the leaf block. Remote values are stored in an indepen‐
540 dent block in the attribute fork (with no structure). Leaf
541 blocks contain the following fields:
542 hdr header containing a blkinfo structure info
543 (magic number 0xfbee), a count of active
544 entries, usedbytes total bytes of names and
545 values, the firstused byte in the name area,
546 holes set if the block needs compaction, and
547 array freemap as for dir leaf blocks.
548 entries array of structures containing a hashval,
549 nameidx (index into the block of the name),
550 and flags incomplete, root, and local.
551 nvlist array of structures describing the attribute
552 names and values. Fields always present: val‐
553 uelen (length of value in bytes), namelen,
554 and name. Fields present for local values:
555 value (value string). Fields present for
556 remote values: valueblk (fork block number of
557 containing the value).
558 bmapbt Files with many extents in their data or attribute fork will
560 have the extents described by the contents of a Btree for
561 that fork, instead of being stored directly in the inode.
562 Each bmap Btree starts with a root block contained within the
563 inode. The other levels of the Btree are stored in filesys‐
564 tem blocks. The blocks are linked to sibling left and right
565 blocks at each level, as well as by pointers from parent to
566 child blocks. Each block contains the following fields:
567 magic bmap Btree block magic number, 0x424d4150
568 ('BMAP').
569 level level of this block above the leaf level.
570 numrecs number of records or keys in the block.
571 leftsib left (logically lower) sibling block, 0 if
572 none.
573 rightsib right (logically higher) sibling block, 0 if
574 none.
575 recs [leaf blocks only] array of extent records.
576 Each record contains startoff, startblock,
577 blockcount, and extentflag (1 if the extent
578 is unwritten).
579 keys [non-leaf blocks only] array of key records.
580 These are the first key value of each block
581 in the level below this one. Each record con‐
582 tains startoff.
583 ptrs [non-leaf blocks only] array of child block
584 pointers. Each pointer is a filesystem block
585 number to the next level in the Btree.
586 bnobt There is one set of filesystem blocks forming the by-block-
588 number allocation Btree for each allocation group. The root
589 block of this Btree is designated by the bnoroot field in the
590 corresponding AGF block. The blocks are linked to sibling
591 left and right blocks at each level, as well as by pointers
592 from parent to child blocks. Each block has the following
593 fields:
594 magic BNOBT block magic number, 0x41425442
595 ('ABTB').
596 level level number of this block, 0 is a leaf.
597 numrecs number of data entries in the block.
598 leftsib left (logically lower) sibling block, 0 if
599 none.
600 rightsib right (logically higher) sibling block, 0 if
601 none.
602 recs [leaf blocks only] array of freespace
603 records. Each record contains startblock and
604 blockcount.
605 keys [non-leaf blocks only] array of key records.
606 These are the first value of each block in
607 the level below this one. Each record con‐
608 tains startblock and blockcount.
609 ptrs [non-leaf blocks only] array of child block
610 pointers. Each pointer is a block number
611 within the allocation group to the next level
612 in the Btree.
613 cntbt There is one set of filesystem blocks forming the by-block-
615 count allocation Btree for each allocation group. The root
616 block of this Btree is designated by the cntroot field in the
617 corresponding AGF block. The blocks are linked to sibling
618 left and right blocks at each level, as well as by pointers
619 from parent to child blocks. Each block has the following
620 fields:
621 magic CNTBT block magic number, 0x41425443
622 ('ABTC').
623 level level number of this block, 0 is a leaf.
624 numrecs number of data entries in the block.
625 leftsib left (logically lower) sibling block, 0 if
626 none.
627 rightsib right (logically higher) sibling block, 0 if
628 none.
629 recs [leaf blocks only] array of freespace
630 records. Each record contains startblock and
631 blockcount.
632 keys [non-leaf blocks only] array of key records.
633 These are the first value of each block in
634 the level below this one. Each record con‐
635 tains blockcount and startblock.
636 ptrs [non-leaf blocks only] array of child block
637 pointers. Each pointer is a block number
638 within the allocation group to the next level
639 in the Btree.
640 data User file blocks, and other blocks whose type is unknown,
642 have this type for display purposes in xfs_db. The block
643 data is displayed in hexadecimal format.
644 dir A version 1 directory is organized as a Btree with the direc‐
646 tory data embedded in the leaf blocks. The root of the Btree
647 is found in block 0 of the file. The index (sort order) of
648 the Btree is the hash value of the entry name. All the blocks
649 contain a blkinfo structure at the beginning with the follow‐
650 ing fields:
651 forw next sibling block.
652 back previous sibling block.
653 magic magic number for this block type.
654 The non-leaf (node) blocks have the following fields:
655 hdr header containing a blkinfo structure info
656 (magic number 0xfebe), the count of active
657 entries, and the level of this block above
658 the leaves.
659 btree array of entries containing hashval and
660 before fields. The before value is a block
661 number within the directory file to the child
662 block, the hashval is the last hash value in
663 that block.
664 The leaf blocks have the following fields:
665 hdr header containing a blkinfo structure info
666 (magic number 0xfeeb), the count of active
667 entries, namebytes (total name string bytes),
668 holes flag (block needs compaction), and
669 freemap (array of base, size entries for free
670 regions).
671 entries array of structures containing hashval,
672 nameidx (byte index into the block of the
673 name string), and namelen.
674 namelist array of structures containing inumber and
675 name.
676 dir2 A version 2 directory has four kinds of blocks. Data blocks
678 start at offset 0 in the file. There are two kinds of data
679 blocks: single-block directories have the leaf information
680 embedded at the end of the block, data blocks in multi-block
681 directories do not. Node and leaf blocks start at offset
682 32GiB (with either a single leaf block or the root node
683 block). Freespace blocks start at offset 64GiB. The node
684 and leaf blocks form a Btree, with references to the data in
685 the data blocks. The freespace blocks form an index of long‐
686 est free spaces within the data blocks.
687 A single-block directory block contains the following fields:
689 bhdr header containing magic number 0x58443242
690 ('XD2B') and an array bestfree of the longest
691 3 free spaces in the block (offset, length).
692 bu array of union structures. Each element is
693 either an entry or a freespace. For entries,
694 there are the following fields: inumber,
695 namelen, name, and tag. For freespace, there
696 are the following fields: freetag (0xffff),
697 length, and tag. The tag value is the byte
698 offset in the block of the start of the entry
699 it is contained in.
700 bleaf array of leaf entries containing hashval and
701 address. The address is a 64-bit word offset
702 into the file.
703 btail tail structure containing the total count of
704 leaf entries and stale count of unused leaf
705 entries.
706 A data block contains the following fields:
707 dhdr header containing magic number 0x58443244
708 ('XD2D') and an array bestfree of the longest
709 3 free spaces in the block (offset, length).
710 du array of union structures as for bu.
711 Leaf blocks have two possible forms. If the Btree consists of
712 a single leaf then the freespace information is in the leaf
713 block, otherwise it is in separate blocks and the root of the
714 Btree is a node block. A leaf block contains the following
715 fields:
716 lhdr header containing a blkinfo structure info
717 (magic number 0xd2f1 for the single leaf
718 case, 0xd2ff for the true Btree case), the
719 total count of leaf entries, and stale count
720 of unused leaf entries.
721 lents leaf entries, as for bleaf.
722 lbests [single leaf only] array of values which rep‐
723 resent the longest freespace in each data
724 block in the directory.
725 ltail [single leaf only] tail structure containing
726 bestcount count of lbests.
727 A node block is identical to that for types attr and dir.
728 A freespace block contains the following fields:
730 fhdr header containing magic number 0x58443246
731 ('XD2F'), firstdb first data block number
732 covered by this freespace block, nvalid num‐
733 ber of valid entries, and nused number of
734 entries representing real data blocks.
735 fbests array of values as for lbests.
736 dqblk The quota information is stored in files referred to by the
738 superblock uquotino and pquotino fields. Each filesystem
739 block in a quota file contains a constant number of quota
740 entries. The quota entry size is currently 136 bytes, so with
741 a 4KiB filesystem block size there are 30 quota entries per
742 block. The dquot command is used to locate these entries in
743 the filesystem. The file entries are indexed by the user or
744 project identifier to determine the block and offset. Each
745 quota entry has the following fields:
746 magic magic number, 0x4451 ('DQ').
747 version version number, currently 1.
748 flags flags, values include 0x01 for user quota,
749 0x02 for project quota.
750 id user or project identifier.
751 blk_hardlimit absolute limit on blocks in use.
752 blk_softlimit preferred limit on blocks in use.
753 ino_hardlimit absolute limit on inodes in use.
754 ino_softlimit preferred limit on inodes in use.
755 bcount blocks actually in use.
756 icount inodes actually in use.
757 itimer time when service will be refused if soft
758 limit is violated for inodes.
759 btimer time when service will be refused if soft
760 limit is violated for blocks.
761 iwarns number of warnings issued about inode
762 limit violations.
763 bwarns number of warnings issued about block
764 limit violations.
765 rtb_hardlimit absolute limit on realtime blocks in use.
766 rtb_softlimit preferred limit on realtime blocks in use.
767 rtbcount realtime blocks actually in use.
768 rtbtimer time when service will be refused if soft
769 limit is violated for realtime blocks.
770 rtbwarns number of warnings issued about realtime
771 block limit violations.
772 inobt There is one set of filesystem blocks forming the inode allo‐
774 cation Btree for each allocation group. The root block of
775 this Btree is designated by the root field in the correspond‐
776 ing AGI block. The blocks are linked to sibling left and
777 right blocks at each level, as well as by pointers from par‐
778 ent to child blocks. Each block has the following fields:
779 magic INOBT block magic number, 0x49414254
780 ('IABT').
781 level level number of this block, 0 is a leaf.
782 numrecs number of data entries in the block.
783 leftsib left (logically lower) sibling block, 0 if
784 none.
785 rightsib right (logically higher) sibling block, 0 if
786 none.
787 recs [leaf blocks only] array of inode records.
788 Each record contains startino allocation-
789 group relative inode number, freecount count
790 of free inodes in this chunk, and free bit‐
791 map, LSB corresponds to inode 0.
792 keys [non-leaf blocks only] array of key records.
793 These are the first value of each block in
794 the level below this one. Each record con‐
795 tains startino.
796 ptrs [non-leaf blocks only] array of child block
797 pointers. Each pointer is a block number
798 within the allocation group to the next level
799 in the Btree.
800 inode Inodes are allocated in "chunks" of 64 inodes each. Usually a
802 chunk is multiple filesystem blocks, although there are cases
803 with large filesystem blocks where a chunk is less than one
804 block. The inode Btree (see inobt above) refers to the inode
805 numbers per allocation group. The inode numbers directly
806 reflect the location of the inode block on disk. Use the
807 inode command to point xfs_db to a specific inode. Each inode
808 contains four regions: core, next_unlinked, u, and a. core
809 contains the fixed information. next_unlinked is separated
810 from the core due to journaling considerations, see type agi
811 field unlinked. u is a union structure that is different in
812 size and format depending on the type and representation of
813 the file data ("data fork"). a is an optional union struc‐
814 ture to describe attribute data, that is different in size,
815 format, and location depending on the presence and represen‐
816 tation of attribute data, and the size of the u data
817 ("attribute fork"). xfs_db automatically selects the proper
818 union members based on information in the inode.
819 The following are fields in the inode core:
821 magic inode magic number, 0x494e ('IN').
822 mode mode and type of file, as described in
823 chmod(2), mknod(2), and stat(2).
824 version inode version, 1 or 2.
825 format format of u union data (0: xfs_dev_t, 1:
826 local file - in-inode directory or symlink,
827 2: extent list, 3: Btree root, 4: unique id
828 [unused]).
829 nlinkv1 number of links to the file in a version 1
830 inode.
831 nlinkv2 number of links to the file in a version 2
832 inode.
833 projid_lo owner's project id (low word; version 2 inode
834 only). projid_hi owner's project id (high
835 word; version 2 inode only).
836 uid owner's user id.
837 gid owner's group id.
838 atime time last accessed (seconds and nanoseconds).
839 mtime time last modified.
840 ctime time created or inode last modified.
841 size number of bytes in the file.
842 nblocks total number of blocks in the file including
843 indirect and attribute.
844 extsize basic/minimum extent size for the file.
845 nextents number of extents in the data fork.
846 naextents number of extents in the attribute fork.
847 forkoff attribute fork offset in the inode, in 64-bit
848 words from the start of u.
849 aformat format of a data (1: local attribute data, 2:
850 extent list, 3: Btree root).
851 dmevmask DMAPI event mask.
852 dmstate DMAPI state information.
853 newrtbm file is the realtime bitmap and is "new" for‐
854 mat.
855 prealloc file has preallocated data space after EOF.
856 realtime file data is in the realtime subvolume.
857 gen inode generation number.
858 The following fields are in the u data fork union:
859 bmbt bmap Btree root. This looks like a bmapbtd
860 block with redundant information removed.
861 bmx array of extent descriptors.
862 dev dev_t for the block or character device.
863 sfdir shortform (in-inode) version 1 directory.
864 This consists of a hdr containing the parent
865 inode number and a count of active entries in
866 the directory, followed by an array list of
867 hdr.count entries. Each such entry contains
868 inumber, namelen, and name string.
869 sfdir2 shortform (in-inode) version 2 directory.
870 This consists of a hdr containing a count of
871 active entries in the directory, an i8count
872 of entries with inumbers that don't fit in a
873 32-bit value, and the parent inode number,
874 followed by an array list of hdr.count
875 entries. Each such entry contains namelen, a
876 saved offset used when the directory is con‐
877 verted to a larger form, a name string, and
878 the inumber.
879 symlink symbolic link string value.
880 The following fields are in the a attribute fork union if it
881 exists:
882 bmbt bmap Btree root, as above.
883 bmx array of extent descriptors.
884 sfattr shortform (in-inode) attribute values. This
885 consists of a hdr containing a totsize (total
886 size in bytes) and a count of active entries,
887 followed by an array list of hdr.count
888 entries. Each such entry contains namelen,
889 valuelen, root flag, name, and value.
890 log Log blocks contain the journal entries for XFS. It's not
892 useful to examine these with xfs_db, use xfs_logprint(8)
893 instead.
894 rtbitmap If the filesystem has a realtime subvolume, then the rbmino
896 field in the superblock refers to a file that contains the
897 realtime bitmap. Each bit in the bitmap file controls the
898 allocation of a single realtime extent (set == free). The
899 bitmap is processed in 32-bit words, the LSB of a word is
900 used for the first extent controlled by that bitmap word. The
901 atime field of the realtime bitmap inode contains a counter
902 that is used to control where the next new realtime file will
903 start.
904 rtsummary If the filesystem has a realtime subvolume, then the rsumino
906 field in the superblock refers to a file that contains the
907 realtime summary data. The summary file contains a two-dimen‐
908 sional array of 16-bit values. Each value counts the number
909 of free extent runs (consecutive free realtime extents) of a
910 given range of sizes that starts in a given bitmap block.
911 The size ranges are binary buckets (low size in the bucket is
912 a power of 2). There are as many size ranges as are neces‐
913 sary given the size of the realtime subvolume. The first
914 dimension is the size range, the second dimension is the
915 starting bitmap block number (adjacent entries are for the
916 same size, adjacent bitmap blocks).
917 sb There is one sb (superblock) structure per allocation group.
919 It is the first disk block in the allocation group. Only the
920 first one (block 0 of the filesystem) is actually used; the
921 other blocks are redundant information for xfs_repair(8) to
922 use if the first superblock is damaged. Fields defined:
923 magicnum superblock magic number, 0x58465342 ('XFSB').
924 blocksize filesystem block size in bytes.
925 dblocks number of filesystem blocks present in the
926 data subvolume.
927 rblocks number of filesystem blocks present in the
928 realtime subvolume.
929 rextents number of realtime extents that rblocks con‐
930 tain.
931 uuid unique identifier of the filesystem.
932 logstart starting filesystem block number of the log
933 (journal). If this value is 0 the log is
934 "external".
935 rootino root inode number.
936 rbmino realtime bitmap inode number.
937 rsumino realtime summary data inode number.
938 rextsize realtime extent size in filesystem blocks.
939 agblocks size of an allocation group in filesystem
940 blocks.
941 agcount number of allocation groups.
942 rbmblocks number of realtime bitmap blocks.
943 logblocks number of log blocks (filesystem blocks).
944 versionnum filesystem version information. This value
945 is currently 1, 2, 3, or 4 in the low 4 bits.
946 If the low bits are 4 then the other bits
947 have additional meanings. 1 is the original
948 value. 2 means that attributes were used. 3
949 means that version 2 inodes (large link
950 counts) were used. 4 is the bitmask version
951 of the version number. In this case, the
952 other bits are used as flags (0x0010:
953 attributes were used, 0x0020: version 2
954 inodes were used, 0x0040: quotas were used,
955 0x0080: inode cluster alignment is in force,
956 0x0100: data stripe alignment is in force,
957 0x0200: the shared_vn field is used, 0x1000:
958 unwritten extent tracking is on, 0x2000: ver‐
959 sion 2 directories are in use).
960 sectsize sector size in bytes, currently always 512.
961 This is the size of the superblock and the
962 other header blocks.
963 inodesize inode size in bytes.
964 inopblock number of inodes per filesystem block.
965 fname obsolete, filesystem name.
966 fpack obsolete, filesystem pack name.
967 blocklog log2 of blocksize.
968 sectlog log2 of sectsize.
969 inodelog log2 of inodesize.
970 inopblog log2 of inopblock.
971 agblklog log2 of agblocks (rounded up).
972 rextslog log2 of rextents.
973 inprogress mkfs.xfs(8) or xfs_copy(8) aborted before
974 completing this filesystem.
975 imax_pct maximum percentage of filesystem space used
976 for inode blocks.
977 icount number of allocated inodes.
978 ifree number of allocated inodes that are not in
979 use.
980 fdblocks number of free data blocks.
981 frextents number of free realtime extents.
982 uquotino user quota inode number.
983 pquotino project quota inode number; this is currently
984 unused.
985 qflags quota status flags (0x01: user quota account‐
986 ing is on, 0x02: user quota limits are
987 enforced, 0x04: quotacheck has been run on
988 user quotas, 0x08: project quota accounting
989 is on, 0x10: project quota limits are
990 enforced, 0x20: quotacheck has been run on
991 project quotas).
992 flags random flags. 0x01: only read-only mounts are
993 allowed.
994 shared_vn shared version number (shared readonly
995 filesystems).
996 inoalignmt inode chunk alignment in filesystem blocks.
997 unit stripe or RAID unit.
998 width stripe or RAID width.
999 dirblklog log2 of directory block size (filesystem
1000 blocks).
1001 symlink Symbolic link blocks are used only when the symbolic link
1003 value does not fit inside the inode. The block content is
1004 just the string value. Bytes past the logical end of the
1005 symbolic link value have arbitrary values.
1006 text User file blocks, and other blocks whose type is unknown,
1008 have this type for display purposes in xfs_db. The block
1009 data is displayed in two columns: Hexadecimal format and
1010 printable ASCII chars.
1011
1013 Many messages can come from the check (blockget) command. If the
1014 filesystem is completely corrupt, a core dump might be produced instead
1015 of the message
1016 device is not a valid filesystem
1017 If the filesystem is very large (has many files) then check might run
1019 out of memory. In this case the message
1020 out of memory
1021 is printed.
1022 The following is a description of the most likely problems and the
1024 associated messages. Most of the diagnostics produced are only mean‐
1025 ingful with an understanding of the structure of the filesystem.
1026 agf_freeblks n, counted m in ag a
1028 The freeblocks count in the allocation group header for alloca‐
1029 tion group a doesn't match the number of blocks counted free.
1030 agf_longest n, counted m in ag a
1032 The longest free extent in the allocation group header for allo‐
1033 cation group a doesn't match the longest free extent found in
1034 the allocation group.
1035 agi_count n, counted m in ag a
1037 The allocated inode count in the allocation group header for
1038 allocation group a doesn't match the number of inodes counted in
1039 the allocation group.
1040 agi_freecount n, counted m in ag a
1042 The free inode count in the allocation group header for alloca‐
1043 tion group a doesn't match the number of inodes counted free in
1044 the allocation group.
1045 block a/b expected inum 0 got i
1047 The block number is specified as a pair (allocation group num‐
1048 ber, block in the allocation group). The block is used multiple
1049 times (shared), between multiple inodes. This message usually
1050 follows a message of the next type.
1051 block a/b expected type unknown got y
1053 The block is used multiple times (shared).
1054 block a/b type unknown not expected
1056
1058 mkfs.xfs(8), xfs_admin(8), xfs_copy(8), xfs_logprint(8), xfs_metad‐
1059 ump(8), xfs_ncheck(8), xfs_repair(8), mount(8), chmod(2), mknod(2),
1060 stat(2), xfs(5).
1061 xfs_db(8)