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 agresv [agno]
122 Displays the length, free block count, per-AG reservation size,
123 and per-AG reservation usage for a given AG. If no argument is
124 given, display information for all AGs.
125 attr_remove [-r|-u|-s] [-n] name
127 Remove the specified extended attribute from the current file.
128 -r Sets the attribute in the root namespace. Only one
130 namespace option can be specified.
131 -u Sets the attribute in the user namespace. Only one
133 namespace option can be specified.
134 -s Sets the attribute in the secure namespace. Only one
136 namespace option can be specified.
137 -n Do not enable 'noattr2' mode on V4 filesystems.
139 attr_set [-r|-u|-s] [-n] [-R|-C] [-v namelen] name
141 Sets an extended attribute on the current file with the given
142 name.
143 -r Sets the attribute in the root namespace. Only one
145 namespace option can be specified.
146 -u Sets the attribute in the user namespace. Only one
148 namespace option can be specified.
149 -s Sets the attribute in the secure namespace. Only one
151 namespace option can be specified.
152 -n Do not enable 'noattr2' mode on V4 filesystems.
154 -R Replace the attribute. The command will fail if the
156 attribute does not already exist.
157 -C Create the attribute. The command will fail if the
159 attribute already exists.
160 -v Set the attribute value to a string of this length con‐
162 taining the letter 'v'.
163 b See the back command.
165 back Move to the previous location in the position ring.
167 blockfree
169 Free block usage information collected by the last execution of
170 the blockget command. This must be done before another blockget
171 command can be given, presumably with different arguments than
172 the previous one.
173 blockget [-npvs] [-b bno] ... [-i ino] ...
175 Get block usage and check filesystem consistency. The informa‐
176 tion is saved for use by a subsequent blockuse, ncheck, or
177 blocktrash command.
178 -b is used to specify filesystem block numbers about which
180 verbose information should be printed.
181 -i is used to specify inode numbers about which verbose
183 information should be printed.
184 -n is used to save pathnames for inodes visited, this is
186 used to support the xfs_ncheck(8) command. It also means
187 that pathnames will be printed for inodes that have prob‐
188 lems. This option uses a lot of memory so is not enabled
189 by default.
190 -p causes error messages to be prefixed with the filesystem
192 name being processed. This is useful if several copies of
193 xfs_db are run in parallel.
194 -s restricts output to severe errors only. This is useful if
196 the output is too long otherwise.
197 -v enables verbose output. Messages will be printed for
199 every block and inode processed.
200 blocktrash [-z] [-o offset] [-n count] [-x min] [-y max] [-s seed]
202 [-0|1|2|3] [-t type] ...
203 Trash randomly selected filesystem metadata blocks. Trashing
204 occurs to randomly selected bits in the chosen blocks. This
205 command is available only in debugging versions of xfs_db. It
206 is useful for testing xfs_repair(8).
207 -0 | -1 | -2 | -3
209 These are used to set the operating mode for blocktrash.
210 Only one can be used: -0 changed bits are cleared; -1
211 changed bits are set; -2 changed bits are inverted; -3
212 changed bits are randomized.
213 -n supplies the count of block-trashings to perform (default
215 1).
216 -o supplies the bit offset at which to start trashing the
218 block. If the value is preceded by a '+', the trashing
219 will start at a randomly chosen offset that is larger
220 than the value supplied. The default is to randomly
221 choose an offset anywhere in the block.
222 -s supplies a seed to the random processing.
224 -t gives a type of blocks to be selected for trashing. Mul‐
226 tiple -t options may be given. If no -t options are given
227 then all metadata types can be trashed.
228 -x sets the minimum size of bit range to be trashed. The
230 default value is 1.
231 -y sets the maximum size of bit range to be trashed. The
233 default value is 1024.
234 -z trashes the block at the top of the stack. It is not
236 necessary to run blockget if this option is supplied.
237 blockuse [-n] [-c count]
239 Print usage for current filesystem block(s). For each block,
240 the type and (if any) inode are printed.
241 -c specifies a count of blocks to process. The default value
243 is 1 (the current block only).
244 -n specifies that file names should be printed. The prior
246 blockget command must have also specified the -n option.
247 bmap [-a] [-d] [block [len]]
249 Show the block map for the current inode. The map display can
250 be restricted to an area of the file with the block and len
251 arguments. If block is given and len is omitted then 1 is
252 assumed for len.
253 The -a and -d options are used to select the attribute or data
255 area of the inode, if neither option is given then both areas
256 are shown.
257 btdump [-a] [-i]
259 If the cursor points to a btree node, dump the btree from that
260 block downward. If instead the cursor points to an inode, dump
261 the data fork block mapping btree if there is one. If the cur‐
262 sor points to a directory or extended attribute btree node, dump
263 that. By default, only records stored in the btree are dumped.
264 -a If the cursor points at an inode, dump the extended
266 attribute block mapping btree, if present.
267 -i Dump all keys and pointers in intermediate btree nodes,
269 and all records in leaf btree nodes.
270 btheight [-b blksz] [-n recs] [-w max|-w min] btree types...
272 For a given number of btree records and a btree type, report the
273 number of records and blocks for each level of the btree, and
274 the total number of blocks. The btree type must be given after
275 the options.
276 A raw btree geometry can be provided in the format
278 "record_bytes:key_bytes:ptr_bytes:header_type", where
279 header_type is one of "short", "long", "shortcrc", or "longcrc".
280 The supported btree types are: bnobt, cntbt, inobt, finobt,
282 bmapbt, refcountbt, and rmapbt.
283 Options are as follows:
285 -b is used to override the btree block size. The default is
287 the filesystem block size.
288 -n is used to specify the number of records to store. This
290 argument is required.
291 -w max
293 shows only the best case scenario, which is when the
294 btree blocks are maximally loaded.
295 -w min
297 shows only the worst case scenario, which is when the
298 btree blocks are half full.
299 check See the blockget command.
301 convert type number [type number] ... type
303 Convert from one address form to another. The known types, with
304 alternate names, are:
305 agblock or agbno (filesystem block within an allocation
306 group)
307 agino or aginode (inode number within an allocation group)
308 agnumber or agno (allocation group number)
309 bboff or daddroff (byte offset in a daddr)
310 blkoff or fsboff or agboff (byte offset in a agblock or
311 fsblock)
312 byte or fsbyte (byte address in filesystem)
313 daddr or bb (disk address, 512-byte blocks)
314 fsblock or fsb or fsbno (filesystem block, see the fsblock
315 command)
316 ino or inode (inode number)
317 inoidx or offset (index of inode in filesystem block)
318 inooff or inodeoff (byte offset in inode)
319 Only conversions that "make sense" are allowed. The compound
321 form (with more than three arguments) is useful for conversions
322 such as convert agno ag agbno agb fsblock.
323 crc [-i|-r|-v]
325 Invalidates, revalidates, or validates the CRC (checksum) field
326 of the current structure, if it has one. This command is avail‐
327 able only on CRC-enabled filesystems. With no argument, valida‐
328 tion is performed. Each command will display the resulting CRC
329 value and state.
330 -i Invalidate the structure's CRC value (incrementing it by
332 one), and write it to disk.
333 -r Recalculate the current structure's correct CRC value,
335 and write it to disk.
336 -v Validate and display the current value and state of the
338 structure's CRC.
339 daddr [d]
341 Set current address to the daddr (512 byte block) given by d.
342 If no value for d is given, the current address is printed,
343 expressed as a daddr. The type is set to data (uninterpreted).
344 dblock filoff
346 Set current address to the offset filoff (a filesystem block
347 number) in the data area of the current inode.
348 debug [flagbits]
350 Set debug option bits. These are used for debugging xfs_db. If
351 no value is given for flagbits, print the current debug option
352 bits. These are for the use of the implementor.
353 dquot [-g|-p|-u] id
355 Set current address to a group, project or user quota block for
356 the given ID. Defaults to user quota.
357 echo [arg] ...
359 Echo the arguments to the output.
360 f See the forward command.
362 forward
364 Move forward to the next entry in the position ring.
365 frag [-adflqRrv]
367 Get file fragmentation data. This prints information about frag‐
368 mentation of file data in the filesystem (as opposed to fragmen‐
369 tation of freespace, for which see the freesp command). Every
370 file in the filesystem is examined to see how far from ideal its
371 extent mappings are. A summary is printed giving the totals.
372 -v sets verbosity, every inode has information printed for
374 it. The remaining options select which inodes and
375 extents are examined. If no options are given then all
376 are assumed set, otherwise just those given are enabled.
377 -a enables processing of attribute data.
379 -d enables processing of directory data.
381 -f enables processing of regular file data.
383 -l enables processing of symbolic link data.
385 -q enables processing of quota file data.
387 -R enables processing of realtime control file data.
389 -r enables processing of realtime file data.
391 freesp [-bcds] [-A alignment] [-a ag] ... [-e i] [-h h1] ... [-m m]
393 Summarize free space for the filesystem. The free blocks are
394 examined and totalled, and displayed in the form of a histogram,
395 with a count of extents in each range of free extent sizes.
396 -A reports only free extents with starting blocks aligned to
398 alignment blocks.
399 -a adds ag to the list of allocation groups to be processed.
401 If no -a options are given then all allocation groups are
402 processed.
403 -b specifies that the histogram buckets are binary-sized,
405 with the starting sizes being the powers of 2.
406 -c specifies that freesp will search the by-size (cnt) space
408 Btree instead of the default by-block (bno) space Btree.
409 -d specifies that every free extent will be displayed.
411 -e specifies that the histogram buckets are equal-sized,
413 with the size specified as i.
414 -h specifies a starting block number for a histogram bucket
416 as h1. Multiple -h's are given to specify the complete
417 set of buckets.
418 -m specifies that the histogram starting block numbers are
420 powers of m. This is the general case of -b.
421 -s specifies that a final summary of total free extents,
423 free blocks, and the average free extent size is printed.
424 fsb See the fsblock command.
426 fsblock [fsb]
428 Set current address to the fsblock value given by fsb. If no
429 value for fsb is given the current address is printed, expressed
430 as an fsb. The type is set to data (uninterpreted). XFS
431 filesystem block numbers are computed ((agno << agshift) |
432 agblock) where agshift depends on the size of an allocation
433 group. Use the convert command to convert to and from this form.
434 Block numbers given for file blocks (for instance from the bmap
435 command) are in this form.
436 fsmap [ start ] [ end ]
438 Prints the mapping of disk blocks used by an XFS filesystem.
439 The map lists each extent used by files, allocation group meta‐
440 data, journalling logs, and static filesystem metadata, as well
441 as any regions that are unused. All blocks, offsets, and
442 lengths are specified in units of 512-byte blocks, no matter
443 what the filesystem's block size is. The optional start and end
444 arguments can be used to constrain the output to a particular
445 range of disk blocks.
446 fuzz [-c] [-d] field action
448 Write garbage into a specific structure field on disk. Expert
449 mode must be enabled to use this command. The operation happens
450 immediately; there is no buffering.
451 The fuzz command can take the following actions against a field:
453 zeroes
455 Clears all bits in the field.
456 ones
458 Sets all bits in the field.
459 firstbit
461 Flips the first bit in the field. For a scalar value,
462 this is the highest bit.
463 middlebit
465 Flips the middle bit in the field.
466 lastbit
468 Flips the last bit in the field. For a scalar value,
469 this is the lowest bit.
470 add Adds a small value to a scalar field.
472 sub Subtracts a small value from a scalar field.
474 random
476 Randomizes the contents of the field.
477 The following switches affect the write behavior:
479 -c Skip write verifiers and CRC recalculation; allows
481 invalid data to be written to disk.
482 -d Skip write verifiers but perform CRC recalculation;
484 allows invalid data to be written to disk to test detec‐
485 tion of invalid data.
486 hash string
488 Prints the hash value of string using the hash function of the
489 XFS directory and attribute implementation.
490 help [command]
492 Print help for one or all commands.
493 info Displays selected geometry information about the filesystem.
495 The output will have the same format that mkfs.xfs(8) prints
496 when creating a filesystem or xfs_info(8) prints when querying a
497 filesystem.
498 inode [inode#]
500 Set the current inode number. If no inode# is given, print the
501 current inode number.
502 label [label]
504 Set the filesystem label. The filesystem label can be used by
505 mount(8) instead of using a device special file. The maximum
506 length of an XFS label is 12 characters - use of a longer label
507 will result in truncation and a warning will be issued. If no
508 label is given, the current filesystem label is printed.
509 log [stop | start filename]
511 Start logging output to filename, stop logging, or print the
512 current logging status.
513 logformat [-c cycle] [-s sunit]
515 Reformats the log to the specified log cycle and log stripe
516 unit. This has the effect of clearing the log destructively.
517 If the log cycle is not specified, the log is reformatted to the
518 current cycle. If the log stripe unit is not specified, the
519 stripe unit from the filesystem superblock is used.
520 logres Print transaction reservation size information for each transac‐
522 tion type. This makes it easier to find discrepancies in the
523 reservation calculations between xfsprogs and the kernel, which
524 will help when diagnosing minimum log size calculation errors.
525 metadump [-egow] filename
527 Dumps metadata to a file. See xfs_metadump(8) for more informa‐
528 tion.
529 ncheck [-s] [-i ino] ...
531 Print name-inode pairs. A blockget -n command must be run first
532 to gather the information.
533 -i specifies an inode number to be printed. If no -i options
535 are given then all inodes are printed.
536 -s specifies that only setuid and setgid files are printed.
538 p See the print command.
540 pop Pop location from the stack.
542 print [field-expression] ...
544 Print field values. If no argument is given, print all fields
545 in the current structure.
546 push [command]
548 Push location to the stack. If command is supplied, set the cur‐
549 rent location to the results of command after pushing the old
550 location.
551 q See the quit command.
553 quit Exit xfs_db.
555 ring [index]
557 Show position ring (if no index argument is given), or move to a
558 specific entry in the position ring given by index.
559 sb [agno]
561 Set current address to SB header in allocation group agno. If
562 no agno is given, use the current allocation group number.
563 source source-file
565 Process commands from source-file. source commands can be
566 nested.
567 stack View the location stack.
569 type [type]
571 Set the current data type to type. If no argument is given,
572 show the current data type. The possible data types are: agf,
573 agfl, agi, attr, bmapbta, bmapbtd, bnobt, cntbt, data, dir,
574 dir2, dqblk, inobt, inode, log, refcntbt, rmapbt, rtbitmap,
575 rtsummary, sb, symlink and text. See the TYPES section below
576 for more information on these data types.
577 uuid [uuid | generate | rewrite | restore]
579 Set the filesystem universally unique identifier (UUID). The
580 filesystem UUID can be used by mount(8) instead of using a
581 device special file. The uuid can be set directly to the
582 desired UUID, or it can be automatically generated using the
583 generate option. These options will both write the UUID into
584 every copy of the superblock in the filesystem. On a CRC-
585 enabled filesystem, this will set an incompatible superblock
586 flag, and the filesystem will not be mountable with older ker‐
587 nels. This can be reverted with the restore option, which will
588 copy the original UUID back into place and clear the incompati‐
589 ble flag as needed. rewrite copies the current UUID from the
590 primary superblock to all secondary copies of the superblock.
591 If no argument is given, the current filesystem UUID is printed.
592 version [feature | versionnum features2]
594 Enable selected features for a filesystem (certain features can
595 be enabled on an unmounted filesystem, after mkfs.xfs(8) has
596 created the filesystem). Support for unwritten extents can be
597 enabled using the extflg option. Support for version 2 log for‐
598 mat can be enabled using the log2 option. Support for extended
599 attributes can be enabled using the attr1 or attr2 option. Once
600 enabled, extended attributes cannot be disabled, but the user
601 may toggle between attr1 and attr2 at will (older kernels may
602 not support the newer version).
603 If no argument is given, the current version and feature bits
605 are printed. With one argument, this command will write the
606 updated version number into every copy of the superblock in the
607 filesystem. If two arguments are given, they will be used as
608 numeric values for the versionnum and features2 bits respec‐
609 tively, and their string equivalent reported (but no modifica‐
610 tions are made).
611 write [-c|-d] [field value] ...
613 Write a value to disk. Specific fields can be set in structures
614 (struct mode), or a block can be set to data values (data mode),
615 or a block can be set to string values (string mode, for symlink
616 blocks). The operation happens immediately: there is no buffer‐
617 ing.
618 Struct mode is in effect when the current type is structural,
620 i.e. not data. For struct mode, the syntax is "write field
621 value".
622 Data mode is in effect when the current type is data. In this
624 case the contents of the block can be shifted or rotated left or
625 right, or filled with a sequence, a constant value, or a random
626 value. In this mode write with no arguments gives more informa‐
627 tion on the allowed commands.
628 -c Skip write verifiers and CRC recalculation; allows
630 invalid data to be written to disk.
631 -d Skip write verifiers but perform CRC recalculation. This
633 allows invalid data to be written to disk to test detec‐
634 tion of invalid data. (This is not possible for some
635 types.)
636
638 This section gives the fields in each structure type and their mean‐
639 ings. Note that some types of block cover multiple actual structures,
640 for instance directory blocks.
641 agf The AGF block is the header for block allocation information;
643 it is in the second 512-byte block of each allocation group.
644 The following fields are defined:
645 magicnum AGF block magic number, 0x58414746 ('XAGF').
646 versionnum version number, currently 1.
647 seqno sequence number starting from 0.
648 length size in filesystem blocks of the allocation
649 group. All allocation groups except the last
650 one of the filesystem have the superblock's
651 agblocks value here.
652 bnoroot block number of the root of the Btree holding
653 free space information sorted by block num‐
654 ber.
655 cntroot block number of the root of the Btree holding
656 free space information sorted by block count.
657 bnolevel number of levels in the by-block-number
658 Btree.
659 cntlevel number of levels in the by-block-count Btree.
660 flfirst index into the AGFL block of the first active
661 entry.
662 fllast index into the AGFL block of the last active
663 entry.
664 flcount count of active entries in the AGFL block.
665 freeblks count of blocks represented in the freespace
666 Btrees.
667 longest longest free space represented in the
668 freespace Btrees.
669 btreeblks number of blocks held in the AGF Btrees.
670 agfl The AGFL block contains block numbers for use of the block
672 allocator; it is in the fourth 512-byte block of each alloca‐
673 tion group. Each entry in the active list is a block number
674 within the allocation group that can be used for any purpose
675 if space runs low. The AGF block fields flfirst, fllast, and
676 flcount designate which entries are currently active. Entry
677 space is allocated in a circular manner within the AGFL
678 block. Fields defined:
679 bno array of all block numbers. Even those which
680 are not active are printed.
681 agi The AGI block is the header for inode allocation information;
683 it is in the third 512-byte block of each allocation group.
684 Fields defined:
685 magicnum AGI block magic number, 0x58414749 ('XAGI').
686 versionnum version number, currently 1.
687 seqno sequence number starting from 0.
688 length size in filesystem blocks of the allocation
689 group.
690 count count of inodes allocated.
691 root block number of the root of the Btree holding
692 inode allocation information.
693 level number of levels in the inode allocation
694 Btree.
695 freecount count of allocated inodes that are not in
696 use.
697 newino last inode number allocated.
698 dirino unused.
699 unlinked an array of inode numbers within the alloca‐
700 tion group. The entries in the AGI block are
701 the heads of lists which run through the
702 inode next_unlinked field. These inodes are
703 to be unlinked the next time the filesystem
704 is mounted.
705 attr An attribute fork is organized as a Btree with the actual
707 data embedded in the leaf blocks. The root of the Btree is
708 found in block 0 of the fork. The index (sort order) of the
709 Btree is the hash value of the attribute name. All the
710 blocks contain a blkinfo structure at the beginning, see type
711 dir for a description. Nonleaf blocks are identical in format
712 to those for version 1 and version 2 directories, see type
713 dir for a description. Leaf blocks can refer to "local" or
714 "remote" attribute values. Local values are stored directly
715 in the leaf block. Leaf blocks contain the following fields:
716 hdr header containing a blkinfo structure info
717 (magic number 0xfbee), a count of active
718 entries, usedbytes total bytes of names and
719 values, the firstused byte in the name area,
720 holes set if the block needs compaction, and
721 array freemap as for dir leaf blocks.
722 entries array of structures containing a hashval,
723 nameidx (index into the block of the name),
724 and flags incomplete, root, and local.
725 nvlist array of structures describing the attribute
726 names and values. Fields always present: val‐
727 uelen (length of value in bytes), namelen,
728 and name. Fields present for local values:
729 value (value string). Fields present for
730 remote values: valueblk (fork block number of
731 containing the value).
732 Remote values are stored in an independent block in the
734 attribute fork. Prior to v5, value blocks had no structure,
735 but in v5 they acquired a header structure with the following
736 fields:
737 magic attr3 remote block magic number, 0x5841524d
738 ('XARM').
739 offset Byte offset of this data block within the
740 overall attribute value.
741 bytes Number of bytes stored in this block.
742 crc Checksum of the attribute block contents.
743 uuid Filesystem UUID.
744 owner Inode that owns this attribute value.
745 bno Block offset of this block within the inode's
746 attribute fork.
747 lsn Log serial number of the last time this block
748 was logged.
749 data The attribute value data.
750 bmapbt Files with many extents in their data or attribute fork will
752 have the extents described by the contents of a Btree for
753 that fork, instead of being stored directly in the inode.
754 Each bmap Btree starts with a root block contained within the
755 inode. The other levels of the Btree are stored in filesys‐
756 tem blocks. The blocks are linked to sibling left and right
757 blocks at each level, as well as by pointers from parent to
758 child blocks. Each block contains the following fields:
759 magic bmap Btree block magic number, 0x424d4150
760 ('BMAP').
761 level level of this block above the leaf level.
762 numrecs number of records or keys in the block.
763 leftsib left (logically lower) sibling block, 0 if
764 none.
765 rightsib right (logically higher) sibling block, 0 if
766 none.
767 recs [leaf blocks only] array of extent records.
768 Each record contains startoff, startblock,
769 blockcount, and extentflag (1 if the extent
770 is unwritten).
771 keys [non-leaf blocks only] array of key records.
772 These are the first key value of each block
773 in the level below this one. Each record con‐
774 tains startoff.
775 ptrs [non-leaf blocks only] array of child block
776 pointers. Each pointer is a filesystem block
777 number to the next level in the Btree.
778 bnobt There is one set of filesystem blocks forming the by-block-
780 number allocation Btree for each allocation group. The root
781 block of this Btree is designated by the bnoroot field in the
782 corresponding AGF block. The blocks are linked to sibling
783 left and right blocks at each level, as well as by pointers
784 from parent to child blocks. Each block has the following
785 fields:
786 magic BNOBT block magic number, 0x41425442
787 ('ABTB').
788 level level number of this block, 0 is a leaf.
789 numrecs number of data entries in the block.
790 leftsib left (logically lower) sibling block, 0 if
791 none.
792 rightsib right (logically higher) sibling block, 0 if
793 none.
794 recs [leaf blocks only] array of freespace
795 records. Each record contains startblock and
796 blockcount.
797 keys [non-leaf blocks only] array of key records.
798 These are the first value of each block in
799 the level below this one. Each record con‐
800 tains startblock and blockcount.
801 ptrs [non-leaf blocks only] array of child block
802 pointers. Each pointer is a block number
803 within the allocation group to the next level
804 in the Btree.
805 cntbt There is one set of filesystem blocks forming the by-block-
807 count allocation Btree for each allocation group. The root
808 block of this Btree is designated by the cntroot field in the
809 corresponding AGF block. The blocks are linked to sibling
810 left and right blocks at each level, as well as by pointers
811 from parent to child blocks. Each block has the following
812 fields:
813 magic CNTBT block magic number, 0x41425443
814 ('ABTC').
815 level level number of this block, 0 is a leaf.
816 numrecs number of data entries in the block.
817 leftsib left (logically lower) sibling block, 0 if
818 none.
819 rightsib right (logically higher) sibling block, 0 if
820 none.
821 recs [leaf blocks only] array of freespace
822 records. Each record contains startblock and
823 blockcount.
824 keys [non-leaf blocks only] array of key records.
825 These are the first value of each block in
826 the level below this one. Each record con‐
827 tains blockcount and startblock.
828 ptrs [non-leaf blocks only] array of child block
829 pointers. Each pointer is a block number
830 within the allocation group to the next level
831 in the Btree.
832 data User file blocks, and other blocks whose type is unknown,
834 have this type for display purposes in xfs_db. The block
835 data is displayed in hexadecimal format.
836 dir A version 1 directory is organized as a Btree with the direc‐
838 tory data embedded in the leaf blocks. The root of the Btree
839 is found in block 0 of the file. The index (sort order) of
840 the Btree is the hash value of the entry name. All the blocks
841 contain a blkinfo structure at the beginning with the follow‐
842 ing fields:
843 forw next sibling block.
844 back previous sibling block.
845 magic magic number for this block type.
846 The non-leaf (node) blocks have the following fields:
847 hdr header containing a blkinfo structure info
848 (magic number 0xfebe), the count of active
849 entries, and the level of this block above
850 the leaves.
851 btree array of entries containing hashval and
852 before fields. The before value is a block
853 number within the directory file to the child
854 block, the hashval is the last hash value in
855 that block.
856 The leaf blocks have the following fields:
857 hdr header containing a blkinfo structure info
858 (magic number 0xfeeb), the count of active
859 entries, namebytes (total name string bytes),
860 holes flag (block needs compaction), and
861 freemap (array of base, size entries for free
862 regions).
863 entries array of structures containing hashval,
864 nameidx (byte index into the block of the
865 name string), and namelen.
866 namelist array of structures containing inumber and
867 name.
868 dir2 A version 2 directory has four kinds of blocks. Data blocks
870 start at offset 0 in the file. There are two kinds of data
871 blocks: single-block directories have the leaf information
872 embedded at the end of the block, data blocks in multi-block
873 directories do not. Node and leaf blocks start at offset
874 32GiB (with either a single leaf block or the root node
875 block). Freespace blocks start at offset 64GiB. The node
876 and leaf blocks form a Btree, with references to the data in
877 the data blocks. The freespace blocks form an index of long‐
878 est free spaces within the data blocks.
879 A single-block directory block contains the following fields:
881 bhdr header containing magic number 0x58443242
882 ('XD2B') and an array bestfree of the longest
883 3 free spaces in the block (offset, length).
884 bu array of union structures. Each element is
885 either an entry or a freespace. For entries,
886 there are the following fields: inumber,
887 namelen, name, and tag. For freespace, there
888 are the following fields: freetag (0xffff),
889 length, and tag. The tag value is the byte
890 offset in the block of the start of the entry
891 it is contained in.
892 bleaf array of leaf entries containing hashval and
893 address. The address is a 64-bit word offset
894 into the file.
895 btail tail structure containing the total count of
896 leaf entries and stale count of unused leaf
897 entries.
898 A data block contains the following fields:
899 dhdr header containing magic number 0x58443244
900 ('XD2D') and an array bestfree of the longest
901 3 free spaces in the block (offset, length).
902 du array of union structures as for bu.
903 Leaf blocks have two possible forms. If the Btree consists of
904 a single leaf then the freespace information is in the leaf
905 block, otherwise it is in separate blocks and the root of the
906 Btree is a node block. A leaf block contains the following
907 fields:
908 lhdr header containing a blkinfo structure info
909 (magic number 0xd2f1 for the single leaf
910 case, 0xd2ff for the true Btree case), the
911 total count of leaf entries, and stale count
912 of unused leaf entries.
913 lents leaf entries, as for bleaf.
914 lbests [single leaf only] array of values which rep‐
915 resent the longest freespace in each data
916 block in the directory.
917 ltail [single leaf only] tail structure containing
918 bestcount count of lbests.
919 A node block is identical to that for types attr and dir.
920 A freespace block contains the following fields:
922 fhdr header containing magic number 0x58443246
923 ('XD2F'), firstdb first data block number
924 covered by this freespace block, nvalid num‐
925 ber of valid entries, and nused number of
926 entries representing real data blocks.
927 fbests array of values as for lbests.
928 dqblk The quota information is stored in files referred to by the
930 superblock uquotino and pquotino fields. Each filesystem
931 block in a quota file contains a constant number of quota
932 entries. The quota entry size is currently 136 bytes, so with
933 a 4KiB filesystem block size there are 30 quota entries per
934 block. The dquot command is used to locate these entries in
935 the filesystem. The file entries are indexed by the user or
936 project identifier to determine the block and offset. Each
937 quota entry has the following fields:
938 magic magic number, 0x4451 ('DQ').
939 version version number, currently 1.
940 flags flags, values include 0x01 for user quota,
941 0x02 for project quota.
942 id user or project identifier.
943 blk_hardlimit absolute limit on blocks in use.
944 blk_softlimit preferred limit on blocks in use.
945 ino_hardlimit absolute limit on inodes in use.
946 ino_softlimit preferred limit on inodes in use.
947 bcount blocks actually in use.
948 icount inodes actually in use.
949 itimer time when service will be refused if soft
950 limit is violated for inodes.
951 btimer time when service will be refused if soft
952 limit is violated for blocks.
953 iwarns number of warnings issued about inode
954 limit violations.
955 bwarns number of warnings issued about block
956 limit violations.
957 rtb_hardlimit absolute limit on realtime blocks in use.
958 rtb_softlimit preferred limit on realtime blocks in use.
959 rtbcount realtime blocks actually in use.
960 rtbtimer time when service will be refused if soft
961 limit is violated for realtime blocks.
962 rtbwarns number of warnings issued about realtime
963 block limit violations.
964 inobt There is one set of filesystem blocks forming the inode allo‐
966 cation Btree for each allocation group. The root block of
967 this Btree is designated by the root field in the correspond‐
968 ing AGI block. The blocks are linked to sibling left and
969 right blocks at each level, as well as by pointers from par‐
970 ent to child blocks. Each block has the following fields:
971 magic INOBT block magic number, 0x49414254
972 ('IABT').
973 level level number of this block, 0 is a leaf.
974 numrecs number of data entries in the block.
975 leftsib left (logically lower) sibling block, 0 if
976 none.
977 rightsib right (logically higher) sibling block, 0 if
978 none.
979 recs [leaf blocks only] array of inode records.
980 Each record contains startino allocation-
981 group relative inode number, freecount count
982 of free inodes in this chunk, and free bit‐
983 map, LSB corresponds to inode 0.
984 keys [non-leaf blocks only] array of key records.
985 These are the first value of each block in
986 the level below this one. Each record con‐
987 tains startino.
988 ptrs [non-leaf blocks only] array of child block
989 pointers. Each pointer is a block number
990 within the allocation group to the next level
991 in the Btree.
992 inode Inodes are allocated in "chunks" of 64 inodes each. Usually a
994 chunk is multiple filesystem blocks, although there are cases
995 with large filesystem blocks where a chunk is less than one
996 block. The inode Btree (see inobt above) refers to the inode
997 numbers per allocation group. The inode numbers directly
998 reflect the location of the inode block on disk. Use the
999 inode command to point xfs_db to a specific inode. Each inode
1000 contains four regions: core, next_unlinked, u, and a. core
1001 contains the fixed information. next_unlinked is separated
1002 from the core due to journaling considerations, see type agi
1003 field unlinked. u is a union structure that is different in
1004 size and format depending on the type and representation of
1005 the file data ("data fork"). a is an optional union struc‐
1006 ture to describe attribute data, that is different in size,
1007 format, and location depending on the presence and represen‐
1008 tation of attribute data, and the size of the u data
1009 ("attribute fork"). xfs_db automatically selects the proper
1010 union members based on information in the inode.
1011 The following are fields in the inode core:
1013 magic inode magic number, 0x494e ('IN').
1014 mode mode and type of file, as described in
1015 chmod(2), mknod(2), and stat(2).
1016 version inode version, 1 or 2.
1017 format format of u union data (0: xfs_dev_t, 1:
1018 local file - in-inode directory or symlink,
1019 2: extent list, 3: Btree root, 4: unique id
1020 [unused]).
1021 nlinkv1 number of links to the file in a version 1
1022 inode.
1023 nlinkv2 number of links to the file in a version 2
1024 inode.
1025 projid_lo owner's project id (low word; version 2 inode
1026 only). projid_hi owner's project id (high
1027 word; version 2 inode only).
1028 uid owner's user id.
1029 gid owner's group id.
1030 atime time last accessed (seconds and nanoseconds).
1031 mtime time last modified.
1032 ctime time created or inode last modified.
1033 size number of bytes in the file.
1034 nblocks total number of blocks in the file including
1035 indirect and attribute.
1036 extsize basic/minimum extent size for the file.
1037 nextents number of extents in the data fork.
1038 naextents number of extents in the attribute fork.
1039 forkoff attribute fork offset in the inode, in 64-bit
1040 words from the start of u.
1041 aformat format of a data (1: local attribute data, 2:
1042 extent list, 3: Btree root).
1043 dmevmask DMAPI event mask.
1044 dmstate DMAPI state information.
1045 newrtbm file is the realtime bitmap and is "new" for‐
1046 mat.
1047 prealloc file has preallocated data space after EOF.
1048 realtime file data is in the realtime subvolume.
1049 gen inode generation number.
1050 The following fields are in the u data fork union:
1051 bmbt bmap Btree root. This looks like a bmapbtd
1052 block with redundant information removed.
1053 bmx array of extent descriptors.
1054 dev dev_t for the block or character device.
1055 sfdir shortform (in-inode) version 1 directory.
1056 This consists of a hdr containing the parent
1057 inode number and a count of active entries in
1058 the directory, followed by an array list of
1059 hdr.count entries. Each such entry contains
1060 inumber, namelen, and name string.
1061 sfdir2 shortform (in-inode) version 2 directory.
1062 This consists of a hdr containing a count of
1063 active entries in the directory, an i8count
1064 of entries with inumbers that don't fit in a
1065 32-bit value, and the parent inode number,
1066 followed by an array list of hdr.count
1067 entries. Each such entry contains namelen, a
1068 saved offset used when the directory is con‐
1069 verted to a larger form, a name string, and
1070 the inumber.
1071 symlink symbolic link string value.
1072 The following fields are in the a attribute fork union if it
1073 exists:
1074 bmbt bmap Btree root, as above.
1075 bmx array of extent descriptors.
1076 sfattr shortform (in-inode) attribute values. This
1077 consists of a hdr containing a totsize (total
1078 size in bytes) and a count of active entries,
1079 followed by an array list of hdr.count
1080 entries. Each such entry contains namelen,
1081 valuelen, root flag, name, and value.
1082 log Log blocks contain the journal entries for XFS. It's not
1084 useful to examine these with xfs_db, use xfs_logprint(8)
1085 instead.
1086 refcntbt There is one set of filesystem blocks forming the reference
1088 count Btree for each allocation group. The root block of this
1089 Btree is designated by the refcntroot field in the corre‐
1090 sponding AGF block. The blocks are linked to sibling left
1091 and right blocks at each level, as well as by pointers from
1092 parent to child blocks. Each block has the following fields:
1093 magic REFC block magic number, 0x52334643 ('R3FC').
1094 level level number of this block, 0 is a leaf.
1095 numrecs number of data entries in the block.
1096 leftsib left (logically lower) sibling block, 0 if
1097 none.
1098 rightsib right (logically higher) sibling block, 0 if
1099 none.
1100 recs [leaf blocks only] array of reference count
1101 records. Each record contains startblock,
1102 blockcount, and refcount.
1103 keys [non-leaf blocks only] array of key records.
1104 These are the first value of each block in
1105 the level below this one. Each record con‐
1106 tains startblock.
1107 ptrs [non-leaf blocks only] array of child block
1108 pointers. Each pointer is a block number
1109 within the allocation group to the next level
1110 in the Btree.
1111 rmapbt There is one set of filesystem blocks forming the reverse
1113 mapping Btree for each allocation group. The root block of
1114 this Btree is designated by the rmaproot field in the corre‐
1115 sponding AGF block. The blocks are linked to sibling left
1116 and right blocks at each level, as well as by pointers from
1117 parent to child blocks. Each block has the following fields:
1118 magic RMAP block magic number, 0x524d4233 ('RMB3').
1119 level level number of this block, 0 is a leaf.
1120 numrecs number of data entries in the block.
1121 leftsib left (logically lower) sibling block, 0 if
1122 none.
1123 rightsib right (logically higher) sibling block, 0 if
1124 none.
1125 recs [leaf blocks only] array of reference count
1126 records. Each record contains startblock,
1127 blockcount, owner, offset, attr_fork,
1128 bmbt_block, and unwritten.
1129 keys [non-leaf blocks only] array of double-key
1130 records. The first ("low") key contains the
1131 first value of each block in the level below
1132 this one. The second ("high") key contains
1133 the largest key that can be used to identify
1134 any record in the subtree. Each record con‐
1135 tains startblock, owner, offset, attr_fork,
1136 and bmbt_block.
1137 ptrs [non-leaf blocks only] array of child block
1138 pointers. Each pointer is a block number
1139 within the allocation group to the next level
1140 in the Btree.
1141 rtbitmap If the filesystem has a realtime subvolume, then the rbmino
1143 field in the superblock refers to a file that contains the
1144 realtime bitmap. Each bit in the bitmap file controls the
1145 allocation of a single realtime extent (set == free). The
1146 bitmap is processed in 32-bit words, the LSB of a word is
1147 used for the first extent controlled by that bitmap word. The
1148 atime field of the realtime bitmap inode contains a counter
1149 that is used to control where the next new realtime file will
1150 start.
1151 rtsummary If the filesystem has a realtime subvolume, then the rsumino
1153 field in the superblock refers to a file that contains the
1154 realtime summary data. The summary file contains a two-dimen‐
1155 sional array of 16-bit values. Each value counts the number
1156 of free extent runs (consecutive free realtime extents) of a
1157 given range of sizes that starts in a given bitmap block.
1158 The size ranges are binary buckets (low size in the bucket is
1159 a power of 2). There are as many size ranges as are neces‐
1160 sary given the size of the realtime subvolume. The first
1161 dimension is the size range, the second dimension is the
1162 starting bitmap block number (adjacent entries are for the
1163 same size, adjacent bitmap blocks).
1164 sb There is one sb (superblock) structure per allocation group.
1166 It is the first disk block in the allocation group. Only the
1167 first one (block 0 of the filesystem) is actually used; the
1168 other blocks are redundant information for xfs_repair(8) to
1169 use if the first superblock is damaged. Fields defined:
1170 magicnum superblock magic number, 0x58465342 ('XFSB').
1171 blocksize filesystem block size in bytes.
1172 dblocks number of filesystem blocks present in the
1173 data subvolume.
1174 rblocks number of filesystem blocks present in the
1175 realtime subvolume.
1176 rextents number of realtime extents that rblocks con‐
1177 tain.
1178 uuid unique identifier of the filesystem.
1179 logstart starting filesystem block number of the log
1180 (journal). If this value is 0 the log is
1181 "external".
1182 rootino root inode number.
1183 rbmino realtime bitmap inode number.
1184 rsumino realtime summary data inode number.
1185 rextsize realtime extent size in filesystem blocks.
1186 agblocks size of an allocation group in filesystem
1187 blocks.
1188 agcount number of allocation groups.
1189 rbmblocks number of realtime bitmap blocks.
1190 logblocks number of log blocks (filesystem blocks).
1191 versionnum filesystem version information. This value
1192 is currently 1, 2, 3, or 4 in the low 4 bits.
1193 If the low bits are 4 then the other bits
1194 have additional meanings. 1 is the original
1195 value. 2 means that attributes were used. 3
1196 means that version 2 inodes (large link
1197 counts) were used. 4 is the bitmask version
1198 of the version number. In this case, the
1199 other bits are used as flags (0x0010:
1200 attributes were used, 0x0020: version 2
1201 inodes were used, 0x0040: quotas were used,
1202 0x0080: inode cluster alignment is in force,
1203 0x0100: data stripe alignment is in force,
1204 0x0200: the shared_vn field is used, 0x1000:
1205 unwritten extent tracking is on, 0x2000: ver‐
1206 sion 2 directories are in use).
1207 sectsize sector size in bytes, currently always 512.
1208 This is the size of the superblock and the
1209 other header blocks.
1210 inodesize inode size in bytes.
1211 inopblock number of inodes per filesystem block.
1212 fname obsolete, filesystem name.
1213 fpack obsolete, filesystem pack name.
1214 blocklog log2 of blocksize.
1215 sectlog log2 of sectsize.
1216 inodelog log2 of inodesize.
1217 inopblog log2 of inopblock.
1218 agblklog log2 of agblocks (rounded up).
1219 rextslog log2 of rextents.
1220 inprogress mkfs.xfs(8) or xfs_copy(8) aborted before
1221 completing this filesystem.
1222 imax_pct maximum percentage of filesystem space used
1223 for inode blocks.
1224 icount number of allocated inodes.
1225 ifree number of allocated inodes that are not in
1226 use.
1227 fdblocks number of free data blocks.
1228 frextents number of free realtime extents.
1229 uquotino user quota inode number.
1230 pquotino project quota inode number; this is currently
1231 unused.
1232 qflags quota status flags (0x01: user quota account‐
1233 ing is on, 0x02: user quota limits are
1234 enforced, 0x04: quotacheck has been run on
1235 user quotas, 0x08: project quota accounting
1236 is on, 0x10: project quota limits are
1237 enforced, 0x20: quotacheck has been run on
1238 project quotas).
1239 flags random flags. 0x01: only read-only mounts are
1240 allowed.
1241 shared_vn shared version number (shared readonly
1242 filesystems).
1243 inoalignmt inode chunk alignment in filesystem blocks.
1244 unit stripe or RAID unit.
1245 width stripe or RAID width.
1246 dirblklog log2 of directory block size (filesystem
1247 blocks).
1248 symlink Symbolic link blocks are used only when the symbolic link
1250 value does not fit inside the inode. The block content is
1251 just the string value. Bytes past the logical end of the
1252 symbolic link value have arbitrary values.
1253 text User file blocks, and other blocks whose type is unknown,
1255 have this type for display purposes in xfs_db. The block
1256 data is displayed in two columns: Hexadecimal format and
1257 printable ASCII chars.
1258
1260 Many messages can come from the check (blockget) command. If the
1261 filesystem is completely corrupt, a core dump might be produced instead
1262 of the message
1263 device is not a valid filesystem
1264 If the filesystem is very large (has many files) then check might run
1266 out of memory. In this case the message
1267 out of memory
1268 is printed.
1269 The following is a description of the most likely problems and the
1271 associated messages. Most of the diagnostics produced are only mean‐
1272 ingful with an understanding of the structure of the filesystem.
1273 agf_freeblks n, counted m in ag a
1275 The freeblocks count in the allocation group header for alloca‐
1276 tion group a doesn't match the number of blocks counted free.
1277 agf_longest n, counted m in ag a
1279 The longest free extent in the allocation group header for allo‐
1280 cation group a doesn't match the longest free extent found in
1281 the allocation group.
1282 agi_count n, counted m in ag a
1284 The allocated inode count in the allocation group header for
1285 allocation group a doesn't match the number of inodes counted in
1286 the allocation group.
1287 agi_freecount n, counted m in ag a
1289 The free inode count in the allocation group header for alloca‐
1290 tion group a doesn't match the number of inodes counted free in
1291 the allocation group.
1292 block a/b expected inum 0 got i
1294 The block number is specified as a pair (allocation group num‐
1295 ber, block in the allocation group). The block is used multiple
1296 times (shared), between multiple inodes. This message usually
1297 follows a message of the next type.
1298 block a/b expected type unknown got y
1300 The block is used multiple times (shared).
1301 block a/b type unknown not expected
1303
1305 mkfs.xfs(8), xfs_admin(8), xfs_copy(8), xfs_logprint(8), xfs_metad‐
1306 ump(8), xfs_ncheck(8), xfs_repair(8), mount(8), chmod(2), mknod(2),
1307 stat(2), xfs(5).
1308 xfs_db(8)