xfs_db - debug an XFS filesystem


SYNOPSIS

       xfs_db [ -c cmd ] ... [ -p prog ] [ -r ] [ -x ] xfs_special

       xfs_db -f [ -c cmd ] ... [ -p prog ] [ -f ] [ -r ] [ -x ] file


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_chver  that  run
       xfs_db.

       The options to xfs_db are:

       -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 com­
                 mands are run in the sequence  given,  then  the
                 program  exits.   This  is the mechanism used to
                 implement xfs_check(8).

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

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

       -i        Allows execution on a mounted  filesystem,  pro­
                 vided it is mounted read-only.  Useful for shell
                 scripts such as xfs_check(8),  which  must  only
                 operate  on  filesystems in a guarenteed consis­
                 tent state (either unmounted  or  mounted  read-
                 only).   These  semantics are slightly different
                 to that of the -r option.

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

       -r        Open file or xfs_special read-only.  This option
                 is required if xfs_special is a mounted filesys­
                 tem.   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



CONCEPTS

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

       Commands  which are used to navigate the filesystem struc­
       ture take arguments which reflect the names of  filesystem
       structure fields.  There can be multiple field names sepa­
       rated 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 individ­
       ual file (inode) need the current inode to be set, this is
       done with the inode command.

       The  current  address/type  information  is actually main­
       tained 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 alloca­
       tion 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.

                 Set  current  address to the value of the field-
                 expression.  This is used to ``follow'' a refer­
                 ence  in  one  structure  to  the  object  being
                 referred to.  If no argument is given  the  cur­
                 rent address is printed.

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

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

       agi [ agno ]
                 Set current address to the AGI block for alloca­
                 tion 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 [ -npsv ] [ -b bno ] ... [ -i ino ] ...
                 Get block usage  and  check  filesystem  consis­
                 tency.   The  information  is saved for use by a
                 subsequent blockuse, ncheck, or blocktrash  com­
                 mand.  See xfs_check(8) for more information.
                 The  -b  option  is  used  to specify filesystem
                 block numbers about  which  verbose  information
                 should be printed.
                 The  -i  option is used to specify inode numbers
                 about  which  verbose  information   should   be
                 printed.
                 The  -n  option  is  used  to save pathnames for
                 inodes visited, this  is  used  to  support  the
                 xfs_ncheck(8) command.  It also means that path­
                 names will be printed for inodes that have prob­
                 lems.   This  option  uses a lot of memory so is
                 not enabled by default.
                 The -p option causes error messages to  be  pre­
                 fixed  with the filesystem name being processed.
                 This is useful if several copies of  xfs_db  are
                 run in parallel.

                 only.  This is useful if the output is too  long
                 otherwise.
                 The  -v option enables verbose output.  Messages
                 will be printed for every block and  inode  pro­
                 cessed.

       blocktrash [ -n c ] [ -x a ] [ -y b ] [ -s s ] [ -0123 ] [
                 -t t ] ...
                 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)  and
                 xfs_check(8).
                 The -0, -1, -2, and -3 options (mutually  exclu­
                 sive) set the operating mode for blocktrash.  In
                 -0 mode, changed bits are cleared.  In -1  mode,
                 changed  bits are set.  In -2 mode, changed bits
                 are inverted.  In -3 mode, changed bits are ran­
                 domized.
                 The -n option supplies the count of block-trash­
                 ings to perform (default 1).
                 The -s option supplies a seed to the random pro­
                 cessing.
                 The  -t  option  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.
                 The -x option sets the minimum size of bit range
                 to be trashed.  The default value is 1.
                 The -y option sets the maximum size of bit range
                 to be trashed.  The default value is 1024.

       blockuse [ -n ] [ -c blockcount ]
                 Print usage  for  current  filesystem  block(s).
                 For  each block, the type and (if any) inode are
                 printed.
                 The -c option specifies a  count  of  blocks  to
                 process.   The  default  value is 1 (the current
                 block only).
                 The -n option 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.


       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  off­
                 set  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  com­
                 mand),  ino  or  inode (inode number), inoidx or
                 offset (index of inode in filesystem block), and
                 inooff or inodeoff (byte offset in inode).  Only
                 conversions that  ``make  sense''  are  allowed.
                 The  compound  form  (with more than three argu­
                 ments) 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 infor­
                 mation  about  fragmentation of file data in the

                 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.
                 The -v option 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.
                 The  -a  option  enables processing of attribute
                 data.
                 The -d option enables  processing  of  directory
                 data.
                 The -f option enables processing of regular file
                 data.
                 The -l option  enables  processing  of  symbolic
                 link data.
                 The  -q  option enables processing of quota file
                 data.
                 The -R option  enables  processing  of  realtime
                 control file data.
                 The  -r  option  enables  processing of realtime
                 file data.

       freesp [ -bcds ] [ -a a ] ... [ -e i ] [ -h h1 ] ... [ -m
                 m ]
                 Summarize  free  space  for the filesystem.  The
                 free blocks are examined and totalled, and  dis­
                 played  in the form of a histogram, with a count
                 of extents in each range of free extent sizes.
                 The -a a option adds a to the list of allocation
                 groups  to  be  processed.  If no -a options are
                 given then all allocation groups are  processed.
                 The -b option specifies that the histogram buck­
                 ets are binary-sized, with  the  starting  sizes
                 being the powers of 2.
                 The  -c option specifies that freesp will search
                 the by-size (cnt) space  Btree  instead  of  the
                 default by-block (bno) space Btree.
                 The  -d  option specifies that every free extent
                 will be displayed.
                 The -e i option  specifies  that  the  histogram
                 buckets are equal-sized, with the size specified
                 as i.
                 The -h h1 option specifies a starting block num­
                 ber  for  a histogram bucket as h1.  Multiple -h
                 options are given to specify the complete set of
                 buckets.
                 The  -m  m  option  specifies that the histogram
                 starting block numbers are powers of m.  This is
                 the general case of -b.
                 The  -s option specifies that a final summary of

                 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  cur­
                 rent  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  cur­
                 rent filesystem label is printed.

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

       ncheck [ -s ] [ -i ino ] ...
                 Print name-inode pairs.  A blockget  -n  command
                 must be run first to gather the information.
                 The  -i  option  specifies an inode number to be
                 printed.  If no -i options are  given  then  all
                 inodes are printed.
                 The  -s  option  specifies  that only setuid and
                 setgid files are printed.

       p         See the print command.

       pop       Pop location from the stack.

                 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 sup­
                 plied, 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 posi­
                 tion 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 com­
                 mands can be nested.

       stack     View the location stack.

       type [ type ]
                 Set the current data type to type.  If no  argu­
                 ment  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 or generate or rewrite ]
                 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.  rewrite copies  the  current
                 UUID  from  the  primary  superblock to all sec­
                 ondary copies of the superblock.  If no argument
                 is   given,   the  current  filesystem  UUID  is
                 printed.

       write [ field or value ] ...
                 Write a value to disk.  Specific fields  can  be

                 be set to data values (data mode),  or  a  block
                 can  be  set  to string values (string mode, for
                 symlink blocks).  The operation happens  immedi­
                 ately: 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 argu­
                 ments gives more information on the allowed com­
                 mands.


TYPES

       This  section  gives the fields in each structure type and
       their meanings.  Note that some types of block cover  mul­
       tiple 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 alloca­
                 tion 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-num­
                 ber 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

                 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 alloca­
                 tion 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 begin­
                 ning,  see  type dir for a description.  Nonleaf
                 blocks are identical in format to those for ver­
                 sion  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

                 entries, usedbytes total bytes of names and val­
                 ues, 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  hash­
                 val, 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 pre­
                 sent: valuelen (length of value in bytes), name­
                 len, and name.  Fields present for local values:
                 value (value string).  Fields present for remote
                 values:  valueblk (fork block number of contain­
                 ing 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  con­
                 tained  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 con­
                 tains 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,  start­
                 block,  blockcount,  and  extentflag  (1  if the
                 extent is unwritten)
                 keys:  [nonleaf  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: [nonleaf 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  core­
                 sponding  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.

                 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:   [nonleaf   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: [nonleaf 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  coresponding  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:   [nonleaf   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: [nonleaf 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 hexadec­
                 imal format.

                 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 nonleaf (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 num­
                 ber 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 32GB (with either a single leaf
                 block or the root node block).  Freespace blocks
                 start  at offset 64GB.  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 fol­
                 lowing 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

                 there  are  the following fields: inumber, name­
                 len, 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 con­
                 tained in
                 bleaf: array of leaf entries containing  hashval
                 and  address.  The address is a 64-bit word off­
                 set 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, oth­
                 erwise  it is in separate blocks and the root of
                 the Btree is a node block.  A  leaf  block  con­
                 tains 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 con­
                 taining 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 cov­
                 ered by this freespace block, nvalid  number  of
                 valid  entries, and nused number of entries rep­
                 resenting 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

                 are 30 quota entries per block.  The dquot  com­
                 mand  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 fol­
                 lowing 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 real­
                 time 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  desig­
                 nated  by the root field in the coresponding 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

                 inodes  in this chunk, and free bitmap, LSB cor­
                 responds to inode 0
                 keys:  [nonleaf  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: [nonleaf 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 dif­
                 ferent 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: 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  ver­
                 sion 1 inode
                 nlinkv2:  number  of links to the file in a ver­
                 sion 2 inode
                 projid: owner's  project  id  (version  2  inode
                 only)
                 uid: owner's user id
                 gid: owner's group id
                 atime:  time last accessed (seconds and nanosec­
                 onds)

                 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,
                 used only for realtime
                 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  direc­
                 tory.  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,  fol­
                 lowed  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

                 uelen, 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 allo­
                 cation 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

                 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  origi­
                 nal  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) aborted before complet­
                 ing 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

                 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 read­
                 only 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 sym­
                 bolic  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;
       these are documented in xfs_check(8).


SEE ALSO

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


Man(1) output converted with man2html