1xfs_db(8)                   System Manager's Manual                  xfs_db(8)
2
3
4

NAME

6       xfs_db - debug an XFS filesystem
7

SYNOPSIS

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

DESCRIPTION

14       xfs_db is used to examine an XFS filesystem. Under  rare  circumstances
15       it  can also be used to modify an XFS filesystem, but that task is nor‐
16       mally left to xfs_repair(8) or to scripts such as xfs_admin(8) that run
17       xfs_db.
18

OPTIONS

20       -c cmd xfs_db  commands  may  be  run interactively (the default) or as
21              arguments on the command line.  Multiple  -c  arguments  may  be
22              given. The commands are run in the sequence given, then the pro‐
23              gram  exits.  This  is   the   mechanism   used   to   implement
24              xfs_check(8).
25
26       -f     Specifies that the filesystem image to be processed is stored in
27              a regular file at device (see the mkfs.xfs(8) -d  file  option).
28              This might happen if an image copy of a filesystem has been made
29              into an ordinary file with xfs_copy(8).
30
31       -F     Specifies that we want to continue even if the superblock  magic
32              is not correct.  For use in xfs_check and xfs_metadump.
33
34       -i     Allows execution on a mounted filesystem, provided it is mounted
35              read-only.  Useful for shell scripts such as xfs_check(8), which
36              must  only  operate  on  filesystems  in a guarenteed consistent
37              state (either unmounted or mounted read-only).  These  semantics
38              are slightly different to that of the -r option.
39
40       -l logdev
41              Specifies the device where the filesystems external log resides.
42              Only for those filesystems which use an external  log.  See  the
43              mkfs.xfs(8)  -l  option,  and  refer  to  xfs(5)  for a detailed
44              description of the XFS log.
45
46       -p progname
47              Set the program name to progname for prompts and some error mes‐
48              sages, the default value is xfs_db.
49
50       -r     Open  device  or  filename read-only. This option is required if
51              the filesystem is mounted.  It is only necessary  to  omit  this
52              flag if a command that changes data (write, blocktrash) is to be
53              used.
54
55       -x     Specifies expert mode.  This enables the  write  and  blocktrash
56              commands.
57
58       -V     Prints out the current version number and exits.
59

CONCEPTS

61       xfs_db  commands  can  be broken up into two classes. Most commands are
62       for the navigation and display of data structures  in  the  filesystem.
63       Other commands are for scanning the filesystem in some way.
64
65       Commands which are used to navigate the filesystem structure take argu‐
66       ments which reflect the names of filesystem  structure  fields.   There
67       can  be  multiple  field  names  separated  by dots when the underlying
68       structures are nested, as in C.  The field names can be indexed (as  an
69       array  index)  if  the underlying field is an array.  The array indices
70       can be specified as a range, two numbers separated by a dash.
71
72       xfs_db maintains a current address in the filesystem.  The  granularity
73       of  the  address  is  a filesystem structure.  This can be a filesystem
74       block, an inode or quota (smaller than a filesystem block), or a direc‐
75       tory  block  (could  be  larger  than a filesystem block).  There are a
76       variety of commands to set the current address.   Associated  with  the
77       current  address is the current data type, which is the structural type
78       of this data.  Commands which follow the structure  of  the  filesystem
79       always  set  the  type  as well as the address.  Commands which examine
80       pieces of an individual file (inode) need the current inode to be  set,
81       this is done with the inode command.
82
83       The  current address/type information is actually maintained in a stack
84       that can be explicitly manipulated with the push, pop, and  stack  com‐
85       mands.   This allows for easy examination of a nested filesystem struc‐
86       ture.  Also, the last several locations visited are stored  in  a  ring
87       buffer  which  can be manipulated with the forward, back, and ring com‐
88       mands.
89
90       XFS filesystems are divided into a small number of  allocation  groups.
91       xfs_db  maintains  a  notion  of  the current allocation group which is
92       manipulated by some commands. The initial allocation group is 0.
93

COMMANDS

95       Many commands have extensive online help. Use the help command for more
96       details on any command.
97
98       a      See the addr command.
99
100       ablock filoff
101              Set  current  address  to  the offset filoff (a filesystem block
102              number) in the attribute area of the current inode.
103
104       addr [field-expression]
105              Set current address to the value of the field-expression.   This
106              is  used  to "follow" a reference in one structure to the object
107              being referred to. If no argument is given, the current  address
108              is printed.
109
110       agf [agno]
111              Set  current address to the AGF block for allocation group agno.
112              If no argument is given, use the current allocation group.
113
114       agfl [agno]
115              Set current address to the AGFL block for allocation group agno.
116              If no argument is given, use the current allocation group.
117
118       agi [agno]
119              Set  current address to the AGI block for allocation group agno.
120              If no argument is given, use the current allocation group.
121
122       b      See the back command.
123
124       back   Move to the previous location in the position ring.
125
126       blockfree
127              Free block usage information collected by the last execution  of
128              the  blockget command. This must be done before another blockget
129              command can be given, presumably with different  arguments  than
130              the previous one.
131
132       blockget [-npvs] [-b bno] ... [-i ino] ...
133              Get  block usage and check filesystem consistency.  The informa‐
134              tion is saved for use  by  a  subsequent  blockuse,  ncheck,  or
135              blocktrash command. See xfs_check(8) for more information.
136
137                 -b  is  used  to specify filesystem block numbers about which
138                     verbose information should be printed.
139
140                 -i  is used to specify  inode  numbers  about  which  verbose
141                     information should be printed.
142
143                 -n  is  used  to  save  pathnames for inodes visited, this is
144                     used to support the xfs_ncheck(8) command. It also  means
145                     that pathnames will be printed for inodes that have prob‐
146                     lems. This option uses a lot of memory so is not  enabled
147                     by default.
148
149                 -p  causes  error messages to be prefixed with the filesystem
150                     name being processed. This is useful if several copies of
151                     xfs_db are run in parallel.
152
153                 -s  restricts output to severe errors only. This is useful if
154                     the output is too long otherwise.
155
156                 -v  enables verbose output.  Messages  will  be  printed  for
157                     every block and inode processed.
158
159       blocktrash  [-n count] [-x min] [-y max] [-s seed] [-0|1|2|3] [-t type]
160       ...
161              Trash randomly selected filesystem  metadata  blocks.   Trashing
162              occurs  to  randomly  selected  bits in the chosen blocks.  This
163              command is available only in debugging versions of  xfs_db.   It
164              is useful for testing xfs_repair(8) and xfs_check(8).
165
166                 -0 | -1 | -2 | -3
167                     These  are used to set the operating mode for blocktrash.
168                     Only one can be used: -0 changed  bits  are  cleared;  -1
169                     changed  bits  are  set; -2 changed bits are inverted; -3
170                     changed bits are randomized.
171
172                 -n  supplies the count of block-trashings to perform (default
173                     1).
174
175                 -s  supplies a seed to the random processing.
176
177                 -t  gives  a type of blocks to be selected for trashing. Mul‐
178                     tiple -t options may be given. If no -t options are given
179                     then all metadata types can be trashed.
180
181                 -x  sets  the  minimum  size  of bit range to be trashed. The
182                     default value is 1.
183
184                 -y  sets the maximum size of bit range  to  be  trashed.  The
185                     default value is 1024.
186
187       blockuse [-n] [-c count]
188              Print  usage  for  current filesystem block(s).  For each block,
189              the type and (if any) inode are printed.
190
191                 -c  specifies a count of blocks to process. The default value
192                     is 1 (the current block only).
193
194                 -n  specifies  that  file  names should be printed. The prior
195                     blockget command must have also specified the -n option.
196
197       bmap [-a] [-d] [block [len]]
198              Show the block map for the current inode.  The map  display  can
199              be  restricted  to  an  area  of the file with the block and len
200              arguments. If block is given  and  len  is  omitted  then  1  is
201              assumed for len.
202
203              The  -a  and -d options are used to select the attribute or data
204              area of the inode, if neither option is given  then  both  areas
205              are shown.
206
207       check  See the blockget command.
208
209       convert type number [type number] ... type
210              Convert from one address form to another.  The known types, with
211              alternate names, are:
212                 agblock or  agbno  (filesystem  block  within  an  allocation
213                        group)
214                 agino or aginode (inode number within an allocation group)
215                 agnumber or agno (allocation group number)
216                 bboff or daddroff (byte offset in a daddr)
217                 blkoff  or  fsboff  or  agboff  (byte  offset in a agblock or
218                        fsblock)
219                 byte or fsbyte (byte address in filesystem)
220                 daddr or bb (disk address, 512-byte blocks)
221                 fsblock or fsb or fsbno (filesystem block,  see  the  fsblock
222                        command)
223                 ino or inode (inode number)
224                 inoidx or offset (index of inode in filesystem block)
225                 inooff or inodeoff (byte offset in inode)
226
227              Only  conversions  that  "make sense" are allowed.  The compound
228              form (with more than three arguments) is useful for  conversions
229              such as convert agno ag agbno agb fsblock.
230
231       daddr [d]
232              Set  current  address  to the daddr (512 byte block) given by d.
233              If no value for d is given,  the  current  address  is  printed,
234              expressed as a daddr.  The type is set to data (uninterpreted).
235
236       dblock filoff
237              Set  current  address  to  the offset filoff (a filesystem block
238              number) in the data area of the current inode.
239
240       debug [flagbits]
241              Set debug option bits. These are used for debugging xfs_db.   If
242              no  value  is given for flagbits, print the current debug option
243              bits. These are for the use of the implementor.
244
245       dquot [projectid_or_userid]
246              Set current address to a project or user quota block.
247
248       echo [arg] ...
249              Echo the arguments to the output.
250
251       f      See the forward command.
252
253       forward
254              Move forward to the next entry in the position ring.
255
256       frag [-adflqRrv]
257              Get file fragmentation data. This prints information about frag‐
258              mentation of file data in the filesystem (as opposed to fragmen‐
259              tation of freespace, for which see the  freesp  command).  Every
260              file in the filesystem is examined to see how far from ideal its
261              extent mappings are. A summary is printed giving the totals.
262
263                 -v  sets verbosity, every inode has information  printed  for
264                     it.   The  remaining  options  select  which  inodes  and
265                     extents are examined.  If no options are given  then  all
266                     are assumed set, otherwise just those given are enabled.
267
268                 -a  enables processing of attribute data.
269
270                 -d  enables processing of directory data.
271
272                 -f  enables processing of regular file data.
273
274                 -l  enables processing of symbolic link data.
275
276                 -q  enables processing of quota file data.
277
278                 -R  enables processing of realtime control file data.
279
280                 -r  enables processing of realtime file data.
281
282       freesp [-bcds] [-a ag] ... [-e i] [-h h1] ... [-m m]
283              Summarize  free  space  for  the filesystem. The free blocks are
284              examined and totalled, and displayed in the form of a histogram,
285              with a count of extents in each range of free extent sizes.
286
287                 -a  adds ag to the list of allocation groups to be processed.
288                     If no -a options are given then all allocation groups are
289                     processed.
290
291                 -b  specifies  that  the  histogram buckets are binary-sized,
292                     with the starting sizes being the powers of 2.
293
294                 -c  specifies that freesp will search the by-size (cnt) space
295                     Btree instead of the default by-block (bno) space Btree.
296
297                 -d  specifies that every free extent will be displayed.
298
299                 -e  specifies  that  the  histogram  buckets are equal-sized,
300                     with the size specified as i.
301
302                 -h  specifies a starting block number for a histogram  bucket
303                     as  h1.   Multiple -h's are given to specify the complete
304                     set of buckets.
305
306                 -m  specifies that the histogram starting block  numbers  are
307                     powers of m.  This is the general case of -b.
308
309                 -s  specifies  that  a  final  summary of total free extents,
310                     free blocks, and the average free extent size is printed.
311
312       fsb    See the fsblock command.
313
314       fsblock [fsb]
315              Set current address to the fsblock value given by  fsb.   If  no
316              value for fsb is given the current address is printed, expressed
317              as an fsb.   The  type  is  set  to  data  (uninterpreted).  XFS
318              filesystem  block  numbers  are  computed  ((agno  << agshift) |
319              agblock) where agshift depends on  the  size  of  an  allocation
320              group. Use the convert command to convert to and from this form.
321              Block numbers given for file blocks (for instance from the  bmap
322              command) are in this form.
323
324       hash string
325              Prints  the  hash value of string using the hash function of the
326              XFS directory and attribute implementation.
327
328       help [command]
329              Print help for one or all commands.
330
331       inode [inode#]
332              Set the current inode number. If no inode# is given,  print  the
333              current inode number.
334
335       label [label]
336              Set  the  filesystem  label. The filesystem label can be used by
337              mount(8) instead of using a device special  file.   The  maximum
338              length  of an XFS label is 12 characters - use of a longer label
339              will result in truncation and a warning will be  issued.  If  no
340              label is given, the current filesystem label is printed.
341
342       log [stop | start filename]
343              Start  logging  output  to  filename, stop logging, or print the
344              current logging status.
345
346       metadump [-egow] filename
347              Dumps metadata to a file. See xfs_metadump(8) for more  informa‐
348              tion.
349
350       ncheck [-s] [-i ino] ...
351              Print  name-inode pairs. A blockget -n command must be run first
352              to gather the information.
353
354                 -i  specifies an inode number to be printed. If no -i options
355                     are given then all inodes are printed.
356
357                 -s  specifies that only setuid and setgid files are printed.
358
359       p      See the print command.
360
361       pop    Pop location from the stack.
362
363       print [field-expression] ...
364              Print  field  values.  If no argument is given, print all fields
365              in the current structure.
366
367       push [command]
368              Push location to the stack. If command is supplied, set the cur‐
369              rent  location  to  the results of command after pushing the old
370              location.
371
372       q      See the quit command.
373
374       quit   Exit xfs_db.
375
376       ring [index]
377              Show position ring (if no index argument is given), or move to a
378              specific entry in the position ring given by index.
379
380       sb [agno]
381              Set  current  address to SB header in allocation group agno.  If
382              no agno is given, use the current allocation group number.
383
384       source source-file
385              Process commands  from  source-file.   source  commands  can  be
386              nested.
387
388       stack  View the location stack.
389
390       type [type]
391              Set  the  current  data  type to type.  If no argument is given,
392              show the current data type.  The possible data types  are:  agf,
393              agfl,  agi,  attr,  bmapbta,  bmapbtd,  bnobt, cntbt, data, dir,
394              dir2, dqblk, inobt, inode, log, rtbitmap, rtsummary, sb, symlink
395              and  text.   See the TYPES section below for more information on
396              these data types.
397
398       uuid [uuid | generate | rewrite]
399              Set the filesystem universally unique  identifier  (UUID).   The
400              filesystem  UUID  can  be  used  by  mount(8) instead of using a
401              device special file.  The  uuid  can  be  set  directly  to  the
402              desired  UUID,  or  it  can be automatically generated using the
403              generate option. These options will both  write  the  UUID  into
404              every  copy of the superblock in the filesystem.  rewrite copies
405              the current UUID from the primary superblock  to  all  secondary
406              copies  of the superblock.  If no argument is given, the current
407              filesystem UUID is printed.
408
409       version [feature | versionnum features2]
410              Enable selected features for a filesystem (certain features  can
411              be  enabled  on  an  unmounted filesystem, after mkfs.xfs(8) has
412              created the filesystem).  Support for unwritten extents  can  be
413              enabled  using the extflg option. Support for version 2 log for‐
414              mat can be enabled using the log2 option. Support  for  extended
415              attributes  can be enabled using the attr1 or attr2 option. Once
416              enabled, extended attributes cannot be disabled,  but  the  user
417              may  toggle  between  attr1 and attr2 at will (older kernels may
418              not support the newer version).
419
420              If no argument is given, the current version  and  feature  bits
421              are  printed.   With  one  argument, this command will write the
422              updated version number into every copy of the superblock in  the
423              filesystem.   If  two  arguments are given, they will be used as
424              numeric values for the versionnum  and  features2  bits  respec‐
425              tively,  and  their string equivalent reported (but no modifica‐
426              tions are made).
427
428       write [field value] ...
429              Write a value to disk.  Specific fields can be set in structures
430              (struct mode), or a block can be set to data values (data mode),
431              or a block can be set to string values (string mode, for symlink
432              blocks).  The operation happens immediately: there is no buffer‐
433              ing.
434
435              Struct mode is in effect when the current  type  is  structural,
436              i.e.  not  data.  For  struct  mode,  the syntax is "write field
437              value".
438
439              Data mode is in effect when the current type is  data.  In  this
440              case the contents of the block can be shifted or rotated left or
441              right, or filled with a sequence, a constant value, or a  random
442              value.  In this mode write with no arguments gives more informa‐
443              tion on the allowed commands.
444

TYPES

446       This section gives the fields in each structure type  and  their  mean‐
447       ings.   Note that some types of block cover multiple actual structures,
448       for instance directory blocks.
449
450       agf       The AGF block is the header for block allocation information;
451                 it  is in the second 512-byte block of each allocation group.
452                 The following fields are defined:
453                     magicnum    AGF block magic number, 0x58414746 ('XAGF').
454                     versionnum  version number, currently 1.
455                     seqno       sequence number starting from 0.
456                     length      size in filesystem blocks of  the  allocation
457                                 group.  All allocation groups except the last
458                                 one of the filesystem have  the  superblock's
459                                 agblocks value here.
460                     bnoroot     block number of the root of the Btree holding
461                                 free space information sorted by  block  num‐
462                                 ber.
463                     cntroot     block number of the root of the Btree holding
464                                 free space information sorted by block count.
465                     bnolevel    number  of  levels  in  the   by-block-number
466                                 Btree.
467                     cntlevel    number of levels in the by-block-count Btree.
468                     flfirst     index into the AGFL block of the first active
469                                 entry.
470                     fllast      index into the AGFL block of the last  active
471                                 entry.
472                     flcount     count of active entries in the AGFL block.
473                     freeblks    count  of blocks represented in the freespace
474                                 Btrees.
475                     longest     longest  free  space   represented   in   the
476                                 freespace Btrees.
477                     btreeblks   number of blocks held in the AGF Btrees.
478
479       agfl      The  AGFL  block  contains block numbers for use of the block
480                 allocator; it is in the fourth 512-byte block of each alloca‐
481                 tion  group.  Each entry in the active list is a block number
482                 within the allocation group that can be used for any  purpose
483                 if space runs low.  The AGF block fields flfirst, fllast, and
484                 flcount designate which entries are currently active.   Entry
485                 space  is  allocated  in  a  circular  manner within the AGFL
486                 block.  Fields defined:
487                     bno         array of all block numbers. Even those  which
488                                 are not active are printed.
489
490       agi       The AGI block is the header for inode allocation information;
491                 it is in the third 512-byte block of each  allocation  group.
492                 Fields defined:
493                     magicnum    AGI block magic number, 0x58414749 ('XAGI').
494                     versionnum  version number, currently 1.
495                     seqno       sequence number starting from 0.
496                     length      size  in  filesystem blocks of the allocation
497                                 group.
498                     count       count of inodes allocated.
499                     root        block number of the root of the Btree holding
500                                 inode allocation information.
501                     level       number  of  levels  in  the  inode allocation
502                                 Btree.
503                     freecount   count of allocated inodes  that  are  not  in
504                                 use.
505                     newino      last inode number allocated.
506                     dirino      unused.
507                     unlinked    an  array of inode numbers within the alloca‐
508                                 tion group. The entries in the AGI block  are
509                                 the  heads  of  lists  which  run through the
510                                 inode next_unlinked field. These  inodes  are
511                                 to  be  unlinked the next time the filesystem
512                                 is mounted.
513
514       attr      An attribute fork is organized as a  Btree  with  the  actual
515                 data  embedded  in  the leaf blocks. The root of the Btree is
516                 found in block 0 of the fork.  The index (sort order) of  the
517                 Btree  is  the  hash  value  of  the attribute name.  All the
518                 blocks contain a blkinfo structure at the beginning, see type
519                 dir for a description. Nonleaf blocks are identical in format
520                 to those for version 1 and version 2  directories,  see  type
521                 dir  for  a  description. Leaf blocks can refer to "local" or
522                 "remote" attribute values. Local values are  stored  directly
523                 in  the  leaf block.  Remote values are stored in an indepen‐
524                 dent block in the attribute fork (with  no  structure).  Leaf
525                 blocks contain the following fields:
526                     hdr         header  containing  a  blkinfo structure info
527                                 (magic number  0xfbee),  a  count  of  active
528                                 entries,  usedbytes  total bytes of names and
529                                 values, the firstused byte in the name  area,
530                                 holes  set if the block needs compaction, and
531                                 array freemap as for dir leaf blocks.
532                     entries     array of  structures  containing  a  hashval,
533                                 nameidx  (index  into the block of the name),
534                                 and flags incomplete, root, and local.
535                     nvlist      array of structures describing the  attribute
536                                 names and values. Fields always present: val‐
537                                 uelen (length of value  in  bytes),  namelen,
538                                 and  name.   Fields present for local values:
539                                 value  (value  string).  Fields  present  for
540                                 remote values: valueblk (fork block number of
541                                 containing the value).
542
543       bmapbt    Files with many extents in their data or attribute fork  will
544                 have  the  extents  described  by the contents of a Btree for
545                 that fork, instead of being stored  directly  in  the  inode.
546                 Each bmap Btree starts with a root block contained within the
547                 inode.  The other levels of the Btree are stored in  filesys‐
548                 tem  blocks.  The blocks are linked to sibling left and right
549                 blocks at each level, as well as by pointers from  parent  to
550                 child blocks.  Each block contains the following fields:
551                     magic       bmap  Btree  block  magic  number, 0x424d4150
552                                 ('BMAP').
553                     level       level of this block above the leaf level.
554                     numrecs     number of records or keys in the block.
555                     leftsib     left (logically lower) sibling  block,  0  if
556                                 none.
557                     rightsib    right  (logically higher) sibling block, 0 if
558                                 none.
559                     recs        [leaf blocks only] array of  extent  records.
560                                 Each  record  contains  startoff, startblock,
561                                 blockcount, and extentflag (1 if  the  extent
562                                 is unwritten).
563                     keys        [nonleaf  blocks  only] array of key records.
564                                 These are the first key value of  each  block
565                                 in the level below this one. Each record con‐
566                                 tains startoff.
567                     ptrs        [nonleaf blocks only] array  of  child  block
568                                 pointers.  Each pointer is a filesystem block
569                                 number to the next level in the Btree.
570
571       bnobt     There is one set of filesystem blocks forming  the  by-block-
572                 number  allocation  Btree for each allocation group. The root
573                 block of this Btree is designated by the bnoroot field in the
574                 coresponding  AGF  block.   The  blocks are linked to sibling
575                 left and right blocks at each level, as well as  by  pointers
576                 from  parent  to  child blocks.  Each block has the following
577                 fields:
578                     magic       BNOBT   block   magic   number,    0x41425442
579                                 ('ABTB').
580                     level       level number of this block, 0 is a leaf.
581                     numrecs     number of data entries in the block.
582                     leftsib     left  (logically  lower)  sibling block, 0 if
583                                 none.
584                     rightsib    right (logically higher) sibling block, 0  if
585                                 none.
586                     recs        [leaf   blocks   only]   array  of  freespace
587                                 records. Each record contains startblock  and
588                                 blockcount.
589                     keys        [nonleaf  blocks  only] array of key records.
590                                 These are the first value of  each  block  in
591                                 the  level  below  this one. Each record con‐
592                                 tains startblock and blockcount.
593                     ptrs        [nonleaf blocks only] array  of  child  block
594                                 pointers.  Each  pointer  is  a  block number
595                                 within the allocation group to the next level
596                                 in the Btree.
597
598       cntbt     There  is  one set of filesystem blocks forming the by-block-
599                 count allocation Btree for each allocation  group.  The  root
600                 block of this Btree is designated by the cntroot field in the
601                 coresponding AGF block. The blocks are linked to sibling left
602                 and  right  blocks at each level, as well as by pointers from
603                 parent to child blocks. Each block has the following fields:
604                     magic       CNTBT   block   magic   number,    0x41425443
605                                 ('ABTC').
606                     level       level number of this block, 0 is a leaf.
607                     numrecs     number of data entries in the block.
608                     leftsib     left  (logically  lower)  sibling block, 0 if
609                                 none.
610                     rightsib    right (logically higher) sibling block, 0  if
611                                 none.
612                     recs        [leaf   blocks   only]   array  of  freespace
613                                 records. Each record contains startblock  and
614                                 blockcount.
615                     keys        [nonleaf  blocks  only] array of key records.
616                                 These are the first value of  each  block  in
617                                 the  level  below  this one. Each record con‐
618                                 tains blockcount and startblock.
619                     ptrs        [nonleaf blocks only] array  of  child  block
620                                 pointers.  Each  pointer  is  a  block number
621                                 within the allocation group to the next level
622                                 in the Btree.
623
624       data      User  file  blocks,  and  other blocks whose type is unknown,
625                 have this type for display purposes  in  xfs_db.   The  block
626                 data is displayed in hexadecimal format.
627
628       dir       A version 1 directory is organized as a Btree with the direc‐
629                 tory data embedded in the leaf blocks. The root of the  Btree
630                 is  found  in  block 0 of the file. The index (sort order) of
631                 the Btree is the hash value of the entry name. All the blocks
632                 contain a blkinfo structure at the beginning with the follow‐
633                 ing fields:
634                     forw        next sibling block.
635                     back        previous sibling block.
636                     magic       magic number for this block type.
637                 The non-leaf (node) blocks have the following fields:
638                     hdr         header containing a  blkinfo  structure  info
639                                 (magic  number  0xfebe),  the count of active
640                                 entries, and the level of  this  block  above
641                                 the leaves.
642                     btree       array   of  entries  containing  hashval  and
643                                 before fields. The before value  is  a  block
644                                 number within the directory file to the child
645                                 block, the hashval is the last hash value  in
646                                 that block.
647                 The leaf blocks have the following fields:
648                     hdr         header  containing  a  blkinfo structure info
649                                 (magic number 0xfeeb), the  count  of  active
650                                 entries, namebytes (total name string bytes),
651                                 holes  flag  (block  needs  compaction),  and
652                                 freemap (array of base, size entries for free
653                                 regions).
654                     entries     array  of  structures   containing   hashval,
655                                 nameidx  (byte  index  into  the block of the
656                                 name string), and namelen.
657                     namelist    array of structures  containing  inumber  and
658                                 name.
659
660       dir2      A  version 2 directory has four kinds of blocks.  Data blocks
661                 start at offset 0 in the file.  There are two kinds  of  data
662                 blocks:  single-block  directories  have the leaf information
663                 embedded at the end of the block, data blocks in  multi-block
664                 directories  do  not.   Node  and leaf blocks start at offset
665                 32GiB (with either a single  leaf  block  or  the  root  node
666                 block).   Freespace  blocks  start at offset 64GiB.  The node
667                 and leaf blocks form a Btree, with references to the data  in
668                 the data blocks.  The freespace blocks form an index of long‐
669                 est free spaces within the data blocks.
670
671                 A single-block directory block contains the following fields:
672                     bhdr        header  containing  magic  number  0x58443242
673                                 ('XD2B') and an array bestfree of the longest
674                                 3 free spaces in the block (offset, length).
675                     bu          array of union structures.  Each  element  is
676                                 either an entry or a freespace.  For entries,
677                                 there  are  the  following  fields:  inumber,
678                                 namelen, name, and tag.  For freespace, there
679                                 are the following fields:  freetag  (0xffff),
680                                 length,  and  tag.  The tag value is the byte
681                                 offset in the block of the start of the entry
682                                 it is contained in.
683                     bleaf       array  of leaf entries containing hashval and
684                                 address.  The address is a 64-bit word offset
685                                 into the file.
686                     btail       tail  structure containing the total count of
687                                 leaf entries and stale count of  unused  leaf
688                                 entries.
689                 A data block contains the following fields:
690                     dhdr        header  containing  magic  number  0x58443244
691                                 ('XD2D') and an array bestfree of the longest
692                                 3 free spaces in the block (offset, length).
693                     du          array of union structures as for bu.
694                 Leaf blocks have two possible forms. If the Btree consists of
695                 a single leaf then the freespace information is in  the  leaf
696                 block, otherwise it is in separate blocks and the root of the
697                 Btree is a node block. A leaf block  contains  the  following
698                 fields:
699                     lhdr        header  containing  a  blkinfo structure info
700                                 (magic number  0xd2f1  for  the  single  leaf
701                                 case,  0xd2ff  for  the true Btree case), the
702                                 total count of leaf entries, and stale  count
703                                 of unused leaf entries.
704                     lents       leaf entries, as for bleaf.
705                     lbests      [single leaf only] array of values which rep‐
706                                 resent the longest  freespace  in  each  data
707                                 block in the directory.
708                     ltail       [single  leaf only] tail structure containing
709                                 bestcount count of lbests.
710                 A node block is identical to that for types attr and dir.
711
712                 A freespace block contains the following fields:
713                     fhdr        header  containing  magic  number  0x58443246
714                                 ('XD2F'),  firstdb  first  data  block number
715                                 covered by this freespace block, nvalid  num‐
716                                 ber  of  valid  entries,  and nused number of
717                                 entries representing real data blocks.
718                     fbests      array of values as for lbests.
719
720       dqblk     The quota information is stored in files referred to  by  the
721                 superblock  uquotino  and  pquotino  fields.  Each filesystem
722                 block in a quota file contains a  constant  number  of  quota
723                 entries. The quota entry size is currently 136 bytes, so with
724                 a 4KiB filesystem block size there are 30 quota  entries  per
725                 block.  The  dquot command is used to locate these entries in
726                 the filesystem.  The file entries are indexed by the user  or
727                 project  identifier  to determine the block and offset.  Each
728                 quota entry has the following fields:
729                     magic          magic number, 0x4451 ('DQ').
730                     version        version number, currently 1.
731                     flags          flags, values include 0x01 for user quota,
732                                    0x02 for project quota.
733                     id             user or project identifier.
734                     blk_hardlimit  absolute limit on blocks in use.
735                     blk_softlimit  preferred limit on blocks in use.
736                     ino_hardlimit  absolute limit on inodes in use.
737                     ino_softlimit  preferred limit on inodes in use.
738                     bcount         blocks actually in use.
739                     icount         inodes actually in use.
740                     itimer         time  when service will be refused if soft
741                                    limit is violated for inodes.
742                     btimer         time when service will be refused if  soft
743                                    limit is violated for blocks.
744                     iwarns         number  of  warnings  issued  about  inode
745                                    limit violations.
746                     bwarns         number  of  warnings  issued  about  block
747                                    limit violations.
748                     rtb_hardlimit  absolute limit on realtime blocks in use.
749                     rtb_softlimit  preferred limit on realtime blocks in use.
750                     rtbcount       realtime blocks actually in use.
751                     rtbtimer       time  when service will be refused if soft
752                                    limit is violated for realtime blocks.
753                     rtbwarns       number of warnings issued  about  realtime
754                                    block limit violations.
755
756       inobt     There is one set of filesystem blocks forming the inode allo‐
757                 cation Btree for each allocation group.  The  root  block  of
758                 this  Btree is designated by the root field in the corespond‐
759                 ing AGI block.  The blocks are linked  to  sibling  left  and
760                 right  blocks at each level, as well as by pointers from par‐
761                 ent to child blocks.  Each block has the following fields:
762                     magic       INOBT   block   magic   number,    0x49414254
763                                 ('IABT').
764                     level       level number of this block, 0 is a leaf.
765                     numrecs     number of data entries in the block.
766                     leftsib     left  (logically  lower)  sibling block, 0 if
767                                 none.
768                     rightsib    right (logically higher) sibling block, 0  if
769                                 none.
770                     recs        [leaf  blocks  only]  array of inode records.
771                                 Each  record  contains  startino  allocation-
772                                 group  relative inode number, freecount count
773                                 of free inodes in this chunk, and  free  bit‐
774                                 map, LSB corresponds to inode 0.
775                     keys        [nonleaf  blocks  only] array of key records.
776                                 These are the first value of  each  block  in
777                                 the  level  below  this one. Each record con‐
778                                 tains startino.
779                     ptrs        [nonleaf blocks only] array  of  child  block
780                                 pointers.  Each  pointer  is  a  block number
781                                 within the allocation group to the next level
782                                 in the Btree.
783
784       inode     Inodes are allocated in "chunks" of 64 inodes each. Usually a
785                 chunk is multiple filesystem blocks, although there are cases
786                 with  large  filesystem blocks where a chunk is less than one
787                 block. The inode Btree (see inobt above) refers to the  inode
788                 numbers  per  allocation  group.  The  inode numbers directly
789                 reflect the location of the inode  block  on  disk.  Use  the
790                 inode command to point xfs_db to a specific inode. Each inode
791                 contains four regions: core, next_unlinked, u, and  a.   core
792                 contains  the  fixed information.  next_unlinked is separated
793                 from the core due to journaling considerations, see type  agi
794                 field  unlinked.  u is a union structure that is different in
795                 size and format depending on the type and  representation  of
796                 the  file  data ("data fork").  a is an optional union struc‐
797                 ture to describe attribute data, that is different  in  size,
798                 format,  and location depending on the presence and represen‐
799                 tation of  attribute  data,  and  the  size  of  the  u  data
800                 ("attribute  fork").  xfs_db automatically selects the proper
801                 union members based on information in the inode.
802
803                 The following are fields in the inode core:
804                     magic       inode magic number, 0x494e ('IN').
805                     mode        mode  and  type  of  file,  as  described  in
806                                 chmod(2), mknod(2), and stat(2).
807                     version     inode version, 1 or 2.
808                     format      format  of  u  union  data  (0: xfs_dev_t, 1:
809                                 local file - in-inode directory  or  symlink,
810                                 2:  extent  list, 3: Btree root, 4: unique id
811                                 [unused]).
812                     nlinkv1     number of links to the file in  a  version  1
813                                 inode.
814                     nlinkv2     number  of  links  to the file in a version 2
815                                 inode.
816                     projid      owner's project id (version 2 inode only).
817                     uid         owner's user id.
818                     gid         owner's group id.
819                     atime       time last accessed (seconds and nanoseconds).
820                     mtime       time last modified.
821                     ctime       time created or inode last modified.
822                     size        number of bytes in the file.
823                     nblocks     total number of blocks in the file  including
824                                 indirect and attribute.
825                     extsize     basic/minimum extent size for the file.
826                     nextents    number of extents in the data fork.
827                     naextents   number of extents in the attribute fork.
828                     forkoff     attribute fork offset in the inode, in 64-bit
829                                 words from the start of u.
830                     aformat     format of a data (1: local attribute data, 2:
831                                 extent list, 3: Btree root).
832                     dmevmask    DMAPI event mask.
833                     dmstate     DMAPI state information.
834                     newrtbm     file is the realtime bitmap and is "new" for‐
835                                 mat.
836                     prealloc    file has preallocated data space after EOF.
837                     realtime    file data is in the realtime subvolume.
838                     gen         inode generation number.
839                 The following fields are in the u data fork union:
840                     bmbt        bmap Btree root. This looks  like  a  bmapbtd
841                                 block with redundant information removed.
842                     bmx         array of extent descriptors.
843                     dev         dev_t for the block or character device.
844                     sfdir       shortform  (in-inode)  version  1  directory.
845                                 This consists of a hdr containing the  parent
846                                 inode number and a count of active entries in
847                                 the directory, followed by an array  list  of
848                                 hdr.count  entries.  Each such entry contains
849                                 inumber, namelen, and name string.
850                     sfdir2      shortform  (in-inode)  version  2  directory.
851                                 This  consists of a hdr containing a count of
852                                 active entries in the directory,  an  i8count
853                                 of  entries with inumbers that don't fit in a
854                                 32-bit value, and the  parent  inode  number,
855                                 followed   by  an  array  list  of  hdr.count
856                                 entries. Each such entry contains namelen,  a
857                                 saved  offset used when the directory is con‐
858                                 verted to a larger form, a name  string,  and
859                                 the inumber.
860                     symlink     symbolic link string value.
861                 The  following fields are in the a attribute fork union if it
862                 exists:
863                     bmbt        bmap Btree root, as above.
864                     bmx         array of extent descriptors.
865                     sfattr      shortform (in-inode) attribute  values.  This
866                                 consists of a hdr containing a totsize (total
867                                 size in bytes) and a count of active entries,
868                                 followed   by  an  array  list  of  hdr.count
869                                 entries. Each such  entry  contains  namelen,
870                                 valuelen, root flag, name, and value.
871
872       log       Log  blocks  contain  the  journal entries for XFS.  It's not
873                 useful to examine  these  with  xfs_db,  use  xfs_logprint(8)
874                 instead.
875
876       rtbitmap  If  the  filesystem has a realtime subvolume, then the rbmino
877                 field in the superblock refers to a file  that  contains  the
878                 realtime  bitmap.   Each  bit in the bitmap file controls the
879                 allocation of a single realtime extent  (set  ==  free).  The
880                 bitmap  is  processed  in  32-bit words, the LSB of a word is
881                 used for the first extent controlled by that bitmap word. The
882                 atime  field  of the realtime bitmap inode contains a counter
883                 that is used to control where the next new realtime file will
884                 start.
885
886       rtsummary If  the filesystem has a realtime subvolume, then the rsumino
887                 field in the superblock refers to a file  that  contains  the
888                 realtime summary data. The summary file contains a two-dimen‐
889                 sional array of 16-bit values.  Each value counts the  number
890                 of  free extent runs (consecutive free realtime extents) of a
891                 given range of sizes that starts in  a  given  bitmap  block.
892                 The size ranges are binary buckets (low size in the bucket is
893                 a power of 2).  There are as many size ranges as  are  neces‐
894                 sary  given  the  size  of the realtime subvolume.  The first
895                 dimension is the size range,  the  second  dimension  is  the
896                 starting  bitmap  block  number (adjacent entries are for the
897                 same size, adjacent bitmap blocks).
898
899       sb        There is one sb (superblock) structure per allocation  group.
900                 It is the first disk block in the allocation group.  Only the
901                 first one (block 0 of the filesystem) is actually  used;  the
902                 other  blocks  are redundant information for xfs_repair(8) to
903                 use if the first superblock is damaged. Fields defined:
904                     magicnum    superblock magic number, 0x58465342 ('XFSB').
905                     blocksize   filesystem block size in bytes.
906                     dblocks     number of filesystem blocks  present  in  the
907                                 data subvolume.
908                     rblocks     number  of  filesystem  blocks present in the
909                                 realtime subvolume.
910                     rextents    number of realtime extents that rblocks  con‐
911                                 tain.
912                     uuid        unique identifier of the filesystem.
913                     logstart    starting  filesystem  block number of the log
914                                 (journal).  If this value is  0  the  log  is
915                                 "external".
916                     rootino     root inode number.
917                     rbmino      realtime bitmap inode number.
918                     rsumino     realtime summary data inode number.
919                     rextsize    realtime extent size in filesystem blocks.
920                     agblocks    size  of  an  allocation  group in filesystem
921                                 blocks.
922                     agcount     number of allocation groups.
923                     rbmblocks   number of realtime bitmap blocks.
924                     logblocks   number of log blocks (filesystem blocks).
925                     versionnum  filesystem version information.   This  value
926                                 is currently 1, 2, 3, or 4 in the low 4 bits.
927                                 If the low bits are 4  then  the  other  bits
928                                 have  additional meanings.  1 is the original
929                                 value.  2 means that attributes were used.  3
930                                 means  that  version  2  inodes  (large  link
931                                 counts) were used.  4 is the bitmask  version
932                                 of  the  version  number.   In this case, the
933                                 other  bits  are  used  as   flags   (0x0010:
934                                 attributes   were  used,  0x0020:  version  2
935                                 inodes were used, 0x0040: quotas  were  used,
936                                 0x0080:  inode cluster alignment is in force,
937                                 0x0100: data stripe alignment  is  in  force,
938                                 0x0200:  the shared_vn field is used, 0x1000:
939                                 unwritten extent tracking is on, 0x2000: ver‐
940                                 sion 2 directories are in use).
941                     sectsize    sector  size  in bytes, currently always 512.
942                                 This is the size of the  superblock  and  the
943                                 other header blocks.
944                     inodesize   inode size in bytes.
945                     inopblock   number of inodes per filesystem block.
946                     fname       obsolete, filesystem name.
947                     fpack       obsolete, filesystem pack name.
948                     blocklog    log2 of blocksize.
949                     sectlog     log2 of sectsize.
950                     inodelog    log2 of inodesize.
951                     inopblog    log2 of inopblock.
952                     agblklog    log2 of agblocks (rounded up).
953                     rextslog    log2 of rextents.
954                     inprogress  mkfs.xfs(8)  or  xfs_copy(8)  aborted  before
955                                 completing this filesystem.
956                     imax_pct    maximum percentage of filesystem  space  used
957                                 for inode blocks.
958                     icount      number of allocated inodes.
959                     ifree       number  of  allocated  inodes that are not in
960                                 use.
961                     fdblocks    number of free data blocks.
962                     frextents   number of free realtime extents.
963                     uquotino    user quota inode number.
964                     pquotino    project quota inode number; this is currently
965                                 unused.
966                     qflags      quota status flags (0x01: user quota account‐
967                                 ing  is  on,  0x02:  user  quota  limits  are
968                                 enforced,  0x04:  quotacheck  has been run on
969                                 user quotas, 0x08: project  quota  accounting
970                                 is   on,   0x10:  project  quota  limits  are
971                                 enforced, 0x20: quotacheck has  been  run  on
972                                 project quotas).
973                     flags       random flags. 0x01: only read-only mounts are
974                                 allowed.
975                     shared_vn   shared  version   number   (shared   readonly
976                                 filesystems).
977                     inoalignmt  inode chunk alignment in filesystem blocks.
978                     unit        stripe or RAID unit.
979                     width       stripe or RAID width.
980                     dirblklog   log2  of  directory  block  size  (filesystem
981                                 blocks).
982
983       symlink   Symbolic link blocks are used only  when  the  symbolic  link
984                 value  does  not  fit  inside the inode. The block content is
985                 just the string value.  Bytes past the  logical  end  of  the
986                 symbolic link value have arbitrary values.
987
988       text      User  file  blocks,  and  other blocks whose type is unknown,
989                 have this type for display purposes  in  xfs_db.   The  block
990                 data  is  displayed  in  two  columns: Hexadecimal format and
991                 printable ASCII chars.
992

DIAGNOSTICS

994       Many messages can come from the check  (blockget)  command;  these  are
995       documented in xfs_check(8).
996

SEE ALSO

998       mkfs.xfs(8),  xfs_admin(8), xfs_check(8), xfs_copy(8), xfs_logprint(8),
999       xfs_metadump(8),  xfs_ncheck(8),  xfs_repair(8),  mount(8),   chmod(2),
1000       mknod(2), stat(2), xfs(5).
1001
1002
1003
1004                                                                     xfs_db(8)
Impressum