title: xfs_db(8)

summary: debug an XFS filesystem

text:
# xfs_db(8)

## NAME
xfs_db - debug an XFS filesystem

## SYNOPSIS
xfs_db [ -c cmd ] ... [ -i|r|x|F ] [ -f ] [ -l logdev ] [ -R rtdev ] [ -p progname ] device

xfs_db -V

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

## OPTIONS
-c cmd

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

-f

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

-F

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

-i

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

-l logdev

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

-p progname

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

-R

rtdev Specifies the device where the realtime data resides. This is only relevant for filesystems that have a realtime section. See the mkfs.xfs(8) -r option, and refer to xfs(5) for a detailed description of the XFS realtime section.

-r

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

-x

Specifies expert mode. This enables the (write, blocktrash, crc invalidate/revalidate) commands.

-V

Prints the version number and exits.

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

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

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

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

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

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

a

See the addr command.

ablock filoff

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

addr [field-expression]

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

agf [agno]

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

agfl [agno]

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

agi [agno]

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

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.

-p

Sets the attribute in the parent namespace. Only one namespace option can be specified.

-r

Sets the attribute in the root namespace. Only one namespace option can be specified.

-u

Sets the attribute in the user namespace. Only one namespace option can be specified.

-s

Sets the attribute in the secure namespace. Only one namespace option can be specified.

-Z

Sets a filesystem property in the root namespace. Only one namespace option can be specified.

-N

Read the name from this file.

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

Lists the extended attributes of the current file.

-p

Sets the attribute in the parent namespace. Only one namespace option can be specified.

-r

Sets the attribute in the root namespace. Only one namespace option can be specified.

-u

Sets the attribute in the user namespace. Only one namespace option can be specified.

-s

Sets the attribute in the secure namespace. Only one namespace option can be specified.

-Z

Sets a filesystem property in the root namespace. Only one namespace option can be specified.

-v

Print the extended attribute values too.

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

Remove the specified extended attribute from the current file.

-p

Sets the attribute in the parent namespace. Only one namespace option can be specified.

-r

Sets the attribute in the root namespace. Only one namespace option can be specified.

-u

Sets the attribute in the user namespace. Only one namespace option can be specified.

-s

Sets the attribute in the secure namespace. Only one namespace option can be specified.

-Z

Sets a filesystem property in the root namespace. Only one namespace option can be specified.

-N

Read the name from this file.

-n

Do not enable 'noattr2' mode on V4 filesystems.

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.

-p

Sets the attribute in the parent namespace. Only one namespace option can be specified.

-r

Sets the attribute in the root namespace. Only one namespace option can be specified.

-u

Sets the attribute in the user namespace. Only one namespace option can be specified.

-s

Sets the attribute in the secure namespace. Only one namespace option can be specified.

-Z

Sets a filesystem property in the root namespace. Only one namespace option can be specified.

-N

Read the name from this file.

-n

Do not enable 'noattr2' mode on V4 filesystems.

-R

Replace the attribute. The command will fail if the attribute does not already exist.

-C

Create the attribute. The command will fail if the attribute already exists.

-V

Read the value from this file.

-v

Set the attribute value to a string of this length containing the letter 'v'.

b

See the back command.

back

Move to the previous location in the position ring.

blockfree

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

blockget [-npvs] [-b bno] ... [-i ino] ...

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

-b

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

-i

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

-n

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

-p

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

-s

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

-v

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

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

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

-0 | -1 | -2 | -3

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

-n

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

-o

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

-s

supplies a seed to the random processing.

-t

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

-x

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

-y

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

-z

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

blockuse [-n] [-c count]

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

-c

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

-n

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

bmap [-a] [-d] [block [len]]

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

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

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.

-d

Constrain the memory consumption of new dirty btree blocks to this quantity. Defaults to 60MiB.

-e

Estimate the number of blocks and height of the new data fork mapping structure and exit without changing anything.

-n

Create this many copies of the first mapping.

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.

-a

If the cursor points at an inode, dump the extended attribute block mapping btree, if present.

-i

Dump all keys and pointers in intermediate btree nodes, and all records in leaf btree nodes.

btheight [-b blksz] [-n recs] [-w max|min|absmax|avg] 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, rmapbt, rtrefcountbt, and rtrmapbt. The magic value all can be used to walk through all btree types.

Options are as follows:

-b

is used to override the btree block size. The default is the filesystem block size.

-n

is used to specify the number of records to store. This argument is required.

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

-w avg

shows only the average case scenario, which is when the btree blocks are three quarters full.

convert type number [type number] ... type

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

agblock or agbno (filesystem block within an allocation group)

agino or aginode (inode number within an allocation group)

agnumber or agno (allocation group number)

bboff or daddroff (byte offset in a daddr)

blkoff or fsboff or agboff (byte offset in a agblock or fsblock)

byte or fsbyte (byte address in filesystem)

daddr or bb (disk address, 512-byte blocks)

fsblock or fsb or fsbno (filesystem block, see the fsblock command)

ino or inode (inode number)

inoidx or offset (index of inode in filesystem block)

inooff or inodeoff (byte offset in inode)

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

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.

-i

Invalidate the structure's CRC value (incrementing it by one), and write it to disk.

-r

Recalculate the current structure's correct CRC value, and write it to disk.

-v

Validate and display the current value and state of the structure's CRC.

daddr [-r] [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). If an address and the -l option are specified, the current address is set to the external log device. If an address and the -r option are specified, the current address is set to the realtime device.

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:

-a

Print only this AG's unlinked buckets.

-b

Print only this bucket within each AGI.

-q

Only print the essentials.

-v

Print resource usage of each file on the unlinked lists.

echo [arg] ...

Echo the arguments to the output.

f

See the forward command.

forward

Move forward to the next entry in the position ring.

frag [-adflqRrv]

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

-v

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

-a

enables processing of attribute data.

-d

enables processing of directory data.

-f

enables processing of regular file data.

-l

enables processing of symbolic link data.

-q

enables processing of quota file data.

-R

enables processing of realtime control file data.

-r

enables processing of realtime file data.

freesp [-bcds] [-A 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.

-A

reports only free extents with starting blocks aligned to alignment blocks.

-a

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

-b

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

-c

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

-d

specifies that every free extent will be displayed.

-e

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

-h

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

-m

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

-s

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

fsb

See the fsblock command.

fsblock [fsb]

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

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.

add

Adds a small value to a scalar field.

sub

Subtracts a small value from a scalar field.

random

Randomizes the contents of the field.

The following switches affect the write behavior:

-c

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

-d

Skip write verifiers but perform CRC recalculation; allows invalid data to be written to disk to test detection of invalid data.

hash[-d|-pparent_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.

-a

Create extended attribute names.

-i

Read the first name to create from standard input. Up to 255 bytes are read. If this option is not specified, first names are taken from the command line.

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

info

Displays selected geometry information about the filesystem. The output will have the same format that mkfs.xfs(8) prints when creating a filesystem or xfs_info(8) prints when querying a filesystem.

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:

-n

Create this number of unlinked inodes. If not specified, 1 inode will be created.

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] [-m] [-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 -m option specifies that the path lookup should be done in the metadata directory tree. 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.

logblock [logbno]

Set current address to the log block value given by logbno. If no value for logbno is given the current address is printed, expressed as an fsb. The type is set to data (uninterpreted). If the filesystem has an external log, then the address will be within the log device. If the filesystem has an internal log, then the address will be within the internal log.

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.

logres

Print transaction reservation size information for each transaction type. This makes it easier to find discrepancies in the reservation calculations between xfsprogs and the kernel, which will help when diagnosing minimum log size calculation errors.

ls [-im] [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.

-i

Resolve each of the given paths to an inode number and print that number. If no paths are given and the IO cursor points to an inode, print the inode number.

-m

Absolute paths should be walked from the root of the metadata directory tree.

metadump [-egow] filename

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

ncheck [-s] [-i ino] ...

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

-i

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

-s

specifies that only setuid and setgid files are printed.

p

See the print command.

parent [-m] [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 -m option causes absolute paths to be walked from the root of the metadata directory tree. The output format is: inode number, inode generation, ondisk namehash, namehash, name length, name.

path [-m] dir_path

Walk the directory tree to an inode using the supplied path. Absolute and relative paths are supported. The -m option causes absolute paths to be walked from the root of the metadata directory tree.

pop

Pop location from the stack.

print [field-expression] ...

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

push [command]

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

q

See the quit command.

quit

Exit xfs_db.

rdump [-s] [paths...] destination_dir

Recover the files given by the path arguments by copying them of the filesystem into the directory specified in destination_dir. If the -s option is specified, errors are fatal. By default, read errors are ignored in favor of recovering as much data from the filesystem as possible.

If zero paths are specified, the entire filesystem is dumped. If only one path is specified and it is a directory, the children of that directory will be copied directly to the destination. If multiple paths are specified, each file is copied into the directory as a new child.

If possible, sparse holes, xfs file attributes, and extended attributes will be preserved.

rgresv [rgno]

Displays the per-rtgroup reservation size, and per-rtgroup reservation usage for a given realtime allocation group. If no argument is given, display information for all rtgroups.

rtblock [rtbno]

Set current address to the location on the realtime device given by rtbno. This value must be a realtime block number. If no value for rtbno is given the current address is printed, expressed as an rtbno. The type is set to data (uninterpreted).

rtextent [rtxno]

Set current address to the location on the realtime device given by rtextent. This value must be a linear address in units of realtime extents. If no value for rtextent is given the current address is printed, expressed as an rtextent. The type is set to data (uninterpreted).

ring [index]

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

rtconvert type number [type number] ... type

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

rgblock or rgbno (realtime block within a realtime group)

rgnumber or rgno (realtime group number)

bboff or daddroff (byte offset in a daddr)

blkoff or fsboff or rtboff (byte offset in a rtblock or rtextent)

byte or fsbyte (byte address in filesystem)

daddr or bb (disk address, 512-byte blocks)

rtblock or rtb or rtbno (realtime filesystem block, see the fsblock command)

rtx or rtextent (realtime extent)

rbmblock or rbmb (realtime bitmap block)

rbmword or rbmw (32-bit word within a realtime bitmap block)

rsumblock or rsmb (realtime summary file block)

rsuminfo or rsmi (32-bit counter within a realtime summary block)

rsumlog or rsml (log2len parameter used for summary file offset computations)

Only conversions that "make sense" are allowed. The compound form (with more than three arguments) is useful for conversions such as convert rgno rg rgbno rgb rtblock. Realtime summary file location conversions have the following rules: Each info word in the rt summary file counts the number of free extents of a given log2(length) that start in a given rt bitmap block.

To compute summary file location information for a given rt bitmap block, a log2(extent length) must be specified as the last type/number pair before the conversion type, and the type must be rsumlog.

For example, these commands tell us where to look in the rt summary file for the number of free rtextents of length 2^21 starting in rt bitmap block 30:

rtconvert rbmblock 30 rsumlog 21 rsumblock

rtconvert rbmblock 30 rsumlog 21 rsuminfo

To compute the rt bitmap block from summary file location, the type/number pairs must be specified exactly in the order rsumlog, rsuminfo, rsumblock.

For example, this command tells us which block in the rt bitmap file is summarized by info word 809 in rt summary block 10 assuming that the maximum free extent length is 2^21 rtextents:

rtconvert rsumlog 21 rsuminfo 809 rsumblock 10 rbmblock

rtsb

Set current address to the superblock header at the start of the realtime volume.

sb [agno]

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

source source-file

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

stack

View the location stack.

type [type]

Set the current data type to type. If no argument is given, show the current data type. The possible data types are: agf, agfl, agi, attr, bmapbta, bmapbtd, bnobt, cntbt, data, dir, dir2, dqblk, inobt, inode, log, refcntbt, rmapbt, rtbitmap, rtsummary, sb, symlink, rtrmapbt, rtrefcbt, 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.

untorn_write_max [-b blockcount|-l logres]

If -l is specified, compute the maximum (in fsblocks) untorn write that we can emulate with copy on write given a log reservation size (in bytes). If -b is specified, compute the log reservation size that would be needed to emulate an untorn write of the given number of fsblocks.

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.

-c

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

-d

Skip write verifiers but perform CRC recalculation. This allows invalid data to be written to disk to test detection of invalid data. (This is not possible for some types.)

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

agf

The AGF block is the header for block allocation information; it is in the second 512-byte block of each allocation group. The following fields are defined:

magicnum

AGF block magic number, 0x58414746 ('XAGF').

versionnum

version number, currently 1.

seqno

sequence number starting from 0.

length

size in filesystem blocks of the allocation group. All allocation groups except the last one of the filesystem have the superblock's agblocks value here.

bnoroot

block number of the root of the Btree holding free space information sorted by block number.

cntroot

block number of the root of the Btree holding free space information sorted by block count.

bnolevel

number of levels in the by-block-number Btree.

cntlevel

number of levels in the by-block-count Btree.

flfirst

index into the AGFL block of the first active entry.

fllast

index into the AGFL block of the last active entry.

flcount

count of active entries in the AGFL block.

freeblks

count of blocks represented in the freespace Btrees.

longest

longest free space represented in the freespace Btrees.

btreeblks

number of blocks held in the AGF Btrees.

agfl

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

bno

array of all block numbers. Even those which are not active are printed.

agi

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

magicnum

AGI block magic number, 0x58414749 ('XAGI').

versionnum

version number, currently 1.

seqno

sequence number starting from 0.

length

size in filesystem blocks of the allocation group.

count

count of inodes allocated.

root

block number of the root of the Btree holding inode allocation information.

level

number of levels in the inode allocation Btree.

freecount

count of allocated inodes that are not in use.

newino

last inode number allocated.

dirino

unused.

unlinked

an array of inode numbers within the allocation group. The entries in the AGI block are the heads of lists which run through the inode next_unlinked field. These inodes are to be unlinked the next time the filesystem is mounted.

attr

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

hdr

header containing a blkinfo structure info (magic number 0xfbee), a count of active entries, usedbytes total bytes of names and values, the firstused byte in the name area, holes set if the block needs compaction, and array freemap as for dir leaf blocks.

entries

array of structures containing a hashval, nameidx (index into the block of the name), and flags incomplete, root, and local.

nvlist

array of structures describing the attribute names and values. Fields always present: valuelen (length of value in bytes), namelen, and name. Fields present for local values: value (value string). Fields present for remote values: valueblk (fork block number of containing the value).

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:

magic

attr3 remote block magic number, 0x5841524d ('XARM').

offset

Byte offset of this data block within the overall attribute value.

bytes

Number of bytes stored in this block.

crc

Checksum of the attribute block contents.

uuid

Filesystem UUID.

owner

Inode that owns this attribute value.

bno

Block offset of this block within the inode's attribute fork.

lsn

Log serial number of the last time this block was logged.

data

The attribute value data.

bmapbt

Files with many extents in their data or attribute fork will have the extents described by the contents of a Btree for that fork, instead of being stored directly in the inode. Each bmap Btree starts with a root block contained within the inode. The other levels of the Btree are stored in filesystem blocks. The blocks are linked to sibling left and right blocks at each level, as well as by pointers from parent to child blocks. Each block contains the following fields:

magic

bmap Btree block magic number, 0x424d4150 ('BMAP').

level

level of this block above the leaf level.

numrecs

number of records or keys in the block.

leftsib

left (logically lower) sibling block, 0 if none.

rightsib

right (logically higher) sibling block, 0 if none.

recs

[leaf blocks only] array of extent records. Each record contains startoff, startblock, blockcount, and extentflag (1 if the extent is unwritten).

keys

[non-leaf blocks only] array of key records. These are the first key value of each block in the level below this one. Each record contains startoff.

ptrs

[non-leaf blocks only] array of child block pointers. Each pointer is a filesystem block number to the next level in the Btree.

bnobt

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

magic

BNOBT block magic number, 0x41425442 ('ABTB').

level

level number of this block, 0 is a leaf.

numrecs

number of data entries in the block.

leftsib

left (logically lower) sibling block, 0 if none.

rightsib

right (logically higher) sibling block, 0 if none.

recs

[leaf blocks only] array of freespace records. Each record contains startblock and blockcount.

keys

[non-leaf blocks only] array of key records. These are the first value of each block in the level below this one. Each record contains startblock and blockcount.

ptrs

[non-leaf blocks only] array of child block pointers. Each pointer is a block number within the allocation group to the next level in the Btree.

cntbt

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

magic

CNTBT block magic number, 0x41425443 ('ABTC').

level

level number of this block, 0 is a leaf.

numrecs

number of data entries in the block.

leftsib

left (logically lower) sibling block, 0 if none.

rightsib

right (logically higher) sibling block, 0 if none.

recs

[leaf blocks only] array of freespace records. Each record contains startblock and blockcount.

keys

[non-leaf blocks only] array of key records. These are the first value of each block in the level below this one. Each record contains blockcount and startblock.

ptrs

[non-leaf blocks only] array of child block pointers. Each pointer is a block number within the allocation group to the next level in the Btree.

data

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

dir

A version 1 directory is organized as a Btree with the directory data embedded in the leaf blocks. The root of the Btree is found in block 0 of the file. The index (sort order) of the Btree is the hash value of the entry name. All the blocks contain a blkinfo structure at the beginning with the following fields:

forw

next sibling block.

back

previous sibling block.

magic

magic number for this block type.

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

hdr

header containing a blkinfo structure info (magic number 0xfebe), the count of active entries, and the level of this block above the leaves.

btree

array of entries containing hashval and before fields. The before value is a block number within the directory file to the child block, the hashval is the last hash value in that block.

The leaf blocks have the following fields:

hdr

header containing a blkinfo structure info (magic number 0xfeeb), the count of active entries, namebytes (total name string bytes), holes flag (block needs compaction), and freemap (array of base, size entries for free regions).

entries

array of structures containing hashval, nameidx (byte index into the block of the name string), and namelen.

namelist

array of structures containing inumber and name.

dir2

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

A single-block directory block contains the following fields:

bhdr

header containing magic number 0x58443242 ('XD2B') and an array bestfree of the longest 3 free spaces in the block (offset, length).

bu

array of union structures. Each element is either an entry or a freespace. For entries, there are the following fields: inumber, namelen, name, and tag. For freespace, there are the following fields: freetag (0xffff), length, and tag. The tag value is the byte offset in the block of the start of the entry it is contained in.

bleaf

array of leaf entries containing hashval and address. The address is a 64-bit word offset into the file.

btail

tail structure containing the total count of leaf entries and stale count of unused leaf entries.

A data block contains the following fields:

dhdr

header containing magic number 0x58443244 ('XD2D') and an array bestfree of the longest 3 free spaces in the block (offset, length).

du

array of union structures as for bu.

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

lhdr

header containing a blkinfo structure info (magic number 0xd2f1 for the single leaf case, 0xd2ff for the true Btree case), the total count of leaf entries, and stale count of unused leaf entries.

lents

leaf entries, as for bleaf.

lbests

[single leaf only] array of values which represent the longest freespace in each data block in the directory.

ltail

[single leaf only] tail structure containing bestcount count of lbests.

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

A freespace block contains the following fields:

fhdr

header containing magic number 0x58443246 ('XD2F'), firstdb first data block number covered by this freespace block, nvalid number of valid entries, and nused number of entries representing real data blocks.

fbests

array of values as for lbests.

dqblk

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

magic

magic number, 0x4451 ('DQ').

version

version number, currently 1.

flags

flags, values include 0x01 for user quota, 0x02 for project quota.

id

user or project identifier.

blk_hardlimit

absolute limit on blocks in use.

blk_softlimit

preferred limit on blocks in use.

ino_hardlimit

absolute limit on inodes in use.

ino_softlimit

preferred limit on inodes in use.

bcount

blocks actually in use.

icount

inodes actually in use.

itimer

time when service will be refused if soft limit is violated for inodes.

btimer

time when service will be refused if soft limit is violated for blocks.

iwarns

number of warnings issued about inode limit violations.

bwarns

number of warnings issued about block limit violations.

rtb_hardlimit

absolute limit on realtime blocks in use.

rtb_softlimit

preferred limit on realtime blocks in use.

rtbcount

realtime blocks actually in use.

rtbtimer

time when service will be refused if soft limit is violated for realtime blocks.

rtbwarns

number of warnings issued about realtime block limit violations.

inobt

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

magic

INOBT block magic number, 0x49414254 ('IABT').

level

level number of this block, 0 is a leaf.

numrecs

number of data entries in the block.

leftsib

left (logically lower) sibling block, 0 if none.

rightsib

right (logically higher) sibling block, 0 if none.

recs

[leaf blocks only] array of inode records. Each record contains startino allocation-group relative inode number, freecount count of free inodes in this chunk, and free bitmap, LSB corresponds to inode 0.

keys

[non-leaf blocks only] array of key records. These are the first value of each block in the level below this one. Each record contains startino.

ptrs

[non-leaf blocks only] array of child block pointers. Each pointer is a block number within the allocation group to the next level in the Btree.

inode

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

The following are fields in the inode core:

magic

inode magic number, 0x494e ('IN').

mode

mode and type of file, as described in chmod(2), mknod(2), and stat(2).

version

inode version, 1 or 2.

format

format of u union data (0: xfs_dev_t, 1: local file - in-inode directory or symlink, 2: extent list, 3: Btree root, 4: unique id [unused]).

nlinkv1

number of links to the file in a version 1 inode.

nlinkv2

number of links to the file in a version 2 inode.

projid_lo

owner's project id (low word; version 2 inode only). projid_hi owner's project id (high word; version 2 inode only).

uid

owner's user id.

gid

owner's group id.

atime

time last accessed (seconds and nanoseconds).

mtime

time last modified.

ctime

time created or inode last modified.

size

number of bytes in the file.

nblocks

total number of blocks in the file including indirect and attribute.

extsize

basic/minimum extent size for the file.

nextents

number of extents in the data fork.

naextents

number of extents in the attribute fork.

forkoff

attribute fork offset in the inode, in 64-bit words from the start of u.

aformat

format of a data (1: local attribute data, 2: extent list, 3: Btree root).

dmevmask

DMAPI event mask.

dmstate

DMAPI state information.

newrtbm

file is the realtime bitmap and is "new" format.

prealloc

file has preallocated data space after EOF.

realtime

file data is in the realtime subvolume.

gen

inode generation number.

The following fields are in the u data fork union:

bmbt

bmap Btree root. This looks like a bmapbtd block with redundant information removed.

bmx

array of extent descriptors.

dev

dev_t for the block or character device.

sfdir

shortform (in-inode) version 1 directory. This consists of a hdr containing the parent inode number and a count of active entries in the directory, followed by an array list of hdr.count entries. Each such entry contains inumber, namelen, and name string.

sfdir2

shortform (in-inode) version 2 directory. This consists of a hdr containing a count of active entries in the directory, an i8count of entries with inumbers that don't fit in a 32-bit value, and the parent inode number, followed by an array list of hdr.count entries. Each such entry contains namelen, a saved offset used when the directory is converted to a larger form, a name string, and the inumber.

symlink

symbolic link string value.

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

bmbt

bmap Btree root, as above.

bmx

array of extent descriptors.

sfattr

shortform (in-inode) attribute values. This consists of a hdr containing a totsize (total size in bytes) and a count of active entries, followed by an array list of hdr.count entries. Each such entry contains namelen, valuelen, root flag, name, and value.

log

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

refcntbt

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

magic

REFC block magic number, 0x52334643 ('R3FC').

level

level number of this block, 0 is a leaf.

numrecs

number of data entries in the block.

leftsib

left (logically lower) sibling block, 0 if none.

rightsib

right (logically higher) sibling block, 0 if none.

recs

[leaf blocks only] array of reference count records. Each record contains startblock, blockcount, and refcount.

keys

[non-leaf blocks only] array of key records. These are the first value of each block in the level below this one. Each record contains startblock.

ptrs

[non-leaf blocks only] array of child block pointers. Each pointer is a block number within the allocation group to the next level in the Btree.

rtrefcbt

There is one reference count Btree for the entire realtime device. The startblock and blockcount fields are 32 bits wide and record block counts within a realtime group. The root of this Btree is the realtime refcount inode, which is recorded in the metadata directory. Blocks are linked to sibling left and right blocks at each level, as well as by pointers from parent to child blocks. Each block has the following fields:

magic

RTREFC block magic number, 0x52434e54 ('RCNT').

level

level number of this block, 0 is a leaf.

numrecs

number of data entries in the block.

leftsib

left (logically lower) sibling block, 0 if none.

rightsib

right (logically higher) sibling block, 0 if none.

recs

[leaf blocks only] array of reference count records. Each record contains startblock, blockcount, and refcount.

keys

[non-leaf blocks only] array of key records. These are the first value of each block in the level below this one. Each record contains startblock.

ptrs

[non-leaf blocks only] array of child block pointers. Each pointer is a block number within the allocation group to the next level in the Btree.

rmapbt

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:

magic

RMAP block magic number, 0x524d4233 ('RMB3').

level

level number of this block, 0 is a leaf.

numrecs

number of data entries in the block.

leftsib

left (logically lower) sibling block, 0 if none.

rightsib

right (logically higher) sibling block, 0 if none.

recs

[leaf blocks only] array of reference count records. Each record contains startblock, blockcount, owner, offset, attr_fork, bmbt_block, and unwritten.

keys

[non-leaf blocks only] array of double-key records. The first ("low") key contains the first value of each block in the level below this one. The second ("high") key contains the largest key that can be used to identify any record in the subtree. Each record contains startblock, owner, offset, attr_fork, and bmbt_block.

ptrs

[non-leaf blocks only] array of child block pointers. Each pointer is a block number within the allocation group to the next level in the Btree.

rtrmapbt

There is one reverse mapping Btree for each realtime group. The startblock and blockcount fields are 32 bits wide and record blocks within a realtime group. The root of this Btree is the reverse-mapping inode, which is recorded in the metadata directory. Blocks are linked to sibling left and right blocks at each level, as well as by pointers from parent to child blocks. Each block has the following fields:

magic

RTRMAP block magic number, 0x4d415052 ('MAPR').

level

level number of this block, 0 is a leaf.

numrecs

number of data entries in the block.

leftsib

left (logically lower) sibling block, 0 if none.

rightsib

right (logically higher) sibling block, 0 if none.

recs

[leaf blocks only] array of reference count records. Each record contains startblock, blockcount, owner, offset, attr_fork, bmbt_block, and unwritten.

keys

[non-leaf blocks only] array of double-key records. The first ("low") key contains the first value of each block in the level below this one. The second ("high") key contains the largest key that can be used to identify any record in the subtree. Each record contains startblock, owner, offset, attr_fork, and bmbt_block.

ptrs

[non-leaf blocks only] array of child block pointers. Each pointer is a block number within the allocation group to the next level in the Btree.

rtbitmap

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

rtsummary

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

sb

There is one sb (superblock) structure per allocation group. It is the first disk block in the allocation group. Only the first one (block 0 of the filesystem) is actually used; the other blocks are redundant information for xfs_repair(8) to use if the first superblock is damaged. Fields defined:

magicnum

superblock magic number, 0x58465342 ('XFSB').

blocksize

filesystem block size in bytes.

dblocks

number of filesystem blocks present in the data subvolume.

rblocks

number of filesystem blocks present in the realtime subvolume.

rextents

number of realtime extents that rblocks contain.

uuid

unique identifier of the filesystem.

logstart

starting filesystem block number of the log (journal). If this value is 0 the log is "external".

rootino

root inode number.

rbmino

realtime bitmap inode number.

rsumino

realtime summary data inode number.

rextsize

realtime extent size in filesystem blocks.

agblocks

size of an allocation group in filesystem blocks.

agcount

number of allocation groups.

rbmblocks

number of realtime bitmap blocks.

logblocks

number of log blocks (filesystem blocks).

versionnum

filesystem version information. This value is currently 1, 2, 3, or 4 in the low 4 bits. If the low bits are 4 then the other bits have additional meanings. 1 is the original value. 2 means that attributes were used. 3 means that version 2 inodes (large link counts) were used. 4 is the bitmask version of the version number. In this case, the other bits are used as flags (0x0010: attributes were used, 0x0020: version 2 inodes were used, 0x0040: quotas were used, 0x0080: inode cluster alignment is in force, 0x0100: data stripe alignment is in force, 0x0200: the shared_vn field is used, 0x1000: unwritten extent tracking is on, 0x2000: version 2 directories are in use).

sectsize

sector size in bytes, currently always 512. This is the size of the superblock and the other header blocks.

inodesize

inode size in bytes.

inopblock

number of inodes per filesystem block.

fname

obsolete, filesystem name.

fpack

obsolete, filesystem pack name.

blocklog

log2 of blocksize.

sectlog

log2 of sectsize.

inodelog

log2 of inodesize.

inopblog

log2 of inopblock.

agblklog

log2 of agblocks (rounded up).

rextslog

log2 of rextents.

inprogress

mkfs.xfs(8) or xfs_copy(8) aborted before completing this filesystem.

imax_pct

maximum percentage of filesystem space used for inode blocks.

icount

number of allocated inodes.

ifree

number of allocated inodes that are not in use.

fdblocks

number of free data blocks.

frextents

number of free realtime extents.

uquotino

user quota inode number.

pquotino

project quota inode number; this is currently unused.

qflags

quota status flags (0x01: user quota accounting is on, 0x02: user quota limits are enforced, 0x04: quotacheck has been run on user quotas, 0x08: project quota accounting is on, 0x10: project quota limits are enforced, 0x20: quotacheck has been run on project quotas).

flags

random flags. 0x01: only read-only mounts are allowed.

shared_vn

shared version number (shared readonly filesystems).

inoalignmt

inode chunk alignment in filesystem blocks.

unit

stripe or RAID unit.

width

stripe or RAID width.

dirblklog

log2 of directory block size (filesystem blocks).

symlink

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

text

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

## DIAGNOSTICS
Many messages can come from the 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 blockget 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).


package: xfsprogs

title: xfs_estimate(8)

text:
# xfs_estimate(8)

## NAME
xfs_estimate - estimate the space that an XFS filesystem will take

## SYNOPSIS

```
xfs_estimate [ -h ] [ -b blocksize ] [ -i logsize ]
		   [ -e logsize ] [ -v ] directory ...

xfs_estimate -V
```

## DESCRIPTION
For each directory argument, xfs_estimate estimates the space that directory would take if it were copied to an XFS filesystem. xfs_estimate does not cross mount points. The following definitions are used:

KB = *1024

MB = *1024*1024

GB = *1024*1024*1024

The xfs_estimate options are:

-b blocksize

Use blocksize instead of the default blocksize of 4096 bytes. The modifier k can be used after the number to indicate multiplication by 1024. For example,

xfs_estimate -b 64k /

requests an estimate of the space required by the directory / on an XFS filesystem using a blocksize of 64K (65536) bytes.

-v

Display more information, formatted.

-h

Display usage message.

-i, -e logsize

Use logsize instead of the default log size of 1000 blocks. -i refers to an internal log, while -e refers to an external log. The modifiers k or m can be used after the number to indicate multiplication by 1024 or 1048576, respectively.

For example,

xfs_estimate -i 1m /

requests an estimate of the space required by the directory / on an XFS filesystem using an internal log of 1 megabyte.

-V

Print the version number and exits.

## EXAMPLES

```
% xfs_estimate -e 10m /var/tmp
/var/tmp will take about 4.2 megabytes

        with the external log using 2560 blocks or about 10.0 megabytes
```

```
% xfs_estimate -v -e 10m /var/tmp
directory                     bsize   blocks    megabytes    logsize
/var/tmp                       4096      792        4.0MB   10485760
```

```
% xfs_estimate -v /var/tmp
directory                     bsize   blocks    megabytes    logsize
/var/tmp                       4096     3352       14.0MB   10485760
```

```
% xfs_estimate /var/tmp
/var/tmp will take about 14.0 megabytes
```

branch: sisyphus


title: xfs_freeze(8)

summary: suspend access to an XFS filesystem

text:
# xfs_freeze(8)

## NAME
xfs_freeze - suspend access to an XFS filesystem

## SYNOPSIS
xfs_freeze [ -f | -u ] mount-point

xfs_freeze -V

## DESCRIPTION
xfs_freeze suspends and resumes access to an XFS filesystem (see xfs(5)).

xfs_freeze halts new access to the filesystem and creates a stable image on disk. xfs_freeze is intended to be used with volume managers and hardware RAID devices that support the creation of snapshots.

The mount-point argument is the pathname of the directory where the filesystem is mounted. The filesystem must be mounted to be frozen (see mount(8)).

The -f flag requests the specified XFS filesystem to be frozen from new modifications. When this is selected, all ongoing transactions in the filesystem are allowed to complete, new write system calls are halted, other calls which modify the filesystem are halted, and all dirty data, metadata, and log information are written to disk. Any process attempting to write to the frozen filesystem will block waiting for the filesystem to be unfrozen.

Note that even after freezing, the on-disk filesystem can contain information on files that are still in the process of unlinking. These files will not be unlinked until the filesystem is unfrozen or a clean mount of the snapshot is complete.

The -u flag is used to un-freeze the filesystem and allow operations to continue. Any filesystem modifications that were blocked by the freeze are unblocked and allowed to complete.

The -V flag prints the version number and exits.

Unless -V is specified, one of -f or -u must be supplied to xfs_freeze.

## NOTES
A copy of a frozen XFS filesystem will usually have the same universally unique identifier (UUID) as the original, and thus may be prevented from being mounted. The XFS nouuid mount option can be used to circumvent this issue.

In Linux kernel version 2.6.29, the interface which XFS uses to freeze and unfreeze was elevated to the VFS, so that this tool can now be used on many other Linux filesystems.

## SEE ALSO
xfs(5), lvm(8), mount(8).


title: xfs_fsr(8)

summary: filesystem reorganizer for XFS

text:
# xfs_fsr(8)

## NAME
xfs_fsr - filesystem reorganizer for XFS

## SYNOPSIS

```
xfs_fsr [-vdg]
[-t seconds] [-p passes] [-f leftoff] [-m mtab]
xfs_fsr [-vdg]
[xfsdev | file] ...

xfs_fsr -V
```

## DESCRIPTION
xfs_fsr is applicable only to XFS filesystems.

xfs_fsr improves the organization of mounted filesystems. The reorganization algorithm operates on one file at a time, compacting or otherwise improving the layout of the file extents (contiguous blocks of file data).

The following options are accepted by xfs_fsr. The -m, -t, and -f options have no meaning if any filesystems or files are specified on the command line.

-m mtab

Use this file for the list of filesystems to reorganize. The default is to use /etc/mtab.

-t seconds

How long to reorganize. The default is 7200 seconds (2 hours).

-p passes

Number of passes before terminating global re-org. The default is 10 passes.

-f leftoff

Use this file instead of /var/tmp/.fsrlast to read the state of where to start and as the file to store the state of where reorganization left off.

-v

Verbose. Print cryptic information about each file being reorganized.

-d

Debug. Print even more cryptic information.

-g

Print to syslog (default if stdout not a tty).

-V

Prints the version number and exits.

When invoked with no arguments xfs_fsr reorganizes all regular files in all mounted filesystems. xfs_fsr makes many cycles over /etc/mtab each time making a single pass over each XFS filesystem. Each pass goes through and selects files that have the largest number of extents. It attempts to defragment the top 10% of these files on each pass.

It runs for up to two hours after which it records the filesystem where it left off, so it can start there the next time. This information is stored in the file /var/tmp/.fsrlast_xfs. If the information found here is somehow inconsistent or out of date it is ignored and reorganization starts at the beginning of the first filesystem found in /etc/mtab.

xfs_fsr can be called with one or more arguments naming filesystems (block device name), and files to reorganize. In this mode xfs_fsr does not read or write /var/tmp/.fsrlast_xfs nor does it run for a fixed time interval. It makes one pass through each specified regular file and all regular files in each specified filesystem. A command line name referring to a symbolic link (except to a file system device), FIFO, or UNIX domain socket generates a warning message, but is otherwise ignored. While traversing the filesystem these types of files are silently skipped.

## FILES
/etc/mtab

contains default list of filesystems to reorganize.

/var/tmp/.fsrlast_xfs

records the state where reorganization left off.

## SEE ALSO
xfs_fsr(8), mkfs.xfs(8), xfs_ncheck(8), xfs(5).

## NOTES
xfs_fsr improves the layout of extents for each file by copying the entire file to a temporary location and then interchanging the data extents of the target and temporary files in an atomic manner. This method requires that enough free disk space be available to copy any given file and that the space be less fragmented than the original file. It also requires the owner of the file to have enough remaining filespace quota to do the copy on systems running quotas. xfs_fsr generates a warning message if space is not sufficient to improve the target file.

A temporary file used in improving a file given on the command line is created in the same parent directory of the target file and is prefixed by the string '.fsr'. The temporary files used in improving an entire XFS device are stored in a directory at the root of the target device and use the same naming scheme. The temporary files are unlinked upon creation so data will not be readable by any other process.

xfs_fsr does not operate on files that are currently mapped in memory. A 'file busy' error can be seen for these files if the verbose flag (-v) is set.

Files marked as no-defrag will be skipped. The xfs_io(8) chattr command with the f attribute can be used to set or clear this flag. Files and directories created in a directory with the no-defrag flag will inherit the attribute.

An entry in /etc/mtab or the file specified using the -m option must have the rw option specified for read and write access. If this option is not present, then xfs_fsr skips the filesystem described by that line. See the fstab(5) reference page for more details.

In general we do not foresee the need to run xfs_fsr on system partitions such as /, /boot and /usr as in general these will not suffer from fragmentation. There are also issues with defragmenting files lilo(8) uses to boot your system. It is recommended that these files should be flagged as no-defrag with the xfs_io(8) chattr command. Should these files be moved by xfs_fsr then you must rerun lilo before you reboot or you may have an unbootable system.


title: xfs_growfs(8)

summary: expand an XFS filesystem

text:
# xfs_growfs(8)

## NAME
xfs_growfs - expand an XFS filesystem

## SYNOPSIS
xfs_growfs [ -dilnrx ] [ -D size ] [ -e rtextsize ] [ -L size ] [ -m maxpct ] [ -t mtab ] [ -R size ] [ mount-point | block-device ]

xfs_growfs -V

## DESCRIPTION
xfs_growfs expands an existing XFS filesystem (see xfs(5)). The mount-point argument is the pathname of the directory where the filesystem is mounted. The block-device argument is the device name of a mounted XFS filesystem. The filesystem must be mounted to be grown (see mount(8)). The existing contents of the filesystem are undisturbed, and the added space becomes available for additional file storage.

## OPTIONS
-d | -D size

Specifies that the data section of the filesystem should be resized. If the -D size option is given, the data section is changed to that size, otherwise the data section is grown to the largest size possible with the -d option. The size is expressed in filesystem blocks. A filesystem with only 1 AG cannot be shrunk further, and a filesystem cannot be shrunk to the point where it would only have 1 AG. [NOTE: Only shrinking the last AG without removing it is implemented]

-e

Allows the real-time extent size to be specified. In mkfs.xfs(8) this is specified with -r extsize=nnnn.

-i

The new log is an internal log (inside the data section). [NOTE: This option is not implemented]

-l | -L size

Specifies that the log section of the filesystem should be grown, shrunk, or moved. If the -L size option is given, the log section is changed to be that size, if possible. The size is expressed in filesystem blocks. The size of an internal log must be smaller than the size of an allocation group (this value is printed at mkfs(8) time). If neither -i nor -x is given with -l, the log continues to be internal or external as it was before. [NOTE: These options are not implemented]

-m

Specify a new value for the maximum percentage of space in the filesystem that can be allocated as inodes. In mkfs.xfs(8) this is specified with -i maxpct=nn.

-n

Specifies that no change to the filesystem is to be made. The filesystem geometry is printed, and argument checking is performed, but no growth occurs. See output examples below.

-r | -R size

Specifies that the real-time section of the filesystem should be grown. If the -R size option is given, the real-time section is grown to that size, otherwise the real-time section is grown to the largest size possible with the -r option. The size is expressed in filesystem blocks. The filesystem does not need to have contained a real-time section before the xfs_growfs operation.

-t

Specifies an alternate mount table file (default is /proc/mounts if it exists, else /etc/mtab). This is used when working with filesystems mounted without writing to /etc/mtab file - refer to mount(8) for further details.

-V

Prints the version number and exits. The mount-point argument is not required with -V.

xfs_growfs is most often used in conjunction with logical volumes (see md(4) and lvm(8) on Linux). However, it can also be used on a regular disk partition, for example if a partition has been enlarged while retaining the same starting block.

## PRACTICAL USE
Filesystems normally occupy all of the space on the device where they reside. In order to grow a filesystem, it is necessary to provide added space for it to occupy. Therefore there must be at least one spare new disk partition available. Adding the space is often done through the use of a logical volume manager.

## SEE ALSO
mkfs.xfs(8), xfs_info(8), md(4), lvm(8), mount(8).


title: xfs_healer(8)

text:
# xfs_healer(8)

## NAME
xfs_healer - automatically heal damage to XFS filesystem metadata

## SYNOPSIS
xfs_healer [ OPTIONS ] mount-point

xfs_healer -V

## DESCRIPTION
xfs_healer is a daemon that tries to automatically repair damaged XFS filesystem metadata.

WARNING! This program is EXPERIMENTAL, which means that its behavior and interface could change at any time!

xfs_healer asks the kernel to report all observations of corrupt metadata, media errors, filesystem shutdowns, and file I/O errors. The program can respond to runtime metadata corruption errors by initiating targeted repairs of the suspect metadata or a full online fsck of the filesystem.

Normally this program runs as a systemd service. The service is activated via the xfs_healer_start service if systemd is supported.

The kernel may not support repairing or optimizing the filesystem. If this is the case, the filesystem must be unmounted and xfs_repair(8) run on the filesystem to fix the problems.

## OPTIONS
--everything

Ask the kernel to send us good metadata health events, not only events related to metadata corruption, media errors, shutdowns, and I/O errors.

--foreground

Start enough event handling threads to allow consumption of all online CPUs. If not specified, start exactly one event handling thread.

--no-autofsck

Do not use the autofsck filesystem property to decide whether or not to repair corrupt metadata. If the --repair option is given, then all corruptions will be repaired. If the --repair option is not given, then the program will never try to repair the filesystem.

--quiet

Do not print every event to standard output.

--repair

Always try to repair each piece of corrupt metadata when the kernel tells us about it. If an individual repair fails or the kernel tells us that health events were lost, the xfs_scrub service for this mount point will be launched. The default is not to try to repair anything. If this option is specified but the kernel does not support repairs, the program will exit.

--supported

Check if the filesystem supports sending health events. Exits with 0 if it does, and non-zero if not.

-V

Prints the version number and exit.

## AUTOFSCK
By default, this program will read the autofsck filesystem property to decide if it should try to repair corruptions. If the property is set to these values:

repair

Corruptions will be repaired.

check or optimize

Corruptions will be logged.

none

The program will exit.

If the property is not set but the filesystem supports any back-reference metadata (reverse mappings and parent pointers), then corruptions will be logged. If no back-reference metadata are present, the program will exit.

See the xfs_scrub(8) manual page for more details on this filesystem property.

## CAVEATS
xfs_healer is an immature utility! Do not run this program unless you have backups of your data! This program takes advantage of in-kernel scrubbing to verify a given data structure with locks held and can keep the filesystem busy for a long time. The kernel must be new enough to support the SCRUB_METADATA ioctl.

If errors are found and cannot be repaired, the filesystem must be unmounted and repaired.

## SEE ALSO
xfs_repair(8) and xfs_scrub(8).


title: xfs_healer_start(8)

summary: starts xfs_healer instances

text:
# xfs_healer_start(8)

## NAME
xfs_healer_start - starts xfs_healer instances

## SYNOPSIS
xfs_healer_start [ OPTIONS ]

xfs_healer_start -V

## DESCRIPTION
xfs_healer_start starts the xfs_healer service whenever the kernel mounts an XFS filesystem in the current mount namespace.

WARNING! This program is EXPERIMENTAL, which means that its behavior and interface could change at any time!

Normally this program runs as a systemd service.

## OPTIONS
--supported

Check if the kernel supports listening for mount events. Exits with 0 if it does, and non-zero if not.

--mountns path

Monitor the given mount namespace. Defaults to the mount namespace associated with the process itself.

-V

Prints the version number and exit.

## SEE ALSO
xfs_healer(8).


title: xfs_info(8)

text:
# xfs_info(8)

## NAME
xfs_info - display XFS filesystem geometry information

## SYNOPSIS
xfs_info [ -t mtab ] [ mount-point | block-device | file-image ]

xfs_info -V

## DESCRIPTION
xfs_info displays geometry information about an existing XFS filesystem. The mount-point argument is the pathname of a directory where the filesystem is mounted. The block-device or file-image contain a raw XFS filesystem. The existing contents of the filesystem are undisturbed.

## OPTIONS
-t

Specifies an alternate mount table file (default is /proc/mounts if it exists, else /etc/mtab). This is used when working with filesystems mounted without writing to /etc/mtab file - refer to mount(8) for further details. This option has no effect with the block-device or file-image parameters.

-V

Prints the version number and exits. The mount-point argument is not required with -V.

## EXAMPLES
Understanding xfs_info output.

Suppose one has the following "xfs_info /dev/sda" output:

```
meta-data=/dev/pmem0             isize=512    agcount=8, agsize=5974144 blks
         =                       sectsz=512   attr=2, projid32bit=1
         =                       crc=1        finobt=1, sparse=1, rmapbt=1
         =                       reflink=1
data     =                       bsize=4096   blocks=47793152, imaxpct=25
         =                       sunit=32     swidth=128 blks
naming   =version 2              bsize=4096   ascii-ci=0, ftype=1
log      =internal log           bsize=4096   blocks=23336, version=2
         =                       sectsz=512   sunit=0 blks, lazy-count=1
realtime =none                   extsz=4096   blocks=0, rtextents=0
```

Here, the data section of the output indicates "bsize=4096", meaning the data block size for this filesystem is 4096 bytes. This section also shows "sunit=32 swidth=128 blks", which means the stripe unit is 32*4096 bytes = 128 kibibytes and the stripe width is 128*4096 bytes = 512 kibibytes. A single stripe of this filesystem therefore consists of four stripe units (128 blocks / 32 blocks per unit).

## SEE ALSO
mkfs.xfs(8), md(4), lvm(8), mount(8).