Provided by: xfsprogs_4.3.0+nmu1ubuntu1_amd64 bug

NAME

       xfs_db - debug an XFS filesystem

SYNOPSIS

       xfs_db [ -c cmd ] ... [ -i|r|x|F ] [ -f ] [ -l logdev ] [ -p progname ] device
       xfs_db -V

DESCRIPTION

       xfs_db  is used to examine an XFS filesystem. Under rare circumstances it can also be used
       to modify an XFS filesystem, but that task is normally left to xfs_repair(8) or to scripts
       such as xfs_admin(8) that run xfs_db.

OPTIONS

       -c cmd xfs_db  commands  may  be  run  interactively  (the default) or as arguments on the
              command line. Multiple -c arguments may be given.  The  commands  are  run  in  the
              sequence given, then the program exits.

       -f     Specifies  that the filesystem image to be processed is stored in a regular file at
              device (see the mkfs.xfs(8) -d file option).  This might happen if an image copy of
              a filesystem has been made into an ordinary file with xfs_copy(8).

       -F     Specifies  that  we  want  to continue even if the superblock magic is not correct.
              For use in xfs_metadump.

       -i     Allows execution on a mounted filesystem, provided it is mounted read-only.  Useful
              for shell scripts which must only operate on filesystems in a guaranteed consistent
              state (either  unmounted  or  mounted  read-only).  These  semantics  are  slightly
              different to that of the -r option.

       -l logdev
              Specifies  the  device  where the filesystems external log resides.  Only for those
              filesystems which use an external log. See the mkfs.xfs(8) -l option, and refer  to
              xfs(5) for a detailed description of the XFS log.

       -p progname
              Set  the  program name to progname for prompts and some error messages, the default
              value is xfs_db.

       -r     Open device or filename read-only. This option is required  if  the  filesystem  is
              mounted.   It  is  only  necessary to omit this flag if a command that changes data
              (write, blocktrash) is to be used.

       -x     Specifies expert mode.  This enables the write and blocktrash commands.

       -V     Prints the version number and exits.

CONCEPTS

       xfs_db commands can be broken up into two classes. Most commands are  for  the  navigation
       and  display  of  data  structures in the filesystem.  Other commands are for scanning the
       filesystem in some way.

       Commands which are used to navigate the filesystem structure take arguments which  reflect
       the  names of filesystem structure fields.  There can be multiple field names separated by
       dots when the underlying structures are nested, as in C.  The field names can  be  indexed
       (as  an  array  index)  if  the  underlying  field  is an array.  The array indices can be
       specified as a range, two numbers separated by a dash.

       xfs_db maintains a current address in the filesystem.  The granularity of the address is a
       filesystem  structure.   This can be a filesystem block, an inode or quota (smaller than a
       filesystem block), or a directory block (could be larger than a filesystem block).   There
       are a variety of commands to set the current address.  Associated with the current address
       is the current data type, which is the structural  type  of  this  data.   Commands  which
       follow  the  structure  of  the  filesystem  always  set  the type as well as the address.
       Commands which examine pieces of an individual file (inode) need the current inode  to  be
       set, this is done with the inode command.

       The  current  address/type  information  is  actually  maintained  in  a stack that can be
       explicitly manipulated with the push, pop, and  stack  commands.   This  allows  for  easy
       examination  of  a  nested filesystem structure.  Also, the last several locations visited
       are stored in a ring buffer which can be manipulated with  the  forward,  back,  and  ring
       commands.

       XFS  filesystems are divided into a small number of allocation groups.  xfs_db maintains a
       notion of the current allocation group which is manipulated by some commands. The  initial
       allocation group is 0.

COMMANDS

       Many  commands  have  extensive  online help. Use the help command for more details on any
       command.

       a      See the addr command.

       ablock filoff
              Set current address to the  offset  filoff  (a  filesystem  block  number)  in  the
              attribute area of the current inode.

       addr [field-expression]
              Set current address to the value of the field-expression.  This is used to "follow"
              a reference in one structure to the object being referred to.  If  no  argument  is
              given, the current address is printed.

       agf [agno]
              Set  current address to the AGF block for allocation group agno.  If no argument is
              given, use the current allocation group.

       agfl [agno]
              Set current address to the AGFL block for allocation group agno.  If no argument is
              given, use the current allocation group.

       agi [agno]
              Set  current address to the AGI block for allocation group agno.  If no argument is
              given, use the current allocation group.

       b      See the back command.

       back   Move to the previous location in the position ring.

       blockfree
              Free block usage information collected  by  the  last  execution  of  the  blockget
              command. This must be done before another blockget command can be given, presumably
              with different arguments than the previous one.

       blockget [-npvs] [-b bno] ... [-i ino] ...
              Get block usage and check filesystem consistency.  The information is saved for use
              by a subsequent blockuse, ncheck, or blocktrash command.

                 -b  is  used to specify filesystem block numbers about which verbose information
                     should be printed.

                 -i  is used to specify inode numbers about which verbose information  should  be
                     printed.

                 -n  is  used  to  save pathnames for inodes visited, this is used to support the
                     xfs_ncheck(8) command. It also means that  pathnames  will  be  printed  for
                     inodes  that  have  problems.  This  option  uses  a lot of memory so is not
                     enabled by default.

                 -p  causes error  messages  to  be  prefixed  with  the  filesystem  name  being
                     processed. This is useful if several copies of xfs_db are run in parallel.

                 -s  restricts  output to severe errors only. This is useful if the output is too
                     long otherwise.

                 -v  enables verbose output. Messages will be printed for every block  and  inode
                     processed.

       blocktrash  [-z]  [-o  offset] [-n count] [-x min] [-y max] [-s seed] [-0|1|2|3] [-t type]
       ...
              Trash randomly selected filesystem metadata blocks.  Trashing  occurs  to  randomly
              selected  bits  in  the chosen blocks.  This command is available only in debugging
              versions of xfs_db.  It is useful for testing xfs_repair(8).

                 -0 | -1 | -2 | -3
                     These are used to set the operating mode for blocktrash.  Only  one  can  be
                     used:  -0 changed bits are cleared; -1 changed bits are set; -2 changed bits
                     are inverted; -3 changed bits are randomized.

                 -n  supplies the count of block-trashings to perform (default 1).

                 -o  supplies the bit offset at which to start trashing the block.  If the  value
                     is  preceded  by  a '+', the trashing will start at a randomly chosen offset
                     that is larger than the value supplied.  The default is to  randomly  choose
                     an offset anywhere in the block.

                 -s  supplies a seed to the random processing.

                 -t  gives  a type of blocks to be selected for trashing. Multiple -t options may
                     be given. If no -t options are given then all metadata types can be trashed.

                 -x  sets the minimum size of bit range to be trashed. The default value is 1.

                 -y  sets the maximum size of bit range to be trashed. The default value is 1024.

                 -z  trashes the block at the top of the stack.   It  is  not  necessary  to  run
                     blockget if this option is supplied.

       blockuse [-n] [-c count]
              Print usage for current filesystem block(s).  For each block, the type and (if any)
              inode are printed.

                 -c  specifies a count of blocks to process. The default value is 1 (the  current
                     block only).

                 -n  specifies that file names should be printed. The prior blockget command must
                     have also specified the -n option.

       bmap [-a] [-d] [block [len]]
              Show the block map for the current inode.  The map display can be restricted to  an
              area  of  the  file  with the block and len arguments. If block is given and len is
              omitted then 1 is assumed for len.

              The -a and -d options are used to select the attribute or data area of  the  inode,
              if neither option is given then both areas are shown.

       check  See the blockget command.

       convert type number [type number] ... type
              Convert  from  one address form to another.  The known types, with alternate names,
              are:
                 agblock or agbno (filesystem block within an allocation group)
                 agino or aginode (inode number within an allocation group)
                 agnumber or agno (allocation group number)
                 bboff or daddroff (byte offset in a daddr)
                 blkoff or fsboff or agboff (byte offset in a agblock or fsblock)
                 byte or fsbyte (byte address in filesystem)
                 daddr or bb (disk address, 512-byte blocks)
                 fsblock or fsb or fsbno (filesystem block, see the fsblock command)
                 ino or inode (inode number)
                 inoidx or offset (index of inode in filesystem block)
                 inooff or inodeoff (byte offset in inode)

              Only conversions that "make sense" are allowed.  The compound form (with more  than
              three  arguments)  is  useful  for  conversions  such  as convert agno ag agbno agb
              fsblock.

       daddr [d]
              Set current address to the daddr (512 byte block) given by d.  If no value for d is
              given,  the  current  address is printed, expressed as a daddr.  The type is set to
              data (uninterpreted).

       dblock filoff
              Set current address to the offset filoff (a filesystem block number)  in  the  data
              area of the current inode.

       debug [flagbits]
              Set  debug  option bits. These are used for debugging xfs_db.  If no value is given
              for flagbits, print the current debug option bits. These are for  the  use  of  the
              implementor.

       dquot [projectid_or_userid]
              Set current address to a project or user quota block.

       echo [arg] ...
              Echo the arguments to the output.

       f      See the forward command.

       forward
              Move forward to the next entry in the position ring.

       frag [-adflqRrv]
              Get  file  fragmentation  data. This prints information about fragmentation of file
              data in the filesystem (as opposed to fragmentation of freespace, for which see the
              freesp command). Every file in the filesystem is examined to see how far from ideal
              its extent mappings are. A summary is printed giving the totals.

                 -v  sets verbosity, every inode has information printed for it.   The  remaining
                     options  select  which  inodes  and extents are examined.  If no options are
                     given then all are assumed set, otherwise just those given are enabled.

                 -a  enables processing of attribute data.

                 -d  enables processing of directory data.

                 -f  enables processing of regular file data.

                 -l  enables processing of symbolic link data.

                 -q  enables processing of quota file data.

                 -R  enables processing of realtime control file data.

                 -r  enables processing of realtime file data.

       freesp [-bcds] [-a ag] ... [-e i] [-h h1] ... [-m m]
              Summarize free space for the filesystem. The free blocks are examined and totalled,
              and  displayed in the form of a histogram, with a count of extents in each range of
              free extent sizes.

                 -a  adds ag to the list of allocation groups to be processed. If no  -a  options
                     are given then all allocation groups are processed.

                 -b  specifies  that  the  histogram  buckets are binary-sized, with the starting
                     sizes being the powers of 2.

                 -c  specifies that freesp will search the by-size (cnt) space Btree  instead  of
                     the default by-block (bno) space Btree.

                 -d  specifies that every free extent will be displayed.

                 -e  specifies  that  the  histogram  buckets  are  equal-sized,  with  the  size
                     specified as i.

                 -h  specifies a starting block number for a histogram bucket  as  h1.   Multiple
                     -h's are given to specify the complete set of buckets.

                 -m  specifies  that  the histogram starting block numbers are powers of m.  This
                     is the general case of -b.

                 -s  specifies that a final summary of total free extents, free blocks,  and  the
                     average free extent size is printed.

       fsb    See the fsblock command.

       fsblock [fsb]
              Set  current  address  to  the  fsblock value given by fsb.  If no value for fsb is
              given the current address is printed, expressed as an fsb.  The type is set to data
              (uninterpreted).  XFS  filesystem  block  numbers are computed ((agno << agshift) |
              agblock) where agshift depends on the size of an allocation group. Use the  convert
              command  to convert to and from this form. Block numbers given for file blocks (for
              instance from the bmap command) are in this form.

       hash string
              Prints the hash value of string using the hash function of the  XFS  directory  and
              attribute implementation.

       help [command]
              Print help for one or all commands.

       inode [inode#]
              Set  the  current  inode  number.  If  no  inode# is given, print the current inode
              number.

       label [label]
              Set the filesystem label. The filesystem label can be used by mount(8)  instead  of
              using a device special file.  The maximum length of an XFS label is 12 characters -
              use of a longer label will result in truncation and a warning will be issued. If no
              label is given, the current filesystem label is printed.

       log [stop | start filename]
              Start  logging  output  to  filename,  stop  logging,  or print the current logging
              status.

       metadump [-egow] filename
              Dumps metadata to a file. See xfs_metadump(8) for more information.

       ncheck [-s] [-i ino] ...
              Print name-inode pairs. A blockget -n command must  be  run  first  to  gather  the
              information.

                 -i  specifies an inode number to be printed. If no -i options are given then all
                     inodes are printed.

                 -s  specifies that only setuid and setgid files are printed.

       p      See the print command.

       pop    Pop location from the stack.

       print [field-expression] ...
              Print field values.  If no argument is given,  print  all  fields  in  the  current
              structure.

       push [command]
              Push location to the stack. If command is supplied, set the current location to the
              results of command after pushing the old location.

       q      See the quit command.

       quit   Exit xfs_db.

       ring [index]
              Show position ring (if no index argument is given), or move to a specific entry  in
              the position ring given by index.

       sb [agno]
              Set  current  address  to SB header in allocation group agno.  If no agno is given,
              use the current allocation group number.

       source source-file
              Process commands from source-file.  source commands can be nested.

       stack  View the location stack.

       type [type]
              Set the current data type to type.  If no argument is given, show the current  data
              type.   The possible data types are: agf, agfl, agi, attr, bmapbta, bmapbtd, bnobt,
              cntbt, data, dir, dir2, dqblk, inobt, inode, log, rtbitmap, rtsummary, sb,  symlink
              and text.  See the TYPES section below for more information on these data types.

       uuid [uuid | generate | rewrite | restore]
              Set  the  filesystem universally unique identifier (UUID).  The filesystem UUID can
              be used by mount(8) instead of using a device special file.  The uuid  can  be  set
              directly  to  the  desired  UUID,  or  it  can be automatically generated using the
              generate option. These options will both write the UUID  into  every  copy  of  the
              superblock  in  the  filesystem.   On  a  CRC-enabled  filesystem, this will set an
              incompatible superblock flag, and the filesystem will not be mountable  with  older
              kernels.   This  can  be  reverted  with  the  restore  option, which will copy the
              original UUID back into place and clear the incompatible flag as  needed.   rewrite
              copies  the current UUID from the primary superblock to all secondary copies of the
              superblock.  If no argument is given, the current filesystem UUID is printed.

       version [feature | versionnum features2]
              Enable selected features for a filesystem (certain features can be  enabled  on  an
              unmounted  filesystem,  after mkfs.xfs(8) has created the filesystem).  Support for
              unwritten extents can be enabled using the extflg option. Support for version 2 log
              format can be enabled using the log2 option. Support for extended attributes can be
              enabled using the attr1 or attr2 option. Once enabled, extended  attributes  cannot
              be disabled, but the user may toggle between attr1 and attr2 at will (older kernels
              may not support the newer version).

              If no argument is given, the current version and feature bits  are  printed.   With
              one argument, this command will write the updated version number into every copy of
              the superblock in the filesystem.  If two arguments are given, they will be used as
              numeric values for the versionnum and features2 bits respectively, and their string
              equivalent reported (but no modifications are made).

       write [-c] [field value] ...
              Write a value to disk.  Specific fields can be set in structures (struct mode),  or
              a  block  can  be  set  to data values (data mode), or a block can be set to string
              values (string mode, for symlink blocks).  The operation happens immediately: there
              is no buffering.

              Struct  mode  is  in effect when the current type is structural, i.e. not data. For
              struct mode, the syntax is "write field value".

              Data mode is in effect when the current type is data. In this case the contents  of
              the  block  can  be  shifted or rotated left or right, or filled with a sequence, a
              constant value, or a random value. In this mode write with no arguments gives  more
              information on the allowed commands.

                 -c  Skip  write  verifiers  and  CRC  recalculation;  allows  invalid data to be
                     written to disk.

TYPES

       This section gives the fields in each structure type and their meanings.  Note  that  some
       types of block cover multiple actual structures, for instance directory blocks.

       agf       The  AGF  block  is  the  header  for block allocation information; it is in the
                 second 512-byte block of  each  allocation  group.   The  following  fields  are
                 defined:
                     magicnum    AGF block magic number, 0x58414746 ('XAGF').
                     versionnum  version number, currently 1.
                     seqno       sequence number starting from 0.
                     length      size   in   filesystem  blocks  of  the  allocation  group.  All
                                 allocation groups except the last one of the filesystem have the
                                 superblock's agblocks value here.
                     bnoroot     block  number  of  the  root  of  the  Btree  holding free space
                                 information sorted by block number.
                     cntroot     block number of  the  root  of  the  Btree  holding  free  space
                                 information sorted by block count.
                     bnolevel    number of levels in the by-block-number Btree.
                     cntlevel    number of levels in the by-block-count Btree.
                     flfirst     index into the AGFL block of the first active entry.
                     fllast      index into the AGFL block of the last active entry.
                     flcount     count of active entries in the AGFL block.
                     freeblks    count of blocks represented in the freespace Btrees.
                     longest     longest free space represented in the freespace Btrees.
                     btreeblks   number of blocks held in the AGF Btrees.

       agfl      The  AGFL  block contains block numbers for use of the block allocator; it is in
                 the fourth 512-byte block of each allocation group.  Each entry  in  the  active
                 list  is  a  block  number  within the allocation group that can be used for any
                 purpose if space runs low.  The AGF block fields flfirst,  fllast,  and  flcount
                 designate  which  entries  are  currently active.  Entry space is allocated in a
                 circular manner within the AGFL block.  Fields defined:
                     bno         array of all block numbers. Even those which are not active  are
                                 printed.

       agi       The AGI block is the header for inode allocation information; it is in the third
                 512-byte block of each allocation group.  Fields defined:
                     magicnum    AGI block magic number, 0x58414749 ('XAGI').
                     versionnum  version number, currently 1.
                     seqno       sequence number starting from 0.
                     length      size in filesystem blocks of the allocation group.
                     count       count of inodes allocated.
                     root        block number of the root of the Btree holding  inode  allocation
                                 information.
                     level       number of levels in the inode allocation Btree.
                     freecount   count of allocated inodes that are not in use.
                     newino      last inode number allocated.
                     dirino      unused.
                     unlinked    an  array  of  inode  numbers  within  the allocation group. The
                                 entries in the AGI block  are  the  heads  of  lists  which  run
                                 through  the  inode  next_unlinked field. These inodes are to be
                                 unlinked the next time the filesystem is mounted.

       attr      An attribute fork is organized as a Btree with the actual data embedded  in  the
                 leaf  blocks.  The root of the Btree is found in block 0 of the fork.  The index
                 (sort order) of the Btree is the hash value of  the  attribute  name.   All  the
                 blocks  contain  a  blkinfo  structure  at  the  beginning,  see  type dir for a
                 description. Nonleaf blocks are identical in format to those for version  1  and
                 version  2 directories, see type dir for a description. Leaf blocks can refer to
                 "local" or "remote" attribute values. Local values are stored  directly  in  the
                 leaf  block.   Remote values are stored in an independent block in the attribute
                 fork (with no structure). Leaf blocks contain the following fields:
                     hdr         header  containing  a  blkinfo  structure  info  (magic   number
                                 0xfbee),  a  count  of  active entries, usedbytes total bytes of
                                 names and values, the firstused byte in the name area, holes set
                                 if the block needs compaction, and array freemap as for dir leaf
                                 blocks.
                     entries     array of structures containing a hashval,  nameidx  (index  into
                                 the block of the name), and flags incomplete, root, and local.
                     nvlist      array  of  structures describing the attribute names and values.
                                 Fields always present: valuelen  (length  of  value  in  bytes),
                                 namelen,  and  name.   Fields  present  for  local values: value
                                 (value string). Fields present for remote values: valueblk (fork
                                 block number of containing the value).

       bmapbt    Files  with  many  extents in their data or attribute fork will have the extents
                 described by the contents of a Btree for that  fork,  instead  of  being  stored
                 directly  in  the  inode.   Each  bmap  Btree starts with a root block contained
                 within the inode.  The other levels  of  the  Btree  are  stored  in  filesystem
                 blocks.   The  blocks are linked to sibling left and right blocks at each level,
                 as well as by pointers from parent to child blocks.   Each  block  contains  the
                 following fields:
                     magic       bmap Btree block magic number, 0x424d4150 ('BMAP').
                     level       level of this block above the leaf level.
                     numrecs     number of records or keys in the block.
                     leftsib     left (logically lower) sibling block, 0 if none.
                     rightsib    right (logically higher) sibling block, 0 if none.
                     recs        [leaf  blocks  only]  array  of  extent  records.   Each  record
                                 contains startoff, startblock, blockcount, and extentflag (1  if
                                 the extent is unwritten).
                     keys        [non-leaf blocks only] array of key records. These are the first
                                 key value of each block in the level below this one. Each record
                                 contains startoff.
                     ptrs        [non-leaf  blocks  only]  array  of  child block pointers.  Each
                                 pointer is a filesystem block number to the next  level  in  the
                                 Btree.

       bnobt     There  is  one  set  of filesystem blocks forming the by-block-number allocation
                 Btree for each allocation group. The root block of this Btree is  designated  by
                 the  bnoroot  field  in  the  corresponding AGF block.  The blocks are linked to
                 sibling left and right blocks at each level, as well as by pointers from  parent
                 to child blocks.  Each block has the following fields:
                     magic       BNOBT block magic number, 0x41425442 ('ABTB').
                     level       level number of this block, 0 is a leaf.
                     numrecs     number of data entries in the block.
                     leftsib     left (logically lower) sibling block, 0 if none.
                     rightsib    right (logically higher) sibling block, 0 if none.
                     recs        [leaf  blocks  only]  array  of  freespace  records. Each record
                                 contains startblock and blockcount.
                     keys        [non-leaf blocks only] array of key records. These are the first
                                 value  of  each  block  in the level below this one. Each record
                                 contains startblock and blockcount.
                     ptrs        [non-leaf blocks only]  array  of  child  block  pointers.  Each
                                 pointer  is  a  block  number within the allocation group to the
                                 next level in the Btree.

       cntbt     There is one set of filesystem  blocks  forming  the  by-block-count  allocation
                 Btree  for  each allocation group. The root block of this Btree is designated by
                 the cntroot field in the corresponding AGF  block.  The  blocks  are  linked  to
                 sibling  left and right blocks at each level, as well as by pointers from parent
                 to child blocks. Each block has the following fields:
                     magic       CNTBT block magic number, 0x41425443 ('ABTC').
                     level       level number of this block, 0 is a leaf.
                     numrecs     number of data entries in the block.
                     leftsib     left (logically lower) sibling block, 0 if none.
                     rightsib    right (logically higher) sibling block, 0 if none.
                     recs        [leaf blocks only]  array  of  freespace  records.  Each  record
                                 contains startblock and blockcount.
                     keys        [non-leaf blocks only] array of key records. These are the first
                                 value of each block in the level below  this  one.  Each  record
                                 contains blockcount and startblock.
                     ptrs        [non-leaf  blocks  only]  array  of  child  block pointers. Each
                                 pointer is a block number within the  allocation  group  to  the
                                 next level in the Btree.

       data      User  file  blocks,  and  other blocks whose type is unknown, have this type for
                 display purposes in xfs_db.  The block data is displayed in hexadecimal format.

       dir       A version 1 directory is organized as a Btree with the directory  data  embedded
                 in  the  leaf blocks. The root of the Btree is found in block 0 of the file. The
                 index (sort order) of the Btree is the hash value of the  entry  name.  All  the
                 blocks contain a blkinfo structure at the beginning with the following fields:
                     forw        next sibling block.
                     back        previous sibling block.
                     magic       magic number for this block type.
                 The non-leaf (node) blocks have the following fields:
                     hdr         header   containing  a  blkinfo  structure  info  (magic  number
                                 0xfebe), the count of active entries,  and  the  level  of  this
                                 block above the leaves.
                     btree       array  of  entries  containing  hashval  and  before fields. The
                                 before value is a block number within the directory file to  the
                                 child block, the hashval is the last hash value in that block.
                 The leaf blocks have the following fields:
                     hdr         header   containing  a  blkinfo  structure  info  (magic  number
                                 0xfeeb), the count of  active  entries,  namebytes  (total  name
                                 string  bytes), holes flag (block needs compaction), and freemap
                                 (array of base, size entries for free regions).
                     entries     array of structures containing hashval, nameidx (byte index into
                                 the block of the name string), and namelen.
                     namelist    array of structures containing inumber and name.

       dir2      A  version  2 directory has four kinds of blocks.  Data blocks start at offset 0
                 in the file.  There are two kinds of data blocks: single-block directories  have
                 the  leaf  information  embedded  at the end of the block, data blocks in multi-
                 block directories do not.  Node and leaf blocks  start  at  offset  32GiB  (with
                 either  a  single leaf block or the root node block).  Freespace blocks start at
                 offset 64GiB.  The node and leaf blocks form a Btree,  with  references  to  the
                 data  in  the  data  blocks.  The freespace blocks form an index of longest free
                 spaces within the data blocks.

                 A single-block directory block contains the following fields:
                     bhdr        header containing magic number 0x58443242 ('XD2B') and an  array
                                 bestfree  of  the  longest  3  free spaces in the block (offset,
                                 length).
                     bu          array of union structures. Each element is either an entry or  a
                                 freespace.    For  entries,  there  are  the  following  fields:
                                 inumber, namelen, name, and tag.  For freespace, there  are  the
                                 following  fields:  freetag  (0xffff), length, and tag.  The tag
                                 value is the byte offset in the block of the start of the  entry
                                 it is contained in.
                     bleaf       array  of  leaf  entries  containing  hashval  and address.  The
                                 address is a 64-bit word offset into the file.
                     btail       tail structure containing the total count of  leaf  entries  and
                                 stale count of unused leaf entries.
                 A data block contains the following fields:
                     dhdr        header  containing magic number 0x58443244 ('XD2D') and an array
                                 bestfree of the longest 3 free  spaces  in  the  block  (offset,
                                 length).
                     du          array of union structures as for bu.
                 Leaf blocks have two possible forms. If the Btree consists of a single leaf then
                 the freespace information is in the leaf block,  otherwise  it  is  in  separate
                 blocks  and  the  root  of  the Btree is a node block. A leaf block contains the
                 following fields:
                     lhdr        header containing a blkinfo structure info (magic number  0xd2f1
                                 for  the  single leaf case, 0xd2ff for the true Btree case), the
                                 total count of leaf entries, and  stale  count  of  unused  leaf
                                 entries.
                     lents       leaf entries, as for bleaf.
                     lbests      [single  leaf  only] array of values which represent the longest
                                 freespace in each data block in the directory.
                     ltail       [single leaf only] tail structure containing bestcount count  of
                                 lbests.
                 A node block is identical to that for types attr and dir.

                 A freespace block contains the following fields:
                     fhdr        header  containing  magic  number  0x58443246  ('XD2F'), firstdb
                                 first data block number covered by this freespace block,  nvalid
                                 number   of   valid   entries,   and  nused  number  of  entries
                                 representing real data blocks.
                     fbests      array of values as for lbests.

       dqblk     The quota information is stored in files referred to by the superblock  uquotino
                 and  pquotino  fields. Each filesystem block in a quota file contains a constant
                 number of quota entries. The quota entry size is currently 136 bytes, so with  a
                 4KiB  filesystem  block  size  there  are  30 quota entries per block. The dquot
                 command is used to locate these entries in the filesystem.  The file entries are
                 indexed  by  the  user  or project identifier to determine the block and offset.
                 Each quota entry has the following fields:
                     magic          magic number, 0x4451 ('DQ').
                     version        version number, currently 1.
                     flags          flags, values include 0x01 for user quota, 0x02  for  project
                                    quota.
                     id             user or project identifier.
                     blk_hardlimit  absolute limit on blocks in use.
                     blk_softlimit  preferred limit on blocks in use.
                     ino_hardlimit  absolute limit on inodes in use.
                     ino_softlimit  preferred limit on inodes in use.
                     bcount         blocks actually in use.
                     icount         inodes actually in use.
                     itimer         time  when  service will be refused if soft limit is violated
                                    for inodes.
                     btimer         time when service will be refused if soft limit  is  violated
                                    for blocks.
                     iwarns         number of warnings issued about inode limit violations.
                     bwarns         number of warnings issued about block limit violations.
                     rtb_hardlimit  absolute limit on realtime blocks in use.
                     rtb_softlimit  preferred limit on realtime blocks in use.
                     rtbcount       realtime blocks actually in use.
                     rtbtimer       time  when  service will be refused if soft limit is violated
                                    for realtime blocks.
                     rtbwarns       number  of  warnings  issued  about  realtime   block   limit
                                    violations.

       inobt     There  is  one  set  of filesystem blocks forming the inode allocation Btree for
                 each allocation group. The root block of this Btree is designated  by  the  root
                 field in the corresponding AGI block.  The blocks are linked to sibling left and
                 right blocks at each level, as well as by pointers from parent to child  blocks.
                 Each block has the following fields:
                     magic       INOBT block magic number, 0x49414254 ('IABT').
                     level       level number of this block, 0 is a leaf.
                     numrecs     number of data entries in the block.
                     leftsib     left (logically lower) sibling block, 0 if none.
                     rightsib    right (logically higher) sibling block, 0 if none.
                     recs        [leaf  blocks only] array of inode records. Each record contains
                                 startino allocation-group relative inode number, freecount count
                                 of  free  inodes in this chunk, and free bitmap, LSB corresponds
                                 to inode 0.
                     keys        [non-leaf blocks only] array of key records. These are the first
                                 value  of  each  block  in the level below this one. Each record
                                 contains startino.
                     ptrs        [non-leaf blocks only]  array  of  child  block  pointers.  Each
                                 pointer  is  a  block  number within the allocation group to the
                                 next level in the Btree.

       inode     Inodes are allocated in "chunks" of 64 inodes each. Usually a chunk is  multiple
                 filesystem blocks, although there are cases with large filesystem blocks where a
                 chunk is less than one block. The inode Btree (see inobt above)  refers  to  the
                 inode  numbers  per  allocation  group.  The  inode numbers directly reflect the
                 location of the inode block on disk. Use the inode command to point xfs_db to  a
                 specific inode. Each inode contains four regions: core, next_unlinked, u, and a.
                 core contains the fixed information.  next_unlinked is separated from  the  core
                 due  to  journaling  considerations,  see type agi field unlinked.  u is a union
                 structure that is different in  size  and  format  depending  on  the  type  and
                 representation of the file data ("data fork").  a is an optional union structure
                 to describe attribute data, that is different  in  size,  format,  and  location
                 depending  on the presence and representation of attribute data, and the size of
                 the u data ("attribute fork").  xfs_db automatically selects  the  proper  union
                 members based on information in the inode.

                 The following are fields in the inode core:
                     magic       inode magic number, 0x494e ('IN').
                     mode        mode  and  type of file, as described in chmod(2), mknod(2), and
                                 stat(2).
                     version     inode version, 1 or 2.
                     format      format of u union data (0: xfs_dev_t, 1: local file  -  in-inode
                                 directory  or  symlink, 2: extent list, 3: Btree root, 4: unique
                                 id [unused]).
                     nlinkv1     number of links to the file in a version 1 inode.
                     nlinkv2     number of links to the file in a version 2 inode.
                     projid_lo   owner's project id (low word; version 2 inode only).   projid_hi
                                 owner's project id (high word; version 2 inode only).
                     uid         owner's user id.
                     gid         owner's group id.
                     atime       time last accessed (seconds and nanoseconds).
                     mtime       time last modified.
                     ctime       time created or inode last modified.
                     size        number of bytes in the file.
                     nblocks     total  number  of  blocks  in  the  file  including indirect and
                                 attribute.
                     extsize     basic/minimum extent size for the file.
                     nextents    number of extents in the data fork.
                     naextents   number of extents in the attribute fork.
                     forkoff     attribute fork offset in the inode, in  64-bit  words  from  the
                                 start of u.
                     aformat     format  of  a  data (1: local attribute data, 2: extent list, 3:
                                 Btree root).
                     dmevmask    DMAPI event mask.
                     dmstate     DMAPI state information.
                     newrtbm     file is the realtime bitmap and is "new" format.
                     prealloc    file has preallocated data space after EOF.
                     realtime    file data is in the realtime subvolume.
                     gen         inode generation number.
                 The following fields are in the u data fork union:
                     bmbt        bmap Btree root. This looks like a bmapbtd block with  redundant
                                 information removed.
                     bmx         array of extent descriptors.
                     dev         dev_t for the block or character device.
                     sfdir       shortform (in-inode) version 1 directory. This consists of a hdr
                                 containing the parent inode number and a count of active entries
                                 in  the  directory,  followed  by  an  array  list  of hdr.count
                                 entries. Each such entry contains  inumber,  namelen,  and  name
                                 string.
                     sfdir2      shortform (in-inode) version 2 directory. This consists of a hdr
                                 containing a count  of  active  entries  in  the  directory,  an
                                 i8count  of  entries  with  inumbers  that don't fit in a 32-bit
                                 value, and the parent inode number, followed by an array list of
                                 hdr.count  entries.  Each  such  entry contains namelen, a saved
                                 offset used when the directory is converted to a larger form,  a
                                 name string, and the inumber.
                     symlink     symbolic link string value.
                 The following fields are in the a attribute fork union if it exists:
                     bmbt        bmap Btree root, as above.
                     bmx         array of extent descriptors.
                     sfattr      shortform  (in-inode)  attribute  values. This consists of a hdr
                                 containing a totsize (total size in bytes) and a count of active
                                 entries,  followed  by  an array list of hdr.count entries. Each
                                 such entry contains namelen,  valuelen,  root  flag,  name,  and
                                 value.

       log       Log  blocks  contain  the  journal  entries for XFS.  It's not useful to examine
                 these with xfs_db, use xfs_logprint(8) instead.

       rtbitmap  If the filesystem has a  realtime  subvolume,  then  the  rbmino  field  in  the
                 superblock  refers to a file that contains the realtime bitmap.  Each bit in the
                 bitmap file controls the allocation of a single realtime extent (set  ==  free).
                 The bitmap is processed in 32-bit words, the LSB of a word is used for the first
                 extent controlled by that bitmap word. The atime field of  the  realtime  bitmap
                 inode  contains  a  counter  that is used to control where the next new realtime
                 file will start.

       rtsummary If the filesystem has a realtime  subvolume,  then  the  rsumino  field  in  the
                 superblock refers to a file that contains the realtime summary data. The summary
                 file contains a two-dimensional array of 16-bit values.  Each value  counts  the
                 number  of free extent runs (consecutive free realtime extents) of a given range
                 of sizes that starts in a given  bitmap  block.   The  size  ranges  are  binary
                 buckets (low size in the bucket is a power of 2).  There are as many size ranges
                 as are necessary given the size of the realtime subvolume.  The first  dimension
                 is  the  size  range,  the  second dimension is the starting bitmap block number
                 (adjacent entries are for the same size, adjacent bitmap blocks).

       sb        There is one sb (superblock) structure per allocation group.  It  is  the  first
                 disk  block  in  the  allocation  group.   Only  the  first  one (block 0 of the
                 filesystem) is actually used; the other blocks  are  redundant  information  for
                 xfs_repair(8) to use if the first superblock is damaged. Fields defined:
                     magicnum    superblock magic number, 0x58465342 ('XFSB').
                     blocksize   filesystem block size in bytes.
                     dblocks     number of filesystem blocks present in the data subvolume.
                     rblocks     number of filesystem blocks present in the realtime subvolume.
                     rextents    number of realtime extents that rblocks contain.
                     uuid        unique identifier of the filesystem.
                     logstart    starting  filesystem block number of the log (journal).  If this
                                 value is 0 the log is "external".
                     rootino     root inode number.
                     rbmino      realtime bitmap inode number.
                     rsumino     realtime summary data inode number.
                     rextsize    realtime extent size in filesystem blocks.
                     agblocks    size of an allocation group in filesystem blocks.
                     agcount     number of allocation groups.
                     rbmblocks   number of realtime bitmap blocks.
                     logblocks   number of log blocks (filesystem blocks).
                     versionnum  filesystem version information.  This value is currently  1,  2,
                                 3, or 4 in the low 4 bits.  If the low bits are 4 then the other
                                 bits have additional meanings.  1  is  the  original  value.   2
                                 means  that attributes were used.  3 means that version 2 inodes
                                 (large link counts) were used.  4 is the bitmask version of  the
                                 version  number.  In this case, the other bits are used as flags
                                 (0x0010: attributes were used, 0x0020:  version  2  inodes  were
                                 used,  0x0040: quotas were used, 0x0080: inode cluster alignment
                                 is in force, 0x0100: data stripe alignment is in force,  0x0200:
                                 the  shared_vn  field is used, 0x1000: unwritten extent tracking
                                 is on, 0x2000: version 2 directories are in use).
                     sectsize    sector size in bytes, currently always 512.  This is the size of
                                 the superblock and the other header blocks.
                     inodesize   inode size in bytes.
                     inopblock   number of inodes per filesystem block.
                     fname       obsolete, filesystem name.
                     fpack       obsolete, filesystem pack name.
                     blocklog    log2 of blocksize.
                     sectlog     log2 of sectsize.
                     inodelog    log2 of inodesize.
                     inopblog    log2 of inopblock.
                     agblklog    log2 of agblocks (rounded up).
                     rextslog    log2 of rextents.
                     inprogress  mkfs.xfs(8)   or  xfs_copy(8)  aborted  before  completing  this
                                 filesystem.
                     imax_pct    maximum percentage of filesystem space used for inode blocks.
                     icount      number of allocated inodes.
                     ifree       number of allocated inodes that are not in use.
                     fdblocks    number of free data blocks.
                     frextents   number of free realtime extents.
                     uquotino    user quota inode number.
                     pquotino    project quota inode number; this is currently unused.
                     qflags      quota status flags (0x01: user quota  accounting  is  on,  0x02:
                                 user quota limits are enforced, 0x04: quotacheck has been run on
                                 user quotas, 0x08: project quota accounting is on, 0x10: project
                                 quota  limits  are  enforced,  0x20:  quotacheck has been run on
                                 project quotas).
                     flags       random flags. 0x01: only read-only mounts are allowed.
                     shared_vn   shared version number (shared readonly filesystems).
                     inoalignmt  inode chunk alignment in filesystem blocks.
                     unit        stripe or RAID unit.
                     width       stripe or RAID width.
                     dirblklog   log2 of directory block size (filesystem blocks).

       symlink   Symbolic link blocks are used only when the symbolic link  value  does  not  fit
                 inside  the  inode.  The block content is just the string value.  Bytes past the
                 logical end of the symbolic link value have arbitrary values.

       text      User file blocks, and other blocks whose type is unknown,  have  this  type  for
                 display  purposes  in  xfs_db.   The  block  data  is  displayed in two columns:
                 Hexadecimal format and printable ASCII chars.

DIAGNOSTICS

       Many messages can come from the check (blockget) command.  If the filesystem is completely
       corrupt, a core dump might be produced instead of the message
              device is not a valid filesystem

       If  the  filesystem  is very large (has many files) then check might run out of memory. In
       this case the message
              out of memory
       is printed.

       The following is a description of the most likely problems and  the  associated  messages.
       Most  of  the  diagnostics  produced  are  only  meaningful  with  an understanding of the
       structure of the filesystem.

       agf_freeblks n, counted m in ag a
              The freeblocks count in the allocation group header for allocation group a  doesn't
              match the number of blocks counted free.

       agf_longest n, counted m in ag a
              The  longest  free  extent  in  the  allocation group header for allocation group a
              doesn't match the longest free extent found in the allocation group.

       agi_count n, counted m in ag a
              The allocated inode count in the allocation group header  for  allocation  group  a
              doesn't match the number of inodes counted in the allocation group.

       agi_freecount n, counted m in ag a
              The  free inode count in the allocation group header for allocation group a doesn't
              match the number of inodes counted free in the allocation group.

       block a/b expected inum 0 got i
              The block number is specified as a pair (allocation  group  number,  block  in  the
              allocation  group).   The  block  is used multiple times (shared), between multiple
              inodes.  This message usually follows a message of the next type.

       block a/b expected type unknown got y
              The block is used multiple times (shared).

       block a/b type unknown not expected

SEE ALSO

       mkfs.xfs(8), xfs_admin(8), xfs_copy(8), xfs_logprint(8),  xfs_metadump(8),  xfs_ncheck(8),
       xfs_repair(8), mount(8), chmod(2), mknod(2), stat(2), xfs(5).

                                                                                        xfs_db(8)