xfs_db.8

xfs_db

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONCEPTS
COMMANDS
TYPES
DIAGNOSTICS
SEE ALSO

---

NAME

xfs_db − debug an XFS filesystem

SYNOPSIS

xfs_db [ −c cmd ] … [ −i|r|x|F ] [ −f ] [ −l logdev ] [ −p progname ] device **
xfs_db −V**

DESCRIPTION

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

OPTIONS

−l logdev

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

−p progname

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

CONCEPTS

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

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

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

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

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

COMMANDS

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

ablock filoff

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

addr [field-expression]

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

agf [agno]

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

agfl [agno]

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

agi [agno]

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

agresv [agno]

Displays the length, free block count, per-AG reservation size, and per-AG reservation usage for a given AG. If no argument is given, display information for all AGs.

attr_get [−p|−r|−u|−s|−Z] [−N namefile**|name]**

Print the value of the specified extended attribute from the current file.

attr_list [−p|−r|−u|−s|−Z] [−v]

Lists the extended attributes of the current file.

attr_remove [−p|−r|−u|−s|−Z] [−n] [−N namefile**|name]**

Remove the specified extended attribute from the current file.

attr_set [−p−r|−u|−s|−Z] [−n] [−R|−C] [−v valuelen**|−V** valuefile**] [−N** *
namefile***|name] [value]**

Sets an extended attribute on the current file with the given name.

See the back command.

blockfree

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

blockget [−npvs] [−b bno**] … [−i** ino**] …**

Get block usage and check filesystem consistency. The information is saved for use by a subsequent blockuse, ncheck, or blocktrash command.

blocktrash [-z] [−o offset**] [−n** count**] [−x** min**] [−y** max**] [−s** seed**]
[−0|1|2|3] [−t** type**] …**

Trash randomly selected filesystem metadata blocks. Trashing occurs to randomly selected bits in the chosen blocks. This command is available only in debugging versions of xfs_db. It is useful for testing xfs_repair(8).

−0 | -1 | -2 | -3

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

blockuse [−n] [−c count**]**

Print usage for current filesystem block(s). For each block, the type and (if any) inode are printed.

**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.

bmapinflate [−d dirty_bytes**] [-e] [−n** nr**]**

Duplicates the first data fork mapping this many times, as if the mapping had been repeatedly reflinked. This is an expert-mode command for exercising high-refcount filesystems only. Existing data fork mappings will be forgotten and the refcount btree will not be updated. This command leaves at least the refcount btree and the inode inconsistent; xfs_repair must be run afterwards.

btdump [-a] [-i]

If the cursor points to a btree node, dump the btree from that block downward. If instead the cursor points to an inode, dump the data fork block mapping btree if there is one. If the cursor points to a directory or extended attribute btree node, dump that. By default, only records stored in the btree are dumped.

btheight [−b blksz**] [−n** recs**] [−w** max**|min|absmax] btree types…**

For a given number of btree records and a btree type, report the number of records and blocks for each level of the btree, and the total number of blocks. The btree type must be given after the options.

A raw btree geometry can be provided in the format “record_bytes:key_bytes:ptr_bytes:header_type”, where header_type is one of “short”, “long”, “shortcrc”, or “longcrc”.

The supported btree types are: bnobt, cntbt, inobt, finobt, bmapbt, refcountbt, and rmapbt. The magic value all can be used to walk through all btree types.

Options are as follows:

−w absmax

shows the maximum possible height for the given btree types.

−w max

shows only the best case scenario, which is when the btree blocks are maximally loaded.

−w min

shows only the worst case scenario, which is when the btree blocks are half full.

convert type number [type number] … type

Convert from one address form to another. The known types, with alternate names, are:

or aginode (inode number within an allocation group)

or daddroff (byte offset in a daddr)

or fsbyte (byte address in filesystem)

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.

crc [−i|−r|−v]

Invalidates, revalidates, or validates the CRC (checksum) field of the current structure, if it has one. This command is available only on CRC-enabled filesystems. With no argument, validation is performed. Each command will display the resulting CRC value and state.

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 [−g**|−p|−u]** id

Set current address to a group, project or user quota block for the given ID. Defaults to user quota.

dump_iunlinked [-a agno ] [-b bucket ] [-q] [-v]

Dump the contents of unlinked buckets.

Options include:

echo [arg] …

Echo the arguments to the output.

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.

freesp [−bcds] [−A alignment**] [−a** ag**] … [−e** i**] [−h** h1**] … [−m** m**]**

Summarize free space for the filesystem. The free blocks are examined and totalled, and displayed in the form of a histogram, with a count of extents in each range of free extent sizes.

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.

fsmap [ start ] [ end ]

Prints the mapping of disk blocks used by an XFS filesystem. The map lists each extent used by files, allocation group metadata, journalling logs, and static filesystem metadata, as well as any regions that are unused. All blocks, offsets, and lengths are specified in units of 512-byte blocks, no matter what the filesystem’s block size is. The optional start and end arguments can be used to constrain the output to a particular range of disk blocks.

fuzz [−c] [−d] field action

Write garbage into a specific structure field on disk. Expert mode must be enabled to use this command. The operation happens immediately; there is no buffering.

The fuzz command can take the following actions against a field:

zeroes

Clears all bits in the field.

ones

Sets all bits in the field.

firstbit

Flips the first bit in the field. For a scalar value, this is the highest bit.

middlebit

Flips the middle bit in the field.

lastbit

Flips the last bit in the field. For a scalar value, this is the lowest bit.

random

Randomizes the contents of the field.

The following switches affect the write behavior:

hash*[-d|-p***parent_ino]“**strings

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

If the −d option is specified, the directory-specific hash function is used. This only makes a difference on filesystems with ascii case-insensitive lookups enabled.

If the −p option is specified, the parent pointer-specific hash function is used. The parent directory inumber must be specified as an argument. This only makes a difference on filesystems with ascii case-insensitive lookups enabled.

hashcoll [-a] [-s seed] [-n nr**] [-p** path**] -i |** names…

Create directory entries or extended attributes names that all have the same hash value. The metadump name obfuscation algorithm is used here. Names are written to standard output, with a NULL between each name for use with xargs -0.

−n nr

Create this many duplicated names. The default is to create one name.

−p path

Create directory entries or extended attributes in this file instead of writing the names to standard output.

−s seed

Seed the random number generator with this value.

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.

iunlink [-n nr ]

Allocate inodes and put them on the unlinked list.

Options include:

label [label]

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

link [-i ino**] [-p** path**] [-t** ftype**] name**

In the current directory, create a directory entry with the given name pointing to a file. The file must be specified either as a directory tree path as given by the path option; or directly as an inode number as given by the ino option. The file type in the directory entry will be determined from the mode of the child file unless the ftype option is given. The file being targetted must not be on the iunlink list.

log [stop | start filename**]**

Start logging output to filename, stop logging, or print the current logging status.

logformat [−c cycle**] [−s** sunit**]**

Reformats the log to the specified log cycle and log stripe unit. This has the effect of clearing the log destructively. If the log cycle is not specified, the log is reformatted to the current cycle. If the log stripe unit is not specified, the stripe unit from the filesystem superblock is used.

ls [−i] [paths]…

List the contents of a directory. If a path resolves to a directory, the directory will be listed. If no paths are supplied and the IO cursor points at a directory inode, the contents of that directory will be listed.

The output format is: directory cookie, inode number, file type, hash, name length, name.

metadump [−egow] filename

Dumps metadata to a file. See xfs_metadump(8) for more information.

ncheck [−s] [−i ino**] …**

Print name-inode pairs. A blockget −n command must be run first to gather the information.

See the print command.

parent [paths]…

List the parents of a file. If a path resolves to a file, the parents of that file will be listed. If no paths are supplied and the IO cursor points at an inode, the parents of that file will be listed.

The output format is: inode number, inode generation, ondisk namehash, namehash, name length, name.

path dir_path

Walk the directory tree to an inode using the supplied path. Absolute and relative paths are supported.

print [field-expression] …

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

push [command]

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

ring [index]

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

sb [agno]

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

source source-file

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

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, refcntbt, rmapbt, rtbitmap, rtsummary, sb, symlink and text. See the TYPES section below for more information on these data types.

timelimit [OPTIONS]

Print the minimum and maximum supported values for inode timestamps, quota expiration timers, and quota grace periods supported by this filesystem. Options include:

−-bigtime

Print the time limits of an XFS filesystem with the bigtime feature enabled.

−-classic

Print the time limits of a classic XFS filesystem.

−-compact

Print all limits as raw values on a single line.

−-pretty

Print the timestamps in the current locale’s date and time format instead of raw seconds since the Unix epoch.

unlink name

In the current directory, remove a directory entry with the given name. The file being targetted will not be put on the iunlink list.

uuid [uuid | generate | rewrite | restore]

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

version [feature | versionnum features2]

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

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

write [−c|−d] [field value] …

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

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

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

TYPES

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

magicnum

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

The AGI block is the header for inode allocation information; it is in the third 512-byte block of each allocation group. Fields defined:

An attribute fork is organized as a Btree with the actual data embedded in the leaf blocks. The root of the Btree is found in block 0 of the fork. The index (sort order) of the Btree is the hash value of the attribute name. All the blocks contain a blkinfo structure at the beginning, see type dir for a description. Nonleaf blocks are identical in format to those for version 1 and version 2 directories, see type dir for a description. Leaf blocks can refer to “local” or “remote” attribute values. Local values are stored directly in the leaf block. Leaf blocks contain the following fields:

Remote values are stored in an independent block in the attribute fork. Prior to v5, value blocks had no structure, but in v5 they acquired a header structure with the following fields:

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:

There is one set of filesystem blocks forming the by-block-number allocation Btree for each allocation group. The root block of this Btree is designated by the bnoroot field in the corresponding AGF block. The blocks are linked to sibling left and right blocks at each level, as well as by pointers from parent to child blocks. Each block has the following fields:

There is one set of filesystem blocks forming the by-block-count allocation Btree for each allocation group. The root block of this Btree is designated by the cntroot field in the corresponding AGF block. The blocks are linked to sibling left and right blocks at each level, as well as by pointers from parent to child blocks. Each block has the following fields:

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.

forw

The non-leaf (node) blocks have the following fields:

The leaf blocks have the following fields:

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

A single-block directory block contains the following fields:

A data block contains the following fields:

Leaf blocks have two possible forms. If the Btree consists of a single leaf then the freespace information is in the leaf block, otherwise it is in separate blocks and the root of the Btree is a node block. A leaf block contains the following fields:

A node block is identical to that for types attr and dir.

A freespace block contains the following fields:

The quota information is stored in files referred to by the superblock uquotino and pquotino fields. Each filesystem block in a quota file contains a constant number of quota entries. The quota entry size is currently 136 bytes, so with a 4KiB filesystem block size there are 30 quota entries per block. The dquot command is used to locate these entries in the filesystem. The file entries are indexed by the user or project identifier to determine the block and offset. Each quota entry has the following fields:

There is one set of filesystem blocks forming the inode allocation Btree for each allocation group. The root block of this Btree is designated by the root field in the corresponding AGI block. The blocks are linked to sibling left and right blocks at each level, as well as by pointers from parent to child blocks. Each block has the following fields:

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

The following are fields in the inode core:

The following fields are in the u data fork union:

The following fields are in the a attribute fork union if it exists:

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

magic

There is one set of filesystem blocks forming the reverse mapping Btree for each allocation group. The root block of this Btree is designated by the rmaproot field in the corresponding AGF block. The blocks are linked to sibling left and right blocks at each level, as well as by pointers from parent to child blocks. Each block has the following fields:

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.

magicnum

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

DIAGNOSTICS

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

device is not a valid filesystem

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

out of memory

is printed.

The following is a description of the most likely problems and the associated messages. Most of the diagnostics produced are only meaningful with an understanding of the structure of the filesystem. **
agf_freeblks** n**, counted** m in ag a

The freeblocks count in the allocation group header for allocation group a doesn’t match the number of blocks counted free.

agf_longest n**, counted** m in ag a

The longest free extent in the allocation group header for allocation group a doesn’t match the longest free extent found in the allocation group.

agi_count n**, counted** m in ag a

The allocated inode count in the allocation group header for allocation group a doesn’t match the number of inodes counted in the allocation group.

agi_freecount n**, counted** m in ag a

The free inode count in the allocation group header for allocation group a doesn’t match the number of inodes counted free in the allocation group.

block a/b expected inum 0 got i

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

block a/b expected type unknown got y

The block is used multiple times (shared).

block a/b type unknown not expected

SEE ALSO

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

---