xfs_db - debug an XFS filesystem
xfs_db [ -c cmd ] ... [ -p prog ] [ -r ] [ -x ] xfs_special
xfs_db -f [ -c cmd ] ... [ -p prog ] [ -f ] [ -r ] [ -x ] file
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. Multi- ple -c arguments may be given. The commands 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 processed 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). |
|
|
-i |
Allows execution on a mounted filesystem, provided it is mounted read-only. Useful for shell scripts such as xfs_check(8), which must only operate on filesystems in a guarenteed consistent state (either unmounted or mounted read-only). These semantics are slightly different to that of the -r option. |
|
|
-p prog -r |
Set the program name for prompts and some error messages, the default value is xfs_db. Open file or xfs_special read-only. This option is required if xfs_special is a mounted filesystem. It is |
|
|
-x |
Specifies expert mode. This enables the write command. |
xfs_db commands can be broken up into two classes. Most commands are for the navigation and display of data structures in the filesystem. Other commands are for scanning the filesystem in some way.
Commands which are used to navigate the filesystem structure take arguments which reflect the names of filesys- tem structure fields. There can be multiple field names separated by dots when the underlying structures are nested, as in C. The field names can be indexed (as an array index) if the underlying field is an array. The array indices can be specified as a range, two numbers separated by a dash.
xfs_db maintains a current address in the filesystem. The granularity of the address is a filesystem structure. This can be a filesystem block, an inode or quota (smaller than a filesystem block), or a directory block (could be larger than a filesystem block). There are a variety of commands to set the current address. Associated with the cur- rent address is the current data type, which is the structural type of this data. Commands which follow the struc- ture 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 maintained in a stack that can be explicitly manipulated with the push, pop, and stack commands. This allows for easy examination of a nested filesystem structure. Also, the last several locations visited are stored in a ring buffer which can be manipulated with the forward, back, and ring commands.
XFS filesystems are divided into a small number of allocation groups. xfs_db maintains a notion of the current allo- cation group which is manipulated by some commands. The initial allocation group is 0.
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 |
addr [ field-expression ]
|
Set current address to the value of the field-expression. This is used to ``follow'' a reference in one |
agf [ agno ]
Set current address to the AGF block for allocation group agno. If no argument is given use the current
allocation group.
agfl [ agno ]
|
Set current address to the AGFL block for allocation group agno. If no argument is given use the cur- |
agi [ agno ]
|
Set current address to the AGI block for allocation group agno. If no argument is given use the current |
b See the back command.
back Move to the previous location in the position ring.
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 consistency. The information is saved for use by a subsequent
blockuse, ncheck, or blocktrash command. 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 pathnames will be printed for inodes that have problems. This option uses
a lot of memory so is not enabled by default.
The -p option causes error messages to be prefixed with the filesystem name being processed. This is
useful if several copies of xfs_db are run in parallel.
The -s option restricts output to severe errors 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 processed.
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 exclusive) 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 randomized.
The -n option supplies the count of block-trashings to perform (default 1).
The -s option supplies a seed to the random processing.
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 |
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. |
check See the blockget command.
convert type number [ type number ] ... type
|
Convert from one address form to another. The known types, with alternate names, are: agblock or agbno (filesystem block within an allocation group), agino or aginode (inode number within an alloca- tion group), agnumber or agno (allocation group number), bboff or daddroff (byte offset in a daddr), blkoff or fsboff or agboff (byte offset in a agblock or fsblock), byte or fsbyte (byte address in filesys- tem), daddr or bb (disk address, 512-byte blocks), fsblock or fsb or fsbno (filesystem block, see the fsblock command), ino or inode (inode number), inoidx or offset (index of inode in filesystem block), and inooff or inodeoff (byte offset in inode). Only conversions that ``make sense'' are allowed. The compound form (with more than three arguments) is useful for conversions such as convert agno ag |
agbno agb fsblock.
daddr [ d ]
|
Set current address to the daddr (512 byte block) given by d. If no value for d is given the current |
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 |
dquot [ projectid_or_userid ]
Set current address to a project or user quota block.
echo [ arg ] ...
Echo the arguments to the output.
f See the forward command.
forward Move forward to the next entry in the position ring.
frag [ -adflqRrv ]
Get file fragmentation data. This prints information about fragmentation of file data in the filesystem (as
opposed to fragmentation of freespace, for which see the freesp command). Every file in the filesystem
is examined to see how far from ideal its extent mappings are. A summary is printed giving the totals.
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 displayed in the form of a histogram, with a count of extents in each range of free extent sizes. |
fsb See the fsblock command.
fsblock [ fsb ]
Set current address to the fsblock value given by fsb. If no value for fsb is given the current address is
printed, expressed as an fsb. The type is set to data (uninterpreted). XFS filesystem block numbers
are computed ((agno << agshift) | agblock) where agshift depends on the size of an allocation group.
Use the convert command to convert to and from this form. Block numbers given for file blocks (for
instance from the bmap command) are in this form.
hash string
Prints the hash value of string using the hash function of the XFS directory and attribute implementation.
help [ command ]
Print help for one or all commands.
inode [ inode# ]
Set the current inode number. If no inode# is given, print the current inode number.
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. |
p See the print command.
pop Pop location from the stack.
print [ field-expression ] ...
Print field values. If no argument is given, print all fields in the current structure.
push [ command ]
|
Push location to the stack. If command is supplied, set the current location to the results of command |
q See the quit command.
quit Exit xfs_db.
ring [ index ]
|
Show position ring (if no index argument is given), or move to a specific entry in the position ring given |
sb [ agno ]
|
Set current address to SB header in allocation group agno. If no agno is given use the current allocation |
source source-file
Process commands from source-file. source commands can be nested.
stack View the location stack.
type [ type ]
Set the current data type to type. If no argument is given, show the current data type. The possible
data types are: agf, agfl, agi, attr, bmapbta, bmapbtd, bnobt, cntbt, data, dir, dir2, dqblk, inobt,
inode, log, rtbitmap, rtsummary, sb, and symlink. See the TYPES section below for more informa-
tion on these data types.
write [ field or value ] ...
|
Write a value to disk. Specific fields can be set in structures (struct mode), or a block can be set to data values (data mode), or a block can be set to string values (string mode, for symlink blocks). The opera- tion happens immediately: there is no buffering. |
This section gives the fields in each structure type and their meanings. Note that some types of block cover multi- ple 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: |
|
cntlevel: number of levels in the by-block-count Btree |
||
|
agfl |
The AGFL block contains block numbers for use of the block allocator; it is in the fourth 512-byte block of each allocation group. Each entry in the active list is a block number within the allocation group that can be used for any purpose if space runs low. The AGF block fields flfirst, fllast, and flcount desig- nate which entries are currently active. Entry space is allocated in a circular manner within the AGFL block. Fields defined: |
|
|
agi |
The AGI block is the header for inode allocation information; it is in the third 512-byte block of each allo- cation group. Fields defined: |
|
|
attr |
An attribute fork is organized as a Btree with the actual data embedded in the leaf blocks. The root of the Btree is found in block 0 of the fork. The index (sort order) of the Btree is the hash value of the attribute name. All the blocks contain a blkinfo structure at the beginning, see type dir for a descrip- tion. Nonleaf blocks are identical in format to those for version 1 and version 2 directories, see type dir for a description. Leaf blocks can refer to ``local'' or ``remote'' attribute values. Local values are stored directly in the leaf block. Remote values are stored in an independent block in the attribute fork (with no structure). Leaf blocks contain the following fields: |
|
|
bmapbt |
Files with many extents in their data or attribute fork will have the extents described by the contents of a Btree for that fork, instead of being stored directly in the inode. Each bmap Btree starts with a root block contained within the inode. The other levels of the Btree are stored in filesystem blocks. The blocks are linked to sibling left and right blocks at each level, as well as by pointers from parent to child blocks. Each block contains the following fields: |
|
|
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 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: |
|
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: |
|
|
data |
User file blocks, and other blocks whose type is unknown, have this type for display purposes in xfs_db. The block data is displayed in hexadecimal format. |
|
|
dir |
A version 1 directory is organized as a Btree with the directory data embedded in the leaf blocks. The root of the Btree is found in block 0 of the file. The index (sort order) of the Btree is the hash value of the entry name. All the blocks contain a blkinfo structure at the beginning with the following fields: The nonleaf (node) blocks have the following fields: The leaf blocks have the following fields: |
|
|
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 following fields: |
|
freetag (0xffff), length, and tag. The tag value is the byte offset in the block of the start of the entry it is contained in A data block contains the following fields: Leaf blocks have two possible forms. If the Btree consists of a single leaf then the freespace informa- tion is in the leaf block, otherwise it is in separate blocks and the root of the Btree is a node block. A leaf block contains the following fields: A node block is identical to that for types attr and dir. A freespace block contains the following fields: |
|
dqblk |
The quota information is stored in files referred to by the superblock uquotino and pquotino fields. Each filesystem block in a quota file contains a constant number of quota entries. The quota entry size is currently 136 bytes, so with a 4KB filesystem block size there are 30 quota entries per block. The dquot command is used to locate these entries in the filesystem. The file entries are indexed by the user or project identifier to determine the block and offset. Each quota entry has the following fields: |
|
|
inobt |
There is one set of filesystem blocks forming the inode allocation Btree for each allocation group. The root block of this Btree is designated by the root field in the 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: |
|
recs: [leaf blocks only] array of inode records. Each record contains startino allocation-group relative inode number, freecount count of free inodes in this chunk, and free bitmap, LSB corresponds to inode 0 |
|
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 infor- mation. next_unlinked is separated from the core due to journalling considerations, see type agi field unlinked. u is a union structure that is different in size and format depending on the type and represen- tation of the file data (``data fork''). a is an optional union structure to describe attribute data, that is dif- ferent 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 fields are in the u data fork union: The following fields are in the a attribute fork union if it exists: |
sfattr: shortform (in-inode) attribute values. This consists of a hdr containing a totsize (total size in
bytes) and a count of active entries, followed by an array list of hdr.count entries. Each such entry
contains namelen, valuelen, root flag, name, and value
log Log blocks contain the journal entries for XFS. It's not useful to examine these with xfs_db, use
xfs_logprint(8) instead.
|
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 val- ues. Each value counts the number of free extent runs (consecutive free realtime extents) of a given range of sizes that starts in a given bitmap block. The size ranges are binary buckets (low size in the bucket is a power of 2). There are as many size ranges as are necessary given the size of the realtime subvolume. The first dimension is the size range, the second dimension is the starting bitmap block number (adjacent entries are for the same size, adjacent bitmap blocks). |
|
sb |
There is one sb (superblock) structure per allocation group. It is the first disk block in the allocation group. Only the first one (block 0 of the filesystem) is actually used; the other blocks are redundant information for xfs_repair(8) to use if the first superblock is damaged. Fields defined: |
|
fdblocks: number of free data blocks |
symlink Symbolic link blocks are used only when the symbolic link value does not fit inside the inode. The block
content is just the string value. Bytes past the logical end of the symbolic link value have arbitrary val-
ues.
Many messages can come from the check (blockget) command; these are documented in xfs_check(8).
mkfs.xfs(8), xfs_check(8), xfs_copy(8), xfs_logprint(8), xfs_ncheck(8), xfs_repair(8), chmod(2), mknod(2), stat(2), xfs(5).